Skip to content

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
  • 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
00000000-0000-0000-0000-000000000001    Custom Auth Check         HIGH        2025-10-15T10:00:00Z  2025-10-15T10:00:00Z
00000000-0000-0000-0000-000000000002    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:

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

Aliases: c, add, new

Example rule configuration:

{
  "name": "Custom Authentication Check",
  "severity": "HIGH",
  "description": "Validates custom authentication requirements",
  "context": "DAST",
  "rule": {
    "type": "detection",
    "pattern": "...",
    "remediation": "Implement proper authentication..."
  }
}

For complete schema, see Escape V3 API Documentation.

Updating Custom Rules

Modify an existing custom rule.

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

Aliases: u, edit

Deleting Custom Rules

Remove a custom rule from your organization.

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

Aliases: d, rm

Custom Rule Examples

Business Logic Rule

cat > business-logic-rule.json << 'EOF'
{
  "name": "Price Manipulation Check",
  "severity": "CRITICAL",
  "description": "Detects ability to manipulate prices in checkout flow",
  "context": "DAST"
}
EOF

escape-cli custom-rules create < business-logic-rule.json

Compliance Rule

cat > compliance-rule.json << 'EOF'
{
  "name": "PCI-DSS Compliance Check",
  "severity": "HIGH",
  "description": "Validates PCI-DSS requirements",
  "context": "ASM"
}
EOF

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

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
00000000-0000-0000-0000-000000000001    production         e03d3d
00000000-0000-0000-0000-000000000002    staging            f5a623
00000000-0000-0000-0000-000000000003    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 assets by tag
escape-cli assets list --tag-ids <tag-id>

# 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 '.id')
echo "Uploaded with ID: $UPLOAD_ID"

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

Using Uploaded Files

Use the upload ID when creating profiles:

# Capture upload ID
UPLOAD_ID=$(escape-cli upload schema < large-schema.json -o json | jq -r '.id')

# Create profile referencing the upload
cat > profile-config.json << EOF
{
  "name": "My API Profile",
  "asset_id": "00000000-0000-0000-0000-000000000000",
  "schema_upload_id": "$UPLOAD_ID",
  "configuration": {
    ...
  }
}
EOF

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

Complete Workflow Example

#!/bin/bash
# Complete workflow: Upload schema and create profile

# 1. Upload large OpenAPI spec
echo "Uploading schema..."
UPLOAD_ID=$(escape-cli upload schema < large-openapi-spec.json -o json | jq -r '.id')

if [ -z "$UPLOAD_ID" ]; then
  echo "Failed to upload schema"
  exit 1
fi

echo "Schema uploaded with ID: $UPLOAD_ID"

# 2. Create profile using uploaded schema
echo "Creating profile..."
cat > temp-profile.json << EOF
{
  "name": "Production API",
  "asset_id": "$ASSET_ID",
  "schema_upload_id": "$UPLOAD_ID",
  "configuration": {
    "authentication": {
      "type": "bearer",
      "token": "$API_TOKEN"
    }
  }
}
EOF

PROFILE_ID=$(escape-cli profiles create-rest < temp-profile.json -o json | jq -r '.id')
rm temp-profile.json

echo "Profile created with ID: $PROFILE_ID"

# 3. Start scan
echo "Starting scan..."
escape-cli scans start "$PROFILE_ID" --watch

Upload Limitations

  • Files are stored temporarily
  • Maximum file size limits apply (check platform documentation)
  • Upload IDs are valid for a limited time
  • 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

#!/bin/bash
# Upload multiple schemas and create profiles

SCHEMAS_DIR="./schemas"

for schema_file in "$SCHEMAS_DIR"/*.json; do
  SCHEMA_NAME=$(basename "$schema_file" .json)
  echo "Processing $SCHEMA_NAME..."

  # Upload schema
  UPLOAD_ID=$(escape-cli upload schema < "$schema_file" -o json | jq -r '.id')

  if [ -z "$UPLOAD_ID" ]; then
    echo "  ✗ Failed to upload schema"
    continue
  fi

  # Create profile
  cat > temp-profile.json << EOF
{
  "name": "$SCHEMA_NAME Profile",
  "schema_upload_id": "$UPLOAD_ID"
}
EOF

  PROFILE_ID=$(escape-cli profiles create-rest < temp-profile.json -o json | jq -r '.id')
  rm temp-profile.json

  echo "  ✓ Created profile: $PROFILE_ID"
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 (limited validity period)
  • 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 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