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

Example Output:

ID                                    CREATED AT                ASSET TYPE  INITIATORS      NAME
00000000-0000-0000-0000-000000000001  2025-08-14T11:54:56.653Z  WEBAPP      [SCHEDULED]     Production Web App
00000000-0000-0000-0000-000000000002  2025-07-22T09:12:34.221Z  REST        [MANUAL]        User API Service
00000000-0000-0000-0000-000000000003  2025-06-15T14:28:11.024Z  GRAPHQL     [CI]            GraphQL Gateway

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 BLST_WEBAPP --risk EXPOSED

Available filters:

Flag	Description	Example Values
`--all`	Include ASM profiles	-
`-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`, `BLST_WEBAPP`
`-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:

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 00000000-0000-0000-0000-000000000001

Example Output:

ID                                    CREATED AT                CRON       RISKS             NAME
00000000-0000-0000-0000-000000000001  2025-04-22T14:44:19.805Z  0 9 * * 6  [SENSITIVE_DATA]  User API Service

API Reference: GET /profiles/{id}

Creating Profiles¶

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

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

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).
Inside configuration JSON — set the nested field for your scanner kind: rest_api_dast.mode, graphql_api_dast.mode, or frontend_dast.mode.

If you send both, the top-level mode wins. If you omit both, the profile defaults to read_only unless your configuration JSON already defines a mode in the nested object (then that value is used).

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": "00000000-0000-0000-0000-000000000001",
  "name": "Production REST API",
  "proxyId": "00000000-0000-0000-0000-000000000002",
  "schemaId": "00000000-0000-0000-0000-000000000003",
  "mode": "read_only",
  "tagsIds": []
}

Required fields:

assetId - ID of the REST service asset
name - Profile name for identification
proxyId - Location ID for scan execution (use escape-cli locations list)
schemaId - ID of the uploaded OpenAPI/Swagger schema

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": "00000000-0000-0000-0000-000000000001",
  "name": "GraphQL API Gateway",
  "proxyId": "00000000-0000-0000-0000-000000000002",
  "schemaId": "00000000-0000-0000-0000-000000000003",
  "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": "00000000-0000-0000-0000-000000000001",
  "name": "Production Web Application",
  "proxyId": "00000000-0000-0000-0000-000000000002",
  "mode": "read_only",
  "tagsIds": []
}

API Reference: POST /profiles/webapp

Creating AI Pentesting Profiles (Beta)¶

Beta

AI Pentesting profile creation is in beta and may change.

In addition to DAST profiles, you can create AI Pentesting profiles via the Public API. These profiles run the automated pentesting scanner (including the XSS, SQLi, BOLA, and Business Logic agents).

The available endpoints are:

Endpoint	Application type
`POST /v3/profiles/ai-pentesting/rest`	REST API
`POST /v3/profiles/ai-pentesting/graphql`	GraphQL API
`POST /v3/profiles/ai-pentesting/webapp`	Web Application

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

{
  "assetId": "00000000-0000-0000-0000-000000000001",
  "name": "AI Pentest - Production REST API",
  "proxyId": "00000000-0000-0000-0000-000000000002",
  "schemaId": "00000000-0000-0000-0000-000000000003",
  "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:

Upload schema before creating the profile
Update schemas when your API changes
Version your schemas for tracking

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",
  "schemaId": "$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 automatically initiates an initial scan to establish a security baseline.

Manual Scan Triggering¶

Start scans on demand:

escape-cli scans start <profile-id>

See Scans Management for detailed scan operations.

Profile Updates¶

Profile configurations can be updated through the Escape web interface. CLI-based updates may be supported in future versions.

Profile Deletion¶

Profiles can be deleted through the Escape web interface. This action:

Removes the profile configuration
Preserves historical scan data
Cannot be undone

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