finish off sprint advisories and sprints
This commit is contained in:
master
219
docs/modules/policy/guides/policy-import-export.md
Normal file
219
docs/modules/policy/guides/policy-import-export.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# Policy Import/Export Guide
|
||||
|
||||
This guide covers bidirectional policy exchange between Stella's native C# engine and OPA/Rego.
|
||||
|
||||
## Overview
|
||||
|
||||
Stella supports two policy formats:
|
||||
- **PolicyPack v2 (JSON)**: Canonical format with typed gates, environment overrides, and remediation hints.
|
||||
- **OPA/Rego**: Standard policy-as-code format for interoperability with OPA-based toolchains.
|
||||
|
||||
The C# gate engine remains primary. Rego is an export target for teams using OPA, and an import source for adopting external policies.
|
||||
|
||||
## Formats
|
||||
|
||||
### PolicyPack v2 (JSON)
|
||||
|
||||
Schema: `policy.stellaops.io/v2`
|
||||
|
||||
Structure:
|
||||
```json
|
||||
{
|
||||
"apiVersion": "policy.stellaops.io/v2",
|
||||
"kind": "PolicyPack",
|
||||
"metadata": { "name": "...", "version": "1.0.0" },
|
||||
"spec": {
|
||||
"settings": { "defaultAction": "block", "deterministicMode": true },
|
||||
"gates": [...],
|
||||
"rules": [...]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Key features:
|
||||
- Per-environment configuration overrides (production/staging/development thresholds)
|
||||
- Structured remediation hints with CLI command templates
|
||||
- Deterministic evaluation mode
|
||||
- SHA-256 content digest for integrity
|
||||
|
||||
### OPA/Rego
|
||||
|
||||
Generated or imported Rego follows the deny-by-default pattern:
|
||||
|
||||
```rego
|
||||
package stella.release
|
||||
|
||||
import rego.v1
|
||||
|
||||
default allow := false
|
||||
|
||||
deny contains msg if {
|
||||
not input.dsse.verified
|
||||
msg := "DSSE signature missing"
|
||||
}
|
||||
|
||||
allow if { count(deny) == 0 }
|
||||
|
||||
remediation contains hint if {
|
||||
some msg in deny
|
||||
msg == "DSSE signature missing"
|
||||
hint := {"code": "DSSE_MISS", "fix": "...", "severity": "critical"}
|
||||
}
|
||||
```
|
||||
|
||||
## CLI Commands
|
||||
|
||||
### Export
|
||||
|
||||
Export a policy to JSON or Rego:
|
||||
|
||||
```bash
|
||||
# Export to Rego
|
||||
stella policy export --file policy.json --format rego --output-file release.rego
|
||||
|
||||
# Export with environment-specific thresholds
|
||||
stella policy export --file policy.json --format rego --environment production
|
||||
|
||||
# Export without remediation hints
|
||||
stella policy export --file policy.json --format json --include-remediation false
|
||||
|
||||
# Export to stdout (pipe-friendly)
|
||||
stella policy export --file policy.json --format rego | opa check -
|
||||
```
|
||||
|
||||
### Import
|
||||
|
||||
Import a policy from JSON or Rego:
|
||||
|
||||
```bash
|
||||
# Import and validate a JSON policy
|
||||
stella policy import --file production-baseline.json
|
||||
|
||||
# Import with validation only (no persist)
|
||||
stella policy import --file external-policy.rego --validate-only
|
||||
|
||||
# Dry-run to preview changes
|
||||
stella policy import --file new-rules.json --dry-run
|
||||
|
||||
# Force format detection
|
||||
stella policy import --file rules.txt --format rego
|
||||
```
|
||||
|
||||
### Validate
|
||||
|
||||
Validate a policy file:
|
||||
|
||||
```bash
|
||||
# Basic validation
|
||||
stella policy validate --file policy.json
|
||||
|
||||
# Strict mode (warnings become errors)
|
||||
stella policy validate --file policy.json --strict
|
||||
|
||||
# JSON output for CI integration
|
||||
stella policy validate --file policy.json --output json
|
||||
```
|
||||
|
||||
Exit codes: `0` = valid, `1` = warnings, `2` = errors.
|
||||
|
||||
### Evaluate
|
||||
|
||||
Evaluate a policy against evidence:
|
||||
|
||||
```bash
|
||||
# Evaluate with table output
|
||||
stella policy evaluate --policy baseline.json --input evidence.json
|
||||
|
||||
# With environment override
|
||||
stella policy evaluate --policy baseline.json --input evidence.json --environment staging
|
||||
|
||||
# JSON output for programmatic use
|
||||
stella policy evaluate --policy baseline.json --input evidence.json --output json
|
||||
|
||||
# CI mode (GitHub Actions annotations)
|
||||
stella policy evaluate --policy baseline.json --input evidence.json --output ci
|
||||
```
|
||||
|
||||
Exit codes: `0` = allow, `1` = warn, `2` = block.
|
||||
|
||||
## Evidence Input Format
|
||||
|
||||
The evaluation input follows the canonical evidence JSON schema:
|
||||
|
||||
```json
|
||||
{
|
||||
"environment": "production",
|
||||
"subject": {
|
||||
"imageDigest": "sha256:abc...",
|
||||
"purl": "pkg:docker/myapp@1.0.0",
|
||||
"tags": ["env:prod"]
|
||||
},
|
||||
"dsse": { "verified": true, "signers": ["ca://fulcio/..."] },
|
||||
"rekor": { "verified": true, "logID": "...", "integratedTime": 1737480000 },
|
||||
"sbom": { "format": "cyclonedx-1.6", "canonicalDigest": "sha256:..." },
|
||||
"freshness": { "tstVerified": true, "timestamp": "2026-01-22T10:00:00Z", "maxAgeHours": 24 },
|
||||
"cvss": { "score": 7.5, "version": "3.1" },
|
||||
"reachability": { "status": "confirmed", "confidence": 0.85 },
|
||||
"confidence": 0.82
|
||||
}
|
||||
```
|
||||
|
||||
## Remediation Hints
|
||||
|
||||
When a gate blocks, the CLI displays actionable fix suggestions:
|
||||
|
||||
```
|
||||
Decision: BLOCK
|
||||
|
||||
Gate Type Result Reason
|
||||
signature SignatureRequiredGate FAIL Required signature missing
|
||||
sbom SbomPresenceGate PASS passed
|
||||
|
||||
Remediation:
|
||||
SIG_MISS: Required signature missing
|
||||
- Sign attestation with DSSE.
|
||||
$ stella attest attach --sign --image sha256:abc...
|
||||
- Anchor attestation in Rekor.
|
||||
$ stella attest attach --rekor --image sha256:abc...
|
||||
```
|
||||
|
||||
## Rego Import Behavior
|
||||
|
||||
When importing Rego files, the system:
|
||||
1. Parses `deny` rules and maps known patterns to native gates (CVSS comparisons, boolean checks).
|
||||
2. Extracts `remediation` rules into structured hints.
|
||||
3. Unknown patterns are preserved and evaluated via the embedded OPA evaluator.
|
||||
4. Validation reports which rules mapped natively vs. remain OPA-evaluated.
|
||||
|
||||
## Determinism
|
||||
|
||||
All evaluations are deterministic:
|
||||
- Same policy + same input = same output (hash-verifiable)
|
||||
- No time-dependent logic in deterministic mode
|
||||
- `outputDigest` in evaluation results enables replay verification
|
||||
|
||||
## API Endpoints
|
||||
|
||||
The Platform API exposes policy interop at `/api/v1/policy/interop`:
|
||||
|
||||
| Method | Path | Description |
|
||||
|--------|------|-------------|
|
||||
| POST | `/export` | Export policy to format |
|
||||
| POST | `/import` | Import policy from format |
|
||||
| POST | `/validate` | Validate policy document |
|
||||
| POST | `/evaluate` | Evaluate policy against input |
|
||||
| GET | `/formats` | List supported formats |
|
||||
|
||||
## Gate Types
|
||||
|
||||
Supported gate types with Rego translation:
|
||||
|
||||
| Gate Type | Rego Pattern | Remediation Code |
|
||||
|-----------|-------------|-----------------|
|
||||
| `CvssThresholdGate` | `input.cvss.score >= threshold` | `CVSS_EXCEED` |
|
||||
| `SignatureRequiredGate` | `not input.dsse.verified` | `SIG_MISS` |
|
||||
| `EvidenceFreshnessGate` | `not input.freshness.tstVerified` | `FRESH_EXPIRED` |
|
||||
| `SbomPresenceGate` | `not input.sbom.canonicalDigest` | `SBOM_MISS` |
|
||||
| `MinimumConfidenceGate` | `input.confidence < threshold` | `CONF_LOW` |
|
||||
| `UnknownsBudgetGate` | `input.unknownsRatio > threshold` | `UNK_EXCEED` |
|
||||
| `ReachabilityRequirementGate` | `not input.reachability.status` | `REACH_REQUIRED` |
|
||||
Reference in New Issue
Block a user