Scans Management¶

Scans are the core of Escape's security testing capabilities. Each scan executes comprehensive security tests against your applications, identifying vulnerabilities, misconfigurations, and security risks.

Understanding Scans¶

A scan represents a single execution of security tests against a configured profile. During a scan, Escape:

• Analyzes your application's API or web interface
• Tests for security vulnerabilities across multiple categories
• Generates detailed findings with reproduction steps
• Provides remediation guidance for identified issues

Scans can be triggered manually, scheduled automatically, or integrated into CI/CD pipelines.

Listing Scans¶

List all scans with flexible filtering options.

escape-cli scans list [flags]

Aliases: list, ls

Filtering Options:

Basic Example:

# List all scans for a profile
escape-cli scans list -p 00000000-0000-0000-0000-000000000001

Advanced Filtering Examples:

# List only running scans
escape-cli scans list --status RUNNING

# List failed scans from last week
escape-cli scans list --status FAILED --after 2025-01-01T00:00:00Z

# List CI-triggered scans for multiple profiles
escape-cli scans list -p profile-1,profile-2 -i CI

# List REST API scans only
escape-cli scans list --kind BLST_REST

# Export to JSON
escape-cli scans list -o json > scans.json

Example Output:

ID                                      CREATED AT                           KIND           STATUS      PROGRESS    LINK
00000000-0000-0000-0000-000000000001    2025-02-05 08:34:47.541 +0000 UTC    BLST_REST      FINISHED    1.000000    https://...
00000000-0000-0000-0000-000000000002    2025-02-02 08:27:23.919 +0000 UTC    BLST_GRAPHQL   RUNNING     0.453000    https://...
00000000-0000-0000-0000-000000000003    2025-01-31 18:35:48.477 +0000 UTC    FRONTEND_DAST  FINISHED    1.000000    https://...

Scan Statuses¶

Scanner Types¶

Scan Initiators¶

Getting Scan Details¶

Retrieve detailed information about a specific scan.

escape-cli scans get <scan-id>

Aliases: describe, show, status

Example:

escape-cli scans get 00000000-0000-0000-0000-000000000001

Example Output:

ID                                      STATUS      CREATED AT                           PROGRESS
00000000-0000-0000-0000-000000000001    FINISHED    2024-11-27 08:06:59.576 +0000 UTC    1.000000

Starting a Scan¶

Initiate a new security scan against a profile.

Basic Usage¶

escape-cli scans start <profile-id>

Example:

escape-cli scans start 00000000-0000-0000-0000-000000000001

The command returns the scan ID. Save it to monitor progress:

SCAN_ID=$(escape-cli scans start <profile-id> -o json | jq -r '.id')
echo "Started scan: $SCAN_ID"

Start and Watch¶

Monitor the scan in real-time by adding the --watch flag:

escape-cli scans start <profile-id> --watch

Short form:

escape-cli scans start <profile-id> -w

Including Commit Metadata¶

When running scans from CI/CD pipelines, include commit information for better traceability:

escape-cli scans start <profile-id> \
  --commit-hash "a1b2c3d4" \
  --commit-branch "feature/security-improvements" \
  --commit-author "john.doe@example.com" \
  --commit-link "https://github.com/org/repo/commit/a1b2c3d4" \
  --profile-picture "https://github.com/johndoe.png"

Available commit metadata flags:

CI/CD Auto-Detection¶

The CLI automatically detects and uses commit information from CI/CD environments:

GitHub Actions:

• Auto-detects: GITHUB_SHA, GITHUB_REF_NAME, GITHUB_ACTOR, GITHUB_ACTOR_ID
• Automatically builds commit link from repository info

GitLab CI:

• Auto-detects: CI_COMMIT_SHA, CI_COMMIT_REF_NAME, GITLAB_USER_EMAIL
• Automatically builds commit link from CI_PROJECT_URL

CircleCI:

• Auto-detects: CIRCLE_SHA1, CIRCLE_BRANCH, CIRCLE_USERNAME

Generic/Local:

