# VEX Gate Configuration for Scanner
# Copy to etc/scanner.yaml and customize for your deployment
#
# VEX Gate filters findings before they reach triage, reducing noise by
# applying VEX statements and configurable policies. Gate decisions:
#   - Pass: Finding cleared by VEX evidence, no action needed
#   - Warn: Finding has partial evidence, proceed with caution
#   - Block: Finding requires attention, exploitable and reachable

vexGate:
  # Enable VEX-first gating (default: false)
  # When disabled, all findings pass through to triage unchanged
  enabled: true

  # Default decision when no rules match (default: Warn)
  # Options: Pass, Warn, Block
  # Conservative default is Warn to avoid blocking legitimate alerts
  defaultDecision: Warn

  # Policy version for audit/replay purposes
  # Should be incremented when rules change
  policyVersion: "1.0.0"

  # Evaluation rules (ordered by priority, highest first)
  # Each rule has: ruleId, priority, condition, decision
  rules:
    # Rule: Block exploitable AND reachable findings without compensating controls
    # This is the highest priority rule - these findings require immediate attention
    - ruleId: "block-exploitable-reachable"
      priority: 100
      condition:
        isExploitable: true
        isReachable: true
        hasCompensatingControl: false
      decision: Block

    # Rule: Warn for high/critical severity but not reachable
    # These findings may need attention but are lower risk if not reachable
    - ruleId: "warn-high-not-reachable"
      priority: 90
      condition:
        severityLevels:
          - critical
          - high
        isReachable: false
      decision: Warn

    # Rule: Pass vendor-declared not-affected
    # Vendor VEX statements saying component is not affected are authoritative
    - ruleId: "pass-vendor-not-affected"
      priority: 80
      condition:
        vendorStatus: not_affected
      decision: Pass

    # Rule: Pass backport-confirmed fixes
    # When vendor declares fixed and we have backport evidence
    - ruleId: "pass-backport-confirmed"
      priority: 70
      condition:
        vendorStatus: fixed
        # Backport evidence is implied by fixed status with justification
      decision: Pass

    # Rule: Pass when compensating controls are in place
    # Even if exploitable, compensating controls reduce risk
    - ruleId: "pass-compensating-control"
      priority: 60
      condition:
        hasCompensatingControl: true
      decision: Pass

    # Rule: Warn for KEV entries regardless of other factors
    # Known Exploited Vulnerabilities always warrant attention
    - ruleId: "warn-kev-entry"
      priority: 50
      condition:
        isKnownExploited: true
      decision: Warn

  # Caching settings for VEX observation lookups
  cache:
    # TTL for cached VEX observations (seconds)
    # Shorter TTL means fresher data but more lookups
    ttlSeconds: 300

    # Maximum cache entries
    # Memory usage: ~1KB per entry, 10000 entries = ~10MB
    maxEntries: 10000

  # Audit logging settings
  audit:
    # Enable structured audit logging for compliance
    enabled: true

    # Include full evidence in audit logs (increases log size)
    includeEvidence: true

    # Log level for gate decisions
    # Options: Information, Warning, Debug
    logLevel: Information

  # Metrics settings
  metrics:
    # Enable OpenTelemetry metrics for gate operations
    enabled: true

    # Histogram buckets for evaluation latency (milliseconds)
    latencyBuckets:
      - 1
      - 5
      - 10
      - 25
      - 50
      - 100
      - 250

  # Bypass settings for emergency scans
  bypass:
    # Allow gate bypass via CLI flag (--bypass-gate)
    # Default: true
    allowCliBypass: true

    # Require specific reason when bypassing
    # Default: false
    requireReason: false

    # Emit warning when bypass is used
    # Default: true
    warnOnBypass: true

# Tenant-specific overrides (optional)
# Each tenant can customize rules, thresholds, and default decisions
# tenantOverrides:
#   tenant-high-security:
#     defaultDecision: Block
#     rules:
#       - ruleId: "block-exploitable-reachable"
#         priority: 100
#         condition:
#           isExploitable: true
#           isReachable: true
#           hasCompensatingControl: false
#         decision: Block
#       # Additional stricter rules...
#
#   tenant-permissive:
#     defaultDecision: Pass
#     rules:
#       - ruleId: "block-critical-exploitable"
#         priority: 100
#         condition:
#           severityLevels:
#             - critical
#           isExploitable: true
#         decision: Block

# Example: Minimal configuration (enabled with defaults)
# vexGate:
#   enabled: true

# Example: Strict configuration (high-assurance environments)
# vexGate:
#   enabled: true
#   defaultDecision: Block
#   policyVersion: "1.0.0-strict"
#   rules:
#     - ruleId: "pass-vendor-not-affected"
#       priority: 100
#       condition:
#         vendorStatus: not_affected
#         confidenceThreshold: 0.9
#       decision: Pass
#     - ruleId: "block-everything-else"
#       priority: 1
#       condition: {}  # Empty condition matches all
#       decision: Block

# Example: Permissive configuration (development environments)
# vexGate:
#   enabled: true
#   defaultDecision: Pass
#   policyVersion: "1.0.0-dev"
#   rules:
#     - ruleId: "block-kev-critical"
#       priority: 100
#       condition:
#         isKnownExploited: true
#         severityLevels:
#           - critical
#       decision: Block