Scan Events¶

Events provide detailed logs of scan execution activities, helping you monitor test progress, troubleshoot issues, and understand scan behavior.

Overview¶

Scan events track:

Test execution details
Discovery and reconnaissance activities
Security test results
Errors and warnings
Performance metrics
Progress updates

Events are essential for:

Troubleshooting: Debug failed or problematic scans
Monitoring: Track scan progress and performance
Analysis: Understand what tests were executed
Optimization: Identify bottlenecks and improve configurations

Listing Events¶

View scan events with flexible filtering.

escape-cli events list [flags]

Aliases: ls, event

Filtering Options¶

Flag	Short	Description
`--search`	`-s`	Free-text search across events
`--scan-id`		Filter by scan ID
`--asset-id`	`-a`	Filter by asset ID
`--issue-id`	`-i`	Filter by issue ID
`--stage`		Filter by execution stage
`--levels`	`-l`	Filter by event level
`--has-attachments`		Show only events with attachments

Basic Examples¶

# List all recent events
escape-cli events list

# List events for a specific scan
escape-cli events list --scan-id <scan-id>

# List events for an asset
escape-cli events list --asset-id <asset-id>

# List events related to an issue
escape-cli events list --issue-id <issue-id>

Event Levels¶

Events are categorized by severity:

Level	Description	Use Case
`ERROR`	Scan errors and failures	Critical issues preventing scan completion
`WARN`	Warnings and potential issues	Problems that don't stop the scan but need attention
`INFO`	General informational messages	Normal scan progress and activities
`DEBUG`	Detailed debugging information	Deep dive into scan behavior

Filtering by Level¶

# Show only errors
escape-cli events list --levels ERROR

# Show errors and warnings
escape-cli events list --levels ERROR,WARN

# Show all logs including debug
escape-cli events list --levels ERROR,WARN,INFO,DEBUG

Event Stages¶

Events are organized by execution phase:

Stage	Description
`DISCOVERY`	API endpoint discovery and reconnaissance
`EXECUTION`	Active security testing
`ANALYSIS`	Results processing and vulnerability analysis
`REPORTING`	Report generation and finalization

Filtering by Stage¶

# View discovery phase events
escape-cli events list --stage DISCOVERY

# View execution phase (active testing)
escape-cli events list --stage EXECUTION

# View analysis phase
escape-cli events list --stage ANALYSIS

Viewing Event Details¶

Get comprehensive information about a specific event.

escape-cli events get <event-id>

Aliases: g, show, describe

Example:

escape-cli events get 00000000-0000-0000-0000-000000000001

JSON Output¶

escape-cli events get <event-id> -o json

Example Output:

{
  "id": "00000000-0000-0000-0000-000000000001",
  "createdAt": "2025-10-15T10:30:00Z",
  "level": "INFO",
  "stage": "EXECUTION",
  "title": "Testing authentication endpoint",
  "message": "Executing authentication bypass tests on POST /api/login",
  "scanId": "00000000-0000-0000-0000-000000000002",
  "assetId": "00000000-0000-0000-0000-000000000003",
  "attachments": []
}

Output Format¶

Table Format (Default)¶

escape-cli events list --scan-id <scan-id>

Example Output:

ID                                      CREATED AT                LEVEL    STAGE        TITLE
00000000-0000-0000-0000-000000000001    2025-10-15T10:30:00Z     INFO     DISCOVERY    Discovered 45 API endpoints
00000000-0000-0000-0000-000000000002    2025-10-15T10:31:00Z     INFO     EXECUTION    Starting authentication tests
00000000-0000-0000-0000-000000000003    2025-10-15T10:32:00Z     WARN     EXECUTION    Rate limit detected, throttling requests
00000000-0000-0000-0000-000000000004    2025-10-15T10:33:00Z     ERROR    EXECUTION    Connection timeout on endpoint /api/data

Searching Events¶

Free-text search across all event fields.

# Search for timeout issues
escape-cli events list --search "timeout"

