# API Testing Scope

The scan scope can be refined through the definition of allowlists and blocklists, which specify operations to be included or excluded from security testing. When operations are blocklisted, they won't be evaluated during the scan execution. When allowlists are defined, only operations that match the allowlist rules will be tested.

Both GraphQL and REST API DAST configurations use the same scope structure with `allowlist` and `blocklist` parameters. The `extend_global_scope` parameter controls whether the scanner-specific scope extends the global allowlist. It defaults to `true`. The global blocklist always applies, even when `extend_global_scope` is `false`.

## GraphQL Scope

The `scope` parameter is defined within the GraphQL scan configuration and supports both allowlist and blocklist rules.

```yaml
graphql_api_dast:
  scope:
    extend_global_scope: true
    blocklist:
      - type: graphql_operation
        value: 'mutation.createUser'
      - type: graphql_operation
        value: 'mutation\.delete.*'
        operation: regex
    allowlist:
      - type: graphql_operation
        value: 'query\.users'
        operation: regex
```

The `type` field specifies the rule type (`graphql_operation` for GraphQL operations). GraphQL scope also evaluates the endpoint URL, so `domain` and `rest_api_url` rules can restrict endpoints. The `value` field contains the operation name pattern. The `operation` field specifies the matching operation (defaults to exact match if not provided). See [Scope Operations](<#scope-operations>) for details on available operations.

Reference: [GraphQL configuration](<https://docs.escape.tech/documentation/reference/configuration-schemas/api-dast-graphql/index.md>)

## REST Scope

The `scope` parameter in REST API DAST is configured as a list of rules that define which API endpoints should be included or excluded from testing.

```yaml
rest_api_dast:
  scope:
    extend_global_scope: true
    blocklist:
      - type: rest_api_path
        value: '/api/auth/login'
        method: POST
      - type: rest_api_path
        value: '/api/users/.*'
        operation: regex
      - type: rest_api_path
        value: '/api/admin/.*'
        operation: regex
    allowlist:
      - type: rest_api_path
        value: '/api/v[0-9]+/users'
        operation: regex
```

REST API DAST evaluates templates by path and method using `rest_api_path` rules. The `value` field contains the path pattern; the optional `method` field restricts the HTTP method, for example GET or POST. The `operation` field controls matching (see [Scope Operations](<#scope-operations>)).

Use `rest_api_path` with an optional `method` to select REST API DAST targets. These targets are evaluated by path: the `domain` field on path rules, `domain` rules, and `rest_api_url` rules have no effect on them. Use URL-based rules for GraphQL endpoint scope or [WebApp API testing scope](<https://docs.escape.tech/documentation/dast/webapp-testing/scope/#api-testing-scope-configuration>).

Reference: [REST configuration](<https://docs.escape.tech/documentation/reference/configuration-schemas/api-dast-rest/index.md>)

## Scope Operations

Scope rules support various matching operations to provide flexible pattern matching. The `operation` field in each rule specifies how the `value` should be matched against targets. When not specified, the operation defaults to `equals` (exact match).

### Supported Operations

- **`equals`** (default): Exact string match

  - Example: `value: "mutation.createUser"` matches exactly `"mutation.createUser"`
- **`starts_with`**: Match if target starts with the value

  - Example: `value: "query.users"` matches `"query.users"`, `"query.usersById"`, `"query.usersList"`
- **`ends_with`**: Match if target ends with the value

  - Example: `value: "User"` matches `"createUser"`, `"updateUser"`, `"deleteUser"`
- **`contains`**: Match if target contains the value anywhere

  - Example: `value: "auth"` matches `"authentication"`, `"authorize"`, `"getUserAuth"`
- **`regex`**: Match using regular expression pattern

  - Example: `value: "mutation\\.(create|update|delete).*"`, `operation: regex` matches GraphQL mutations starting with create, update, or delete
  - Uses complete pattern matching against the target value, not a substring search. `rest_api_path` matches only the URL path, while `rest_api_url`, where endpoint URL targets are evaluated, matches the complete URL including the scheme and host
- **`wildcard`**: Match using wildcard/glob pattern

  - Example: `value: "query.user*"` matches `"query.user"`, `"query.users"`, `"query.userById"`
  - Supports `*` (any characters), `?` (single character), `[seq]` (a character in the sequence) and `[!seq]` (a character outside the sequence)