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¶

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:

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

JSON Output¶

Get structured data for automation:

escape-cli profiles list --output json

API Reference: GET /profiles

Getting Profile Details¶

Retrieve detailed information about a specific profile.

escape-cli profiles get <profile-id>

Aliases: get, describe

Example:

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

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

API Reference: GET /profiles/{id}

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:

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.

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

Or using pipe:

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

Profile Configuration Structure:

{
  "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.

API Reference: POST /profiles/rest

Creating a GraphQL Profile¶

Create a profile for testing GraphQL API services.

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

Profile Configuration Structure:

{
  "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

Creating a Web Application Profile¶

Create a profile for testing browser-based web applications.

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

Profile Configuration Structure:

{
  "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

Creating AI Pentesting Profiles (Beta)¶

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

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

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

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

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:

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

escape-cli scans start <profile-id>

See Scans Management for detailed scan operations.

Profile Updates¶

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¶

# 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¶

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 - Learn to create and manage assets for your profiles
• Scans Management - Run and monitor security scans
• Practical Recipes - Complete profile creation examples