97 lines
3.1 KiB
Markdown
97 lines
3.1 KiB
Markdown
# Execution Evidence Gate
|
|
|
|
**Gate ID:** `execution-evidence`
|
|
|
|
Enforces that an artifact has signed execution evidence from a specific environment before promotion. Ensures artifacts are observed running (with sufficient trace quality) before advancing through the release pipeline.
|
|
|
|
## How It Works
|
|
|
|
1. Checks if the target environment requires execution evidence (configurable per environment)
|
|
2. Reads execution evidence metadata from the policy context
|
|
3. If no evidence exists, applies the configured action (warn or block)
|
|
4. If evidence exists, validates trace quality (minimum hot symbols and unique call paths)
|
|
5. Returns pass, warn, or block result
|
|
|
|
## Configuration
|
|
|
|
```json
|
|
{
|
|
"PolicyGates": {
|
|
"ExecutionEvidence": {
|
|
"Enabled": false,
|
|
"MissingEvidenceAction": "Warn",
|
|
"RequiredEnvironments": ["production"],
|
|
"MinHotSymbolCount": 3,
|
|
"MinUniqueCallPaths": 1
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Options
|
|
|
|
| Option | Type | Default | Description |
|
|
|--------|------|---------|-------------|
|
|
| `Enabled` | bool | `false` | Whether the gate is active (opt-in) |
|
|
| `MissingEvidenceAction` | enum | `Warn` | Action when evidence is missing: `Warn` or `Block` |
|
|
| `RequiredEnvironments` | string[] | `["production"]` | Environments that require execution evidence |
|
|
| `MinHotSymbolCount` | int | `3` | Minimum hot symbols for sufficient trace quality |
|
|
| `MinUniqueCallPaths` | int | `1` | Minimum unique call paths for sufficient trace quality |
|
|
|
|
## Context Metadata Keys
|
|
|
|
The gate reads the following keys from `PolicyGateContext.Metadata`:
|
|
|
|
| Key | Type | Description |
|
|
|-----|------|-------------|
|
|
| `has_execution_evidence` | `"true"/"false"` | Whether execution evidence exists |
|
|
| `execution_evidence_hot_symbol_count` | int string | Number of hot symbols in the evidence |
|
|
| `execution_evidence_unique_call_paths` | int string | Number of unique call paths |
|
|
|
|
## Example Gate Results
|
|
|
|
**Pass (evidence meets quality):**
|
|
```
|
|
Execution evidence meets quality thresholds (hot symbols: 42, call paths: 17)
|
|
```
|
|
|
|
**Pass (environment not required):**
|
|
```
|
|
Execution evidence not required for environment 'staging'
|
|
```
|
|
|
|
**Warn (no evidence, warn mode):**
|
|
```
|
|
No execution evidence found for this artifact (warn mode)
|
|
```
|
|
|
|
**Fail (no evidence, block mode):**
|
|
```
|
|
No execution evidence found for this artifact in required environment
|
|
```
|
|
|
|
**Fail (insufficient quality):**
|
|
```
|
|
Execution evidence trace quality is insufficient: hot symbols 1 < 3 or call paths 0 < 1
|
|
```
|
|
|
|
## Integration
|
|
|
|
This gate consumes `stella.ops/executionEvidence@v1` predicates generated by the Signals execution evidence pipeline. Evidence is populated in the policy context during release evaluation.
|
|
|
|
Typical flow:
|
|
1. Artifact runs in staging environment
|
|
2. Signals captures runtime trace via eBPF/ETW
|
|
3. `ExecutionEvidenceBuilder` generates signed predicate
|
|
4. Release promotion to production triggers policy evaluation
|
|
5. This gate verifies execution evidence exists from staging
|
|
|
|
## Related Documents
|
|
|
|
- `docs/contracts/execution-evidence-v1.md` — Predicate contract
|
|
- `docs/modules/policy/gates/beacon-rate-gate.md` — Companion beacon rate gate
|
|
|
|
---
|
|
|
|
*Last updated: 2026-02-19.*
|