• Uses: COMMIT_HASH, COMMIT_LINK, COMMIT_BRANCH, COMMIT_AUTHOR

When running in these environments, commit metadata is populated automatically - no flags needed!

Configuration Overrides¶

Override scan configuration using JSON:

escape-cli scans start <profile-id> \
  --override '{"scan": {"read_only": true}}'

Short form:

escape-cli scans start <profile-id> -c '{"scan": {"read_only": true}}'

Common override examples:

# Run scan in read-only mode (no mutations)
--override '{"scan": {"read_only": true}}'

# Set custom timeout (in seconds)
--override '{"scan": {"timeout": 3600}}'

# Limit scan depth
--override '{"scan": {"max_depth": 5}}'

Watching Scan Progress¶

Monitor a running scan in real-time.

escape-cli scans watch <scan-id>

This command:

• Connects to the scan in progress
• Streams real-time events and progress updates
• Displays findings as they're discovered
• Blocks until the scan completes
• Returns exit code 0 on success, non-zero on failure

Example:

# Start a scan and save the ID
SCAN_ID=$(escape-cli scans start <profile-id> -o json | jq -r '.id')

# Watch the scan progress
escape-cli scans watch $SCAN_ID

Typical output:

Scan 00000000-0000-0000-0000-000000000001
Status: RUNNING
Progress: 25%
Tests completed: 150/600

Finding: SQL Injection vulnerability detected
Severity: HIGH
Endpoint: POST /api/users/search
...

Retrieving Scan Issues¶

List all security findings from a completed scan.

escape-cli scans issues <scan-id>

Aliases: issues, results, res, result, iss

Example:

escape-cli scans issues 00000000-0000-0000-0000-000000000001

Example Output:

ID                                      SEVERITY    TYPE    CATEGORY                  NAME                                         IGNORED    URL
00000000-0000-0000-0000-000000000001    HIGH        API     INJECTION                 SQL Injection                                false      https://app.escape.tech/scan/xxx/issues/xxx/overview/
00000000-0000-0000-0000-000000000002    MEDIUM      API     PROTOCOL                  Insecure Security Policy header              false      https://app.escape.tech/scan/xxx/issues/xxx/overview/
00000000-0000-0000-0000-000000000003    LOW         API     INFORMATION_DISCLOSURE    Debug mode enabled                           false      https://app.escape.tech/scan/xxx/issues/xxx/overview/

Filtering Issues¶

Get specific issue details:

# Get issues in JSON format for parsing
escape-cli scans issues <scan-id> -o json

# Filter high severity issues
escape-cli scans issues <scan-id> -o json | jq '.[] | select(.severity=="HIGH")'

# Count issues by severity
escape-cli scans issues <scan-id> -o json | jq 'group_by(.severity) | map({severity: .[0].severity, count: length})'

Cancelling a Scan¶

Stop a running scan before it completes.

escape-cli scans cancel <scan-id>

Example:

escape-cli scans cancel 00000000-0000-0000-0000-000000000001

For AI Pentesting scans, cancellation immediately stops the currently running pentesting agent. Use this when you need to interrupt an active agent run right away, not just prevent later work from being scheduled.

If you need to stop all current and future AI Pentesting scans for an organization, enable the AI Pentesting scan kill switch from Organization Settings. That setting cancels running AI Pentesting scans and blocks new AI Pentesting scans from starting until it is disabled again.

Ignoring a Scan¶

Mark a scan as ignored, excluding it from reports and metrics.

escape-cli scans ignore <scan-id>

Example:

escape-cli scans ignore 00000000-0000-0000-0000-000000000001

Use cases for ignoring scans:

• Test runs during configuration
• Failed scans due to temporary issues
• Scans with incorrect settings
• Historical scans that should be excluded from metrics

Complete Scan Workflow¶

Here's a typical end-to-end scan workflow:

#!/bin/bash
set -e

# Configuration
PROFILE_ID="00000000-0000-0000-0000-000000000001"

