# 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. ```bash escape-cli events list [flags] ``` **Aliases:** `ls`, `event` ### Filtering Options | Flag | Short | Description | | --- | --- | --- | | `--search` | `-s` | Free-text search across events | | `--profile-id` | `-p` | Filter by profile ID | | `--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 | | `--attachments` | `-t` | Filter by attachment type | ### Basic Examples ```bash # List all recent events escape-cli events list # List events for a specific profile escape-cli events list --profile-id # List events for a specific scan escape-cli events list --scan-id # List events for an asset escape-cli events list --asset-id # List events related to an issue escape-cli events list --issue-id ``` ## Event Levels Events are categorized by severity: | Level | Description | Use Case | | --- | --- | --- | | `ERROR` | Scan errors and failures | Critical issues preventing scan completion | | `WARNING` | 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 ```bash # Show only errors escape-cli events list --levels ERROR # Show errors and warnings escape-cli events list --levels ERROR,WARNING # Show all logs including debug escape-cli events list --levels ERROR,WARNING,INFO,DEBUG ``` ## Event Stages Events are organized by execution phase: | Stage | Description | | --- | --- | | `CONFIGURATION` | Scan setup, validation, and configuration | | `EXECUTION` | Active security testing | | `AGENT_REASONING` | AI Pentesting agent reasoning steps | | `AGENT_ACTION` | AI Pentesting agent actions | ### Filtering by Stage ```bash # View configuration phase events escape-cli events list --stage CONFIGURATION # View execution phase (active testing) escape-cli events list --stage EXECUTION # View AI Pentesting agent reasoning events escape-cli events list --stage AGENT_REASONING ``` ## Viewing Event Details Get comprehensive information about a specific event. ```bash escape-cli events get ``` **Alias:** `g` **Example:** ```bash escape-cli events get 11111111-1111-1111-1111-111111111111 ``` ### JSON Output `events get` includes `description`. `events list` returns summarized events without that field. ```bash escape-cli events get -o json ``` **Example Output:** ```json { "id": "11111111-1111-1111-1111-111111111111", "createdAt": "2025-10-15T10:30:00Z", "level": "INFO", "stage": "EXECUTION", "title": "Testing authentication endpoint", "description": "Executing authentication bypass tests on POST /api/login", "scanId": "22222222-2222-2222-2222-222222222222", "issuesCount": 0, "attachments": [] } ``` ## Output Format ### Table Format (Default) ```bash escape-cli events list --scan-id ``` **Example Output:** ```text ID CREATED AT LEVEL STAGE TITLE 11111111-1111-1111-1111-111111111111 2025-10-15T10:30:00Z INFO CONFIGURATION Discovered 45 API endpoints 22222222-2222-2222-2222-222222222222 2025-10-15T10:31:00Z INFO EXECUTION Starting authentication tests 33333333-3333-3333-3333-333333333333 2025-10-15T10:32:00Z WARNING EXECUTION Rate limit detected, throttling requests 44444444-4444-4444-4444-444444444444 2025-10-15T10:33:00Z ERROR EXECUTION Connection timeout on endpoint /api/data ``` ## Searching Events Free-text search across all event fields. ```bash # 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. ```bash # Show only events with attachments escape-cli events list --has-attachments # Filter by attachment type escape-cli events list --attachments ``` ## Common Use Cases ### Troubleshooting Failed Scans ```bash #!/bin/bash # Investigate why a scan failed 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 WARNING # Export for detailed analysis escape-cli events list --scan-id "$SCAN_ID" -o json > scan-events.json ``` ### Monitoring Scan Progress ```bash #!/bin/bash # Watch scan progress in real-time 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 the Configuration Phase ```bash # See what endpoints were discovered escape-cli events list \ --scan-id \ --stage CONFIGURATION \ --levels INFO # Export configuration details escape-cli events list \ --scan-id \ --stage CONFIGURATION \ -o json | \ jq '.[] | select(.title | contains("Discovered"))' ``` ### Finding Performance Issues ```bash # Find slow requests escape-cli events list \ --scan-id \ --search "slow" \ --levels WARNING # Find timeout events escape-cli events list \ --scan-id \ --search "timeout" \ --levels ERROR,WARNING ``` ### Debugging Authentication Issues ```bash # Find authentication-related events escape-cli events list \ --scan-id \ --search "auth" # Look for 401/403 errors escape-cli events list \ --scan-id \ --search "401" \ --levels ERROR,WARNING ``` ## Event Analysis ### Count Events by Level ```bash escape-cli events list --scan-id -o json | \ jq 'group_by(.level) | map({level: .[0].level, count: length})' ``` **Example Output:** ```json [ {"level": "INFO", "count": 523}, {"level": "WARNING", "count": 15}, {"level": "ERROR", "count": 3}, {"level": "DEBUG", "count": 1247} ] ``` ### Count Events by Stage ```bash escape-cli events list --scan-id -o json | \ jq 'group_by(.stage) | map({stage: .[0].stage, count: length})' ``` **Example Output:** ```json [ {"stage": "CONFIGURATION", "count": 45}, {"stage": "EXECUTION", "count": 1520}, {"stage": "AGENT_REASONING", "count": 180}, {"stage": "AGENT_ACTION", "count": 43} ] ``` ### Event Timeline ```bash # Get events ordered by time escape-cli events list --scan-id -o json | \ jq -r '.[] | "\(.createdAt) [\(.level)] \(.stage) - \(.title)"' | \ sort ``` ### Find Most Common Issues ```bash # Group events by title to find patterns escape-cli events list --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 ```bash #!/bin/bash # Export complete scan log with all events 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 ```bash #!/bin/bash # Generate error report for failed scan SCAN_ID="" escape-cli events list \ --scan-id "$SCAN_ID" \ --levels ERROR \ -o json | \ jq -r '.[] | "[\(.createdAt)] \(.stage): \(.title)"' \ > "error-report-${SCAN_ID}.txt" echo "Error report saved" ``` ## Comparison and Diff ### Compare Scans ```bash #!/bin/bash # Compare events between two scans SCAN1="" SCAN2="" echo "=== Scan 1 Summary ===" escape-cli events list --scan-id "$SCAN1" -o json | \ jq '{errors: [.[] | select(.level == "ERROR")] | length, warnings: [.[] | select(.level == "WARNING")] | 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 == "WARNING")] | length}' ``` ## Integration with Monitoring ### Send Events to External System ```bash #!/bin/bash # Stream error events to monitoring system 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 ```bash #!/bin/bash # Alert on critical errors during scan 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 WARNING 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