# Stella Ops Starter Policy Pack - Day 1
# Version: 1.0.0
# Last Updated: 2025-12-22
#
# This policy provides sensible defaults for organizations beginning
# their software supply chain security journey. Customize as needed.
#
# Key principles:
# - Block reachable HIGH/CRITICAL vulnerabilities without VEX
# - Allow bypass only with evidence-based VEX justification
# - Enforce unknowns budget to maintain scan quality
# - Require signed artifacts for production deployments

apiVersion: policy.stellaops.io/v1
kind: PolicyPack
metadata:
  name: starter-day1
  version: "1.0.0"
  description: "Production-ready starter policy for Day 1 adoption"
  labels:
    tier: starter
    environment: all
    recommended: "true"
  annotations:
    stellaops.io/maintainer: "policy-team@stellaops.io"
    stellaops.io/docs: "https://docs.stellaops.io/policy/starter-guide"

spec:
  # Global settings - can be overridden per environment
  settings:
    # Default action for unmatched findings: warn | block | allow
    defaultAction: warn

    # Maximum percentage of packages with unknown metadata
    # Before blocking deployment (5% = conservative default)
    unknownsThreshold: 0.05

    # Require cryptographically signed SBOM for production
    requireSignedSbom: true

    # Require cryptographically signed policy verdict
    requireSignedVerdict: true

    # Trust score threshold for VEX acceptance (0.0-1.0)
    minimumVexTrustScore: 0.5

  # Rule evaluation order: first match wins
  rules:
    # =========================================================================
    # Rule 1: Block reachable HIGH/CRITICAL vulnerabilities
    # =========================================================================
    # This is the core security gate. Deployments with reachable HIGH or
    # CRITICAL severity vulnerabilities are blocked unless VEX justifies.
    - name: block-reachable-high-critical
      description: "Block deployments with reachable HIGH or CRITICAL vulnerabilities"
      priority: 100
      match:
        severity:
          - CRITICAL
          - HIGH
        reachability: reachable
      unless:
        # Allow if VEX says not_affected with valid justification
        vexStatus: not_affected
        vexJustification:
          - vulnerable_code_not_present
          - vulnerable_code_cannot_be_controlled_by_adversary
          - inline_mitigations_already_exist
        # Require minimum trust score for VEX source
        vexTrustScore:
          gte: ${settings.minimumVexTrustScore}
      action: block
      message: |
        Reachable {severity} vulnerability {cve} in {package} must be remediated.
        Options:
        - Upgrade to a fixed version
        - Provide VEX justification (not_affected with evidence)
        - Request exception through governance process

    # =========================================================================
    # Rule 2: Warn on reachable MEDIUM vulnerabilities
    # =========================================================================
    # Medium severity findings are not blocking but should be tracked.
    - name: warn-reachable-medium
      description: "Warn on reachable MEDIUM severity vulnerabilities"
      priority: 90
      match:
        severity: MEDIUM
        reachability: reachable
      unless:
        vexStatus: not_affected
      action: warn
      message: "Reachable MEDIUM vulnerability {cve} in {package} should be reviewed"

    # =========================================================================
    # Rule 3: Allow unreachable vulnerabilities
    # =========================================================================
    # Unreachable vulnerabilities pose lower risk and are allowed, but logged.
    - name: allow-unreachable
      description: "Allow unreachable vulnerabilities but log for awareness"
      priority: 80
      match:
        reachability: unreachable
      action: allow
      log: true
      message: "Vulnerability {cve} is unreachable in {package} - allowing"

    # =========================================================================
    # Rule 4: Fail on excessive unknowns
    # =========================================================================
    # Too many packages with unknown metadata indicates scan quality issues.
    - name: fail-on-unknowns
      description: "Block if too many packages have unknown metadata"
      priority: 200
      type: aggregate  # Applies to entire scan, not individual findings
      match:
        unknownsRatio:
          gt: ${settings.unknownsThreshold}
      action: block
      message: |
        Unknown packages exceed threshold: {unknownsRatio}% > {threshold}%.
        Improve SBOM quality or adjust threshold in policy settings.

    # =========================================================================
    # Rule 5: Require signed SBOM for production
    # =========================================================================
    - name: require-signed-sbom-prod
      description: "Production deployments must have signed SBOM"
      priority: 300
      match:
        environment: production
      require:
        signedSbom: ${settings.requireSignedSbom}
      action: block
      message: "Production deployment requires cryptographically signed SBOM"

    # =========================================================================
    # Rule 6: Require signed verdict for production
    # =========================================================================
    - name: require-signed-verdict-prod
      description: "Production deployments must have signed policy verdict"
      priority: 300
      match:
        environment: production
      require:
        signedVerdict: ${settings.requireSignedVerdict}
      action: block
      message: "Production deployment requires signed policy verdict"

    # =========================================================================
    # Rule 7: Block on KEV (Known Exploited Vulnerabilities)
    # =========================================================================
    # CISA KEV vulnerabilities are actively exploited and should be prioritized.
    - name: block-kev
      description: "Block deployments with CISA KEV vulnerabilities"
      priority: 110
      match:
        kev: true
        reachability: reachable
      unless:
        vexStatus: not_affected
      action: block
      message: |
        {cve} is in CISA Known Exploited Vulnerabilities catalog.
        Active exploitation detected - immediate remediation required.

    # =========================================================================
    # Rule 8: Warn on dependencies with no security contact
    # =========================================================================
    - name: warn-no-security-contact
      description: "Warn when critical dependencies have no security contact"
      priority: 50
      match:
        isDirect: true
        hasSecurityContact: false
        severity:
          - CRITICAL
          - HIGH
      action: warn
      message: "Package {package} has no security contact - coordinated disclosure may be difficult"

    # =========================================================================
    # Rule 9: Default allow for everything else
    # =========================================================================
    - name: default-allow
      description: "Allow everything not matched by above rules"
      priority: 0
      match:
        always: true
      action: allow