# Profiles Management

Profiles define how security scans are executed against your applications. Each profile contains configuration for scan parameters, authentication, scheduling, and risk categories to test.

## Understanding Profiles

A profile connects an **asset** (your application) with scan configuration and execution settings. Profiles are specific to the application type:

- **REST API profiles** - For RESTful API services
- **GraphQL profiles** - For GraphQL API services
- **Web Application profiles** - For browser-based applications

## Listing Profiles

View all configured security testing profiles in your organization.

### Basic Usage

```bash
escape-cli profiles list
```

**Aliases:** `list`, `ls`

**Table Columns:** `ID`, `CREATED AT`, `ASSET TYPE`, `INITIATORS`, `SCORE`, `OPEN ISSUES`, `LAST SCAN STATUS`, `NAME`.

### Filtering Profiles

Use filters to find specific profiles:

```bash
# Search by name
escape-cli profiles list --search "Production"

# Filter by asset type
escape-cli profiles list --kind BLST_REST

# Filter by risk category
escape-cli profiles list --risk SENSITIVE_DATA

# Filter by initiator
escape-cli profiles list --initiator SCHEDULED

# Combine multiple filters
escape-cli profiles list --kind FRONTEND_DAST --risk EXPOSED

# Include pentest and ASM profiles (default list is DAST only)
escape-cli profiles list --all
```

**Available filters:**

| Flag | Description | Example Values |
| --- | --- | --- |
| `--all` | Include all profile kinds (pentest and ASM). Default is DAST. | \- |
| `-d, --domain` | Filter by domain | `example.com` |
| `-n, --initiator` | Filter by initiator | `SCHEDULED`, `MANUAL`, `CI` |
| `-k, --kind` | Filter by profile type | `BLST_REST`, `BLST_GRAPHQL`, `FRONTEND_DAST` |
| `-r, --risk` | Filter by risk category | `SENSITIVE_DATA`, `EXPOSED`, `BOLA` |
| `-s, --search` | Search by name | `Production` |
| `-a, --asset-id` | Filter by asset ID | UUID |
| `-i, --issue-id` | Filter by issue ID | UUID |
| `-t, --tag-id` | Filter by tag ID | UUID |

### JSON Output

Get structured data for automation:

```bash
escape-cli profiles list --output json
```

