old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions
This commit is contained in:
@@ -81,6 +81,99 @@ The Console uses these concepts to keep VEX explainable:
|
||||
|
||||
See `docs/UI_GUIDE.md` for the operator workflow perspective.
|
||||
|
||||
## Anchor-Aware Mode (v1.1)
|
||||
|
||||
> **Sprint:** SPRINT_20260112_004_BE_policy_determinization_attested_rules
|
||||
|
||||
Anchor-aware mode enforces cryptographic attestation requirements on VEX proofs used for allow decisions.
|
||||
|
||||
### VexProofGate Options
|
||||
|
||||
| Option | Type | Default | Strict Mode |
|
||||
|--------|------|---------|-------------|
|
||||
| `AnchorAwareMode` | bool | `false` | `true` |
|
||||
| `RequireVexAnchoring` | bool | `false` | `true` |
|
||||
| `RequireRekorVerification` | bool | `false` | `true` |
|
||||
| `RequireSignedStatements` | bool | `false` | `true` |
|
||||
| `RequireProofForFixed` | bool | `false` | `true` |
|
||||
| `MaxAllowedConflicts` | int | `5` | `0` |
|
||||
| `MaxProofAgeHours` | int | `168` | `72` |
|
||||
|
||||
### Strict Anchor-Aware Preset
|
||||
|
||||
For production environments requiring maximum security:
|
||||
|
||||
```csharp
|
||||
var options = VexProofGateOptions.StrictAnchorAware;
|
||||
// Enables: RequireVexAnchoring, RequireRekorVerification,
|
||||
// RequireSignedStatements, RequireProofForFixed
|
||||
// Sets: MinimumConfidenceTier=high, MaxAllowedConflicts=0, MaxProofAgeHours=72
|
||||
```
|
||||
|
||||
### Metadata Keys
|
||||
|
||||
When passing VEX proof context through policy evaluation:
|
||||
|
||||
| Key | Type | Description |
|
||||
|-----|------|-------------|
|
||||
| `vex_proof_anchored` | bool | Whether proof has DSSE anchoring |
|
||||
| `vex_proof_envelope_digest` | string | DSSE envelope sha256 digest |
|
||||
| `vex_proof_rekor_verified` | bool | Whether Rekor transparency verified |
|
||||
| `vex_proof_rekor_log_index` | long | Rekor log index if verified |
|
||||
|
||||
### Failure Reasons
|
||||
|
||||
| Reason | Description |
|
||||
|--------|-------------|
|
||||
| `vex_not_anchored` | VEX proof requires DSSE anchoring but is not anchored |
|
||||
| `rekor_verification_missing` | VEX proof requires Rekor verification but not verified |
|
||||
|
||||
## VEX Change Events
|
||||
|
||||
> Sprint: SPRINT_20260112_006_EXCITITOR_vex_change_events
|
||||
|
||||
Excititor emits deterministic events when VEX statements change, enabling policy reanalysis.
|
||||
|
||||
### Event Types
|
||||
|
||||
| Event | Description | Policy Trigger |
|
||||
|-------|-------------|----------------|
|
||||
| `vex.statement.added` | New statement ingested | Immediate reanalysis |
|
||||
| `vex.statement.superseded` | Statement replaced | Immediate reanalysis |
|
||||
| `vex.statement.conflict` | Status disagreement detected | Queue for review |
|
||||
| `vex.status.changed` | Effective status changed | Immediate reanalysis |
|
||||
|
||||
### Conflict Detection
|
||||
|
||||
Conflicts are detected when multiple providers report different statuses for the same vulnerability-product pair:
|
||||
|
||||
| Conflict Type | Description |
|
||||
|---------------|-------------|
|
||||
| `status_mismatch` | Different status values (e.g., affected vs not_affected) |
|
||||
| `trust_tie` | Equal trust scores with different recommendations |
|
||||
| `supersession_conflict` | Disagreement on which statement supersedes |
|
||||
|
||||
### Event Ordering
|
||||
|
||||
Events follow deterministic ordering:
|
||||
1. Ordered by timestamp (ascending)
|
||||
2. Conflict events after related statement events
|
||||
3. Same-timestamp events sorted by provider ID
|
||||
|
||||
### Integration with Policy
|
||||
|
||||
Subscribe to VEX events for automatic reanalysis:
|
||||
|
||||
```yaml
|
||||
subscriptions:
|
||||
- event: vex.statement.*
|
||||
action: reanalyze
|
||||
filter:
|
||||
trustScore: { $gte: 0.7 }
|
||||
```
|
||||
|
||||
See [Excititor Architecture](docs/modules/excititor/architecture.md#33-vex-change-events) for full event schemas.
|
||||
|
||||
## Offline / Air-Gap Operation
|
||||
|
||||
- VEX observations/linksets are included in Offline Kit snapshots with content hashes and timestamps.
|
||||
|
||||
Reference in New Issue
Block a user