# Extractors

> [!NOTE]
>
> **Available on API custom rules only**
>
> Extractors are an API-only feature. WebApp custom rules drive the browser via the `seed:` block instead: see [Seeders](<https://docs.escape.tech/documentation/dast/custom-rules/seeders/index.md>).

The extractors are used to extract the data from the response. This data can be used later to re-inject into requests, enhance alert context

## Block Structure

```yaml
extractors:
  trigger:
    - if: response.status_code
      is: 200
  extract:
    - key: response.body.json
      jq: '.user.id'
      variable: 'user_id'
```

## Variable Injection

Variables extracted can be reused in different blocks in custom rules. Supported blocks will include a `use_extraction` attribute. When set to true, this will trigger parsing of used variables.

This currently includes:

- [Detectors](<https://docs.escape.tech/documentation/dast/custom-rules/detectors/index.md>)
- [Mutators](<https://docs.escape.tech/documentation/dast/custom-rules/mutators/index.md>)

### Example

```yaml
transform:
    trigger:
      - if: schema.url
        is: '/api/v1/tested/route'
    mutate:
      - key: schema.url
        value: '/api/v2/{{user_id}}'
        use_extraction: true
```

### Properties

- `trigger`: The detectors to trigger the extraction on the request or response. [Detectors](<https://docs.escape.tech/documentation/dast/custom-rules/detectors/index.md>)
- `extract`: The extractions to apply to the request/response. (See below)

---

## Available Extractors

### Schema URL Extractor

`key: schema.url`

You can use this extractor to extract variables from the schema URL.

#### Example

This example will extract the schema URL and store it in the variable `request_url`.

```yaml
extractors:
  trigger:
    - if: response.status_code
      is: 200
  extract:
    - key: schema.url
      variable: 'request_url'
```

#### Properties

- `variable`: The variable name (Case Insensitive) to store the extracted data.
- `can_overwrite`: Whether the extractor can overwrite the variable if it already exists.

---

### Response Body JSON Extractor

`key: response.body.json`

You can use this extractor to extract variables from the response body JSON.

#### Example

This example will extract the user ID from the response body JSON and store it in the variable `user_id`.

```yaml
extractors:
  trigger:
    - if: response.status_code
      is: 200
  extract:
    - key: response.body.json
      jq: '.user.id'
      variable: 'user_id'
```

#### Properties

- `variable`: The variable name (Case Insensitive) to store the extracted data.
- `can_overwrite`: Whether the extractor can overwrite the variable if it already exists.
- `jq`: JQ query to apply to the JSON body. See [https://stedolan.github.io/jq/manual/](<https://stedolan.github.io/jq/manual/>)

---

### Response Header Extractor

`key: response.headers`

You can use this extractor to extract variables from the response headers.

#### Example

This example will extract a token from the response header `X-Token` and store it in the variable `x_token`.

```yaml
extractors:
  trigger:
    - if: response.status_code
      is: 200
  extract:
    - key: response.headers
      name: 'X-Token'
      variable: 'x_token'
```

#### Properties

- `variable`: The variable name (Case Insensitive) to store the extracted data.
- `can_overwrite`: Whether the extractor can overwrite the variable if it already exists.
- `name`: Header name to extract from

---

### Response Header Extractor

`key: response.body.text`

You can use this extractor to extract variables from the response body text.

#### Example

This example will extract the response body text and store it in the variable `body_data`.

```yaml
extractors:
  trigger:
    - if: response.status_code
      is: 200
  extract:
    - key: response.body.text
      variable: 'body_data'
```

#### Properties

- `variable`: The variable name (Case Insensitive) to store the extracted data.
- `can_overwrite`: Whether the extractor can overwrite the variable if it already exists.

---

### Response Cookies Extractor

`key: response.cookies`

You can use this extractor to extract variables from the response cookies.

#### Example

This example will extract a session cookie returned in response (`set-cookie`) and store it in the variable `session`.

```yaml
extractors:
  trigger:
    - if: response.status_code
      is: 200
  extract:
    - key: response.cookies
      name: 'session'
      variable: 'session'
```

#### Properties

- `variable`: The variable name (Case Insensitive) to store the extracted data.
- `can_overwrite`: Whether the extractor can overwrite the variable if it already exists.
- `name`: Cookie name to extract from

---

### Response Status Code Extractor

`key: response.status_code`

You can use this extractor to extract the response status code as a variable.

#### Example

This example will extract the response status code and store it in the variable `status_code`.

```yaml
extractors:
  extract:
    - key: response.status_code
      variable: 'status_code'
```

#### Properties

- `variable`: The variable name (Case Insensitive) to store the extracted data.
- `can_overwrite`: Whether the extractor can overwrite the variable if it already exists.

---

### Request Cookies Extractor

`key: request.cookies`

You can use this extractor to extract variables from the request cookies.

#### Example

This example will extract a session cookie sent in request (`cookie`) and store it in the variable `session`.

```yaml
extractors:
  trigger:
    - if: response.status_code
      is: 200
  extract:
    - key: request.cookies
      name: 'session'
      variable: 'session'
```

#### Properties

- `variable`: The variable name (Case Insensitive) to store the extracted data.
- `can_overwrite`: Whether the extractor can overwrite the variable if it already exists.
- `name`: Cookie name to extract from

---

### Response Duration Extractor

`key: response.duration`

You can use this extractor to extract the response duration as a variable.

#### Example

This example will extract the response duration and store it in the variable `duration`.

```yaml
extractors:
  extract:
    - key: response.duration
      variable: 'duration'
```

#### Properties

- `variable`: The variable name (Case Insensitive) to store the extracted data.
- `can_overwrite`: Whether the extractor can overwrite the variable if it already exists.

---

### Request Argument Extractor

`key: request.argument`

You can use this extractor to extract an argument from request body as a variable.

#### Example

This example will extract the request argument value if it matches the given scalar and store it in the variable `arg`.

```yaml
extractors:
  extract:
    - key: request.argument
      variable: 'arg'
      scalars:
        - id
        - uuid
```

This example will extract the user ID sent in a request body JSON and store it in the variable `arg`.

```yaml
extractors:
  extract:
    - key: request.argument
      variable: 'arg'
      jq: '.user.id'
```

#### Properties

- `variable`: The variable name (Case Insensitive) to store the extracted data.
- `can_overwrite`: Whether the extractor can overwrite the variable if it already exists.
- `jq`: JQ query to apply to the JSON body. See [https://stedolan.github.io/jq/manual/](<https://stedolan.github.io/jq/manual/>)

---