Scan Problems¶

The problems command helps you identify and troubleshoot applications experiencing scan failures or configuration issues across your entire organization.

Examples using date -d require GNU date. On macOS, use BSD date's -v option instead; for example, date -u -v-24H +%Y-%m-%dT%H:%M:%SZ gives the timestamp 24 hours ago.

Overview¶

Problems represent issues that prevent successful scan completion, such as:

Scan failures due to technical issues
Configuration errors in profiles
Authentication or authorization failures
Network connectivity problems
Timeout issues
Resource constraints

The problems view provides a quick way to identify which applications need attention.

Listing Problems¶

Display all applications that have at least one scan problem.

escape-cli problems [flags]

Aliases: problem

Basic Usage¶

# List all applications with problems
escape-cli problems

# Show detailed problem information
escape-cli problems --all
escape-cli problems -a

Filtering Options¶

Flag	Short	Description
`--all`	`-a`	Show detailed problem information
`--asset-ids`		Filter by specific asset IDs
`--domains`		Filter by domain names
`--issue-ids`		Filter by issue IDs
`--tag-ids`		Filter by tag IDs
`--search`	`-s`	Free-text search
`--initiators`		Filter by scan initiators
`--kinds`		Filter by scan kinds
`--risks`		Filter by risk types

Filtering Examples¶

# Problems for specific assets
escape-cli problems --asset-ids "asset-id-1,asset-id-2"

# Problems in production domain
escape-cli problems --domains "api.production.example.com"

# Search for specific problems
escape-cli problems --search "timeout"

# Filter by scan type
escape-cli problems --kinds BLST_REST,BLST_GRAPHQL

# Filter by initiator
escape-cli problems --initiators CI,SCHEDULED

Output Formats¶

Basic View (Default)¶

Shows application overview with problem count.

escape-cli problems

Example Output:

ID                                      NAME                    SCAN STATUS    PROBLEMS
11111111-1111-1111-1111-111111111111    Production API         FAILED         2
22222222-2222-2222-2222-222222222222    Staging API            FINISHED          1
33333333-3333-3333-3333-333333333333    Internal Service       FAILED         3

Detailed View¶

Shows individual problem details for each application.

escape-cli problems --all

Example Output:

ID                                      NAME                    SCAN STATUS    PROBLEM CODE    SEVERITY    MESSAGE
11111111-1111-1111-1111-111111111111    Production API         FAILED         AUTH_FAILURE     ERROR        Authentication failed: invalid credentials
11111111-1111-1111-1111-111111111111    Production API         FAILED         TIMEOUT         ERROR      Scan exceeded maximum duration limit
22222222-2222-2222-2222-222222222222    Staging API            FINISHED       CONFIGURATION_IMPROVEMENT    INFO         Profile configuration is invalid
33333333-3333-3333-3333-333333333333    Internal Service       FAILED         UNREACHABLE_ASSET   ERROR        Unable to reach target: connection refused

JSON Output¶

JSON uses uppercase field names. The basic view has AppID, AppName, ScanStatus, and ProblemCount. With --all, each problem has AppID (the profile ID), AppName, ScanStatus, Code, Severity, and Message.

For programmatic processing:

escape-cli problems -o json
escape-cli problems --all -o json

Problem Codes¶

Problem severities are ERROR, WARNING, and INFO.

Problem Code	Description
`AUTH_FAILURE`	Authentication failure.
`BLOCKED_BY_WAF`	A web application firewall blocks scanning.
`CAPTCHA_HIT`	A CAPTCHA was encountered.
`CONFIGURATION_IMPROVEMENT`	Configuration could be improved.
`HIGH_NUMBER_OF_ERROR_ENDPOINTS`	Many endpoints return errors.
`INTEGRATION_ERROR`	Integration error.
`NO_AUTHENTICATION_CONFIGURED`	The scan only tests the public user.
`NO_SCHEMA_FOUND`	No schema was found for the asset.
`PL_FAILURE`	Private Location failure.
`RATE_LIMIT_EXCEEDED`	A rate limit was exceeded.
`SCHEMA_IMPROVEMENT`	Schema could be improved.
`TIMEOUT`	Scan timeout.
`UNEXPECTED_ERROR`	Unexpected scan error.
`UNREACHABLE_ASSET`	The asset couldn't be reached.

Common Use Cases¶

Quick Health Check¶

#!/bin/bash
# Check organization health

PROBLEM_COUNT=$(escape-cli problems -o json | jq 'length')

if [ "$PROBLEM_COUNT" -gt 0 ]; then
  echo "⚠️  WARNING: $PROBLEM_COUNT applications have scan problems"
  escape-cli problems
  exit 1
else
  echo "✓ All scans running successfully"
  exit 0
