# How to Set Up Focus and Avoid Rules to Scope Shannon Pentesting to Specific API Endpoints

> Scope Shannon pentesting to specific API endpoints by defining focus and avoid arrays in the YAML configuration. Filter URLs efficiently for targeted security testing.

- Repository: [KeygraphHQ/shannon](https://github.com/keygraphhq/shannon)
- Tags: how-to-guide
- Published: 2026-02-16

---

**Use the `rules` section in Shannon's YAML configuration to define `focus` arrays for target API endpoints and `avoid` arrays for excluded paths, which the agent then uses to filter URLs before scanning.**

Shannon, an open-source AI-powered pentesting framework from KeygraphHQ/shannon, lets you precisely control testing scope through declarative configuration. By leveraging the `focus` and `avoid` rule collections, security teams can restrict automated testing to specific API endpoints while ensuring sensitive routes remain untouched.

## Understanding Focus and Avoid Rules in Shannon

Shannon's testing scope is driven entirely by the **rules** section of the YAML configuration file. Two collections control agent behavior:

- **avoid**: Areas that agents must skip, such as endpoints you do not want to test
- **focus**: Areas that agents should prioritize, such as the exact API paths you want to exercise

Both collections are arrays of **Rule** objects defined in [`src/types/config.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/types/config.ts). According to the source code, a rule consists of three fields:

1. `description` – Human-readable note shown in prompts
2. `type` – One of `path`, `subdomain`, `domain`, `method`, `header`, or `parameter`
3. `url_path` – The concrete value that the rule matches (for example, `/api/v2/user-profile` for a `path` rule)

## Configuration Validation and Security Checks

When a configuration file loads, [`src/config-parser.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts) parses the YAML, validates it against the JSON schema in [`configs/config-schema.json`](https://github.com/KeygraphHQ/shannon/blob/main/configs/config-schema.json), and sanitizes the rules through a five-stage validation flow:

1. **Schema validation** – Guarantees required fields and basic shapes
2. **Security validation** – Rejects dangerous patterns defined in the `DANGEROUS_PATTERNS` array (such as `../`, `<`, or `javascript:`) in [`src/config-parser.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts)
3. **Rule-type checks** – Each rule is type-checked in `validateRuleTypeSpecific`. For a `path` rule, the `url_path` must start with `/`
4. **Duplicate detection** – `checkForDuplicates` throws an error on identical `type:url_path` pairs
5. **Conflict detection** – `checkForConflicts` ensures a rule never appears in both `avoid` and `focus` collections

If any check fails, `parseConfig` raises a `PentestError` with a descriptive message, preventing the workflow from starting.

## Practical Examples for Scoping API Endpoints

### Targeting Specific API Paths with Focus Rules

To restrict testing to a specific API endpoint, define a `path` rule in the `focus` array:

```yaml
rules:
  focus:
    - description: "Target the user-profile update API"
      type: path
      url_path: "/api/v2/user-profile"

```

This configuration tells Shannon agents to prioritize the `/api/v2/user-profile` endpoint while still allowing testing of other discovered paths unless explicitly avoided.

### Excluding Sensitive Endpoints with Avoid Rules

Use the `avoid` collection to prevent testing of health checks, logout routes, or administrative functions:

```yaml
rules:
  avoid:
    - description: "Do not test the public health-check endpoint"
      type: path
      url_path: "/healthz"
    - description: "Skip logout to preserve session state"
      type: path
      url_path: "/api/v1/logout"

```

According to the source code in [`src/config-parser.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts), these rules undergo security validation to ensure no dangerous patterns are present in the `url_path` values.

### Combining Focus and Avoid for Precise Scoping

For complex API surfaces, combine both collections to create a whitelist-blacklist approach:

```yaml
rules:
  avoid:
    - description: "Skip all admin endpoints"
      type: path
      url_path: "/api/v1/admin"
  focus:
    - description: "Test user creation endpoints"
      type: path
      url_path: "/api/v1/users/create"
    - description: "Test order processing"
      type: path
      url_path: "/api/v1/orders"

```

The `checkForConflicts` function in [`src/config-parser.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts) ensures that identical rules cannot exist in both arrays simultaneously, preventing configuration errors.

### Scoping by Subdomain or HTTP Method

Shannon supports scoping beyond simple paths. To test only a specific subdomain:

```yaml
rules:
  focus:
    - description: "Only test the beta admin panel"
      type: subdomain
      url_path: "beta-admin"

```

To restrict testing to POST requests on a specific endpoint:

```yaml
rules:
  focus:
    - description: "Only test POST requests to the upload endpoint"
      type: method
      url_path: "POST"
  avoid:
    - description: "Never test DELETE methods"
      type: method
      url_path: "DELETE"

```

## How Rules Are Distributed to Agents

After a configuration file passes validation, the `distributeConfig` function in [`src/config-parser.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts) creates a **DistributedConfig** object. This object contains only the sanitized `avoid`, `focus`, and optional `authentication` sections, stripping away any unnecessary metadata before sending it to agents.

This distributed configuration is injected into the prompt interpolation pipeline in [`src/prompts/prompt-manager.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/prompts/prompt-manager.ts). During prompt generation, the `interpolateVariables` function replaces the `{{RULES_AVOID}}` and `{{RULES_FOCUS}}` placeholders with bullet lists of the rule descriptions. If both collections are empty, a clean "No specific rules" section is inserted as a fallback.

Agents receive the **DistributedConfig** via the Temporal workflow and use it to filter URLs before launching scans, ensuring that only the specified API endpoints are exercised according to the focus and avoid rules you configured.

## Summary

- **Rule Collections**: Shannon uses `avoid` and `focus` arrays in the YAML configuration to control pentesting scope, defined in [`src/types/config.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/types/config.ts).
- **Rule Structure**: Each rule requires a `description`, `type` (path, subdomain, method, etc.), and `url_path` value.
- **Validation Pipeline**: [`src/config-parser.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts) enforces schema compliance, security patterns, type-specific checks, duplicate detection, and conflict prevention between avoid and focus rules.
- **Agent Distribution**: Validated rules are distributed via `distributeConfig` and interpolated into agent prompts through [`src/prompts/prompt-manager.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/prompts/prompt-manager.ts) using `{{RULES_AVOID}}` and `{{RULES_FOCUS}}` placeholders.
- **Practical Application**: Combine path-based focus rules with avoid rules to create precise API endpoint scoping without exposing sensitive routes or production health checks.

## Frequently Asked Questions

### What happens if I put the same rule in both focus and avoid collections?

Shannon's configuration parser explicitly prevents this scenario. The `checkForConflicts` function in [`src/config-parser.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts) scans for identical `type:url_path` pairs across both collections and throws a `PentestError` if any overlap is detected, ensuring unambiguous scoping instructions.

### Can I use wildcards or regex in url_path values?

Based on the current implementation in [`src/types/config.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/types/config.ts) and the validation logic in [`src/config-parser.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts), rules use exact string matching for `url_path` values. The validation specifically checks for dangerous patterns like `../` or `<` but does not implement regex or glob pattern matching, requiring explicit endpoint definitions for precise control.

### How does Shannon handle conflicting path rules with different descriptions?

The `checkForDuplicates` function in [`src/config-parser.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts) identifies rules by their composite key of `type:url_path`, not by description. If two rules share the same type and path but have different descriptions, the parser still rejects the configuration as a duplicate, enforcing unique scoping directives regardless of descriptive text.

### Is authentication configuration required when setting up focus and avoid rules?

No, the `authentication` section is entirely optional. As shown in the `DistributedConfig` type definition and the `distributeConfig` function in [`src/config-parser.ts`](https://github.com/KeygraphHQ/shannon/blob/main/src/config-parser.ts), you can configure standalone `avoid` and `focus` rules without defining authentication flows, making it possible to scope public API endpoints or unauthenticated routes independently.