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

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. 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 parses the YAML, validates it against the JSON schema in 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
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:

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:

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, 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:

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 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:

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:

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 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. 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.
• Rule Structure: Each rule requires a description, type (path, subdomain, method, etc.), and url_path value.
• Validation Pipeline: 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 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 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 and the validation logic in 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 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, you can configure standalone avoid and focus rules without defining authentication flows, making it possible to scope public API endpoints or unauthenticated routes independently.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}