fi

Daily Problem Report¶

#!/bin/bash
# Generate daily problem report

REPORT_FILE="problems-report-$(date +%Y-%m-%d).json"

escape-cli problems --all -o json > "$REPORT_FILE"

# Summary
TOTAL_APPS=$(jq '[.[] | .AppID] | unique | length' "$REPORT_FILE")
TOTAL_PROBLEMS=$(jq 'length' "$REPORT_FILE")

cat > "problems-summary-$(date +%Y-%m-%d).txt" <<EOF
Daily Problems Summary
======================
Date: $(date)
Applications with Problems: $TOTAL_APPS
Total Problems: $TOTAL_PROBLEMS

Top Problem Types:
$(jq -r 'group_by(.Code) | map({type: .[0].Code, count: length}) | sort_by(.count) | reverse | .[] | "  \(.type): \(.count)"' "$REPORT_FILE")

Report file: $REPORT_FILE
EOF

cat "problems-summary-$(date +%Y-%m-%d).txt"

Alert on Scan Errors¶

#!/bin/bash
# Alert on scan errors

HIGH_SEVERITY=$(escape-cli problems --all -o json | \
  jq '[.[] | select(.Severity == "ERROR")] | length')

if [ "$HIGH_SEVERITY" -gt 0 ]; then
  MESSAGE=$(escape-cli problems --all -o json | \
    jq -r '[.[] | select(.Severity == "ERROR")] |
           .[] | "• \(.AppName): \(.Message)"' | head -5)

  # Send to Slack
  curl -X POST "$SLACK_WEBHOOK_URL" \
    -H "Content-Type: application/json" \
    -d "{
      \"text\": \":rotating_light: $HIGH_SEVERITY Scan Errors\",
      \"attachments\": [{
        \"text\": \"$MESSAGE\",
        \"color\": \"danger\"
      }]
    }"
fi

Problem Trend Analysis¶

#!/bin/bash
# Track problem trends over time

TODAY=$(date +%Y-%m-%d)
PROBLEMS_TODAY=$(escape-cli problems --all -o json)

echo "$PROBLEMS_TODAY" > "problems-${TODAY}.json"

# Compare with yesterday
if [ -f "problems-$(date -d yesterday +%Y-%m-%d).json" ]; then
  TODAY_COUNT=$(echo "$PROBLEMS_TODAY" | jq 'length')
  YESTERDAY_COUNT=$(jq 'length' "problems-$(date -d yesterday +%Y-%m-%d).json")

  DIFF=$((TODAY_COUNT - YESTERDAY_COUNT))

  if [ $DIFF -gt 0 ]; then
    echo "📈 Problems increased by $DIFF"
  elif [ $DIFF -lt 0 ]; then
    echo "📉 Problems decreased by ${DIFF#-}"
  else
    echo "➡️  No change in problem count"
  fi
fi

Problem Analysis¶

Group by Problem Type¶

escape-cli problems --all -o json | \
  jq 'group_by(.Code) | map({
    type: .[0].Code,
    count: length,
    applications: [.[] | .AppName] | unique
  })'

Example Output:

[
  {
    "type": "AUTH_FAILURE",
    "count": 5,
    "applications": ["API Gateway", "User Service", "Payment API"]
  },
  {
    "type": "TIMEOUT",
    "count": 3,
    "applications": ["Legacy API", "Data Service"]
  }
]

Identify Most Problematic Applications¶

escape-cli problems --all -o json | \
  jq 'group_by(.AppID) | map({
    id: .[0].AppID,
    name: .[0].AppName,
    problem_count: length,
    problems: [.[] | {code: .Code, message: .Message}]
  }) | sort_by(.problem_count) | reverse'

Find Recurring Problems¶

#!/bin/bash
# Identify problems that occur repeatedly

# Collect problems over a week
for i in {1..7}; do
  DATE=$(date -d "$i days ago" +%Y-%m-%d)
  if [ -f "problems-${DATE}.json" ]; then
    jq -r '.[] | "\(.AppID):\(.Code)"' "problems-${DATE}.json"
  fi
done | sort | uniq -c | sort -rn | awk '$1 >= 5 {print "Recurring: " $2 " (" $1 " occurrences)"}'

Troubleshooting by Problem Type¶

Authentication Failures¶

# Find all AUTH_FAILURE problems
escape-cli problems --all -o json | \
  jq '.[] | select(.Code == "AUTH_FAILURE") | {
    application: .AppName,
    message: .Message,
    profile_id: .AppID
  }'

Common Solutions:

Verify credentials are current
Check if tokens/API keys have expired
Review authentication configuration in profile
Test credentials manually

Network Errors¶

