# Concelier EPSS Connector Operations

This playbook covers deployment and monitoring of the EPSS connector that ingests daily FIRST.org EPSS snapshots.

## 1. Prerequisites

- Network egress to `https://epss.empiricalsecurity.com/` (or a mirrored endpoint).
- Updated `concelier.yaml` (or environment variables) with the EPSS source configuration:

```yaml
concelier:
  sources:
    epss:
      baseUri: "https://epss.empiricalsecurity.com/"
      fetchCurrent: true
      catchUpDays: 7
      httpTimeout: "00:02:00"
      maxRetries: 3
      airgapMode: false
      bundlePath: "/var/stellaops/bundles/epss"
```

## 2. Smoke Test (staging)

1. Restart Concelier workers after configuration changes.
2. Trigger a full cycle:
   - CLI: `stella db jobs run source:epss:fetch --and-then source:epss:parse --and-then source:epss:map`
   - REST: `POST /jobs/run { "kind": "source:epss:fetch", "chain": ["source:epss:parse", "source:epss:map"] }`
3. Verify document status transitions: `pending_parse` -> `pending_map` -> `mapped`.
4. Confirm log entries for `Fetched EPSS snapshot` and parse/map summaries.

## 3. Monitoring

- **Meter**: `StellaOps.Concelier.Connector.Epss`
- **Key counters**:
  - `epss.fetch.attempts`, `epss.fetch.success`, `epss.fetch.failures`, `epss.fetch.unchanged`
  - `epss.parse.rows`, `epss.parse.failures`
  - `epss.map.rows`
- **Alert suggestions**:
  - `rate(epss_fetch_failures_total[15m]) > 0`
  - `rate(epss_map_rows_total[1h]) == 0` during business hours while other connectors are active

## 4. Airgap Mode

- Place snapshots in the bundle directory:
  - `epss_scores-YYYY-MM-DD.csv.gz`
  - Optional `manifest.json` listing `name`, `modelVersion`, `sha256`, and `rowCount`.
- Set `airgapMode: true` and `bundlePath` to the directory or specific file.
- The connector validates the manifest hash when present and logs warnings on mismatch.