stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity

finish off sprint advisories and sprints

Browse Source
This commit is contained in:
master
2026-01-24 00:12:43 +02:00
parent 726d70dc7f
commit c70e83719e
266 changed files with 46699 additions and 1328 deletions
Download Patch File Download Diff File Expand all files Collapse all files

143
docs/modules/policy/architecture.md
View File

@@ -173,6 +173,10 @@ The Determinization subsystem calculates uncertainty scores based on signal comp
Determinization scores are exposed to SPL policies via the `signals.trust.*` and `signals.uncertainty.*` namespaces. Use `signals.uncertainty.entropy` to access entropy values and `signals.trust.score` for aggregated trust scores that combine VEX, reachability, runtime, and other signals with decay/weighting.
**Weight Manifests:**
EWS weights are externalized to versioned JSON manifests in `etc/weights/`. The unified score facade (`IUnifiedScoreService`) loads weights from these manifests rather than using compiled defaults, enabling auditable weight changes without code modifications. See [Unified Score Architecture](../../technical/scoring-algebra.md) §4 for manifest schema and versioning rules.
### 3.2 - License compliance configuration
License compliance evaluation runs during SBOM evaluation when enabled in
@@ -856,4 +860,141 @@ The following product advisories provide strategic context for Policy Engine fea
---
*Last updated: 2025-12-26 (Sprint 006).*
## 13 · Policy Interop Layer
> **Sprint:** SPRINT_20260122_041_Policy_interop_import_export_rego
The Interop Layer provides bidirectional policy exchange between Stella's native C# gate engine and OPA/Rego. The C# engine remains primary; Rego serves as an interoperability adapter for teams using OPA-based toolchains.
### 13.1 · Supported Formats
| Format | Schema | Direction | Notes |
|--------|--------|-----------|-------|
| **PolicyPack v2 (JSON)** | `policy.stellaops.io/v2` | Import + Export | Canonical format with typed gates, environment overrides, remediation hints |
| **OPA/Rego** | `package stella.release` | Export (+ Import with pattern matching) | Deny-by-default pattern, `remediation` output rules |
### 13.2 · Architecture
```mermaid
graph TD
subgraph Interop["StellaOps.Policy.Interop"]
Exporter[JsonPolicyExporter / RegoPolicyExporter]
Importer[JsonPolicyImporter / RegoPolicyImporter]
Validator[PolicySchemaValidator]
Generator[RegoCodeGenerator]
Resolver[RemediationResolver]
OPA[EmbeddedOpaEvaluator]
Detector[FormatDetector]
end
subgraph Consumers
CLI[stella policy export/import/validate/evaluate]
API[Platform API /api/v1/policy/interop]
UI[Policy Editor UI]
end
CLI --> Exporter
CLI --> Importer
CLI --> Validator
API --> Exporter
API --> Importer
API --> Validator
UI --> API
Exporter --> Generator
Exporter --> Resolver
Importer --> Detector
Importer --> OPA
Generator --> Resolver
```
### 13.3 · Gate-to-Rego Translation
Each C# gate type maps to a Rego deny rule pattern:
| 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` |
### 13.4 · Remediation Hints
When a gate blocks, the system resolves structured remediation hints:
```
Priority: Gate-defined hint > Built-in defaults > null
RemediationHint:
Code: Machine-readable (e.g., "CVSS_EXCEED")
Title: Human-readable summary
Actions[]: CLI command templates with {placeholders}
References: External documentation links
Severity: critical | high | medium | low
```
Placeholders (`{purl}`, `{image}`, `{reason}`) are resolved via `RemediationContext` at evaluation time.
### 13.5 · Determinism
All exports and evaluations are deterministic:
- Same policy + same input = same output (hash-verifiable)
- Exports include SHA-256 `digest` field
- No time-dependent logic in deterministic mode
- `outputDigest` in evaluation results enables replay verification
### 13.6 · Implementation Reference
| Component | Source File |
|-----------|-------------|
| Contracts | `src/Policy/__Libraries/StellaOps.Policy.Interop/Contracts/PolicyPackDocument.cs` |
| Remediation Models | `src/Policy/__Libraries/StellaOps.Policy.Interop/Contracts/RemediationModels.cs` |
| Interfaces | `src/Policy/__Libraries/StellaOps.Policy.Interop/Abstractions/` |
| JSON Exporter | `src/Policy/__Libraries/StellaOps.Policy.Interop/Export/JsonPolicyExporter.cs` |
| JSON Importer | `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/JsonPolicyImporter.cs` |
| Rego Generator | `src/Policy/__Libraries/StellaOps.Policy.Interop/Rego/RegoCodeGenerator.cs` |
| Rego Importer | `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/RegoPolicyImporter.cs` |
| Embedded OPA | `src/Policy/__Libraries/StellaOps.Policy.Interop/Evaluation/EmbeddedOpaEvaluator.cs` |
| Remediation Resolver | `src/Policy/__Libraries/StellaOps.Policy.Interop/Evaluation/RemediationResolver.cs` |
| Format Detector | `src/Policy/__Libraries/StellaOps.Policy.Interop/Import/FormatDetector.cs` |
| Schema Validator | `src/Policy/__Libraries/StellaOps.Policy.Interop/Validation/PolicySchemaValidator.cs` |
| CLI Commands | `src/Cli/StellaOps.Cli/Commands/Policy/PolicyInteropCommandGroup.cs` |
| Platform API | `src/Platform/StellaOps.Platform.WebService/Endpoints/PolicyInteropEndpoints.cs` |
| JSON Schema | `docs/schemas/policy-pack-v2.schema.json` |
### 13.7 · CLI Interface
```bash
# Export to Rego
stella policy export --file policy.json --format rego --output-file release.rego
# Import with validation
stella policy import --file external.rego --validate-only
# Validate policy document
stella policy validate --file policy.json --strict
# Evaluate with remediation hints
stella policy evaluate --policy baseline.json --input evidence.json --environment production
```
Exit codes: `0` = success/allow, `1` = warn, `2` = block/errors, `10` = input-error, `12` = policy-error.
### 13.8 · Platform API
Group: `/api/v1/policy/interop` with tag `PolicyInterop`
| Method | Path | Auth Policy | Description |
|--------|------|-------------|-------------|
| POST | `/export` | `platform.policy.read` | Export policy to format |
| POST | `/import` | `platform.policy.write` | Import policy from format |
| POST | `/validate` | `platform.policy.read` | Validate policy document |
| POST | `/evaluate` | `platform.policy.evaluate` | Evaluate policy against input |
| GET | `/formats` | `platform.policy.read` | List supported formats |
---
*Last updated: 2026-01-23 (Sprint 041).*

219
docs/modules/policy/guides/policy-import-export.md Normal file
View 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` |