# 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.

```bash
escape-cli problems [flags]
```

**Aliases:** `problem`

### Basic Usage

```bash
# 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

```bash
# 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.

```bash
escape-cli problems
```

**Example Output:**

```text
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.

```bash
escape-cli problems --all
```

**Example Output:**

```text
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:

```bash
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_CORS` | The browser blocked requests (CORS). |
| `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

```bash
#!/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

```bash
#!/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

```bash
#!/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

```bash
#!/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

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

**Example Output:**

```json
[
  {
    "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

```bash
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

```bash
#!/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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
#!/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

```bash
#!/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

```bash
#!/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

```bash
#!/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

1. **Triage by severity** - Address high-severity problems first
2. **Identify patterns** - Look for common root causes
3. **Document solutions** - Create runbooks for recurring issues
4. **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](<https://docs.escape.tech/documentation/automate/cli/scans/index.md>)** - Run and monitor scans
- **[Events Management](<https://docs.escape.tech/documentation/automate/cli/events/index.md>)** - Debug scan execution
- **[Audit Logs](<https://docs.escape.tech/documentation/automate/cli/audit-logs/index.md>)** - Track system activity
- **[Practical Recipes](<https://docs.escape.tech/documentation/automate/cli/recipes/index.md>)** - Complete workflow examples