# EPSS Threshold Gate

**Gate ID:** `epss-threshold`

Blocks CVEs with Exploit Prediction Scoring System (EPSS) probability above a configurable threshold. EPSS predicts the likelihood that a CVE will be exploited in the wild within 30 days.

## How It Works

1. For each CVE finding in the release candidate, queries the EPSS score
2. Compares EPSS probability against the configured threshold
3. Blocks if any CVE exceeds threshold (or all match in "all must pass" mode)
4. Provides grace period for newly published CVEs

## Configuration

```json
{
  "Policy": {
    "Gates": {
      "EpssThreshold": {
        "Enabled": true,
        "Threshold": 0.6,
        "Mode": "any",
        "GracePeriodDays": 7,
        "RequireReachability": false,
        "Environments": {
          "production": {
            "Threshold": 0.3
          }
        }
      }
    }
  }
}
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `Enabled` | bool | `true` | Whether the gate is active |
| `Threshold` | double | `0.6` | EPSS probability threshold (0.0 - 1.0) |
| `Mode` | string | `any` | `any` = block if any CVE exceeds; `all` = block only if all exceed |
| `GracePeriodDays` | int? | `null` | Days after CVE publication before enforcing (null = no grace) |
| `RequireReachability` | bool | `false` | Only evaluate reachable CVEs |
| `Environments` | dict | `{}` | Per-environment overrides |

## EPSS Score Interpretation

| EPSS Range | Risk Level | Typical Action |
|------------|------------|----------------|
| 0.0 - 0.1 | Very Low | Monitor |
| 0.1 - 0.3 | Low | Schedule remediation |
| 0.3 - 0.6 | Medium | Prioritize remediation |
| 0.6 - 0.9 | High | Block or exception required |
| 0.9 - 1.0 | Critical | Immediate block |

## Example Gate Results

**Pass:**
```
EPSS threshold check passed. 12 CVE(s) evaluated, all below threshold 0.6
```

**Fail:**
```
EPSS threshold exceeded: CVE-2024-1234 (EPSS: 0.72), CVE-2024-5678 (EPSS: 0.85)
```

## CLI Usage

```bash
# Evaluate EPSS gate against image
stella policy evaluate --gate epss-threshold --image myapp:v1.2.3

# Override threshold for testing
stella policy evaluate --gate epss-threshold --threshold 0.9 --image myapp:v1.2.3
```

## Data Source

EPSS scores are fetched from [FIRST EPSS](https://www.first.org/epss/) via the configured `IEpssDataProvider`. Scores are cached and updated daily.

---

*Last updated: 2026-01-19.*