# Search for authentication-related events
escape-cli events list --search "auth"

# Search for specific endpoints
escape-cli events list --search "/api/users"

# Search for error patterns
escape-cli events list --search "failed"

Events with Attachments¶

Some events include attachments like request/response data or screenshots.

# Show only events with attachments
escape-cli events list --has-attachments

# View events with specific attachment types
escape-cli events list --has-attachments --search "screenshot"

Common Use Cases¶

Troubleshooting Failed Scans¶

#!/bin/bash
# Investigate why a scan failed

SCAN_ID="<your-scan-id>"

# Get all error events
echo "=== Error Events ==="
escape-cli events list --scan-id "$SCAN_ID" --levels ERROR

# Get warnings that might indicate issues
echo -e "\n=== Warning Events ==="
escape-cli events list --scan-id "$SCAN_ID" --levels WARN

# Export for detailed analysis
escape-cli events list --scan-id "$SCAN_ID" -o json > scan-events.json

Monitoring Scan Progress¶

#!/bin/bash
# Watch scan progress in real-time

SCAN_ID="<your-scan-id>"

while true; do
  clear
  echo "=== Scan Progress ==="
  escape-cli scans get "$SCAN_ID"

  echo -e "\n=== Recent Events ==="
  escape-cli events list --scan-id "$SCAN_ID" | tail -20

  sleep 5
done

Analyzing Discovery Phase¶

# See what endpoints were discovered
escape-cli events list \
  --scan-id <scan-id> \
  --stage DISCOVERY \
  --levels INFO

# Export discovery details
escape-cli events list \
  --scan-id <scan-id> \
  --stage DISCOVERY \
  -o json | \
  jq '.[] | select(.title | contains("Discovered"))'

Finding Performance Issues¶

# Find slow requests
escape-cli events list \
  --scan-id <scan-id> \
  --search "slow" \
  --levels WARN

# Find timeout events
escape-cli events list \
  --scan-id <scan-id> \
  --search "timeout" \
  --levels ERROR,WARN

Debugging Authentication Issues¶

# Find authentication-related events
escape-cli events list \
  --scan-id <scan-id> \
  --search "auth"

# Look for 401/403 errors
escape-cli events list \
  --scan-id <scan-id> \
  --search "401" \
  --levels ERROR,WARN

Event Analysis¶

Count Events by Level¶

escape-cli events list --scan-id <scan-id> -o json | \
  jq 'group_by(.level) | map({level: .[0].level, count: length})'

Example Output:

[
  {"level": "INFO", "count": 523},
  {"level": "WARN", "count": 15},
  {"level": "ERROR", "count": 3},
  {"level": "DEBUG", "count": 1247}
]

Count Events by Stage¶

escape-cli events list --scan-id <scan-id> -o json | \
  jq 'group_by(.stage) | map({stage: .[0].stage, count: length})'

Example Output:

[
  {"stage": "DISCOVERY", "count": 45},
  {"stage": "EXECUTION", "count": 1520},
  {"stage": "ANALYSIS", "count": 180},
  {"stage": "REPORTING", "count": 43}
]

Event Timeline¶

# Get events ordered by time
escape-cli events list --scan-id <scan-id> -o json | \
  jq -r '.[] | "\(.createdAt) [\(.level)] \(.stage) - \(.title)"' | \
  sort

Find Most Common Issues¶

# Group events by title to find patterns
escape-cli events list --scan-id <scan-id> -o json | \
  jq 'group_by(.title) | map({issue: .[0].title, occurrences: length}) | sort_by(.occurrences) | reverse | .[0:10]'

Exporting Events¶

Export Scan Log¶

#!/bin/bash
# Export complete scan log with all events

SCAN_ID="<your-scan-id>"
OUTPUT_FILE="scan-log-${SCAN_ID}.json"

escape-cli events list --scan-id "$SCAN_ID" -o json > "$OUTPUT_FILE"

echo "Exported $(jq 'length' "$OUTPUT_FILE") events to $OUTPUT_FILE"

