Advanced Features¶

This guide covers advanced CLI features including custom rules, tags, and file uploads for extending your security testing capabilities.

Custom Rules¶

Custom rules allow you to define organization-specific security checks beyond the standard OWASP and industry tests.

Overview¶

Create custom rules for:

Business logic vulnerabilities
Company-specific security policies
Custom compliance requirements
API-specific security patterns

Rule Contexts:

ASM (API Security Management) - Attack surface monitoring
Business Logic Aware DAST (Dynamic Testing) - Active security testing

Rule Severity: CRITICAL, HIGH, MEDIUM, LOW, INFO

Listing Custom Rules¶

View all custom rules in your organization.

escape-cli custom-rules list

Aliases: ls, cr, rules

Example Output:

ID                                      NAME                       SEVERITY    CREATED AT            UPDATED AT
11111111-1111-1111-1111-111111111111    Custom Auth Check         HIGH        2025-10-15T10:00:00Z  2025-10-15T10:00:00Z
22222222-2222-2222-2222-222222222222    Business Logic Rule       MEDIUM      2025-10-14T15:30:00Z  2025-10-14T15:30:00Z

Getting Custom Rule Details¶

Retrieve detailed information about a specific rule.

escape-cli custom-rules get <rule-id>

Aliases: g

View rule content (-c is the short form):

escape-cli custom-rules get <rule-id> --content

Export rule:

escape-cli custom-rules get <rule-id> -o json > my-rule.json

Creating Custom Rules¶

Create a new custom rule from JSON configuration.

escape-cli custom-rules create < rule-config.json

Alias: c

The request wraps the definition in content.rule. Alert metadata, including name, severity, context, and category, belongs in content.rule.alert. Optional dastEnabled, inventoryEnabled, and tagIds fields belong at the top level.

Inspect the input schema before preparing your JSON:

escape-cli custom-rules create --input-schema

See the Custom Rules reference for rule definitions.

Updating Custom Rules¶

Modify an existing custom rule.

escape-cli custom-rules update <rule-id> < updated-rule.json

Alias: u

Deleting Custom Rules¶

Remove a custom rule from your organization.

escape-cli custom-rules delete <rule-id>

Alias: d

Tags¶

Tags help organize and filter assets, profiles, issues, and other resources across your organization.

Overview¶

Common Use Cases:

Environment labels (production, staging, development)
Team ownership (frontend-team, backend-team, security-team)
Criticality (critical, high-priority, low-priority)
Compliance (pci-dss, hipaa, gdpr)
Project grouping (project-alpha, project-beta)

Listing Tags¶

View all tags in your organization.

escape-cli tags list

Aliases: ls, tag

Example Output:

ID                                      NAME                COLOR
11111111-1111-1111-1111-111111111111    production         e03d3d
22222222-2222-2222-2222-222222222222    staging            f5a623
33333333-3333-3333-3333-333333333333    backend-team       4a90e2

Export tags:

escape-cli tags list -o json > organization-tags.json

Creating Tags¶

Create a new tag with custom name and color.

escape-cli tags create --name <name> --color <hex-color>

Aliases: cr, add, new

Color Format: Hex color code without # prefix

Examples:

# Production tag (red)
escape-cli tags create --name production --color e03d3d

# Staging tag (yellow)
escape-cli tags create --name staging --color f5a623

# Development tag (green)
escape-cli tags create --name development --color 50c878

# Team tags (various blues)
escape-cli tags create --name backend-team --color 4a90e2
escape-cli tags create --name frontend-team --color 7b68ee
escape-cli tags create --name security-team --color 00008b

# Priority tags
escape-cli tags create --name critical --color ff0000
escape-cli tags create --name high-priority --color ff6600
escape-cli tags create --name low-priority --color cccccc

# Compliance tags
escape-cli tags create --name pci-dss --color 9370db
escape-cli tags create --name hipaa --color 8b4513
escape-cli tags create --name gdpr --color 2f4f4f

Using Tags¶

Once created, use tag IDs to filter and organize resources:

# Filter profiles by tag
escape-cli profiles list --tag-id <tag-id>

# Filter issues by tag
escape-cli issues list --tag-id <tag-id>

# Update asset with tags
escape-cli assets update <asset-id> --tag-ids "tag-id-1,tag-id-2"

Tag Organization Strategy¶

By Environment¶

# Create environment tags
TAG_PROD=$(escape-cli tags create --name production --color e03d3d -o json | jq -r '.id')
TAG_STAGING=$(escape-cli tags create --name staging --color f5a623 -o json | jq -r '.id')
TAG_DEV=$(escape-cli tags create --name development --color 50c878 -o json | jq -r '.id')

# Tag assets by environment
escape-cli assets update prod-api-id --tag-ids "$TAG_PROD"
escape-cli assets update staging-api-id --tag-ids "$TAG_STAGING"

By Team¶

# Create team tags
TAG_BACKEND=$(escape-cli tags create --name backend-team --color 4a90e2 -o json | jq -r '.id')
TAG_FRONTEND=$(escape-cli tags create --name frontend-team --color 7b68ee -o json | jq -r '.id')

# Assign ownership
escape-cli assets update api-asset-id --tag-ids "$TAG_BACKEND"
escape-cli assets update webapp-asset-id --tag-ids "$TAG_FRONTEND"

By Criticality¶

# Create criticality tags
TAG_CRITICAL=$(escape-cli tags create --name critical --color ff0000 -o json | jq -r '.id')
TAG_HIGH=$(escape-cli tags create --name high-priority --color ff6600 -o json | jq -r '.id')

# Mark critical assets
escape-cli assets update payment-api-id --tag-ids "$TAG_CRITICAL"

File Upload¶

Upload large files (like API schemas) to temporary Escape storage for use in profile creation.

