stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 2 Releases Wiki Activity
Files
5d5f4de2e18f411dfd530c95da09759249d5f8f2
git.stella-ops.org/docs/features/checked/policy/policy-interop-framework.md
master 9ca2de05df more features checks. setup improvements
2026-02-13 02:04:55 +02:00

4.6 KiB
Raw Blame History

Policy Interop Framework (JSON Export/Import)

Module

Policy

Status

IMPLEMENTED

Description

Policy interoperability framework enabling bidirectional JSON export/import of policy rules. OPA/Rego export was planned but only JSON export confirmed in source. Includes PolicyPack document format for portable policy bundles. Full interop library exists with JSON import/export, Rego code generation, and schema validation.

What's Implemented

  • JsonPolicyExporter: src/Policy/__Libraries/StellaOps.Policy.Interop/Export/JsonPolicyExporter.cs
    • ExportToJsonAsync(PolicyPackDocument, PolicyExportRequest): canonical JSON export with deterministic output
    • Environment filtering: merges environment-specific config into base config
    • Remediation stripping option
    • Content-addressed digest: sha256:{hex} via SHA256 of canonical JSON
    • ExportToRegoAsync(): bridges to RegoCodeGenerator
    • SerializeCanonical() / SerializeToString() static helpers
  • JsonPolicyImporter: src/Policy/__Libraries/StellaOps.Policy.Interop/Import/JsonPolicyImporter.cs
    • ImportAsync(Stream, PolicyImportOptions) / ImportFromStringAsync()
    • Format detection via FormatDetector (auto-detect JSON vs Rego)
    • API version validation: policy.stellaops.io/v2 (with v1 compatibility adapter warning)
    • Kind validation: PolicyPack or PolicyOverride
    • Structural validation: duplicate gate IDs, duplicate rule names
    • Remediation hint validation (code, actions)
    • Diagnostic codes: FORMAT_UNKNOWN, REGO_USE_IMPORTER, JSON_PARSE_ERROR, VERSION_UNKNOWN, KIND_INVALID, GATE_ID_DUPLICATE, RULE_NAME_DUPLICATE
    • PolicyImportResult with Success, Document, DetectedFormat, Diagnostics, GateCount, RuleCount
  • RegoCodeGenerator: src/Policy/__Libraries/StellaOps.Policy.Interop/Rego/RegoCodeGenerator.cs
    • Generates OPA Rego deny rules from PolicyPackDocument
    • Gate type mappings: CvssThreshold, SignatureRequired, EvidenceFreshness, SbomPresence, MinimumConfidence, UnknownsBudget, ReachabilityRequirement
    • Rego v1 syntax support (import rego.v1)
    • Environment-specific config extraction
    • Remediation hints as structured output rules
    • Content-addressed digest of generated Rego source
    • Warning collection for unmapped gate types
  • RegoPolicyImporter: src/Policy/__Libraries/StellaOps.Policy.Interop/Import/RegoPolicyImporter.cs
    • Imports Rego source back into PolicyPackDocument
  • FormatDetector: src/Policy/__Libraries/StellaOps.Policy.Interop/Import/FormatDetector.cs
    • Auto-detects policy format (JSON, Rego)
  • PolicyPack v2 schema: src/Policy/__Libraries/StellaOps.Policy.Interop/Schemas/policy-pack-v2.schema.json
  • Abstractions: src/Policy/__Libraries/StellaOps.Policy.Interop/Abstractions/
    • IPolicyExporter, IPolicyImporter, IRegoCodeGenerator interfaces
  • Contracts: src/Policy/__Libraries/StellaOps.Policy.Interop/Contracts/
    • PolicyPackDocument, PolicyExportRequest, PolicyImportOptions, RegoGenerationOptions, RegoExportResult, PolicyDiagnostic
  • DI registration: src/Policy/__Libraries/StellaOps.Policy.Interop/DependencyInjection/PolicyInteropServiceCollectionExtensions.cs
  • Evaluation: src/Policy/__Libraries/StellaOps.Policy.Interop/Evaluation/
  • Tests: src/Policy/__Libraries/__Tests/StellaOps.Policy.Interop.Tests/
    • JsonPolicyExporterTests, JsonPolicyImporterTests, RegoPolicyImporterTests, RegoCodeGeneratorTests, FormatDetectorTests, PolicySchemaValidatorTests
    • Golden file: Fixtures/golden-policy-pack-v2.json

What's Missing

  • YAML import/export: Only JSON and Rego formats are supported; no YAML PolicyPack format
  • Policy diff/merge: No tool to diff two PolicyPackDocuments and produce a delta or merge two packs
  • CLI integration: No stella policy export --format rego or stella policy import CLI commands wrapping the interop library
  • Round-trip validation: No automated tests proving JSON -> Rego -> JSON round-trip produces identical PolicyPackDocument
  • OPA evaluation bridge: Rego code is generated but there is no OPA evaluation service that runs the generated Rego against actual inputs

Implementation Plan

  • Add CLI commands wrapping export/import operations
  • Build round-trip test suite (JSON -> Rego -> JSON identity check)
  • Consider YAML format support using existing ScorePolicyLoader YAML infrastructure
  • Add policy diff/merge utility for comparing policy versions

Related Documentation

  • Interop library: src/Policy/__Libraries/StellaOps.Policy.Interop/ (6 subdirectories)
  • Interop tests: src/Policy/__Libraries/__Tests/StellaOps.Policy.Interop.Tests/
  • Policy registry: src/Policy/StellaOps.Policy.Registry/