# Start the scan and capture ID
echo "Starting security scan..."
SCAN_ID=$(escape-cli scans start "${PROFILE_ID}" -o json | jq -r '.id')
echo "Scan ID: ${SCAN_ID}"

# Watch the scan progress
echo "Monitoring scan progress..."
escape-cli scans watch "${SCAN_ID}"

# Retrieve results
echo "Fetching scan results..."
escape-cli scans issues "${SCAN_ID}" -o json > scan-results.json

# Check for high severity issues
HIGH_ISSUES=$(jq '[.[] | select(.severity=="HIGH" or .severity=="CRITICAL")] | length' scan-results.json)

if [ "$HIGH_ISSUES" -gt 0 ]; then
    echo "ERROR: Found $HIGH_ISSUES high/critical severity issues"
    jq '.[] | select(.severity=="HIGH" or .severity=="CRITICAL") | {severity, name, category}' scan-results.json
    exit 1
else
    echo "SUCCESS: No high/critical severity issues found"
    exit 0
fi

CI/CD Integration¶

GitHub Actions Example¶

name: Security Scan

on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Install Escape CLI
        run: |
          curl -sf https://raw.githubusercontent.com/Escape-Technologies/cli/refs/heads/main/scripts/install.sh | sudo bash

      - name: Run Security Scan
        env:
          ESCAPE_API_KEY: ${{ secrets.ESCAPE_API_KEY }}
        run: |
          SCAN_ID=$(escape-cli scans start ${{ vars.PROFILE_ID }} \
            --commit-hash ${{ github.sha }} \
            --commit-branch ${{ github.ref_name }} \
            --commit-author ${{ github.actor }} \
            --commit-link ${{ github.server_url }}/${{ github.repository }}/commit/${{ github.sha }} \
            -o json | jq -r '.id')

          escape-cli scans watch $SCAN_ID
          escape-cli scans issues $SCAN_ID -o json > results.json

      - name: Upload Results
        uses: actions/upload-artifact@v3
        with:
          name: security-scan-results
          path: results.json

See CI/CD Integration for more examples.

Scan Scheduling¶

While the CLI allows on-demand scan execution, you can configure recurring scans through the Escape web interface:

1. Navigate to your profile settings
2. Configure the scan schedule (cron expression)
3. Set scan parameters and notification preferences

Scheduled scans run automatically without CLI intervention.

Best Practices¶

Scan Frequency¶

• Production: Weekly or bi-weekly scheduled scans
• Staging: After each deployment
• Development: On-demand or per pull request
• Critical APIs: Daily scans for high-value targets

Resource Management¶

• Cancel stale or stuck scans to free resources
• Monitor scan duration and optimize configurations
• Stagger scheduled scans to avoid resource contention

Result Management¶

• Archive scan results for compliance and auditing
• Track security trends over time
• Automate issue creation in bug tracking systems

Error Handling¶

Always check scan status and handle failures:

if escape-cli scans start <profile-id>; then
    echo "Scan started successfully"
else
    echo "Failed to start scan"
    exit 1
fi

Troubleshooting¶

Scan Stuck in QUEUED¶

If a scan remains queued:

• Check location health: escape-cli locations list
• Verify the location is enabled and running
• Cancel and restart the scan if necessary

Scan Fails Immediately¶

Common causes:

• Target application is unreachable
• Authentication credentials are invalid
• Network connectivity issues
• Configuration errors in the profile

Check scan details for error messages:

escape-cli scans get <scan-id> -o json | jq '.error'

No Issues Returned¶

If a scan completes but shows no issues:

• Verify the scan completed successfully
• Check the scan didn't run in read-only mode accidentally
• Review scan configuration for scope limitations

Performance Issues¶

If scans take too long:

• Review scan configuration for unnecessary depth
• Enable read-only mode for faster passive scanning
• Consider splitting into multiple focused profiles

Next Steps¶

• Issues Management - Learn to manage and triage security findings
• Locations Management - Configure scan execution locations
• Scan Problems - Troubleshoot scan failures
• Practical Recipes - Complete scan automation examples
• CI/CD Integration - Integrate scans into your pipeline