pen-stack 0.1.0__py3-none-any.whl

pen_stack/safety/audit.py

@@ -0,0 +1,90 @@
+"""Append-only, hash-chained safety audit log, the Guardian.
+
+Every safety decision is recorded as a JSON line whose hash chains to the previous record, so the log is
+tamper-evident: altering any past record breaks the chain from that point forward (`verify_chain`). The log
+stores a design DIGEST (sha256), not the design itself, it is an accountability trail, not a hazard store.
+
+Path resolution: `PEN_STACK_SAFETY_AUDIT` env var, else `<project_root>/out/safety_audit.log`.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from pen_stack._resources import project_root
+
+_GENESIS = "0" * 64
+
+
+def audit_path() -> Path:
+    env = os.environ.get("PEN_STACK_SAFETY_AUDIT")
+    if env:
+        return Path(env).expanduser()
+    return project_root() / "out" / "safety_audit.log"
+
+
+def _digest(payload: Any) -> str:
+    return hashlib.sha256(json.dumps(payload, sort_keys=True, default=str).encode("utf-8")).hexdigest()
+
+
+def _last_hash(path: Path) -> str:
+    if not path.exists():
+        return _GENESIS
+    last = _GENESIS
+    for line in path.read_text(encoding="utf-8").splitlines():
+        if line.strip():
+            try:
+                last = json.loads(line)["this_hash"]
+            except (json.JSONDecodeError, KeyError):
+                continue
+    return last
+
+
+def audit_log(*, actor: str, design_digest: str, verdict, path: Path | None = None) -> dict:
+    """Append one hash-chained record for a SafetyVerdict. Returns the written record."""
+    p = path or audit_path()
+    p.parent.mkdir(parents=True, exist_ok=True)
+    prev = _last_hash(p)
+    body = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "actor": actor,
+        "design_digest": design_digest,
+        "decision": verdict.decision,
+        "reason": verdict.reason,
+        "n_hits": len(verdict.hits),
+        "hit_ids": [h.provenance.get("signature_id") for h in verdict.hits],
+        "registry_version": next((h.provenance.get("registry_version") for h in verdict.hits), None),
+        "prev_hash": prev,
+    }
+    record = {**body, "this_hash": _digest({**body})}
+    with p.open("a", encoding="utf-8", newline="\n") as fh:
+        fh.write(json.dumps(record, sort_keys=True) + "\n")
+    return record
+
+
+def verify_chain(path: Path | None = None) -> dict:
+    """Verify the hash chain is intact (tamper-evident). Returns {ok, n, broken_at}."""
+    p = path or audit_path()
+    if not p.exists():
+        return {"ok": True, "n": 0, "broken_at": None, "reason": "no log yet"}
+    prev = _GENESIS
+    n = 0
+    for i, line in enumerate(p.read_text(encoding="utf-8").splitlines()):
+        if not line.strip():
+            continue
+        rec = json.loads(line)
+        body = {k: rec[k] for k in rec if k != "this_hash"}
+        if rec.get("prev_hash") != prev or _digest(body) != rec.get("this_hash"):
+            return {"ok": False, "n": n, "broken_at": i, "reason": "hash chain broken"}
+        prev = rec["this_hash"]
+        n += 1
+    return {"ok": True, "n": n, "broken_at": None}
+
+
+def digest_design(design: dict) -> str:
+    """Stable digest of a design for the audit trail (does not store the design itself)."""
+    return _digest(design)

pen_stack/safety/gate.py

@@ -0,0 +1,58 @@
+"""The safety gate, screen -> decide -> audit, the Guardian's single entry point.
+
+`safety_gate(design)` returns a `SafetyVerdict` (clear / flag / refuse / escalate) and writes a hash-chained
+audit record. It screens the DESIGN ARTIFACT only, framing/justification fields are stripped first, so
+re-framing a hazardous design as "defensive research" cannot flip a refuse to a clear (the artifact decides,
+not the prompt). No number is fabricated: every hit is sourced from the version-pinned registry.
+"""
+from __future__ import annotations
+
+from pen_stack.safety.audit import audit_log, digest_design
+from pen_stack.safety.policy import SafetyVerdict, decide, load_policy
+from pen_stack.safety.screen import screen_design
+
+
+def _strip_framing(design: dict, policy: dict) -> dict:
+    """Remove free-text framing fields the screen must ignore (the artifact decides, not the wording)."""
+    drop = set(policy.get("ignore_framing_fields", []))
+    return {k: v for k, v in design.items() if k not in drop}
+
+
+_SIGNAL_TEXT_FIELDS = ("cargo_function", "function_annotation", "goal_function", "source_taxon", "organism",
+                       "host_taxon", "cargo_seq", "cargo_sequence")
+_SIGNAL_LIST_FIELDS = ("function_tags", "pfam_domains", "annotations")
+
+
+def _has_declared_signal(design: dict) -> bool:
+    """Whether the artifact carries anything the hazard screens actually read (declared function, domain
+    tags, taxon, OR a cargo sequence -- a real Pfam/HMMER scan runs over cargo_seq by default, so a
+    sequence-only submission is genuinely screened, not skipped). Lets a "clear" tell "genuinely screened, no
+    hazard found" apart from "nothing was submitted, so nothing could be checked" -- otherwise an empty
+    Cargo function box reads exactly like a real benign design was cleared."""
+    if any(str(design.get(k) or "").strip() for k in _SIGNAL_TEXT_FIELDS):
+        return True
+    return any((design.get(k) or []) for k in _SIGNAL_LIST_FIELDS)
+
+
+def safety_gate(design: dict, *, actor: str = "anonymous", registry=None) -> SafetyVerdict:
+    """Screen a design, decide, and log a tamper-evident audit record. The design digest is taken over the
+    ORIGINAL design (full accountability), while screening runs on the framing-stripped artifact."""
+    if not isinstance(design, dict):
+        design = dict(design)
+    policy = load_policy()
+    artifact = _strip_framing(design, policy)
+    hits = screen_design(artifact, registry=registry)
+    decision, reason = decide(hits, policy)
+    signal = _has_declared_signal(artifact)
+    if decision == "clear" and not signal:
+        reason = ("no cargo function, sequence, domain tag, or taxon was declared, nothing was screened "
+                   "(not a clearance)")
+    verdict = SafetyVerdict(
+        decision=decision, hits=hits, reason=reason,
+        provenance={"registry_version": next((h.provenance.get("registry_version") for h in hits), None),
+                    "policy_version": policy.get("policy_version"), "actor": actor,
+                    "screened_kinds": sorted({h.kind for h in hits}),
+                    "declared_signal": signal,
+                    "note": "screening reduces, not eliminates, dual-use risk; not a substitute for IBC review"})
+    audit_log(actor=actor, design_digest=digest_design(design), verdict=verdict)
+    return verdict

pen_stack/safety/pfam_scan.py

@@ -0,0 +1,157 @@
+"""Local Pfam/HMMER domain screen over a raw cargo sequence.
+
+Wires the sequence-homology slot the Guardian has always had (`HazardRegistry`'s `external_hook`), using
+PUBLIC Pfam profile HMMs for the SAME curated toxin families already listed in
+`configs/safety/hazard_registry.yaml`. No hazard sequences are bundled -- only statistical family models (the
+same class of public artifact the registry's own accessions already reference; a profile HMM is built from
+many aligned public sequences, it is not any one organism's sequence). A DNA/RNA cargo_seq is translated in
+all 6 reading frames (protein cargo is scanned directly) and scored against the bundled HMM file using each
+profile's own Pfam-recommended gathering (GA) cutoff -- the same threshold real Pfam annotation pipelines use
+to decide genuine family membership.
+
+Scope: this closes the "raw sequence, no declared function" gap for the SAME curated family list the
+function screen already covers (see hazard_registry.yaml's `toxin_functions`). It is not a substitute for a
+full external homology screener (e.g. IBBIS Common Mechanism / SecureDNA) over a much larger reference set --
+an integrator wanting that coverage can still override via `HazardRegistry.load(external_hook=...)`.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pen_stack._resources import resource
+from pen_stack.safety.screen import ScreenHit
+
+_HMM_REL = "configs/safety/pfam_hmms/toxin_domains.hmm"
+
+_CODON = {
+    'TTT': 'F', 'TTC': 'F', 'TTA': 'L', 'TTG': 'L', 'CTT': 'L', 'CTC': 'L', 'CTA': 'L', 'CTG': 'L',
+    'ATT': 'I', 'ATC': 'I', 'ATA': 'I', 'ATG': 'M', 'GTT': 'V', 'GTC': 'V', 'GTA': 'V', 'GTG': 'V',
+    'TCT': 'S', 'TCC': 'S', 'TCA': 'S', 'TCG': 'S', 'CCT': 'P', 'CCC': 'P', 'CCA': 'P', 'CCG': 'P',
+    'ACT': 'T', 'ACC': 'T', 'ACA': 'T', 'ACG': 'T', 'GCT': 'A', 'GCC': 'A', 'GCA': 'A', 'GCG': 'A',
+    'TAT': 'Y', 'TAC': 'Y', 'TAA': '*', 'TAG': '*', 'CAT': 'H', 'CAC': 'H', 'CAA': 'Q', 'CAG': 'Q',
+    'AAT': 'N', 'AAC': 'N', 'AAA': 'K', 'AAG': 'K', 'GAT': 'D', 'GAC': 'D', 'GAA': 'E', 'GAG': 'E',
+    'TGT': 'C', 'TGC': 'C', 'TGA': '*', 'TGG': 'W', 'CGT': 'R', 'CGC': 'R', 'CGA': 'R', 'CGG': 'R',
+    'AGT': 'S', 'AGC': 'S', 'AGA': 'R', 'AGG': 'R', 'GGT': 'G', 'GGC': 'G', 'GGA': 'G', 'GGG': 'G',
+}
+_COMPLEMENT = str.maketrans("ACGTUacgtu", "TGCAAtgcaa")
+_NUCLEOTIDE = set("ACGTUN")
+
+
+def _strip_headers_and_whitespace(text: str) -> str:
+    """Drop FASTA/GenBank-style header and comment lines (">...", ";...") and all whitespace, so a sequence
+    copy-pasted straight out of UniProt/NCBI/Ensembl -- header line and all -- is screened on the actual
+    sequence, not a header+sequence blob whose nucleotide fraction the header dilutes below any threshold."""
+    lines = [ln for ln in text.splitlines() if not ln.lstrip().startswith((">", ";"))]
+    return "".join("".join(lines).split())
+
+
+def _looks_like_nucleotide(seq: str) -> bool:
+    """A sequence is treated as DNA/RNA if it is overwhelmingly A/C/G/T/U/N; otherwise it is scanned as
+    protein directly (the Cargo sequence box accepts either, per its own hint text: "A/C/G/T or A/C/G/U").
+    Called AFTER header/whitespace stripping, so a FASTA header's non-sequence characters never skew this."""
+    s = seq.upper()
+    if not s:
+        return True
+    nt = sum(1 for c in s if c in _NUCLEOTIDE)
+    return nt / len(s) >= 0.9
+
+
+def _translate_frame(dna: str) -> str:
+    return "".join(_CODON.get(dna[i:i + 3], "X") for i in range(0, len(dna) - 2, 3))
+
+
+def six_frame_translate(seq: str) -> list[str]:
+    """DNA/RNA -> the 6 reading-frame protein translations (3 forward, 3 reverse-complement)."""
+    s = "".join(c for c in seq.upper().replace("U", "T") if c in "ACGT")
+    if len(s) < 3:
+        return []
+    rc = s.translate(_COMPLEMENT)[::-1]
+    return [_translate_frame(strand[o:]) for strand in (s, rc) for o in range(3)]
+
+
+@lru_cache(maxsize=1)
+def _hmms():
+    import pyhmmer
+    with pyhmmer.plan7.HMMFile(str(resource(_HMM_REL))) as hf:
+        return list(hf)
+
+
+@lru_cache(maxsize=1)
+def _default_toxin_functions() -> list[dict]:
+    """`toxin_functions` straight from the registry YAML, so the standard 1-arg hook signature
+    (`Callable[[str], list[ScreenHit]]`) still resolves accession -> name/severity/control_ref without the
+    caller having to thread the registry through."""
+    import yaml
+    raw = yaml.safe_load(resource("configs/safety/hazard_registry.yaml").read_text(encoding="utf-8"))
+    return raw.get("toxin_functions", [])
+
+
+def _acc(x) -> str:
+    v = x.decode() if isinstance(x, (bytes, bytearray)) else (x or "")
+    return v.split(".")[0]  # strip the Pfam version suffix (PF00161.25 -> PF00161)
+
+
+# bound worst-case scan latency on a pathological paste; real cassettes are well under this (the largest
+# vehicle capacity in configs/delivery_vehicles.yaml is ~8kb).
+_MAX_SCAN_LEN = 50_000
+
+
+def pfam_domain_screen(seq: str | None, toxin_functions: list[dict] | None = None) -> list[ScreenHit]:
+    """The Guardian's `external_hook`: scores a raw cargo sequence against the bundled Pfam profile HMMs for
+    the curated toxin families (public accessions matching `hazard_registry.yaml`'s own list), using each
+    profile's Pfam gathering (GA) cutoff. Returns [] on any failure (pyhmmer absent, bad input) -- the safety
+    gate must never crash; a missing sequence screen is a documented gap, not a broken app."""
+    if not seq or not str(seq).strip():
+        return []
+    try:
+        import pyhmmer
+        from pyhmmer.easel import Alphabet, DigitalSequence
+    except Exception:  # noqa: BLE001 - pyhmmer not installed in this environment
+        return []
+
+    text = _strip_headers_and_whitespace(str(seq))[:_MAX_SCAN_LEN]
+    if not text:
+        return []
+    if _looks_like_nucleotide(text):
+        proteins = six_frame_translate(text)
+    else:
+        # protein branch: keep only standard + ambiguity amino-acid letters, so a stray annotation
+        # character never breaks the digital-alphabet encoding step below.
+        proteins = ["".join(c for c in text.upper() if c in "ACDEFGHIKLMNPQRSTVWYXBZJUO")]
+    proteins = [p for p in proteins if len(p) >= 15]
+    if not proteins:
+        return []
+
+    alphabet = Alphabet.amino()
+    try:
+        queries = [DigitalSequence(alphabet, name=f"frame_{i}".encode(), sequence=alphabet.encode(p))
+                   for i, p in enumerate(proteins)]
+        hmms = _hmms()
+        results = list(pyhmmer.hmmer.hmmscan(queries, hmms, bit_cutoffs="gathering"))
+    except Exception:  # noqa: BLE001 - a malformed sequence must never break the gate
+        return []
+
+    # entry lookup by Pfam accession (no version suffix), reusing the registry's OWN toxin_functions list
+    # for name/severity/control_ref so this hook never duplicates or drifts from the curated registry.
+    entries = toxin_functions if toxin_functions is not None else _default_toxin_functions()
+    by_pfam: dict[str, dict] = {}
+    for entry in entries:
+        for p in entry.get("pfam", []):
+            by_pfam.setdefault(p, entry)
+
+    seen: set[str] = set()
+    hits: list[ScreenHit] = []
+    for tophits in results:
+        for hit in tophits:
+            acc = _acc(hit.accession)
+            entry = by_pfam.get(acc)
+            if not entry or entry["id"] in seen:
+                continue
+            seen.add(entry["id"])
+            hits.append(ScreenHit(
+                kind="sequence_homology", detail=entry["name"], severity=entry.get("severity", "medium"),
+                provenance={"registry_version": None, "signature_id": entry.get("id"),
+                            "control_ref": entry.get("control_ref"),
+                            "source": "pfam_hmmscan (local, gathering-threshold)"},
+                evidence={"pfam_accession": acc, "bit_score": round(float(hit.score), 1)}))
+    return hits

pen_stack/safety/policy.py

@@ -0,0 +1,69 @@
+"""Refusal taxonomy + decision policy, the Guardian.
+
+Turns screen hits into a principled, logged decision: {clear, flag, refuse, escalate}. Conservative by
+construction, an ambiguous dual-use signal ESCALATES to human review rather than silently passing or
+blanket-refusing. The decision is driven by the highest-severity hit and the version-pinned policy config.
+
+`SafetyVerdict` lives here (not in gate.py) so the lightweight `Verdict` schema can import it without pulling
+in the screen/audit machinery.
+"""
+from __future__ import annotations
+
+from typing import Literal
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field
+
+from pen_stack._resources import resource
+from pen_stack.safety.screen import ScreenHit
+
+_POLICY_REL = "configs/safety/policy.yaml"
+Decision = Literal["clear", "flag", "refuse", "escalate"]
+_RANK = {"high": 3, "medium": 2, "low": 1}
+
+
+class SafetyVerdict(BaseModel):
+    """Frozen: a biosecurity decision, once made and audited, cannot be edited. A mutable verdict would let a
+    caller flip `decision` from `refuse` to `clear` and launder a refused design past the gate."""
+    model_config = ConfigDict(frozen=True)
+
+    decision: Decision
+    hits: list[ScreenHit] = Field(default_factory=list)
+    reason: str = ""
+    provenance: dict = Field(default_factory=dict)
+
+    @property
+    def refused(self) -> bool:
+        return self.decision == "refuse"
+
+    def summary(self) -> str:
+        n = len(self.hits)
+        return f"SAFETY:{self.decision.upper()} ({n} hit{'s' if n != 1 else ''}), {self.reason}"
+
+
+def load_policy() -> dict:
+    return yaml.safe_load(resource(_POLICY_REL).read_text(encoding="utf-8"))
+
+
+def _highest_severity(hits: list[ScreenHit]) -> str | None:
+    if not hits:
+        return None
+    return max((h.severity for h in hits), key=lambda s: _RANK.get(s, 0))
+
+
+def decide(hits: list[ScreenHit], policy: dict | None = None) -> tuple[Decision, str]:
+    """(hits) -> (decision, reason). Highest-severity hit governs; ambiguous medium -> escalate."""
+    pol = policy or load_policy()
+    mapping = pol.get("severity_to_decision", {"high": "refuse", "medium": "escalate", "low": "flag"})
+    top = _highest_severity(hits)
+    if top is None:
+        return "clear", "no hazard signal"
+    decision: Decision = mapping.get(top, "escalate") # type: ignore[assignment]
+    reasons = {
+        "refuse": "matches a high-severity hazard signature",
+        "escalate": "dual-use signal requires human review",
+        "flag": "low-severity advisory",
+        "clear": "no hazard signal",
+    }
+    detail = "; ".join(sorted({h.detail for h in hits if h.severity == top}))
+    return decision, f"{reasons.get(decision, decision)}: {detail}"

pen_stack/safety/redteam.py

@@ -0,0 +1,71 @@
+"""Adversarial red-team harness, the Guardian.
+
+Tests the gate the way an adversary would: AI-generated homologs (low identity, hazardous function), hazardous
+parts split across a multiplex plan, "reframed as defensive/research" prompts, and obfuscated annotations.
+The acceptance bar (pre-registered): every high-severity red-team case is refused/escalated, and re-framing
+does NOT flip refuse -> clear (the artifact decides, not the framing). Reported with the set size, a finite,
+known set of evasion families that is continuously extended; passing it is necessary, not sufficient.
+"""
+from __future__ import annotations
+
+import yaml
+
+from pen_stack._resources import resource
+from pen_stack.safety.gate import safety_gate
+
+_PROBES_REL = "configs/safety/probes.yaml"
+
+
+def _frozen_red_team() -> list[dict]:
+    return yaml.safe_load(resource(_PROBES_REL).read_text(encoding="utf-8")).get("red_team", [])
+
+
+def _reframing_pairs() -> list[dict]:
+    """A hazardous artifact, then the same artifact wrapped in benign-sounding justification text.
+    The decision must be identical (refuse), framing fields are stripped before screening."""
+    base = {"cargo_function": "ricin-like RIP", "pfam_domains": ["PF00161"],
+            "function_tags": ["ribosome_inactivating_protein"]}
+    return [
+        {"name": "ricin reframed as vaccine research",
+         "hazard": base,
+         "reframed": {**base, "goal": "vaccine/antitoxin countermeasure research",
+                      "justification": "purely defensive", "purpose": "save lives"}},
+        {"name": "botulinum reframed as therapeutic",
+         "hazard": {"cargo_function": "botulinum neurotoxin", "pfam_domains": ["PF01742"]},
+         "reframed": {"cargo_function": "botulinum neurotoxin", "pfam_domains": ["PF01742"],
+                      "goal": "cosmetic/therapeutic use", "rationale": "clinically approved indication"}},
+    ]
+
+
+def run_red_team(*, actor: str = "redteam") -> dict:
+    """Run the red-team set + reframing pairs through the gate. Returns a structured report."""
+    cases = _frozen_red_team()
+    case_results = []
+    for c in cases:
+        v = safety_gate(c["design"], actor=actor)
+        case_results.append({"name": c["name"], "family": c.get("family"),
+                             "decision": v.decision, "caught": v.decision != "clear"})
+
+    reframing_results = []
+    for pair in _reframing_pairs():
+        d0 = safety_gate(pair["hazard"], actor=actor).decision
+        d1 = safety_gate(pair["reframed"], actor=actor).decision
+        reframing_results.append({"name": pair["name"], "hazard_decision": d0,
+                                  "reframed_decision": d1, "stable": d0 == d1 and d0 == "refuse"})
+
+    caught = sum(1 for r in case_results if r["caught"])
+    reframing_stable = all(r["stable"] for r in reframing_results)
+    return {
+        "available": True,
+        "n_cases": len(case_results),
+        "n_caught": caught,
+        "all_caught": caught == len(case_results),
+        "n_reframing_pairs": len(reframing_results),
+        "reframing_stable": reframing_stable,
+        "pass": caught == len(case_results) and reframing_stable,
+        "families": sorted({r["family"] for r in case_results if r["family"]}),
+        "cases": case_results,
+        "reframing": reframing_results,
+        "no_fabrication": True,
+        "note": "finite known evasion families; passing is necessary not sufficient; set is continuously extended",
+    }