feat: add Attestation Chain and Triage Evidence API clients and models

- Implemented Attestation Chain API client with methods for verifying, fetching, and managing attestation chains.
- Created models for Attestation Chain, including DSSE envelope structures and verification results.
- Developed Triage Evidence API client for fetching finding evidence, including methods for evidence retrieval by CVE and component.
- Added models for Triage Evidence, encapsulating evidence responses, entry points, boundary proofs, and VEX evidence.
- Introduced mock implementations for both API clients to facilitate testing and development.
This commit is contained in:
master
2025-12-18 13:15:13 +02:00
parent 7d5250238c
commit 00d2c99af9
118 changed files with 13463 additions and 151 deletions

View File

@@ -333,12 +333,86 @@ For each vulnerability instance:
- [ ] Trend visualization
### Phase 5: Operations
- [ ] Backfill tool (last 180 days)
- [ ] Ops runbook: schedules, manual re-run, air-gap import
- [x] Backfill tool (last 180 days)
- [x] Ops runbook: schedules, manual re-run, air-gap import
---
## 10. Anti-Patterns to Avoid
## 10. Operations Runbook
### 10.1 Configuration
EPSS ingestion is configured via the `Epss:Ingest` section in Scanner Worker configuration:
```yaml
Epss:
Ingest:
Enabled: true # Enable/disable the job
Schedule: "0 5 0 * * *" # Cron expression (default: 00:05 UTC daily)
SourceType: "online" # "online" or "bundle"
BundlePath: null # Path for air-gapped bundle import
InitialDelay: "00:00:30" # Wait before first run (30s)
RetryDelay: "00:05:00" # Delay between retries (5m)
MaxRetries: 3 # Maximum retry attempts
```
### 10.2 Online Mode (Connected)
The job automatically fetches EPSS data from FIRST.org at the scheduled time:
1. Downloads `https://epss.empiricalsecurity.com/epss_scores-YYYY-MM-DD.csv.gz`
2. Validates SHA256 hash
3. Parses CSV and bulk inserts to `epss_scores`
4. Computes delta against `epss_current`
5. Updates `epss_current` projection
6. Publishes `epss.updated` event
### 10.3 Air-Gap Mode (Bundle)
For offline deployments:
1. Download EPSS CSV from FIRST.org on an internet-connected system
2. Copy to the configured `BundlePath` location
3. Set `SourceType: "bundle"` in configuration
4. The job will read from the local file instead of fetching online
### 10.4 Manual Ingestion
Trigger manual ingestion via the Scanner Worker API:
```bash
# POST to trigger immediate ingestion for a specific date
curl -X POST "https://scanner-worker/epss/ingest?date=2025-12-18"
```
### 10.5 Troubleshooting
| Symptom | Likely Cause | Resolution |
|---------|--------------|------------|
| Job not running | `Enabled: false` | Set `Enabled: true` |
| Download fails | Network/firewall | Check HTTPS egress to `epss.empiricalsecurity.com` |
| Parse errors | Corrupted file | Re-download, check SHA256 |
| Slow ingestion | Large dataset | Normal for ~250k rows; expect 60-90s |
| Duplicate runs | Idempotent | Safe - existing data preserved |
### 10.6 Monitoring
Key metrics and traces:
- **Activity**: `StellaOps.Scanner.EpssIngest` with tags:
- `epss.model_date`: Date of EPSS model
- `epss.row_count`: Number of rows ingested
- `epss.cve_count`: Distinct CVEs processed
- `epss.duration_ms`: Total ingestion time
- **Logs**: Structured logs at Info/Warning/Error levels
- `EPSS ingest job started`
- `Starting EPSS ingestion for {ModelDate}`
- `EPSS ingestion completed: modelDate={ModelDate}, rows={RowCount}...`
---
## 11. Anti-Patterns to Avoid
| Anti-Pattern | Why It's Wrong |
|--------------|----------------|