# Thuban Shield — Rule Pack Schema
#
# Defines the shape of a signed, versioned rule pack that Shield loads at
# runtime (in addition to its hardcoded checks). Rule packs are DATA, not
# CODE — this is what lets Shield ship new threat coverage as a pushed
# YAML file instead of a code release.
#
# This file is documentation-as-schema: packages/shield/rule-pack-loader.js
# validates loaded rule packs against the shape described here by hand
# (no external JSON-Schema/YAML-Schema library dependency — consistent
# with the rest of Shield, which is zero-external-dependency by design).
#
# Top-level shape
# ----------------
# pack:
#   id: string                          # e.g. "hermes-2026-07"
#   version: string (semver)            # e.g. "1.0.0"
#   created: string (ISO8601)           # e.g. "2026-07-28T00:00:00Z"
#   provenance:
#     sources: array<enum>              # see PROVENANCE_SOURCES below
#     incident_refs: array<string>      # e.g. ["INC-2026-0714-HERMES"]
#   minimum_engine_version: string (semver)  # min Shield version required
#   rules: array<rule>                  # see rule shape below
#   signature: string (hex)             # detached signature over the
#                                        # canonicalized pack content.
#                                        # STUB in this version — presence
#                                        # is checked, not cryptographically
#                                        # verified. See rule-pack-loader.js.
#
# Enums
# -----
# PROVENANCE_SOURCES:
#   - vendor_advisory
#   - reproduced_in_crucible
#   - security_research
#   - incident_report
#   - internal_research
#
# SEVERITY:
#   - low
#   - medium
#   - high
#   - critical
#
# RESPONSE_LEVEL:
#   - observe   # log only, never blocks
#   - warn      # surfaced as a warning, does not block by default
#   - block     # blocks the action
#
# RULE_TYPE:
#   - single    # evaluated against one action event at a time
#   - sequence  # evaluated against an ordered series of action events
#               # within a time window (see SequenceDetector, future work)
#
# Rule shape (common fields, all rule types)
# -------------------------------------------
# id: string                            # e.g. "THREAT-2026-001"
# severity: enum (SEVERITY)
# name: string                          # short human-readable name
# description: string                   # what this rule detects and why
# response_level: enum (RESPONSE_LEVEL)
# type: enum (RULE_TYPE)
#
# Rule shape — type: single
# ---------------------------
# conditions:
#   action_type: string                 # e.g. "WRITE", "EXECUTE", "READ",
#                                        # "NETWORK_CONNECT", "PROCESS_SPAWN"
#   target_pattern: string (glob)       # glob matched against the action's
#                                        # target (file path, command, host)
#   context: object                     # optional extra requirements,
#                                        # e.g. { requires_prior_action: "..." }
#
# Rule shape — type: sequence
# -----------------------------
# sequence: array<step>                 # ordered steps, each:
#   - action_type: string
#     conditions: object                # e.g. { target_pattern: "*.env" }
# window_seconds: integer                # max time span for the full
#                                        # sequence to be considered a match
# action: enum [block, warn, isolate, block_and_isolate]
#
# Example (single rule)
# ----------------------
# - id: THREAT-2026-001
#   severity: high
#   name: Suspicious credential path access
#   description: Flags direct reads of well-known credential file paths.
#   response_level: block
#   type: single
#   conditions:
#     action_type: READ
#     target_pattern: "**/.ssh/id_rsa"
#
# Example (sequence rule)
# --------------------------
# - id: THREAT-2026-002
#   severity: critical
#   name: Credential exfiltration chain
#   description: >
#     Credential file read followed by an outbound network connection
#     within a short window — the shape of a harvest-then-exfiltrate step.
#   response_level: block
#   type: sequence
#   sequence:
#     - action_type: READ
#       conditions:
#         target_pattern: "**/.env"
#     - action_type: NETWORK_CONNECT
#       conditions: {}
#   window_seconds: 30
#   action: block_and_isolate