# Issues Management

Issues represent security findings identified during scans. The Escape CLI provides comprehensive capabilities for listing, filtering, and managing security issues across your application portfolio.

## Understanding Issues

Security issues in Escape include:

- **Vulnerabilities** - SQL injection, XSS, authentication bypass
- **Misconfigurations** - Weak security headers, exposed debug endpoints
- **Information Disclosure** - Leaked credentials, verbose error messages
- **Protocol Issues** - Missing encryption, weak TLS configuration
- **Business Logic Flaws** - BOLA, mass assignment, rate limiting issues

Each issue includes:

- Severity rating (Critical, High, Medium, Low, Info)
- Detailed description and impact analysis
- Reproduction steps
- Remediation guidance
- Affected endpoints or components

## Listing Issues

View all security issues across your organization.

```bash
escape-cli issues list
```

**Aliases:** `list`, `ls`

**Table Columns:** `ID`, `CREATED AT`, `SEVERITY`, `STATUS`, `NAME`, `ASSET`, `LINK`.

### Filtering Issues

Use powerful filters to find specific security findings:

```bash
# Filter by severity
escape-cli issues list --severity HIGH,CRITICAL

# Filter by status
escape-cli issues list --status OPEN

# Filter by specific profile
escape-cli issues list --profile-id <profile-id>

# Filter by asset
escape-cli issues list --asset-id <asset-id>

# Free-text search
escape-cli issues list --search "SQL injection"

# Combine multiple filters
escape-cli issues list --severity HIGH --status OPEN --asset-id <asset-id>
```

**Available Filters:**

| Flag | Short | Description | Example Values |
| --- | --- | --- | --- |
| `--severity` | `-l` | Issue severity | `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFO` |
| `--status` |  | Issue status | `OPEN`, `MANUAL_REVIEW`, `RESOLVED`, `FALSE_POSITIVE`, `IGNORED` |
| `--profile-id` | `-p` | Filter by profile ID | UUID or comma-separated UUIDs |
| `--asset-id` | `-a` | Filter by asset ID | UUID or comma-separated UUIDs |
| `--domain` | `-d` | Filter by domain name | Domain string |
| `--issue-id` | `-i` | Filter by specific issue IDs | UUID or comma-separated UUIDs |
| `--scan-id` |  | Filter by scan ID | UUID |
| `--tag-id` | `-t` | Filter by tag ID | UUID |
| `--risk` | `-r` | Filter by risk level | Risk classification |
| `--asset-class` |  | Filter by asset classification | Asset class type |
| `--search` | `-s` | Free-text search | Any string |

## Getting Issue Details

Retrieve comprehensive information about a specific issue.

```bash
escape-cli issues get <issue-id>
```

**Aliases:** `describe`, `show`

**Example:**

```bash
escape-cli issues get 11111111-1111-1111-1111-111111111111
```

**Output includes:**

- Issue ID and name
- Severity and category
- Detailed description
- Affected endpoint or component
- Reproduction steps
- Remediation guidance
- Related CWE/CVE identifiers
- Issue status and history

**JSON output for detailed analysis:**

```bash
escape-cli issues get <issue-id> -o json
```

## Viewing Scan-Specific Issues

Fetch one page of issues from a specific scan:

```bash
escape-cli scans issues <scan-id>
```

**Aliases:** `issues`, `results`, `res`, `result`, `iss`

**Example:**

```bash
escape-cli scans issues 11111111-1111-1111-1111-111111111111
```

For complete results, use `escape-cli issues list --scan-id <scan-id>`, which follows pagination. Add `--status OPEN` when evaluating open findings. Scan-specific results are useful for:

- Tracking new issues in recent scans
- Comparing issues across scan runs
- Generating scan reports
- CI/CD pipeline integration