**API Reference:** [GET /profiles](<https://public.escape.tech/v3/#tag/profiles/get/profiles>)

## Getting Profile Details

Retrieve detailed information about a specific profile.

```bash
escape-cli profiles get <profile-id>
```

**Aliases:** `get`, `describe`

**Example:**

```bash
escape-cli profiles get 11111111-1111-1111-1111-111111111111
```

**Table Columns:** `ID`, `CREATED AT`, `CRON`, `RISKS`, `NAME`, `EXTRA ASSETS`.

**API Reference:** [GET /profiles/{id}](<https://public.escape.tech/v3/#tag/profiles/get/profiles/%7BprofileId%7D>)

## Creating Profiles

Create new security testing profiles for your applications. The creation process varies by application type.

### Configuration Fields Compatibility

When creating profiles through the Public API:

- `configurationObject` (object) is the preferred field for typed configuration payloads.
- `configuration` (string) is the legacy compatibility field and must contain a JSON-encoded configuration object. The backend accepts both. If both fields are sent, `configurationObject` is used first.

### Scan Mode (Production vs. Pre-production)

In the Escape product UI, basic scan settings use **Production** and **Pre-production**. In the Public API and configuration JSON, the same choice is expressed as:

| UI label | API / config value | When to use it |
| --- | --- | --- |
| Production | `read_only` | Safer, non-destructive testing; avoids state-changing operations on the target. |
| Pre-production | `read_write` | Full testing including mutations; intended for staging, pre-production, or dedicated test environments. |

**Ways to set it when creating a profile** (Public API):

1. **Top-Level Field**: Send optional `mode` with value `read_only` or `read_write` on the create-profile request body (all profile types: REST, GraphQL, WebApp, and Automated Pentest variants).
2. **Legacy Create-Profile Input**: The create-profile parser also accepts the nested field for your scanner kind: `rest_api_dast.mode`, `graphql_api_dast.mode`, or `frontend_dast.mode` (in `configurationObject`, or in JSON content of legacy `configuration`).

These nested fields apply to profile creation compatibility. For `scans start --override`, use the top-level scanner configuration field `mode`. If you send both on creation, the **top-level `mode` wins**. If the request omits `mode`, Escape uses `mode` from the configuration JSON (top-level or legacy nested form), then falls back to `read_only`.

### Creating a REST API Profile

Create a profile for testing REST API services.

```bash
escape-cli profiles create-rest < profile-config.json
```

Or using pipe:

```bash
cat profile-config.json | escape-cli profiles create-rest
```

**Profile Configuration Structure:**

```json
{
  "assetId": "11111111-1111-1111-1111-111111111111",
  "name": "Production REST API",
  "proxyId": "22222222-2222-2222-2222-222222222222",
  "extraAssetIds": ["33333333-3333-3333-3333-333333333333"],
  "mode": "read_only",
  "tagsIds": []
}
```

**Required fields:**

- `assetId` - ID of the REST service asset
- `name` - Profile name for identification

**Optional fields:**

- `proxyId` - Location ID for scan execution (use `escape-cli locations list`)
- `extraAssetIds` - IDs of uploaded OpenAPI/Swagger schema assets (class `SCHEMA`). Pass multiple IDs to link several schemas to one profile.

`proxyId` and `extraAssetIds` are optional. Set `"start": false` to skip the initial scan; `start` defaults to `true`.

> [!NOTE]
>
> **Legacy `schemaId`**
>
> `schemaId` is still accepted for backward compatibility but deprecated. Prefer `extraAssetIds` for new integrations.

**API Reference:** [POST /profiles/rest](<https://public.escape.tech/v3/#tag/profiles/post/profiles/rest>)

### Creating a GraphQL Profile

Create a profile for testing GraphQL API services.

```bash
escape-cli profiles create-graphql < profile-config.json
```

**Profile Configuration Structure:**

```json
{
  "assetId": "11111111-1111-1111-1111-111111111111",
  "name": "GraphQL API Gateway",
  "proxyId": "22222222-2222-2222-2222-222222222222",
  "extraAssetIds": ["33333333-3333-3333-3333-333333333333"],
  "mode": "read_write",
  "tagsIds": []
}
```

**API Reference:** [POST /profiles/graphql](<https://public.escape.tech/v3/#tag/profiles/post/profiles/graphql>)

### Creating a Web Application Profile

Create a profile for testing browser-based web applications.

```bash
escape-cli profiles create-webapp < profile-config.json
```

**Profile Configuration Structure:**

```json
{
  "assetId": "11111111-1111-1111-1111-111111111111",
  "name": "Production Web Application",
  "proxyId": "22222222-2222-2222-2222-222222222222",
  "mode": "read_only",
  "tagsIds": []
}
```

**API Reference:** [POST /profiles/webapp](<https://public.escape.tech/v3/#tag/profiles/post/profiles/webapp>)

### Creating AI Pentesting Profiles (Beta)

> [!WARNING]
>
> **Beta**
>
> AI Pentesting profile creation is in beta and may change.

Create **AI Pentesting** profiles with the CLI (alias `caip`):

```bash
escape-cli profiles create-ai-pentest < profile-config.json
```

You can also use the Public API. These profiles run the automated pentesting scanner (including the XSS, SQLi, BOLA, and Business Logic agents).

Use the following endpoint (the linked asset’s type determines whether the profile targets a REST API, GraphQL API, or web application):

| Endpoint | Description |
| --- | --- |
| `POST /v3/profiles/ai-pentest` | Create an AI Pentesting profile (all asset types) |

The request body is the same as for DAST profiles. For example:

```json
{
  "assetId": "11111111-1111-1111-1111-111111111111",
  "name": "AI Pentest - Production REST API",
  "proxyId": "22222222-2222-2222-2222-222222222222",
  "extraAssetIds": ["33333333-3333-3333-3333-333333333333"],
  "mode": "read_only"
}
```

**API Reference:** See the [OpenAPI specification](<https://public.escape.tech/v3/openapi.json>) for full request and response schemas.

## Profile Configuration Best Practices

### Naming Conventions

Use clear, descriptive names that indicate:

- **Environment**: Production, Staging, Development
- **Application**: User Service, Payment API, Admin Portal
- **Purpose**: Weekly Scan, PR Checks, Compliance Testing

**Examples:**

```text
Production - User Authentication API
Staging - Payment Gateway - Weekly Scan
Development - GraphQL API - PR Checks
```

### Schema Management

For API profiles, ensure schemas are current:

1. Upload schema before creating the profile
2. Update schemas when your API changes
3. Version your schemas for tracking
4. Link multiple schemas via `extraAssetIds` when one API is described by several OpenAPI documents (for example one schema per microservice)

To update linked schemas on an existing profile, use `PUT /profiles/:profileId` with `extraAssetIds`.

### Location Selection

Choose the appropriate location based on your application:

- **Public locations**: For publicly accessible applications
- **Private locations**: For internal applications or those behind firewalls

### Tag Organization

Use tags to group related profiles:

- By team (frontend, backend, platform)
- By environment (production, staging)
- By compliance requirements (PCI-DSS, SOC2)
- By application criticality (critical, high, medium, low)

## Complete Profile Creation Example

Here's a complete workflow for creating a REST API profile:

```bash
# Step 1: Upload your OpenAPI schema
UPLOAD_ID=$(escape-cli upload schema -o json < openapi.json | jq -r '.')

# Step 2: Create a schema asset
cat <<EOF > schema-asset.json
{
  "asset_type": "SCHEMA",
  "upload": {
    "temporaryObjectKey": "$UPLOAD_ID"
  }
}
EOF
SCHEMA_ASSET_ID=$(escape-cli asset create -o json < schema-asset.json | jq -r '.id')

# Step 3: Create a service asset
cat <<EOF > service-asset.json
{
  "asset_class": "API_SERVICE",
  "asset_type": "REST",
  "url": "https://api.example.com"
}
EOF
SERVICE_ASSET_ID=$(escape-cli asset create -o json < service-asset.json | jq -r '.id')

# Step 4: Get available location
PROXY_ID=$(escape-cli locations list -o json | jq -r '.[0].id')

# Step 5: Create the profile
cat <<EOF > profile.json
{
  "assetId": "$SERVICE_ASSET_ID",
  "name": "Production REST API",
  "proxyId": "$PROXY_ID",
  "extraAssetIds": ["$SCHEMA_ASSET_ID"],
  "tagsIds": []
}
EOF
PROFILE_ID=$(escape-cli profiles create-rest -o json < profile.json | jq -r '.id')

echo "Profile created: $PROFILE_ID"

# A scan is automatically started when the profile is created
# To start additional scans manually:
escape-cli scans start $PROFILE_ID
```

## Profile Lifecycle

### Automatic Scan Triggering

When you create a new profile, Escape starts an initial scan unless you set `"start": false`.

### Manual Scan Triggering

Start scans on demand:

```bash
escape-cli scans start <profile-id>
```

See [Scans Management](<https://docs.escape.tech/documentation/automate/cli/scans/index.md>) for detailed scan operations.

### Profile Updates

```bash
escape-cli profiles update <profile-id> --name "User API" --description "Weekly scan" --cron "0 9 * * 6"
escape-cli profiles update <profile-id> --extra-asset-id <schema-asset-id>
escape-cli profiles update <profile-id> --clear-extra-assets
escape-cli profiles update-configuration <profile-id> < configuration.json
```

`update-configuration` reads a request with a `configuration` object from stdin and replaces the full configuration. Send all sections you want to keep. Inspect the request format with `escape-cli profiles update-configuration <profile-id> --input-schema`.

`update` has aliases `u` and `edit`; `update-configuration` has aliases `uc` and `update-config`. `--extra-asset-id` accepts comma-separated IDs and replaces the full list. It can't be combined with `--clear-extra-assets`.

### Schema Commands and Diagnostics

```bash
# Upload, create a schema asset, and attach it to the profile
escape-cli profiles upload-schema <profile-id> --file openapi.json

# Attach an existing upload
UPLOAD_ID=$(escape-cli upload schema -o json < openapi.json | jq -r '.')
escape-cli profiles update-schema <profile-id> "$UPLOAD_ID"

# Read schema metadata, or write schema bytes to a file
escape-cli profiles get-schema <profile-id>
escape-cli profiles get-schema <profile-id> --file openapi.json

# Inspect extra assets and validation problems
escape-cli profiles get <profile-id> --extra-assets
escape-cli profiles problems <profile-id>
```

Aliases: `ups` for `upload-schema`, `us` for `update-schema`, `gs` for `get-schema`, and `pb` for `problems`.

### Profile Deletion

```bash
escape-cli profiles delete <profile-id>
```

Aliases: `del`, `rm`.

## Troubleshooting

### Profile Creation Fails

**Issue**: "Asset not found"

- Verify the asset ID exists: `escape-cli assets get <asset-id>`
- Ensure you have permissions to access the asset

**Issue**: "Schema not found"

- Confirm the schema was successfully uploaded
- Check the schema asset ID is correct

**Issue**: "Invalid location"

- Verify the location exists: `escape-cli locations list`
- Ensure the location is enabled and healthy

### No Profiles Found

If `escape-cli profiles list` returns empty results:

- Verify your API key has the correct organization access
- Check if profiles exist in the web interface
- Confirm you're not filtering too restrictively

## Next Steps

- **[Assets Management](<https://docs.escape.tech/documentation/automate/cli/assets/index.md>)** - Learn to create and manage assets for your profiles
- **[Scans Management](<https://docs.escape.tech/documentation/automate/cli/scans/index.md>)** - Run and monitor security scans
- **[Practical Recipes](<https://docs.escape.tech/documentation/automate/cli/recipes/index.md>)** - Complete profile creation examples