# Dependency Security Exception Flow (pip-audit)

This document defines the auditable exception process for Python dependency vulnerabilities.

## Policy

- CI blocks unresolved `HIGH` and `CRITICAL` dependency vulnerabilities.
- If a vulnerability does not provide severity metadata, it is treated as `HIGH` by policy.
- Temporary exceptions are allowed only through `ops/security/pip-audit-allowlist.json`.

## Allowlist Location

- File: `ops/security/pip-audit-allowlist.json`
- Format:

```json
{
  "entries": [
    {
      "id": "CVE-2026-12345",
      "package": "example-package",
      "reason": "Upstream fix not released yet",
      "approved_by": "security-owner",
      "issue": "NX-202",
      "expires_on": "2026-12-31"
    }
  ]
}
```

## Required Fields

- `id`: Vulnerability ID (`CVE-*`, `GHSA-*`, or advisory ID)
- `reason`: Why exception is necessary
- `approved_by`: Approver identity
- `issue`: Tracking issue/ticket
- `expires_on`: Expiry date in `YYYY-MM-DD`

Optional:

- `package`: Restrict exception to one dependency package

## Rules

- Expired allowlist entries fail CI.
- Missing required fields fail CI.
- Exceptions must be time-limited and linked to a tracking issue.
- Removing an exception is required once an upstream fix is available.

## Auditability

- Every exception change is tracked in Git history and code review.
- CI logs include blocked vulnerabilities and allowlisted findings counts.