Scan Problems¶

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

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
00000000-0000-0000-0000-000000000001    Production API         FAILED         2
00000000-0000-0000-0000-000000000002    Staging API            ERROR          1
00000000-0000-0000-0000-000000000003    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
00000000-0000-0000-0000-000000000001    Production API         FAILED         AUTH_FAILED     HIGH        Authentication failed: invalid credentials
00000000-0000-0000-0000-000000000001    Production API         FAILED         TIMEOUT         MEDIUM      Scan exceeded maximum duration limit
00000000-0000-0000-0000-000000000002    Staging API            ERROR          CONFIG_ERROR    LOW         Profile configuration is invalid
00000000-0000-0000-0000-000000000003    Internal Service       FAILED         NETWORK_ERROR   HIGH        Unable to reach target: connection refused

JSON Output¶

For programmatic processing:

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

Problem Types¶

Common problem categories:

Problem Type	Description	Typical Causes
`SCAN_FAILED`	Scan could not complete	Technical errors, crashes, unexpected conditions
`CONFIG_ERROR`	Profile configuration issues	Invalid settings, missing required fields
`AUTH_FAILED`	Authentication problems	Invalid credentials, expired tokens
`AUTHZ_FAILED`	Authorization issues	Insufficient permissions, access denied
`NETWORK_ERROR`	Connectivity problems	Unreachable hosts, DNS failures, firewalls
`TIMEOUT`	Scan duration exceeded	Slow responses, large attack surface
`RESOURCE_ERROR`	Resource constraints	Memory limits, quota exceeded
`TARGET_ERROR`	Target application issues	Application down, returning errors

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 '[.[] | .id] | 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(.problemCode) | map({type: .[0].problemCode, 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 Critical Problems¶

#!/bin/bash
# Alert on high-severity problems

HIGH_SEVERITY=$(escape-cli problems --all -o json | \
  jq '[.[] | select(.severity == "HIGH" or .severity == "CRITICAL")] | length')

if [ "$HIGH_SEVERITY" -gt 0 ]; then
  MESSAGE=$(escape-cli problems --all -o json | \
    jq -r '[.[] | select(.severity == "HIGH" or .severity == "CRITICAL")] |
           .[] | "• \(.name): \(.message)"' | head -5)

  # Send to Slack
  curl -X POST "$SLACK_WEBHOOK_URL" \
    -H "Content-Type: application/json" \
    -d "{
      \"text\": \":rotating_light: $HIGH_SEVERITY High-Severity Scan Problems\",
      \"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(.problemCode) | map({
    type: .[0].problemCode,
    count: length,
    applications: [.[] | .name] | unique
  })'

Example Output:

[
  {
    "type": "AUTH_FAILED",
    "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(.id) | map({
    id: .[0].id,
    name: .[0].name,
    problem_count: length,
    problems: [.[] | {code: .problemCode, 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 '.[] | "\(.id):\(.problemCode)"' "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_FAILED problems
escape-cli problems --all -o json | \
  jq '.[] | select(.problemCode == "AUTH_FAILED") | {
    application: .name,
    message: .message,
    profile_id: .profileId
  }'

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 NETWORK_ERROR problems
escape-cli problems --all -o json | \
  jq '.[] | select(.problemCode == "NETWORK_ERROR")'

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(.problemCode == "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 CONFIG_ERROR problems
escape-cli problems --all -o json | \
  jq '.[] | select(.problemCode == "CONFIG_ERROR")'

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 == "HIGH" or .severity == "CRITICAL")' | \
  while read -r problem; do
    APP_NAME=$(echo "$problem" | jq -r '.name')
    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: [.[] | .id] | unique | length,
  by_severity: (group_by(.severity) | map({severity: .[0].severity, count: length})),
  by_type: (group_by(.problemCode) | map({type: .[0].problemCode, 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(.problemCode == "NETWORK_ERROR" or .problemCode == "TIMEOUT") |
         "\(.profileId)"' | \
  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
# Increase timeout for profiles with timeout issues

escape-cli problems --all -o json | \
  jq -r '.[] | select(.problemCode == "TIMEOUT") | .profileId' | \
  sort -u | \
  while read -r profile_id; do
    echo "Note: Profile $profile_id has timeout issues"
    echo "Consider updating with: --override '{\"scan\": {\"timeout\": 7200}}'"
  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