# Generate summary
jq '{
  total_events: length,
  by_level: (group_by(.level) | map({level: .[0].level, count: length})),
  by_stage: (group_by(.stage) | map({stage: .[0].stage, count: length})),
  errors: [.[] | select(.level == "ERROR") | {time: .createdAt, message: .title}]
}' "$OUTPUT_FILE" > "scan-summary-${SCAN_ID}.json"

echo "Summary saved to scan-summary-${SCAN_ID}.json"

Export Error Report¶

#!/bin/bash
# Generate error report for failed scan

SCAN_ID="<your-scan-id>"

escape-cli events list \
  --scan-id "$SCAN_ID" \
  --levels ERROR \
  -o json | \
  jq -r '.[] | "[\(.createdAt)] \(.stage): \(.title)\n\(.message)\n"' \
  > "error-report-${SCAN_ID}.txt"

echo "Error report saved"

Comparison and Diff¶

Compare Scans¶

#!/bin/bash
# Compare events between two scans

SCAN1="<scan-id-1>"
SCAN2="<scan-id-2>"

echo "=== Scan 1 Summary ==="
escape-cli events list --scan-id "$SCAN1" -o json | \
  jq '{errors: [.[] | select(.level == "ERROR")] | length, warnings: [.[] | select(.level == "WARN")] | length}'

echo -e "\n=== Scan 2 Summary ==="
escape-cli events list --scan-id "$SCAN2" -o json | \
  jq '{errors: [.[] | select(.level == "ERROR")] | length, warnings: [.[] | select(.level == "WARN")] | length}'

Integration with Monitoring¶

Send Events to External System¶

#!/bin/bash
# Stream error events to monitoring system

SCAN_ID="<your-scan-id>"

escape-cli events list \
  --scan-id "$SCAN_ID" \
  --levels ERROR \
  -o json | \
  jq -c '.[]' | \
  while read -r event; do
    # Send to monitoring endpoint
    curl -X POST https://monitoring.example.com/api/events \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $MONITORING_TOKEN" \
      -d "$event"
  done

Alert on Critical Events¶

#!/bin/bash
# Alert on critical errors during scan

SCAN_ID="<your-scan-id>"

ERROR_COUNT=$(escape-cli events list \
  --scan-id "$SCAN_ID" \
  --levels ERROR \
  -o json | jq 'length')

if [ "$ERROR_COUNT" -gt 10 ]; then
  # Send alert
  curl -X POST "$SLACK_WEBHOOK_URL" \
    -H "Content-Type: application/json" \
    -d "{\"text\": \":warning: Scan $SCAN_ID has $ERROR_COUNT errors\"}"
fi

Best Practices¶

Event Monitoring¶

Review error and warning events for every scan
Set up alerts for critical errors
Track event patterns over time
Archive event logs for historical analysis

Troubleshooting¶

Start with ERROR level events
Check WARN events for potential issues
Use stage filtering to isolate problems
Search for specific error messages or patterns

Performance Analysis¶

Monitor event frequency and timing
Identify slow stages using timestamps
Track resource usage patterns
Optimize based on event data

Documentation¶

Document recurring error patterns
Create runbooks for common issues
Share insights with team
Update scan configurations based on findings

Troubleshooting¶

No Events Returned¶

If events list is empty:

Verify the scan ID is correct
Check if scan has started/generated events
Ensure you have permission to view events
Try without filters to see all events

Too Many Events¶

If overwhelmed with events:

Use level filtering to focus on errors/warnings
Filter by specific stages
Use search to find relevant events
Export to JSON for offline analysis

Missing Event Details¶

If events lack information:

Some fields may be null for certain event types
Use JSON output to see all available fields
Check if attachments provide additional context

Next Steps¶

Audit Logs - Organization activity logs
Scan Problems - Troubleshoot scan failures
Scans Management - Run and monitor scans
Issues Management - Review security findings
Practical Recipes - Complete workflow examples