Concelier EPSS Connector - Operations Runbook

This playbook is for operators who deploy and monitor the EPSS connector in a Stella Ops Concelier instance. The connector ingests the daily FIRST.org EPSS snapshots that feed exploit-probability scoring into the Stella Ops policy engine. It covers prerequisites, smoke testing, monitoring, and air-gapped operation.

1. Prerequisites

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

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: run stella db fetch --source epss --stage fetch, then --stage parse, then --stage 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. Air-gapped Mode

For staging and verifying mirrored bundles, see the mirror operations guide.

• 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 a specific file.
• The connector validates the manifest hash when present and logs warnings on mismatch.