# Issues Management

Purplemet tracks security issues across all your sites. Use the `issues` commands to list, triage, and collaborate on findings.

## List Issues

```bash
purplemet-cli issues list [flags]
```

Lists issues across all your sites.

| Flag | Default | Description |
|------|---------|-------------|
| `--limit` | `100` | Page size (1–1000) |
| `--all` | `false` | Fetch every page automatically (capped by `--max`) |
| `--max` | `10000` | Hard cap on items fetched when `--all` is set |
| `--severity` | — | Filter by severity: `critical`, `high`, `medium`, `low`, `info` |
| `--status` | — | Filter by status: `OPEN`, `FIXED`, `REJECTED`, `IGNORED` |
| `--query` | — | Generic filter, e.g. `--query "severity=high,status=OPEN"` |
| `--json` | `false` | JSON output |

See [Pagination](configuration.md#pagination) for the full set of pagination flags shared by every `list` command.

**Example:**

```bash
# List all open high/critical issues
purplemet-cli issues list --severity high --status OPEN

# JSON output for scripting — fetch every page
purplemet-cli issues list --json --all | jq '.[] | select(.severity == "CRITICAL")'
```

**Output columns:**

| Column | Description |
|--------|-------------|
| ID | Unique issue ID (use as input for `issues ignore` / `issues activate`) |
| SEVERITY | CRITICAL, HIGH, MEDIUM, LOW, INFO |
| STATUS | OPEN, FIXED, REJECTED, IGNORED |
| NAME | CVE identifier or vulnerability name |
| TECHNOLOGY | Affected technology and version |
| TYPE | Issue category (e.g. `SSL_TLS_PROTOCOLS`, `HTTP_HEADERS`) |

### JSON Fields

Each issue in JSON output contains:

> **Fields are omitted when empty.** The JSON is encoded with `omitempty`, so a
> field appears only when it holds a non-zero / non-empty value. A web issue
> (e.g. a TLS or HTTP-header finding with no associated CVE) therefore emits a
> subset of the fields below — `description`, `reference`, `cwe.name`,
> `exploitMaturity` and the `details.*` block appear only when populated. The
> table lists every field `issues list --json` *can* emit, not a guaranteed-present set.

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique issue ID |
| `site.id` | string | Site UUID |
| `site.url` | string | Site URL |
| `severity` | string | Severity level |
| `type` | string | Issue type |
| `name` | string | CVE or issue name |
| `description` | string | Detailed description |
| `reference` | string | External reference URL |
| `cweId` | string | CWE identifier |
| `cwe.name` | string | CWE name |
| `exploitMaturity` | string | `ATTACKED` if actively exploited |
| `status` | string | OPEN, FIXED, REJECTED, IGNORED |
| `technology.id` | string | Affected technology UUID |
| `technology.name` | string | Affected technology |
| `technology.version` | string | Affected version |
| `technology.category` | string | Technology category |
| `technology` | string | Human-readable `name version` summary |
| `weight` | int | Internal weight used to compute the score |
| `publishedAt` | int | Vulnerability publication date (unix ms) |
| `commentCnt` | int | Number of comments |
| `firstDetectedAt` | int | First detection (unix ms) |
| `lastDetectedAt` | int | Last detection (unix ms) |
| `details.cvss3Score` | float | CVSS v3 score (0–10) |
| `details.cvss3Vector` | string | CVSS v3 vector |
| `details.cvss4Score` | float | CVSS v4 score (0–10), when available |
| `details.cvss4Vector` | string | CVSS v4 vector |
| `details.cvssScore` | float | Generic CVSS score when no version-specific score is provided |
| `details.cvssVector` | string | Generic CVSS vector when no version-specific vector is provided |

> **Most fields are optional** (`omitempty`): they appear only when populated.
> An issue without a CWE, description, comments or CVSS details simply omits
> those keys, so a given `issues list --json` row may carry only a subset of the
> fields above. Run the command once on your own data to see which keys a
> finding actually has.

## Ignore Issues

Mark issues as ignored with a reason. Ignored issues are always excluded from gate evaluation — an acknowledged risk should not re-fail a pipeline.

```bash
purplemet-cli issues ignore <issueId> [id...] --reason <reason> [flags]
```

| Flag | Required | Description |
|------|----------|-------------|
| `--reason` | **Yes** | Reason for ignoring |
| `--comments` | No | Additional notes |
| `--snooze` | No | Snooze until date (YYYY-MM-DD) — re-activates automatically |

**Valid reasons** (enum defined by the Purplemet API):

`RISK_ACCEPTED`, `NOT_APPLICABLE`, `FIX_IN_PROGRESS`, `BACKPORTING`, `FALSE_POSITIVE`

Refer to the [official Purplemet documentation](https://cloud.purplemet.com/docs) for the authoritative semantics of each reason.

**Examples:**

```bash
# Ignore a single issue
purplemet-cli issues ignore abc123 --reason RISK_ACCEPTED --comments "Low impact for our use case"

# Ignore multiple issues at once
purplemet-cli issues ignore abc123 def456 ghi789 --reason NOT_APPLICABLE

# Snooze an issue until a fix is expected
purplemet-cli issues ignore abc123 --reason FIX_IN_PROGRESS --snooze 2025-06-01
```

## Activate Issues

Re-activate previously ignored issues:

```bash
purplemet-cli issues activate <issueId> [id...]
```

**Examples:**

```bash
# Re-activate one issue
purplemet-cli issues activate abc123

# Re-activate multiple issues
purplemet-cli issues activate abc123 def456
```

## Comments

Collaborate on issues by adding comments.

### List Comments

```bash
purplemet-cli issues comment list <issueId> [--limit 100]
```

### Create a Comment

```bash
purplemet-cli issues comment create <issueId> --contents "Investigated — this is a known upstream issue, tracking in JIRA-1234"
```

### Update a Comment

```bash
purplemet-cli issues comment update <issueId> <commentId> --contents "Updated: fix deployed in v2.3.1"
```

### Delete a Comment

```bash
purplemet-cli issues comment delete <issueId> <commentId>
```

## Workflow Example

A typical triage workflow:

```bash
# 1. List critical and high issues
purplemet-cli issues list --severity high --status OPEN

# 2. Investigate a specific issue (check the reference URL)
purplemet-cli issues list --json | jq '.[] | select(.id == "abc123") | {name, description, reference}'

# 3. Accept the risk for a low-impact issue
purplemet-cli issues ignore abc123 --reason RISK_ACCEPTED --comments "Internal-only endpoint, no user data"

# 4. Mark an issue as fix in progress
purplemet-cli issues ignore def456 --reason FIX_IN_PROGRESS --snooze 2025-07-01 --comments "PR #42 pending review"

# 5. Run analysis (ignored issues are automatically excluded from gates)
purplemet-cli analyze https://app.com --json --fail-on-severity high
```