git.stella-ops.org/etc/policy.poe.yaml.sample

# StellaOps Proof of Exposure (PoE) Policy Configuration
#
# This file configures policy gates for validating Proof of Exposure artifacts.
# PoE artifacts provide compact, offline-verifiable proof of vulnerability reachability
# at the function level with signed DSSE attestations.
#
# Documentation: docs/modules/policy/poe-policy-gates.md
# Schema: src/Policy/StellaOps.Policy.Engine/ProofOfExposure/PoEPolicyModels.cs

# ====================================
# Example 1: Minimal (Development)
# ====================================
# Minimal configuration for development environments.
# PoE is optional, warnings only.

poe_policy_minimal:
  require_poe_for_reachable: false
  require_signed_poe: false
  require_rekor_timestamp: false
  on_validation_failure: warn
  max_poe_age_days: 90
  reject_stale_poe: false

# ====================================
# Example 2: Standard (Production)
# ====================================
# Standard configuration for production environments.
# Requires PoE for reachable vulnerabilities with DSSE signatures.

poe_policy_standard:
  require_poe_for_reachable: true
  require_signed_poe: true
  require_rekor_timestamp: false
  min_edge_confidence: 0.7
  allow_guarded_paths: true
  trusted_key_ids:
    - scanner-signing-2025
    - scanner-signing-2025-backup
  max_poe_age_days: 90
  reject_stale_poe: false
  require_build_id_match: true
  require_policy_digest_match: false
  on_validation_failure: warn

# ====================================
# Example 3: Strict (Critical Systems)
# ====================================
# Strict configuration for critical systems (finance, healthcare, defense).
# Requires PoE with Rekor timestamps and rejects failures.

poe_policy_strict:
  require_poe_for_reachable: true
  require_signed_poe: true
  require_rekor_timestamp: true
  min_paths: 1
  max_path_depth: 15
  min_edge_confidence: 0.85
  allow_guarded_paths: false
  trusted_key_ids:
    - scanner-signing-2025
  max_poe_age_days: 30
  reject_stale_poe: true
  require_build_id_match: true
  require_policy_digest_match: true
  on_validation_failure: reject

# ====================================
# Example 4: Custom
# ====================================
# Custom configuration with specific requirements.

poe_policy_custom:
  # Require PoE for all reachable vulnerabilities
  require_poe_for_reachable: true

  # DSSE signature is mandatory
  require_signed_poe: true

  # Rekor transparency log timestamp required for audit compliance
  require_rekor_timestamp: true

  # Subgraph constraints
  min_paths: 1                    # At least one path to vulnerable code
  max_path_depth: 20              # Maximum call depth in path
  min_edge_confidence: 0.75       # Minimum confidence for edges (0.0-1.0)

  # Allow paths with feature flag guards (e.g., if (FeatureFlags.Beta))
  allow_guarded_paths: true

  # Trusted signing key IDs for DSSE verification
  trusted_key_ids:
    - scanner-signing-2025
    - scanner-signing-2025-backup

  # PoE age constraints
  max_poe_age_days: 60            # PoE must be refreshed every 60 days
  reject_stale_poe: false         # Warn but don't reject stale PoE

  # Build reproducibility
  require_build_id_match: true    # PoE build ID must match scan build ID

  # Policy versioning
  require_policy_digest_match: false  # Allow PoE from previous policy versions

  # Action on validation failure
  # Options: warn, reject, downgrade, review
  on_validation_failure: downgrade

# ====================================
# Integration with Policy Engine
# ====================================
# Use PoE policy configuration in policy evaluation rules.
#
# Example OPA/Rego policy:
#
# package stellaops.policy
#
# import data.poe_policy_standard as poe_config
#
# violation[msg] {
#   finding := input.findings[_]
#   finding.is_reachable == true
#   not finding.poe_validation.is_valid
#   poe_config.require_poe_for_reachable == true
#   msg := sprintf("Reachable vulnerability %s missing valid PoE", [finding.vuln_id])
# }
#
# severity_adjustment[adjusted] {
#   finding := input.findings[_]
#   not finding.poe_validation.is_valid
#   poe_config.on_validation_failure == "downgrade"
#   adjusted := {
#     "finding_id": finding.finding_id,
#     "original_severity": finding.severity,
#     "adjusted_severity": downgrade_severity(finding.severity)
#   }
# }
#
# downgrade_severity(severity) = "High" {
#   severity == "Critical"
# }
#
# downgrade_severity(severity) = "Medium" {
#   severity == "High"
# }
#
# downgrade_severity(severity) = "Low" {
#   severity == "Medium"
# }
#
# downgrade_severity(severity) = severity {
#   severity != "Critical"
#   severity != "High"
#   severity != "Medium"
# }

# ====================================
# Field Descriptions
# ====================================
#
# require_poe_for_reachable: (boolean)
#   Whether PoE is mandatory for vulnerabilities marked as reachable.
#   Default: false
#
# require_signed_poe: (boolean)
#   Whether PoE must be cryptographically signed with DSSE.
#   Default: true
#
# require_rekor_timestamp: (boolean)
#   Whether PoE signatures must be timestamped in Rekor transparency log.
#   Default: false
#
# min_paths: (integer, optional)
#   Minimum number of paths required in PoE subgraph.
#   Null means no minimum.
#
# max_path_depth: (integer, optional)
#   Maximum allowed path depth in PoE subgraph.
#   Null means no maximum.
#
# min_edge_confidence: (decimal, 0.0-1.0)
#   Minimum confidence threshold for PoE edges.
#   Default: 0.7
#
# allow_guarded_paths: (boolean)
#   Whether to allow PoE with feature flag guards.
#   Default: true
#
# trusted_key_ids: (array of strings)
#   List of trusted key IDs for DSSE signature verification.
#   Example: ["scanner-signing-2025"]
#
# max_poe_age_days: (integer)
#   Maximum age of PoE artifacts before they're considered stale.
#   Default: 90
#
# reject_stale_poe: (boolean)
#   Whether to reject findings with stale PoE.
#   Default: false
#
# require_build_id_match: (boolean)
#   Whether PoE build ID must match scan build ID.
#   Default: true
#
# require_policy_digest_match: (boolean)
#   Whether PoE policy digest must match current policy.
#   Default: false
#
# on_validation_failure: (enum)
#   Action to take when PoE validation fails.
#   Options:
#     - warn:      Allow the finding but add a warning
#     - reject:    Reject the finding (treat as policy violation)
#     - downgrade: Downgrade severity of the finding
#     - review:    Mark the finding for manual review
#   Default: warn

# ====================================
# Related Configuration
# ====================================
# - Scanner PoE emission: etc/scanner.poe.yaml.sample
# - Signing keys: etc/keys/scanner-signing-2025.key.json.sample
# - Public keys: etc/keys/scanner-signing-2025.pub.json.sample
# - CLI export: stella poe export --help
# - CLI verify: stella poe verify --help