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:
@@ -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 |
|
||||
|--------------|----------------|
|
||||
|
||||
Reference in New Issue
Block a user