Overview¶

Use Cases:

Large OpenAPI/Swagger specifications
GraphQL schemas
Postman collections
Any schema file referenced in profile creation

Uploading Schemas¶

Upload an API schema file.

escape-cli upload schema < schema-file.json

Aliases: s

Returns: Upload ID for use in profile creation

Examples:

# Upload OpenAPI schema
escape-cli upload schema < openapi-spec.json

# Upload and capture ID
UPLOAD_ID=$(escape-cli upload schema < schema.json -o json | jq -r '.')
echo "Uploaded with ID: $UPLOAD_ID"

# Upload GraphQL schema
escape-cli upload schema < graphql-schema.graphql

Using Uploaded Files¶

Upload JSON output is a string. Extract it with jq -r '.', create a schema asset, then pass that asset's ID in extraAssetIds:

UPLOAD_ID=$(escape-cli upload schema -o json < openapi.json | jq -r '.')
SCHEMA_ASSET_ID=$(jq -nc --arg upload "$UPLOAD_ID" '{
  asset_type: "SCHEMA", upload: {temporaryObjectKey: $upload}
}' | escape-cli assets create -o json | jq -r '.id')

SERVICE_ASSET_ID=$(echo '{"asset_class":"API_SERVICE","asset_type":"REST","url":"https://api.example.com"}' |
  escape-cli assets create -o json | jq -r '.id')

jq -nc --arg asset "$SERVICE_ASSET_ID" --arg schema "$SCHEMA_ASSET_ID" '{
  assetId: $asset, name: "Production API", extraAssetIds: [$schema], start: false
}' | escape-cli profiles create-rest -o json

assetId and name are required. extraAssetIds attaches schema assets; an upload ID isn't a profile field. For scan configuration, use configurationObject for a JSON object or configuration for a JSON-encoded string. See Creating Profiles for the full workflow.

Upload Requirements¶

Files are stored temporarily
Maximum file size limits apply (check platform documentation)
Upload IDs expire
Use immediately after upload for profile creation

Integration Examples¶

Automated Tag Management¶

#!/bin/bash
# Auto-tag new assets based on naming conventions

escape-cli assets list -o json | jq -c '.[]' | while read -r asset; do
  ASSET_ID=$(echo "$asset" | jq -r '.id')
  ASSET_NAME=$(echo "$asset" | jq -r '.name')

  # Determine tags based on name
  TAGS=""

  if [[ $ASSET_NAME == *"prod"* ]]; then
    TAGS="$TAG_PROD"
  elif [[ $ASSET_NAME == *"staging"* ]]; then
    TAGS="$TAG_STAGING"
  fi

  if [[ $ASSET_NAME == *"api"* ]]; then
    TAGS="$TAGS,$TAG_API"
  fi

  if [ -n "$TAGS" ]; then
    escape-cli assets update "$ASSET_ID" --tag-ids "$TAGS"
    echo "Tagged $ASSET_NAME"
  fi
done

Custom Rule Deployment¶

#!/bin/bash
# Deploy custom rules across environments

RULES_DIR="./custom-rules"

for rule_file in "$RULES_DIR"/*.json; do
  echo "Deploying rule: $rule_file"

  RULE_ID=$(escape-cli custom-rules create < "$rule_file" -o json | jq -r '.id')

  if [ -n "$RULE_ID" ]; then
    echo "  ✓ Deployed with ID: $RULE_ID"
  else
    echo "  ✗ Failed to deploy"
  fi
done

Bulk Schema Upload¶

For each schema file, create a schema asset and a REST profile. Set ASSET_ID to the existing REST service asset's ID:

#!/bin/bash
set -euo pipefail

for schema_file in ./schemas/*.json; do
  UPLOAD_ID=$(escape-cli upload schema -o json < "$schema_file" | jq -r '.')
  SCHEMA_ASSET_ID=$(jq -nc --arg upload "$UPLOAD_ID" '{
    asset_type: "SCHEMA", upload: {temporaryObjectKey: $upload}
  }' | escape-cli assets create -o json | jq -r '.id')

  jq -nc --arg asset "$ASSET_ID" --arg schema "$SCHEMA_ASSET_ID" \
    --arg name "$(basename "$schema_file" .json) Profile" '{
      assetId: $asset, name: $name, extraAssetIds: [$schema], start: false
    }' | escape-cli profiles create-rest -o json
done

Best Practices¶

Custom Rules¶

Test thoroughly before deploying to production
Document rules clearly with descriptions and remediation steps
Version control rule definitions
Review regularly and update as threats evolve
Start with INFO severity for new rules, increase after validation

Tags¶

Establish conventions early (naming, colors, usage)
Use consistently across all resources
Document tag meanings for team reference
Review and clean up unused tags periodically
Limit tag count to maintain clarity

File Uploads¶

Validate files before upload
Use immediately after upload, before the upload ID expires
Monitor file sizes to avoid upload failures
Clean up unused uploads when possible
Version control schema files for traceability

Troubleshooting¶

Custom Rules Not Applying¶

If custom rules aren't detected:

Verify rule is enabled
Check rule context matches scan type (ASM vs Business Logic Aware DAST)
Review rule syntax and pattern
Test rule on known vulnerable endpoint
Check scan logs for rule execution

Tags Not Appearing¶

If tags don't show up:

Verify tag was created successfully
Check tag ID is correct
Ensure you have permission to view tags
Refresh or re-query the resource

Upload Failures¶

If schema upload fails:

Check file format is valid JSON
Verify file size is within limits
Ensure network connectivity
Try uploading a smaller file first
Check API authentication

Next Steps¶

Profiles Management - Create profiles with uploaded schemas
Assets Management - Organize assets with tags
Issues Management - Filter issues by tags
Practical Recipes - Complete workflow examples