# cURL Sequence Authentication with Escape

## Description

The `cURL Sequence` authentication preset facilitates complex authentication flows by executing a templated sequence of cURL requests in a secure sandboxed cURL simulator:

- **Templated cURL Requests**: Enables the definition of a sequence of cURL requests, where each request can be templated with variables.
- **Dynamic Token Extractions**: Variables are dynamically extracted from the responses of these requests, allowing for sequential data dependency across requests.
- **Token Re-injection**: Extracted tokens or variables can be reinjected into subsequent authenticated requests.
- **User-Specific Variables**: Supports defining user-specific variables that can be injected into the cURL sequences.

This preset is particularly useful for complex authentication scenarios where multiple steps or interactions are required, and where each step might depend on the outcome of the previous one.

**Warning**: This preset requires to name your variables in order to be able to extract and inject them properly in the templates or the final injections.

The simulator supports a subset of arguments commonly used in `cURL`:

- `url`: The URL for the HTTP request.
- `-X`, `--request`: Specify a custom request method to use when communicating with the HTTP server.
- `-H`, `--header`: Add a header to the request (can be used multiple times for multiple headers).
- `-b`, `--cookie`: Add a cookie to the request (can be used multiple times for multiple cookies).
- `-d`, `--data`, `--data-ascii`, `--data-binary`, `--data-raw`: Sends the specified data in a POST request.
- `-u`, `--user`: Specify the user and password for server authentication.
- `-A`, `--user-agent`: Sets the user agent string for the HTTP request.
- `-x`, `--proxy`: Use the specified proxy.
- `-k`, `--insecure`: Allow connections to SSL sites without certificates.
- `-L`, `--location`: Follow redirects (the maximum number of redirects is defined by `--max-redirs`).
- `--max-redirs`: Set the maximum number of redirections to follow for `-L`.
- `-m`, `--max-time`: Maximum time in seconds for the request to complete.

**Note**: The simulator doesn't support all `cURL` arguments. Adding unsupported arguments may result in an error.

## Examples

```yaml
presets:
-   type: curl_sequence
    requests:
    -   curl: curl -X POST https://api.example.com/login -d "username={{username}}&password={{password}}"
        extractions:
        -   name: session_id
            key: SessionID
            location: cookie
        -   name: csrfToken
            key: X-CSRF-Token
            location: header
    -   curl: 'curl -X POST https://auth.example.com/token?session_id={{session_id}}
            -H "X-CSRF-Token: {{csrfToken}}"'
        extractions:
        -   name: bearerToken
            key: bearer
            location: body
    injections:
    -   key: X-CSRF-Token
        location: header
        variable: csrfToken
    -   key: Authorization
        location: header
        prefix: Bearer
        variable: bearerToken
    users:
    -   username: user1
        variables:
            username: user1
            password: user1Password
    -   username: admin2
        variables:
            username: user2
            password: user2Password
```

```yaml
presets:
-   type: curl_sequence
    requests:
    -   curl: curl -X GET https://api.example.com/auth -H "key:1234567890" -H "Content-Type:application/json"
            -d '{}'
        extractions:
        -   name: token_one
            key: access_token
            location: body
    -   curl: curl -X POST https://second.api.example.com/auth -H "Authorization:Bearer
            {{token_one}}" -H "Content-Type:application/json" -d "username=user1&password=pass1"
        extractions:
        -   name: token_two
            key: access_token
            location: body
    injections:
    -   key: Authorization
        location: header
        prefix: Bearer
        variable: token_two
    users:
    -   username: user1
```

## Extensive Configuration

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `injections` | `List[`[HTTPInjection](<#HTTPInjection>)`]` | `null` | Final variables injected into the authenticated requests. |
| `requests` \* | `List[`[CurlSequenceRequestPreset](<#CurlSequenceRequestPreset>)`]` |  | A sequence of curl templates used to make requests and extract variables. |
| `type` | `Const[curl_sequence]` | `curl_sequence` |  |
| `users` \* | `List[`[CurlSequenceUserPreset](<#CurlSequenceUserPreset>)`]` |  | The list of users to generate tokens for. |

## Objects

### CurlSequenceRequestPreset

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `curl` \* | `string` |  | A curl template used to make a request. |
| `extractions` | `List[`[HTTPExtraction](<#HTTPExtraction>)`]` | `null` | Variables extracted from the response that can be templated in further requests. |
| `timeout` | `integer` | `null` | The timeout of this request in seconds. Overrides `-m` / `--max-time` from the curl command when set. |

### CurlSequenceUserPreset

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `allow_failure` | `boolean` | `false` | If false, authentication failure for this user will fail the scan. Ignored for the main user: failures for main user are always fatal. |
| `basic` | `string` | `null` | The basic to attach Reach the Login Page and attack to the HTTP requests sent for this user. |
| `cookies` | `Dict[string, string]` | `null` | Optional cookies injected during the authentication process and in authenticated requests. |
| `digest` | `string` | `null` | The digest to attach Reach the Login Page and attack to the HTTP requests sent for this user. |
| `headers` | `Dict[string, string]` | `null` | Optional headers injected during the authentication process and in authenticated requests. |
| `main_user` | `boolean` | `false` | When running a WebApp Testing scan, this indicates that the scanner must use this user when crawling. There must be only one main user per scan. If none is provided, a random user will be selected. |
| `query_parameters` | `Dict[string, string]` | `null` | Optional query parameters injected during the authentication process and in authenticated requests. |
| `role` | `string` | `null` | The role of the user (for example, admin or user). |
| `username` \* | `string` |  | The arbitrary name that identifies the user. |
| `variables` | `Dict[string, string]` | `null` | A dict of variables to inject into the cURL sequences. |

### HTTPExtraction

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `key` \* | `string` |  | The key to use for the extracted value, depending on the location |
| `location` \* | [HTTPLocation](<#HTTPLocation>) |  | The location of the HTTP request where the value should be extracted |
| `name` \* | `string` |  | The name of the variable to store the extracted value into |
| `regex` | `string` | `null` | The regex to use to extract the token from the key value. By default the entire value is taken. |

### HTTPInjection

| Property | Type | Default | Description |
| --- | --- | --- | --- |
| `key` \* | `string` |  | The key to use for the injected token. Its usage depends on the location. For headers, cookies,and query parameters, this key describes the name of the header, cookie or query parameter. For a body location, the key is the field where the token should be injected within the request bodies |
| `location` \* | [HTTPLocation](<#HTTPLocation>) |  | The location of the HTTP request where the token should be injected |
| `prefix` | `string` | `null` | A prefix to prepend to the token before it's injected |
| `variable` \* | `string` |  | The name of a variable to retrieve to create the token's value. If not provided, the token will be inferred as the first successful extraction of the procedure |

## Enums

### HTTPLocation

| Value |
| --- |
| `header` |
| `cookie` |
| `body` |
| `query` |