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

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