See [Scans Management](<https://docs.escape.tech/documentation/automate/cli/scans/#retrieving-scan-issues>) for detailed scan issue commands.

## Updating Issues

Update issue status to track remediation progress.

```bash
escape-cli issues update <issue-id> --status <STATUS>
```

**Aliases:** `set-status`

**Available Statuses:**

| Status | Description |
| --- | --- |
| `OPEN` | Newly discovered, awaiting review |
| `MANUAL_REVIEW` | Under investigation by security team |
| `RESOLVED` | Fixed and verified |
| `FALSE_POSITIVE` | Determined not to be a real issue |
| `IGNORED` | Excluded from active remediation |

**Update Options:**

| Option | Description | Required |
| --- | --- | --- |
| `--status` | New status for the issue | No |
| `--reason` | Reason for the status change (only with `--status`) | No\* |
| `--severity` | New severity level for the issue | No |
| `--reset-severity` | Reset severity to scanner-detected value | No |

\*`--reason` requires `--status` to be set.

**Example updates:**

```bash
# Mark issue under review
escape-cli issues update <issue-id> --status MANUAL_REVIEW

# Keep under review while fixing
escape-cli issues update <issue-id> --status MANUAL_REVIEW

# Mark as resolved after fixing
escape-cli issues update <issue-id> --status RESOLVED

# Mark as false positive
escape-cli issues update <issue-id> --status FALSE_POSITIVE

# Accept risk
escape-cli issues update <issue-id> --status IGNORED

# Update with explanation
escape-cli issues update <issue-id> --status IGNORED --reason "Mitigation in place via WAF"

# Update severity only
escape-cli issues update <issue-id> --severity HIGH
```

**Workflow Example:**

1. New issue discovered: `OPEN`
2. Security team reviews: `MANUAL_REVIEW`
3. Fix deployed and tested: `RESOLVED`

**Example workflow with reasons:**

```bash
# Report new issue
escape-cli issues update <issue-id> --status OPEN

# Team starts investigation
escape-cli issues update <issue-id> --status MANUAL_REVIEW --reason "Assigned for triage"

# Keep the issue under review while work starts
escape-cli issues update <issue-id> --status MANUAL_REVIEW --reason "Fix in development branch feature/auth-bypass"

# Mark as resolved after deployment
escape-cli issues update <issue-id> --status RESOLVED --reason "Fixed in v2.3.1 with input validation"

# Accept risk if not fixing
escape-cli issues update <issue-id> --status IGNORED --reason "Rate limited by CloudFlare, no code change needed"
```

**Bulk updates:**

```bash
# Update multiple issues from a list
cat issue_ids.txt | xargs -I {} escape-cli issues update {} --status MANUAL_REVIEW
```

## Viewing Issue Activity

View the complete activity history and timeline for an issue.

```bash
escape-cli issues list-activities <issue-id>
```

**Aliases:** `ls-activities`, `activities`, `history`, `timeline`

**Example:**

```bash
escape-cli issues list-activities 11111111-1111-1111-1111-111111111111

# Export activity history
escape-cli issues list-activities <issue-id> -o json
```

**Activity types include:**

- Issue creation and first detection
- Status changes (with timestamp and author)
- Scan detections (when issue appears in new scans)
- Resolution confirmations
- Reopen events

This audit trail helps track:

- Who changed what and when
- How long issues remain open
- Resolution verification
- Issue recurrence

## Events, Comments, and Bulk Operations

| Command | Purpose | Options |
| --- | --- | --- |
| `issues get-with-events <issue-id>` | Retrieve an issue with hydrated recent events; aliases `with-events`, `events`. | `-o json` |
| `issues comment <issue-id> --message "Review requested"` | Add a comment; alias `add-comment`. | `--message` is required. |
| `issues funnel` | Show counts across funnel stages. | `--project-id` |
| `issues trends` | Show severity trends. | Required `--after` and `--before` (ISO 8601); `--interval`, `--application-id`, `--project-id`. |
| `issues bulk-update` | Update matching issues. | `--status`, `--reason`, `--set-severity`, or `--reset-severity`; filter with `--issue-id`, `--asset-id`, `--severity`, `--profile-id`, `--tag-id`, `--scanner-kind`. |
| `issues notify <issue-id> --scan-id <scan-id>` | Send an email notification to asset owners. | `--scan-id` is required. |

Bulk updates require at least one of `--status`, `--set-severity`, or `--reset-severity`. `--set-severity` and `--reset-severity` are mutually exclusive.

Additional `issues list` filters include `--jira-ticket` (`-j`), `--scanner-kind`, and `--name`. Use `--sort-by LAST_SEEN|FIRST_SEEN|SEVERITY|STATUS` with `--sort-direction asc|desc` to sort results.

## Issue Severity Levels

Understanding severity helps prioritize remediation:

### Critical

- **Impact**: Immediate security risk, potential data breach
- **Examples**: SQL injection, authentication bypass, RCE
- **Action**: Fix immediately, escalate to security team
- **Timeline**: 24-48 hours

### High

- **Impact**: Significant security risk, potential unauthorized access
- **Examples**: Stored XSS, BOLA, weak authentication
- **Action**: Prioritize in current sprint
- **Timeline**: 1-2 weeks

### Medium

- **Impact**: Moderate security risk, potential information disclosure
- **Examples**: Missing security headers, debug mode enabled
- **Action**: Schedule for upcoming sprint
- **Timeline**: 2-4 weeks

### Low

- **Impact**: Minor security concern, limited exploitability
- **Examples**: Verbose error messages, outdated dependencies
- **Action**: Include in regular maintenance
- **Timeline**: Next release cycle

### Info

- **Impact**: Informational finding, security best practices
- **Examples**: Security recommendations, hardening suggestions
- **Action**: Consider for long-term improvements
- **Timeline**: Backlog

## Issue Categories

Common vulnerability categories in Escape:

| Category | Description | Common Issues |
| --- | --- | --- |
| `INJECTION` | Code injection vulnerabilities | SQL injection, NoSQL injection, command injection |
| `AUTHENTICATION` | Authentication weaknesses | Weak credentials, broken auth flows |
| `AUTHORIZATION` | Authorization flaws | BOLA, privilege escalation, IDOR |
| `PROTOCOL` | Protocol-level issues | Missing TLS, weak ciphers, insecure headers |
| `INFORMATION_DISCLOSURE` | Data exposure | Sensitive data in responses, verbose errors |
| `BUSINESS_LOGIC` | Application logic flaws | Mass assignment, rate limiting bypass |
| `CONFIGURATION` | Misconfigurations | Debug mode, default credentials |

## Filtering and Reporting

### Export High-Severity Issues

```bash
escape-cli issues list --severity CRITICAL,HIGH -o json > high-severity.json
```

### Count Issues by Severity

```bash
escape-cli issues list -o json | jq 'group_by(.severity) | map({severity: .[0].severity, count: length})'
```

**Output:**

```json
[
  {"severity": "CRITICAL", "count": 2},
  {"severity": "HIGH", "count": 15},
  {"severity": "MEDIUM", "count": 42},
  {"severity": "LOW", "count": 28},
  {"severity": "INFO", "count": 10}
]
```

### Generate CSV Report

```bash
escape-cli issues list -o json | jq -r '.[] | [.severity, .category, .name, .status] | @csv' > issues-report.csv
```

### Find Issues in Specific Assets

```bash
# Get issues for a specific asset
ASSET_ID="11111111-1111-1111-1111-111111111111"
escape-cli issues list --asset-id $ASSET_ID -o json
```

### Track New Issues

Compare issues between scans to identify newly discovered vulnerabilities:

```bash
# Get issues from latest scan
escape-cli issues list --scan-id <latest-scan-id> -o json > latest-issues.json

# Get issues from previous scan
escape-cli issues list --scan-id <previous-scan-id> -o json > previous-issues.json

# Compare to find new issues
jq -s '.[0] - .[1]' latest-issues.json previous-issues.json
```

## Issue Lifecycle Management

### Typical Workflow

1. **Detection** - Issue discovered during scan
2. **Triage** - Security team reviews and assesses impact
3. **Assignment** - Issue assigned to development team
4. **Acknowledgment** - Team acknowledges and plans fix
5. **Resolution** - Vulnerability remediated
6. **Verification** - Next scan confirms resolution

### Workflow Example

```bash
#!/bin/bash
# Add triage comments to critical issues

CRITICAL_ISSUES=$(escape-cli issues list --severity CRITICAL --status OPEN -o json)

echo "$CRITICAL_ISSUES" | jq -r '.[].id' | while read -r issue_id; do
    escape-cli issues comment "$issue_id" \
        --message "Security team review requested: Critical severity"
    echo "Commented on issue $issue_id"
done
```

## Integration with Issue Tracking

### Create Jira Tickets

```bash
#!/bin/bash
# Create Jira tickets for high-severity issues

escape-cli issues list --severity HIGH --status OPEN -o json | jq -c '.[]' | while read -r issue; do
    ISSUE_ID=$(echo "$issue" | jq -r '.id')
    ISSUE_NAME=$(echo "$issue" | jq -r '.name')
    ISSUE_URL=$(echo "$issue" | jq -r '.links.issueOverview')

    # Create Jira ticket via REST API
    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\": \"SEC\"},
                \"summary\": \"[Escape] $ISSUE_NAME\",
                \"description\": \"Security issue found: $ISSUE_URL\",
                \"issuetype\": {\"name\": \"Bug\"},
                \"priority\": {\"name\": \"High\"}
            }
        }"
done
```

### Create GitHub Issues

```bash
#!/bin/bash
# Create GitHub issues for critical findings

escape-cli issues list --severity CRITICAL --status OPEN -o json | jq -c '.[]' | while read -r issue; do
    ISSUE_NAME=$(echo "$issue" | jq -r '.name')
    ISSUE_URL=$(echo "$issue" | jq -r '.links.issueOverview')
    ISSUE_DESC=$(echo "$issue" | jq -r '.context')

    gh issue create \
        --title "[Security] $ISSUE_NAME" \
        --body "**Critical Security Finding**\n\n$ISSUE_DESC\n\n[View in Escape]($ISSUE_URL)" \
        --label security,critical
done
```

## Best Practices

### Prioritization

1. **Critical/High issues first** - Address severe vulnerabilities immediately
2. **Consider exploitability** - Prioritize issues with known exploits
3. **Assess business impact** - Focus on issues affecting critical functionality
4. **Track trends** - Monitor if specific issue types are increasing

### Remediation Workflow

1. **Verify the issue** - Confirm it's a true positive
2. **Assess impact** - Understand the security implications
3. **Plan the fix** - Determine remediation approach
4. **Implement** - Apply the security fix
5. **Test** - Verify the fix doesn't break functionality
6. **Re-scan** - Confirm the issue is resolved

### Communication

- **Regular reports** - Share security status with stakeholders
- **Trend analysis** - Track issue resolution rates
- **Team collaboration** - Use assignments and comments effectively
- **Escalation paths** - Define clear escalation for critical issues

### False Positive Handling

If an issue is a false positive:

```bash
# Mark as false positive with explanation
escape-cli issues update <issue-id> \
    --status FALSE_POSITIVE \
    --reason "False positive: Using parameterized queries, not vulnerable to SQL injection"
```

## Troubleshooting

### No Issues Returned

If scans complete but show no issues:

- Verify the scan completed successfully
- Check scan configuration for scope limitations
- Review scan logs for errors
- Ensure the application is accessible from the scan location

### Duplicate Issues

If the same issue appears multiple times:

- Check if it affects multiple endpoints
- Review issue grouping settings in the web interface
- Consider if this indicates a systemic problem requiring broader fixes

### Issues Not Updating

If issue updates fail:

- Verify you have permission to modify issues
- Check the issue ID is correct
- Ensure the status value is valid
- Use JSON output to see detailed error messages

## Next Steps

- **[Scans Management](<https://docs.escape.tech/documentation/automate/cli/scans/index.md>)** - Run scans to discover issues
- **[Practical Recipes](<https://docs.escape.tech/documentation/automate/cli/recipes/index.md>)** - Complete issue management workflows
- **[CI/CD Integration](<https://docs.escape.tech/documentation/automate/ci-cd/index.md>)** - Automate issue detection in pipelines