# Find all UNREACHABLE_ASSET problems
escape-cli problems --all -o json | \
  jq '.[] | select(.Code == "UNREACHABLE_ASSET")'

Common Solutions:

Verify target is reachable
Check firewall rules
Ensure private location has network access
Test DNS resolution

Timeout Issues¶

# Find all TIMEOUT problems
escape-cli problems --all -o json | \
  jq '.[] | select(.Code == "TIMEOUT")'

Common Solutions:

Increase scan timeout in profile configuration
Enable read-only mode for faster scanning
Reduce scan scope or depth
Optimize target application performance

Configuration Errors¶

# Find all CONFIGURATION_IMPROVEMENT problems
escape-cli problems --all -o json | \
  jq '.[] | select(.Code == "CONFIGURATION_IMPROVEMENT")'

Common Solutions:

Review profile configuration
Validate schema/specification files
Check required fields are populated
Verify location is properly configured

Integration Examples¶

Create Tickets for Problems¶

#!/bin/bash
# Create Jira tickets for unresolved problems

escape-cli problems --all -o json | \
  jq -c '.[] | select(.Severity == "ERROR")' | \
  while read -r problem; do
    APP_NAME=$(echo "$problem" | jq -r '.AppName')
    PROBLEM_MSG=$(echo "$problem" | jq -r '.Message')

    # Create Jira ticket
    curl -X POST "https://jira.example.com/rest/api/2/issue" \
      -H "Content-Type: application/json" \
      -u "$JIRA_USER:$JIRA_TOKEN" \
      -d "{
        \"fields\": {
          \"project\": {\"key\": \"OPS\"},
          \"summary\": \"[Escape] Scan Problem: $APP_NAME\",
          \"description\": \"$PROBLEM_MSG\",
          \"issuetype\": {\"name\": \"Bug\"},
          \"priority\": {\"name\": \"High\"}
        }
      }"
  done

Dashboard Metrics¶

#!/bin/bash
# Export metrics to monitoring dashboard

METRICS=$(escape-cli problems --all -o json | jq '{
  total_problems: length,
  applications_affected: [.[] | .AppID] | unique | length,
  by_severity: (group_by(.Severity) | map({severity: .[0].Severity, count: length})),
  by_type: (group_by(.Code) | map({type: .[0].Code, count: length}))
}')

# Send to monitoring system
curl -X POST "https://metrics.example.com/api/escape" \
  -H "Content-Type: application/json" \
  -d "$METRICS"

Automated Remediation¶

Auto-Retry Failed Scans¶

#!/bin/bash
# Automatically retry failed scans with transient errors

escape-cli problems --all -o json | \
  jq -r '.[] | select(.Code == "UNREACHABLE_ASSET" or .Code == "TIMEOUT") |
         "\(.AppID)"' | \
  sort -u | \
  while read -r profile_id; do
    echo "Retrying scan for profile $profile_id"
    escape-cli scans start "$profile_id"
  done

Update Problematic Configurations¶

#!/bin/bash
# max_duration is the maximum scan duration in minutes

escape-cli problems --all -o json | \
  jq -r '.[] | select(.Code == "TIMEOUT") | .AppID' | \
  sort -u | \
  while read -r profile_id; do
    echo "Note: Profile $profile_id has timeout issues"
    echo "Consider starting a scan with: escape-cli scans start $profile_id --override '{\"max_duration\": 240}'"
  done

Best Practices¶

Regular Monitoring¶

Check problems dashboard daily
Set up alerts for new problems
Track problem trends over time
Review and resolve systematically

Problem Resolution¶

Triage by severity - Address high-severity problems first
Identify patterns - Look for common root causes
Document solutions - Create runbooks for recurring issues
Verify fixes - Re-run scans after resolving problems

Preventive Measures¶

Validate configurations before deployment
Test credentials before scheduled scans
Monitor network connectivity
Set appropriate timeouts and resource limits

Communication¶

Share problem reports with relevant teams
Update stakeholders on resolution progress
Document lessons learned
Improve processes to prevent recurrence

Troubleshooting¶

No Problems Shown¶

If no problems are returned but scans are failing:

Check if you're filtering too narrowly
Verify you have permission to view all assets
Try --all flag for detailed view
Check recent scan history directly

Stale Problems¶

If problems persist after fixes:

Run a new scan to update status
Verify the fix was applied correctly
Check if the underlying issue truly resolved
Review scan logs for current status

Too Many Problems¶

If overwhelmed with problems:

Filter by severity to prioritize
Use --asset-ids to focus on specific applications
Export to JSON and analyze patterns
Address root causes rather than symptoms

Next Steps¶

Scans Management - Run and monitor scans
Events Management - Debug scan execution
Audit Logs - Track system activity
Practical Recipes - Complete workflow examples