diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc new file mode 100644 index 0000000..a90abf3 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,663 @@ +== Changelog + +=== [Unreleased] + +==== Fixed — assail detector precision (false-positive reduction, 2026-06-24) + +Three `+assail+` analyzer fixes, all conservative (no new false +negatives), found while triaging hyperpolymath/proven#68 and +JoshuaJewell/paint-type#86: + +* *UncheckedAllocation (C) is now NULL-check aware.* The detector +previously flagged _every_ `+malloc(...)+` and emitted a line-less, +file-level finding. It now scans per line, skips a malloc whose result +is NULL-checked within a short window (`+if (p == NULL)+`, `+if (!p)+`, +`+nullptr+`), and attaches a line number — which also lets an inline +`+// panic-attack: accepted+` marker suppress a reviewed site (marker +suppression is line-gated). A genuinely-unchecked malloc still fires. +This is why a real null-check fix (proven `+stubs.c+`) previously failed +to clear. +* *DynamicCodeExecution (JS/Python) is word-boundary aware.* +`+contains("eval(")+` matched FFI symbol names like +`+proven_calculator_eval(+`. Now `+\beval\s*\(+` (and +`+\b(?:eval|exec)\s*\(+` for Python); a genuine `+eval(+` still fires. +* *CommandInjection (Shell) no longer matches the `+--eval+` CLI flag.* +`+contains("eval ")+` matched `+--eval+`/`+-eval+`. Now the eval builtin +is matched only in statement position (`+(?m)(?:^|[\s;&|(])eval[ \t]+`). + +Verified end-to-end: proven 1→0 active Critical/High (`+stubs.c+` +clears), paint-type 36→35 (gossamer `+--eval+` benchmark FP clears; +genuinely-unsafe vendored FFI + the irreducible `+believe_me+` axiom +correctly remain). 4 new tests in `+tests/analyzer_tests.rs+`; full +analyzer suite green; zero warnings. PR #134. Refs #32. + +==== Added — attestation unforgeability proof (Idris2, PROOF-PROGRAMME §3.2) + +* *`+src/abi/AttestationUnforgeability.idr+`*: Idris2 proof that the +intent→evidence→seal attestation chain is unforgeable. Models +`+chain_hash = H(intent‖evidence‖report)+` + the Ed25519 signature with +the cryptographic facts (chain-hash collision-resistance, Ed25519 +EUF-CMA message- and signer-binding, signature correctness) as a +`+parameters+` block — hypotheses, *not* `+postulate+` (PA021 bans +escape hatches), so it is an honest _conditional_ theorem. Under +`+%default total+` it Qed-closes `+integrity+` (tampering any phase +invalidates the seal), `+authenticity+` (a verifying seal comes from the +matching key), and `+nonRepudiation+` (a genuine seal verifies), plus +two corollaries. Typechecks under Idris2 0.8.0. Closes #123. + +==== Added — contractile registry (INDEX.a2ml) + +* *`+.machine_readable/contractiles/INDEX.a2ml+`*: the +previously-missing contractile registry, modelled on echidna’s canonical +INDEX. Catalogues all six verbs (must / trust / intend / adjust / bust / +dust) with their _actual current locations_ across the three +pre-consolidation trees, flags the duplicate `+trust+` Trustfile, and +records the canonical trident target. The physical consolidation of the +three trees stays in #124 — it couples to the `+contractile gen-just+` +generator (which reads the root `+contractiles/+` tree) and needs the +standards CONTRACTILE-SPEC to do safely. + +==== Added — `+assay+` / `+assimilate+` / `+aggregate+` proof-integration subcommands + +Three new a-themed subcommands that wire panic-attack into the +PROOF-PROGRAMME loop (survey → swap → fold-in-proofs): + +* *`+panic-attack assay [TARGET] [--proven DIR]…+`* +(`+src/assay/mod.rs+`): surveys a target for code that has a formally +proven drop-in equivalent in a `+proven+` / `+proven-servers+` library +and reports each candidate with the proof artifact that backs it — +operationalising the "`Proven cross-fit`" table in +`+PROOF-PROGRAMME.md+` mechanically instead of by hand. Built-in +catalogue: `+SafePath+` (canonicalize/unwrap pattern) and `+SafeUrl+` +(`+VERISIMDB_URL+`). On this repo: `+safe-path+` *Offered* (port present +in `+src/safe_path.rs+`, call sites still to rewire), `+safe-url+` +*NoReplacementSource* (not yet ported). +* *`+panic-attack assimilate [TARGET] --candidate ID [--proven DIR] [--from FILE] [--all] [--dry-run]+`*: +performs a swap — stages the proven module into the tree, backs up the +original (`+*.orig+`), and writes a provenance record (source BLAKE3 +hash + proof backing + pending call-site rewires) under +`+.assimilated/+`. Module swaps are automatic; call-site rewiring is +reported, never auto-edited (mechanically editing arbitrary call sites +is not a reviewable operation). +* *`+panic-attack aggregate --proof PATH… [--label PATH=NAME] [--covers PATH=SPEC] [--report BASE]+`* +(`+src/aggregate/mod.rs+`): folds external prover output (Agda / Idris2 +/ Coq·Rocq / Lean / Isabelle / TSTP / Alethe / DRAT·LRAT) into a report. +Each artifact is *BLAKE3-hashed for non-repudiation*, given a friendly +name, classified (Closed / Holes / Refuted / Indeterminate — +comment-stripped so prose mentioning `+postulate+` / `+Admitted+` does +not false-trigger), and reconciled against findings (*Backed / +Corroborated / Contradicted*). Every verdict is explicitly conditioned +on the named checker’s trust; the recorded hash lets the tool show +exactly which bytes it was handed if the assessment is later challenged. +`+@name "…"+` / `+@covers [claim:]kind:value+` annotations travel inside +the artifact; CLI `+--label+` / `+--covers+` override. + +Proof foundation re-verified from first principles under a fresh *Idris2 +0.8.0* install: `+Types+`, `+Stripping+` (Layer 1.0), +`+PatternCompleteness+` (PA1) and `+ClassificationSoundness+` (PA2) all +typecheck. 17 new unit tests; full library suite (395 tests) green; zero +new compiler warnings. + +=== [2.5.5] — 2026-06-02 + +Release of the v2.5.5 cohort that landed across 11 PRs in panic-attack + +wiki + gitbot-fleet on 2026-06-02 PM. Tagged 2026-06-02 PM-evening. + +==== Added (2026-06-02 PM) — v2.5.5 context-awareness cohort + v3.0.0 Chapel→VeriSimDB push + PROOF-PROGRAMME + +Eight PRs landed in one cohort closing the v2.5.5 ROADMAP section, a +v3.0.0 item, and opening the first proof slice of the new +PROOF-PROGRAMME. + +*v2.5.5 — Attack Surface Widening (false-positive reduction)* + +* *`+test_context+` foundation* (#102): new `+src/test_context.rs+` +module with cross-language test-path classification (Rust / Python / Go +/ JavaScript / Julia / Zig / Elixir / docs-examples). New +`+WeakPoint.test_context: Option+` field (Production / +TestOnly / Doc) plumbed through 137 construction sites. Content-based +promotion via `+use ExUnit.Case+` / `+unittest.TestCase+` / +`+pytest.fixture+` / `+@testset+` markers. +* *`+comment_marker+` inline suppression* (#105): new +`+src/comment_marker.rs+` module recognising +`+// panic-attack: accepted [- reason]+` on the same or preceding line. +Cross-language comment leaders: `+//+` mid-line for C-family; `+#+` / +`+--+` / `+;+` / `+%+` / `+///+` / `+//!+` start-of-line for +Python/Haskell/Lisp/Erlang/Rust-doc/Rust-inner-doc. String-literal +aware. Shebang `+#!+` excluded. +* *`+ffi_kind+` subtyping* (#106): new `+src/ffi_kind.rs+` module +subtyping `+WeakPointCategory::UnsafeFFI+` (PA013) into BuildSystem / +RuntimeAbi / TestMock / Unknown. `+classify_by_path+` distinguishes +`+build.zig+` / `+build.rs+` (BuildSystem, audit-accepted by default) +from `+bindings/+` / `+ffi/+` / `+sys/+` / `+cdef.zig+` (RuntimeAbi, +audit-significant) from `+tests/mocks/+` / `+tests/stubs/+` (TestMock, +also audit-accepted). New `+is_audited_boundary(audit_text, file_path)+` +parses `+audits/audit-ffi-unsafe.md+` `+## Approved boundaries+` +markdown. +* *`+jit_context+` classifier* (#107): new `+src/jit_context.rs+` module +classifying JIT frameworks — Cranelift / Llvm / Wasm / Javascript / +None. Factors existing inline Cranelift detection at +`+analyzer.rs:1117..1129+` into reusable surface. +`+transmute_targets_fn_ptr+` made tolerant of +`+= unsafe { ... transmute(..) }+` wrappers. +* *Phase 2 analyzer wire-up* (#110): new +`+apply_v255_context_suppression(&mut report)+` runs after the +kanren-based rule pass and (a) marker-flips +`+WeakPoint.suppressed = true+` when `+panic-attack: accepted+` is on or +above the line, (b) auto-suppresses `+PanicPath+` in TestOnly/Doc +context, (c) auto-suppresses `+UnsafeFFI+` in BuildSystem/TestMock +context. Sets `+test_context+` metadata on every finding with a known +file path. + +*v3.0.0 — Distributed Scanning (HTTP push from Chapel)* + +* *`+panic-attack verisim-push +` subcommand* (#108): new +`+Commands::VerisimPush+` gated on the `+http+` Cargo feature. Reads a +JSON hexad (typically what Chapel `+takeSnapshot+` just wrote), POSTs to +`+$VERISIMDB_URL+` (default `+http://localhost:8080+`) via the existing +`+storage::push_hexad_http_with_retry+`. `+--fallback-dir+` writes a +JSON copy on HTTP failure for offline replay. +* *Chapel `+takeSnapshot+` overload* (#108): new 6-arg form accepting +`+verisimPushUrl+` + `+panicAttackBin+` parameters. Spawns +`+panic-attack verisim-push --url --retry +` after local +hexad write. Local writes remain authoritative; push is additive. Closes +the `+[ ]+` ROADMAP item. + +*PROOF-PROGRAMME — first-principles soundness* + +* *`+PROOF-PROGRAMME.md+`* (#104): 3-layer landscape (Surface / Engine / +Persistence) covering all 25 PA-code soundness proofs + miniKanren +correctness + bridge reachability + attestation chain unforgeability. +9-phase sequencing (~16 weeks). Identifies `+proven+` cross-fit +candidates: only `+SafePath+` + `+SafeUrl+` qualify as port-to-Rust +(perf-neutral, semantic-equivalent); `+SafeJson+` / `+SafeRegex+` / +`+SafeDateTime+` / `+SafeCommand+` / `+SafeEnv+` / `+SafeUUID+` marked +skip (already total / semantic mismatch). +* *Layer 1.0 partial* (#111): new `+src/abi/Stripping.idr+` Qed-closing +the foundation lemmas for line-comment stripping — +`+stripBodyProducesStrippedShape+` (every body output satisfies +`+IsStrippedBody+`) + base cases of `+stripLineCommentsIdempotent+` +(empty + non-slash-headed input). Open: the slash-slash inductive +closure `+stripIsIdentityOnStrippedBody+` (recorded as the next +Layer-1.0 slice in `+PROOF-NEEDS.md+`). + +==== Changed (2026-06-02) — truthfulness audit (humans + machines) + +* *README badge + Status block* corrected: 402 → *782 runnable tests* +(per `+cargo test --release -- --list+`; the underlying 539 `+#[test]+` +annotations expand via doctests + integration tiers). The badge had not +tracked actual count for several releases. Wiki Home was `+282++`. +* *chapel-ci `+chapel-multilocale+` gate* robustified (#100 collateral): +pinned `+CHPL_UNWIND=system+` explicitly + moved `+libunwind-dev+` +install to always-run (not gated on cache-hit). On cache-hit runs +without libunwind-dev, chpl auto-inferred `+CHPL_UNWIND=bundled+` and +aborted with "`no runtime for bundled`" because the cached runtime was +built with `+system+`. Cache-gen counter bumped `+v1+` → `+v2+` to +discard the inconsistent cache. Fifth Chapel-2.8.0 sharp edge from #99 +Wave 2. +* *ROADMAP v2.2.0*: downgraded "`Per-project VeriSimDB instance: +`+deploy/panic-attack/fly.toml+` for `+verisim-panic-api+``" from +`+[x]+` to `+[~]+` — the API runs but the toml file is NOT in this repo +(lives in the `+verisimdb+` deployment tree). The `+[x]+` checkbox +previously pointed at a path that didn’t exist on `+main+`. +* *ROADMAP front matter + Wiki Home*: "`500+ repositories`" replaced +with the empirically verifiable "`303-repo hyperpolymath estate +(2026-04-12)`" — the number that appears in +`+docs/mass-panic-fnirs-paper.adoc+` Table I. +* *`+chapel/README.md+`*: 5× softening of "`~5–15% slower`" to +"`(UNMEASURED ESTIMATE)`" with explicit link to +`+panic-attack#87 Wave-3 followup+` for the actual benchmark. +* *README Status block + Wiki Home*: noted that the 25 canonical PA +codes correspond to 26 `+WeakPointCategory+` enum variants — `+PA001+` ⇒ +`+UncheckedAllocation+` and `+PA001b+` ⇒ `+UnboundedAllocation+` share +the same canonical SARIF rule for taxonomy purposes (see +`+src/report/sarif.rs+`). + +==== Added (2026-06-01) — Chapel Wave 2: single-host multilocale gate + +* *`+chapel-multilocale+` CI gate* (#99, closes #87 option A): adds a +7th strict chapel-ci job that builds Chapel 2.8.0 from source with +`+CHPL_COMM=gasnet+` + `+CHPL_COMM_SUBSTRATE=smp+` + +`+CHPL_LAUNCHER=smp+`, caches `+$CHPL_HOME+` (`+actions/cache@v4+`, +stable key with manual `+CHAPEL_MULTILOCALE_CACHE_GEN+` invalidation +counter; cold build ~30-40 min, warm restore ~30s for 7 days), runs +`+mass-panic --numLocales=2+` against a synthetic 2-repo corpus, and +greps the emitted `+system-image-*.json+` for both repo names to prove +cross-locale aggregation actually executed. The Wave 1 binary `+.deb+` +install path is single-locale only; this gate closes the gap. +* Aggregator `+chapel-ci-gate+` updated to wait on the 7th job and to +surface it as `+multilocale=+` in the gate summary. +* Wave 3 (`+gasnet/ofi+` over a real NIC across cluster nodes) and the +~50-repo "`~5-15% slower`" benchmark from `+chapel/README.md+` remain +parked — both need a beefier or self-hosted runner to be meaningful. + +==== Fixed (2026-06-01) — baseline-red corrective maintenance + +* *Dogfood Gate A2ML validation* restored (#94, #97): bumped +`+hyperpolymath/a2ml-validate-action+` from `+59145c7d+` to `+6bff6ec+` +to pick up s-expression-form identity/version recognition (upstream PR +#26); relocated `+docs/campaigns/2026-05-26.a2ml+` to +`+.machine_readable/campaigns/+` so it inherits the structural-identity +exemption (the file’s own header describes it as "`machine-readable A2ML +form`"). +* *Governance Trusted-base reduction policy* restored (#94): added +`+.trusted-base-ignore+` exemption for `+src/assail/analyzer.rs+` — the +file IS the scanner that defines the escape-hatch patterns, so its +literal references to them are by design. +* *Secret Scanner rust-secrets* false-positive cleared (#94): refactored +`+RE_HARDCODED_SECRET+` regex construction via `+concat!+` to split +detector keywords across source-string boundaries (the literal +`+password+` keyword in the source was self-flagging). +* *Rust CI reusable* SHA bumped past `+standards#334+` (#97) — caller +now resolves the `+${{ }}+`-wrapped job-level `+if:+` fix and unblocks +the `+rust-ci.yml+` wrapper that was reporting 0-second parse failures +(root cause documented at `+standards#322+`). +* *rsr-template scaffolding gaps filled* (#96): LICENSE flipped from +AGPL-3.0 body to MPL-2.0 (matching SPDX headers + Cargo.toml + +README.adoc); CODE_OF_CONDUCT.md placeholders instantiated +(`+{{CONDUCT_EMAIL}}+` → `+j.d.a.jewell@open.ac.uk+`, +`+{{CONDUCT_TEAM}}+` → `+panic-attack maintainers+`, +`+{{RESPONSE_TIME}}+` → `+48 hours+`, `+language-bridges+` → +`+panic-attack+`); bug_report/feature_request issue templates +Rust-toolchain-aware; empty `+custom.md+` removed; SECURITY.md version +table updated from `+0.2.x+` to `+2.5.x+`. + +==== Changed (2026-06-01) + +* *Dependabot rust-minor group bumps* (#93): `+log+` 0.4.29 → 0.4.30, +`+eframe+` minor update. + +==== Added (2026-05-30) — issue #33 closure + +* *VeriSimDB hexad persistence complete (issue #33 S1–S3)* — per-finding +hexads, campaign state lifecycle, and S-expression query DSL all +shipped: +** *S1*: per-finding hexad emission gated by +`+PANIC_ATTACK_STORE_FINDING_HEXADS=1+` +(`+src/storage/mod.rs :: build_finding_hexads+`, subject format +`+finding::::+`). +** *S2*: `+panic-attack campaign+` subcommand (`+register-pr+`, +`+dismiss+`, `+status+`, `+poll+`) drives finding lifecycle with state +transitions persisted as campaign hexads. `+poll+` performs GitHub PR +state transitions (open → pr-filed → pr-merged / pr-closed). +** *S3*: `+panic-attack query +` evaluates a small S-expression +language over the persisted hexads. Heads: `+category+`, `+rule-id+`, +`+severity+`, `+repo+`, `+file+`, `+pr-state+`, `+since+`, +`+crosslang+`, `+diff+`, `+and+`, `+or+`, `+not+`. +* *Query parser: `+(diff :since :category ...)+` head + inline +`+:keyword VALUE+` kwargs on every unary head* (`+src/query/mod.rs+`). +The issue body’s three literal example expressions now parse verbatim: +** `+(crosslang :from FFI :to ProofDrift)+` — already worked. +** `+(category PA001 :severity Critical :pr-state nil)+` — now parses as +`+(and (rule-id PA001) (severity Critical) (pr-state nil))+`, with +PA-prefixed values on `+category+` auto-routed to `+rule-id+` so the +query actually matches findings. +** `+(diff :since 2026-04-12 :category PA022)+` — new `+diff+` head is +keyword-only sugar for an `+(and ...)+` over its kwarg pairs. Inline +kwargs are accepted on `+category+`, `+rule-id+`, `+severity+`, +`+repo+`, `+file+`, `+pr-state+`, and `+since+` — adding a +`+:keyword VALUE+` after the positional value desugars to +`+(and (head positional) (kw value) ...)+`. Behaviour unchanged for +existing query expressions; 12 new unit tests. + +==== Added (2026-04-18) + +* *User-classification registry* (`+assail::UserClassification+`, +`+load_user_classifications+`, `+apply_user_classifications+`): +panic-attack now reads an optional project-local classification file at +every assail pass and flips matching findings to `+suppressed = true+` +after the kanren structural-suppression pass. Two lookup paths: +** `+/audits/assail-classifications.a2ml+` (preferred) +** `+/.panic-attack-classifications.a2ml+` (fallback) File +format is a simple A2ML S-expression with +`+(classification (file …) (category …) (audit …) (rationale …))+` +blocks; `+;;+` line comments ignored. The registry pattern lets +repositories record audited findings out-of-band from the source under +scan so a PR adding a new unsafe block cannot self-suppress without a +reviewable companion edit to the registry. +* *Rocq scaffold classifier* (`+analyze_coq+` + +`+count_rocq_unverified_postulates+` + +`+is_rocq_abstraction_parameter+`): the Rocq detector no longer counts +Section-scoped `+Variable+` / `+Hypothesis+` / `+Parameter+` +declarations (they discharge at `+End Section+`) and classifies +module-level `+Parameter+` declarations by stated type: carrier types +(`+Type+`, `+Set+`), decidability witnesses +(`+forall _, { _ = _ } + { _ <> _ }+`), and function types with a +concrete non-Prop codomain are treated as abstraction parameters. +Prop-valued declarations (classical excluded-middle, choice, unresolved +theorem statements) remain counted. Removes the false-positive stream +that surfaced on every canonical-proof-suite scaffold. + +==== Changed + +* *Suppression pipeline*: `+analyze()+` and `+analyze_verbose()+` now +chain `+apply_suppression+` → `+apply_user_classifications+` in that +order; the explicit post-analyze calls in `+assail::analyze+` and +`+assail::analyze_verbose+` at the module boundary are retained for +API-contract clarity but are no-ops when an `+Analyzer+` pass has +already run. +* *Rocq test coverage*: 12 new unit tests across `+analyzer.rs+` +(Section-scoped Variables / module-level Type carriers / decidable +equality / concrete-codomain functions / Prop-valued axioms / missing +type annotation / full scaffold shape — 7 tests) and `+mod.rs+` +(missing-registry / single-entry / multiple-entry / comment handling / +end-to-end suppression-flip — 5 tests). + +==== Verified + +* 007 canonical-proof-suite scan: active finding count *8 → 0* (the 6 +scaffold ProofDrifts via the detector enhancement, the 2 +`+zig_bridge.rs+` UnsafeCode findings via the classification registry +pointing at `+audits/audit-ffi-unsafe.md §1+`). No in-source suppression +markers added to either repo. + +=== [2.5.0] - 2026-04-12 + +==== Added + +* *InputBoundary category (PA024)*: New weak point category detecting +unguarded structured-data parsing at trust boundaries. +** *Rust*: `+serde_cbor::from_slice+`/`+from_reader+`, +`+ciborium::de::from_reader+`, `+rmp_serde::from_slice+`/`+from_read+` — +CBOR/MessagePack deserialization without a validation layer (Medium). +All five crate patterns flagged. +** *JavaScript/ReScript*: `+JSON.parse(+` in files without any +`+try+`/`+catch+` context (High). Files that do wrap their JSON.parse in +try/catch are not flagged. +** *Julia*: `+JSON3.read(+` and `+JSON.parse(+` without error handling +context (High). +** Taint tracking from external reads to trust-sensitive sinks deferred +to kanren phase. +** A2ML boundary detection deferred — requires cross-file analysis. +* *PA024 → panicbot*: InputBoundary mapped to +`+static-analysis/input-boundary+`, 0.72 confidence, Control tier, +Partial fixability. +* *MutationGap category (PA025)*: New weak point category detecting +mutation and chaos coverage gaps in test suites. +** *Rust* (project-level): Tests present (`+mod tests+` / +`+#[cfg(test)]+`) but no `+cargo-mutants+` config in `+Cargo.toml+` or +`+mutants.toml+` — mutation tooling absent (Low). +** *Julia* (per-file): `+@testset+` blocks where every `+@test+` is a +type-check assertion (`+@test … isa …+`) with no value assertions — no +assertion diversity (Medium). +** *Elixir* (per-file): Test files using `+ExUnit.Case+` without +importing `+ExUnitProperties+` or `+StreamData+` for property-based +testing (Low). +** Coverage-plus-mutation-score check deferred — requires runtime +coverage data. +* *PA025 → panicbot*: MutationGap mapped to +`+static-analysis/mutation-gap+`, 0.80 confidence, Substitute tier, +Partial fixability. +* *Idris2 ABI completeness*: `+PatternCompleteness.idr+` updated — +InputBoundary (Rust/JS/Julia) and MutationGap (Rust/Julia/Elixir) added +to `+WPCategory+` with `+detectorsFor+` entries. + +==== Changed + +* *Category count*: 23 → 25 (added InputBoundary, MutationGap) +* *v2.5.0 milestone*: All tractable items complete. Two deferred items +each for `+input_boundary+` (taint+A2ML) and `+mutation+` +(coverage-score), and three for `+crypto_misuse+` (key-reuse, +nonce-reuse, sig-verify) marked as statically undetectable or requiring +runtime data. + +=== [2.3.0] - 2026-04-12 + +==== Added + +* *CryptoMisuse category (PA022)*: New weak point category detecting +cryptographic primitive misuse across five languages. Context-window +heuristic (±200 chars) restricts MD5/SHA-1 findings to +security-sensitive usage — MD5 for file checksums is not flagged. +** *Rust*: `+md5::compute+`/`+Md5::new+` and +`+sha1::Sha1+`/`+Sha1::new+` in security context (High); `+==+` +comparison on `+secret+`/`+password+`/`+token+`/`+key+` variables +(Critical — timing attack). +** *Python*: `+hashlib.md5()+`/`+hashlib.sha1()+` in security context +(High); `+==+` on secret-named variables — use `+hmac.compare_digest()+` +instead (Critical). +** *JavaScript*: `+crypto.createHash('md5')+` and +`+crypto.createHash('sha1')+` (High); `+crypto.createHash('sha256')+` is +fine and not flagged. +** *Go*: `+md5.New()+`/`+md5.Sum()+` and `+sha1.New()+`/`+sha1.Sum()+` +in security context (High). +** *Elixir*: `+:crypto.hash(:md5, ...)+` and `+:crypto.hash(:sha, ...)+` +(High); `+:crypto.mac(:hmac, :sha, ...)+` is acceptable (HMAC-SHA1 is +not broken) and not flagged. +** Key-reuse and nonce-reuse deferred — not reliably detectable +statically. +* *has_security_context() helper*: Module-level helper function checks +±200 char window around a pattern match for security vocabulary +(password, secret, token, auth, key, credential, hash, sign, verify, +encrypt) to reduce false positives on benign MD5/SHA-1 use. +* *PA022 → panicbot*: CryptoMisuse mapped to fleet category +`+static-analysis/crypto-misuse+` with 0.75 confidence, Eliminate tier, +Partial fixability. Confidence is honest — the context window has a +modest false-positive rate when security vocabulary appears for +unrelated reasons. +* *Idris2 ABI completeness*: `+PatternCompleteness.idr+` updated — +CryptoMisuse added to `+WPCategory+` with `+detectorsFor+` covering +Rust, Python, JavaScript, Go, Elixir. + +=== [2.2.0] - 2026-04-12 + +==== Added + +* *SupplyChain category (PA023)*: New weak point category detecting +dependency and build integrity gaps: `+Cargo.toml+` git dependencies +without `+rev =+`, absent `+Cargo.lock+` for library/binary crates, +Julia `+Manifest.toml+` without `+git-tree-sha1+` hash entries, +`+flake.nix+` inputs without `+narHash+`, and `+deno.json+` import map +entries without a version pin. Project-level manifest checks run as a +synthesis stage after file analysis. Confidence 0.85 — these are +explicit manifest/config patterns with low false-positive rate. +* *PA023 → panicbot*: SupplyChain mapped to fleet category +`+static-analysis/supply-chain+` with 0.85 confidence, Eliminate tier, +fixable (adding pins resolves the finding). +* *Idris2 ABI completeness*: `+PatternCompleteness.idr+` updated — +SupplyChain added to `+WPCategory+` with `+detectorsFor+` covering Rust, +Julia, Nix, JavaScript. + +==== Changed + +* *Category count*: 22 → 23 (added SupplyChain) + +=== [2.1.0] - 2026-04-12 + +==== Added + +* *ProofDrift category (PA021)*: New weak point category detecting +formal verification drift across all proof assistant languages. Catches +banned proof escape hatches (`+sorry+`, `+Admitted+`, `+believe_me+`, +`+oops+`, `+trustMe+`, `+assert_total+`, `+%partial+`, +`+{-# TERMINATING #-}+`) and Julia mirror files substituting +`+@test x isa Y+` or `+# sorry+` comments for formal proofs. Confidence +0.92 — proof escape hatches have essentially no false positives in their +file types. +* *Isabelle/HOL language support*: `+.thy+` files parsed with +`+analyze_isabelle()+` detecting `+sorry+`, `+oops+`, and +`+axiomatization+` as ProofDrift findings. +* *Coq/Rocq language support*: `+.v+` files parsed with +`+analyze_coq()+` detecting `+Admitted+`, `+admit+` tactic, +`+Axiom+`/`+Parameter+` declarations, and `+Obj.magic+` in extraction +artifacts. +* *Isabelle + Coq dispatch*: Both new languages wired into +`+analyze_inner()+` dispatch. +* *Lean4 ProofDrift upgrade*: `+sorry+` upgraded from UnsafeCode → +ProofDrift (Critical). Added `+unsafeNativeIO+`/`+unsafeBaseIO+` as +ProofDrift (IO discipline bypass). +* *Agda ProofDrift upgrade*: `+trustMe+`/`+primTrustMe+` upgraded to +ProofDrift (Critical). Added `+{-# TERMINATING #-}+`, +`+{-# NON_TERMINATING #-}+`, bare `+postulate+` as ProofDrift. +* *Idris2 ProofDrift upgrade*: `+believe_me+` already ProofDrift; added +`+assert_total+` (High) and `+%partial+` (Medium) as ProofDrift +findings. +* *Julia mirror detection*: `+# sorry+`, `+# TODO: prove+`, +`+# admitted+` comments and `+@test x isa Y+` patterns (no value check) +flagged as ProofDrift in Julia files. +* *FP suppression wiring*: `+apply_suppression()+` now runs on every +scan, marking weak points `+suppressed: true+` when logic engine finds +defensive-pattern context. Suppressed items stay in report for audit +transparency; filtered by panicbot and CI gates. +* *PA021 → panicbot*: ProofDrift mapped to fleet category +`+static-analysis/proof-drift+` with 0.92 confidence and Control tier. +* *Idris2 ABI completeness*: `+PatternCompleteness.idr+` updated — +Isabelle, Coq added to `+Lang+` enum; ProofDrift added to `+WPCategory+` +with `+detectorsFor+` covering all new languages. +* *Hypatia integration*: JSON AssailReport consumed by Hypatia Elixir +rules. Logtalk export removed 2026-04-12. + +==== Changed + +* *Language count*: 47 → 49 (added Isabelle, Coq) +* *Category count*: 20 → 21 (added ProofDrift) +* *Verbose output*: Two views — filtered (active, what CI sees) and +unfiltered (total, audit transparency) with explicit labelling of what +each count means. + +=== [2.0.0+] - 2026-03-23 + +==== Fixed + +* *A2ML parser*: Now handles TOML-like format (key = "`value`") in +addition to S-expression format +* *Manifest lookup*: Tries `+0-AI-MANIFEST.a2ml+` first before falling +back to `+AI.a2ml+` +* *Language detection*: Skips `+external_corpora/+`, `+third_party/+`, +and `+corpus/+` directories to avoid false positives from vendored or +reference text + +=== [2.0.0+] - 2026-03-01 + +==== Added + +* *SARIF output format*: `+--output-format sarif+` for GitHub Security +tab integration +* *Assemblyline batch scanning*: Scan entire directories of repos with +`+assemblyline+` subcommand +** Rayon parallelism: 17.7x speedup (141 repos in 39.9s) +** BLAKE3 fingerprinting for incremental scanning (infrastructure ready) +** Sorted output: riskiest repos first +* *Notification pipeline*: `+notify+` subcommand generates annotated +finding summaries +** Markdown output with severity breakdown per repo +** `+--critical-only+` flag for filtering +** `+--create-issues+` for GitHub issue creation +* *Cryptographic attestation chain*: Three-phase model (intent, +evidence, seal) +** Pre-execution commitment hashing +** Rolling evidence accumulator +** Post-execution binding with optional Ed25519 signing +(`+--features signing+`) +** A2ML envelope wrapper for attestation bundles +* *i18n support*: ISO 639-1, 10 languages (en, fr, de, es, it, pt, ja, +zh, ko, ar) +** Compile-time safe catalog with `+t()+` and `+t_or_key()+` lookups +** Doc-tested examples +* *Panicbot integration*: JSON output contract verified for gitbot-fleet +** PA001-PA020 rule mapping for all 20 WeakPointCategory variants +** Bot directives at `+.machine_readable/bot_directives/panicbot.scm+` +** Diagnostics self-check for panicbot readiness +* *Machine-verifiable readiness tests*: 18 tests across CRG grades D/C/B +** Grade D (Alpha): component runs without crashing +** Grade C (Beta): correct output on representative input +** Grade B (RC): edge cases and multi-language support +* *Justfile*: build, test, readiness, readiness-summary, clean, install, +dogfood, lint recipes +* *Manifest-first framework detection*: Detects frameworks from +Cargo.toml, mix.exs, package.json etc. instead of source scanning +(eliminates false positives) + +==== Fixed + +* *Framework detection false positives*: Self-referential matches +eliminated by using dependency manifests as primary signal; Rust source +scanning removed entirely +* *All compiler warnings*: 0 warnings in both release and test builds +* *Test count*: 269 tests (up from ~30), 0 failures + +==== Changed + +* *Diagnostics*: Now checks panicbot integration readiness (JSON +contract, directives) +* *AI.a2ml*: Added panicbot, updated SARIF format, corrected metadata +* *ECOSYSTEM.scm*: Added panicbot with full interface documentation +* *STATE.scm*: Updated with all session 8/9 capabilities and outcomes + +=== [2.0.0] - 2026-02-08 + +==== Added + +* *47-language support*: BEAM (Elixir, Erlang, Gleam), ML (ReScript, +OCaml, SML), Lisp (Scheme, Racket), Functional (Haskell, PureScript), +Proof (Idris, Lean, Agda), Logic (Prolog, Logtalk, Datalog), Systems +(Zig, Ada, Odin, Nim, Pony, D), Config (Nickel, Nix), Scripting (Shell, +Julia, Lua), plus 12 nextgen DSLs +* *20 weak point categories*: UnsafeCode, PanicPath, CommandInjection, +UnsafeDeserialization, DynamicCodeExecution, UnsafeFFI, AtomExhaustion, +InsecureProtocol, ExcessivePermissions, PathTraversal, HardcodedSecret, +UncheckedError, InfiniteRecursion, UnsafeTypeCoercion, +UncheckedAllocation, UnboundedLoop, BlockingIO, RaceCondition, +DeadlockPotential, ResourceLeak +* *miniKanren-inspired logic engine* (`+src/kanren/+`): +** Substitution-based unification +** Forward chaining: derives vulnerability facts from rules +** Backward queries: find files by vulnerability category +** Taint analysis: source-to-sink data flow tracking +** Cross-language vulnerability chain detection +(FFI/NIF/Port/subprocess) +** Search strategy auto-selection (RiskWeighted, BoundaryFirst, +LanguageFamily, BreadthFirst, DepthFirst) +* *PanLL event-chain export*: DAW-style timeline export for +visualisation +* *Ambush timeline scheduling*: Stressor sequencing with timeline files +* *Report views*: Summary, accordion, dashboard, matrix views + TUI +viewer +* *Nickel output format* + +==== Changed + +* *Renamed*: xray -> assail, XRayReport -> AssailReport, src/xray/ -> +src/assail/ +* *Renamed*: panic-attacker binary -> panic-attack + +=== [1.0.1] - 2026-02-07 + +==== Fixed + +* *CI/CD workflows*: All GitHub Actions now passing +** Updated MSRV from 1.75.0 to 1.85.0 (required for Cargo.lock v4 +format) +** Fixed invalid codeql-action SHA pins +** Fixed TruffleHog configuration +** Fixed EditorConfig indentation violations +* *Code quality*: Resolved clippy warnings, removed unused imports + +==== Changed + +* *MSRV*: Updated from 1.75.0 to 1.85.0 + +=== [1.0.0] - 2026-02-07 + +==== Added + +* *Production-ready infrastructure*: RSR compliance, 11 workflows, docs +* *Testing*: 21 unit + 3 integration + 3 regression tests +* *Configuration*: Config file support, EditorConfig, MSRV policy + +=== [0.2.0] - 2026-02-07 + +==== Fixed + +* *Weak points now per-file*: Eliminates duplicates (echidna: 271 -> 15) +* *File locations always populated*: No more `+location: None+` + +==== Added + +* FileStatistics, Latin-1 fallback, verbose mode, pattern library, +integration tests + +=== [0.1.0] - 2026-02-06 + +Initial proof-of-concept: Assail static analysis, multi-axis stress +testing, logic-based bug signature detection. diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 60d450f..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,496 +0,0 @@ - - -# Changelog - -## [Unreleased] - -### Fixed — assail detector precision (false-positive reduction, 2026-06-24) - -Three `assail` analyzer fixes, all conservative (no new false negatives), found -while triaging hyperpolymath/proven#68 and JoshuaJewell/paint-type#86: - -- **UncheckedAllocation (C) is now NULL-check aware.** The detector previously - flagged *every* `malloc(...)` and emitted a line-less, file-level finding. It - now scans per line, skips a malloc whose result is NULL-checked within a short - window (`if (p == NULL)`, `if (!p)`, `nullptr`), and attaches a line number — - which also lets an inline `// panic-attack: accepted` marker suppress a - reviewed site (marker suppression is line-gated). A genuinely-unchecked malloc - still fires. This is why a real null-check fix (proven `stubs.c`) previously - failed to clear. -- **DynamicCodeExecution (JS/Python) is word-boundary aware.** `contains("eval(")` - matched FFI symbol names like `proven_calculator_eval(`. Now `\beval\s*\(` - (and `\b(?:eval|exec)\s*\(` for Python); a genuine `eval(` still fires. -- **CommandInjection (Shell) no longer matches the `--eval` CLI flag.** - `contains("eval ")` matched `--eval`/`-eval`. Now the eval builtin is matched - only in statement position (`(?m)(?:^|[\s;&|(])eval[ \t]`). - -Verified end-to-end: proven 1→0 active Critical/High (`stubs.c` clears), -paint-type 36→35 (gossamer `--eval` benchmark FP clears; genuinely-unsafe -vendored FFI + the irreducible `believe_me` axiom correctly remain). 4 new -tests in `tests/analyzer_tests.rs`; full analyzer suite green; zero warnings. -PR #134. Refs #32. - -### Added — attestation unforgeability proof (Idris2, PROOF-PROGRAMME §3.2) - -- **`src/abi/AttestationUnforgeability.idr`**: Idris2 proof that the - intent→evidence→seal attestation chain is unforgeable. Models - `chain_hash = H(intent‖evidence‖report)` + the Ed25519 signature with the - cryptographic facts (chain-hash collision-resistance, Ed25519 EUF-CMA - message- and signer-binding, signature correctness) as a `parameters` - block — hypotheses, **not** `postulate` (PA021 bans escape hatches), so it - is an honest *conditional* theorem. Under `%default total` it Qed-closes - `integrity` (tampering any phase invalidates the seal), `authenticity` - (a verifying seal comes from the matching key), and `nonRepudiation` - (a genuine seal verifies), plus two corollaries. Typechecks under Idris2 - 0.8.0. Closes #123. - -### Added — contractile registry (INDEX.a2ml) - -- **`.machine_readable/contractiles/INDEX.a2ml`**: the previously-missing - contractile registry, modelled on echidna's canonical INDEX. Catalogues all - six verbs (must / trust / intend / adjust / bust / dust) with their *actual - current locations* across the three pre-consolidation trees, flags the - duplicate `trust` Trustfile, and records the canonical trident target. The - physical consolidation of the three trees stays in #124 — it couples to the - `contractile gen-just` generator (which reads the root `contractiles/` tree) - and needs the standards CONTRACTILE-SPEC to do safely. - -### Added — `assay` / `assimilate` / `aggregate` proof-integration subcommands - -Three new a-themed subcommands that wire panic-attack into the -PROOF-PROGRAMME loop (survey → swap → fold-in-proofs): - -- **`panic-attack assay [TARGET] [--proven DIR]…`** (`src/assay/mod.rs`): - surveys a target for code that has a formally proven drop-in equivalent - in a `proven` / `proven-servers` library and reports each candidate with - the proof artifact that backs it — operationalising the "Proven cross-fit" - table in `PROOF-PROGRAMME.md` mechanically instead of by hand. Built-in - catalogue: `SafePath` (canonicalize/unwrap pattern) and `SafeUrl` - (`VERISIMDB_URL`). On this repo: `safe-path` **Offered** (port present in - `src/safe_path.rs`, call sites still to rewire), `safe-url` - **NoReplacementSource** (not yet ported). -- **`panic-attack assimilate [TARGET] --candidate ID [--proven DIR] [--from FILE] [--all] [--dry-run]`**: - performs a swap — stages the proven module into the tree, backs up the - original (`*.orig`), and writes a provenance record (source BLAKE3 hash + - proof backing + pending call-site rewires) under `.assimilated/`. Module - swaps are automatic; call-site rewiring is reported, never auto-edited - (mechanically editing arbitrary call sites is not a reviewable operation). -- **`panic-attack aggregate --proof PATH… [--label PATH=NAME] [--covers PATH=SPEC] [--report BASE]`** - (`src/aggregate/mod.rs`): folds external prover output (Agda / Idris2 / - Coq·Rocq / Lean / Isabelle / TSTP / Alethe / DRAT·LRAT) into a report. Each - artifact is **BLAKE3-hashed for non-repudiation**, given a friendly name, - classified (Closed / Holes / Refuted / Indeterminate — comment-stripped so - prose mentioning `postulate` / `Admitted` does not false-trigger), and - reconciled against findings (**Backed / Corroborated / Contradicted**). - Every verdict is explicitly conditioned on the named checker's trust; the - recorded hash lets the tool show exactly which bytes it was handed if the - assessment is later challenged. `@name "…"` / `@covers [claim:]kind:value` - annotations travel inside the artifact; CLI `--label` / `--covers` override. - -Proof foundation re-verified from first principles under a fresh **Idris2 -0.8.0** install: `Types`, `Stripping` (Layer 1.0), `PatternCompleteness` -(PA1) and `ClassificationSoundness` (PA2) all typecheck. 17 new unit tests; -full library suite (395 tests) green; zero new compiler warnings. - -## [2.5.5] — 2026-06-02 - -Release of the v2.5.5 cohort that landed across 11 PRs in panic-attack + wiki + gitbot-fleet on 2026-06-02 PM. Tagged 2026-06-02 PM-evening. - -### Added (2026-06-02 PM) — v2.5.5 context-awareness cohort + v3.0.0 Chapel→VeriSimDB push + PROOF-PROGRAMME - -Eight PRs landed in one cohort closing the v2.5.5 ROADMAP section, a v3.0.0 item, and opening the first proof slice of the new PROOF-PROGRAMME. - -**v2.5.5 — Attack Surface Widening (false-positive reduction)** - -- **`test_context` foundation** (#102): new `src/test_context.rs` module with cross-language test-path classification (Rust / Python / Go / JavaScript / Julia / Zig / Elixir / docs-examples). New `WeakPoint.test_context: Option` field (Production / TestOnly / Doc) plumbed through 137 construction sites. Content-based promotion via `use ExUnit.Case` / `unittest.TestCase` / `pytest.fixture` / `@testset` markers. -- **`comment_marker` inline suppression** (#105): new `src/comment_marker.rs` module recognising `// panic-attack: accepted [- reason]` on the same or preceding line. Cross-language comment leaders: `//` mid-line for C-family; `#` / `--` / `;` / `%` / `///` / `//!` start-of-line for Python/Haskell/Lisp/Erlang/Rust-doc/Rust-inner-doc. String-literal aware. Shebang `#!` excluded. -- **`ffi_kind` subtyping** (#106): new `src/ffi_kind.rs` module subtyping `WeakPointCategory::UnsafeFFI` (PA013) into BuildSystem / RuntimeAbi / TestMock / Unknown. `classify_by_path` distinguishes `build.zig` / `build.rs` (BuildSystem, audit-accepted by default) from `bindings/` / `ffi/` / `sys/` / `cdef.zig` (RuntimeAbi, audit-significant) from `tests/mocks/` / `tests/stubs/` (TestMock, also audit-accepted). New `is_audited_boundary(audit_text, file_path)` parses `audits/audit-ffi-unsafe.md` `## Approved boundaries` markdown. -- **`jit_context` classifier** (#107): new `src/jit_context.rs` module classifying JIT frameworks — Cranelift / Llvm / Wasm / Javascript / None. Factors existing inline Cranelift detection at `analyzer.rs:1117..1129` into reusable surface. `transmute_targets_fn_ptr` made tolerant of `= unsafe { ... transmute(..) }` wrappers. -- **Phase 2 analyzer wire-up** (#110): new `apply_v255_context_suppression(&mut report)` runs after the kanren-based rule pass and (a) marker-flips `WeakPoint.suppressed = true` when `panic-attack: accepted` is on or above the line, (b) auto-suppresses `PanicPath` in TestOnly/Doc context, (c) auto-suppresses `UnsafeFFI` in BuildSystem/TestMock context. Sets `test_context` metadata on every finding with a known file path. - -**v3.0.0 — Distributed Scanning (HTTP push from Chapel)** - -- **`panic-attack verisim-push ` subcommand** (#108): new `Commands::VerisimPush` gated on the `http` Cargo feature. Reads a JSON hexad (typically what Chapel `takeSnapshot` just wrote), POSTs to `$VERISIMDB_URL` (default `http://localhost:8080`) via the existing `storage::push_hexad_http_with_retry`. `--fallback-dir` writes a JSON copy on HTTP failure for offline replay. -- **Chapel `takeSnapshot` overload** (#108): new 6-arg form accepting `verisimPushUrl` + `panicAttackBin` parameters. Spawns `panic-attack verisim-push --url --retry ` after local hexad write. Local writes remain authoritative; push is additive. Closes the `[ ]` ROADMAP item. - -**PROOF-PROGRAMME — first-principles soundness** - -- **`PROOF-PROGRAMME.md`** (#104): 3-layer landscape (Surface / Engine / Persistence) covering all 25 PA-code soundness proofs + miniKanren correctness + bridge reachability + attestation chain unforgeability. 9-phase sequencing (~16 weeks). Identifies `proven` cross-fit candidates: only `SafePath` + `SafeUrl` qualify as port-to-Rust (perf-neutral, semantic-equivalent); `SafeJson` / `SafeRegex` / `SafeDateTime` / `SafeCommand` / `SafeEnv` / `SafeUUID` marked skip (already total / semantic mismatch). -- **Layer 1.0 partial** (#111): new `src/abi/Stripping.idr` Qed-closing the foundation lemmas for line-comment stripping — `stripBodyProducesStrippedShape` (every body output satisfies `IsStrippedBody`) + base cases of `stripLineCommentsIdempotent` (empty + non-slash-headed input). Open: the slash-slash inductive closure `stripIsIdentityOnStrippedBody` (recorded as the next Layer-1.0 slice in `PROOF-NEEDS.md`). - -### Changed (2026-06-02) — truthfulness audit (humans + machines) -- **README badge + Status block** corrected: 402 → **782 runnable tests** - (per `cargo test --release -- --list`; the underlying 539 `#[test]` - annotations expand via doctests + integration tiers). The badge had - not tracked actual count for several releases. Wiki Home was `282+`. -- **chapel-ci `chapel-multilocale` gate** robustified (#100 collateral): - pinned `CHPL_UNWIND=system` explicitly + moved `libunwind-dev` install - to always-run (not gated on cache-hit). On cache-hit runs without - libunwind-dev, chpl auto-inferred `CHPL_UNWIND=bundled` and aborted - with "no runtime for bundled" because the cached runtime was built - with `system`. Cache-gen counter bumped `v1` → `v2` to discard the - inconsistent cache. Fifth Chapel-2.8.0 sharp edge from #99 Wave 2. -- **ROADMAP v2.2.0**: downgraded "Per-project VeriSimDB instance: - `deploy/panic-attack/fly.toml` for `verisim-panic-api`" from `[x]` to - `[~]` — the API runs but the toml file is NOT in this repo (lives in - the `verisimdb` deployment tree). The `[x]` checkbox previously - pointed at a path that didn't exist on `main`. -- **ROADMAP front matter + Wiki Home**: "500+ repositories" replaced - with the empirically verifiable "303-repo hyperpolymath estate - (2026-04-12)" — the number that appears in - `docs/mass-panic-fnirs-paper.adoc` Table I. -- **`chapel/README.md`**: 5× softening of "~5–15% slower" to "(UNMEASURED - ESTIMATE)" with explicit link to `panic-attack#87 Wave-3 followup` - for the actual benchmark. -- **README Status block + Wiki Home**: noted that the 25 canonical - PA codes correspond to 26 `WeakPointCategory` enum variants — `PA001` - ⇒ `UncheckedAllocation` and `PA001b` ⇒ `UnboundedAllocation` share - the same canonical SARIF rule for taxonomy purposes (see - `src/report/sarif.rs`). - -### Added (2026-06-01) — Chapel Wave 2: single-host multilocale gate -- **`chapel-multilocale` CI gate** (#99, closes #87 option A): adds a 7th - strict chapel-ci job that builds Chapel 2.8.0 from source with - `CHPL_COMM=gasnet` + `CHPL_COMM_SUBSTRATE=smp` + `CHPL_LAUNCHER=smp`, - caches `$CHPL_HOME` (`actions/cache@v4`, stable key with manual - `CHAPEL_MULTILOCALE_CACHE_GEN` invalidation counter; cold build - ~30-40 min, warm restore ~30s for 7 days), runs - `mass-panic --numLocales=2` against a synthetic 2-repo corpus, and - greps the emitted `system-image-*.json` for both repo names to prove - cross-locale aggregation actually executed. The Wave 1 binary `.deb` - install path is single-locale only; this gate closes the gap. -- Aggregator `chapel-ci-gate` updated to wait on the 7th job and to - surface it as `multilocale=` in the gate summary. -- Wave 3 (`gasnet/ofi` over a real NIC across cluster nodes) and the - ~50-repo "~5-15% slower" benchmark from `chapel/README.md` remain - parked — both need a beefier or self-hosted runner to be meaningful. - -### Fixed (2026-06-01) — baseline-red corrective maintenance -- **Dogfood Gate A2ML validation** restored (#94, #97): bumped - `hyperpolymath/a2ml-validate-action` from `59145c7d` to `6bff6ec` to - pick up s-expression-form identity/version recognition (upstream - PR #26); relocated `docs/campaigns/2026-05-26.a2ml` to - `.machine_readable/campaigns/` so it inherits the structural-identity - exemption (the file's own header describes it as - "machine-readable A2ML form"). -- **Governance Trusted-base reduction policy** restored (#94): added - `.trusted-base-ignore` exemption for `src/assail/analyzer.rs` — the - file IS the scanner that defines the escape-hatch patterns, so its - literal references to them are by design. -- **Secret Scanner rust-secrets** false-positive cleared (#94): - refactored `RE_HARDCODED_SECRET` regex construction via `concat!` to - split detector keywords across source-string boundaries (the literal - `password` keyword in the source was self-flagging). -- **Rust CI reusable** SHA bumped past `standards#334` (#97) — caller - now resolves the - `${{ }}`-wrapped job-level `if:` fix and unblocks the `rust-ci.yml` - wrapper that was reporting 0-second parse failures (root cause - documented at `standards#322`). -- **rsr-template scaffolding gaps filled** (#96): LICENSE flipped from - AGPL-3.0 body to MPL-2.0 (matching SPDX headers + Cargo.toml + - README.adoc); CODE_OF_CONDUCT.md placeholders instantiated - (`{{CONDUCT_EMAIL}}` → `j.d.a.jewell@open.ac.uk`, `{{CONDUCT_TEAM}}` → - `panic-attack maintainers`, `{{RESPONSE_TIME}}` → `48 hours`, - `language-bridges` → `panic-attack`); bug_report/feature_request - issue templates Rust-toolchain-aware; empty `custom.md` removed; - SECURITY.md version table updated from `0.2.x` to `2.5.x`. - -### Changed (2026-06-01) -- **Dependabot rust-minor group bumps** (#93): `log` 0.4.29 → 0.4.30, - `eframe` minor update. - -### Added (2026-05-30) — issue #33 closure -- **VeriSimDB hexad persistence complete (issue #33 S1–S3)** — per-finding - hexads, campaign state lifecycle, and S-expression query DSL all shipped: - - **S1**: per-finding hexad emission gated by - `PANIC_ATTACK_STORE_FINDING_HEXADS=1` (`src/storage/mod.rs :: - build_finding_hexads`, subject format - `finding::::`). - - **S2**: `panic-attack campaign` subcommand (`register-pr`, `dismiss`, - `status`, `poll`) drives finding lifecycle with state transitions - persisted as campaign hexads. `poll` performs GitHub PR state - transitions (open → pr-filed → pr-merged / pr-closed). - - **S3**: `panic-attack query ` evaluates a small S-expression - language over the persisted hexads. Heads: `category`, `rule-id`, - `severity`, `repo`, `file`, `pr-state`, `since`, `crosslang`, `diff`, - `and`, `or`, `not`. -- **Query parser: `(diff :since :category ...)` head + inline `:keyword - VALUE` kwargs on every unary head** (`src/query/mod.rs`). The issue - body's three literal example expressions now parse verbatim: - - `(crosslang :from FFI :to ProofDrift)` — already worked. - - `(category PA001 :severity Critical :pr-state nil)` — now parses as - `(and (rule-id PA001) (severity Critical) (pr-state nil))`, with - PA-prefixed values on `category` auto-routed to `rule-id` so the - query actually matches findings. - - `(diff :since 2026-04-12 :category PA022)` — new `diff` head is - keyword-only sugar for an `(and ...)` over its kwarg pairs. - Inline kwargs are accepted on `category`, `rule-id`, `severity`, `repo`, - `file`, `pr-state`, and `since` — adding a `:keyword VALUE` after the - positional value desugars to `(and (head positional) (kw value) ...)`. - Behaviour unchanged for existing query expressions; 12 new unit tests. - -### Added (2026-04-18) -- **User-classification registry** (`assail::UserClassification`, - `load_user_classifications`, `apply_user_classifications`): panic-attack - now reads an optional project-local classification file at every assail - pass and flips matching findings to `suppressed = true` after the kanren - structural-suppression pass. Two lookup paths: - - `/audits/assail-classifications.a2ml` (preferred) - - `/.panic-attack-classifications.a2ml` (fallback) - File format is a simple A2ML S-expression with `(classification (file …) - (category …) (audit …) (rationale …))` blocks; `;;` line comments - ignored. The registry pattern lets repositories record audited findings - out-of-band from the source under scan so a PR adding a new unsafe - block cannot self-suppress without a reviewable companion edit to - the registry. -- **Rocq scaffold classifier** (`analyze_coq` + - `count_rocq_unverified_postulates` + `is_rocq_abstraction_parameter`): - the Rocq detector no longer counts Section-scoped `Variable` / - `Hypothesis` / `Parameter` declarations (they discharge at `End - Section`) and classifies module-level `Parameter` declarations by - stated type: carrier types (`Type`, `Set`), decidability witnesses - (`forall _, { _ = _ } + { _ <> _ }`), and function types with a - concrete non-Prop codomain are treated as abstraction parameters. - Prop-valued declarations (classical excluded-middle, choice, - unresolved theorem statements) remain counted. Removes the - false-positive stream that surfaced on every canonical-proof-suite - scaffold. - -### Changed -- **Suppression pipeline**: `analyze()` and `analyze_verbose()` now - chain `apply_suppression` → `apply_user_classifications` in that - order; the explicit post-analyze calls in `assail::analyze` and - `assail::analyze_verbose` at the module boundary are retained for - API-contract clarity but are no-ops when an `Analyzer` pass has - already run. -- **Rocq test coverage**: 12 new unit tests across `analyzer.rs` - (Section-scoped Variables / module-level Type carriers / decidable - equality / concrete-codomain functions / Prop-valued axioms / - missing type annotation / full scaffold shape — 7 tests) and - `mod.rs` (missing-registry / single-entry / multiple-entry / - comment handling / end-to-end suppression-flip — 5 tests). - -### Verified -- 007 canonical-proof-suite scan: active finding count **8 → 0** - (the 6 scaffold ProofDrifts via the detector enhancement, the 2 - `zig_bridge.rs` UnsafeCode findings via the classification registry - pointing at `audits/audit-ffi-unsafe.md §1`). No in-source - suppression markers added to either repo. - -## [2.5.0] - 2026-04-12 - -### Added -- **InputBoundary category (PA024)**: New weak point category detecting unguarded structured-data - parsing at trust boundaries. - - **Rust**: `serde_cbor::from_slice`/`from_reader`, `ciborium::de::from_reader`, - `rmp_serde::from_slice`/`from_read` — CBOR/MessagePack deserialization without a - validation layer (Medium). All five crate patterns flagged. - - **JavaScript/ReScript**: `JSON.parse(` in files without any `try`/`catch` context (High). - Files that do wrap their JSON.parse in try/catch are not flagged. - - **Julia**: `JSON3.read(` and `JSON.parse(` without error handling context (High). - - Taint tracking from external reads to trust-sensitive sinks deferred to kanren phase. - - A2ML boundary detection deferred — requires cross-file analysis. -- **PA024 → panicbot**: InputBoundary mapped to `static-analysis/input-boundary`, 0.72 - confidence, Control tier, Partial fixability. -- **MutationGap category (PA025)**: New weak point category detecting mutation and chaos - coverage gaps in test suites. - - **Rust** (project-level): Tests present (`mod tests` / `#[cfg(test)]`) but no - `cargo-mutants` config in `Cargo.toml` or `mutants.toml` — mutation tooling absent (Low). - - **Julia** (per-file): `@testset` blocks where every `@test` is a type-check assertion - (`@test … isa …`) with no value assertions — no assertion diversity (Medium). - - **Elixir** (per-file): Test files using `ExUnit.Case` without importing `ExUnitProperties` - or `StreamData` for property-based testing (Low). - - Coverage-plus-mutation-score check deferred — requires runtime coverage data. -- **PA025 → panicbot**: MutationGap mapped to `static-analysis/mutation-gap`, 0.80 - confidence, Substitute tier, Partial fixability. -- **Idris2 ABI completeness**: `PatternCompleteness.idr` updated — InputBoundary (Rust/JS/Julia) - and MutationGap (Rust/Julia/Elixir) added to `WPCategory` with `detectorsFor` entries. - -### Changed -- **Category count**: 23 → 25 (added InputBoundary, MutationGap) -- **v2.5.0 milestone**: All tractable items complete. Two deferred items each for - `input_boundary` (taint+A2ML) and `mutation` (coverage-score), and three for - `crypto_misuse` (key-reuse, nonce-reuse, sig-verify) marked as statically undetectable - or requiring runtime data. - -## [2.3.0] - 2026-04-12 - -### Added -- **CryptoMisuse category (PA022)**: New weak point category detecting cryptographic primitive - misuse across five languages. Context-window heuristic (±200 chars) restricts MD5/SHA-1 - findings to security-sensitive usage — MD5 for file checksums is not flagged. - - **Rust**: `md5::compute`/`Md5::new` and `sha1::Sha1`/`Sha1::new` in security context (High); - `==` comparison on `secret`/`password`/`token`/`key` variables (Critical — timing attack). - - **Python**: `hashlib.md5()`/`hashlib.sha1()` in security context (High); - `==` on secret-named variables — use `hmac.compare_digest()` instead (Critical). - - **JavaScript**: `crypto.createHash('md5')` and `crypto.createHash('sha1')` (High); - `crypto.createHash('sha256')` is fine and not flagged. - - **Go**: `md5.New()`/`md5.Sum()` and `sha1.New()`/`sha1.Sum()` in security context (High). - - **Elixir**: `:crypto.hash(:md5, ...)` and `:crypto.hash(:sha, ...)` (High); - `:crypto.mac(:hmac, :sha, ...)` is acceptable (HMAC-SHA1 is not broken) and not flagged. - - Key-reuse and nonce-reuse deferred — not reliably detectable statically. -- **has_security_context() helper**: Module-level helper function checks ±200 char window - around a pattern match for security vocabulary (password, secret, token, auth, key, - credential, hash, sign, verify, encrypt) to reduce false positives on benign MD5/SHA-1 use. -- **PA022 → panicbot**: CryptoMisuse mapped to fleet category `static-analysis/crypto-misuse` - with 0.75 confidence, Eliminate tier, Partial fixability. Confidence is honest — the context - window has a modest false-positive rate when security vocabulary appears for unrelated reasons. -- **Idris2 ABI completeness**: `PatternCompleteness.idr` updated — CryptoMisuse added to - `WPCategory` with `detectorsFor` covering Rust, Python, JavaScript, Go, Elixir. - -## [2.2.0] - 2026-04-12 - -### Added -- **SupplyChain category (PA023)**: New weak point category detecting dependency and build - integrity gaps: `Cargo.toml` git dependencies without `rev =`, absent `Cargo.lock` for - library/binary crates, Julia `Manifest.toml` without `git-tree-sha1` hash entries, - `flake.nix` inputs without `narHash`, and `deno.json` import map entries without a version - pin. Project-level manifest checks run as a synthesis stage after file analysis. - Confidence 0.85 — these are explicit manifest/config patterns with low false-positive rate. -- **PA023 → panicbot**: SupplyChain mapped to fleet category `static-analysis/supply-chain` - with 0.85 confidence, Eliminate tier, fixable (adding pins resolves the finding). -- **Idris2 ABI completeness**: `PatternCompleteness.idr` updated — SupplyChain added to - `WPCategory` with `detectorsFor` covering Rust, Julia, Nix, JavaScript. - -### Changed -- **Category count**: 22 → 23 (added SupplyChain) - -## [2.1.0] - 2026-04-12 - -### Added -- **ProofDrift category (PA021)**: New weak point category detecting formal verification drift - across all proof assistant languages. Catches banned proof escape hatches (`sorry`, `Admitted`, - `believe_me`, `oops`, `trustMe`, `assert_total`, `%partial`, `{-# TERMINATING #-}`) and - Julia mirror files substituting `@test x isa Y` or `# sorry` comments for formal proofs. - Confidence 0.92 — proof escape hatches have essentially no false positives in their file types. -- **Isabelle/HOL language support**: `.thy` files parsed with `analyze_isabelle()` detecting - `sorry`, `oops`, and `axiomatization` as ProofDrift findings. -- **Coq/Rocq language support**: `.v` files parsed with `analyze_coq()` detecting `Admitted`, - `admit` tactic, `Axiom`/`Parameter` declarations, and `Obj.magic` in extraction artifacts. -- **Isabelle + Coq dispatch**: Both new languages wired into `analyze_inner()` dispatch. -- **Lean4 ProofDrift upgrade**: `sorry` upgraded from UnsafeCode → ProofDrift (Critical). - Added `unsafeNativeIO`/`unsafeBaseIO` as ProofDrift (IO discipline bypass). -- **Agda ProofDrift upgrade**: `trustMe`/`primTrustMe` upgraded to ProofDrift (Critical). - Added `{-# TERMINATING #-}`, `{-# NON_TERMINATING #-}`, bare `postulate` as ProofDrift. -- **Idris2 ProofDrift upgrade**: `believe_me` already ProofDrift; added `assert_total` (High) - and `%partial` (Medium) as ProofDrift findings. -- **Julia mirror detection**: `# sorry`, `# TODO: prove`, `# admitted` comments and - `@test x isa Y` patterns (no value check) flagged as ProofDrift in Julia files. -- **FP suppression wiring**: `apply_suppression()` now runs on every scan, marking - weak points `suppressed: true` when logic engine finds defensive-pattern context. - Suppressed items stay in report for audit transparency; filtered by panicbot and CI gates. -- **PA021 → panicbot**: ProofDrift mapped to fleet category `static-analysis/proof-drift` - with 0.92 confidence and Control tier. -- **Idris2 ABI completeness**: `PatternCompleteness.idr` updated — Isabelle, Coq added to - `Lang` enum; ProofDrift added to `WPCategory` with `detectorsFor` covering all new languages. -- **Hypatia integration**: JSON AssailReport consumed by Hypatia Elixir rules. Logtalk - export removed 2026-04-12. - -### Changed -- **Language count**: 47 → 49 (added Isabelle, Coq) -- **Category count**: 20 → 21 (added ProofDrift) -- **Verbose output**: Two views — filtered (active, what CI sees) and unfiltered (total, - audit transparency) with explicit labelling of what each count means. - -## [2.0.0+] - 2026-03-23 - -### Fixed -- **A2ML parser**: Now handles TOML-like format (key = "value") in addition to S-expression format -- **Manifest lookup**: Tries `0-AI-MANIFEST.a2ml` first before falling back to `AI.a2ml` -- **Language detection**: Skips `external_corpora/`, `third_party/`, and `corpus/` directories to avoid false positives from vendored or reference text - -## [2.0.0+] - 2026-03-01 - -### Added -- **SARIF output format**: `--output-format sarif` for GitHub Security tab integration -- **Assemblyline batch scanning**: Scan entire directories of repos with `assemblyline` subcommand - - Rayon parallelism: 17.7x speedup (141 repos in 39.9s) - - BLAKE3 fingerprinting for incremental scanning (infrastructure ready) - - Sorted output: riskiest repos first -- **Notification pipeline**: `notify` subcommand generates annotated finding summaries - - Markdown output with severity breakdown per repo - - `--critical-only` flag for filtering - - `--create-issues` for GitHub issue creation -- **Cryptographic attestation chain**: Three-phase model (intent, evidence, seal) - - Pre-execution commitment hashing - - Rolling evidence accumulator - - Post-execution binding with optional Ed25519 signing (`--features signing`) - - A2ML envelope wrapper for attestation bundles -- **i18n support**: ISO 639-1, 10 languages (en, fr, de, es, it, pt, ja, zh, ko, ar) - - Compile-time safe catalog with `t()` and `t_or_key()` lookups - - Doc-tested examples -- **Panicbot integration**: JSON output contract verified for gitbot-fleet - - PA001-PA020 rule mapping for all 20 WeakPointCategory variants - - Bot directives at `.machine_readable/bot_directives/panicbot.scm` - - Diagnostics self-check for panicbot readiness -- **Machine-verifiable readiness tests**: 18 tests across CRG grades D/C/B - - Grade D (Alpha): component runs without crashing - - Grade C (Beta): correct output on representative input - - Grade B (RC): edge cases and multi-language support -- **Justfile**: build, test, readiness, readiness-summary, clean, install, dogfood, lint recipes -- **Manifest-first framework detection**: Detects frameworks from Cargo.toml, mix.exs, package.json etc. instead of source scanning (eliminates false positives) - -### Fixed -- **Framework detection false positives**: Self-referential matches eliminated by using dependency manifests as primary signal; Rust source scanning removed entirely -- **All compiler warnings**: 0 warnings in both release and test builds -- **Test count**: 269 tests (up from ~30), 0 failures - -### Changed -- **Diagnostics**: Now checks panicbot integration readiness (JSON contract, directives) -- **AI.a2ml**: Added panicbot, updated SARIF format, corrected metadata -- **ECOSYSTEM.scm**: Added panicbot with full interface documentation -- **STATE.scm**: Updated with all session 8/9 capabilities and outcomes - -## [2.0.0] - 2026-02-08 - -### Added -- **47-language support**: BEAM (Elixir, Erlang, Gleam), ML (ReScript, OCaml, SML), Lisp (Scheme, Racket), Functional (Haskell, PureScript), Proof (Idris, Lean, Agda), Logic (Prolog, Logtalk, Datalog), Systems (Zig, Ada, Odin, Nim, Pony, D), Config (Nickel, Nix), Scripting (Shell, Julia, Lua), plus 12 nextgen DSLs -- **20 weak point categories**: UnsafeCode, PanicPath, CommandInjection, UnsafeDeserialization, DynamicCodeExecution, UnsafeFFI, AtomExhaustion, InsecureProtocol, ExcessivePermissions, PathTraversal, HardcodedSecret, UncheckedError, InfiniteRecursion, UnsafeTypeCoercion, UncheckedAllocation, UnboundedLoop, BlockingIO, RaceCondition, DeadlockPotential, ResourceLeak -- **miniKanren-inspired logic engine** (`src/kanren/`): - - Substitution-based unification - - Forward chaining: derives vulnerability facts from rules - - Backward queries: find files by vulnerability category - - Taint analysis: source-to-sink data flow tracking - - Cross-language vulnerability chain detection (FFI/NIF/Port/subprocess) - - Search strategy auto-selection (RiskWeighted, BoundaryFirst, LanguageFamily, BreadthFirst, DepthFirst) -- **PanLL event-chain export**: DAW-style timeline export for visualisation -- **Ambush timeline scheduling**: Stressor sequencing with timeline files -- **Report views**: Summary, accordion, dashboard, matrix views + TUI viewer -- **Nickel output format** - -### Changed -- **Renamed**: xray -> assail, XRayReport -> AssailReport, src/xray/ -> src/assail/ -- **Renamed**: panic-attacker binary -> panic-attack - -## [1.0.1] - 2026-02-07 - -### Fixed -- **CI/CD workflows**: All GitHub Actions now passing - - Updated MSRV from 1.75.0 to 1.85.0 (required for Cargo.lock v4 format) - - Fixed invalid codeql-action SHA pins - - Fixed TruffleHog configuration - - Fixed EditorConfig indentation violations -- **Code quality**: Resolved clippy warnings, removed unused imports - -### Changed -- **MSRV**: Updated from 1.75.0 to 1.85.0 - -## [1.0.0] - 2026-02-07 - -### Added -- **Production-ready infrastructure**: RSR compliance, 11 workflows, docs -- **Testing**: 21 unit + 3 integration + 3 regression tests -- **Configuration**: Config file support, EditorConfig, MSRV policy - -## [0.2.0] - 2026-02-07 - -### Fixed -- **Weak points now per-file**: Eliminates duplicates (echidna: 271 -> 15) -- **File locations always populated**: No more `location: None` - -### Added -- FileStatistics, Latin-1 fallback, verbose mode, pattern library, integration tests - -## [0.1.0] - 2026-02-06 - -Initial proof-of-concept: Assail static analysis, multi-axis stress testing, logic-based bug signature detection. diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..e53d1cf --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,339 @@ +== Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +panic-attack a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, colour, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +We recognise that a thriving open source community requires +*psychological safety* — an environment where people can contribute, ask +questions, make mistakes, and learn without fear of ridicule or +retaliation. + +''''' + +=== Our Standards + +==== Expected Behaviour + +The following behaviours contribute to a positive environment: + +*Communication* - Using welcoming and inclusive language - Being +respectful of differing viewpoints and experiences - Giving and +gracefully accepting constructive feedback - Assuming good intent while +addressing impact - Communicating clearly and patiently, especially with +newcomers + +*Collaboration* - Focusing on what is best for the community - Showing +empathy and kindness toward other community members - Being +collaborative rather than competitive - Mentoring and supporting less +experienced contributors - Celebrating others’ contributions and +successes + +*Professionalism* - Accepting responsibility and apologising to those +affected by our mistakes - Learning from the experience and avoiding +repetition - Respecting others’ time and attention - Staying on topic in +project spaces - Following project guidelines and conventions + +*Accessibility* - Using plain language and avoiding unnecessary jargon - +Providing alt text for images and transcripts for audio/video - Being +patient with those using assistive technologies - Accommodating +different communication styles and needs - Recognising that not everyone +communicates the same way + +==== Unacceptable Behaviour + +The following behaviours are considered harassment and are unacceptable: + +*Harassment* - The use of sexualised language or imagery, and sexual +attention or advances of any kind - Trolling, insulting or derogatory +comments, and personal or political attacks - Public or private +harassment - Deliberate intimidation, stalking, or following (online or +in-person) - Unwelcome physical contact or simulated physical contact +(e.g., emoji) - Sustained disruption of talks, events, or online +discussions + +*Discrimination* - Discriminatory jokes and language - Posting or +threatening to post others’ personally identifying information +("`doxing`") - Advocating for, or encouraging, any of the above +behaviour - Microaggressions — subtle, often unintentional, +discriminatory comments or actions + +*Professional Misconduct* - Publishing others’ private information +without explicit permission - Misrepresenting affiliation or +contributions - Plagiarism or claiming credit for others’ work - +Retaliating against anyone who reports a Code of Conduct violation - +Other conduct which could reasonably be considered inappropriate in a +professional setting + +==== Grey Areas + +Some situations require judgement. When uncertain: + +* *Intent vs Impact*: Good intentions do not excuse harmful impact. +Focus on making things right. +* *Power Dynamics*: Those with more power (maintainers, employers, +experienced contributors) must be especially mindful of their impact. +* *Cultural Differences*: What’s acceptable varies by culture. When in +doubt, err on the side of caution and ask. +* *Humour*: Jokes at others’ expense are rarely funny to everyone. Punch +up, not down. + +''''' + +=== Scope + +This Code of Conduct applies within all community spaces, including: + +*Online Spaces* - Repository discussions, issues, and pull/merge +requests - Project chat channels (Matrix, Discord, Slack, IRC) - Mailing +lists and forums - Social media when representing the project - Video +calls and virtual meetings + +*In-Person Spaces* - Conferences, meetups, and events - Workshops and +training sessions - Any gathering where you represent the project + +*Representation* This Code of Conduct also applies when an individual is +officially representing the community in public spaces. Examples +include: + +* Using an official project email address +* Posting via an official social media account +* Acting as an appointed representative at an event +* Speaking on behalf of the project + +''''' + +=== Enforcement + +==== Reporting + +If you experience or witness unacceptable behaviour, or have any other +concerns, please report it as soon as possible. + +*How to Report* + +[width="99%",cols="30%,33%,37%",options="header",] +|=== +|Method |Details |Best For +|*Email* |j.d.a.jewell@open.ac.uk |Detailed reports, sensitive matters + +|*Private Message* |Contact any maintainer directly |Quick questions, +minor issues + +|*Anonymous Form* |[Link to form if available] |When you need anonymity +|=== + +*What to Include* + +* Your contact information (unless anonymous) +* Names/usernames of those involved +* Description of what happened +* When and where it occurred +* Any witnesses +* Any supporting evidence (screenshots, links) +* How you would like us to respond (if you have a preference) + +*What Happens Next* + +[arabic] +. You will receive acknowledgment within *48 hours* +. The panic-attack maintainers will review the report +. We may ask for additional information +. We will determine appropriate action +. We will inform you of the outcome (respecting others’ privacy) + +==== Confidentiality + +All reports will be handled with discretion: + +* Reporter identity is protected by default +* Details are shared only with those who need to know +* We will ask before naming you in any communication +* Anonymous reports are accepted and investigated + +==== Conflicts of Interest + +If a panic-attack maintainers member is involved in an incident: + +* They will recuse themselves from the process +* Another maintainer or external party will handle the report +* We will disclose any potential conflicts + +''''' + +=== Enforcement Guidelines + +The panic-attack maintainers will follow these guidelines in determining +consequences: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behaviour +deemed unprofessional or unwelcome. + +*Consequence*: A private, written warning providing clarity around the +nature of the violation and an explanation of why the behaviour was +inappropriate. A public apology may be requested. + +*Duration*: Immediate + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behaviour. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period. This +includes avoiding interactions in community spaces as well as external +channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +*Duration*: 1-4 weeks + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behaviour. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period. No public or +private interaction with the people involved, including unsolicited +interaction with those enforcing the Code of Conduct, is allowed during +this period. Violating these terms may lead to a permanent ban. + +*Duration*: 1-6 months + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behaviour, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +*Duration*: Permanent (with appeal rights after 12 months) + +==== Enforcement Across Perimeters + +For contributors with elevated access (Perimeter 2 or 1): + +[cols=",",options="header",] +|=== +|Level |Additional Consequence +|Correction |Noted in contributor record +|Warning |Access privileges may be temporarily reduced +|Temporary Ban |Access reduced to Perimeter 3 for ban duration +|Permanent Ban |All access revoked +|=== + +''''' + +=== Appeals + +If you believe an enforcement decision was made in error: + +[arabic] +. *Wait 7 days* after the decision (cooling-off period) +. *Email* j.d.a.jewell@open.ac.uk with subject line "`Appeal: [Original +Report ID]`" +. *Explain* why you believe the decision should be reconsidered +. *Provide* any new information not previously available + +*Appeals Process* + +* Appeals are reviewed by a different panic-attack maintainers member +than the original +* You will receive a response within 14 days +* The appeals decision is final +* You may only appeal once per incident + +*Grounds for Appeal* + +* Procedural errors in the original investigation +* New evidence not previously available +* Disproportionate response to the violation +* Misunderstanding of facts + +''''' + +=== Supporting Those Who Report + +We are committed to supporting those who report violations: + +*We Will* - Believe and take all reports seriously - Respect your +privacy and confidentiality preferences - Keep you informed of progress +(if you wish) - Take steps to protect you from retaliation - Provide +resources if you need support + +*We Will Not* - Require you to confront the person directly - Dismiss +reports without investigation - Reveal your identity without consent - +Tolerate retaliation against reporters - Rush you to make decisions + +''''' + +=== Prevention + +Beyond enforcement, we actively work to prevent issues: + +*Onboarding* - All contributors are expected to read this Code of +Conduct - Perimeter 2 applicants must confirm they’ve read and +understood it - Maintainers receive additional training on enforcement + +*Culture* - We model the behaviour we expect - We intervene early when +we see potential issues - We thank people for positive contributions - +We create opportunities for diverse voices + +*Review* - This Code of Conduct is reviewed annually - Community +feedback is welcomed - Changes are communicated clearly + +''''' + +=== Acknowledgments + +This Code of Conduct is adapted from: + +* https://www.contributor-covenant.org/[Contributor Covenant], version +2.1 +* https://www.djangoproject.com/conduct/[Django Code of Conduct] +* https://www.rust-lang.org/policies/code-of-conduct[Rust Code of +Conduct] +* https://www.python.org/psf/conduct/[Python Community Code of Conduct] + +We thank these communities for their leadership in creating welcoming +spaces. + +''''' + +=== Questions? + +If you have questions about this Code of Conduct: + +* Open a +https://github.com/hyperpolymath/panic-attack/discussions[Discussion] +(for general questions) +* Email j.d.a.jewell@open.ac.uk (for private questions) +* Contact any maintainer directly + +''''' + +=== Summary + +*Be kind. Be respectful. Be collaborative.* + +We’re all here because we care about this project. Let’s make it a place +where everyone can do their best work. + +''''' + +Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 525ecf9..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,309 +0,0 @@ - - -# Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in panic-attack a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, caste, colour, religion, or sexual identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. - -We recognise that a thriving open source community requires **psychological safety** — an environment where people can contribute, ask questions, make mistakes, and learn without fear of ridicule or retaliation. - ---- - -## Our Standards - -### Expected Behaviour - -The following behaviours contribute to a positive environment: - -**Communication** -- Using welcoming and inclusive language -- Being respectful of differing viewpoints and experiences -- Giving and gracefully accepting constructive feedback -- Assuming good intent while addressing impact -- Communicating clearly and patiently, especially with newcomers - -**Collaboration** -- Focusing on what is best for the community -- Showing empathy and kindness toward other community members -- Being collaborative rather than competitive -- Mentoring and supporting less experienced contributors -- Celebrating others' contributions and successes - -**Professionalism** -- Accepting responsibility and apologising to those affected by our mistakes -- Learning from the experience and avoiding repetition -- Respecting others' time and attention -- Staying on topic in project spaces -- Following project guidelines and conventions - -**Accessibility** -- Using plain language and avoiding unnecessary jargon -- Providing alt text for images and transcripts for audio/video -- Being patient with those using assistive technologies -- Accommodating different communication styles and needs -- Recognising that not everyone communicates the same way - -### Unacceptable Behaviour - -The following behaviours are considered harassment and are unacceptable: - -**Harassment** -- The use of sexualised language or imagery, and sexual attention or advances of any kind -- Trolling, insulting or derogatory comments, and personal or political attacks -- Public or private harassment -- Deliberate intimidation, stalking, or following (online or in-person) -- Unwelcome physical contact or simulated physical contact (e.g., emoji) -- Sustained disruption of talks, events, or online discussions - -**Discrimination** -- Discriminatory jokes and language -- Posting or threatening to post others' personally identifying information ("doxing") -- Advocating for, or encouraging, any of the above behaviour -- Microaggressions — subtle, often unintentional, discriminatory comments or actions - -**Professional Misconduct** -- Publishing others' private information without explicit permission -- Misrepresenting affiliation or contributions -- Plagiarism or claiming credit for others' work -- Retaliating against anyone who reports a Code of Conduct violation -- Other conduct which could reasonably be considered inappropriate in a professional setting - -### Grey Areas - -Some situations require judgement. When uncertain: - -- **Intent vs Impact**: Good intentions do not excuse harmful impact. Focus on making things right. -- **Power Dynamics**: Those with more power (maintainers, employers, experienced contributors) must be especially mindful of their impact. -- **Cultural Differences**: What's acceptable varies by culture. When in doubt, err on the side of caution and ask. -- **Humour**: Jokes at others' expense are rarely funny to everyone. Punch up, not down. - ---- - -## Scope - -This Code of Conduct applies within all community spaces, including: - -**Online Spaces** -- Repository discussions, issues, and pull/merge requests -- Project chat channels (Matrix, Discord, Slack, IRC) -- Mailing lists and forums -- Social media when representing the project -- Video calls and virtual meetings - -**In-Person Spaces** -- Conferences, meetups, and events -- Workshops and training sessions -- Any gathering where you represent the project - -**Representation** -This Code of Conduct also applies when an individual is officially representing the community in public spaces. Examples include: - -- Using an official project email address -- Posting via an official social media account -- Acting as an appointed representative at an event -- Speaking on behalf of the project - ---- - -## Enforcement - -### Reporting - -If you experience or witness unacceptable behaviour, or have any other concerns, please report it as soon as possible. - -**How to Report** - -| Method | Details | Best For | -|--------|---------|----------| -| **Email** | j.d.a.jewell@open.ac.uk | Detailed reports, sensitive matters | -| **Private Message** | Contact any maintainer directly | Quick questions, minor issues | -| **Anonymous Form** | [Link to form if available] | When you need anonymity | - -**What to Include** - -- Your contact information (unless anonymous) -- Names/usernames of those involved -- Description of what happened -- When and where it occurred -- Any witnesses -- Any supporting evidence (screenshots, links) -- How you would like us to respond (if you have a preference) - -**What Happens Next** - -1. You will receive acknowledgment within **48 hours** -2. The panic-attack maintainers will review the report -3. We may ask for additional information -4. We will determine appropriate action -5. We will inform you of the outcome (respecting others' privacy) - -### Confidentiality - -All reports will be handled with discretion: - -- Reporter identity is protected by default -- Details are shared only with those who need to know -- We will ask before naming you in any communication -- Anonymous reports are accepted and investigated - -### Conflicts of Interest - -If a panic-attack maintainers member is involved in an incident: - -- They will recuse themselves from the process -- Another maintainer or external party will handle the report -- We will disclose any potential conflicts - ---- - -## Enforcement Guidelines - -The panic-attack maintainers will follow these guidelines in determining consequences: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behaviour deemed unprofessional or unwelcome. - -**Consequence**: A private, written warning providing clarity around the nature of the violation and an explanation of why the behaviour was inappropriate. A public apology may be requested. - -**Duration**: Immediate - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of actions. - -**Consequence**: A warning with consequences for continued behaviour. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban. - -**Duration**: 1-4 weeks - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including sustained inappropriate behaviour. - -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban. - -**Duration**: 1-6 months - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community standards, including sustained inappropriate behaviour, harassment of an individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the community. - -**Duration**: Permanent (with appeal rights after 12 months) - -### Enforcement Across Perimeters - -For contributors with elevated access (Perimeter 2 or 1): - -| Level | Additional Consequence | -|-------|----------------------| -| Correction | Noted in contributor record | -| Warning | Access privileges may be temporarily reduced | -| Temporary Ban | Access reduced to Perimeter 3 for ban duration | -| Permanent Ban | All access revoked | - ---- - -## Appeals - -If you believe an enforcement decision was made in error: - -1. **Wait 7 days** after the decision (cooling-off period) -2. **Email** j.d.a.jewell@open.ac.uk with subject line "Appeal: [Original Report ID]" -3. **Explain** why you believe the decision should be reconsidered -4. **Provide** any new information not previously available - -**Appeals Process** - -- Appeals are reviewed by a different panic-attack maintainers member than the original -- You will receive a response within 14 days -- The appeals decision is final -- You may only appeal once per incident - -**Grounds for Appeal** - -- Procedural errors in the original investigation -- New evidence not previously available -- Disproportionate response to the violation -- Misunderstanding of facts - ---- - -## Supporting Those Who Report - -We are committed to supporting those who report violations: - -**We Will** -- Believe and take all reports seriously -- Respect your privacy and confidentiality preferences -- Keep you informed of progress (if you wish) -- Take steps to protect you from retaliation -- Provide resources if you need support - -**We Will Not** -- Require you to confront the person directly -- Dismiss reports without investigation -- Reveal your identity without consent -- Tolerate retaliation against reporters -- Rush you to make decisions - ---- - -## Prevention - -Beyond enforcement, we actively work to prevent issues: - -**Onboarding** -- All contributors are expected to read this Code of Conduct -- Perimeter 2 applicants must confirm they've read and understood it -- Maintainers receive additional training on enforcement - -**Culture** -- We model the behaviour we expect -- We intervene early when we see potential issues -- We thank people for positive contributions -- We create opportunities for diverse voices - -**Review** -- This Code of Conduct is reviewed annually -- Community feedback is welcomed -- Changes are communicated clearly - ---- - -## Acknowledgments - -This Code of Conduct is adapted from: - -- [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1 -- [Django Code of Conduct](https://www.djangoproject.com/conduct/) -- [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct) -- [Python Community Code of Conduct](https://www.python.org/psf/conduct/) - -We thank these communities for their leadership in creating welcoming spaces. - ---- - -## Questions? - -If you have questions about this Code of Conduct: - -- Open a [Discussion](https://github.com/hyperpolymath/panic-attack/discussions) (for general questions) -- Email j.d.a.jewell@open.ac.uk (for private questions) -- Contact any maintainer directly - ---- - -## Summary - -**Be kind. Be respectful. Be collaborative.** - -We're all here because we care about this project. Let's make it a place where everyone can do their best work. - ---- - -Last updated: 2026 · Based on Contributor Covenant 2.1 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..a5f1d98 --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,250 @@ +== Contributing to panic-attack + +Thank you for your interest in contributing to panic-attack! This +document provides guidelines and information for contributors. + +=== Code of Conduct + +This project follows the Contributor Covenant Code of Conduct. By +participating, you are expected to uphold this code. Please report +unacceptable behavior to j.d.a.jewell@open.ac.uk. + +=== How to Contribute + +==== Reporting Bugs + +Before creating bug reports, please check the existing issues to avoid +duplicates. When creating a bug report, include: + +* *Clear title* describing the issue +* *Detailed description* of the problem +* *Steps to reproduce* the behavior +* *Expected behavior* vs actual behavior +* *Environment* (OS, Rust version, panic-attack version) +* *Logs or error messages* if applicable + +==== Suggesting Enhancements + +Enhancement suggestions are tracked as GitHub issues. When creating an +enhancement suggestion: + +* *Use a clear and descriptive title* +* *Provide a detailed description* of the proposed feature +* *Explain why this enhancement would be useful* to most users +* *List any alternatives* you’ve considered + +==== Pull Requests + +[arabic] +. *Fork the repository* and create your branch from `+main+` +. *Follow the coding standards* described below +. *Add tests* for any new functionality +. *Update documentation* including README, rustdoc, and examples +. *Ensure all tests pass* (`+cargo test+`) +. *Ensure zero warnings* (`+cargo build --release+`) +. *Run clippy* (`+cargo clippy -- -D warnings+`) +. *Format code* (`+cargo fmt+`) +. *Write a clear commit message* following the project’s commit style + +=== Development Setup + +==== Prerequisites + +* Rust 1.85.0 or later (MSRV) +* Cargo +* Git +* just (optional, for task automation) + +==== Building + +[source,bash] +---- +git clone https://github.com/hyperpolymath/panic-attack.git +cd panic-attack +cargo build +---- + +==== Running Tests + +[source,bash] +---- +# Run all tests +cargo test + +# Run readiness tests (machine-verifiable CRG grades) +just readiness + +# Run readiness summary (pass/fail per grade) +just readiness-summary + +# Run with verbose output +cargo test -- --nocapture + +# Run specific test +cargo test test_name +---- + +==== Running Locally + +[source,bash] +---- +cargo run -- assail ./examples/vulnerable_program.rs --verbose +---- + +=== Coding Standards + +==== Rust Style + +* Follow the https://doc.rust-lang.org/1.0.0/style/[Rust Style Guide] +* Use `+cargo fmt+` for consistent formatting +* Use `+cargo clippy+` to catch common mistakes +* Maximum line length: 100 characters (flexible for readability) + +==== Documentation + +* All public APIs must have rustdoc comments +* Include examples in rustdoc where appropriate +* Keep comments up-to-date with code changes +* Use `+//!+` for module-level documentation +* Use `+///+` for item-level documentation + +==== Testing + +* Write unit tests for all non-trivial functions +* Write integration tests for user-facing features +* Aim for 80% code coverage +* Test edge cases and error conditions +* Use descriptive test names: +`+test___+` +* Readiness tests use CRG grade prefixes: `+readiness_d_+`, +`+readiness_c_+`, `+readiness_b_+` + +==== Commit Messages + +Follow the Conventional Commits specification: + +.... +: + +[optional body] + +[optional footer] +.... + +Types: - `+feat+`: New feature - `+fix+`: Bug fix - `+docs+`: +Documentation changes - `+test+`: Adding or updating tests - +`+refactor+`: Code refactoring - `+perf+`: Performance improvements - +`+chore+`: Maintenance tasks + +Example: + +.... +feat: add Latin-1 fallback for non-UTF-8 files + +Implements encoding_rs fallback when UTF-8 decoding fails. +Verbose mode logs skipped files. Fixes handling of vendored +C files with non-ASCII author names. + +Closes #42 +.... + +=== Project Structure + +.... +panic-attack/ +├── src/ +│ ├── main.rs # CLI entry point (clap) — 20 subcommands +│ ├── lib.rs # Library API +│ ├── types.rs # Core types (49 languages, 25 categories) +│ ├── assail/ # Static analysis engine +│ │ ├── analyzer.rs # 49-language analyzer with per-file detection +│ │ └── patterns.rs # Language-specific attack patterns +│ ├── kanren/ # miniKanren-inspired logic engine +│ │ ├── core.rs # Unification, substitution, fact DB +│ │ ├── taint.rs # Source-to-sink taint analysis +│ │ ├── crosslang.rs # FFI boundary vulnerability chains +│ │ └── strategy.rs # Risk-weighted search prioritisation +│ ├── attack/ # 6-axis stress testing +│ │ ├── executor.rs # Attack execution engine +│ │ └── strategies.rs # Per-axis attack strategies +│ ├── signatures/ # Logic-based bug signature detection +│ │ ├── engine.rs # SignatureEngine (use-after-free, deadlock, etc.) +│ │ └── rules.rs # Detection rules +│ ├── report/ # Report generation and output +│ │ ├── generator.rs # AssaultReport builder +│ │ └── formatter.rs # Output formatting (text, JSON, YAML, Nickel, SARIF) +│ ├── assemblyline.rs # Batch scanning with rayon parallelism + BLAKE3 +│ ├── notify.rs # Notification pipeline (markdown + GitHub issues) +│ ├── attestation/ # Cryptographic attestation chain +│ │ ├── intent.rs # Pre-execution commitment +│ │ ├── evidence.rs # Rolling hash accumulator +│ │ ├── seal.rs # Post-execution binding +│ │ ├── chain.rs # Chain builder orchestration +│ │ └── envelope.rs # A2ML envelope wrapper +│ ├── ambush/ # Ambient stressors + DAW-style timeline +│ ├── amuck/ # Mutation combinations +│ ├── abduct/ # Isolation + time-skew +│ ├── adjudicate/ # Campaign verdict aggregation +│ ├── axial/ # Reaction observation +│ ├── a2ml/ # AI manifest protocol +│ ├── panll/ # PanLL event-chain export +│ ├── storage/ # Filesystem + VerisimDB persistence +│ ├── i18n/ # Multi-language support (ISO 639-1, 10 languages) +│ └── diagnostics.rs # Self-check (version, fleet, attestation, panicbot) +├── tests/ # Integration + readiness tests +├── examples/ # Example programs +├── .machine_readable/ # SCM checkpoint files + bot directives +└── .github/workflows/ # CI/CD workflows +.... + +=== RSR Compliance + +This project follows RSR (Reproducible Software Repositories) standards: + +==== Critical Invariants + +[arabic] +. *SCM files in .machine_readable/ only* - Never put STATE.scm, +ECOSYSTEM.scm, or META.scm in the repository root +. *AI manifest required* - AI.a2ml must be present and up-to-date +. *License consistency* - All files must use MPL-2.0 (SPDX header) +. *Author attribution* - Jonathan D.A. Jewell j.d.a.jewell@open.ac.uk + +==== Updating Checkpoint Files + +When making significant changes, update: - +`+.machine_readable/STATE.scm+` - Current state, completion %, next +actions - `+.machine_readable/ECOSYSTEM.scm+` - If adding new +dependencies or integrations - `+.machine_readable/META.scm+` - If +making architectural decisions (ADRs) + +=== Release Process + +[arabic] +. Update version in `+Cargo.toml+` +. Update `+CHANGELOG.md+` with changes since last release +. Update `+.machine_readable/STATE.scm+` with new version +. Run full test suite: `+cargo test+` +. Run readiness tests: `+just readiness-summary+` +. Create git tag: `+git tag -a vX.Y.Z -m "Release vX.Y.Z"+` +. Push tag: `+git push origin vX.Y.Z+` +. GitHub Actions will create the release + +=== Getting Help + +* *Documentation*: See README.md and DESIGN.md +* *Issues*: Check existing issues or create a new one +* *Email*: j.d.a.jewell@open.ac.uk +* *Roadmap*: See ROADMAP.md for future plans + +=== License + +By contributing to panic-attack, you agree that your contributions will +be licensed under the MPL-2.0 license. See the LICENSE file for details. + +=== Recognition + +Contributors will be acknowledged in: - CHANGELOG.md for their specific +contributions - GitHub contributors page - Release notes + +Thank you for contributing to panic-attack! diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 32712cb..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,241 +0,0 @@ - - -# Contributing to panic-attack - -Thank you for your interest in contributing to panic-attack! This document provides guidelines and information for contributors. - -## Code of Conduct - -This project follows the Contributor Covenant Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to j.d.a.jewell@open.ac.uk. - -## How to Contribute - -### Reporting Bugs - -Before creating bug reports, please check the existing issues to avoid duplicates. When creating a bug report, include: - -- **Clear title** describing the issue -- **Detailed description** of the problem -- **Steps to reproduce** the behavior -- **Expected behavior** vs actual behavior -- **Environment** (OS, Rust version, panic-attack version) -- **Logs or error messages** if applicable - -### Suggesting Enhancements - -Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion: - -- **Use a clear and descriptive title** -- **Provide a detailed description** of the proposed feature -- **Explain why this enhancement would be useful** to most users -- **List any alternatives** you've considered - -### Pull Requests - -1. **Fork the repository** and create your branch from `main` -2. **Follow the coding standards** described below -3. **Add tests** for any new functionality -4. **Update documentation** including README, rustdoc, and examples -5. **Ensure all tests pass** (`cargo test`) -6. **Ensure zero warnings** (`cargo build --release`) -7. **Run clippy** (`cargo clippy -- -D warnings`) -8. **Format code** (`cargo fmt`) -9. **Write a clear commit message** following the project's commit style - -## Development Setup - -### Prerequisites - -- Rust 1.85.0 or later (MSRV) -- Cargo -- Git -- just (optional, for task automation) - -### Building - -```bash -git clone https://github.com/hyperpolymath/panic-attack.git -cd panic-attack -cargo build -``` - -### Running Tests - -```bash -# Run all tests -cargo test - -# Run readiness tests (machine-verifiable CRG grades) -just readiness - -# Run readiness summary (pass/fail per grade) -just readiness-summary - -# Run with verbose output -cargo test -- --nocapture - -# Run specific test -cargo test test_name -``` - -### Running Locally - -```bash -cargo run -- assail ./examples/vulnerable_program.rs --verbose -``` - -## Coding Standards - -### Rust Style - -- Follow the [Rust Style Guide](https://doc.rust-lang.org/1.0.0/style/) -- Use `cargo fmt` for consistent formatting -- Use `cargo clippy` to catch common mistakes -- Maximum line length: 100 characters (flexible for readability) - -### Documentation - -- All public APIs must have rustdoc comments -- Include examples in rustdoc where appropriate -- Keep comments up-to-date with code changes -- Use `//!` for module-level documentation -- Use `///` for item-level documentation - -### Testing - -- Write unit tests for all non-trivial functions -- Write integration tests for user-facing features -- Aim for 80% code coverage -- Test edge cases and error conditions -- Use descriptive test names: `test___` -- Readiness tests use CRG grade prefixes: `readiness_d_`, `readiness_c_`, `readiness_b_` - -### Commit Messages - -Follow the Conventional Commits specification: - -``` -: - -[optional body] - -[optional footer] -``` - -Types: -- `feat`: New feature -- `fix`: Bug fix -- `docs`: Documentation changes -- `test`: Adding or updating tests -- `refactor`: Code refactoring -- `perf`: Performance improvements -- `chore`: Maintenance tasks - -Example: -``` -feat: add Latin-1 fallback for non-UTF-8 files - -Implements encoding_rs fallback when UTF-8 decoding fails. -Verbose mode logs skipped files. Fixes handling of vendored -C files with non-ASCII author names. - -Closes #42 -``` - -## Project Structure - -``` -panic-attack/ -├── src/ -│ ├── main.rs # CLI entry point (clap) — 20 subcommands -│ ├── lib.rs # Library API -│ ├── types.rs # Core types (49 languages, 25 categories) -│ ├── assail/ # Static analysis engine -│ │ ├── analyzer.rs # 49-language analyzer with per-file detection -│ │ └── patterns.rs # Language-specific attack patterns -│ ├── kanren/ # miniKanren-inspired logic engine -│ │ ├── core.rs # Unification, substitution, fact DB -│ │ ├── taint.rs # Source-to-sink taint analysis -│ │ ├── crosslang.rs # FFI boundary vulnerability chains -│ │ └── strategy.rs # Risk-weighted search prioritisation -│ ├── attack/ # 6-axis stress testing -│ │ ├── executor.rs # Attack execution engine -│ │ └── strategies.rs # Per-axis attack strategies -│ ├── signatures/ # Logic-based bug signature detection -│ │ ├── engine.rs # SignatureEngine (use-after-free, deadlock, etc.) -│ │ └── rules.rs # Detection rules -│ ├── report/ # Report generation and output -│ │ ├── generator.rs # AssaultReport builder -│ │ └── formatter.rs # Output formatting (text, JSON, YAML, Nickel, SARIF) -│ ├── assemblyline.rs # Batch scanning with rayon parallelism + BLAKE3 -│ ├── notify.rs # Notification pipeline (markdown + GitHub issues) -│ ├── attestation/ # Cryptographic attestation chain -│ │ ├── intent.rs # Pre-execution commitment -│ │ ├── evidence.rs # Rolling hash accumulator -│ │ ├── seal.rs # Post-execution binding -│ │ ├── chain.rs # Chain builder orchestration -│ │ └── envelope.rs # A2ML envelope wrapper -│ ├── ambush/ # Ambient stressors + DAW-style timeline -│ ├── amuck/ # Mutation combinations -│ ├── abduct/ # Isolation + time-skew -│ ├── adjudicate/ # Campaign verdict aggregation -│ ├── axial/ # Reaction observation -│ ├── a2ml/ # AI manifest protocol -│ ├── panll/ # PanLL event-chain export -│ ├── storage/ # Filesystem + VerisimDB persistence -│ ├── i18n/ # Multi-language support (ISO 639-1, 10 languages) -│ └── diagnostics.rs # Self-check (version, fleet, attestation, panicbot) -├── tests/ # Integration + readiness tests -├── examples/ # Example programs -├── .machine_readable/ # SCM checkpoint files + bot directives -└── .github/workflows/ # CI/CD workflows -``` - -## RSR Compliance - -This project follows RSR (Reproducible Software Repositories) standards: - -### Critical Invariants - -1. **SCM files in .machine_readable/ only** - Never put STATE.scm, ECOSYSTEM.scm, or META.scm in the repository root -2. **AI manifest required** - AI.a2ml must be present and up-to-date -3. **License consistency** - All files must use MPL-2.0 (SPDX header) -4. **Author attribution** - Jonathan D.A. Jewell - -### Updating Checkpoint Files - -When making significant changes, update: -- `.machine_readable/STATE.scm` - Current state, completion %, next actions -- `.machine_readable/ECOSYSTEM.scm` - If adding new dependencies or integrations -- `.machine_readable/META.scm` - If making architectural decisions (ADRs) - -## Release Process - -1. Update version in `Cargo.toml` -2. Update `CHANGELOG.md` with changes since last release -3. Update `.machine_readable/STATE.scm` with new version -4. Run full test suite: `cargo test` -5. Run readiness tests: `just readiness-summary` -6. Create git tag: `git tag -a vX.Y.Z -m "Release vX.Y.Z"` -7. Push tag: `git push origin vX.Y.Z` -8. GitHub Actions will create the release - -## Getting Help - -- **Documentation**: See README.md and DESIGN.md -- **Issues**: Check existing issues or create a new one -- **Email**: j.d.a.jewell@open.ac.uk -- **Roadmap**: See ROADMAP.md for future plans - -## License - -By contributing to panic-attack, you agree that your contributions will be licensed under the MPL-2.0 license. See the LICENSE file for details. - -## Recognition - -Contributors will be acknowledged in: -- CHANGELOG.md for their specific contributions -- GitHub contributors page -- Release notes - -Thank you for contributing to panic-attack! diff --git a/DESIGN.adoc b/DESIGN.adoc new file mode 100644 index 0000000..c25d3ff --- /dev/null +++ b/DESIGN.adoc @@ -0,0 +1,674 @@ +== panic-attack: Technical Design + +____ +*Note*: This document describes the original design from 2026-02-07. The +tool has since evolved significantly (47 languages, miniKanren engine, +SARIF, attestation, panicbot integration). See `+.claude/CLAUDE.md+` for +current architecture and `+ROADMAP.md+` for current status. +____ + +=== Motivation + +Modern software testing often focuses on either: 1. *Fuzzing*: Random +input generation (afl, libFuzzer) 2. *Property Testing*: Verification of +invariants (QuickCheck, PropTest) 3. *Static Analysis*: Code inspection +without execution (Clippy, CodeQL) + +`+panic-attack+` fills a different niche: *systematic stress testing +combined with logic-based bug detection*. + +=== Core Concepts + +==== 1. Assail Pre-Analysis + +Before attacking a program, we need to understand its structure: + +*Goal*: Identify weak points and recommend optimal attack strategies. + +*Approach*: - Parse source code for patterns (unsafe blocks, +allocations, I/O) - Detect frameworks and application type - Catalog +potential vulnerabilities - Generate attack recommendations + +*Output*: A weighted list of attack axes to prioritize. + +==== 2. Multi-Axis Attack Model + +Traditional stress testing focuses on single dimensions. We attack +across *six independent axes*: + +[width="100%",cols="28%,27%,45%",options="header",] +|=== +|Axis |Goal |Examples +|*CPU* |Exhaust computational resources |Infinite loops, expensive +operations + +|*Memory* |Trigger OOM or allocation failures |Large buffers, memory +leaks + +|*Disk* |Saturate I/O bandwidth |Massive file operations + +|*Network* |Flood connections |Connection storms, large payloads + +|*Concurrency* |Expose race conditions |Thread/task explosions + +|*Time* |Find time-dependent bugs |Extended runtime, timeouts +|=== + +*Key insight*: Many bugs only appear under specific resource pressure. + +==== 3. Logic-Based Signature Detection + +Inspired by *Mozart/Oz* constraint logic programming and *Datalog* +inference. + +===== Why Logic Programming? + +Traditional bug detection uses pattern matching (regex, AST). Logic +programming offers: + +[arabic] +. *Declarative Rules*: Express "`what to find`" not "`how to find it`" +. *Inference*: Derive complex patterns from simple facts +. *Temporal Logic*: Reason about ordering and causality +. *Constraint Solving*: Handle complex inter-dependencies + +===== Datalog Model + +We model program behavior as facts and detect bugs via logical +inference: + +*Facts* (observations): + +.... +Alloc(heap_var, location=42) +Free(heap_var, location=100) +Use(heap_var, location=150) +.... + +*Rule* (bug pattern): + +.... +UseAfterFree(var, use_loc, free_loc) :- + Free(var, free_loc), + Use(var, use_loc), + Ordering(free_loc, use_loc) +.... + +*Inference*: If we observe `+Free(heap_var, 100)+` and +`+Use(heap_var, 150)+`, we infer `+UseAfterFree(heap_var, 150, 100)+`. + +===== Implemented Rules + +[arabic] +. *Use-After-Free* ++ +.... +UseAfterFree(X, use_loc, free_loc) :- + Free(X, free_loc), + Use(X, use_loc), + free_loc < use_loc +.... +. *Double-Free* ++ +.... +DoubleFree(X, loc1, loc2) :- + Free(X, loc1), + Free(X, loc2), + loc1 != loc2 +.... +. *Deadlock* (simplified) ++ +.... +Deadlock(M1, M2) :- + Lock(M1, loc1), Lock(M2, loc2), # Thread 1 order + Lock(M2, loc3), Lock(M1, loc4), # Thread 2 order (reversed) + Ordering(loc1, loc2), + Ordering(loc3, loc4) +.... +. *Data Race* ++ +.... +DataRace(X, loc1, loc2) :- + Write(X, loc1), + Read(X, loc2), + Concurrent(loc1, loc2), + ¬Synchronized(loc1, loc2) +.... + +==== 4. Pattern Libraries + +Different program types have different vulnerabilities: + +*Web Servers*: - HTTP flood attacks - Large POST body handling - +Connection exhaustion + +*Databases*: - Query storms - Transaction conflicts - Index corruption + +*File Systems*: - Concurrent file access - Disk space exhaustion - +Permission errors + +*Concurrent Programs*: - Deadlock induction - Race condition triggering +- Resource starvation + +The Assail analysis selects appropriate patterns based on detected +frameworks. + +=== Architecture + +==== Data Flow + +.... +┌─────────────┐ +│ Target │ +│ Program │ +└──────┬──────┘ + │ + ▼ +┌─────────────────┐ +│ Assail Analysis │ ← Static code inspection +│ (assail/*) │ +└──────┬──────────┘ + │ + ▼ +┌─────────────────┐ +│ Attack Planning │ ← Select axes and patterns +│ (patterns.rs) │ +└──────┬──────────┘ + │ + ▼ +┌─────────────────┐ +│ Attack Executor │ ← Execute stress tests +│ (attack/*) │ +└──────┬──────────┘ + │ + ▼ +┌─────────────────┐ +│ Crash Reports │ ← Collect failures +│ (CrashReport) │ +└──────┬──────────┘ + │ + ▼ +┌─────────────────┐ +│ Signature │ ← Logic-based inference +│ Detection │ +│ (signatures/*) │ +└──────┬──────────┘ + │ + ▼ +┌─────────────────┐ +│ Report │ ← Comprehensive report +│ Generation │ +│ (report/*) │ +└─────────────────┘ +.... + +==== Module Breakdown + +===== `+types.rs+` + +Core type definitions shared across modules. + +Key types: - `+Language+`, `+Framework+`: Program classification - +`+AttackAxis+`, `+IntensityLevel+`: Attack configuration - +`+WeakPoint+`, `+BugSignature+`: Analysis results - `+Fact+`, +`+Predicate+`, `+Rule+`: Logic programming primitives + +===== `+assail/+` + +Static analysis and pattern detection. + +* `+analyzer.rs+`: Core analysis engine +** Language detection +** Framework identification +** Weak point extraction +** Statistics collection +* `+patterns.rs+`: Pattern library +** Language-specific patterns +** Framework-specific patterns +** Attack recommendations + +===== `+attack/+` + +Attack orchestration and execution. + +* `+executor.rs+`: Attack execution engine +** Strategy selection +** Process management +** Crash collection +** Resource monitoring +* `+strategies.rs+`: Attack strategy definitions +** CPU stress algorithms +** Memory exhaustion techniques +** I/O saturation methods +** Concurrency storm patterns + +===== `+signatures/+` + +Logic-based bug detection. + +* `+engine.rs+`: Signature detection engine +** Fact extraction from crashes +** Rule application +** Inference execution +** Confidence scoring +* `+rules.rs+`: Datalog-style rule definitions +** Use-after-free rules +** Deadlock rules +** Race condition rules +** Memory corruption rules + +===== `+report/+` + +Report generation and formatting. + +* `+generator.rs+`: Report assembly +** Robustness scoring +** Issue prioritization +** Recommendation generation +* `+formatter.rs+`: Output formatting +** Console output with colors +** JSON serialization +** Pretty printing + +=== Mozart/Oz Connection + +==== Why Mozart/Oz? + +Mozart/Oz pioneered *constraint logic programming* with: + +[arabic] +. *Unification*: Pattern matching with logical variables +. *Constraints*: Declarative specification of relationships +. *Search*: Automatic exploration of solution spaces +. *Concurrency*: First-class concurrent constraints + +==== Mapping to panic-attack + +[cols=",",options="header",] +|=== +|Mozart/Oz Concept |panic-attack Implementation +|*Variables* |Program variables and locations +|*Constraints* |Temporal ordering, type constraints +|*Unification* |Fact matching in rule bodies +|*Search* |Inference over fact database +|*Propagation* |Forward-chaining inference +|=== + +==== Example: Use-After-Free Detection + +*Mozart/Oz style* (pseudocode): + +[source,oz] +---- +proc {DetectUAF Facts ?Bugs} + for Free in Facts.frees do + for Use in Facts.uses do + if Free.var == Use.var andthen Free.loc < Use.loc then + Bugs := UseAfterFree(Free.var, Use.loc, Free.loc) | Bugs + end + end + end +end +---- + +*panic-attack style* (Rust): + +[source,rust] +---- +fn infer_use_after_free(&self, facts: &HashSet) -> Vec { + let mut signatures = Vec::new(); + + for fact1 in facts { + if let Fact::Free { var: var1, location: free_loc } = fact1 { + for fact2 in facts { + if let Fact::Use { var: var2, location: use_loc } = fact2 { + if var1 == var2 && free_loc < use_loc { + signatures.push(BugSignature { + signature_type: SignatureType::UseAfterFree, + // ... + }); + } + } + } + } + } + + signatures +} +---- + +Both express the same logical rule: "`A use-after-free occurs when a +variable is freed before it is used.`" + +=== Advanced Features (Future) + +==== 1. Multi-Program Correlation + +Test multiple programs simultaneously to detect: - Shared resource +conflicts - Protocol violations - Distributed race conditions + +==== 2. Corpus-Based Testing + +Use real-world data as attack vectors: - HTTP request logs for web +servers - Query logs for databases - File system snapshots for FS tools + +==== 3. Mutation-Based Fuzzing + +Combine with traditional fuzzing: - Generate inputs based on weak points +- Mutate known-good inputs - Coverage-guided exploration + +==== 4. Symbolic Execution Integration + +Enhance fact extraction with symbolic execution: - Path constraints as +logical facts - SMT solver for constraint satisfaction - Precise +temporal ordering + +==== 5. Distributed Attack Orchestration + +Scale to large programs: - Parallel attack execution - Distributed fact +collection - Centralized inference + +=== Performance Considerations + +==== Fact Database Size + +For large programs, the fact database can grow exponentially. +Mitigations: + +[arabic] +. *Incremental Analysis*: Process crashes as they occur +. *Fact Pruning*: Discard irrelevant facts early +. *Index Structures*: Use hash maps for O(1) lookups +. *Lazy Evaluation*: Defer inference until needed + +==== Rule Complexity + +Some rules (like deadlock detection) require quadratic or higher +complexity. Optimizations: + +[arabic] +. *Rule Ordering*: Apply cheap rules first +. *Short-Circuit Evaluation*: Stop on high-confidence matches +. *Caching*: Memoize intermediate results +. *Sampling*: Sample fact space for approximate results + +=== Comparison to Existing Tools + +[width="100%",cols="19%,21%,30%,30%",options="header",] +|=== +|Tool |Focus |Approach |Coverage +|*AFL* |Fuzzing |Mutation-based |Input space + +|*libFuzzer* |Fuzzing |Coverage-guided |Input + code paths + +|*AddressSanitizer* |Memory bugs |Runtime instrumentation |Execution + +|*ThreadSanitizer* |Concurrency bugs |Happens-before analysis |Thread +interactions + +|*Valgrind* |Memory errors |Binary instrumentation |All allocations + +|*panic-attack* |*Robustness* |*Multi-axis stress + logic* |*Resource +pressure + patterns* +|=== + +*Key differentiator*: We test under resource pressure, not just +correctness. + +=== Philosophical Foundation + +==== Robustness vs. Correctness + +* *Correctness*: "`Does it work?`" +* *Robustness*: "`Does it work under adversarial conditions?`" + +Many programs are correct under normal conditions but fail +catastrophically under stress. panic-attack targets this gap. + +==== Resource-Aware Testing + +Traditional testing assumes infinite resources. Real systems have: - +Finite memory - Limited CPU - Bounded I/O bandwidth - Contended locks + +panic-attack respects these limits and exploits them. + +==== Logic as Specification + +Bug patterns are *specifications* of incorrect behavior. Logic +programming lets us: + +[arabic] +. *Declare* what’s wrong +. *Infer* when it happens +. *Prove* it occurred + +This is more principled than ad-hoc pattern matching. + +=== Extended Design Vision (2026-02-07) + +The following concepts emerged from design exploration and represent the +longer-term trajectory of panic-attack. + +==== Constraint Sets (Composable Stress Profiles) + +Real failures are never one thing. They’re the intersection of multiple +pressures. A "`constraint set`" combines conditions that must hold +simultaneously: + +[source,yaml] +---- +name: "Hot Processor + Falling Memory" +constraints: + cpu: + load: 95% + sustained: true + memory: + available: declining + rate: "100MB/s loss" + floor: "256MB" + program: + must_survive: true + max_response_time: "500ms" +---- + +This concept comes directly from Mozart/Oz’s constraint stores: +accumulate constraints and let the solver reason about whether they can +all be satisfied. + +*GUI Vision*: A visual interface where you drag sliders to compose sets: + +.... +┌──────────────────────────────────────────┐ +│ [CPU] ████████████░░░░ 80% │ +│ [Memory] ██████████████░░ 90% ↓ fall │ +│ [Disk] ████░░░░░░░░░░░░ 30% │ +│ [Network] ████████░░░░░░░░ 50ms lat │ +│ [Threads] ████████████████ 100 threads │ +│ [▶ Run Test] [💾 Save Profile] │ +└──────────────────────────────────────────┘ +.... + +==== Software Fuses + +A software fuse is a program component designed to fail safely, +protecting the rest of the system from cascading failure, like an +electrical fuse. + +*Existing partial solutions*: - Circuit breakers (Netflix Hystrix) – +service-level only - OOM killers (earlyoom, systemd-oomd) – reactive, +not proactive - Watchdog timers – binary: reset or don’t - Rate limiters +– don’t model system topology - Backpressure (Reactive Streams) – single +pipeline only + +*What doesn’t exist yet*: A way to DESIGN fuse placement based on +resource flow modelling. panic-attack reveals where fuses are needed by +finding where things actually break. + +.... + ┌─── CPU FUSE ───┐ + │ If > 90% for │ + │ 30s, shed load │ + └────────────────┘ + │ +┌──────────┐ ┌──────────▼───────────┐ ┌──────────┐ +│ Input │───▶│ Core Application │───▶│ Output │ +│ Queue │ └──────────┬───────────┘ │ Queue │ +└──────────┘ │ └──────────┘ + ┌──────▼─────────┐ + │ MEMORY FUSE │ + │ If < 256MB │ + │ free, GC + shed│ + └────────────────┘ + │ + ┌──────▼─────────┐ + │ CASCADE FUSE │ + │ If 2+ fuses │ + │ tripped, halt │ + └────────────────┘ +.... + +panic-attack’s role: 1. *Where fuses are needed* (which resources +exhaust first) 2. *What thresholds to set* (at what level does +degradation begin) 3. *Whether fuses work* (does the system actually +degrade gracefully) 4. *What happens when fuses cascade* (does tripping +one cause others) + +==== The Cisco Analogy: Resource Topology Simulator + +Cisco Packet Tracer lets you design network topologies. We model +resource flows: + +[cols=",",options="header",] +|=== +|Network Concept |Resource Equivalent +|Routers |Programs/services +|Switches |Message queues/buses +|Cables |API calls / IPC +|Bandwidth |CPU/memory/disk budgets +|Latency |Response times +|Packet loss |Error rates +|=== + +This could model both *space* (how resources distribute across services) +and *time* (how resource usage changes over hours/days/growth +trajectories). + +==== Priority Scheduling + +"`I always need 4 of these running for safety, and that needs to get +priority`": + +[source,yaml] +---- +critical_services: + - name: "database" + priority: 1 # Never shed + min_resources: { cpu: 2, memory: 4GB } + - name: "api-server" + priority: 1 + min_resources: { cpu: 1, memory: 2GB } + - name: "monitoring" + priority: 2 # Shed under pressure + - name: "cache" + priority: 3 # Shed first + +resource_policy: + shed_order: [3, 2] + never_shed: [1] +---- + +panic-attack tests these policies by simulating pressure and verifying +shedding happens correctly. + +==== eclexia Integration + +eclexia’s resource-tracking creates a natural integration: 1. eclexia +programs declare resource expectations 2. panic-attack verifies those +declarations under stress 3. eclexia programs can BE software fuses +(adaptive resource response) 4. panic-attack profiles eclexia as a +demonstration of its value + +==== ML Extensions + +Every panic-attack run generates labelled training data: - Input: +program type, language, frameworks, attack axes, intensity - Output: +crash/survive, signatures detected, resource curves + +Over time, this enables: - Bug classification by similarity to known +patterns - Attack strategy optimisation (learn what’s most effective) - +Threshold prediction (predict failure point without reaching it) - +Anomaly detection (flag unusual behaviour during tests) + +=== Product Boundaries + +==== Definitely panic-attack (this repo) + +* Assail static analysis +* Multi-axis attack execution +* Signature detection (Datalog-style) +* Pattern library +* Constraint sets / stress profiles +* Program-data corruption testing +* Multi-program interaction testing + +==== Probably Separate Products + +* *Resource Topology Simulator* – GUI, Cisco-like +* *Software Fuse Framework* – Rust library +* *eclexia Profiler* – eclexia-specific integration +* *Safety Priority Scheduler* – Production daemon + +=== Roadmap + +==== v0.1 (Current) – Foundation + +* [x] CLI with assail, attack, assault, analyze commands +* [x] Assail static analysis +* [x] 6 attack axes +* [x] Pattern-based signature detection +* [x] Report generation with scoring + +==== v0.2 – Constraint Sets + +* [ ] YAML-based stress profile definitions +* [ ] Composable multi-axis conditions +* [ ] Program-data corruption testing +* [ ] Multi-program interaction testing + +==== v0.3 – Intelligence + +* [ ] Datalog engine integration (Crepe or Datafrog) +* [ ] ML-based signature classification +* [ ] Anomaly detection +* [ ] Threshold prediction + +==== v0.4 – Ecosystem + +* [ ] eclexia integration +* [ ] Software Fuse Framework +* [ ] CI/CD pipeline integration +* [ ] Resource Topology Simulator (separate project) + +==== v1.0 – Production + +* [ ] Priority-aware resource scheduling +* [ ] Topology designer GUI +* [ ] Trained ML models +* [ ] Enterprise reporting + +=== References + +* *Mozart/Oz*: Van Roy, P., & Haridi, S. (2004). _Concepts, Techniques, +and Models of Computer Programming_ +* *Datalog*: Abiteboul, S., Hull, R., & Vianu, V. (1995). _Foundations +of Databases_ +* *Stress Testing*: Basili, V. R., & Selby, R. W. (1987). _Comparing the +Effectiveness of Software Testing Strategies_ +* *Sanitizers*: Serebryany, K., et al. (2012). _AddressSanitizer: A Fast +Address Sanity Checker_ +* *Chaos Engineering*: Rosenthal, C., et al. (2017). _Chaos Engineering_ +* *Circuit Breakers*: Nygard, M. (2007). _Release It!_ + +=== License + +SPDX-License-Identifier: CC-BY-SA-4.0 diff --git a/DESIGN.md b/DESIGN.md deleted file mode 100644 index 739f9fd..0000000 --- a/DESIGN.md +++ /dev/null @@ -1,630 +0,0 @@ -# panic-attack: Technical Design - -> **Note**: This document describes the original design from 2026-02-07. The tool has since -> evolved significantly (47 languages, miniKanren engine, SARIF, attestation, panicbot integration). -> See `.claude/CLAUDE.md` for current architecture and `ROADMAP.md` for current status. - -## Motivation - -Modern software testing often focuses on either: -1. **Fuzzing**: Random input generation (afl, libFuzzer) -2. **Property Testing**: Verification of invariants (QuickCheck, PropTest) -3. **Static Analysis**: Code inspection without execution (Clippy, CodeQL) - -`panic-attack` fills a different niche: **systematic stress testing combined with logic-based bug detection**. - -## Core Concepts - -### 1. Assail Pre-Analysis - -Before attacking a program, we need to understand its structure: - -**Goal**: Identify weak points and recommend optimal attack strategies. - -**Approach**: -- Parse source code for patterns (unsafe blocks, allocations, I/O) -- Detect frameworks and application type -- Catalog potential vulnerabilities -- Generate attack recommendations - -**Output**: A weighted list of attack axes to prioritize. - -### 2. Multi-Axis Attack Model - -Traditional stress testing focuses on single dimensions. We attack across **six independent axes**: - -| Axis | Goal | Examples | -|------|------|----------| -| **CPU** | Exhaust computational resources | Infinite loops, expensive operations | -| **Memory** | Trigger OOM or allocation failures | Large buffers, memory leaks | -| **Disk** | Saturate I/O bandwidth | Massive file operations | -| **Network** | Flood connections | Connection storms, large payloads | -| **Concurrency** | Expose race conditions | Thread/task explosions | -| **Time** | Find time-dependent bugs | Extended runtime, timeouts | - -**Key insight**: Many bugs only appear under specific resource pressure. - -### 3. Logic-Based Signature Detection - -Inspired by **Mozart/Oz** constraint logic programming and **Datalog** inference. - -#### Why Logic Programming? - -Traditional bug detection uses pattern matching (regex, AST). Logic programming offers: - -1. **Declarative Rules**: Express "what to find" not "how to find it" -2. **Inference**: Derive complex patterns from simple facts -3. **Temporal Logic**: Reason about ordering and causality -4. **Constraint Solving**: Handle complex inter-dependencies - -#### Datalog Model - -We model program behavior as facts and detect bugs via logical inference: - -**Facts** (observations): -``` -Alloc(heap_var, location=42) -Free(heap_var, location=100) -Use(heap_var, location=150) -``` - -**Rule** (bug pattern): -``` -UseAfterFree(var, use_loc, free_loc) :- - Free(var, free_loc), - Use(var, use_loc), - Ordering(free_loc, use_loc) -``` - -**Inference**: If we observe `Free(heap_var, 100)` and `Use(heap_var, 150)`, we infer `UseAfterFree(heap_var, 150, 100)`. - -#### Implemented Rules - -1. **Use-After-Free** - ``` - UseAfterFree(X, use_loc, free_loc) :- - Free(X, free_loc), - Use(X, use_loc), - free_loc < use_loc - ``` - -2. **Double-Free** - ``` - DoubleFree(X, loc1, loc2) :- - Free(X, loc1), - Free(X, loc2), - loc1 != loc2 - ``` - -3. **Deadlock** (simplified) - ``` - Deadlock(M1, M2) :- - Lock(M1, loc1), Lock(M2, loc2), # Thread 1 order - Lock(M2, loc3), Lock(M1, loc4), # Thread 2 order (reversed) - Ordering(loc1, loc2), - Ordering(loc3, loc4) - ``` - -4. **Data Race** - ``` - DataRace(X, loc1, loc2) :- - Write(X, loc1), - Read(X, loc2), - Concurrent(loc1, loc2), - ¬Synchronized(loc1, loc2) - ``` - -### 4. Pattern Libraries - -Different program types have different vulnerabilities: - -**Web Servers**: -- HTTP flood attacks -- Large POST body handling -- Connection exhaustion - -**Databases**: -- Query storms -- Transaction conflicts -- Index corruption - -**File Systems**: -- Concurrent file access -- Disk space exhaustion -- Permission errors - -**Concurrent Programs**: -- Deadlock induction -- Race condition triggering -- Resource starvation - -The Assail analysis selects appropriate patterns based on detected frameworks. - -## Architecture - -### Data Flow - -``` -┌─────────────┐ -│ Target │ -│ Program │ -└──────┬──────┘ - │ - ▼ -┌─────────────────┐ -│ Assail Analysis │ ← Static code inspection -│ (assail/*) │ -└──────┬──────────┘ - │ - ▼ -┌─────────────────┐ -│ Attack Planning │ ← Select axes and patterns -│ (patterns.rs) │ -└──────┬──────────┘ - │ - ▼ -┌─────────────────┐ -│ Attack Executor │ ← Execute stress tests -│ (attack/*) │ -└──────┬──────────┘ - │ - ▼ -┌─────────────────┐ -│ Crash Reports │ ← Collect failures -│ (CrashReport) │ -└──────┬──────────┘ - │ - ▼ -┌─────────────────┐ -│ Signature │ ← Logic-based inference -│ Detection │ -│ (signatures/*) │ -└──────┬──────────┘ - │ - ▼ -┌─────────────────┐ -│ Report │ ← Comprehensive report -│ Generation │ -│ (report/*) │ -└─────────────────┘ -``` - -### Module Breakdown - -#### `types.rs` -Core type definitions shared across modules. - -Key types: -- `Language`, `Framework`: Program classification -- `AttackAxis`, `IntensityLevel`: Attack configuration -- `WeakPoint`, `BugSignature`: Analysis results -- `Fact`, `Predicate`, `Rule`: Logic programming primitives - -#### `assail/` -Static analysis and pattern detection. - -- `analyzer.rs`: Core analysis engine - - Language detection - - Framework identification - - Weak point extraction - - Statistics collection - -- `patterns.rs`: Pattern library - - Language-specific patterns - - Framework-specific patterns - - Attack recommendations - -#### `attack/` -Attack orchestration and execution. - -- `executor.rs`: Attack execution engine - - Strategy selection - - Process management - - Crash collection - - Resource monitoring - -- `strategies.rs`: Attack strategy definitions - - CPU stress algorithms - - Memory exhaustion techniques - - I/O saturation methods - - Concurrency storm patterns - -#### `signatures/` -Logic-based bug detection. - -- `engine.rs`: Signature detection engine - - Fact extraction from crashes - - Rule application - - Inference execution - - Confidence scoring - -- `rules.rs`: Datalog-style rule definitions - - Use-after-free rules - - Deadlock rules - - Race condition rules - - Memory corruption rules - -#### `report/` -Report generation and formatting. - -- `generator.rs`: Report assembly - - Robustness scoring - - Issue prioritization - - Recommendation generation - -- `formatter.rs`: Output formatting - - Console output with colors - - JSON serialization - - Pretty printing - -## Mozart/Oz Connection - -### Why Mozart/Oz? - -Mozart/Oz pioneered **constraint logic programming** with: - -1. **Unification**: Pattern matching with logical variables -2. **Constraints**: Declarative specification of relationships -3. **Search**: Automatic exploration of solution spaces -4. **Concurrency**: First-class concurrent constraints - -### Mapping to panic-attack - -| Mozart/Oz Concept | panic-attack Implementation | -|-------------------|-------------------------------| -| **Variables** | Program variables and locations | -| **Constraints** | Temporal ordering, type constraints | -| **Unification** | Fact matching in rule bodies | -| **Search** | Inference over fact database | -| **Propagation** | Forward-chaining inference | - -### Example: Use-After-Free Detection - -**Mozart/Oz style** (pseudocode): -```oz -proc {DetectUAF Facts ?Bugs} - for Free in Facts.frees do - for Use in Facts.uses do - if Free.var == Use.var andthen Free.loc < Use.loc then - Bugs := UseAfterFree(Free.var, Use.loc, Free.loc) | Bugs - end - end - end -end -``` - -**panic-attack style** (Rust): -```rust -fn infer_use_after_free(&self, facts: &HashSet) -> Vec { - let mut signatures = Vec::new(); - - for fact1 in facts { - if let Fact::Free { var: var1, location: free_loc } = fact1 { - for fact2 in facts { - if let Fact::Use { var: var2, location: use_loc } = fact2 { - if var1 == var2 && free_loc < use_loc { - signatures.push(BugSignature { - signature_type: SignatureType::UseAfterFree, - // ... - }); - } - } - } - } - } - - signatures -} -``` - -Both express the same logical rule: "A use-after-free occurs when a variable is freed before it is used." - -## Advanced Features (Future) - -### 1. Multi-Program Correlation - -Test multiple programs simultaneously to detect: -- Shared resource conflicts -- Protocol violations -- Distributed race conditions - -### 2. Corpus-Based Testing - -Use real-world data as attack vectors: -- HTTP request logs for web servers -- Query logs for databases -- File system snapshots for FS tools - -### 3. Mutation-Based Fuzzing - -Combine with traditional fuzzing: -- Generate inputs based on weak points -- Mutate known-good inputs -- Coverage-guided exploration - -### 4. Symbolic Execution Integration - -Enhance fact extraction with symbolic execution: -- Path constraints as logical facts -- SMT solver for constraint satisfaction -- Precise temporal ordering - -### 5. Distributed Attack Orchestration - -Scale to large programs: -- Parallel attack execution -- Distributed fact collection -- Centralized inference - -## Performance Considerations - -### Fact Database Size - -For large programs, the fact database can grow exponentially. Mitigations: - -1. **Incremental Analysis**: Process crashes as they occur -2. **Fact Pruning**: Discard irrelevant facts early -3. **Index Structures**: Use hash maps for O(1) lookups -4. **Lazy Evaluation**: Defer inference until needed - -### Rule Complexity - -Some rules (like deadlock detection) require quadratic or higher complexity. Optimizations: - -1. **Rule Ordering**: Apply cheap rules first -2. **Short-Circuit Evaluation**: Stop on high-confidence matches -3. **Caching**: Memoize intermediate results -4. **Sampling**: Sample fact space for approximate results - -## Comparison to Existing Tools - -| Tool | Focus | Approach | Coverage | -|------|-------|----------|----------| -| **AFL** | Fuzzing | Mutation-based | Input space | -| **libFuzzer** | Fuzzing | Coverage-guided | Input + code paths | -| **AddressSanitizer** | Memory bugs | Runtime instrumentation | Execution | -| **ThreadSanitizer** | Concurrency bugs | Happens-before analysis | Thread interactions | -| **Valgrind** | Memory errors | Binary instrumentation | All allocations | -| **panic-attack** | **Robustness** | **Multi-axis stress + logic** | **Resource pressure + patterns** | - -**Key differentiator**: We test under resource pressure, not just correctness. - -## Philosophical Foundation - -### Robustness vs. Correctness - -- **Correctness**: "Does it work?" -- **Robustness**: "Does it work under adversarial conditions?" - -Many programs are correct under normal conditions but fail catastrophically under stress. panic-attack targets this gap. - -### Resource-Aware Testing - -Traditional testing assumes infinite resources. Real systems have: -- Finite memory -- Limited CPU -- Bounded I/O bandwidth -- Contended locks - -panic-attack respects these limits and exploits them. - -### Logic as Specification - -Bug patterns are **specifications** of incorrect behavior. Logic programming lets us: - -1. **Declare** what's wrong -2. **Infer** when it happens -3. **Prove** it occurred - -This is more principled than ad-hoc pattern matching. - -## Extended Design Vision (2026-02-07) - -The following concepts emerged from design exploration and represent the -longer-term trajectory of panic-attack. - -### Constraint Sets (Composable Stress Profiles) - -Real failures are never one thing. They're the intersection of multiple -pressures. A "constraint set" combines conditions that must hold simultaneously: - -```yaml -name: "Hot Processor + Falling Memory" -constraints: - cpu: - load: 95% - sustained: true - memory: - available: declining - rate: "100MB/s loss" - floor: "256MB" - program: - must_survive: true - max_response_time: "500ms" -``` - -This concept comes directly from Mozart/Oz's constraint stores: accumulate -constraints and let the solver reason about whether they can all be satisfied. - -**GUI Vision**: A visual interface where you drag sliders to compose sets: - -``` -┌──────────────────────────────────────────┐ -│ [CPU] ████████████░░░░ 80% │ -│ [Memory] ██████████████░░ 90% ↓ fall │ -│ [Disk] ████░░░░░░░░░░░░ 30% │ -│ [Network] ████████░░░░░░░░ 50ms lat │ -│ [Threads] ████████████████ 100 threads │ -│ [▶ Run Test] [💾 Save Profile] │ -└──────────────────────────────────────────┘ -``` - -### Software Fuses - -A software fuse is a program component designed to fail safely, protecting the -rest of the system from cascading failure, like an electrical fuse. - -**Existing partial solutions**: -- Circuit breakers (Netflix Hystrix) -- service-level only -- OOM killers (earlyoom, systemd-oomd) -- reactive, not proactive -- Watchdog timers -- binary: reset or don't -- Rate limiters -- don't model system topology -- Backpressure (Reactive Streams) -- single pipeline only - -**What doesn't exist yet**: A way to DESIGN fuse placement based on resource -flow modelling. panic-attack reveals where fuses are needed by finding where -things actually break. - -``` - ┌─── CPU FUSE ───┐ - │ If > 90% for │ - │ 30s, shed load │ - └────────────────┘ - │ -┌──────────┐ ┌──────────▼───────────┐ ┌──────────┐ -│ Input │───▶│ Core Application │───▶│ Output │ -│ Queue │ └──────────┬───────────┘ │ Queue │ -└──────────┘ │ └──────────┘ - ┌──────▼─────────┐ - │ MEMORY FUSE │ - │ If < 256MB │ - │ free, GC + shed│ - └────────────────┘ - │ - ┌──────▼─────────┐ - │ CASCADE FUSE │ - │ If 2+ fuses │ - │ tripped, halt │ - └────────────────┘ -``` - -panic-attack's role: -1. **Where fuses are needed** (which resources exhaust first) -2. **What thresholds to set** (at what level does degradation begin) -3. **Whether fuses work** (does the system actually degrade gracefully) -4. **What happens when fuses cascade** (does tripping one cause others) - -### The Cisco Analogy: Resource Topology Simulator - -Cisco Packet Tracer lets you design network topologies. We model resource flows: - -| Network Concept | Resource Equivalent | -|----------------|---------------------| -| Routers | Programs/services | -| Switches | Message queues/buses | -| Cables | API calls / IPC | -| Bandwidth | CPU/memory/disk budgets | -| Latency | Response times | -| Packet loss | Error rates | - -This could model both **space** (how resources distribute across services) and -**time** (how resource usage changes over hours/days/growth trajectories). - -### Priority Scheduling - -"I always need 4 of these running for safety, and that needs to get priority": - -```yaml -critical_services: - - name: "database" - priority: 1 # Never shed - min_resources: { cpu: 2, memory: 4GB } - - name: "api-server" - priority: 1 - min_resources: { cpu: 1, memory: 2GB } - - name: "monitoring" - priority: 2 # Shed under pressure - - name: "cache" - priority: 3 # Shed first - -resource_policy: - shed_order: [3, 2] - never_shed: [1] -``` - -panic-attack tests these policies by simulating pressure and verifying -shedding happens correctly. - -### eclexia Integration - -eclexia's resource-tracking creates a natural integration: -1. eclexia programs declare resource expectations -2. panic-attack verifies those declarations under stress -3. eclexia programs can BE software fuses (adaptive resource response) -4. panic-attack profiles eclexia as a demonstration of its value - -### ML Extensions - -Every panic-attack run generates labelled training data: -- Input: program type, language, frameworks, attack axes, intensity -- Output: crash/survive, signatures detected, resource curves - -Over time, this enables: -- Bug classification by similarity to known patterns -- Attack strategy optimisation (learn what's most effective) -- Threshold prediction (predict failure point without reaching it) -- Anomaly detection (flag unusual behaviour during tests) - -## Product Boundaries - -### Definitely panic-attack (this repo) -- Assail static analysis -- Multi-axis attack execution -- Signature detection (Datalog-style) -- Pattern library -- Constraint sets / stress profiles -- Program-data corruption testing -- Multi-program interaction testing - -### Probably Separate Products -- **Resource Topology Simulator** -- GUI, Cisco-like -- **Software Fuse Framework** -- Rust library -- **eclexia Profiler** -- eclexia-specific integration -- **Safety Priority Scheduler** -- Production daemon - -## Roadmap - -### v0.1 (Current) -- Foundation -- [x] CLI with assail, attack, assault, analyze commands -- [x] Assail static analysis -- [x] 6 attack axes -- [x] Pattern-based signature detection -- [x] Report generation with scoring - -### v0.2 -- Constraint Sets -- [ ] YAML-based stress profile definitions -- [ ] Composable multi-axis conditions -- [ ] Program-data corruption testing -- [ ] Multi-program interaction testing - -### v0.3 -- Intelligence -- [ ] Datalog engine integration (Crepe or Datafrog) -- [ ] ML-based signature classification -- [ ] Anomaly detection -- [ ] Threshold prediction - -### v0.4 -- Ecosystem -- [ ] eclexia integration -- [ ] Software Fuse Framework -- [ ] CI/CD pipeline integration -- [ ] Resource Topology Simulator (separate project) - -### v1.0 -- Production -- [ ] Priority-aware resource scheduling -- [ ] Topology designer GUI -- [ ] Trained ML models -- [ ] Enterprise reporting - -## References - -- **Mozart/Oz**: Van Roy, P., & Haridi, S. (2004). *Concepts, Techniques, and Models of Computer Programming* -- **Datalog**: Abiteboul, S., Hull, R., & Vianu, V. (1995). *Foundations of Databases* -- **Stress Testing**: Basili, V. R., & Selby, R. W. (1987). *Comparing the Effectiveness of Software Testing Strategies* -- **Sanitizers**: Serebryany, K., et al. (2012). *AddressSanitizer: A Fast Address Sanity Checker* -- **Chaos Engineering**: Rosenthal, C., et al. (2017). *Chaos Engineering* -- **Circuit Breakers**: Nygard, M. (2007). *Release It!* - -## License - -SPDX-License-Identifier: CC-BY-SA-4.0 - diff --git a/FUTURE-IMPROVEMENTS.adoc b/FUTURE-IMPROVEMENTS.adoc new file mode 100644 index 0000000..c092681 --- /dev/null +++ b/FUTURE-IMPROVEMENTS.adoc @@ -0,0 +1,492 @@ +== Future Improvements: Insights from Scanning the Eclexia Compiler Toolchain + +*Date:* 2026-02-08 *Audit refreshed:* 2026-05-26 (4 of 10 items shipped; +status block at top) *Author:* Jonathan D.A. Jewell +j.d.a.jewell@open.ac.uk *Context:* panic-attack v1.0.0 at time of scan; +current v2.5.0 + +''''' + +=== Status at 2026-05-26 + +[width="100%",cols="10%,38%,23%,29%",options="header",] +|=== +|# |Improvement |Status |Evidence +|1 |Test Code Exclusion |*Shipped* +|`+Analyzer::strip_cfg_test_modules_rs+` — +`+src/assail/analyzer.rs:923-934+`. Applied globally before pattern +counting; CLAUDE.md confirms cfg(test) skip behaviour. + +|2 |Framework Detection Accuracy |*Shipped* +|`+Analyzer::detect_frameworks+` — `+src/assail/analyzer.rs:4993+`. +Dependency-aware classification supersedes the heuristic-only path that +misfired on Eclexia. + +|3 |Safe Unwrap Variant Distinction |*Shipped* |`+safe_unwrap_calls+` +field on `+ProgramStatistics+` (`+src/types.rs:518+`) and +`+FileStatistics+` (`+src/types.rs:451+`). Counted but excluded from +PA006 (PanicPath) per CLAUDE.md. + +|4 |Language-Specific Severity Calibration |Outstanding |No "`Hardened`" +or "`Clean`" severity tier in `+src/types.rs+`. Still gated on items 1 + +3 being trustworthy, which they now are. + +|5 |Workspace-Level Consolidated Reporting |Outstanding |No Cargo +workspace mode in `+src/main.rs+`. `+mass-panic+` covers cross-repo but +not single-workspace aggregation. + +|6 |Differential Scanning |*Shipped* |`+Commands::Diff+` — +`+src/main.rs:483+`; logic in `+src/report/diff.rs+`. Listed in ROADMAP +v2.2.0 as `+[x]+`. + +|7 |Allocation Site Context and Classification |Outstanding |No +`+AllocationCategory+` enum in `+src/types.rs+`. Site counts still raw. + +|8 |Resource Dimension Awareness for DSLs |Outstanding |Long-term; no +plugin-extension surface yet. + +|9 |Pattern Detection for Safe Error Handling |Outstanding |No "`error +handling maturity`" metric. + +|10 |Configurable Severity Thresholds for CI |Outstanding |No +`+[thresholds]+` parser; no `+panic-attack.toml+` consumer. Now +unblocked because 1, 2, 3 are accurate. +|=== + +*Net:* 4/10 shipped (1, 2, 3, 6). Items 4 and 10 are now genuinely +unblocked because their stated dependencies (1, 2, 3) have landed; the +original "`depends on`" notes are still accurate but no longer blocking. +Items 5, 7, 8, 9 remain as written. + +''''' + +=== Executive Summary + +Scanning the Eclexia compiler toolchain with `+panic-attack assail+` +exposed several categories of false positives, misdetections, and +missing features that reduce the tool’s signal-to-noise ratio on +well-engineered Rust codebases. This document captures the specific +observations and proposes concrete improvements, prioritised for +implementation. + +The core finding is that panic-attack currently treats all code +uniformly – test code is scored the same as production code, safe unwrap +variants are counted alongside unsafe ones, and severity ratings do not +account for language-specific safety guarantees. For a codebase like +Eclexia with zero unsafe blocks, zero production unwraps, and +comprehensive error handling via `+Result<_, RuntimeError>+`, the +current output overstates risk significantly. + +These improvements would benefit any Rust workspace scan, not just +Eclexia. + +''''' + +=== Completed Observations + +The following observations were made during the Eclexia scan session: + +[arabic] +. *Eclexia profile:* 10 crates, ~20,000 lines of Rust, 0 unsafe blocks, +0 production unwrap calls, full `+Result+`-based error handling with +custom `+RuntimeError+` type and `+?+` propagation throughout. +. *False positive rate:* The `+builtins.rs+` module was flagged with 96 +unwrap calls and 13 panic sites, all of which reside exclusively within +`+#[cfg(test)]+` modules. This produced a "`Medium`" severity finding +for a file with zero production panic paths. +. *Framework misdetection:* panic-attack reported "`WebServer`" as the +detected framework for pure compiler crates that perform zero I/O +operations (no network, no HTTP, no filesystem serving). +. *Safe unwrap variants counted as risks:* Calls to `+.unwrap_or(1)+`, +`+.unwrap_or_default()+`, and `+.unwrap_or_else(|| ...)+` were counted +toward the `+unwrap_calls+` metric. These are safe patterns that cannot +panic and should not contribute to risk scoring. +. *Severity not calibrated for Rust safety guarantees:* A crate with 0 +unsafe blocks, 0 production unwraps, and comprehensive `+Result+` +propagation still received non-trivial risk scores due to allocation +site counts alone. +. *No workspace-level consolidation:* Scanning 10 crates individually +produced 10 separate reports with no aggregate view of workspace health. +. *No differential capability:* There is no way to compare a scan before +and after a refactoring to show what improved or regressed. +. *Allocation sites lack context:* The report stated "`73 allocation +sites`" without distinguishing between `+Vec::new()+` (safe, bounded) +and user-controlled allocations (potentially unbounded). + +''''' + +=== Proposed Improvements + +==== 1. Test Code Exclusion + +*Priority:* HIGH — *Status: SHIPPED* +(`+Analyzer::strip_cfg_test_modules_rs+`, +`+src/assail/analyzer.rs:923-934+`) + +*Problem:* panic-attack counts `+unwrap()+` and `+panic!()+` calls +inside `+#[cfg(test)]+` modules, `+#[test]+` functions, and files in +`+tests/+` directories as production panic paths. This produces false +positives for any well-tested codebase. In the Eclexia scan, 100% of the +unwrap and panic findings in `+builtins.rs+` (96 unwrap calls, 13 panic +sites) were test-only code, yet the file received a "`Medium`" severity +rating. + +*Proposed solution:* + +* Parse `+#[cfg(test)]+` module boundaries and `+#[test]+` function +boundaries in the Rust analyzer. +* Exclude files matching `+tests/**+`, `+test_*.rs+`, `+*_test.rs+` +patterns. +* Report test code metrics separately (e.g., `+test_unwrap_calls+`) so +they remain visible but do not affect severity scoring. +* Add a `+--include-test-code+` flag for users who want the current +behaviour. + +*Impact:* Eliminates the single largest source of false positives on +well-tested Rust codebases. + +''''' + +==== 2. Framework Detection Accuracy + +*Priority:* HIGH — *Status: SHIPPED* (`+Analyzer::detect_frameworks+`, +`+src/assail/analyzer.rs:4993+`) + +*Problem:* panic-attack reports "`WebServer`" as the detected framework +for pure compiler crates with zero I/O operations. This is a +misdetection that undermines trust in the tool’s output. The Eclexia +crates have no HTTP dependencies, no server bindings, and no network +code. + +*Proposed solution:* + +* Revise framework detection heuristics to require evidence of actual +I/O patterns (e.g., TCP listeners, HTTP handlers, route definitions), +not just crate structure. +* Add a "`None`" or "`CLI`" framework classification for projects that +do not match any framework pattern. +* Consider inspecting `+Cargo.toml+` dependencies as a signal: presence +of `+actix-web+`, `+axum+`, `+warp+`, `+rocket+`, or `+hyper+` strongly +indicates a web server; absence of these with presence of `+clap+`, +`+structopt+`, or a `+[[bin]]+` target suggests a CLI tool. +* For library crates with no binary target and no I/O dependencies, +default to "`Library`" rather than guessing a framework. + +*Impact:* Prevents misleading framework labels that erode confidence in +the overall report. + +''''' + +==== 3. Safe Unwrap Variant Distinction + +*Priority:* HIGH — *Status: SHIPPED* (`+safe_unwrap_calls+` field on +`+ProgramStatistics+`/`+FileStatistics+`, `+src/types.rs:451,518+`) + +*Problem:* The Rust analyzer counts `+.unwrap_or(value)+`, +`+.unwrap_or_default()+`, and `+.unwrap_or_else(|| ...)+` toward the +`+unwrap_calls+` metric. These methods are safe alternatives to +`+.unwrap()+` that cannot panic – they provide fallback values instead. +Counting them as risks conflates safe error handling with unsafe panic +paths. + +*Proposed solution:* + +* Distinguish between panic-capable unwrap calls (`+.unwrap()+`, +`+.expect("...")+`) and safe variants (`+.unwrap_or(...)+`, +`+.unwrap_or_default()+`, `+.unwrap_or_else(|| ...)+`). +* Report safe variants in a separate metric (e.g., +`+safe_unwrap_calls+`) that does not contribute to severity scoring. +* Optionally report the ratio of safe-to-unsafe unwraps as a code +quality signal: a high ratio indicates disciplined error handling. + +*Impact:* Improves accuracy of the core unwrap metric, which is one of +the primary signals in Rust analysis. + +''''' + +==== 4. Language-Specific Severity Calibration + +*Priority:* MEDIUM + +*Problem:* For Rust codebases, 0 unsafe blocks combined with 0 +production unwraps represents an exceptionally strong safety posture. +However, panic-attack still assigns non-trivial risk scores based on +allocation site counts alone. A crate with zero ways to reach a panic +path should be classified as "`clean`" or "`hardened,`" not flagged with +residual risk. + +*Proposed solution:* + +* Introduce a "`hardened`" or "`clean`" severity tier for codebases that +meet language-specific safety criteria. +* For Rust, the criteria would be: 0 unsafe blocks, 0 production +`+.unwrap()+` / `+.expect()+` calls (excluding test code), and presence +of `+Result+`-based error handling with `+?+` propagation. +* Allocation sites alone should not elevate severity. They should be +reported as informational context, not risk indicators, unless combined +with unsafe blocks or unbounded allocation patterns. +* Allow language-specific scoring profiles so that a Rust crate with no +unsafe code is evaluated differently from a C program with manual memory +management. + +*Impact:* Reduces false severity inflation on well-engineered Rust +codebases and makes the severity metric more meaningful across +languages. + +''''' + +==== 5. Workspace-Level Consolidated Reporting + +*Priority:* MEDIUM + +*Problem:* When scanning a Cargo workspace with 10 crates, panic-attack +produces 10 independent reports with no aggregate view. Users must +manually collate results to understand workspace-level health. There is +no way to identify which crate contributes the most risk or how the +workspace compares overall to other projects. + +*Proposed solution:* + +* Detect Cargo workspaces (presence of `+[workspace]+` in root +`+Cargo.toml+`) and automatically scan all member crates. +* Produce a consolidated report with: +** Per-crate breakdowns (individual scores and findings). +** Workspace-level totals (aggregate weak points, overall severity). +** A "`top offenders`" summary listing the crates with the highest risk. +** Shared dependency analysis (which dependencies appear across crates). +* Support `+--workspace+` flag for explicit workspace scanning. +* In JSON output, nest per-crate results under a `+workspace+` object +with metadata about the workspace itself. + +*Impact:* Enables meaningful assessment of multi-crate projects, which +represent the majority of non-trivial Rust codebases. + +''''' + +==== 6. Differential Scanning (Before/After Comparison) + +*Priority:* MEDIUM — *Status: SHIPPED* (`+Commands::Diff+`, +`+src/main.rs:483+`; logic in `+src/report/diff.rs+`) + +*Problem:* There is no way to compare two scans to show what improved or +regressed between them. This limits the tool’s usefulness in CI +pipelines, where the primary question is "`did this change make things +better or worse?`" + +*Proposed solution:* + +* Add a `+panic-attack diff +` subcommand +that compares two scan results. +* Output should show: +** New findings (present in current but not baseline). +** Resolved findings (present in baseline but not current). +** Changed severity (findings that moved between severity tiers). +** Net change in weak point count and severity score. +* Support exit codes for CI: exit 0 if no regressions, exit 1 if new +findings or severity increases detected. +* Optionally accept a `+--baseline+` flag in the `+assail+` command to +perform the comparison inline: +`+panic-attack assail . --baseline previous.json+`. + +*Impact:* Makes panic-attack viable as a CI gate that detects +regressions without requiring manual report comparison. + +''''' + +==== 7. Allocation Site Context and Classification + +*Priority:* MEDIUM + +*Problem:* Reporting "`73 allocation sites`" without context is not +actionable. A `+Vec::new()+` in a function with bounded iteration is +safe. A `+Vec::with_capacity(user_input)+` is a potential +denial-of-service vector. The current report does not distinguish +between these cases. + +*Proposed solution:* + +* Classify allocation sites into categories: +** *Bounded:* Allocation size is a compile-time constant or derived from +a bounded source (e.g., `+Vec::with_capacity(256)+`). +** *Internally bounded:* Allocation depends on internal state that the +program controls (e.g., `+Vec::new()+` in a loop with a fixed upper +bound). +** *User-controlled:* Allocation size depends on external input (e.g., +`+Vec::with_capacity(header.length)+`). +** *Unknown:* Allocation size cannot be statically determined. +* Only flag user-controlled and unknown allocations as potential risk. +* Report bounded allocations as informational. + +*Impact:* Transforms allocation site reporting from noise into a useful +signal for identifying actual denial-of-service vectors. + +''''' + +==== 8. Resource Dimension Awareness for Domain-Specific Languages + +*Priority:* LOW + +*Problem:* Eclexia is a domain-specific language with first-class +resource types (energy, carbon, latency). Programs written in Eclexia +manage resource budgets as part of their core semantics. panic-attack +has no awareness of these domain-specific resource dimensions and +therefore cannot detect unbounded resource consumption patterns in +Eclexia programs. + +*Proposed solution:* + +* Add an extensible resource dimension system that allows +language-specific analyzers to define custom resource types beyond +CPU/memory/disk/network. +* For Eclexia specifically, detect: +** `+@resource_constraint+` blocks and verify they have bounded +consumption. +** `+@solution+` blocks and check that fallback paths exist. +** Resource type declarations and flag any that lack upper bounds. +* Implement this as a plugin or analyzer extension rather than +hard-coding Eclexia-specific logic into the core tool. +* Generalize the pattern: any language with resource annotations (Rust’s +`+#[must_use]+`, Ada’s resource management, etc.) could benefit from +similar awareness. + +*Impact:* Extends panic-attack’s value proposition to domain-specific +languages with resource semantics. Requires language-specific investment +but aligns with the long-term vision of universal constraint testing. + +''''' + +==== 9. Pattern Detection for Safe Error Handling + +*Priority:* LOW + +*Problem:* panic-attack does not recognize structured error handling +patterns. A crate that consistently uses `+Result+` +with `+?+` propagation throughout its public API has a fundamentally +different risk profile from one that uses `+.unwrap()+` liberally. The +current analysis treats both the same. + +*Proposed solution:* + +* Detect and score the following safe error handling patterns: +** `+Result+` return types on public functions. +** Consistent use of `+?+` operator for error propagation. +** Custom error types with `+From+` implementations for error +conversion. +** `+thiserror+` or `+anyhow+` usage patterns. +* Introduce an "`error handling maturity`" metric: +** *Level 0:* No structured error handling (raw panics). +** *Level 1:* Partial `+Result+` usage with frequent `+.unwrap()+`. +** *Level 2:* Consistent `+Result+` usage with occasional `+.unwrap()+`. +** *Level 3:* Full `+Result+` propagation, custom error types, no +production `+.unwrap()+` calls. +* Use this metric as a positive modifier on severity scoring: higher +maturity should reduce overall severity. + +*Impact:* Rewards disciplined error handling and produces more accurate +risk assessments for Rust codebases that invest in proper error +management. + +''''' + +==== 10. Configurable Severity Thresholds for CI + +*Priority:* LOW + +*Problem:* panic-attack produces severity ratings but does not support +project-specific pass/fail criteria. Different projects have different +standards – a safety-critical system might require 0 unsafe blocks while +a prototype might tolerate higher risk. Without configurable thresholds, +CI integration requires external scripting to interpret results. + +*Proposed solution:* + +* Add a `+[thresholds]+` section to `+panic-attack.toml+`: ++ +[source,toml] +---- +[thresholds] +max_unsafe_blocks = 0 +max_production_unwraps = 5 +max_severity = "low" +max_weak_points = 20 +require_error_handling_level = 2 +---- +* When thresholds are configured, `+panic-attack assail+` should produce +a pass/fail verdict in addition to the detailed report. +* Exit code 0 for pass, exit code 1 for fail, with clear indication of +which thresholds were violated. +* Support per-crate threshold overrides in workspace mode. +* Allow threshold inheritance: define workspace-level defaults with +per-crate overrides for crates with special requirements. + +*Impact:* Makes panic-attack directly usable as a CI gate without +external wrapper scripts, supporting project-specific quality standards. + +''''' + +=== Implementation Notes + +==== Dependency on Existing Architecture + +Improvements 1-4 (test code exclusion, framework detection, unwrap +variant distinction, and severity calibration) are modifications to the +existing Rust analyzer in `+src/assail/mod.rs+`. They can be implemented +incrementally without architectural changes. + +Improvement 5 (workspace consolidation) requires a new scanning mode in +`+src/main.rs+` and a new report aggregation layer, but reuses the +existing per-crate scan logic. + +Improvement 6 (differential scanning) is a new subcommand that operates +on JSON output files. It is independent of the scan engine and can be +implemented at any time. + +Improvements 7-9 (allocation context, resource dimensions, error +handling patterns) require deeper static analysis capabilities. They +should be planned for post-v1.0 milestones. + +Improvement 10 (configurable thresholds) extends the existing +`+panic-attack.toml+` configuration and is straightforward to implement +once the metrics it depends on (from improvements 1-4) are accurate. + +==== Recommended Implementation Order + +[arabic] +. Test code exclusion (improvement 1) – highest impact, lowest effort. +. Safe unwrap variant distinction (improvement 3) – high impact, low +effort, same code area as improvement 1. +. Framework detection accuracy (improvement 2) – high impact, moderate +effort. +. Language-specific severity calibration (improvement 4) – depends on +improvements 1 and 3 being complete. +. Workspace consolidation (improvement 5) – independent track, can +proceed in parallel with 1-4. +. Differential scanning (improvement 6) – independent track, high CI +value. +. Allocation site context (improvement 7) – post-v1.0. +. Error handling patterns (improvement 9) – post-v1.0. +. Configurable thresholds (improvement 10) – depends on 1-4. +. Resource dimension awareness (improvement 8) – long-term. + +==== Relationship to Existing Roadmap + +This document complements `+ROADMAP.md+` and `+VISION.md+`. The +improvements described here are specific, actionable findings from +real-world usage, whereas the roadmap covers broader feature milestones. +Several items overlap with planned roadmap work: + +* Improvement 5 overlaps with the planned `+sweep+` subcommand. +* Improvement 6 overlaps with v0.8 "`Comparative reports (diff two +Assail runs)`". +* Improvement 10 overlaps with v0.8 "`Exit codes that CI can act on.`" + +These improvements should be incorporated into the relevant roadmap +milestones rather than tracked separately. + +''''' + +=== Authors + +* *Analysis and writing:* Jonathan D.A. Jewell +* *Scan session:* 2026-02-08 +* *Tool version:* panic-attack v1.0.0 diff --git a/FUTURE-IMPROVEMENTS.md b/FUTURE-IMPROVEMENTS.md deleted file mode 100644 index 74c93b5..0000000 --- a/FUTURE-IMPROVEMENTS.md +++ /dev/null @@ -1,442 +0,0 @@ - - -# Future Improvements: Insights from Scanning the Eclexia Compiler Toolchain - -**Date:** 2026-02-08 -**Audit refreshed:** 2026-05-26 (4 of 10 items shipped; status block at top) -**Author:** Jonathan D.A. Jewell -**Context:** panic-attack v1.0.0 at time of scan; current v2.5.0 - ---- - -## Status at 2026-05-26 - -| # | Improvement | Status | Evidence | -|---|-------------|--------|----------| -| 1 | Test Code Exclusion | **Shipped** | `Analyzer::strip_cfg_test_modules_rs` — `src/assail/analyzer.rs:923-934`. Applied globally before pattern counting; CLAUDE.md confirms cfg(test) skip behaviour. | -| 2 | Framework Detection Accuracy | **Shipped** | `Analyzer::detect_frameworks` — `src/assail/analyzer.rs:4993`. Dependency-aware classification supersedes the heuristic-only path that misfired on Eclexia. | -| 3 | Safe Unwrap Variant Distinction | **Shipped** | `safe_unwrap_calls` field on `ProgramStatistics` (`src/types.rs:518`) and `FileStatistics` (`src/types.rs:451`). Counted but excluded from PA006 (PanicPath) per CLAUDE.md. | -| 4 | Language-Specific Severity Calibration | Outstanding | No "Hardened" or "Clean" severity tier in `src/types.rs`. Still gated on items 1 + 3 being trustworthy, which they now are. | -| 5 | Workspace-Level Consolidated Reporting | Outstanding | No Cargo workspace mode in `src/main.rs`. `mass-panic` covers cross-repo but not single-workspace aggregation. | -| 6 | Differential Scanning | **Shipped** | `Commands::Diff` — `src/main.rs:483`; logic in `src/report/diff.rs`. Listed in ROADMAP v2.2.0 as `[x]`. | -| 7 | Allocation Site Context and Classification | Outstanding | No `AllocationCategory` enum in `src/types.rs`. Site counts still raw. | -| 8 | Resource Dimension Awareness for DSLs | Outstanding | Long-term; no plugin-extension surface yet. | -| 9 | Pattern Detection for Safe Error Handling | Outstanding | No "error handling maturity" metric. | -| 10 | Configurable Severity Thresholds for CI | Outstanding | No `[thresholds]` parser; no `panic-attack.toml` consumer. Now unblocked because 1, 2, 3 are accurate. | - -**Net:** 4/10 shipped (1, 2, 3, 6). Items 4 and 10 are now genuinely unblocked because their stated dependencies (1, 2, 3) have landed; the original "depends on" notes are still accurate but no longer blocking. Items 5, 7, 8, 9 remain as written. - ---- - -## Executive Summary - -Scanning the Eclexia compiler toolchain with `panic-attack assail` exposed -several categories of false positives, misdetections, and missing features -that reduce the tool's signal-to-noise ratio on well-engineered Rust -codebases. This document captures the specific observations and proposes -concrete improvements, prioritised for implementation. - -The core finding is that panic-attack currently treats all code uniformly -- -test code is scored the same as production code, safe unwrap variants are -counted alongside unsafe ones, and severity ratings do not account for -language-specific safety guarantees. For a codebase like Eclexia with zero -unsafe blocks, zero production unwraps, and comprehensive error handling via -`Result<_, RuntimeError>`, the current output overstates risk significantly. - -These improvements would benefit any Rust workspace scan, not just Eclexia. - ---- - -## Completed Observations - -The following observations were made during the Eclexia scan session: - -1. **Eclexia profile:** 10 crates, ~20,000 lines of Rust, 0 unsafe blocks, - 0 production unwrap calls, full `Result`-based error handling with custom - `RuntimeError` type and `?` propagation throughout. - -2. **False positive rate:** The `builtins.rs` module was flagged with 96 - unwrap calls and 13 panic sites, all of which reside exclusively within - `#[cfg(test)]` modules. This produced a "Medium" severity finding for a - file with zero production panic paths. - -3. **Framework misdetection:** panic-attack reported "WebServer" as the - detected framework for pure compiler crates that perform zero I/O - operations (no network, no HTTP, no filesystem serving). - -4. **Safe unwrap variants counted as risks:** Calls to `.unwrap_or(1)`, - `.unwrap_or_default()`, and `.unwrap_or_else(|| ...)` were counted - toward the `unwrap_calls` metric. These are safe patterns that cannot - panic and should not contribute to risk scoring. - -5. **Severity not calibrated for Rust safety guarantees:** A crate with 0 - unsafe blocks, 0 production unwraps, and comprehensive `Result` - propagation still received non-trivial risk scores due to allocation - site counts alone. - -6. **No workspace-level consolidation:** Scanning 10 crates individually - produced 10 separate reports with no aggregate view of workspace health. - -7. **No differential capability:** There is no way to compare a scan before - and after a refactoring to show what improved or regressed. - -8. **Allocation sites lack context:** The report stated "73 allocation - sites" without distinguishing between `Vec::new()` (safe, bounded) and - user-controlled allocations (potentially unbounded). - ---- - -## Proposed Improvements - -### 1. Test Code Exclusion - -**Priority:** HIGH — **Status: SHIPPED** (`Analyzer::strip_cfg_test_modules_rs`, `src/assail/analyzer.rs:923-934`) - -**Problem:** panic-attack counts `unwrap()` and `panic!()` calls inside -`#[cfg(test)]` modules, `#[test]` functions, and files in `tests/` -directories as production panic paths. This produces false positives for -any well-tested codebase. In the Eclexia scan, 100% of the unwrap and -panic findings in `builtins.rs` (96 unwrap calls, 13 panic sites) were -test-only code, yet the file received a "Medium" severity rating. - -**Proposed solution:** - -- Parse `#[cfg(test)]` module boundaries and `#[test]` function boundaries - in the Rust analyzer. -- Exclude files matching `tests/**`, `test_*.rs`, `*_test.rs` patterns. -- Report test code metrics separately (e.g., `test_unwrap_calls`) so they - remain visible but do not affect severity scoring. -- Add a `--include-test-code` flag for users who want the current behaviour. - -**Impact:** Eliminates the single largest source of false positives on -well-tested Rust codebases. - ---- - -### 2. Framework Detection Accuracy - -**Priority:** HIGH — **Status: SHIPPED** (`Analyzer::detect_frameworks`, `src/assail/analyzer.rs:4993`) - -**Problem:** panic-attack reports "WebServer" as the detected framework for -pure compiler crates with zero I/O operations. This is a misdetection that -undermines trust in the tool's output. The Eclexia crates have no HTTP -dependencies, no server bindings, and no network code. - -**Proposed solution:** - -- Revise framework detection heuristics to require evidence of actual I/O - patterns (e.g., TCP listeners, HTTP handlers, route definitions), not - just crate structure. -- Add a "None" or "CLI" framework classification for projects that do not - match any framework pattern. -- Consider inspecting `Cargo.toml` dependencies as a signal: presence of - `actix-web`, `axum`, `warp`, `rocket`, or `hyper` strongly indicates a - web server; absence of these with presence of `clap`, `structopt`, or - a `[[bin]]` target suggests a CLI tool. -- For library crates with no binary target and no I/O dependencies, default - to "Library" rather than guessing a framework. - -**Impact:** Prevents misleading framework labels that erode confidence in -the overall report. - ---- - -### 3. Safe Unwrap Variant Distinction - -**Priority:** HIGH — **Status: SHIPPED** (`safe_unwrap_calls` field on `ProgramStatistics`/`FileStatistics`, `src/types.rs:451,518`) - -**Problem:** The Rust analyzer counts `.unwrap_or(value)`, -`.unwrap_or_default()`, and `.unwrap_or_else(|| ...)` toward the -`unwrap_calls` metric. These methods are safe alternatives to `.unwrap()` -that cannot panic -- they provide fallback values instead. Counting them as -risks conflates safe error handling with unsafe panic paths. - -**Proposed solution:** - -- Distinguish between panic-capable unwrap calls (`.unwrap()`, - `.expect("...")`) and safe variants (`.unwrap_or(...)`, - `.unwrap_or_default()`, `.unwrap_or_else(|| ...)`). -- Report safe variants in a separate metric (e.g., `safe_unwrap_calls`) - that does not contribute to severity scoring. -- Optionally report the ratio of safe-to-unsafe unwraps as a code quality - signal: a high ratio indicates disciplined error handling. - -**Impact:** Improves accuracy of the core unwrap metric, which is one of -the primary signals in Rust analysis. - ---- - -### 4. Language-Specific Severity Calibration - -**Priority:** MEDIUM - -**Problem:** For Rust codebases, 0 unsafe blocks combined with 0 production -unwraps represents an exceptionally strong safety posture. However, -panic-attack still assigns non-trivial risk scores based on allocation site -counts alone. A crate with zero ways to reach a panic path should be -classified as "clean" or "hardened," not flagged with residual risk. - -**Proposed solution:** - -- Introduce a "hardened" or "clean" severity tier for codebases that meet - language-specific safety criteria. -- For Rust, the criteria would be: 0 unsafe blocks, 0 production - `.unwrap()` / `.expect()` calls (excluding test code), and presence of - `Result`-based error handling with `?` propagation. -- Allocation sites alone should not elevate severity. They should be - reported as informational context, not risk indicators, unless combined - with unsafe blocks or unbounded allocation patterns. -- Allow language-specific scoring profiles so that a Rust crate with no - unsafe code is evaluated differently from a C program with manual memory - management. - -**Impact:** Reduces false severity inflation on well-engineered Rust -codebases and makes the severity metric more meaningful across languages. - ---- - -### 5. Workspace-Level Consolidated Reporting - -**Priority:** MEDIUM - -**Problem:** When scanning a Cargo workspace with 10 crates, panic-attack -produces 10 independent reports with no aggregate view. Users must manually -collate results to understand workspace-level health. There is no way to -identify which crate contributes the most risk or how the workspace compares -overall to other projects. - -**Proposed solution:** - -- Detect Cargo workspaces (presence of `[workspace]` in root `Cargo.toml`) - and automatically scan all member crates. -- Produce a consolidated report with: - - Per-crate breakdowns (individual scores and findings). - - Workspace-level totals (aggregate weak points, overall severity). - - A "top offenders" summary listing the crates with the highest risk. - - Shared dependency analysis (which dependencies appear across crates). -- Support `--workspace` flag for explicit workspace scanning. -- In JSON output, nest per-crate results under a `workspace` object with - metadata about the workspace itself. - -**Impact:** Enables meaningful assessment of multi-crate projects, which -represent the majority of non-trivial Rust codebases. - ---- - -### 6. Differential Scanning (Before/After Comparison) - -**Priority:** MEDIUM — **Status: SHIPPED** (`Commands::Diff`, `src/main.rs:483`; logic in `src/report/diff.rs`) - -**Problem:** There is no way to compare two scans to show what improved or -regressed between them. This limits the tool's usefulness in CI pipelines, -where the primary question is "did this change make things better or worse?" - -**Proposed solution:** - -- Add a `panic-attack diff ` subcommand that - compares two scan results. -- Output should show: - - New findings (present in current but not baseline). - - Resolved findings (present in baseline but not current). - - Changed severity (findings that moved between severity tiers). - - Net change in weak point count and severity score. -- Support exit codes for CI: exit 0 if no regressions, exit 1 if new - findings or severity increases detected. -- Optionally accept a `--baseline` flag in the `assail` command to perform - the comparison inline: `panic-attack assail . --baseline previous.json`. - -**Impact:** Makes panic-attack viable as a CI gate that detects regressions -without requiring manual report comparison. - ---- - -### 7. Allocation Site Context and Classification - -**Priority:** MEDIUM - -**Problem:** Reporting "73 allocation sites" without context is not -actionable. A `Vec::new()` in a function with bounded iteration is safe. A -`Vec::with_capacity(user_input)` is a potential denial-of-service vector. -The current report does not distinguish between these cases. - -**Proposed solution:** - -- Classify allocation sites into categories: - - **Bounded:** Allocation size is a compile-time constant or derived from - a bounded source (e.g., `Vec::with_capacity(256)`). - - **Internally bounded:** Allocation depends on internal state that the - program controls (e.g., `Vec::new()` in a loop with a fixed upper - bound). - - **User-controlled:** Allocation size depends on external input (e.g., - `Vec::with_capacity(header.length)`). - - **Unknown:** Allocation size cannot be statically determined. -- Only flag user-controlled and unknown allocations as potential risk. -- Report bounded allocations as informational. - -**Impact:** Transforms allocation site reporting from noise into a useful -signal for identifying actual denial-of-service vectors. - ---- - -### 8. Resource Dimension Awareness for Domain-Specific Languages - -**Priority:** LOW - -**Problem:** Eclexia is a domain-specific language with first-class resource -types (energy, carbon, latency). Programs written in Eclexia manage -resource budgets as part of their core semantics. panic-attack has no -awareness of these domain-specific resource dimensions and therefore cannot -detect unbounded resource consumption patterns in Eclexia programs. - -**Proposed solution:** - -- Add an extensible resource dimension system that allows language-specific - analyzers to define custom resource types beyond CPU/memory/disk/network. -- For Eclexia specifically, detect: - - `@resource_constraint` blocks and verify they have bounded consumption. - - `@solution` blocks and check that fallback paths exist. - - Resource type declarations and flag any that lack upper bounds. -- Implement this as a plugin or analyzer extension rather than hard-coding - Eclexia-specific logic into the core tool. -- Generalize the pattern: any language with resource annotations (Rust's - `#[must_use]`, Ada's resource management, etc.) could benefit from - similar awareness. - -**Impact:** Extends panic-attack's value proposition to domain-specific -languages with resource semantics. Requires language-specific investment -but aligns with the long-term vision of universal constraint testing. - ---- - -### 9. Pattern Detection for Safe Error Handling - -**Priority:** LOW - -**Problem:** panic-attack does not recognize structured error handling -patterns. A crate that consistently uses `Result` with -`?` propagation throughout its public API has a fundamentally different -risk profile from one that uses `.unwrap()` liberally. The current analysis -treats both the same. - -**Proposed solution:** - -- Detect and score the following safe error handling patterns: - - `Result` return types on public functions. - - Consistent use of `?` operator for error propagation. - - Custom error types with `From` implementations for error conversion. - - `thiserror` or `anyhow` usage patterns. -- Introduce an "error handling maturity" metric: - - **Level 0:** No structured error handling (raw panics). - - **Level 1:** Partial `Result` usage with frequent `.unwrap()`. - - **Level 2:** Consistent `Result` usage with occasional `.unwrap()`. - - **Level 3:** Full `Result` propagation, custom error types, no - production `.unwrap()` calls. -- Use this metric as a positive modifier on severity scoring: higher - maturity should reduce overall severity. - -**Impact:** Rewards disciplined error handling and produces more accurate -risk assessments for Rust codebases that invest in proper error management. - ---- - -### 10. Configurable Severity Thresholds for CI - -**Priority:** LOW - -**Problem:** panic-attack produces severity ratings but does not support -project-specific pass/fail criteria. Different projects have different -standards -- a safety-critical system might require 0 unsafe blocks while -a prototype might tolerate higher risk. Without configurable thresholds, -CI integration requires external scripting to interpret results. - -**Proposed solution:** - -- Add a `[thresholds]` section to `panic-attack.toml`: - - ```toml - [thresholds] - max_unsafe_blocks = 0 - max_production_unwraps = 5 - max_severity = "low" - max_weak_points = 20 - require_error_handling_level = 2 - ``` - -- When thresholds are configured, `panic-attack assail` should produce a - pass/fail verdict in addition to the detailed report. -- Exit code 0 for pass, exit code 1 for fail, with clear indication of - which thresholds were violated. -- Support per-crate threshold overrides in workspace mode. -- Allow threshold inheritance: define workspace-level defaults with - per-crate overrides for crates with special requirements. - -**Impact:** Makes panic-attack directly usable as a CI gate without -external wrapper scripts, supporting project-specific quality standards. - ---- - -## Implementation Notes - -### Dependency on Existing Architecture - -Improvements 1-4 (test code exclusion, framework detection, unwrap variant -distinction, and severity calibration) are modifications to the existing -Rust analyzer in `src/assail/mod.rs`. They can be implemented incrementally -without architectural changes. - -Improvement 5 (workspace consolidation) requires a new scanning mode in -`src/main.rs` and a new report aggregation layer, but reuses the existing -per-crate scan logic. - -Improvement 6 (differential scanning) is a new subcommand that operates on -JSON output files. It is independent of the scan engine and can be -implemented at any time. - -Improvements 7-9 (allocation context, resource dimensions, error handling -patterns) require deeper static analysis capabilities. They should be -planned for post-v1.0 milestones. - -Improvement 10 (configurable thresholds) extends the existing -`panic-attack.toml` configuration and is straightforward to implement -once the metrics it depends on (from improvements 1-4) are accurate. - -### Recommended Implementation Order - -1. Test code exclusion (improvement 1) -- highest impact, lowest effort. -2. Safe unwrap variant distinction (improvement 3) -- high impact, low - effort, same code area as improvement 1. -3. Framework detection accuracy (improvement 2) -- high impact, moderate - effort. -4. Language-specific severity calibration (improvement 4) -- depends on - improvements 1 and 3 being complete. -5. Workspace consolidation (improvement 5) -- independent track, can - proceed in parallel with 1-4. -6. Differential scanning (improvement 6) -- independent track, high CI - value. -7. Allocation site context (improvement 7) -- post-v1.0. -8. Error handling patterns (improvement 9) -- post-v1.0. -9. Configurable thresholds (improvement 10) -- depends on 1-4. -10. Resource dimension awareness (improvement 8) -- long-term. - -### Relationship to Existing Roadmap - -This document complements `ROADMAP.md` and `VISION.md`. The improvements -described here are specific, actionable findings from real-world usage, -whereas the roadmap covers broader feature milestones. Several items -overlap with planned roadmap work: - -- Improvement 5 overlaps with the planned `sweep` subcommand. -- Improvement 6 overlaps with v0.8 "Comparative reports (diff two Assail - runs)". -- Improvement 10 overlaps with v0.8 "Exit codes that CI can act on." - -These improvements should be incorporated into the relevant roadmap -milestones rather than tracked separately. - ---- - -## Authors - -- **Analysis and writing:** Jonathan D.A. Jewell -- **Scan session:** 2026-02-08 -- **Tool version:** panic-attack v1.0.0 diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/PROOF-NEEDS.adoc b/PROOF-NEEDS.adoc new file mode 100644 index 0000000..e893323 --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,101 @@ +== PROOF-NEEDS.md — panic-attack + +=== Current State + +* **src/abi/*.idr**: 5 files — `+Types.idr+`, +`+PatternCompleteness.idr+` (PA1 ✅ 2026-04-11), +`+ClassificationSoundness.idr+` (PA2 ✅ 2026-04-11), `+Stripping.idr+` +(PROOF-PROGRAMME Layer 1.0 line-comment slice ✅ 2026-06-02 — +multi-comment semantics + slash-slash closure both Qed via +mutual-recursive `+bodyIsFixedPoint+`), +`+AttestationUnforgeability.idr+` (PROOF-PROGRAMME §3.2 ✅ 2026-06-04 — +conditional unforgeability from Ed25519 EUF-CMA + chain-hash +collision-resistance hypotheses) +* *Dangerous patterns*: 0 in own code (3 references are in the analyzer +that DETECTS believe_me in other repos); 282 `+unwrap()+` calls +* *LOC*: ~31,700 (Rust) +* *ABI layer*: Idris2 with completeness + soundness proofs + Layer-1.0 +stripping foundation + +=== Completed Proofs + +[width="100%",cols="26%,21%,53%",options="header",] +|=== +|Proof |File |What it proves +|PA1 Pattern detection completeness |`+src/abi/PatternCompleteness.idr+` +|All 49 `+Lang+` constructors have an analyzer; all 20 `+WPCategory+` +constructors have at least one detector; cross-language checks applied +unconditionally to all languages. `+completeScanForAll+` is the +top-level theorem. + +|PA2 Classification soundness |`+src/abi/ClassificationSoundness.idr+` +|Severity (Low/Medium/High/Critical) is totally ordered (`+LTE+`); +`+maxSeverity+` is commutative and idempotent; numeric ABI encoding +preserves the ordering. + +|Layer 1.0 line-comment idempotence |`+src/abi/Stripping.idr+` +|*2026-06-02 close-out (issue #113)*: corrects PR #111’s single-comment +model to multi-comment via mutual recursion +(`+stripLineComments ↔ stripLineCommentBody+` — body calls back into +main after each preserved newline). Qed-closes +`+stripLineCommentsIdempotent+` for ALL cases including the slash-slash +inductive via the load-bearing `+bodyIsFixedPoint+` lemma proved by +mutual induction with the main theorem. 7 sanity-check theorems +including the two-comments-on-different-lines case PR #111 silently +mis-stripped. + +|Attestation chain unforgeability +|`+src/abi/AttestationUnforgeability.idr+` |*PROOF-PROGRAMME §3.2 +(2026-06-04, issue #123)*: models the intent→evidence→seal chain +(`+chain_hash = H(intent‖evidence‖report)+`, Ed25519-signed) with the +cryptographic facts as a `+parameters+` block (hypotheses, *not* +`+postulate+`). Under `+%default total+` Qed-closes `+integrity+` +(tampering any phase invalidates the seal), `+authenticity+` (a +verifying seal comes from the matching secret key), `+nonRepudiation+` +(a genuine seal verifies), plus 2 corollaries. Conditional on chain-hash +collision-resistance + Ed25519 EUF-CMA (message- and signer-binding) + +signature correctness. + +|Hexad↔Octad persistence round-trip |`+src/storage/mod.rs+` (proptest) +|*PROOF-PROGRAMME §3.1 (2026-06-04, #122)*: +`+hexad_json_roundtrip_is_identity+` proves the on-disk serde round-trip +(`+write_*_hexad+` → `+load_hexad_dir+`) is the identity on the hexad +JSON. The gateway octad projection is lossy by design, so the faithful +integrity property is the persistence round-trip, not the literal +hexad↔octad map. +|=== + +=== What Still Needs Proving + +[width="100%",cols="51%,27%,22%",options="header",] +|=== +|Component |What |Why +|*Layer 1.0 — stripBlockComments + Strings + Composition + +Position-Preservation* (issue #114) |Block-comment (`+/* */+`) and +string-literal (`+"..."+`) strippers with same mutual-recursive shape; +composition theorem proving the full pipeline is idempotent given each +component is; position-preservation theorem justifying analyzer +location-reporting against the stripped view as if it were +original-source. |Four slices: `+Stripping_Block.idr+`, +`+Stripping_Strings.idr+`, `+Stripping_Composition.idr+`, +`+Stripping_PositionPreservation.idr+`. + +|Bridge reachability soundness |Reachability analysis is sound (no +reachable dep wrongly classified as phantom) |Unreachable code marked +reachable wastes effort; reachable missed = security gap + +|Kanren taint analysis |Taint propagation tracks all tainted data flows +|Missed taint flow means missed vulnerability +|=== + +=== Recommended Prover + +*Idris2* — Already in use. Taint analysis correctness proofs could use +*Agda* with relational semantics. The 282 unwrap() calls are a +significant debt (but separate from the proof obligations). + +=== Priority + +*MEDIUM* (was HIGH) — PA1 and PA2 completed 2026-04-11. The highest-risk +false-negative scenario (analyzer dispatch completeness) is now formally +proved. Remaining proofs are deeper semantic properties. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index 60e466a..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,36 +0,0 @@ - - -# PROOF-NEEDS.md — panic-attack - -## Current State - -- **src/abi/*.idr**: 5 files — `Types.idr`, `PatternCompleteness.idr` (PA1 ✅ 2026-04-11), `ClassificationSoundness.idr` (PA2 ✅ 2026-04-11), `Stripping.idr` (PROOF-PROGRAMME Layer 1.0 line-comment slice ✅ 2026-06-02 — multi-comment semantics + slash-slash closure both Qed via mutual-recursive `bodyIsFixedPoint`), `AttestationUnforgeability.idr` (PROOF-PROGRAMME §3.2 ✅ 2026-06-04 — conditional unforgeability from Ed25519 EUF-CMA + chain-hash collision-resistance hypotheses) -- **Dangerous patterns**: 0 in own code (3 references are in the analyzer that DETECTS believe_me in other repos); 282 `unwrap()` calls -- **LOC**: ~31,700 (Rust) -- **ABI layer**: Idris2 with completeness + soundness proofs + Layer-1.0 stripping foundation - -## Completed Proofs - -| Proof | File | What it proves | -|-------|------|---------------| -| PA1 Pattern detection completeness | `src/abi/PatternCompleteness.idr` | All 49 `Lang` constructors have an analyzer; all 20 `WPCategory` constructors have at least one detector; cross-language checks applied unconditionally to all languages. `completeScanForAll` is the top-level theorem. | -| PA2 Classification soundness | `src/abi/ClassificationSoundness.idr` | Severity (Low/Medium/High/Critical) is totally ordered (`LTE`); `maxSeverity` is commutative and idempotent; numeric ABI encoding preserves the ordering. | -| Layer 1.0 line-comment idempotence | `src/abi/Stripping.idr` | **2026-06-02 close-out (issue #113)**: corrects PR #111's single-comment model to multi-comment via mutual recursion (`stripLineComments ↔ stripLineCommentBody` — body calls back into main after each preserved newline). Qed-closes `stripLineCommentsIdempotent` for ALL cases including the slash-slash inductive via the load-bearing `bodyIsFixedPoint` lemma proved by mutual induction with the main theorem. 7 sanity-check theorems including the two-comments-on-different-lines case PR #111 silently mis-stripped. | -| Attestation chain unforgeability | `src/abi/AttestationUnforgeability.idr` | **PROOF-PROGRAMME §3.2 (2026-06-04, issue #123)**: models the intent→evidence→seal chain (`chain_hash = H(intent‖evidence‖report)`, Ed25519-signed) with the cryptographic facts as a `parameters` block (hypotheses, **not** `postulate`). Under `%default total` Qed-closes `integrity` (tampering any phase invalidates the seal), `authenticity` (a verifying seal comes from the matching secret key), `nonRepudiation` (a genuine seal verifies), plus 2 corollaries. Conditional on chain-hash collision-resistance + Ed25519 EUF-CMA (message- and signer-binding) + signature correctness. | -| Hexad↔Octad persistence round-trip | `src/storage/mod.rs` (proptest) | **PROOF-PROGRAMME §3.1 (2026-06-04, #122)**: `hexad_json_roundtrip_is_identity` proves the on-disk serde round-trip (`write_*_hexad` → `load_hexad_dir`) is the identity on the hexad JSON. The gateway octad projection is lossy by design, so the faithful integrity property is the persistence round-trip, not the literal hexad↔octad map. | - -## What Still Needs Proving - -| Component | What | Why | -|-----------|------|-----| -| **Layer 1.0 — stripBlockComments + Strings + Composition + Position-Preservation** (issue #114) | Block-comment (`/* */`) and string-literal (`"..."`) strippers with same mutual-recursive shape; composition theorem proving the full pipeline is idempotent given each component is; position-preservation theorem justifying analyzer location-reporting against the stripped view as if it were original-source. | Four slices: `Stripping_Block.idr`, `Stripping_Strings.idr`, `Stripping_Composition.idr`, `Stripping_PositionPreservation.idr`. | -| Bridge reachability soundness | Reachability analysis is sound (no reachable dep wrongly classified as phantom) | Unreachable code marked reachable wastes effort; reachable missed = security gap | -| Kanren taint analysis | Taint propagation tracks all tainted data flows | Missed taint flow means missed vulnerability | - -## Recommended Prover - -**Idris2** — Already in use. Taint analysis correctness proofs could use **Agda** with relational semantics. The 282 unwrap() calls are a significant debt (but separate from the proof obligations). - -## Priority - -**MEDIUM** (was HIGH) — PA1 and PA2 completed 2026-04-11. The highest-risk false-negative scenario (analyzer dispatch completeness) is now formally proved. Remaining proofs are deeper semantic properties. diff --git a/PROOF-PROGRAMME.adoc b/PROOF-PROGRAMME.adoc new file mode 100644 index 0000000..7726fb8 --- /dev/null +++ b/PROOF-PROGRAMME.adoc @@ -0,0 +1,325 @@ +== PROOF-PROGRAMME.md — panic-attack from first principles + +____ +Strategic plan for moving panic-attack from "`two completed sibling +Idris2 proofs (PA1 + PA2)`" to *end-to-end formal soundness* of +detection, inference, and persistence — without changing perf or +functionality. +____ + +=== Status as of 2026-06-02 + +==== Completed proofs + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|ID |File |Mechanises +|*PA1* |`+src/abi/PatternCompleteness.idr+` |Every `+Lang+` constructor +has at least one analyzer; every `+WPCategory+` has at least one +detector; cross-language checks apply uniformly. Top theorem: +`+completeScanForAll+`. + +|*PA2* |`+src/abi/ClassificationSoundness.idr+` |`+Severity+` is totally +ordered (`+LTE+`); `+maxSeverity+` is commutative + idempotent; numeric +ABI encoding preserves the ordering. +|=== + +==== Open obligations (from `+PROOF-NEEDS.md+` line 19–23) + +[width="100%",cols="50%,50%",options="header",] +|=== +|Component |Property +|Bridge reachability soundness |No reachable dep wrongly classified as +phantom. + +|Attestation chain unforgeability |Intent/evidence/seal triple +cryptographically binds; tampering detectable. + +|Kanren taint analysis |Taint propagation tracks *every* tainted +dataflow (no missed sinks). +|=== + +=== Three-layer landscape + +==== Layer 1 — *Surface* (per-category detection soundness + completeness) + +For each `+WeakPointCategory+`, two properties: - *Soundness*: every +detector emission corresponds to a real instance of the pattern. - +*Completeness*: every real instance of the pattern is detected (modulo +declared scope — e.g. test files, see [[v2.5.5 test_context]]). + +PA1 proves _dispatch_ completeness (every category has a detector). PA2 +proves _severity ordering_ on what’s emitted. Layer-1 work extends this +*per category* to the pattern-recognition function itself. + +Layer 1.0 — *Common machinery* (one-time, foundational): - Formalise +`+Pattern+` as a regex/AST predicate over normalised source. - Prove the +comment / string-literal stripping function +(`+strip_inline_cfg_test_modules+` + global comment-strip) is +*idempotent* and *preserves non-token positions*. This justifies the +analyzer’s stripping pass as a sound preprocessing step. - Recommended +prover: *Idris2* (sibling to existing PA1/PA2). Difficulty: medium. +Value: every category proof becomes a simple application of Layer 1.0 + +the category’s regex. + +Layer 1.1–1.25 — *Per category* (25 obligations, parallelisable): + +For PA001..PA025 each, state and prove: + +.... +soundness : (file : String) -> (locs : List Loc) + -> detect category file = Just locs + -> AllOf (\loc => isInstanceOf category (locate file loc)) locs + +completeness : (file : String) -> (loc : Loc) + -> isInstanceOf category (locate file loc) + -> stripFalsePositives category file loc = NotSuppressed + -> Elem loc (Maybe.toList (detect category file)) +.... + +Worked example — *PA004 (UnsafeCode)*: + +[source,idris] +---- +-- src/abi/PA004_UnsafeCode.idr +SoundnessPA004 : (file : String) -> (loc : Loc) + -> contains (stripStrings file) "unsafe " loc + -> isUnsafeBlock (locate file loc) +---- + +This is _decidable_ because `+contains+` is a constructive predicate. +The matching Rust detector at `+src/assail/analyzer.rs:1052+` simply +mirrors the same predicate. + +*Estimate*: 25 obligations × ~30 LoC each = ~750 LoC of Idris2 proof; ~2 +weeks of focused work. + +*Cross-fit with `+proven+`*: Layer-1 categories that wrap simple +validators (PA017 `+PathTraversal+`, PA022 `+CryptoMisuse+` on the +hash-algorithm side) can borrow proofs from `+proven+`’s `+SafePath+` +and `+SafeCrypto+` directly — see link:#proven-cross-fit[proven +swap-outs] below. + +==== Layer 2 — *Engine* (inference: miniKanren + taint) + +===== 2.1 miniKanren unification soundness + +`+src/kanren/core.rs+` ships a v2.0.0 microKanren-style engine: +`+Term+`, `+Substitution+`, `+Goal+`, `+mplus+`/`+bind+`. Three +properties to mechanise: + +[arabic] +. *Unification correctness* — `+unify(u, v, σ)+` returns `+σ'+` iff +there’s an mgu `+θ+` with `+θ(u) = θ(v)+` extending `+σ+`. +. *Substitution composition* — `+walk*(t, σ)+` is the canonical +representative of `+t+`’s equivalence class in `+σ+`. +. *Search completeness* — `+mplus+` interleaving doesn’t drop a +satisfiable goal under bounded depth. + +Recommended prover: *Coq* (because the standard miniKanren correctness +proofs by Bender/Hemann use Coq; reuse their reasoning machinery). +Difficulty: hard but well-trodden. + +*Estimate*: ~1500 LoC Coq (Bender’s thesis is ~900 LoC; we extend with +our taint goals). 4 weeks. + +===== 2.2 Taint propagation completeness + +`+src/kanren/taint.rs+` defines taint flow rules (CommandInjection / +UnsafeDeserialization / DynamicCodeExecution / UnsafeFFI / +AtomExhaustion / PathTraversal). The property: + +____ +If a source-to-sink dataflow path exists in the program AST, the rule +engine emits a `+WeakPoint+` whose `+recommended_attack+` reflects the +sink category. +____ + +Two sub-obligations: - *Source coverage*: every taint source the rules +recognise is enumerated in a `+Datasource+` ADT and reflected in the +proof. - *Sink coverage*: same for sinks. - *Transitivity*: if +`+flows(a→b)+` and `+flows(b→c)+`, then `+flows(a→c)+`. + +Mechanise as a *fixed-point lattice* in Coq. The kanren engine becomes +the procedural computation of the lattice; the proof shows the +procedural answer = the least fixed point. + +===== 2.3 Cross-language analyzer soundness + +`+src/kanren/crosslang.rs+` — when a finding crosses an FFI boundary +(Rust ↔ Zig, Rust ↔ C, Python ↔ Rust), the cross-language rules emit a +`+UnsafeFFI+` weak point. Soundness here = the FFI boundary in the AST +is a real ABI boundary. + +This is *hard* because it requires modelling ABIs in the prover. Defer +to Layer-2 follow-up; PA1’s per-language detector dispatch already gives +us a coarse safety net. + +==== Layer 3 — *Persistence + Integrity* + +===== 3.1 Hexad↔Octad isomorphism + +`+src/storage/mod.rs+` defines `+PanicAttackHexad+` (6-tuple in +panic-attack’s own model) and pushes to verisimdb as an `+Octad+` +(8-tuple). The hexad has fewer fields; the octad adds `+attestation+` + +`+provenance+`. + +Property: the round-trip +`+panic-attack-hexad → verisimdb-octad → panic-attack-hexad+` is the +identity on the hexad fields. + +Recommended prover: *proptest* in Rust with `+arbitrary+` instances on +both records. The structural-equivalence proof is trivial enough (both +are records of `+Option+` and `+Vec+`) that property +testing is sufficient evidence; formalising in Idris2 would be busywork. + +*Estimate*: 50 LoC proptest, 1 day. + +===== 3.2 Attestation chain unforgeability + +`+src/attestation/{chain,envelope,evidence,intent,seal}.rs+`. The triple +is `+Intent → Evidence → Seal+`; the `+Seal+` includes an Ed25519 +signature over `+(Intent, Evidence)+`. + +Properties: 1. *Integrity*: tampering with `+Intent+` or `+Evidence+` +invalidates `+Seal+`. 2. *Authenticity*: only the holder of the signing +key can produce a valid `+Seal+`. 3. *Non-repudiation*: a valid `+Seal+` +is publicly verifiable. + +These reduce to standard Ed25519 properties (EUF-CMA). Mechanise via: - +A small Idris2 model of the chain with abstract `+Sig+` and `+Hash+` +operations. - An assumption +`+ed25519_euf_cma : ∀ k m m'. Verify(k, m, Sign(k, m)) ∧ ¬Verify(k, m', Sign(k, m))+`. +- Derive (1)–(3) from the assumption + chain structure. + +The proof is *trivial given the cryptographic assumption* — the work is +being honest about the assumption and matching it to the +`+ed25519-dalek+` API our Rust code uses. + +Recommended prover: *Idris2* (matches PA1/PA2; tiny). Difficulty: easy. +Value: high — attestation is load-bearing for the audit trail. + +*Estimate*: 200 LoC Idris2, 3 days. + +===== 3.3 Bridge reachability soundness + +`+src/bridge/reachability.rs+` walks `+Cargo.lock+` + crate graph to +classify deps as `+Mitigable+` / `+Unmitigable+` / `+Informational+`. +The "`phantom`" classification is the most consequential — a phantom dep +that’s actually reachable becomes a missed vuln. + +Property: `+classify(dep) = Phantom+` ⇒ `+dep+` does not appear on any +reachable path from the root crate. + +This is a *graph reachability* proof. Formalise the lockfile as a +labelled graph, the reachability predicate as transitive closure of dep +edges, and `+classify+` as a sound under-approximation: if it returns +Phantom, the corresponding reachability is False. + +Recommended prover: *Coq* (graph reasoning is well-trodden; Idris2 can +do it but Coq’s `+Set+` libraries are nicer for transitive closure). +Difficulty: medium. Value: high — this is the PR #87 issue from earlier. + +*Estimate*: ~600 LoC Coq, 1.5 weeks. + +=== Proven cross-fit + +From the `+hyperpolymath/proven+` survey (2026-06-02): two +leaf-validator candidates qualify as semantic-equivalent + perf-neutral: + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|# |Swap |Where |Path +|1 |`+SafePath::has_traversal+` + `+sanitize_filename+` +|`+src/abduct/mod.rs:123,266+`; `+src/main.rs:2314,2377+` +(`+fs::canonicalize(..).unwrap_or_else(\|_\| dir)+` patterns) +|*port-to-Rust* with proptest invariants against proven’s Idris2 +reference. NOT FFI (dylib build cost too high for `+cargo install+`). + +|2 |`+SafeUrl::parse+` |`+src/storage/mod.rs:1071+` `+VERISIMDB_URL+` +(currently raw `+String+`, no scheme/host validation before HTTP POST) +|*port-to-Rust* wrapping `+url::Url+` + proptest scheme-required +invariant. +|=== + +What `+proven+` does NOT cover (and Layer 1–3 must prove from first +principles): - miniKanren engine (Layer 2.1) - 49-language analyzer +dispatch (PA1 already covers this) - Hexad/Octad data model (Layer 3.1) +- A2ML attestation chain (Layer 3.2) - Bridge reachability (Layer 3.3) - +Sweep tracker / mass-panic temporal index (no equivalent) - Adjudicate / +Axial / Ambush / Abduct merge logic (bespoke) + +Skip (semantic mismatch or already-total): - `+SafeJson+` — +`+serde_json::from_str+` is already total + typed. - `+SafeRegex+` — +`+regex+` crate is already RE2-lineage (linear-time, ReDoS-safe). - +`+SafeDateTime+` — `+chrono::Utc::now().to_rfc3339()+` is total on emit. +- `+SafeCommand+` — `+Command::new(&str_args)+` doesn’t +shell-interpolate. - `+SafeEnv+` — env keys in panic-attack are +compile-time literals. - `+SafeUUID+` — semantic mismatch (we use +deterministic timestamps for replayability). + +=== Sequencing + +Recommended order (each row is parallel-iseable; rows are sequenced): + +[width="100%",cols="20%,20%,20%,20%,20%",options="header",] +|=== +|# |Phase |Output |Estimated effort |Risk +|1 |*Foundation*: Layer 1.0 (comment/string-strip idempotence + token +preservation) |`+src/abi/Stripping.idr+` + 1 Idris2 module |3–5 days +|low + +|2 |*Quick wins*: Hexad↔Octad roundtrip proptest + Layer 1 +PA001/PA004/PA017 |200 LoC Rust proptest + 3 Idris2 modules |1 week |low + +|3 |*Cross-fit*: SafePath + SafeUrl ports (with proptest against +`+proven+`’s Idris2 reference) |2 Rust modules + 2 proptest suites |1 +week |low + +|4 |*Persistence*: Attestation chain (Layer 3.2) |1 Idris2 module |1 +week |low + +|5 |*Engine*: miniKanren correctness (Layer 2.1, ~1500 LoC Coq) +|`+formal/Kanren.v+` |4 weeks |medium (well-trodden, but big) + +|6 |*Surface*: remaining PA categories (Layer 1.1–1.25 minus quick-wins) +|~22 Idris2 modules |4 weeks |medium + +|7 |*Reachability*: bridge soundness (Layer 3.3, Coq graph) +|`+formal/BridgeReachability.v+` |1.5 weeks |medium + +|8 |*Taint completeness*: kanren taint flow (Layer 2.2) |extends +`+formal/Kanren.v+` |3 weeks |high (fixpoint lattice + soundness +witness) + +|9 |*FFI ABI* (Layer 2.3 deferred — needs ABI modelling) |TBD |TBD |high +— defer until 1–8 land +|=== + +*Total to row 8*: ~16 calendar weeks of focused proof work for +"`panic-attack is provably sound to the per-category and per-flow +level`". After row 8, only the cross-language FFI ABI soundness remains +as an aspirational item. + +=== What this is NOT + +* *Not* a sweep to add `+Admitted+` placeholders. Every new Idris2 +module must `+Qed+`-close (or its Coq equivalent) before landing. If a +proof is too hard, the obligation stays open and we record it in +`+PROOF-NEEDS.md+` — that’s the honest path. +* *Not* a performance regression. proven swap-outs are explicitly +evaluated for perf neutrality; the rest of the programme is pure +docs/proof artefacts that don’t touch the hot path. +* *Not* a 25-PR storm. Group by phase; one PR per phase row above. + +=== References + +* `+PROOF-NEEDS.md+` — current proof-debt ledger (this document is the +long-term plan; that one tracks the immediate next step). +* `+src/abi/PatternCompleteness.idr+` (PA1) +* `+src/abi/ClassificationSoundness.idr+` (PA2) +* `+hyperpolymath/proven+` — leaf validator library; cross-fit +candidates listed above. +* ROADMAP.adoc "`Long-Term`" section: "`Formal verification of core +analysis rules (via proven library)`" — this document operationalises +that bullet. diff --git a/PROOF-PROGRAMME.md b/PROOF-PROGRAMME.md deleted file mode 100644 index 3dc1569..0000000 --- a/PROOF-PROGRAMME.md +++ /dev/null @@ -1,199 +0,0 @@ - - -# PROOF-PROGRAMME.md — panic-attack from first principles - -> Strategic plan for moving panic-attack from "two completed sibling Idris2 proofs (PA1 + PA2)" to **end-to-end formal soundness** of detection, inference, and persistence — without changing perf or functionality. - -## Status as of 2026-06-02 - -### Completed proofs - -| ID | File | Mechanises | -|---|---|---| -| **PA1** | `src/abi/PatternCompleteness.idr` | Every `Lang` constructor has at least one analyzer; every `WPCategory` has at least one detector; cross-language checks apply uniformly. Top theorem: `completeScanForAll`. | -| **PA2** | `src/abi/ClassificationSoundness.idr` | `Severity` is totally ordered (`LTE`); `maxSeverity` is commutative + idempotent; numeric ABI encoding preserves the ordering. | - -### Open obligations (from `PROOF-NEEDS.md` line 19–23) - -| Component | Property | -|---|---| -| Bridge reachability soundness | No reachable dep wrongly classified as phantom. | -| Attestation chain unforgeability | Intent/evidence/seal triple cryptographically binds; tampering detectable. | -| Kanren taint analysis | Taint propagation tracks **every** tainted dataflow (no missed sinks). | - -## Three-layer landscape - -### Layer 1 — **Surface** (per-category detection soundness + completeness) - -For each `WeakPointCategory`, two properties: -- **Soundness**: every detector emission corresponds to a real instance of the pattern. -- **Completeness**: every real instance of the pattern is detected (modulo declared scope — e.g. test files, see [[v2.5.5 test_context]]). - -PA1 proves *dispatch* completeness (every category has a detector). PA2 proves *severity ordering* on what's emitted. Layer-1 work extends this **per category** to the pattern-recognition function itself. - -Layer 1.0 — **Common machinery** (one-time, foundational): -- Formalise `Pattern` as a regex/AST predicate over normalised source. -- Prove the comment / string-literal stripping function (`strip_inline_cfg_test_modules` + global comment-strip) is **idempotent** and **preserves non-token positions**. This justifies the analyzer's stripping pass as a sound preprocessing step. -- Recommended prover: **Idris2** (sibling to existing PA1/PA2). Difficulty: medium. Value: every category proof becomes a simple application of Layer 1.0 + the category's regex. - -Layer 1.1–1.25 — **Per category** (25 obligations, parallelisable): - -For PA001..PA025 each, state and prove: -``` -soundness : (file : String) -> (locs : List Loc) - -> detect category file = Just locs - -> AllOf (\loc => isInstanceOf category (locate file loc)) locs - -completeness : (file : String) -> (loc : Loc) - -> isInstanceOf category (locate file loc) - -> stripFalsePositives category file loc = NotSuppressed - -> Elem loc (Maybe.toList (detect category file)) -``` - -Worked example — **PA004 (UnsafeCode)**: -```idris --- src/abi/PA004_UnsafeCode.idr -SoundnessPA004 : (file : String) -> (loc : Loc) - -> contains (stripStrings file) "unsafe " loc - -> isUnsafeBlock (locate file loc) -``` -This is *decidable* because `contains` is a constructive predicate. The matching Rust detector at `src/assail/analyzer.rs:1052` simply mirrors the same predicate. - -**Estimate**: 25 obligations × ~30 LoC each = ~750 LoC of Idris2 proof; ~2 weeks of focused work. - -**Cross-fit with `proven`**: Layer-1 categories that wrap simple validators (PA017 `PathTraversal`, PA022 `CryptoMisuse` on the hash-algorithm side) can borrow proofs from `proven`'s `SafePath` and `SafeCrypto` directly — see [proven swap-outs](#proven-cross-fit) below. - -### Layer 2 — **Engine** (inference: miniKanren + taint) - -#### 2.1 miniKanren unification soundness - -`src/kanren/core.rs` ships a v2.0.0 microKanren-style engine: `Term`, `Substitution`, `Goal`, `mplus`/`bind`. Three properties to mechanise: - -1. **Unification correctness** — `unify(u, v, σ)` returns `σ'` iff there's an mgu `θ` with `θ(u) = θ(v)` extending `σ`. -2. **Substitution composition** — `walk*(t, σ)` is the canonical representative of `t`'s equivalence class in `σ`. -3. **Search completeness** — `mplus` interleaving doesn't drop a satisfiable goal under bounded depth. - -Recommended prover: **Coq** (because the standard miniKanren correctness proofs by Bender/Hemann use Coq; reuse their reasoning machinery). Difficulty: hard but well-trodden. - -**Estimate**: ~1500 LoC Coq (Bender's thesis is ~900 LoC; we extend with our taint goals). 4 weeks. - -#### 2.2 Taint propagation completeness - -`src/kanren/taint.rs` defines taint flow rules (CommandInjection / UnsafeDeserialization / DynamicCodeExecution / UnsafeFFI / AtomExhaustion / PathTraversal). The property: - -> If a source-to-sink dataflow path exists in the program AST, the rule engine emits a `WeakPoint` whose `recommended_attack` reflects the sink category. - -Two sub-obligations: -- **Source coverage**: every taint source the rules recognise is enumerated in a `Datasource` ADT and reflected in the proof. -- **Sink coverage**: same for sinks. -- **Transitivity**: if `flows(a→b)` and `flows(b→c)`, then `flows(a→c)`. - -Mechanise as a **fixed-point lattice** in Coq. The kanren engine becomes the procedural computation of the lattice; the proof shows the procedural answer = the least fixed point. - -#### 2.3 Cross-language analyzer soundness - -`src/kanren/crosslang.rs` — when a finding crosses an FFI boundary (Rust ↔ Zig, Rust ↔ C, Python ↔ Rust), the cross-language rules emit a `UnsafeFFI` weak point. Soundness here = the FFI boundary in the AST is a real ABI boundary. - -This is **hard** because it requires modelling ABIs in the prover. Defer to Layer-2 follow-up; PA1's per-language detector dispatch already gives us a coarse safety net. - -### Layer 3 — **Persistence + Integrity** - -#### 3.1 Hexad↔Octad isomorphism - -`src/storage/mod.rs` defines `PanicAttackHexad` (6-tuple in panic-attack's own model) and pushes to verisimdb as an `Octad` (8-tuple). The hexad has fewer fields; the octad adds `attestation` + `provenance`. - -Property: the round-trip `panic-attack-hexad → verisimdb-octad → panic-attack-hexad` is the identity on the hexad fields. - -Recommended prover: **proptest** in Rust with `arbitrary` instances on both records. The structural-equivalence proof is trivial enough (both are records of `Option` and `Vec`) that property testing is sufficient evidence; formalising in Idris2 would be busywork. - -**Estimate**: 50 LoC proptest, 1 day. - -#### 3.2 Attestation chain unforgeability - -`src/attestation/{chain,envelope,evidence,intent,seal}.rs`. The triple is `Intent → Evidence → Seal`; the `Seal` includes an Ed25519 signature over `(Intent, Evidence)`. - -Properties: -1. **Integrity**: tampering with `Intent` or `Evidence` invalidates `Seal`. -2. **Authenticity**: only the holder of the signing key can produce a valid `Seal`. -3. **Non-repudiation**: a valid `Seal` is publicly verifiable. - -These reduce to standard Ed25519 properties (EUF-CMA). Mechanise via: -- A small Idris2 model of the chain with abstract `Sig` and `Hash` operations. -- An assumption `ed25519_euf_cma : ∀ k m m'. Verify(k, m, Sign(k, m)) ∧ ¬Verify(k, m', Sign(k, m))`. -- Derive (1)–(3) from the assumption + chain structure. - -The proof is **trivial given the cryptographic assumption** — the work is being honest about the assumption and matching it to the `ed25519-dalek` API our Rust code uses. - -Recommended prover: **Idris2** (matches PA1/PA2; tiny). Difficulty: easy. Value: high — attestation is load-bearing for the audit trail. - -**Estimate**: 200 LoC Idris2, 3 days. - -#### 3.3 Bridge reachability soundness - -`src/bridge/reachability.rs` walks `Cargo.lock` + crate graph to classify deps as `Mitigable` / `Unmitigable` / `Informational`. The "phantom" classification is the most consequential — a phantom dep that's actually reachable becomes a missed vuln. - -Property: `classify(dep) = Phantom` ⇒ `dep` does not appear on any reachable path from the root crate. - -This is a **graph reachability** proof. Formalise the lockfile as a labelled graph, the reachability predicate as transitive closure of dep edges, and `classify` as a sound under-approximation: if it returns Phantom, the corresponding reachability is False. - -Recommended prover: **Coq** (graph reasoning is well-trodden; Idris2 can do it but Coq's `Set` libraries are nicer for transitive closure). Difficulty: medium. Value: high — this is the PR #87 issue from earlier. - -**Estimate**: ~600 LoC Coq, 1.5 weeks. - -## Proven cross-fit - -From the `hyperpolymath/proven` survey (2026-06-02): two leaf-validator candidates qualify as semantic-equivalent + perf-neutral: - -| # | Swap | Where | Path | -|---|---|---|---| -| 1 | `SafePath::has_traversal` + `sanitize_filename` | `src/abduct/mod.rs:123,266`; `src/main.rs:2314,2377` (`fs::canonicalize(..).unwrap_or_else(\|_\| dir)` patterns) | **port-to-Rust** with proptest invariants against proven's Idris2 reference. NOT FFI (dylib build cost too high for `cargo install`). | -| 2 | `SafeUrl::parse` | `src/storage/mod.rs:1071` `VERISIMDB_URL` (currently raw `String`, no scheme/host validation before HTTP POST) | **port-to-Rust** wrapping `url::Url` + proptest scheme-required invariant. | - -What `proven` does NOT cover (and Layer 1–3 must prove from first principles): -- miniKanren engine (Layer 2.1) -- 49-language analyzer dispatch (PA1 already covers this) -- Hexad/Octad data model (Layer 3.1) -- A2ML attestation chain (Layer 3.2) -- Bridge reachability (Layer 3.3) -- Sweep tracker / mass-panic temporal index (no equivalent) -- Adjudicate / Axial / Ambush / Abduct merge logic (bespoke) - -Skip (semantic mismatch or already-total): -- `SafeJson` — `serde_json::from_str` is already total + typed. -- `SafeRegex` — `regex` crate is already RE2-lineage (linear-time, ReDoS-safe). -- `SafeDateTime` — `chrono::Utc::now().to_rfc3339()` is total on emit. -- `SafeCommand` — `Command::new(&str_args)` doesn't shell-interpolate. -- `SafeEnv` — env keys in panic-attack are compile-time literals. -- `SafeUUID` — semantic mismatch (we use deterministic timestamps for replayability). - -## Sequencing - -Recommended order (each row is parallel-iseable; rows are sequenced): - -| # | Phase | Output | Estimated effort | Risk | -|---|---|---|---|---| -| 1 | **Foundation**: Layer 1.0 (comment/string-strip idempotence + token preservation) | `src/abi/Stripping.idr` + 1 Idris2 module | 3–5 days | low | -| 2 | **Quick wins**: Hexad↔Octad roundtrip proptest + Layer 1 PA001/PA004/PA017 | 200 LoC Rust proptest + 3 Idris2 modules | 1 week | low | -| 3 | **Cross-fit**: SafePath + SafeUrl ports (with proptest against `proven`'s Idris2 reference) | 2 Rust modules + 2 proptest suites | 1 week | low | -| 4 | **Persistence**: Attestation chain (Layer 3.2) | 1 Idris2 module | 1 week | low | -| 5 | **Engine**: miniKanren correctness (Layer 2.1, ~1500 LoC Coq) | `formal/Kanren.v` | 4 weeks | medium (well-trodden, but big) | -| 6 | **Surface**: remaining PA categories (Layer 1.1–1.25 minus quick-wins) | ~22 Idris2 modules | 4 weeks | medium | -| 7 | **Reachability**: bridge soundness (Layer 3.3, Coq graph) | `formal/BridgeReachability.v` | 1.5 weeks | medium | -| 8 | **Taint completeness**: kanren taint flow (Layer 2.2) | extends `formal/Kanren.v` | 3 weeks | high (fixpoint lattice + soundness witness) | -| 9 | **FFI ABI** (Layer 2.3 deferred — needs ABI modelling) | TBD | TBD | high — defer until 1–8 land | - -**Total to row 8**: ~16 calendar weeks of focused proof work for "panic-attack is provably sound to the per-category and per-flow level". After row 8, only the cross-language FFI ABI soundness remains as an aspirational item. - -## What this is NOT - -- **Not** a sweep to add `Admitted` placeholders. Every new Idris2 module must `Qed`-close (or its Coq equivalent) before landing. If a proof is too hard, the obligation stays open and we record it in `PROOF-NEEDS.md` — that's the honest path. -- **Not** a performance regression. proven swap-outs are explicitly evaluated for perf neutrality; the rest of the programme is pure docs/proof artefacts that don't touch the hot path. -- **Not** a 25-PR storm. Group by phase; one PR per phase row above. - -## References - -- `PROOF-NEEDS.md` — current proof-debt ledger (this document is the long-term plan; that one tracks the immediate next step). -- `src/abi/PatternCompleteness.idr` (PA1) -- `src/abi/ClassificationSoundness.idr` (PA2) -- `hyperpolymath/proven` — leaf validator library; cross-fit candidates listed above. -- ROADMAP.adoc "Long-Term" section: "Formal verification of core analysis rules (via proven library)" — this document operationalises that bullet. diff --git a/READINESS.adoc b/READINESS.adoc new file mode 100644 index 0000000..6080ce3 --- /dev/null +++ b/READINESS.adoc @@ -0,0 +1,342 @@ +== panic-attack Component Readiness Assessment + +*Standard:* +https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades[Component +Readiness Grades (CRG) v1.0] *Assessed:* 2026-03-01 *Assessor:* Jonathan +D.A. Jewell + Claude Opus 4.6 + +*Current Grade:* B + +=== Summary + +[width="100%",cols="20%,5%,17%,58%",options="header",] +|=== +|Component |Grade |Release Stage |Evidence Summary +|`+assail+` |B |Beta |Dogfooded on self; 22 findings. Tested on 283+ +repos (diverse: Rust, Elixir, Gleam, Julia, ReScript, Idris2, Zig, +OCaml, Ada, Haskell, 007-lang, Coq, Isabelle) via assemblyline and +estate-wide CI. + +|`+attack+` |D |Alpha |Works on example binary (cpu axis). Other axes +not tested on diverse targets. + +|`+assault+` |D |Alpha |Works on self + example binary. Full multi-axis +only tested on one target. + +|`+ambush+` |D |Alpha |Works with and without timeline. Timeline events +skip when target exits fast (correct behaviour). + +|`+amuck+` |D |Alpha |Generates mutated files. Preset light works. +Dangerous preset and exec-program untested on diverse targets. + +|`+abduct+` |D |Alpha |File isolation + mtime-shift works. Time-skewing +(frozen/slow modes) and exec-program untested on diverse targets. + +|`+adjudicate+` |D |Alpha |Aggregates 2+ reports with expert-system +verdict. Only tested on panic-attack’s own reports. + +|`+axial+` |D |Alpha |Observation with –report works. Exec-program +observation works. grep/agrep/aspell/pandoc untested. + +|`+analyze+` |C |Beta |Detects UseAfterFree, NullPointerDeref from crash +reports. Both rule evaluation and stderr matching work on synthetic +data. + +|`+report+` |C |Beta |Renders assault reports in terminal. Works on +self-generated reports. All view modes available. + +|`+tui+` |E |Pre-alpha |Initialises but requires real terminal. Cannot +be tested in CI/headless. No smoke test possible. + +|`+gui+` |E |Pre-alpha |Initialises but requires display server. Cannot +be tested in CI/headless. + +|`+diff+` |C |Beta |Compares two reports correctly. Shows robustness +delta, weak point delta, per-axis changes. + +|`+manifest+` |C |Beta |Exports AI.a2ml to Nickel format. Works on self. +Output is valid Nickel. + +|`+a2ml-export+` |C |Beta |Round-trips assault report to A2ML bundle. +Works on self-generated reports. + +|`+a2ml-import+` |C |Beta |Round-trips A2ML bundle back to JSON. +Verified round-trip integrity. + +|`+panll+` |C |Beta |Exports event-chain with real constraints. 2 +critical WPs, attack events extracted correctly. + +|`+assemblyline+` |C |Beta |Scanned 141 repos in parallel (rayon). +BLAKE3 fingerprinting. 3448 findings, 254 critical. + +|`+diagnostics+` |C |Beta |Reports version, manifest, directories, +integrations. Works on self. + +|`+help+` |C |Beta |Lists all 19 subcommands with descriptions and +options. +|=== + +=== Overall Project Readiness + +* *Components at B or above:* 1/19 (5%) — `+assail+` elevated 2026-04-04 +* *Components at C (Beta) or above:* 14/19 (74%) +* *Components at D (Alpha):* 5/19 (26%) +* *Components at E (Pre-alpha):* 2/19 (11%) +* *Components at F (Reject):* 0/19 (0%) +* *Minimum project-wide grade:* E (tui, gui) +* *Weighted assessment:* `+assail+` has reached grade B (diverse +external targets confirmed). The project is *Grade B* for its primary +use case (static analysis) and *Alpha-quality* for the full dynamic +testing suite. + +=== Detailed Assessment + +==== `+assail+` — Static Analysis Engine (Grade: B) + +*Evidence:* - Deployed in CI (dogfood-gate / static-analysis-gate) +across 283+ repositories - Assemblyline scan of 141 repos: 3448 total +findings, 254 critical - Language diversity confirmed across external +targets: 1. Elixir/OTP (hypatia, burble, oblibeny) — Phoenix, GenServer, +Ecto patterns 2. Rust systems code (iseriser, conflow, a2ml-rs, +panic-attack itself) — unsafe, FFI, unwrap 3. Gleam/BEAM (k9_gleam, +a2ml_gleam) — typed BEAM target 4. Idris2/formal-verified (ephapax, +stapeln) — dependent type code 5. Julia scientific (7-tentacles, +statistease, developer-ecosystem) — REPL scripting 6. ReScript/Deno +(idaptik, nafa-app, vscode-k9) — web frontend code 7. Coq proof scripts +(ephapax/formal) — academic/proof code 8. Ada/SPARK (safety-critical +components) — safety-critical language 9. OCaml (affinescript compiler) +— functional language 10. Haskell (a2ml-haskell) — pure functional - +Issues fed back: framework detection false positives reported and +documented - All 49 language analyzers validated against at least one +real-world repo + +*Known limitations:* - Framework detection has false positives (reports +Phoenix/Ecto/OTP on pure Rust) - Some patterns detect their own search +strings (e.g., "`transmute`" in analyzer.rs) - Sequential scan on very +large repos can be slow (Chapel metalayer planned) + +*Promotion path to A:* External users outside hyperpolymath confirm +value and report no harm. + +==== `+attack+` — Single Axis Stress Test (Grade: D) + +*Evidence:* - CPU axis works on example binary (exits cleanly, 0 +crashes) - Report output is structured and correct + +*Known limitations:* - Only tested on one binary with one axis - +Memory/disk/network/concurrency/time axes not individually validated - +No test against a program that actually crashes under stress + +*Promotion path to C:* Test all 6 axes on panic-attack’s own test +binaries and the vulnerable_program example. + +==== `+assault+` — Combined Static + Dynamic (Grade: D) + +*Evidence:* - Combines assail + attack successfully - Produces +structured AssaultReport with all sections - VerisimDB hexad storage +works automatically - Multi-format output (JSON, YAML, Nickel) works + +*Known limitations:* - Only tested with cpu axis (full multi-axis on +self not validated in this session) - Previous session ran full +multi-axis; results were valid but only on one target + +*Promotion path to C:* Run full multi-axis assault on panic-attack’s own +binary. + +==== `+ambush+` — Ambient Stress with Timeline (Grade: D) + +*Evidence:* - Works without timeline (falls back to standard attack +flow) - Timeline YAML parsing works correctly (4 events across 3 tracks) +- Timeline events are correctly scheduled with start offsets - Events +are correctly skipped when target exits before their start time + +*Known limitations:* - Timeline events only tested once; stressor +threads for cpu/memory/concurrency verified but only in isolation - No +test with a long-running program that exercises the full timeline +duration + +*Promotion path to C:* Create a test binary that runs for 15+ seconds, +run with the timeline spec, verify all events fire in sequence. + +==== `+amuck+` — File Mutation Testing (Grade: D) + +*Evidence:* - Light preset generates 1 mutated variant with +prepend/append operations - Output file written to runtime/amuck/ - JSON +report correctly records operations applied + +*Known limitations:* - Dangerous preset not tested - Custom spec file +not tested - exec-program integration not tested (compile and test +mutated files) + +*Promotion path to C:* Test dangerous preset, write a custom spec, and +use exec-program to compile and test mutated variants of our own source +files. + +==== `+abduct+` — File Isolation & Time-Skewing (Grade: D) + +*Evidence:* - Direct scope copies target + dependencies correctly - +mtime-offset-days shifts file timestamps - Readonly lock is applied to +copied files - Workspace created in runtime/abduct/ + +*Known limitations:* - frozen/slow time modes not tested - virtual-now +not tested - exec-program integration not tested - twohops/directory +scope not tested + +*Promotion path to C:* Test frozen time mode with exec-program on a +binary that checks timestamps. + +==== `+adjudicate+` — Report Aggregation (Grade: D) + +*Evidence:* - Processes 2 assault reports correctly - Expert-system +verdict ("`fail`" based on critical weak points) is generated - Rule +hits documented with confidence scores - Priorities extracted correctly + +*Known limitations:* - Only tested with assault reports; amuck/abduct +report aggregation untested - Only 2 reports aggregated; scaling +untested - Only one campaign pattern exercised +(campaign_fail_on_high_signal) + +*Promotion path to C:* Test with all 3 report types (assault, amuck, +abduct) and with 5+ reports. + +==== `+axial+` — Target Reaction Observation (Grade: D) + +*Evidence:* - Report observation mode works (reads assault JSON, +produces markdown) - Exec-program mode works (runs binary, captures +output) - Markdown output is well-formatted + +*Known limitations:* - grep/agrep pattern matching not tested - aspell +integration not tested - pandoc conversion not tested - i18n +(non-English output) not tested via this subcommand + +*Promotion path to C:* Test grep patterns on stderr of a crashing +program, test aspell on output text. + +==== `+analyze+` — Crash Report Analysis (Grade: C) + +*Evidence:* - Detects UseAfterFree from both rule evaluation +(Alloc→Free→Use sequence) and stderr patterns - Detects NullPointerDeref +from SIGSEGV in signal field - Confidence scores differentiated (0.85 +rule-based, 0.95 stderr-based) - Variable bindings reported in evidence +(X_loc, X_loc2, X = heap_var) + +*Known limitations:* - Only synthetic crash reports tested (no real +crash from running code) - Deadlock, DataRace, MemoryLeak, +BufferOverflow rules not exercised + +*Promotion path to B:* Feed in real crash reports from at least 6 +different crash scenarios (use ASAN/TSAN output from real C/Rust +programs). + +==== `+report+` — Report Rendering (Grade: C) + +*Evidence:* - Renders full assault report in terminal with sections: +assail, detail panel, attack results, signatures, assessment - All view +modes available via –report-view flag + +*Promotion path to B:* Test rendering of reports from 6+ diverse +projects. + +==== `+tui+` — Terminal UI (Grade: E) + +*Evidence:* - Code exists and compiles - Attempts to initialize +crossterm terminal but fails without a real TTY (os error 6) - Cannot be +smoke-tested in a headless/CI environment + +*Promotion path to D:* Add a –dry-run flag or test harness that +validates the report loading without needing a terminal. + +==== `+gui+` — Graphical UI (Grade: E) + +*Evidence:* - Code exists and compiles - Times out (no display server in +CLI context) - eframe-based; requires Wayland/X11 + +*Promotion path to D:* Same as TUI — add headless validation mode. + +==== `+diff+` — Report Comparison (Grade: C) + +*Evidence:* - Correctly compares two reports: robustness delta, weak +point delta, per-axis status changes - Framework changes tracked - +Severity breakdown tracked (critical, high, medium, low) + +*Promotion path to B:* Compare reports from 6+ diverse projects at +different points in time. + +==== `+manifest+` — AI Manifest Export (Grade: C) + +*Evidence:* - Parses AI.a2ml and exports to Nickel format - Output +includes all manifest sections: version, project, canonical-locations, +critical-invariants, lifecycle, tools, reports + +*Promotion path to B:* Test on AI.a2ml files from 6+ different repos. + +==== `+a2ml-export+` / `+a2ml-import+` (Grade: C each) + +*Evidence:* - Round-trip verified: assault JSON → A2ML bundle → JSON - +Output file sizes match (3371 lines round-tripped) - Kind discrimination +works (–kind assault) + +*Promotion path to B:* Test with all report kinds (assault, amuck, +abduct) from 6+ projects. + +==== `+panll+` — PanLL Event-Chain Export (Grade: C) + +*Evidence:* - Exports event chain from assault report - 2 constraints +extracted from critical weak points - Attack events correctly +represented - Summary includes weak points, crashes, robustness score + +*Promotion path to B:* Test with reports from 6+ projects with varying +numbers of findings. + +==== `+assemblyline+` — Batch Repo Scanning (Grade: C) + +*Evidence:* - Scanned 141 repos in parallel via rayon - 3448 weak points +found, 254 critical - BLAKE3 fingerprinting computed for all repos - +Results sorted by risk (developer-ecosystem: 633, idaptik: 427, …) - +Filters (–findings-only, –min-findings) work correctly + +*Promotion path to B:* Run on 6+ different parent directories (different +machines, different repo structures). + +==== `+diagnostics+` — Self-Diagnostics (Grade: C) + +*Evidence:* - Reports version, AI manifest status, directory existence, +report cache counts - Correctly identifies missing integration configs +(Hypatia, gitbot-fleet) + +*Promotion path to B:* Validate diagnostics output on 6+ repos with +different configurations. + +==== `+help+` — Help Text (Grade: C) + +*Evidence:* - Lists all 19 subcommands with accurate descriptions - +Shows all global options - Per-subcommand help available + +*Promotion path to B:* Help is generic by nature; B/A grades apply once +external users confirm the docs are clear. + +=== F-Grade Analysis + +No components earned an F. Candidates considered and rejected: + +* *tui/gui*: These are E, not F. They serve a real purpose (interactive +report review) and are salvageable with a dry-run mode. No better +alternative exists specifically for panic-attack reports. +* *axial*: Some features (aspell, pandoc) could be delegated to external +tools, but the integrated observation + report correlation is unique to +panic-attack. Not an F. + +=== Concerns and Maintenance Notes + +[arabic] +. *Framework detection false positives*: assail detects Elixir/Erlang +frameworks (Phoenix, Ecto, OTP) on a pure Rust project. This should be +gated on detected language. +. *Self-detection*: The tool detects its own pattern-matching strings as +vulnerabilities. Consider adding self-exclusion or annotation support. +. *Timeline event scheduling*: The DAW-style timeline works but needs a +long-running test target to exercise fully. +. *amuck dangerous preset*: Untested. Could generate broken mutations +that confuse users. +. *abduct time modes*: frozen/slow modes are implemented but completely +untested. diff --git a/READINESS.md b/READINESS.md deleted file mode 100644 index 1dab617..0000000 --- a/READINESS.md +++ /dev/null @@ -1,294 +0,0 @@ - - - - -# panic-attack Component Readiness Assessment - -**Standard:** [Component Readiness Grades (CRG) v1.0](https://github.com/hyperpolymath/standards/tree/main/component-readiness-grades) -**Assessed:** 2026-03-01 -**Assessor:** Jonathan D.A. Jewell + Claude Opus 4.6 - -**Current Grade:** B - -## Summary - -| Component | Grade | Release Stage | Evidence Summary | -|---------------------|-------|--------------------|---------------------------------------------------------------------| -| `assail` | B | Beta | Dogfooded on self; 22 findings. Tested on 283+ repos (diverse: Rust, Elixir, Gleam, Julia, ReScript, Idris2, Zig, OCaml, Ada, Haskell, 007-lang, Coq, Isabelle) via assemblyline and estate-wide CI. | -| `attack` | D | Alpha | Works on example binary (cpu axis). Other axes not tested on diverse targets. | -| `assault` | D | Alpha | Works on self + example binary. Full multi-axis only tested on one target. | -| `ambush` | D | Alpha | Works with and without timeline. Timeline events skip when target exits fast (correct behaviour). | -| `amuck` | D | Alpha | Generates mutated files. Preset light works. Dangerous preset and exec-program untested on diverse targets. | -| `abduct` | D | Alpha | File isolation + mtime-shift works. Time-skewing (frozen/slow modes) and exec-program untested on diverse targets. | -| `adjudicate` | D | Alpha | Aggregates 2+ reports with expert-system verdict. Only tested on panic-attack's own reports. | -| `axial` | D | Alpha | Observation with --report works. Exec-program observation works. grep/agrep/aspell/pandoc untested. | -| `analyze` | C | Beta | Detects UseAfterFree, NullPointerDeref from crash reports. Both rule evaluation and stderr matching work on synthetic data. | -| `report` | C | Beta | Renders assault reports in terminal. Works on self-generated reports. All view modes available. | -| `tui` | E | Pre-alpha | Initialises but requires real terminal. Cannot be tested in CI/headless. No smoke test possible. | -| `gui` | E | Pre-alpha | Initialises but requires display server. Cannot be tested in CI/headless. | -| `diff` | C | Beta | Compares two reports correctly. Shows robustness delta, weak point delta, per-axis changes. | -| `manifest` | C | Beta | Exports AI.a2ml to Nickel format. Works on self. Output is valid Nickel. | -| `a2ml-export` | C | Beta | Round-trips assault report to A2ML bundle. Works on self-generated reports. | -| `a2ml-import` | C | Beta | Round-trips A2ML bundle back to JSON. Verified round-trip integrity. | -| `panll` | C | Beta | Exports event-chain with real constraints. 2 critical WPs, attack events extracted correctly. | -| `assemblyline` | C | Beta | Scanned 141 repos in parallel (rayon). BLAKE3 fingerprinting. 3448 findings, 254 critical. | -| `diagnostics` | C | Beta | Reports version, manifest, directories, integrations. Works on self. | -| `help` | C | Beta | Lists all 19 subcommands with descriptions and options. | - -## Overall Project Readiness - -- **Components at B or above:** 1/19 (5%) — `assail` elevated 2026-04-04 -- **Components at C (Beta) or above:** 14/19 (74%) -- **Components at D (Alpha):** 5/19 (26%) -- **Components at E (Pre-alpha):** 2/19 (11%) -- **Components at F (Reject):** 0/19 (0%) -- **Minimum project-wide grade:** E (tui, gui) -- **Weighted assessment:** `assail` has reached grade B (diverse external targets confirmed). The project is **Grade B** for its primary use case (static analysis) and **Alpha-quality** for the full dynamic testing suite. - -## Detailed Assessment - -### `assail` — Static Analysis Engine (Grade: B) - -**Evidence:** -- Deployed in CI (dogfood-gate / static-analysis-gate) across 283+ repositories -- Assemblyline scan of 141 repos: 3448 total findings, 254 critical -- Language diversity confirmed across external targets: - 1. Elixir/OTP (hypatia, burble, oblibeny) — Phoenix, GenServer, Ecto patterns - 2. Rust systems code (iseriser, conflow, a2ml-rs, panic-attack itself) — unsafe, FFI, unwrap - 3. Gleam/BEAM (k9_gleam, a2ml_gleam) — typed BEAM target - 4. Idris2/formal-verified (ephapax, stapeln) — dependent type code - 5. Julia scientific (7-tentacles, statistease, developer-ecosystem) — REPL scripting - 6. ReScript/Deno (idaptik, nafa-app, vscode-k9) — web frontend code - 7. Coq proof scripts (ephapax/formal) — academic/proof code - 8. Ada/SPARK (safety-critical components) — safety-critical language - 9. OCaml (affinescript compiler) — functional language - 10. Haskell (a2ml-haskell) — pure functional -- Issues fed back: framework detection false positives reported and documented -- All 49 language analyzers validated against at least one real-world repo - -**Known limitations:** -- Framework detection has false positives (reports Phoenix/Ecto/OTP on pure Rust) -- Some patterns detect their own search strings (e.g., "transmute" in analyzer.rs) -- Sequential scan on very large repos can be slow (Chapel metalayer planned) - -**Promotion path to A:** External users outside hyperpolymath confirm value and report no harm. - -### `attack` — Single Axis Stress Test (Grade: D) - -**Evidence:** -- CPU axis works on example binary (exits cleanly, 0 crashes) -- Report output is structured and correct - -**Known limitations:** -- Only tested on one binary with one axis -- Memory/disk/network/concurrency/time axes not individually validated -- No test against a program that actually crashes under stress - -**Promotion path to C:** Test all 6 axes on panic-attack's own test binaries and the vulnerable_program example. - -### `assault` — Combined Static + Dynamic (Grade: D) - -**Evidence:** -- Combines assail + attack successfully -- Produces structured AssaultReport with all sections -- VerisimDB hexad storage works automatically -- Multi-format output (JSON, YAML, Nickel) works - -**Known limitations:** -- Only tested with cpu axis (full multi-axis on self not validated in this session) -- Previous session ran full multi-axis; results were valid but only on one target - -**Promotion path to C:** Run full multi-axis assault on panic-attack's own binary. - -### `ambush` — Ambient Stress with Timeline (Grade: D) - -**Evidence:** -- Works without timeline (falls back to standard attack flow) -- Timeline YAML parsing works correctly (4 events across 3 tracks) -- Timeline events are correctly scheduled with start offsets -- Events are correctly skipped when target exits before their start time - -**Known limitations:** -- Timeline events only tested once; stressor threads for cpu/memory/concurrency verified but only in isolation -- No test with a long-running program that exercises the full timeline duration - -**Promotion path to C:** Create a test binary that runs for 15+ seconds, run with the timeline spec, verify all events fire in sequence. - -### `amuck` — File Mutation Testing (Grade: D) - -**Evidence:** -- Light preset generates 1 mutated variant with prepend/append operations -- Output file written to runtime/amuck/ -- JSON report correctly records operations applied - -**Known limitations:** -- Dangerous preset not tested -- Custom spec file not tested -- exec-program integration not tested (compile and test mutated files) - -**Promotion path to C:** Test dangerous preset, write a custom spec, and use exec-program to compile and test mutated variants of our own source files. - -### `abduct` — File Isolation & Time-Skewing (Grade: D) - -**Evidence:** -- Direct scope copies target + dependencies correctly -- mtime-offset-days shifts file timestamps -- Readonly lock is applied to copied files -- Workspace created in runtime/abduct/ - -**Known limitations:** -- frozen/slow time modes not tested -- virtual-now not tested -- exec-program integration not tested -- twohops/directory scope not tested - -**Promotion path to C:** Test frozen time mode with exec-program on a binary that checks timestamps. - -### `adjudicate` — Report Aggregation (Grade: D) - -**Evidence:** -- Processes 2 assault reports correctly -- Expert-system verdict ("fail" based on critical weak points) is generated -- Rule hits documented with confidence scores -- Priorities extracted correctly - -**Known limitations:** -- Only tested with assault reports; amuck/abduct report aggregation untested -- Only 2 reports aggregated; scaling untested -- Only one campaign pattern exercised (campaign_fail_on_high_signal) - -**Promotion path to C:** Test with all 3 report types (assault, amuck, abduct) and with 5+ reports. - -### `axial` — Target Reaction Observation (Grade: D) - -**Evidence:** -- Report observation mode works (reads assault JSON, produces markdown) -- Exec-program mode works (runs binary, captures output) -- Markdown output is well-formatted - -**Known limitations:** -- grep/agrep pattern matching not tested -- aspell integration not tested -- pandoc conversion not tested -- i18n (non-English output) not tested via this subcommand - -**Promotion path to C:** Test grep patterns on stderr of a crashing program, test aspell on output text. - -### `analyze` — Crash Report Analysis (Grade: C) - -**Evidence:** -- Detects UseAfterFree from both rule evaluation (Alloc→Free→Use sequence) and stderr patterns -- Detects NullPointerDeref from SIGSEGV in signal field -- Confidence scores differentiated (0.85 rule-based, 0.95 stderr-based) -- Variable bindings reported in evidence (X_loc, X_loc2, X = heap_var) - -**Known limitations:** -- Only synthetic crash reports tested (no real crash from running code) -- Deadlock, DataRace, MemoryLeak, BufferOverflow rules not exercised - -**Promotion path to B:** Feed in real crash reports from at least 6 different crash scenarios (use ASAN/TSAN output from real C/Rust programs). - -### `report` — Report Rendering (Grade: C) - -**Evidence:** -- Renders full assault report in terminal with sections: assail, detail panel, attack results, signatures, assessment -- All view modes available via --report-view flag - -**Promotion path to B:** Test rendering of reports from 6+ diverse projects. - -### `tui` — Terminal UI (Grade: E) - -**Evidence:** -- Code exists and compiles -- Attempts to initialize crossterm terminal but fails without a real TTY (os error 6) -- Cannot be smoke-tested in a headless/CI environment - -**Promotion path to D:** Add a --dry-run flag or test harness that validates the report loading without needing a terminal. - -### `gui` — Graphical UI (Grade: E) - -**Evidence:** -- Code exists and compiles -- Times out (no display server in CLI context) -- eframe-based; requires Wayland/X11 - -**Promotion path to D:** Same as TUI — add headless validation mode. - -### `diff` — Report Comparison (Grade: C) - -**Evidence:** -- Correctly compares two reports: robustness delta, weak point delta, per-axis status changes -- Framework changes tracked -- Severity breakdown tracked (critical, high, medium, low) - -**Promotion path to B:** Compare reports from 6+ diverse projects at different points in time. - -### `manifest` — AI Manifest Export (Grade: C) - -**Evidence:** -- Parses AI.a2ml and exports to Nickel format -- Output includes all manifest sections: version, project, canonical-locations, critical-invariants, lifecycle, tools, reports - -**Promotion path to B:** Test on AI.a2ml files from 6+ different repos. - -### `a2ml-export` / `a2ml-import` (Grade: C each) - -**Evidence:** -- Round-trip verified: assault JSON → A2ML bundle → JSON -- Output file sizes match (3371 lines round-tripped) -- Kind discrimination works (--kind assault) - -**Promotion path to B:** Test with all report kinds (assault, amuck, abduct) from 6+ projects. - -### `panll` — PanLL Event-Chain Export (Grade: C) - -**Evidence:** -- Exports event chain from assault report -- 2 constraints extracted from critical weak points -- Attack events correctly represented -- Summary includes weak points, crashes, robustness score - -**Promotion path to B:** Test with reports from 6+ projects with varying numbers of findings. - -### `assemblyline` — Batch Repo Scanning (Grade: C) - -**Evidence:** -- Scanned 141 repos in parallel via rayon -- 3448 weak points found, 254 critical -- BLAKE3 fingerprinting computed for all repos -- Results sorted by risk (developer-ecosystem: 633, idaptik: 427, ...) -- Filters (--findings-only, --min-findings) work correctly - -**Promotion path to B:** Run on 6+ different parent directories (different machines, different repo structures). - -### `diagnostics` — Self-Diagnostics (Grade: C) - -**Evidence:** -- Reports version, AI manifest status, directory existence, report cache counts -- Correctly identifies missing integration configs (Hypatia, gitbot-fleet) - -**Promotion path to B:** Validate diagnostics output on 6+ repos with different configurations. - -### `help` — Help Text (Grade: C) - -**Evidence:** -- Lists all 19 subcommands with accurate descriptions -- Shows all global options -- Per-subcommand help available - -**Promotion path to B:** Help is generic by nature; B/A grades apply once external users confirm the docs are clear. - -## F-Grade Analysis - -No components earned an F. Candidates considered and rejected: - -- **tui/gui**: These are E, not F. They serve a real purpose (interactive report review) and are salvageable with a dry-run mode. No better alternative exists specifically for panic-attack reports. -- **axial**: Some features (aspell, pandoc) could be delegated to external tools, but the integrated observation + report correlation is unique to panic-attack. Not an F. - -## Concerns and Maintenance Notes - -1. **Framework detection false positives**: assail detects Elixir/Erlang frameworks (Phoenix, Ecto, OTP) on a pure Rust project. This should be gated on detected language. -2. **Self-detection**: The tool detects its own pattern-matching strings as vulnerabilities. Consider adding self-exclusion or annotation support. -3. **Timeline event scheduling**: The DAW-style timeline works but needs a long-running test target to exercise fully. -4. **amuck dangerous preset**: Untested. Could generate broken mutations that confuse users. -5. **abduct time modes**: frozen/slow modes are implemented but completely untested. diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..19b8978 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,87 @@ +== Security Policy + +=== Supported Versions + +We release patches for security vulnerabilities for the following +versions: + +[cols=",",options="header",] +|=== +|Version |Supported +|2.5.x |:white_check_mark: +|< 2.5 |:x: +|=== + +=== Reporting a Vulnerability + +*Please do not report security vulnerabilities through public GitHub +issues.* + +Instead, please report them via email to: + +*j.d.a.jewell@open.ac.uk* + +You should receive a response within 48 hours. If for some reason you do +not, please follow up via email to ensure we received your original +message. + +Please include the following information: + +* Type of issue (e.g. buffer overflow, SQL injection, cross-site +scripting, etc.) +* Full paths of source file(s) related to the manifestation of the issue +* The location of the affected source code (tag/branch/commit or direct +URL) +* Any special configuration required to reproduce the issue +* Step-by-step instructions to reproduce the issue +* Proof-of-concept or exploit code (if possible) +* Impact of the issue, including how an attacker might exploit it + +This information will help us triage your report more quickly. + +=== Preferred Languages + +We prefer all communications to be in English. + +=== Policy + +We follow the principle of +https://vuls.cert.org/confluence/display/CVD/Executive+Summary[Coordinated +Vulnerability Disclosure]. + +=== Security Measures + +panic-attack implements several security measures: + +[arabic] +. *No unsafe code* in the core library (only in specific +performance-critical sections with documented justification) +. *Dependency auditing* via cargo-audit in CI +. *OpenSSF Scorecard* for supply chain security +. *CodeQL analysis* for vulnerability detection +. *Secret scanning* with TruffleHog +. *SBOM generation* for dependency transparency + +=== Self-Testing + +panic-attack is tested against itself ("`eating our own dogfood`") to +verify its own robustness and identify potential security issues in its +implementation. + +=== Security Advisories + +Security advisories will be published via: - GitHub Security Advisories +- The CHANGELOG.md file - Release notes for security-related releases + +=== Attribution + +We appreciate responsible disclosure and will acknowledge security +researchers in our release notes and CHANGELOG (unless you prefer to +remain anonymous). + +=== Learn More + +For more information about security in the hyperpolymath ecosystem: - +RSR Security Standards: +https://github.com/hyperpolymath/rsr-template-repo - Hypatia Security +Analysis: https://github.com/hyperpolymath/hypatia diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 0ba8abf..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,74 +0,0 @@ - - -# Security Policy - -## Supported Versions - -We release patches for security vulnerabilities for the following versions: - -| Version | Supported | -| ------- | ------------------ | -| 2.5.x | :white_check_mark: | -| < 2.5 | :x: | - -## Reporting a Vulnerability - -**Please do not report security vulnerabilities through public GitHub issues.** - -Instead, please report them via email to: - -**j.d.a.jewell@open.ac.uk** - -You should receive a response within 48 hours. If for some reason you do not, please follow up via email to ensure we received your original message. - -Please include the following information: - -- Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) -- Full paths of source file(s) related to the manifestation of the issue -- The location of the affected source code (tag/branch/commit or direct URL) -- Any special configuration required to reproduce the issue -- Step-by-step instructions to reproduce the issue -- Proof-of-concept or exploit code (if possible) -- Impact of the issue, including how an attacker might exploit it - -This information will help us triage your report more quickly. - -## Preferred Languages - -We prefer all communications to be in English. - -## Policy - -We follow the principle of [Coordinated Vulnerability Disclosure](https://vuls.cert.org/confluence/display/CVD/Executive+Summary). - -## Security Measures - -panic-attack implements several security measures: - -1. **No unsafe code** in the core library (only in specific performance-critical sections with documented justification) -2. **Dependency auditing** via cargo-audit in CI -3. **OpenSSF Scorecard** for supply chain security -4. **CodeQL analysis** for vulnerability detection -5. **Secret scanning** with TruffleHog -6. **SBOM generation** for dependency transparency - -## Self-Testing - -panic-attack is tested against itself ("eating our own dogfood") to verify its own robustness and identify potential security issues in its implementation. - -## Security Advisories - -Security advisories will be published via: -- GitHub Security Advisories -- The CHANGELOG.md file -- Release notes for security-related releases - -## Attribution - -We appreciate responsible disclosure and will acknowledge security researchers in our release notes and CHANGELOG (unless you prefer to remain anonymous). - -## Learn More - -For more information about security in the hyperpolymath ecosystem: -- RSR Security Standards: https://github.com/hyperpolymath/rsr-template-repo -- Hypatia Security Analysis: https://github.com/hyperpolymath/hypatia diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..b520a26 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,221 @@ +== TEST-NEEDS.md — panic-attack + +=== CRG Grade: B — ACHIEVED 2026-04-04 + +____ +Updated 2026-04-04 by CRG C blitz. CRG B achieved 2026-04-04: Ran +`+panic-attack assail+` on 6 diverse external repos with real output. +____ + +=== CRG B Evidence — External Targets + +[width="99%",cols="29%,20%,35%,16%",options="header",] +|=== +|Target Repo |Language |What Was Tested |Result +|gossamer |Gleam/Rust/Idris2 |`+assail+` static analysis on src/ |23 +weak points, Language=Idris, Attacks=[Concurrency,Disk,Memory,Cpu] + +|protocol-squisher |Rust (shape-ir crate) |`+assail+` static analysis on +crates/shape-ir/src |5 weak points, Language=Rust, +Attacks=[Memory,Disk,Cpu] + +|burble |Elixir/ReScript/Idris2 |`+assail+` static analysis on src/ |2 +weak points, Language=Idris, Attacks=[Memory,Cpu] + +|stapeln |Idris2/Zig |`+assail+` static analysis on ffi/zig/src |0 weak +points, Language=Zig, Attacks=[Cpu] + +|boj-server |ReScript/Deno/Idris2 |`+assail+` static analysis on src/ |5 +weak points, Language=Idris, Attacks=[Cpu,Memory] + +|standards |Rust (k9-svc LSP) |`+assail+` static analysis on +k9-svc/lsp/src |1 weak point, Language=Rust, Attacks=[Disk,Cpu,Memory] +|=== + +==== Target Details + +*1. gossamer (Gleam/Rust/Idris2 — window manager)* - Command: +`+panic-attack assail /var/mnt/eclipse/repos/gossamer/src+` - Key +findings: 23 weak points detected in Idris2 ABI layer. Recommended +attack axes: Concurrency, Disk, Memory, Cpu. Highest weak point density +in formal verification files. + +*2. protocol-squisher (Rust — shape-ir crate)* - Command: +`+panic-attack assail /var/mnt/eclipse/repos/protocol-squisher/crates/shape-ir/src+` +- Key findings: 5 weak points in core shape IR library. Memory and Disk +attack axes recommended. Clean crate with minimal attack surface. + +*3. burble (Elixir/ReScript/Idris2 — WebRTC comms)* - Command: +`+panic-attack assail /var/mnt/eclipse/repos/developer-ecosystem/burble/src+` +- Key findings: 2 weak points detected. Minimal attack surface in the +Idris2 ABI layer. Memory and Cpu axes only. + +*4. stapeln (Idris2/Zig — container orchestration)* - Command: +`+panic-attack assail /var/mnt/eclipse/repos/fleet-ecosystem/stapeln/ffi/zig/src+` +- Key findings: Zero weak points in Zig FFI layer. Only Cpu axis +recommended. Demonstrates Zig’s safety properties. + +*5. boj-server (ReScript/Deno/Idris2 — MCP server)* - Command: +`+panic-attack assail /var/mnt/eclipse/repos/boj-server/src+` - Key +findings: 5 weak points in Idris2 ABI layer (SafeHTTP, SafeCORS, etc.). +Cpu and Memory axes recommended. + +*6. standards (Rust — k9-svc LSP)* - Command: +`+panic-attack assail /var/mnt/eclipse/repos/developer-ecosystem/standards/k9-svc/lsp/src+` +- Key findings: 1 weak point in LSP server. Disk, Cpu, Memory axes +recommended. Very clean codebase. + +=== Current State + +[width="100%",cols="50%,25%,25%",options="header",] +|=== +|Category |Count |Notes +|Unit tests |116 |Inline `+#[test]+` across 62 modules: strategies(3), +engine(9), rules(3), taint(2), crosslang(3), strategy(4), core(15), +storage(2), a2ml(9), timeline(15), attestation(11), mass_panic(9), +notify(7), signatures(8), plus others + +|P2P (Property-Based) |14 |NEW: tests/property_tests.rs — invariant +verification, kanren correctness, weak point consistency + +|E2E |12 |NEW: tests/e2e_tests.rs — self-scan dogfooding, vulnerable +examples, full pipeline, serialization, determinism + +|Aspect (Error/Perf/Security) |18 |NEW: tests/aspect_tests.rs — +malformed code, deeply nested, long lines, mixed encodings, scaling, +evasion resilience + +|Integration |3 |tests/integration.rs — assail on vulnerable_program, +no-duplicates, per-file stats + +|Benchmarks |7 |benches/scan_bench.rs — language detect, family +classify, self-scan, taint analysis, rule eval, location extract, stats +calc +|=== + +*Total test count:* 116 (lib) + 14 (P2P) + 12 (E2E) + 18 (Aspect) + 3 +(Integration) + 12 (Pattern) + 22 (Readiness) + 10 (Types) + 8 +(Regression) + 11 (Report) + 7 (Panll) + 6 (Assemblyline) + 16 (SARIF) = +*202+ tests passing* + +*Fake fuzz alert resolved:* Removed `+tests/fuzz/placeholder.txt+` +(scorecard placeholder). + +=== Completed (v2.0 → CRG C) + +==== P2P (Property-Based) Tests ✓ + +* [x] Language detection: idempotent, all languages have valid families +* [x] Weak point location validity: must be present or explicitly None +* [x] Pattern matching: no false positives on comments, proper detection +of actual code constructs +* [x] Report statistics: consistency (metrics don’t exceed total lines) +* [x] Kanren logic engine: unification symmetry, forward chaining +preservation, fact DB integrity +* [x] Error recovery: empty input, long file names, Unicode content + +==== E2E Tests ✓ + +* [x] *Self-scan (dogfooding)*: Scan panic-attack’s own source code — +detects issues, all weak points have locations +* [x] Full analysis pipeline: File → Language detection → Rules → Report +generation +* [x] Vulnerable examples: Scan examples/vulnerable_program.rs, +examples/attack_harness.rs +* [x] Report serialization: JSON and YAML output validation +* [x] Deterministic analysis: Same input produces same output +* [x] Directory vs file consistency: Aggregate reports match component +scans +* [x] Multi-language: Python file scanning (if fixtures exist) + +==== Aspect Tests ✓ + +* *Error Handling:* +** [x] Malformed Rust code (unclosed braces) +** [x] Deeply nested code (100 levels) — no stack overflow +** [x] Very long lines (10K+ chars) — no regex engine DoS +** [x] Mixed line endings (LF/CRLF/CR) +** [x] NUL bytes in source files +** [x] UTF-8 BOM handling +** [x] Empty files and whitespace-only files +** [x] Permission denied files (Unix) +** [x] Binary files in scan path (skipped correctly) +* *Performance Scaling:* +** [x] File count scaling: 1 → 5 → 10 files, times remain reasonable +(<5s for 10 small files) +** [x] Memory bounded: Large files (1000+ lines) analyzed without +excessive allocation +** [x] Parallel analysis: rayon-based concurrent scanning is thread-safe +* *Security Evasion (Critical for security tools):* +** [x] Comment evasion: `+// unwrap()+` in comments not flagged as code +** [x] String evasion: Code in strings (eval, base64 etc.) not executed, +patterns still detected +** [x] Encoding evasion resilience: Base64-encoded patterns don’t bypass +actual code detection + +==== Benchmarks (Enhanced) ✓ + +* [x] Language detection speed: 18 file extensions +* [x] Language family classification: 12 languages +* [x] Self-scan: panic-attack source analysis (dogfooding) +* [x] Taint analysis: TaintAnalyzer sources iteration +* [x] Rule evaluation: 4 languages in sequence +* [x] Location extraction: 100 weak points +* [x] Statistics calculation: Field access throughput + +=== Test Results Summary + +.... +cargo test --lib --tests + Unit tests (lib): 116 passed + Property tests: 14 passed + E2E tests: 12 passed + Aspect tests: 18 passed + Integration: 3 passed + Pattern tests: 12 passed + Readiness: 22 passed (CRG D+C+B verification) + Types: 10 passed + Regression: 8 passed + Report: 11 passed + PanLL: 7 passed + Assemblyline: 6 passed + SARIF: 16 passed + +TOTAL: ~170+ tests, ALL PASSING +.... + +=== Coverage Achieved + +* *Unit*: 116 inline tests covering 62 modules +* *P2P*: 14 property-based invariant tests +* *E2E*: 12 end-to-end pipeline tests (including self-scan) +* *Aspect*: 18 cross-cutting concern tests (error, perf, security, +evasion) +* *Benchmarks*: 7 criterion benchmarks baselined +* *Integration*: 3 integration tests + +=== CRG C Checklist + +* [x] *Unit tests*: ✓ (116 existing) +* [x] *Smoke tests*: ✓ (E2E self-scan + vulnerable examples) +* [x] *Build*: ✓ (`+cargo build --release+` 0 warnings) +* [x] *P2P*: ✓ (14 property tests) +* [x] *E2E*: ✓ (12 full-pipeline tests) +* [x] *Reflexive*: ✓ (Self-scan dogfooding) +* [x] *Contract*: ✓ (Report serialization contracts verified) +* [x] *Aspect*: ✓ (18 error/perf/security tests) +* [x] *Benchmarks*: ✓ (7 criterion benchmarks, baselines established) + +=== Notes + +* *Fake fuzz removed*: `+tests/fuzz/placeholder.txt+` was inherited from +template, contained no real fuzz logic +* *Proptest added*: v1.4 dev-dependency for future advanced property +testing +* *Self-scan is highest value*: E2E test that verifies tool works on +real codebase (itself) +* *Security tests critical*: Verified that comment/string/encoding +evasion attempts don’t bypass detection +* *All tests passing*: `+cargo test+` + `+cargo bench --no-run+` both +succeed +* *Zero compiler warnings* in release builds maintained diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index d77fd79..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,161 +0,0 @@ - - -# TEST-NEEDS.md — panic-attack - -## CRG Grade: B — ACHIEVED 2026-04-04 - -> Updated 2026-04-04 by CRG C blitz. -> CRG B achieved 2026-04-04: Ran `panic-attack assail` on 6 diverse external repos with real output. - -## CRG B Evidence — External Targets - -| Target Repo | Language | What Was Tested | Result | -|-------------|----------|-----------------|--------| -| gossamer | Gleam/Rust/Idris2 | `assail` static analysis on src/ | 23 weak points, Language=Idris, Attacks=[Concurrency,Disk,Memory,Cpu] | -| protocol-squisher | Rust (shape-ir crate) | `assail` static analysis on crates/shape-ir/src | 5 weak points, Language=Rust, Attacks=[Memory,Disk,Cpu] | -| burble | Elixir/ReScript/Idris2 | `assail` static analysis on src/ | 2 weak points, Language=Idris, Attacks=[Memory,Cpu] | -| stapeln | Idris2/Zig | `assail` static analysis on ffi/zig/src | 0 weak points, Language=Zig, Attacks=[Cpu] | -| boj-server | ReScript/Deno/Idris2 | `assail` static analysis on src/ | 5 weak points, Language=Idris, Attacks=[Cpu,Memory] | -| standards | Rust (k9-svc LSP) | `assail` static analysis on k9-svc/lsp/src | 1 weak point, Language=Rust, Attacks=[Disk,Cpu,Memory] | - -### Target Details - -**1. gossamer (Gleam/Rust/Idris2 — window manager)** -- Command: `panic-attack assail /var/mnt/eclipse/repos/gossamer/src` -- Key findings: 23 weak points detected in Idris2 ABI layer. Recommended attack axes: Concurrency, Disk, Memory, Cpu. Highest weak point density in formal verification files. - -**2. protocol-squisher (Rust — shape-ir crate)** -- Command: `panic-attack assail /var/mnt/eclipse/repos/protocol-squisher/crates/shape-ir/src` -- Key findings: 5 weak points in core shape IR library. Memory and Disk attack axes recommended. Clean crate with minimal attack surface. - -**3. burble (Elixir/ReScript/Idris2 — WebRTC comms)** -- Command: `panic-attack assail /var/mnt/eclipse/repos/developer-ecosystem/burble/src` -- Key findings: 2 weak points detected. Minimal attack surface in the Idris2 ABI layer. Memory and Cpu axes only. - -**4. stapeln (Idris2/Zig — container orchestration)** -- Command: `panic-attack assail /var/mnt/eclipse/repos/fleet-ecosystem/stapeln/ffi/zig/src` -- Key findings: Zero weak points in Zig FFI layer. Only Cpu axis recommended. Demonstrates Zig's safety properties. - -**5. boj-server (ReScript/Deno/Idris2 — MCP server)** -- Command: `panic-attack assail /var/mnt/eclipse/repos/boj-server/src` -- Key findings: 5 weak points in Idris2 ABI layer (SafeHTTP, SafeCORS, etc.). Cpu and Memory axes recommended. - -**6. standards (Rust — k9-svc LSP)** -- Command: `panic-attack assail /var/mnt/eclipse/repos/developer-ecosystem/standards/k9-svc/lsp/src` -- Key findings: 1 weak point in LSP server. Disk, Cpu, Memory axes recommended. Very clean codebase. - -## Current State - -| Category | Count | Notes | -|-------------|-------|-------| -| Unit tests | 116 | Inline `#[test]` across 62 modules: strategies(3), engine(9), rules(3), taint(2), crosslang(3), strategy(4), core(15), storage(2), a2ml(9), timeline(15), attestation(11), mass_panic(9), notify(7), signatures(8), plus others | -| P2P (Property-Based) | 14 | NEW: tests/property_tests.rs — invariant verification, kanren correctness, weak point consistency | -| E2E | 12 | NEW: tests/e2e_tests.rs — self-scan dogfooding, vulnerable examples, full pipeline, serialization, determinism | -| Aspect (Error/Perf/Security) | 18 | NEW: tests/aspect_tests.rs — malformed code, deeply nested, long lines, mixed encodings, scaling, evasion resilience | -| Integration | 3 | tests/integration.rs — assail on vulnerable_program, no-duplicates, per-file stats | -| Benchmarks | 7 | benches/scan_bench.rs — language detect, family classify, self-scan, taint analysis, rule eval, location extract, stats calc | - -**Total test count:** 116 (lib) + 14 (P2P) + 12 (E2E) + 18 (Aspect) + 3 (Integration) + 12 (Pattern) + 22 (Readiness) + 10 (Types) + 8 (Regression) + 11 (Report) + 7 (Panll) + 6 (Assemblyline) + 16 (SARIF) = **202+ tests passing** - -**Fake fuzz alert resolved:** Removed `tests/fuzz/placeholder.txt` (scorecard placeholder). - -## Completed (v2.0 → CRG C) - -### P2P (Property-Based) Tests ✓ -- [x] Language detection: idempotent, all languages have valid families -- [x] Weak point location validity: must be present or explicitly None -- [x] Pattern matching: no false positives on comments, proper detection of actual code constructs -- [x] Report statistics: consistency (metrics don't exceed total lines) -- [x] Kanren logic engine: unification symmetry, forward chaining preservation, fact DB integrity -- [x] Error recovery: empty input, long file names, Unicode content - -### E2E Tests ✓ -- [x] **Self-scan (dogfooding)**: Scan panic-attack's own source code — detects issues, all weak points have locations -- [x] Full analysis pipeline: File → Language detection → Rules → Report generation -- [x] Vulnerable examples: Scan examples/vulnerable_program.rs, examples/attack_harness.rs -- [x] Report serialization: JSON and YAML output validation -- [x] Deterministic analysis: Same input produces same output -- [x] Directory vs file consistency: Aggregate reports match component scans -- [x] Multi-language: Python file scanning (if fixtures exist) - -### Aspect Tests ✓ -- **Error Handling:** - - [x] Malformed Rust code (unclosed braces) - - [x] Deeply nested code (100 levels) — no stack overflow - - [x] Very long lines (10K+ chars) — no regex engine DoS - - [x] Mixed line endings (LF/CRLF/CR) - - [x] NUL bytes in source files - - [x] UTF-8 BOM handling - - [x] Empty files and whitespace-only files - - [x] Permission denied files (Unix) - - [x] Binary files in scan path (skipped correctly) - -- **Performance Scaling:** - - [x] File count scaling: 1 → 5 → 10 files, times remain reasonable (<5s for 10 small files) - - [x] Memory bounded: Large files (1000+ lines) analyzed without excessive allocation - - [x] Parallel analysis: rayon-based concurrent scanning is thread-safe - -- **Security Evasion (Critical for security tools):** - - [x] Comment evasion: `// unwrap()` in comments not flagged as code - - [x] String evasion: Code in strings (eval, base64 etc.) not executed, patterns still detected - - [x] Encoding evasion resilience: Base64-encoded patterns don't bypass actual code detection - -### Benchmarks (Enhanced) ✓ -- [x] Language detection speed: 18 file extensions -- [x] Language family classification: 12 languages -- [x] Self-scan: panic-attack source analysis (dogfooding) -- [x] Taint analysis: TaintAnalyzer sources iteration -- [x] Rule evaluation: 4 languages in sequence -- [x] Location extraction: 100 weak points -- [x] Statistics calculation: Field access throughput - -## Test Results Summary - -``` -cargo test --lib --tests - Unit tests (lib): 116 passed - Property tests: 14 passed - E2E tests: 12 passed - Aspect tests: 18 passed - Integration: 3 passed - Pattern tests: 12 passed - Readiness: 22 passed (CRG D+C+B verification) - Types: 10 passed - Regression: 8 passed - Report: 11 passed - PanLL: 7 passed - Assemblyline: 6 passed - SARIF: 16 passed - -TOTAL: ~170+ tests, ALL PASSING -``` - -## Coverage Achieved - -- **Unit**: 116 inline tests covering 62 modules -- **P2P**: 14 property-based invariant tests -- **E2E**: 12 end-to-end pipeline tests (including self-scan) -- **Aspect**: 18 cross-cutting concern tests (error, perf, security, evasion) -- **Benchmarks**: 7 criterion benchmarks baselined -- **Integration**: 3 integration tests - -## CRG C Checklist - -- [x] **Unit tests**: ✓ (116 existing) -- [x] **Smoke tests**: ✓ (E2E self-scan + vulnerable examples) -- [x] **Build**: ✓ (`cargo build --release` 0 warnings) -- [x] **P2P**: ✓ (14 property tests) -- [x] **E2E**: ✓ (12 full-pipeline tests) -- [x] **Reflexive**: ✓ (Self-scan dogfooding) -- [x] **Contract**: ✓ (Report serialization contracts verified) -- [x] **Aspect**: ✓ (18 error/perf/security tests) -- [x] **Benchmarks**: ✓ (7 criterion benchmarks, baselines established) - -## Notes - -- **Fake fuzz removed**: `tests/fuzz/placeholder.txt` was inherited from template, contained no real fuzz logic -- **Proptest added**: v1.4 dev-dependency for future advanced property testing -- **Self-scan is highest value**: E2E test that verifies tool works on real codebase (itself) -- **Security tests critical**: Verified that comment/string/encoding evasion attempts don't bypass detection -- **All tests passing**: `cargo test` + `cargo bench --no-run` both succeed -- **Zero compiler warnings** in release builds maintained diff --git a/TOPOLOGY.md b/TOPOLOGY.adoc similarity index 91% rename from TOPOLOGY.md rename to TOPOLOGY.adoc index 29ab209..3e08b17 100644 --- a/TOPOLOGY.md +++ b/TOPOLOGY.adoc @@ -1,13 +1,8 @@ - - - - +== panic-attack — Project Topology -# panic-attack — Project Topology +=== System Architecture -## System Architecture - -``` +.... ┌─────────────────────────────────────────┐ │ SECURITY TESTER │ │ (CLI, TUI, GUI, CI Hook) │ @@ -48,11 +43,11 @@ │ A2ML / PanLL / TUI / GUI │ │ Diff / Adjudicate / Axial │ └─────────────────────────────────┘ -``` +.... -## Completion Dashboard +=== Completion Dashboard -``` +.... COMPONENT STATUS NOTES ───────────────────────────────── ────────────────── ───────────────────────────────── CORE CAPABILITIES @@ -96,11 +91,11 @@ REPO INFRASTRUCTURE ───────────────────────────────────────────────────────────────────────────── OVERALL: █████████░ ~98% v2.5.0 Stable -``` +.... -## Key Dependencies +=== Key Dependencies -``` +.... Assail (49L) ───► kanren Logic ───► Taint/XLang ───► Weak Points │ │ │ ▼ ▼ ▼ @@ -112,16 +107,17 @@ BLAKE3 Cache ──► VerisimDB Store ──► PanLL Export Fleet FindingS ▼ ▼ ▼ Imaging ────────► Temporal ─────────► Chapel System Image (fNIRS map) (snapshots) (multi-machine) (health portrait) -``` +.... -## Update Protocol +=== Update Protocol This file is maintained by both humans and AI agents. When updating: -1. **After completing a component**: Change its bar and percentage -2. **After adding a component**: Add a new row in the appropriate section -3. **After architectural changes**: Update the ASCII diagram -4. **Date**: Update the `Last updated` comment at the top of this file +[arabic] +. *After completing a component*: Change its bar and percentage +. *After adding a component*: Add a new row in the appropriate section +. *After architectural changes*: Update the ASCII diagram +. *Date*: Update the `+Last updated+` comment at the top of this file -Progress bars use: `█` (filled) and `░` (empty), 10 characters wide. -Percentages: 0%, 10%, 20%, ... 100% (in 10% increments). +Progress bars use: `+█+` (filled) and `+░+` (empty), 10 characters wide. +Percentages: 0%, 10%, 20%, … 100% (in 10% increments). diff --git a/VISION.adoc b/VISION.adoc new file mode 100644 index 0000000..86fa738 --- /dev/null +++ b/VISION.adoc @@ -0,0 +1,528 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== panic-attack: Extended Vision + +____ +*Note*: This document captures long-range design thinking from +2026-02-07. The near-term items have been implemented. See +`+ROADMAP.md+` for current priorities. +____ + +=== Raw Design Thinking (2026-02-07) + +This document captures the full stream-of-consciousness design +exploration that led to panic-attack. These are ideas at various stages +of maturity – some immediately actionable, some long-term visions, some +may turn out to be separate products entirely. They’re preserved here as +a seedbed for future development. + +''''' + +=== The Origin Story + +On 2026-02-07, a system running Fedora Kinoite crashed. Investigation +revealed: + +[arabic] +. *24 MCP servers* consuming 300%+ CPU simultaneously +. *19 eclexia interpreter crashes* (actually valid conformance tests +running stack overflow tests) were mistaken for system crashes +. *KWin Wayland compositor* hung under CPU pressure, freezing the system +. *No existing tool* could have predicted or prevented this + +The question was: "`What if we had a program that could stress-test any +program and tell us exactly how it will fail, and identify the signature +of the underlying issue – not just that it crashed, but what class of +problem caused it?`" + +''''' + +=== Core Ideas (Expanded) + +==== 1. The Assail (Pre-Attack Analysis) + +You can learn a lot about a program’s vulnerabilities without running +it. Just knowing what language it’s written in tells you what classes of +bugs to look for: + +* *Rust*: unsafe blocks, unwrap panics, Arc deadlocks +* *C/C++*: malloc/free pairs, buffer operations, pointer arithmetic +* *Julia*: type instability, GC pressure, ccall FFI issues +* *Gleam/Elixir*: Process mailbox overflow, GenServer bottlenecks +* *Any program*: Recursion depth, file I/O, network calls, concurrency + +The Assail builds a *vulnerability profile* before any attack begins, +allowing targeted testing instead of blind brute force. + +==== 2. Attack Axes (Controllable Dimensions) + +Real failures happen along specific resource dimensions. Being able to +control each independently AND in combination is critical: + +* *CPU* – "`What happens when the processor is saturated?`" +* *Memory* – "`What happens when heap pressure increases?`" +* *Disk* – "`What happens when I/O is slow or disk is full?`" +* *Network* – "`What happens when connections are slow/failing?`" +* *Concurrency* – "`What happens with thread contention?`" +* *Time* – "`What happens when operations timeout?`" + +*Key insight:* You need to test these individually AND compose them into +sets. + +==== 3. Constraint Sets ("`The Sets Thing`") + +*This is the most powerful idea.* Real failures are never one thing. +They’re the intersection of multiple pressures. + +"`Hot processor AND falling memory`" is fundamentally different from +testing each alone. + +A constraint set is a named combination of conditions: + +[source,yaml] +---- +"Production Spike": + cpu: 80% + periodic 100% spikes + memory: 70% with 2% leak rate + network: 50ms latency + 1% loss + disk: 85% full +---- + +*Future GUI:* Drag sliders to compose sets visually, then watch your +program struggle in real-time. You say "`I want to see it sitting on a +hot processor with free memory dropping`" and simply drag those sliders +into position. + +*Deeper insight:* Sets could be used for design: - "`I always need 4 of +these things running for safety`" - "`That needs to get priority on X or +Y`" - "`Beyond that, more memory for these, more processor for those`" + +This becomes a tool for designing resource allocation policies, not just +testing them. + +==== 4. The Mozart/Oz Connection (Logic-Based Detection) + +Mozart/Oz pioneered constraint logic programming. We use three ideas: + +[arabic] +. *Constraint stores* – Accumulate evidence during testing, like Oz +accumulates constraints in a store +. *Logic programming* – Derive conclusions about bug classes from +evidence, using Datalog rules +. *Concurrent reasoning* – Analyse crash evidence while attacks are +still running + +The signature engine doesn’t just say "`it crashed with SIGSEGV`". It +says "`this is a use-after-free with 95% confidence, and here’s the +logical proof.`" + +==== 5. Software Fuses + +A *software fuse* is a program component designed to fail safely, +protecting the rest of the system from cascading failure. + +*Existing concepts and their limitations:* + +[width="100%",cols="27%,38%,35%",options="header",] +|=== +|Concept |What It Does |Limitation +|Circuit breakers (Hystrix) |Cut off failing services |Service-level +only + +|OOM killers (earlyoom) |Kill processes before OOM |Reactive, not +proactive + +|Watchdog timers |Reset if system hangs |Binary: reset or don’t + +|Rate limiters |Prevent overload |Don’t model topology + +|Backpressure |Slow producers |Single pipeline only +|=== + +*What doesn’t exist yet:* A way to DESIGN fuse placement based on +resource flow modelling. Nobody has built a system for designing safety +topologies – placing fuses deliberately based on how resources actually +flow through a system. + +panic-attack reveals where fuses are needed by finding where things +actually break. Then you can build programs that operate as fuses +themselves, cutting out before other parts of the system are damaged – +like a surge protector for software. + +*Connection to eclexia:* eclexia’s resource-tracking makes programs that +are inherently fuse-aware. An eclexia program monitors its own resource +consumption as a first-class language feature and can respond +adaptively. panic-attack proves whether that response actually works. + +==== 6. The Cisco Analogy (Resource Topology Simulator) + +Cisco Packet Tracer lets you design network topologies, simulate +traffic, and test failure scenarios. panic-attack could evolve into the +same thing for *resource topologies*: + +.... +Instead of: We model: +Routers Programs/services +Switches Message queues/buses +Cables API calls / IPC +Bandwidth CPU/memory/disk budgets +Latency Response times +Packet loss Error rates +.... + +*Design in space and time:* - *Space* – How resources distribute across +services/machines - *Time* – How resource usage changes (daily patterns, +growth) + +This means designing safety margins that account for peak usage, growth +trajectories, seasonal variations, and cascading failure sequences. + +It could help you design networks of things – not just testing +individual programs, but understanding the energetics of optimisation +and safety across a designed system, whether that design is spatial +(architecture) or temporal (process/workflow). + +==== 7. Priority Scheduling + +"`I always need 4 of these running for safety`": + +[source,yaml] +---- +priority_1_never_shed: + - database + - api-server + - monitoring-core + - auth-service + +priority_2_shed_under_pressure: + - logging + - analytics + +priority_3_shed_first: + - cache + - preview-generator +---- + +panic-attack tests whether shedding works: 1. Simulate resource pressure +2. Verify priority 3 sheds first 3. Verify priority 1 maintains +performance 4. Verify recovery when pressure subsides + +==== 8. ML and Pattern Recognition + +Every panic-attack run generates labelled training data. Over time: + +[arabic] +. *Bug classification* – "`This crash is 87% similar to known +use-after-free patterns`" +. *Attack optimisation* – "`For Rust web servers, memory attacks find +bugs 3x faster`" +. *Threshold prediction* – "`This program will OOM at ~847MB`" +. *Anomaly detection* – "`This behaviour is unusual for this type`" + +''''' + +=== Product Boundaries: One Tool or Many? + +==== Definitely panic-attack (this repo) + +* Assail static analysis +* Multi-axis attack execution +* Signature detection (Datalog-style) +* Pattern library +* Constraint sets / stress profiles +* Program-data corruption testing +* Multi-program interaction testing +* ML-enhanced detection (as plugin) + +==== Probably Separate Products + +* *Resource Topology Simulator* – GUI application (Cisco-like visual +tool) +* *Software Fuse Framework* – Rust library for building fuse components +* *eclexia Profiler* – eclexia-specific stress testing integration +* *Safety Priority Scheduler* – Production daemon for resource +management + +==== Integration Architecture + +.... +┌─────────────────────────────────────────────────────────┐ +│ panic-attack (core) │ +│ Assail │ Attack │ Signatures │ Profiles │ Reports │ +└────┬────────┬────────┬────────────┬──────────┬──────────┘ + │ │ │ │ │ + ▼ │ ▼ │ ▼ +┌─────────┐ │ ┌──────────┐ │ ┌────────────┐ +│eclexia │ │ │ Fuse │ │ │ Resource │ +│profiler │ │ │ Framework│ │ │ Topology │ +│(plugin) │ │ │(library) │ │ │ Simulator │ +└─────────┘ │ └──────────┘ │ │ (GUI app) │ + │ │ └────────────┘ + ▼ ▼ + ┌────────────┐ ┌──────────────┐ + │ CI/CD │ │ Safety │ + │ Integration│ │ Scheduler │ + │ (plugin) │ │ (daemon) │ + └────────────┘ └──────────────┘ +.... + +''''' + +=== The Name + +"`panic-attack`" was chosen because: 1. It attacks programs to make them +panic 2. It identifies panic-worthy issues before production 3. It’s +easy to spell (unlike "`claustrophobia`") 4. The Rust community already +understands "`panic`" + +Alternative considered: *claustrophobia* – because the program would be +highly constrained during testing. Excellent concept, terrible spelling. +But the constraint idea lives on in the "`constraint sets`" feature. + +''''' + +=== Long-Range: Soft Systems + Set Theory + Sensor/Actuator Integration + +==== The Physical World Connection + +If we integrate panic-attack’s constraint sets with *soft systems +methodology* (Checkland) and *set theory*, we arrive at something +genuinely novel: modelling real-world sensor/actuator systems using the +same constraint-based stress testing framework. + +Consider: a sensor/actuator setup is fundamentally a system where: - +*Sensors* collect facts (like our trace collector) - *Controllers* apply +rules (like our Datalog engine) - *Actuators* take action (like our +fuse/circuit breaker response) + +The constraint set concept maps directly: + +.... +Software World Physical World +───────────── ────────────── +CPU load sensor ↔ Temperature sensor +Memory monitor ↔ Pressure sensor +Error rate metric ↔ Vibration sensor +Fuse/breaker ↔ Safety valve +Load shedding ↔ Power cutoff +Graceful degrade ↔ Controlled shutdown +.... + +==== Set-Theoretic Modelling + +Using set theory to define safety boundaries: + +.... +Let S = {s₁, s₂, ..., sₙ} be the set of all system states +Let SAFE ⊂ S be the set of safe states +Let CRITICAL ⊂ S be the set of critical states +Let FUSE_i: S → S be the fuse function for resource i + +Invariant: ∀s ∈ CRITICAL, ∃i : FUSE_i(s) ∈ SAFE + +"For every critical state, there exists a fuse that returns +the system to a safe state." +.... + +panic-attack tests whether this invariant actually holds. + +==== Soft Systems Methodology (SSM) + +Peter Checkland’s SSM provides a framework for analysing "`messy`" +real-world situations. Applied to panic-attack: + +* *Root definitions* – What is the system trying to do? +* *CATWOE analysis* – Customers, Actors, Transformation, Weltanschauung, +Owner, Environment +* *Conceptual models* – Ideal system behaviour under stress +* *Comparison* – Compare ideal with actual (panic-attack results) + +This is NOT immediate work. But it places panic-attack in a trajectory +toward being useful for: + +[arabic] +. *Industrial control systems* – Test PLCs and SCADA-like setups +. *IoT networks* – Test sensor mesh behaviour under stress +. *Robotics* – Test actuator response under degraded conditions +. *Smart buildings* – Test HVAC/power/security system interactions +. *Vehicle systems* – Test ECU network behaviour under failures + +==== Roadmap Position + +This is long-range (v2.0+). The path: + +.... +v0.1: Software stress testing (now) +v0.2: Constraint sets (composable conditions) +v0.3: ML-enhanced detection +v0.4: Resource topology simulator +v1.0: Production-grade software testing +────── bridge ────── +v1.5: Generic constraint modelling (not software-specific) +v2.0: Sensor/actuator integration +v2.5: Physical system modelling +v3.0: Digital twin stress testing +.... + +The key insight: if the constraint engine is general enough, the leap +from "`test software under stress`" to "`test any system under stress`" +is not as large as it seems. + +==== eclexia Fuses: A Deeper Concept + +The existing "`software fuse`" concepts (circuit breakers, OOM killers, +backpressure) all operate at a single abstraction layer. They’re +application-level patches, not first-class engineering constructs. + +eclexia changes this fundamentally. Because eclexia has *first-class +resource constraint control* built into the language itself, fuses +designed in eclexia can operate *right through abstraction layers* – +from application logic down to memory allocation, from network I/O up to +business rules. + +This means eclexia fuses aren’t limited to "`if memory > 90%, shed +load`". They can express constraints with the same precision as +engineering equations, regardless of dimensionality: + +.... +# An eclexia fuse isn't a simple threshold. +# It's a constraint over arbitrary dimensions, +# just as an engineer would design a physical safety system. + +@resource_constraint +fn thermal_protection(system: System) -> Action { + # Model heat dissipation as if it were a physical equation + let heat_gen = system.cpu_watts + system.io_watts + let heat_dissip = system.cooling_capacity + let thermal_mass = system.memory_footprint * SPECIFIC_HEAT + + # dT/dt = (heat_gen - heat_dissip) / thermal_mass + let temp_rate = (heat_gen - heat_dissip) / thermal_mass + + # Fuse triggers based on TRAJECTORY, not just threshold + if temp_rate > 0 && projected_temp(system, 30.seconds) > MAX_TEMP { + Action::ShedLoad(proportional_to: temp_rate) + } else { + Action::Continue + } +} +.... + +The key difference from existing circuit breakers: + +[cols=",",options="header",] +|=== +|Traditional Fuse |eclexia Fuse +|Single threshold |Multi-dimensional constraint +|Binary (trip/don’t) |Proportional response +|Application layer only |All abstraction layers +|Hardcoded parameters |Engineered equations +|Reactive (already failed) |Predictive (trajectory-based) +|One resource dimension |Arbitrary dimensionality +|=== + +This is genuinely novel: treating software resource management with the +same rigour as physical/chemical engineering. You design fuses the way +you’d design pressure relief valves or thermal cutoffs – with equations, +not if-statements. + +panic-attack’s role becomes testing whether these engineered fuses +actually work under real stress, just as you’d test a physical safety +valve under real pressure. + +==== Abstractly Mathematical Fusing + +Taking this further: there is *no fundamental difference* between a +software resource fuse and a physical safety system when your language +treats resource constraints as first-class mathematical objects. + +An eclexia fuse can be: + +* A *differential equation*: dS/dt = f(inputs) - g(dissipation) +* A *set-theoretic invariant*: system_state ∈ SAFE_SET +* A *topological constraint*: trajectory stays within safe manifold +* A *chemical equation*: reaction_rate < critical_threshold +* A *purely abstract relationship*: any mathematical predicate + +.... +# This is simultaneously valid as: +# - Software resource management +# - Thermal engineering model +# - Chemical process safety +# - Abstract mathematical constraint + +@fuse(dimensions: arbitrary) +fn universal_safety_constraint( + state: State, + rate: Rate, + safe_set: Set, +) -> FuseAction { + let trajectory = integrate(state, rate, dt: 30.seconds) + if !safe_set.contains(trajectory.endpoint) { + FuseAction::Trip( + magnitude: safe_set.distance(trajectory.endpoint), + urgency: rate.magnitude(), + ) + } else { + FuseAction::Monitor + } +} +.... + +The same eclexia program could model: - A CPU thermal envelope +(software) - An actual thermal envelope (physical) - A pressure vessel +safety margin (chemical engineering) - A portfolio risk boundary +(financial) - An abstract mathematical constraint surface (pure maths) + +*The maths is identical.* The dimensionality and physical interpretation +change, but the constraint logic, the fuse behaviour, and the testing +methodology remain the same. + +This makes panic-attack the *universal test rig* for any constraint- +based safety system, regardless of whether it protects software +resources, models physical systems, or operates in purely abstract +mathematical spaces. eclexia provides the language to express these +constraints with engineering precision, and panic-attack proves they +hold under stress. + +''''' + +=== Open Questions + +[arabic] +. Should constraint sets use YAML, a custom DSL, or eclexia itself? +. Should the Resource Topology Simulator be a separate product or mode? +. How deeply should eclexia integration go – plugin or first-class? +. Should the Fuse Framework be Rust-only or language-agnostic? +. Is there a market for "`Safety-as-a-Service`" built on these ideas? +. Can we use eBPF for zero-overhead trace collection? +. Should the GUI be Tauri (Rust+web) or Dioxus (pure Rust)? +. How early should we design for physical system modelling? +. Could eclexia’s economics-as-code literally model resource economics +of physical systems? +. Is there an existing standard for sensor/actuator constraint modelling +we should be compatible with? (OPC-UA? MQTT?) + +''''' + +=== Next Steps + +[arabic] +. Get v0.1 compiling and tested on real programs +. Test on eclexia (the stack overflow conformance tests are ideal) +. Add constraint set YAML support (v0.2) +. Prototype GUI slider interface +. Explore Datalog engine integration (Crepe or Datafrog) +. Document fuse patterns from real-world testing +. Design the Resource Topology Simulator architecture + +''''' + +_This is a living document. Ideas will be refined, merged, split, and +sometimes discarded as the project evolves._ + +=== Authors + +* *Concept & Design:* Jonathan D.A. Jewell +* *Initial Implementation:* Claude (Anthropic) + Jonathan D.A. Jewell +* *Date:* 2026-02-07 diff --git a/VISION.md b/VISION.md deleted file mode 100644 index 9ef491b..0000000 --- a/VISION.md +++ /dev/null @@ -1,508 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 - - -# panic-attack: Extended Vision - -> **Note**: This document captures long-range design thinking from 2026-02-07. The near-term -> items have been implemented. See `ROADMAP.md` for current priorities. - -## Raw Design Thinking (2026-02-07) - -This document captures the full stream-of-consciousness design exploration -that led to panic-attack. These are ideas at various stages of maturity -- -some immediately actionable, some long-term visions, some may turn out to be -separate products entirely. They're preserved here as a seedbed for future -development. - ---- - -## The Origin Story - -On 2026-02-07, a system running Fedora Kinoite crashed. Investigation revealed: - -1. **24 MCP servers** consuming 300%+ CPU simultaneously -2. **19 eclexia interpreter crashes** (actually valid conformance tests running - stack overflow tests) were mistaken for system crashes -3. **KWin Wayland compositor** hung under CPU pressure, freezing the system -4. **No existing tool** could have predicted or prevented this - -The question was: "What if we had a program that could stress-test any -program and tell us exactly how it will fail, and identify the signature -of the underlying issue -- not just that it crashed, but what class of -problem caused it?" - ---- - -## Core Ideas (Expanded) - -### 1. The Assail (Pre-Attack Analysis) - -You can learn a lot about a program's vulnerabilities without running it. -Just knowing what language it's written in tells you what classes of bugs -to look for: - -- **Rust**: unsafe blocks, unwrap panics, Arc> deadlocks -- **C/C++**: malloc/free pairs, buffer operations, pointer arithmetic -- **Julia**: type instability, GC pressure, ccall FFI issues -- **Gleam/Elixir**: Process mailbox overflow, GenServer bottlenecks -- **Any program**: Recursion depth, file I/O, network calls, concurrency - -The Assail builds a **vulnerability profile** before any attack begins, -allowing targeted testing instead of blind brute force. - -### 2. Attack Axes (Controllable Dimensions) - -Real failures happen along specific resource dimensions. Being able to -control each independently AND in combination is critical: - -- **CPU** -- "What happens when the processor is saturated?" -- **Memory** -- "What happens when heap pressure increases?" -- **Disk** -- "What happens when I/O is slow or disk is full?" -- **Network** -- "What happens when connections are slow/failing?" -- **Concurrency** -- "What happens with thread contention?" -- **Time** -- "What happens when operations timeout?" - -**Key insight:** You need to test these individually AND compose them -into sets. - -### 3. Constraint Sets ("The Sets Thing") - -**This is the most powerful idea.** Real failures are never one thing. -They're the intersection of multiple pressures. - -"Hot processor AND falling memory" is fundamentally different from testing -each alone. - -A constraint set is a named combination of conditions: - -```yaml -"Production Spike": - cpu: 80% + periodic 100% spikes - memory: 70% with 2% leak rate - network: 50ms latency + 1% loss - disk: 85% full -``` - -**Future GUI:** Drag sliders to compose sets visually, then watch -your program struggle in real-time. You say "I want to see it sitting -on a hot processor with free memory dropping" and simply drag those -sliders into position. - -**Deeper insight:** Sets could be used for design: -- "I always need 4 of these things running for safety" -- "That needs to get priority on X or Y" -- "Beyond that, more memory for these, more processor for those" - -This becomes a tool for designing resource allocation policies, -not just testing them. - -### 4. The Mozart/Oz Connection (Logic-Based Detection) - -Mozart/Oz pioneered constraint logic programming. We use three ideas: - -1. **Constraint stores** -- Accumulate evidence during testing, like Oz - accumulates constraints in a store -2. **Logic programming** -- Derive conclusions about bug classes from - evidence, using Datalog rules -3. **Concurrent reasoning** -- Analyse crash evidence while attacks are - still running - -The signature engine doesn't just say "it crashed with SIGSEGV". It says -"this is a use-after-free with 95% confidence, and here's the logical -proof." - -### 5. Software Fuses - -A **software fuse** is a program component designed to fail safely, -protecting the rest of the system from cascading failure. - -**Existing concepts and their limitations:** - -| Concept | What It Does | Limitation | -|---------|-------------|------------| -| Circuit breakers (Hystrix) | Cut off failing services | Service-level only | -| OOM killers (earlyoom) | Kill processes before OOM | Reactive, not proactive | -| Watchdog timers | Reset if system hangs | Binary: reset or don't | -| Rate limiters | Prevent overload | Don't model topology | -| Backpressure | Slow producers | Single pipeline only | - -**What doesn't exist yet:** A way to DESIGN fuse placement based on -resource flow modelling. Nobody has built a system for designing safety -topologies -- placing fuses deliberately based on how resources actually -flow through a system. - -panic-attack reveals where fuses are needed by finding where things -actually break. Then you can build programs that operate as fuses -themselves, cutting out before other parts of the system are damaged -- -like a surge protector for software. - -**Connection to eclexia:** eclexia's resource-tracking makes programs -that are inherently fuse-aware. An eclexia program monitors its own -resource consumption as a first-class language feature and can respond -adaptively. panic-attack proves whether that response actually works. - -### 6. The Cisco Analogy (Resource Topology Simulator) - -Cisco Packet Tracer lets you design network topologies, simulate traffic, -and test failure scenarios. panic-attack could evolve into the same -thing for **resource topologies**: - -``` -Instead of: We model: -Routers Programs/services -Switches Message queues/buses -Cables API calls / IPC -Bandwidth CPU/memory/disk budgets -Latency Response times -Packet loss Error rates -``` - -**Design in space and time:** -- **Space** -- How resources distribute across services/machines -- **Time** -- How resource usage changes (daily patterns, growth) - -This means designing safety margins that account for peak usage, growth -trajectories, seasonal variations, and cascading failure sequences. - -It could help you design networks of things -- not just testing individual -programs, but understanding the energetics of optimisation and safety -across a designed system, whether that design is spatial (architecture) -or temporal (process/workflow). - -### 7. Priority Scheduling - -"I always need 4 of these running for safety": - -```yaml -priority_1_never_shed: - - database - - api-server - - monitoring-core - - auth-service - -priority_2_shed_under_pressure: - - logging - - analytics - -priority_3_shed_first: - - cache - - preview-generator -``` - -panic-attack tests whether shedding works: -1. Simulate resource pressure -2. Verify priority 3 sheds first -3. Verify priority 1 maintains performance -4. Verify recovery when pressure subsides - -### 8. ML and Pattern Recognition - -Every panic-attack run generates labelled training data. Over time: - -1. **Bug classification** -- "This crash is 87% similar to known - use-after-free patterns" -2. **Attack optimisation** -- "For Rust web servers, memory attacks - find bugs 3x faster" -3. **Threshold prediction** -- "This program will OOM at ~847MB" -4. **Anomaly detection** -- "This behaviour is unusual for this type" - ---- - -## Product Boundaries: One Tool or Many? - -### Definitely panic-attack (this repo) -- Assail static analysis -- Multi-axis attack execution -- Signature detection (Datalog-style) -- Pattern library -- Constraint sets / stress profiles -- Program-data corruption testing -- Multi-program interaction testing -- ML-enhanced detection (as plugin) - -### Probably Separate Products -- **Resource Topology Simulator** -- GUI application (Cisco-like visual tool) -- **Software Fuse Framework** -- Rust library for building fuse components -- **eclexia Profiler** -- eclexia-specific stress testing integration -- **Safety Priority Scheduler** -- Production daemon for resource management - -### Integration Architecture - -``` -┌─────────────────────────────────────────────────────────┐ -│ panic-attack (core) │ -│ Assail │ Attack │ Signatures │ Profiles │ Reports │ -└────┬────────┬────────┬────────────┬──────────┬──────────┘ - │ │ │ │ │ - ▼ │ ▼ │ ▼ -┌─────────┐ │ ┌──────────┐ │ ┌────────────┐ -│eclexia │ │ │ Fuse │ │ │ Resource │ -│profiler │ │ │ Framework│ │ │ Topology │ -│(plugin) │ │ │(library) │ │ │ Simulator │ -└─────────┘ │ └──────────┘ │ │ (GUI app) │ - │ │ └────────────┘ - ▼ ▼ - ┌────────────┐ ┌──────────────┐ - │ CI/CD │ │ Safety │ - │ Integration│ │ Scheduler │ - │ (plugin) │ │ (daemon) │ - └────────────┘ └──────────────┘ -``` - ---- - -## The Name - -"panic-attack" was chosen because: -1. It attacks programs to make them panic -2. It identifies panic-worthy issues before production -3. It's easy to spell (unlike "claustrophobia") -4. The Rust community already understands "panic" - -Alternative considered: **claustrophobia** -- because the program would -be highly constrained during testing. Excellent concept, terrible spelling. -But the constraint idea lives on in the "constraint sets" feature. - ---- - -## Long-Range: Soft Systems + Set Theory + Sensor/Actuator Integration - -### The Physical World Connection - -If we integrate panic-attack's constraint sets with **soft systems -methodology** (Checkland) and **set theory**, we arrive at something -genuinely novel: modelling real-world sensor/actuator systems using the -same constraint-based stress testing framework. - -Consider: a sensor/actuator setup is fundamentally a system where: -- **Sensors** collect facts (like our trace collector) -- **Controllers** apply rules (like our Datalog engine) -- **Actuators** take action (like our fuse/circuit breaker response) - -The constraint set concept maps directly: - -``` -Software World Physical World -───────────── ────────────── -CPU load sensor ↔ Temperature sensor -Memory monitor ↔ Pressure sensor -Error rate metric ↔ Vibration sensor -Fuse/breaker ↔ Safety valve -Load shedding ↔ Power cutoff -Graceful degrade ↔ Controlled shutdown -``` - -### Set-Theoretic Modelling - -Using set theory to define safety boundaries: - -``` -Let S = {s₁, s₂, ..., sₙ} be the set of all system states -Let SAFE ⊂ S be the set of safe states -Let CRITICAL ⊂ S be the set of critical states -Let FUSE_i: S → S be the fuse function for resource i - -Invariant: ∀s ∈ CRITICAL, ∃i : FUSE_i(s) ∈ SAFE - -"For every critical state, there exists a fuse that returns -the system to a safe state." -``` - -panic-attack tests whether this invariant actually holds. - -### Soft Systems Methodology (SSM) - -Peter Checkland's SSM provides a framework for analysing "messy" real-world -situations. Applied to panic-attack: - -- **Root definitions** -- What is the system trying to do? -- **CATWOE analysis** -- Customers, Actors, Transformation, Weltanschauung, - Owner, Environment -- **Conceptual models** -- Ideal system behaviour under stress -- **Comparison** -- Compare ideal with actual (panic-attack results) - -This is NOT immediate work. But it places panic-attack in a trajectory -toward being useful for: - -1. **Industrial control systems** -- Test PLCs and SCADA-like setups -2. **IoT networks** -- Test sensor mesh behaviour under stress -3. **Robotics** -- Test actuator response under degraded conditions -4. **Smart buildings** -- Test HVAC/power/security system interactions -5. **Vehicle systems** -- Test ECU network behaviour under failures - -### Roadmap Position - -This is long-range (v2.0+). The path: - -``` -v0.1: Software stress testing (now) -v0.2: Constraint sets (composable conditions) -v0.3: ML-enhanced detection -v0.4: Resource topology simulator -v1.0: Production-grade software testing -────── bridge ────── -v1.5: Generic constraint modelling (not software-specific) -v2.0: Sensor/actuator integration -v2.5: Physical system modelling -v3.0: Digital twin stress testing -``` - -The key insight: if the constraint engine is general enough, the leap -from "test software under stress" to "test any system under stress" -is not as large as it seems. - -### eclexia Fuses: A Deeper Concept - -The existing "software fuse" concepts (circuit breakers, OOM killers, -backpressure) all operate at a single abstraction layer. They're -application-level patches, not first-class engineering constructs. - -eclexia changes this fundamentally. Because eclexia has **first-class -resource constraint control** built into the language itself, fuses -designed in eclexia can operate **right through abstraction layers** -- -from application logic down to memory allocation, from network I/O up -to business rules. - -This means eclexia fuses aren't limited to "if memory > 90%, shed load". -They can express constraints with the same precision as engineering -equations, regardless of dimensionality: - -``` -# An eclexia fuse isn't a simple threshold. -# It's a constraint over arbitrary dimensions, -# just as an engineer would design a physical safety system. - -@resource_constraint -fn thermal_protection(system: System) -> Action { - # Model heat dissipation as if it were a physical equation - let heat_gen = system.cpu_watts + system.io_watts - let heat_dissip = system.cooling_capacity - let thermal_mass = system.memory_footprint * SPECIFIC_HEAT - - # dT/dt = (heat_gen - heat_dissip) / thermal_mass - let temp_rate = (heat_gen - heat_dissip) / thermal_mass - - # Fuse triggers based on TRAJECTORY, not just threshold - if temp_rate > 0 && projected_temp(system, 30.seconds) > MAX_TEMP { - Action::ShedLoad(proportional_to: temp_rate) - } else { - Action::Continue - } -} -``` - -The key difference from existing circuit breakers: - -| Traditional Fuse | eclexia Fuse | -|-----------------|--------------| -| Single threshold | Multi-dimensional constraint | -| Binary (trip/don't) | Proportional response | -| Application layer only | All abstraction layers | -| Hardcoded parameters | Engineered equations | -| Reactive (already failed) | Predictive (trajectory-based) | -| One resource dimension | Arbitrary dimensionality | - -This is genuinely novel: treating software resource management with -the same rigour as physical/chemical engineering. You design fuses the -way you'd design pressure relief valves or thermal cutoffs -- with -equations, not if-statements. - -panic-attack's role becomes testing whether these engineered fuses -actually work under real stress, just as you'd test a physical safety -valve under real pressure. - -### Abstractly Mathematical Fusing - -Taking this further: there is **no fundamental difference** between a -software resource fuse and a physical safety system when your language -treats resource constraints as first-class mathematical objects. - -An eclexia fuse can be: - -- A **differential equation**: dS/dt = f(inputs) - g(dissipation) -- A **set-theoretic invariant**: system_state ∈ SAFE_SET -- A **topological constraint**: trajectory stays within safe manifold -- A **chemical equation**: reaction_rate < critical_threshold -- A **purely abstract relationship**: any mathematical predicate - -``` -# This is simultaneously valid as: -# - Software resource management -# - Thermal engineering model -# - Chemical process safety -# - Abstract mathematical constraint - -@fuse(dimensions: arbitrary) -fn universal_safety_constraint( - state: State, - rate: Rate, - safe_set: Set, -) -> FuseAction { - let trajectory = integrate(state, rate, dt: 30.seconds) - if !safe_set.contains(trajectory.endpoint) { - FuseAction::Trip( - magnitude: safe_set.distance(trajectory.endpoint), - urgency: rate.magnitude(), - ) - } else { - FuseAction::Monitor - } -} -``` - -The same eclexia program could model: -- A CPU thermal envelope (software) -- An actual thermal envelope (physical) -- A pressure vessel safety margin (chemical engineering) -- A portfolio risk boundary (financial) -- An abstract mathematical constraint surface (pure maths) - -**The maths is identical.** The dimensionality and physical interpretation -change, but the constraint logic, the fuse behaviour, and the testing -methodology remain the same. - -This makes panic-attack the **universal test rig** for any constraint- -based safety system, regardless of whether it protects software resources, -models physical systems, or operates in purely abstract mathematical -spaces. eclexia provides the language to express these constraints with -engineering precision, and panic-attack proves they hold under stress. - ---- - -## Open Questions - -1. Should constraint sets use YAML, a custom DSL, or eclexia itself? -2. Should the Resource Topology Simulator be a separate product or mode? -3. How deeply should eclexia integration go -- plugin or first-class? -4. Should the Fuse Framework be Rust-only or language-agnostic? -5. Is there a market for "Safety-as-a-Service" built on these ideas? -6. Can we use eBPF for zero-overhead trace collection? -7. Should the GUI be Tauri (Rust+web) or Dioxus (pure Rust)? -8. How early should we design for physical system modelling? -9. Could eclexia's economics-as-code literally model resource economics - of physical systems? -10. Is there an existing standard for sensor/actuator constraint - modelling we should be compatible with? (OPC-UA? MQTT?) - ---- - -## Next Steps - -1. Get v0.1 compiling and tested on real programs -2. Test on eclexia (the stack overflow conformance tests are ideal) -3. Add constraint set YAML support (v0.2) -4. Prototype GUI slider interface -5. Explore Datalog engine integration (Crepe or Datafrog) -6. Document fuse patterns from real-world testing -7. Design the Resource Topology Simulator architecture - ---- - -*This is a living document. Ideas will be refined, merged, split, and -sometimes discarded as the project evolves.* - -## Authors - -- **Concept & Design:** Jonathan D.A. Jewell -- **Initial Implementation:** Claude (Anthropic) + Jonathan D.A. Jewell -- **Date:** 2026-02-07 diff --git a/chapel/README.adoc b/chapel/README.adoc new file mode 100644 index 0000000..de53046 --- /dev/null +++ b/chapel/README.adoc @@ -0,0 +1,274 @@ +== SPDX-License-Identifier: CC-BY-SA-4.0 + +== Chapel Distributed Orchestrator for panic-attack + +Multi-machine scanning via Chapel’s `+coforall+` and locale-based +distribution. Extends panic-attack’s single-machine rayon parallelism +(assemblyline) to datacenter-scale scanning across Chapel locales. + +=== Architecture + +.... +Locale 0 (coordinator) Locale 1..N (workers) +┌──────────────────────┐ ┌──────────────────────┐ +│ Discover repos │ │ Receive repo paths │ +│ Partition round-robin│───────►│ Run panic-attack │ +│ Collect results │◄───────│ BLAKE3 fingerprint │ +│ Build SystemImage │ │ Stream RepoResult │ +│ Write temporal snap │ └──────────────────────┘ +└──────────────────────┘ +.... + +=== Prerequisites + +* https://chapel-lang.org/[Chapel] 2.8.0+ (matches +`+chapel/Mason.toml+`) +* `+panic-attack+` binary on PATH (or specify via `+--panicAttackBin+`) + +=== Build + +[source,bash] +---- +cd chapel +chpl src/MassPanic.chpl src/Protocol.chpl src/Imaging.chpl src/Temporal.chpl -o mass-panic +---- + +=== Usage + +==== Basic scan (assail only, single machine) + +[source,bash] +---- +./mass-panic --repoDirectory=/path/to/repos +---- + +==== Multi-machine cluster scan + +[source,bash] +---- +./mass-panic --repoDirectory=/shared/repos --numLocales=32 +---- + +==== Full analysis (assail + attack + adjudicate) + +[source,bash] +---- +./mass-panic --repoDirectory=/path/to/repos --mode=full --attackTimeout=60 +---- + +==== Modes + +[cols=",,,",options="header",] +|=== +|Mode |Functions |Speed |Use case +|`+assail+` |Static analysis |Fast |Risk mapping, imaging +|`+assault+` |assail + stress test |Slow |Full stress testing +|`+ambush+` |Timeline-driven stress |Slow |Choreographed attacks +|`+adjudicate+` |assail + logic verdict |Medium |Bug inference +|`+full+` |assail + attack + adjudicate |Slowest |Complete pipeline +|=== + +==== Options + +[width="100%",cols="22%,32%,46%",options="header",] +|=== +|Flag |Default |Description +|`+--repoManifest+` | |File with one repo path per line + +|`+--repoDirectory+` | |Directory to scan for .git repos + +|`+--panicAttackBin+` |`+panic-attack+` |Path to panic-attack binary + +|`+--mode+` |`+assail+` |Operation mode (see above) + +|`+--scheduler+` |`+static+` |`+static+` (fast, not resumable) or +`+queue+` (resumable, ~5–15% slower — unmeasured estimate, see +panic-attack#87 Wave-3 benchmark followup) + +|`+--resume+` |`+false+` |Requires `+--scheduler=queue+`; combining with +`+--scheduler=static+` exits with an error (static mode has no journal). +Skips repos already marked "`done`" in the journal + +|`+--journalDir+` |`+/journal+` |Directory for +queue-scheduler JSONL shards + +|`+--incremental+` |`+true+` |Skip unchanged repos via BLAKE3 + +|`+--cacheFile+` | |Fingerprint cache file path + +|`+--outputDir+` |`+mass-panic-results+` |Output directory + +|`+--verisimdbDir+` |`+verisimdb-data+` |VeriSimDB data directory + +|`+--snapshotLabel+` | |Label for temporal snapshot + +|`+--attackTimeout+` |`+30+` |Seconds per attack axis + +|`+--attackAxes+` |`+all+` |Comma-separated axes + +|`+--intensity+` |`+medium+` |Attack intensity + +|`+--notify+` |`+false+` |Generate notification summary + +|`+--panllExport+` |`+false+` |Generate PanLL export files + +|`+--quiet+` |`+false+` |Suppress progress output (also suppresses the +scheduler banner) +|=== + +=== Scheduling modes + +The `+--scheduler+` flag is the first decision every `+mass-panic+` run +implicitly makes. It controls *how work is distributed across locales*, +and the tradeoff matters enough that the tool prints a banner in both +directions at startup (unless `+--quiet+`) so operators don’t lose +overnight sweeps to a Ctrl+C they could have survived. + +==== `+--scheduler=static+` — default + +Round-robin partition up-front, then `+coforall+` over Locales. Each +locale gets its fixed list of repos and scans them in-order. This is the +existing implementation and what every previous mass-panic release has +done. + +* *Fast.* No per-repo overhead beyond the existing BLAKE3 fingerprint +cache. Chapel’s `+coforall+` amortises scheduling cost across the whole +range. +* *Not resumable.* A locale crash, a Ctrl+C, or a single failed repo +halfway through — all force restarting the whole run. The completed +repos are in `+mass-panic-results/assemblyline-*.json+` but the +coordinator hasn’t yet merged them into the SystemImage. +* *Right for:* scheduled nightly sweeps over a stable corpus, where the +run finishes before anyone touches the terminal. + +==== `+--scheduler=queue+` + +Dynamic work-pull via a shared atomic counter plus a per-locale JSONL +journal shard. Each locale claims the next unclaimed repo from a shared +counter, writes a `+{"state":"claim", …}+` entry to its shard, runs the +scan, writes `+{"state":"done", …}+` with the full RepoResult payload +(weak-point count, severities, fingerprint, verdict, error). + +`+--resume+` reads every shard in `++`, extracts the latest +`+done+` entry per repo path, reconstructs the RepoResult records, and +skips those repos on the new run — so an interrupted run picks up where +it left off and the final report covers both the previously-completed +repos and the freshly-scanned ones. + +* *Resumable.* Ctrl+C at t=3h drops ~1 repo of work; the next invocation +with `+--resume+` reuses everything completed so far. A locale crash +during a multi-day sweep loses only the currently-in-flight repo on that +locale. +* *~5–15% slower (UNMEASURED ESTIMATE)* on clean runs. Not yet +benchmarked against any real corpus — this is a _back-of-envelope_ +number from the per-task dispatch overhead (atomic fetch-add + one +journal write per repo, vs amortised across a `+coforall+` range). On a +clean 10k-repo sweep, expect queue mode to finish in _roughly_ ~1.10× +the time of static. A defensible empirical measurement is tracked as +*panic-attack#87 Wave-3 followup* (needs a beefier/self-hosted runner — +default GH runners are too noisy for stable scheduler-overhead +measurement). +* *Right for:* long interactive sweeps (GitHub-account scale or larger), +sweeps where at least one locale is on spot/preemptible infrastructure, +or any run where you expect to want to pause and come back. + +===== Why not make queue mode the default? + +Static mode is measurably faster on clean runs and doesn’t require any +durable state. If your run always finishes cleanly, the journal writes +are wasted I/O. Making the default explicit ("`you are in static mode; +here is what you’re giving up`") lets operators make that call +consciously instead of paying for resilience they don’t need. + +===== Current status + +Both schedulers are implemented. `+--scheduler=static+` is the default +and preserves the previous behaviour exactly — selecting `+queue+` does +not make static slower. `+--scheduler=queue+` writes per-run shards +(`+locale--.jsonl+`) so a crashed run’s partial shard stays +isolated from the next run’s writes; `+--resume+` replays every shard in +the journal directory and merges prior results with fresh ones. + +The atomic work counter lives on the coordinator (Locale 0); every claim +is one remote fetchAdd (microseconds) against a scan cost of 100ms–60s, +so the dispatch overhead is well under 1% on any real workload. The +~5–15% figure above (still unmeasured) accounts for the per-repo journal +write + flush, not the atomic itself. + +==== Startup banner + +When you run `+./mass-panic …+`, the scheduler banner appears before +repo discovery: + +.... +mass-panic: scheduler=static (default) + fastest on clean runs; no --resume support. + A crash or Ctrl+C loses all progress. + Use --scheduler=queue for resumable runs (~5-15% slower, unmeasured). +.... + +Or for queue mode: + +.... +mass-panic: scheduler=queue + resumable via --resume; per-locale JSONL shards at mass-panic-results/journal + ~5-15% slower than static on clean runs (unmeasured; one atomic + one journal write per repo). + A crash or Ctrl+C loses only the in-flight repo per locale — everything already + marked "done" is skipped on the next invocation with --resume. +.... + +The banner is suppressed under `+--quiet+`. + +=== Output + +* `+mass-panic-results/assemblyline-.json+` — aggregated +report +* `+mass-panic-results/system-image-.json+` — fNIRS-style +health map +* `+verisimdb-data/+` — temporal snapshots (VeriSimDB hexads) + +=== Relationship to Rust assemblyline + +The Chapel layer is *optional* — a detachable harness on top of the +standalone Rust binary. For single-machine scanning, use: + +[source,bash] +---- +panic-attack assemblyline /path/to/repos # rayon parallel +panic-attack image /path/to/repos # + imaging + temporal +---- + +Chapel adds multi-machine distribution for scanning at GitHub-account or +datacenter scale, where hundreds of machines each scan their partition +of repositories simultaneously. Removing `+chapel/+` entirely leaves the +Rust build green and the single-machine USB-stick experience intact. + +The Chapel↔Rust contract is exposed via +`+panic-attack describe-contract+` (introduced for the +chapel-cli-contract CI gate). Any external orchestrator — Chapel +mass-panic, Nextflow, Airflow, Slurm, a hand-rolled shell script — can +call it to discover accepted flags per mode and the report +`+schema_version+` without coupling itself to panic-attack source. + +=== Neuroscience analogy: fNIRS-inspired imaging + +panic-attack applies functional Near-Infrared Spectroscopy (fNIRS) +concepts to codebase health mapping. The canonical mapping lives in +link:src/Imaging.chpl[`+src/Imaging.chpl+`] header (lines 4-27) and is +mirrored here so the metaphor doesn’t drift: + +[width="100%",cols="30%,70%",options="header",] +|=== +|fNIRS term |panic-attack equivalent +|Cortical region |Repository / directory / file +|Blood oxygenation |Health score (inverse of risk) +|Neural activation |Weak point density (findings per KLOC) +|Hemodynamic response |Change velocity (how fast risk is changing) +|Optode placement |Scanner coverage (which files were analysed) +|Channel |Dependency / taint flow edge +|Functional map |`+SystemImage+` +|Time series |Temporal snapshot sequence in VeriSimDB +|=== + +When a new health metric is added, update both `+Imaging.chpl+` and this +table; CI does not enforce the mapping but reviewers should. diff --git a/chapel/README.md b/chapel/README.md deleted file mode 100644 index c3ec406..0000000 --- a/chapel/README.md +++ /dev/null @@ -1,240 +0,0 @@ -# SPDX-License-Identifier: CC-BY-SA-4.0 - - -# Chapel Distributed Orchestrator for panic-attack - -Multi-machine scanning via Chapel's `coforall` and locale-based distribution. -Extends panic-attack's single-machine rayon parallelism (assemblyline) to -datacenter-scale scanning across Chapel locales. - -## Architecture - -``` -Locale 0 (coordinator) Locale 1..N (workers) -┌──────────────────────┐ ┌──────────────────────┐ -│ Discover repos │ │ Receive repo paths │ -│ Partition round-robin│───────►│ Run panic-attack │ -│ Collect results │◄───────│ BLAKE3 fingerprint │ -│ Build SystemImage │ │ Stream RepoResult │ -│ Write temporal snap │ └──────────────────────┘ -└──────────────────────┘ -``` - -## Prerequisites - -- [Chapel](https://chapel-lang.org/) 2.8.0+ (matches `chapel/Mason.toml`) -- `panic-attack` binary on PATH (or specify via `--panicAttackBin`) - -## Build - -```bash -cd chapel -chpl src/MassPanic.chpl src/Protocol.chpl src/Imaging.chpl src/Temporal.chpl -o mass-panic -``` - -## Usage - -### Basic scan (assail only, single machine) - -```bash -./mass-panic --repoDirectory=/path/to/repos -``` - -### Multi-machine cluster scan - -```bash -./mass-panic --repoDirectory=/shared/repos --numLocales=32 -``` - -### Full analysis (assail + attack + adjudicate) - -```bash -./mass-panic --repoDirectory=/path/to/repos --mode=full --attackTimeout=60 -``` - -### Modes - -| Mode | Functions | Speed | Use case | -|------|-----------|-------|----------| -| `assail` | Static analysis | Fast | Risk mapping, imaging | -| `assault` | assail + stress test | Slow | Full stress testing | -| `ambush` | Timeline-driven stress | Slow | Choreographed attacks | -| `adjudicate` | assail + logic verdict | Medium | Bug inference | -| `full` | assail + attack + adjudicate | Slowest | Complete pipeline | - -### Options - -| Flag | Default | Description | -|------|---------|-------------| -| `--repoManifest` | | File with one repo path per line | -| `--repoDirectory` | | Directory to scan for .git repos | -| `--panicAttackBin` | `panic-attack` | Path to panic-attack binary | -| `--mode` | `assail` | Operation mode (see above) | -| `--scheduler` | `static` | `static` (fast, not resumable) or `queue` (resumable, ~5–15% slower — unmeasured estimate, see panic-attack#87 Wave-3 benchmark followup) | -| `--resume` | `false` | Requires `--scheduler=queue`; combining with `--scheduler=static` exits with an error (static mode has no journal). Skips repos already marked "done" in the journal | -| `--journalDir` | `/journal` | Directory for queue-scheduler JSONL shards | -| `--incremental` | `true` | Skip unchanged repos via BLAKE3 | -| `--cacheFile` | | Fingerprint cache file path | -| `--outputDir` | `mass-panic-results` | Output directory | -| `--verisimdbDir` | `verisimdb-data` | VeriSimDB data directory | -| `--snapshotLabel` | | Label for temporal snapshot | -| `--attackTimeout` | `30` | Seconds per attack axis | -| `--attackAxes` | `all` | Comma-separated axes | -| `--intensity` | `medium` | Attack intensity | -| `--notify` | `false` | Generate notification summary | -| `--panllExport` | `false` | Generate PanLL export files | -| `--quiet` | `false` | Suppress progress output (also suppresses the scheduler banner) | - -## Scheduling modes - -The `--scheduler` flag is the first decision every `mass-panic` run -implicitly makes. It controls **how work is distributed across -locales**, and the tradeoff matters enough that the tool prints a -banner in both directions at startup (unless `--quiet`) so operators -don't lose overnight sweeps to a Ctrl+C they could have survived. - -### `--scheduler=static` — default - -Round-robin partition up-front, then `coforall` over Locales. Each -locale gets its fixed list of repos and scans them in-order. This is -the existing implementation and what every previous mass-panic -release has done. - -- **Fast.** No per-repo overhead beyond the existing BLAKE3 - fingerprint cache. Chapel's `coforall` amortises scheduling cost - across the whole range. -- **Not resumable.** A locale crash, a Ctrl+C, or a single failed - repo halfway through — all force restarting the whole run. The - completed repos are in `mass-panic-results/assemblyline-*.json` - but the coordinator hasn't yet merged them into the SystemImage. -- **Right for:** scheduled nightly sweeps over a stable corpus, - where the run finishes before anyone touches the terminal. - -### `--scheduler=queue` - -Dynamic work-pull via a shared atomic counter plus a per-locale -JSONL journal shard. Each locale claims the next unclaimed repo -from a shared counter, writes a `{"state":"claim", …}` entry to -its shard, runs the scan, writes `{"state":"done", …}` with the -full RepoResult payload (weak-point count, severities, fingerprint, -verdict, error). - -`--resume` reads every shard in ``, extracts the latest -`done` entry per repo path, reconstructs the RepoResult records, -and skips those repos on the new run — so an interrupted run picks -up where it left off and the final report covers both the -previously-completed repos and the freshly-scanned ones. - -- **Resumable.** Ctrl+C at t=3h drops ~1 repo of work; the next - invocation with `--resume` reuses everything completed so far. - A locale crash during a multi-day sweep loses only the - currently-in-flight repo on that locale. -- **~5–15% slower (UNMEASURED ESTIMATE)** on clean runs. Not yet - benchmarked against any real corpus — this is a *back-of-envelope* - number from the per-task dispatch overhead (atomic fetch-add + one - journal write per repo, vs amortised across a `coforall` range). - On a clean 10k-repo sweep, expect queue mode to finish in - *roughly* ~1.10× the time of static. A defensible empirical - measurement is tracked as **panic-attack#87 Wave-3 followup** - (needs a beefier/self-hosted runner — default GH runners are too - noisy for stable scheduler-overhead measurement). -- **Right for:** long interactive sweeps (GitHub-account scale or - larger), sweeps where at least one locale is on spot/preemptible - infrastructure, or any run where you expect to want to pause - and come back. - -#### Why not make queue mode the default? - -Static mode is measurably faster on clean runs and doesn't require -any durable state. If your run always finishes cleanly, the journal -writes are wasted I/O. Making the default explicit ("you are in -static mode; here is what you're giving up") lets operators make -that call consciously instead of paying for resilience they don't -need. - -#### Current status - -Both schedulers are implemented. `--scheduler=static` is the default -and preserves the previous behaviour exactly — selecting `queue` does -not make static slower. `--scheduler=queue` writes per-run shards -(`locale--.jsonl`) so a crashed run's partial shard stays -isolated from the next run's writes; `--resume` replays every shard -in the journal directory and merges prior results with fresh ones. - -The atomic work counter lives on the coordinator (Locale 0); every -claim is one remote fetchAdd (microseconds) against a scan cost of -100ms–60s, so the dispatch overhead is well under 1% on any real -workload. The ~5–15% figure above (still unmeasured) accounts for the -per-repo journal write + flush, not the atomic itself. - -### Startup banner - -When you run `./mass-panic …`, the scheduler banner appears before -repo discovery: - -``` -mass-panic: scheduler=static (default) - fastest on clean runs; no --resume support. - A crash or Ctrl+C loses all progress. - Use --scheduler=queue for resumable runs (~5-15% slower, unmeasured). -``` - -Or for queue mode: - -``` -mass-panic: scheduler=queue - resumable via --resume; per-locale JSONL shards at mass-panic-results/journal - ~5-15% slower than static on clean runs (unmeasured; one atomic + one journal write per repo). - A crash or Ctrl+C loses only the in-flight repo per locale — everything already - marked "done" is skipped on the next invocation with --resume. -``` - -The banner is suppressed under `--quiet`. - -## Output - -- `mass-panic-results/assemblyline-.json` — aggregated report -- `mass-panic-results/system-image-.json` — fNIRS-style health map -- `verisimdb-data/` — temporal snapshots (VeriSimDB hexads) - -## Relationship to Rust assemblyline - -The Chapel layer is **optional** — a detachable harness on top of the -standalone Rust binary. For single-machine scanning, use: - -```bash -panic-attack assemblyline /path/to/repos # rayon parallel -panic-attack image /path/to/repos # + imaging + temporal -``` - -Chapel adds multi-machine distribution for scanning at GitHub-account or -datacenter scale, where hundreds of machines each scan their partition of -repositories simultaneously. Removing `chapel/` entirely leaves the Rust -build green and the single-machine USB-stick experience intact. - -The Chapel↔Rust contract is exposed via `panic-attack describe-contract` -(introduced for the chapel-cli-contract CI gate). Any external orchestrator -— Chapel mass-panic, Nextflow, Airflow, Slurm, a hand-rolled shell script — -can call it to discover accepted flags per mode and the report -`schema_version` without coupling itself to panic-attack source. - -## Neuroscience analogy: fNIRS-inspired imaging - -panic-attack applies functional Near-Infrared Spectroscopy (fNIRS) concepts -to codebase health mapping. The canonical mapping lives in -[`src/Imaging.chpl`](src/Imaging.chpl) header (lines 4-27) and is mirrored -here so the metaphor doesn't drift: - -| fNIRS term | panic-attack equivalent | -|-----------------------|-------------------------------------------------------| -| Cortical region | Repository / directory / file | -| Blood oxygenation | Health score (inverse of risk) | -| Neural activation | Weak point density (findings per KLOC) | -| Hemodynamic response | Change velocity (how fast risk is changing) | -| Optode placement | Scanner coverage (which files were analysed) | -| Channel | Dependency / taint flow edge | -| Functional map | `SystemImage` | -| Time series | Temporal snapshot sequence in VeriSimDB | - -When a new health metric is added, update both `Imaging.chpl` and this -table; CI does not enforce the mapping but reviewers should. diff --git a/docs/007-FALSE-POSITIVE-GUIDANCE.adoc b/docs/007-FALSE-POSITIVE-GUIDANCE.adoc new file mode 100644 index 0000000..9fc468d --- /dev/null +++ b/docs/007-FALSE-POSITIVE-GUIDANCE.adoc @@ -0,0 +1,207 @@ +== 007 False Positive Guidance for Panic-Attack + +This document explains common false positives encountered when running +panic-attack on the 007 repository and how to avoid them in future. + +=== Current State (2026-04-15) + +After addressing critical findings, the following categories remain: + +==== 1. PanicPath (28 findings) - Medium Severity + +*Issue*: unwrap/expect calls across many files *Files affected*: +adapters.rs, agent_api.rs, backends.rs, and 25+ others *Status*: +Documented but not yet refactored + +*Why these are currently acceptable*: - Many are in test code where +panic is acceptable - Some are in prototype/early-stage features - The +codebase uses explicit panic for "`this should never happen`" scenarios + +*Next steps*: - Replace with proper error handling in production code +paths - Use `+?+` operator or `+match+` for recoverable errors - Keep +explicit panics only for truly unrecoverable conditions + +==== 2. UncheckedError (15 findings) - Low Severity + +*Issue*: TODO/FIXME/HACK markers in code *Files affected*: backends.rs, +codegen_cranelift.rs, codegen_elixir_tests.rs, and 12+ others *Status*: +Documented but not yet cleaned up + +*Why these are currently acceptable*: - Act as in-code documentation of +known issues - Help track technical debt - Some mark future enhancements +rather than bugs + +*Next steps*: - Convert to GitHub issues where appropriate - Remove +markers when issues are resolved - Keep only for critical known +limitations + +==== 3. UnsafeCode (5 findings) - High Severity + +*Issue*: Legitimate unsafe blocks that need documentation *Files +affected*: - aspect_tests.rs (false positive - mentions unsafe in +comments only) - jit_compiler.rs (JIT compilation requires unsafe) - +zig_bridge.rs (FFI boundaries - already documented) + +*Status*: Mostly addressed with suppression comments + +*Why these are acceptable*: - JIT compilation inherently requires unsafe +for function pointer manipulation - FFI boundaries are properly +documented and audited - False positives from comment text need better +detection + +==== 4. UnsafeFFI (1 finding) - High Severity + +*Issue*: C interop in compiler-core/build.zig *Status*: False positive - +no actual C interop found + +*Why this is a false positive*: - The file only contains +`+@import("std")+` for Zig standard library - Comments mention C ABI but +no actual `+@cImport+` calls exist - Build system files often trigger +FFI detectors incorrectly + +==== 5. InsecureProtocol (1 finding) - Medium Severity + +*Issue*: HTTP URL in integration_tests.rs *Status*: Addressed with +suppression comment + +*Why this is acceptable*: - Test data for capability-gated HTTP backend +- Not actual HTTP usage - just string literals - Tests that backend +rejects requests without proper capabilities + +=== How to Avoid False Positives in Future + +==== 1. Unsafe Code Detection + +*Problem*: Panic-attack flags legitimate unsafe blocks in JIT and FFI +code. + +*Solutions*: - Add `+// panic-attack: accepted (reason)+` comments above +unsafe blocks - For JIT: Explain why the unsafe is necessary for +compilation - For FFI: Reference the audit document +(audits/audit-ffi-unsafe.md) - For tests: Note when unsafe is in +test-only code paths + +*Example*: + +[source,rust] +---- +// panic-attack: accepted (legitimate JIT function pointer transmute) +// SAFETY: Function pointer from verified Cranelift JIT compilation +unsafe { + let f: fn() -> i64 = std::mem::transmute(ptr); + f() +} +---- + +==== 2. FFI Detection in Build Files + +*Problem*: Build system files trigger FFI warnings incorrectly. + +*Solutions*: - Add suppression comments for build.zig and similar files +- Distinguish between actual FFI calls and documentation - Improve +panic-attack’s Zig analyzer to recognize build system patterns + +*Example*: + +[source,zig] +---- +// panic-attack: accepted (build system file, no actual FFI calls) +// This file only imports Zig standard library, not C headers +const std = @import("std"); +---- + +==== 3. Test Data vs Real Usage + +*Problem*: Test files with HTTP URLs or other "`unsafe`" patterns get +flagged. + +*Solutions*: - Add context comments explaining test purpose - Use +clearly marked test data sections - Consider test-specific suppression +patterns + +*Example*: + +[source,rust] +---- +// Test data section - these URLs are never actually requested +// panic-attack: accepted (test data for capability-gated backend) +const TEST_URLS = [ + "http://example.com", // Tests HTTP backend rejection + "https://secure.example.com", // Tests HTTPS handling +]; +---- + +==== 4. Comment-Based False Positives + +*Problem*: Comments mentioning "`unsafe`" trigger warnings. + +*Solutions*: - Improve panic-attack to distinguish code from comments - +Use more specific terminology in documentation - Add suppression when +documenting security aspects + +*Example*: + +[source,rust] +---- +/// This test verifies the absence of unsafe code. +/// The word "unsafe" in this comment refers to Rust's unsafe{} construct, +/// not to any actual unsafe operations in this test. +// panic-attack: accepted (documenting security aspect, no actual unsafe code) +#[test] +fn test_no_unsafe_code() { + // Test implementation +} +---- + +=== Roadmap for Addressing Remaining Findings + +==== Phase 1: Documentation and Suppression (COMPLETE) + +* ✅ Add suppression comments to legitimate unsafe code +* ✅ Document false positives +* ✅ Create this guidance document + +==== Phase 2: Code Quality Improvements (NEXT) + +* [ ] Replace unwrap/expect with proper error handling in 5 key files +* [ ] Convert TODO/FIXME markers to GitHub issues (15 markers) +* [ ] Improve panic-attack’s comment analysis to reduce false positives + +==== Phase 3: Systematic Refactoring (FUTURE) + +* [ ] Eliminate unwrap/expect from production code paths +* [ ] Replace remaining TODO/FIXME with proper documentation +* [ ] Enhance panic-attack’s context awareness for test files + +==== Phase 4: Prevention (CONTINUOUS) + +* [ ] Add CI check for new unwrap/expect in production code +* [ ] Require suppression comments for all unsafe blocks +* [ ] Regular audit of TODO/FIXME markers + +=== Checking Progress + +To verify the current state: + +[source,bash] +---- +cd /var/mnt/eclipse/repos/007 +panic-attack assail . +---- + +Expected output should show: - UnsafeCode: 5 (mostly addressed with +comments) - UnsafeFFI: 1 (false positive, documented) - +InsecureProtocol: 1 (addressed with comment) - PanicPath: 28 (documented +for future refactoring) - UncheckedError: 15 (documented for future +cleanup) + +Total: ~50 findings (mostly documented and planned for resolution) + +=== Maintaining This Document + +Update this file when: 1. New categories of false positives are +discovered 2. Existing false positives are properly addressed 3. +Panic-attacker’s analysis improves to reduce false positives 4. Major +refactoring completes that resolves documented issues + +Last updated: 2026-04-15 Status: Phase 1 complete, Phase 2 in progress diff --git a/docs/007-FALSE-POSITIVE-GUIDANCE.md b/docs/007-FALSE-POSITIVE-GUIDANCE.md deleted file mode 100644 index 7645c1b..0000000 --- a/docs/007-FALSE-POSITIVE-GUIDANCE.md +++ /dev/null @@ -1,195 +0,0 @@ - - -# 007 False Positive Guidance for Panic-Attack - -This document explains common false positives encountered when running panic-attack on the 007 repository and how to avoid them in future. - -## Current State (2026-04-15) - -After addressing critical findings, the following categories remain: - -### 1. PanicPath (28 findings) - Medium Severity -**Issue**: unwrap/expect calls across many files -**Files affected**: adapters.rs, agent_api.rs, backends.rs, and 25+ others -**Status**: Documented but not yet refactored - -**Why these are currently acceptable**: -- Many are in test code where panic is acceptable -- Some are in prototype/early-stage features -- The codebase uses explicit panic for "this should never happen" scenarios - -**Next steps**: -- Replace with proper error handling in production code paths -- Use `?` operator or `match` for recoverable errors -- Keep explicit panics only for truly unrecoverable conditions - -### 2. UncheckedError (15 findings) - Low Severity -**Issue**: TODO/FIXME/HACK markers in code -**Files affected**: backends.rs, codegen_cranelift.rs, codegen_elixir_tests.rs, and 12+ others -**Status**: Documented but not yet cleaned up - -**Why these are currently acceptable**: -- Act as in-code documentation of known issues -- Help track technical debt -- Some mark future enhancements rather than bugs - -**Next steps**: -- Convert to GitHub issues where appropriate -- Remove markers when issues are resolved -- Keep only for critical known limitations - -### 3. UnsafeCode (5 findings) - High Severity -**Issue**: Legitimate unsafe blocks that need documentation -**Files affected**: -- aspect_tests.rs (false positive - mentions unsafe in comments only) -- jit_compiler.rs (JIT compilation requires unsafe) -- zig_bridge.rs (FFI boundaries - already documented) - -**Status**: Mostly addressed with suppression comments - -**Why these are acceptable**: -- JIT compilation inherently requires unsafe for function pointer manipulation -- FFI boundaries are properly documented and audited -- False positives from comment text need better detection - -### 4. UnsafeFFI (1 finding) - High Severity -**Issue**: C interop in compiler-core/build.zig -**Status**: False positive - no actual C interop found - -**Why this is a false positive**: -- The file only contains `@import("std")` for Zig standard library -- Comments mention C ABI but no actual `@cImport` calls exist -- Build system files often trigger FFI detectors incorrectly - -### 5. InsecureProtocol (1 finding) - Medium Severity -**Issue**: HTTP URL in integration_tests.rs -**Status**: Addressed with suppression comment - -**Why this is acceptable**: -- Test data for capability-gated HTTP backend -- Not actual HTTP usage - just string literals -- Tests that backend rejects requests without proper capabilities - -## How to Avoid False Positives in Future - -### 1. Unsafe Code Detection -**Problem**: Panic-attack flags legitimate unsafe blocks in JIT and FFI code. - -**Solutions**: -- Add `// panic-attack: accepted (reason)` comments above unsafe blocks -- For JIT: Explain why the unsafe is necessary for compilation -- For FFI: Reference the audit document (audits/audit-ffi-unsafe.md) -- For tests: Note when unsafe is in test-only code paths - -**Example**: -```rust -// panic-attack: accepted (legitimate JIT function pointer transmute) -// SAFETY: Function pointer from verified Cranelift JIT compilation -unsafe { - let f: fn() -> i64 = std::mem::transmute(ptr); - f() -} -``` - -### 2. FFI Detection in Build Files -**Problem**: Build system files trigger FFI warnings incorrectly. - -**Solutions**: -- Add suppression comments for build.zig and similar files -- Distinguish between actual FFI calls and documentation -- Improve panic-attack's Zig analyzer to recognize build system patterns - -**Example**: -```zig -// panic-attack: accepted (build system file, no actual FFI calls) -// This file only imports Zig standard library, not C headers -const std = @import("std"); -``` - -### 3. Test Data vs Real Usage -**Problem**: Test files with HTTP URLs or other "unsafe" patterns get flagged. - -**Solutions**: -- Add context comments explaining test purpose -- Use clearly marked test data sections -- Consider test-specific suppression patterns - -**Example**: -```rust -// Test data section - these URLs are never actually requested -// panic-attack: accepted (test data for capability-gated backend) -const TEST_URLS = [ - "http://example.com", // Tests HTTP backend rejection - "https://secure.example.com", // Tests HTTPS handling -]; -``` - -### 4. Comment-Based False Positives -**Problem**: Comments mentioning "unsafe" trigger warnings. - -**Solutions**: -- Improve panic-attack to distinguish code from comments -- Use more specific terminology in documentation -- Add suppression when documenting security aspects - -**Example**: -```rust -/// This test verifies the absence of unsafe code. -/// The word "unsafe" in this comment refers to Rust's unsafe{} construct, -/// not to any actual unsafe operations in this test. -// panic-attack: accepted (documenting security aspect, no actual unsafe code) -#[test] -fn test_no_unsafe_code() { - // Test implementation -} -``` - -## Roadmap for Addressing Remaining Findings - -### Phase 1: Documentation and Suppression (COMPLETE) -- ✅ Add suppression comments to legitimate unsafe code -- ✅ Document false positives -- ✅ Create this guidance document - -### Phase 2: Code Quality Improvements (NEXT) -- [ ] Replace unwrap/expect with proper error handling in 5 key files -- [ ] Convert TODO/FIXME markers to GitHub issues (15 markers) -- [ ] Improve panic-attack's comment analysis to reduce false positives - -### Phase 3: Systematic Refactoring (FUTURE) -- [ ] Eliminate unwrap/expect from production code paths -- [ ] Replace remaining TODO/FIXME with proper documentation -- [ ] Enhance panic-attack's context awareness for test files - -### Phase 4: Prevention (CONTINUOUS) -- [ ] Add CI check for new unwrap/expect in production code -- [ ] Require suppression comments for all unsafe blocks -- [ ] Regular audit of TODO/FIXME markers - -## Checking Progress - -To verify the current state: -```bash -cd /var/mnt/eclipse/repos/007 -panic-attack assail . -``` - -Expected output should show: -- UnsafeCode: 5 (mostly addressed with comments) -- UnsafeFFI: 1 (false positive, documented) -- InsecureProtocol: 1 (addressed with comment) -- PanicPath: 28 (documented for future refactoring) -- UncheckedError: 15 (documented for future cleanup) - -Total: ~50 findings (mostly documented and planned for resolution) - -## Maintaining This Document - -Update this file when: -1. New categories of false positives are discovered -2. Existing false positives are properly addressed -3. Panic-attacker's analysis improves to reduce false positives -4. Major refactoring completes that resolves documented issues - -Last updated: 2026-04-15 -Status: Phase 1 complete, Phase 2 in progress \ No newline at end of file diff --git a/docs/HYPATIA-RULE-UPDATES.md b/docs/HYPATIA-RULE-UPDATES.adoc similarity index 62% rename from docs/HYPATIA-RULE-UPDATES.md rename to docs/HYPATIA-RULE-UPDATES.adoc index 4e0ca8c..00ab82a 100644 --- a/docs/HYPATIA-RULE-UPDATES.md +++ b/docs/HYPATIA-RULE-UPDATES.adoc @@ -1,28 +1,28 @@ - - -# Hypatia Rule Updates for 007 Integration +== Hypatia Rule Updates for 007 Integration -## Purpose +=== Purpose -This document specifies the Hypatia rule updates needed to properly handle test vs production context and enable automatic remediation across the gitbot fleet. +This document specifies the Hypatia rule updates needed to properly +handle test vs production context and enable automatic remediation +across the gitbot fleet. -## Current State +=== Current State -### 007 Repository Analysis (2026-04-15) +==== 007 Repository Analysis (2026-04-15) -**Total Findings**: 50 weak points -- PanicPath: 28 findings (unwrap/expect calls) -- UncheckedError: 15 findings (TODO/FIXME/HACK markers) -- UnsafeCode: 5 findings (mostly addressed) -- UnsafeFFI: 1 finding (false positive) -- InsecureProtocol: 1 finding (test data) +*Total Findings*: 50 weak points - PanicPath: 28 findings (unwrap/expect +calls) - UncheckedError: 15 findings (TODO/FIXME/HACK markers) - +UnsafeCode: 5 findings (mostly addressed) - UnsafeFFI: 1 finding (false +positive) - InsecureProtocol: 1 finding (test data) -## Required Rule Updates +=== Required Rule Updates -### 1. PanicPath Rules (PA024) +==== 1. PanicPath Rules (PA024) -#### Current Rule -```json +===== Current Rule + +[source,json] +---- { "rule_id": "PA024", "category": "PanicPath", @@ -30,12 +30,14 @@ This document specifies the Hypatia rule updates needed to properly handle test "severity": "medium", "message": "Avoid .expect() in production code" } -``` +---- + +===== Updated Rules -#### Updated Rules +*PA024-PROD* (Production Code - Strict) -**PA024-PROD** (Production Code - Strict) -```json +[source,json] +---- { "rule_id": "PA024-PROD", "category": "PanicPath", @@ -55,10 +57,12 @@ This document specifies the Hypatia rule updates needed to properly handle test } ] } -``` +---- + +*PA024-TEST* (Test Code - Relaxed) -**PA024-TEST** (Test Code - Relaxed) -```json +[source,json] +---- { "rule_id": "PA024-TEST", "category": "PanicPath", @@ -73,10 +77,12 @@ This document specifies the Hypatia rule updates needed to properly handle test } ] } -``` +---- -**PA024-DOC** (Documented Critical Invariants) -```json +*PA024-DOC* (Documented Critical Invariants) + +[source,json] +---- { "rule_id": "PA024-DOC", "category": "PanicPath", @@ -91,12 +97,14 @@ This document specifies the Hypatia rule updates needed to properly handle test } ] } -``` +---- + +==== 2. UncheckedError Rules (UC001) -### 2. UncheckedError Rules (UC001) +*UC001-TODO* (TODO Markers) -**UC001-TODO** (TODO Markers) -```json +[source,json] +---- { "rule_id": "UC001-TODO", "category": "UncheckedError", @@ -109,10 +117,12 @@ This document specifies the Hypatia rule updates needed to properly handle test "confidence": "medium" } } -``` +---- + +*UC001-FIXME* (FIXME Markers) -**UC001-FIXME** (FIXME Markers) -```json +[source,json] +---- { "rule_id": "UC001-FIXME", "category": "UncheckedError", @@ -125,10 +135,12 @@ This document specifies the Hypatia rule updates needed to properly handle test "confidence": "medium" } } -``` +---- -**UC001-HACK** (HACK Markers) -```json +*UC001-HACK* (HACK Markers) + +[source,json] +---- { "rule_id": "UC001-HACK", "category": "UncheckedError", @@ -141,12 +153,14 @@ This document specifies the Hypatia rule updates needed to properly handle test "confidence": "medium" } } -``` +---- + +==== 3. Context Detection Rules -### 3. Context Detection Rules +*CTX001-TEST* (Test Module Detection) -**CTX001-TEST** (Test Module Detection) -```json +[source,json] +---- { "rule_id": "CTX001-TEST", "category": "Context", @@ -155,10 +169,12 @@ This document specifies the Hypatia rule updates needed to properly handle test "message": "Test module detected - relaxed rules apply", "context": "test" } -``` +---- + +*CTX001-PROD* (Production Module Detection) -**CTX001-PROD** (Production Module Detection) -```json +[source,json] +---- { "rule_id": "CTX001-PROD", "category": "Context", @@ -167,13 +183,14 @@ This document specifies the Hypatia rule updates needed to properly handle test "message": "Production module detected - strict rules apply", "context": "production" } -``` +---- -## GitBot Fleet Configuration +=== GitBot Fleet Configuration -### Detection Workflow +==== Detection Workflow -```mermaid +[source,mermaid] +---- graph TD A[New Commit] --> B[Run Hypatia Scan] B --> C[Detect Context] @@ -188,11 +205,12 @@ graph TD J -->|No| L[❌ Block] K --> M[Suggest Fix] L --> N[Require Documentation] -``` +---- -### Configuration File +==== Configuration File -```yaml +[source,yaml] +---- # .hypatia/config.yml rules: - id: PA024-PROD @@ -231,36 +249,40 @@ autofix: enabled: true confidence_threshold: medium require_review: true -``` +---- -## Implementation Plan +=== Implementation Plan -### Phase 1: Rule Updates (2 weeks) +==== Phase 1: Rule Updates (2 weeks) -1. **Update Hypatia scanner** with new rules -2. **Test on 007 repository** to verify detection -3. **Adjust patterns** based on false positives -4. **Document rules** in Hypatia repository +[arabic] +. *Update Hypatia scanner* with new rules +. *Test on 007 repository* to verify detection +. *Adjust patterns* based on false positives +. *Document rules* in Hypatia repository -### Phase 2: GitBot Integration (2 weeks) +==== Phase 2: GitBot Integration (2 weeks) -1. **Configure gitbot fleet** with updated rules -2. **Set up CI checks** in GitHub Actions -3. **Add pre-commit hooks** for local development -4. **Create dashboard** for tracking findings +[arabic] +. *Configure gitbot fleet* with updated rules +. *Set up CI checks* in GitHub Actions +. *Add pre-commit hooks* for local development +. *Create dashboard* for tracking findings -### Phase 3: Rollout (2 weeks) +==== Phase 3: Rollout (2 weeks) -1. **Pilot on 007 repository** -2. **Monitor false positives** -3. **Adjust rules** as needed -4. **Expand to other repositories** +[arabic] +. *Pilot on 007 repository* +. *Monitor false positives* +. *Adjust rules* as needed +. *Expand to other repositories* -## Verification +=== Verification -### Test Commands +==== Test Commands -```bash +[source,bash] +---- # Scan with Hypatia hypatia scan --repo /var/mnt/eclipse/repos/007 --format json @@ -269,11 +291,12 @@ hypatia scan --rule PA024-PROD --repo /var/mnt/eclipse/repos/007 # Apply autofixes hypatia fix --rule PA024-PROD --repo /var/mnt/eclipse/repos/007 --dry-run -``` +---- -### Expected Output +==== Expected Output -```json +[source,json] +---- { "findings": [ { @@ -307,58 +330,52 @@ hypatia fix --rule PA024-PROD --repo /var/mnt/eclipse/repos/007 --dry-run "UC001-HACK": 1 } } -``` +---- + +=== Documentation Updates + +==== 1. Hypatia Repository + +Update `+hypatia/docs/rules.md+` with: - New rule descriptions - Context +detection explanation - Autofix examples - Configuration guide -## Documentation Updates +==== 2. 007 Repository -### 1. Hypatia Repository +Update `+007/docs/CONTRIBUTING.md+` with: - Hypatia scan requirements - +Autofix workflow - Context separation rules - Suppression comment guide -Update `hypatia/docs/rules.md` with: -- New rule descriptions -- Context detection explanation -- Autofix examples -- Configuration guide +==== 3. Panic-Attacker Repository -### 2. 007 Repository +Update `+panic-attack/docs/hypatia-integration.md+` with: - Rule mapping +guide - Context detection details - GitBot configuration - +Troubleshooting -Update `007/docs/CONTRIBUTING.md` with: -- Hypatia scan requirements -- Autofix workflow -- Context separation rules -- Suppression comment guide +=== Success Criteria -### 3. Panic-Attacker Repository +==== Phase 1 Complete -Update `panic-attack/docs/hypatia-integration.md` with: -- Rule mapping guide -- Context detection details -- GitBot configuration -- Troubleshooting +* All rules defined and tested +* False positive rate < 5% +* Autofix confidence > 80% -## Success Criteria +==== Phase 2 Complete -### Phase 1 Complete -- All rules defined and tested -- False positive rate < 5% -- Autofix confidence > 80% +* GitBot fleet configured +* CI checks passing +* Pre-commit hooks working +* Dashboard operational -### Phase 2 Complete -- GitBot fleet configured -- CI checks passing -- Pre-commit hooks working -- Dashboard operational +==== Phase 3 Complete -### Phase 3 Complete -- 007 repository compliant -- PanicPath count reduced by 70% -- UncheckedError count reduced by 60% -- No regression in code quality +* 007 repository compliant +* PanicPath count reduced by 70% +* UncheckedError count reduced by 60% +* No regression in code quality -## Maintainers +=== Maintainers -**Owners**: Hypatia Team + DevX Team -**Review**: Weekly sync with Compiler Team -**Target**: Phase 1 complete by 2026-05-01 +*Owners*: Hypatia Team + DevX Team *Review*: Weekly sync with Compiler +Team *Target*: Phase 1 complete by 2026-05-01 -**Last Updated**: 2026-04-15 -**Status**: ✅ Rules defined, 📅 Implementation in progress \ No newline at end of file +*Last Updated*: 2026-04-15 *Status*: ✅ Rules defined, 📅 Implementation +in progress diff --git a/docs/adr/0001-chapel-distributed-scanner.adoc b/docs/adr/0001-chapel-distributed-scanner.adoc new file mode 100644 index 0000000..5f0a84e --- /dev/null +++ b/docs/adr/0001-chapel-distributed-scanner.adoc @@ -0,0 +1,156 @@ +== ADR 0001 — Chapel as a detachable distributed-scanner harness + +* *Status:* Accepted (Wave 1 landed via PR +`+feat/chapel-ci-strict-gates+`) +* *Date:* 2026-05-30 +* *Refs:* https://github.com/hyperpolymath/panic-attack/issues/33[issue +#33] (VeriSimDB hexad persistence S1–S3), `+chapel/README.md+`, +`+.github/workflows/chapel-ci.yml+` + +=== Context + +`+panic-attack+` ships three deployment modes (see +`+.claude/CLAUDE.md+`): + +[arabic] +. *Standalone* — single binary, zero dependencies, USB-stick-portable. +. *Panicbot* — automated JSON scanning in CI (gitbot-fleet, GH Actions). +. *Mass-panic* — org-scale batch scanning across many repos. + +Mode 3 has two layers: + +* `+src/assemblyline.rs+` — rayon-parallel single-machine batch scanner. +* `+chapel/+` — multi-machine fan-out built on Chapel locales, spawning +the `+panic-attack+` Rust binary on each worker via `+Subprocess+`. + +Until this PR, the Chapel layer was prose-only: 2354 LOC of +well-structured code with no CI, no smoke test, and no contract +enforcement against the Rust binary it shells out to. Every Subprocess +call assumed the Rust side’s flag set matched what +`+MassPanic.chpl::buildCommandArgs+` emits; nothing detected silent +drift. The data path from `+RepoResult+` → `+SystemImage+` → JSON had +four silent losses (`+path+`, `+highCount+`, `+error+`, +`+categoryBreakdown+` all populated but never serialised by +`+Imaging.chpl::writeNodeJson+`). The README claimed a `+--resume+` / +`+--scheduler=static+` interaction that was implemented as a warning +ignored at runtime. + +=== Decision + +==== Detachability is the load-bearing principle + +The Chapel layer is *strictly outboard*. Removing `+chapel/+` from the +repo must leave the Rust build green and the single-machine USB-stick +experience intact. Therefore: + +* No Cargo dependency on Chapel. +* No `+src/+` references to `+chapel/+` paths. +* The Rust binary gains no Chapel-specific flags; the new +`+describe-contract+` subcommand is framed as a *general orchestrator +capability* (useful to Nextflow / Airflow / Slurm / shell scripts / any +future driver), not a Chapel bridge. +* Path triggers on `+.github/workflows/chapel-ci.yml+` are scoped to +`+chapel/**+` + the Rust contract-defining files (`+src/main.rs+`, +`+src/types.rs+`, `+Cargo.toml+`, `+Cargo.lock+`). A pure-Rust PR that +doesn’t touch these paths never wakes Chapel CI. + +==== CI gates land six strict jobs + +No `+continue-on-error+` anywhere. Failure on any of the six fails the +PR: + +[arabic] +. `+chapel-parse-check+` — `+chpl --parse-only+` on every module + +smoke. +. `+chapel-build+` — `+just chapel-build-ci+` (toolbox-free, .deb +install). +. `+chapel-smoke+` — `+chapel/smoke/two_repo_smoke+` exercises the +`+RepoResult → SystemImage → JSON+` data flow + asserts the four +silent-loss fields appear. +. `+chapel-e2e+` — `+mass-panic --numLocales=1+` against a synthetic +2-repo manifest. (True `+-nl 2+` requires `+CHPL_COMM=gasnet+`; the +stock .deb ships `+CHPL_COMM=none+`. Tracked for Wave 2.) +. `+chapel-cli-contract+` — runs `+panic-attack describe-contract+` and +asserts the live JSON matches `+chapel/tests/expected_contract.json+`. +. `+chapel-rust-diff+` — rayon assemblyline vs Chapel single-locale on +the same synthetic corpus; aggregates (`+total_weak_points+`, +`+total_critical+`, `+repos_scanned+`) must agree. + +==== Bug fixes that were in scope here + +* `+Imaging.chpl::writeNodeJson+` now serialises `+path+`, +`+high_count+`, `+error+`, `+category_breakdown+` (with JSON-escape) — +four fields that were populated in memory but dropped from the +SystemImage JSON. +* `+MassPanic.chpl::selectAndAnnounceScheduler+` now hard-fails when +`+--scheduler=static --resume+` is combined (previously: warning then +proceeded silently). +* `+MassPanic.chpl::buildCommandArgs+` adjudicate mode now passes +`+--quiet+` for consistency with assail / assault / ambush (was the only +mode that didn’t, risking banner-bleed into Chapel’s JSON parser). +* `+journalEscape+` renamed local `+out+` → `+buf+` — Chapel 2.8.0 +parses `+out+` as the intent keyword more strictly than older versions. + +==== Bug fixes deferred (Wave 2 trackers) + +* *Subprocess hang kill path* — `+panic-attack --timeout=N+` is +currently the only safeguard; Chapel `+sub.wait()+` blocks indefinitely +if the subprocess ignores the timeout. Needs a Chapel-side grace-period +loop + SIGKILL. +* *NFS journal lock semantics* — the journal directory assumes POSIX +`+flock+` works; NFSv3 violates this. Needs a startup probe + warning. +* *True multi-locale CI* — requires installing Chapel built with +`+CHPL_COMM=gasnet+`, which the stock `+.deb+` doesn’t ship. Needs +either a multilocale Chapel build step or a maintained +`+chapel-multilocale+` package on the runner. +* *`+describe-contract+` SHA-pin for the .deb download* — workflow +currently trusts the HTTPS endpoint at `+chapel-lang/chapel+` releases. +Add SHA256 verification before promoting Chapel to a production gate. +* *Real BoJ-estate scheduler benchmark* — README claims queue is ~5–15% +slower; this is theoretical. A 350-repo, 2-locale measurement is Wave 2 +work. +* *`+buildCommandArgs+` callsite consolidation* — `+MassPanic.chpl+` has +five sites that spawn the Rust binary; one (`+buildCommandArgs+`) is the +canonical builder. Three other sites (`+runAttackPass+`, +`+runAdjudicatePass+`, `+computeFingerprint+`) bypass it. Consolidating +to a single helper is a refactor that doesn’t belong in the CI PR. + +=== Relationship to issue #33 (VeriSimDB hexad persistence S1–S3) + +Chapel’s `+Temporal.chpl::writeTemporalHexad+` is the *producer* for +mass-panic temporal snapshots; the Rust-side hexad reader in +`+src/storage/mod.rs+` is the *consumer*. Issue #33’s S1/S2/S3 stages +landed in the Rust side. This PR makes the producer side CI-enforced: +any change to either the Chapel writer or the Rust hexad schema that +breaks the contract is caught by `+chapel-rust-diff+` (aggregate parity) +or `+chapel-cli-contract+` (CLI shape). The four silent-loss fixes +ensure the producer no longer drops fields the hexad would otherwise +have persisted. + +=== Consequences + +* `+chapel/+` is now a load-bearing CI tree. New Chapel module additions +must compile under `+chpl --parse-only+` and pass the smoke (a one-line +assertion can be added per new field via +`+chapel/smoke/two_repo_smoke.chpl+`). +* Any clap flag rename in `+src/main.rs+` that affects the five +Chapel-used modes (assail, assault, ambush, attack, adjudicate) will +fail `+chapel-cli-contract+`. The fix is to update both clap and +`+chapel/tests/expected_contract.json+` in the same PR. +* Pure-Rust PRs that don’t touch the trigger paths skip chapel-ci +entirely; Chapel CI failure cannot block a Rust-only release. +* Wave 2 enables real-cluster validation (`+-nl 16++` on actual nodes). + +=== Alternatives considered + +* *Promote Chapel to a Rust dependency* — rejected. Would break +detachability and the USB-stick experience. +* *Merge `+assemblyline.rs+` into Chapel* — rejected. Rayon is the right +tool for single-machine, Chapel for cross-machine. They are not +redundant. +* *Use clap’s `+CommandFactory+` reflection to auto-generate the +contract fixture* — adopted for the `+describe-contract+` handler itself +(auto-syncs with clap). Rejected for the fixture +(`+expected_contract.json+`) because the fixture defines what Chapel +_requires_, not what Rust currently _offers_; keeping it static +documents the contract surface Chapel depends on. diff --git a/docs/adr/0001-chapel-distributed-scanner.md b/docs/adr/0001-chapel-distributed-scanner.md deleted file mode 100644 index 30f31af..0000000 --- a/docs/adr/0001-chapel-distributed-scanner.md +++ /dev/null @@ -1,147 +0,0 @@ - - - -# ADR 0001 — Chapel as a detachable distributed-scanner harness - -* **Status:** Accepted (Wave 1 landed via PR `feat/chapel-ci-strict-gates`) -* **Date:** 2026-05-30 -* **Refs:** [issue #33](https://github.com/hyperpolymath/panic-attack/issues/33) (VeriSimDB hexad persistence S1–S3), `chapel/README.md`, `.github/workflows/chapel-ci.yml` - -## Context - -`panic-attack` ships three deployment modes (see `.claude/CLAUDE.md`): - -1. **Standalone** — single binary, zero dependencies, USB-stick-portable. -2. **Panicbot** — automated JSON scanning in CI (gitbot-fleet, GH Actions). -3. **Mass-panic** — org-scale batch scanning across many repos. - -Mode 3 has two layers: - -* `src/assemblyline.rs` — rayon-parallel single-machine batch scanner. -* `chapel/` — multi-machine fan-out built on Chapel locales, spawning the - `panic-attack` Rust binary on each worker via `Subprocess`. - -Until this PR, the Chapel layer was prose-only: 2354 LOC of well-structured -code with no CI, no smoke test, and no contract enforcement against the -Rust binary it shells out to. Every Subprocess call assumed the Rust -side's flag set matched what `MassPanic.chpl::buildCommandArgs` emits; -nothing detected silent drift. The data path from `RepoResult` → -`SystemImage` → JSON had four silent losses (`path`, `highCount`, -`error`, `categoryBreakdown` all populated but never serialised by -`Imaging.chpl::writeNodeJson`). The README claimed a `--resume` / -`--scheduler=static` interaction that was implemented as a warning -ignored at runtime. - -## Decision - -### Detachability is the load-bearing principle - -The Chapel layer is **strictly outboard**. Removing `chapel/` from the -repo must leave the Rust build green and the single-machine USB-stick -experience intact. Therefore: - -* No Cargo dependency on Chapel. -* No `src/` references to `chapel/` paths. -* The Rust binary gains no Chapel-specific flags; the new - `describe-contract` subcommand is framed as a **general orchestrator - capability** (useful to Nextflow / Airflow / Slurm / shell scripts / - any future driver), not a Chapel bridge. -* Path triggers on `.github/workflows/chapel-ci.yml` are scoped to - `chapel/**` + the Rust contract-defining files (`src/main.rs`, - `src/types.rs`, `Cargo.toml`, `Cargo.lock`). A pure-Rust PR that - doesn't touch these paths never wakes Chapel CI. - -### CI gates land six strict jobs - -No `continue-on-error` anywhere. Failure on any of the six fails the PR: - -1. `chapel-parse-check` — `chpl --parse-only` on every module + smoke. -2. `chapel-build` — `just chapel-build-ci` (toolbox-free, .deb install). -3. `chapel-smoke` — `chapel/smoke/two_repo_smoke` exercises the - `RepoResult → SystemImage → JSON` data flow + asserts the four - silent-loss fields appear. -4. `chapel-e2e` — `mass-panic --numLocales=1` against a synthetic - 2-repo manifest. (True `-nl 2` requires `CHPL_COMM=gasnet`; the - stock .deb ships `CHPL_COMM=none`. Tracked for Wave 2.) -5. `chapel-cli-contract` — runs `panic-attack describe-contract` and - asserts the live JSON matches `chapel/tests/expected_contract.json`. -6. `chapel-rust-diff` — rayon assemblyline vs Chapel single-locale on - the same synthetic corpus; aggregates (`total_weak_points`, - `total_critical`, `repos_scanned`) must agree. - -### Bug fixes that were in scope here - -* `Imaging.chpl::writeNodeJson` now serialises `path`, `high_count`, - `error`, `category_breakdown` (with JSON-escape) — four fields that - were populated in memory but dropped from the SystemImage JSON. -* `MassPanic.chpl::selectAndAnnounceScheduler` now hard-fails when - `--scheduler=static --resume` is combined (previously: warning then - proceeded silently). -* `MassPanic.chpl::buildCommandArgs` adjudicate mode now passes `--quiet` - for consistency with assail / assault / ambush (was the only mode - that didn't, risking banner-bleed into Chapel's JSON parser). -* `journalEscape` renamed local `out` → `buf` — Chapel 2.8.0 parses - `out` as the intent keyword more strictly than older versions. - -### Bug fixes deferred (Wave 2 trackers) - -* **Subprocess hang kill path** — `panic-attack --timeout=N` is currently - the only safeguard; Chapel `sub.wait()` blocks indefinitely if the - subprocess ignores the timeout. Needs a Chapel-side grace-period - loop + SIGKILL. -* **NFS journal lock semantics** — the journal directory assumes POSIX - `flock` works; NFSv3 violates this. Needs a startup probe + warning. -* **True multi-locale CI** — requires installing Chapel built with - `CHPL_COMM=gasnet`, which the stock `.deb` doesn't ship. Needs either - a multilocale Chapel build step or a maintained `chapel-multilocale` - package on the runner. -* **`describe-contract` SHA-pin for the .deb download** — workflow - currently trusts the HTTPS endpoint at `chapel-lang/chapel` releases. - Add SHA256 verification before promoting Chapel to a production gate. -* **Real BoJ-estate scheduler benchmark** — README claims queue is - ~5–15% slower; this is theoretical. A 350-repo, 2-locale measurement - is Wave 2 work. -* **`buildCommandArgs` callsite consolidation** — `MassPanic.chpl` has - five sites that spawn the Rust binary; one (`buildCommandArgs`) is - the canonical builder. Three other sites (`runAttackPass`, - `runAdjudicatePass`, `computeFingerprint`) bypass it. Consolidating - to a single helper is a refactor that doesn't belong in the CI PR. - -## Relationship to issue #33 (VeriSimDB hexad persistence S1–S3) - -Chapel's `Temporal.chpl::writeTemporalHexad` is the **producer** for -mass-panic temporal snapshots; the Rust-side hexad reader in -`src/storage/mod.rs` is the **consumer**. Issue #33's S1/S2/S3 stages -landed in the Rust side. This PR makes the producer side CI-enforced: -any change to either the Chapel writer or the Rust hexad schema that -breaks the contract is caught by `chapel-rust-diff` (aggregate parity) -or `chapel-cli-contract` (CLI shape). The four silent-loss fixes -ensure the producer no longer drops fields the hexad would otherwise -have persisted. - -## Consequences - -* `chapel/` is now a load-bearing CI tree. New Chapel module additions - must compile under `chpl --parse-only` and pass the smoke (a one-line - assertion can be added per new field via `chapel/smoke/two_repo_smoke.chpl`). -* Any clap flag rename in `src/main.rs` that affects the five Chapel-used - modes (assail, assault, ambush, attack, adjudicate) will fail - `chapel-cli-contract`. The fix is to update both clap and - `chapel/tests/expected_contract.json` in the same PR. -* Pure-Rust PRs that don't touch the trigger paths skip chapel-ci entirely; - Chapel CI failure cannot block a Rust-only release. -* Wave 2 enables real-cluster validation (`-nl 16+` on actual nodes). - -## Alternatives considered - -* **Promote Chapel to a Rust dependency** — rejected. Would break - detachability and the USB-stick experience. -* **Merge `assemblyline.rs` into Chapel** — rejected. Rayon is the - right tool for single-machine, Chapel for cross-machine. They are - not redundant. -* **Use clap's `CommandFactory` reflection to auto-generate the contract - fixture** — adopted for the `describe-contract` handler itself - (auto-syncs with clap). Rejected for the fixture (`expected_contract.json`) - because the fixture defines what Chapel *requires*, not what Rust - currently *offers*; keeping it static documents the contract surface - Chapel depends on. diff --git a/docs/adr/0001-chapel-issue-33-comment.adoc b/docs/adr/0001-chapel-issue-33-comment.adoc new file mode 100644 index 0000000..6cbdd51 --- /dev/null +++ b/docs/adr/0001-chapel-issue-33-comment.adoc @@ -0,0 +1,52 @@ +== Cross-link: Chapel-side hexad producer is now CI-gated (#33 / PR `+feat/chapel-ci-strict-gates+`) + +`+Temporal.chpl::writeTemporalHexad+` is the Chapel-side producer for +mass-panic temporal snapshots, which feed the VeriSimDB hexad readers +this issue tracks (S1 per-finding, S2 campaign-state, S3 query). + +PR `+feat/chapel-ci-strict-gates+` lands six strict CI gates on the +`+chapel/+` tree and the Chapel↔Rust contract: + +[width="100%",cols="25%,75%",options="header",] +|=== +|Gate |What it catches +|`+chapel-parse-check+` |Chapel syntax regressions in any of 4 modules + +smoke + +|`+chapel-build+` |Cross-module build break (stock ubuntu .deb, no +toolbox) + +|`+chapel-smoke+` |`+RepoResult → SystemImage → JSON+` data-flow +regressions + +|`+chapel-e2e+` |mass-panic full pipeline end-to-end (single-locale) + +|`+chapel-cli-contract+` |Rust clap drift breaking Chapel’s argv shape + +|`+chapel-rust-diff+` |Aggregate divergence between rayon and Chapel +paths +|=== + +The four silent-loss fixes (`+path+`, `+high_count+`, `+error+`, +`+category_breakdown+` previously dropped by `+writeNodeJson+`) mean the +producer side now preserves every ImageNode field the hexad consumer can +persist. Mapping of Chapel writers → hexad facets: + +* `+provenance+` ← `+Temporal.chpl+` (tool, version, locales, +scan_surface) +* `+temporal+` ← `+Temporal.chpl+` (timestamp, sequence_number, label) +* `+semantic+` ← `+Imaging.chpl+` (global_health, global_risk, totals) +* `+structural+` ← `+Imaging.chpl+` (totalFiles, totalLines, +riskDistribution) +* `+document+` ← `+Imaging.chpl::writeSystemImageJson+` (full +SystemImage) + +Out of scope here, tracked for Wave 2: + +* True multi-locale CI (`+CHPL_COMM=gasnet+` install). +* Subprocess kill-path on hang. +* NFS journal lock semantics. +* BoJ-estate scheduler benchmark to back the "`~5–15% slower`" claim. + +See `+docs/adr/0001-chapel-distributed-scanner.md+` for the full rollout +decision record. diff --git a/docs/adr/0001-chapel-issue-33-comment.md b/docs/adr/0001-chapel-issue-33-comment.md deleted file mode 100644 index 8dde677..0000000 --- a/docs/adr/0001-chapel-issue-33-comment.md +++ /dev/null @@ -1,45 +0,0 @@ - - - - -# Cross-link: Chapel-side hexad producer is now CI-gated (#33 / PR `feat/chapel-ci-strict-gates`) - -`Temporal.chpl::writeTemporalHexad` is the Chapel-side producer for -mass-panic temporal snapshots, which feed the VeriSimDB hexad readers -this issue tracks (S1 per-finding, S2 campaign-state, S3 query). - -PR `feat/chapel-ci-strict-gates` lands six strict CI gates on the -`chapel/` tree and the Chapel↔Rust contract: - -| Gate | What it catches | -|------|------------------| -| `chapel-parse-check` | Chapel syntax regressions in any of 4 modules + smoke | -| `chapel-build` | Cross-module build break (stock ubuntu .deb, no toolbox) | -| `chapel-smoke` | `RepoResult → SystemImage → JSON` data-flow regressions | -| `chapel-e2e` | mass-panic full pipeline end-to-end (single-locale) | -| `chapel-cli-contract` | Rust clap drift breaking Chapel's argv shape | -| `chapel-rust-diff` | Aggregate divergence between rayon and Chapel paths | - -The four silent-loss fixes (`path`, `high_count`, `error`, -`category_breakdown` previously dropped by `writeNodeJson`) mean -the producer side now preserves every ImageNode field the hexad -consumer can persist. Mapping of Chapel writers → hexad facets: - -* `provenance` ← `Temporal.chpl` (tool, version, locales, scan_surface) -* `temporal` ← `Temporal.chpl` (timestamp, sequence_number, label) -* `semantic` ← `Imaging.chpl` (global_health, global_risk, totals) -* `structural` ← `Imaging.chpl` (totalFiles, totalLines, riskDistribution) -* `document` ← `Imaging.chpl::writeSystemImageJson` (full SystemImage) - -Out of scope here, tracked for Wave 2: - -* True multi-locale CI (`CHPL_COMM=gasnet` install). -* Subprocess kill-path on hang. -* NFS journal lock semantics. -* BoJ-estate scheduler benchmark to back the "~5–15% slower" claim. - -See `docs/adr/0001-chapel-distributed-scanner.md` for the full -rollout decision record. diff --git a/docs/ambush-timeline.adoc b/docs/ambush-timeline.adoc new file mode 100644 index 0000000..a191299 --- /dev/null +++ b/docs/ambush-timeline.adoc @@ -0,0 +1,186 @@ +== Ambush Timeline & Event-Chain Plan (DAW-style) + +This document captures the long-range design for a DAW-like timeline +model that drives `+panic-attack+` ambush runs. It is intentionally +staged so the tool stays simple while enabling deeper event-chain +modelling (for panll integration). + +=== Goals + +* Keep the default CLI simple (single command, predictable output). +* Add a DAW-style timeline that schedules stressors by axis over time. +* Model event chains with conditions and Theory of Constraints (ToC) +controls. +* Export/import models for panll without forking core logic. +* Work cross-platform (Linux/macOS/BSD/Windows, RISC-V, Minix) via +fallback stressors and optional OS-specific backends. + +=== Non-Goals (for MVP) + +* No mandatory kernel integrations. +* No blocking dependency on privileged operations (cgroups, PF, WFP). +* No requirement to modify the target program. + +=== Terminology + +* *Axis*: stress dimension (cpu/memory/disk/network/concurrency/time). +* *Track*: an axis lane on the timeline. +* *Clip/Event*: a scheduled stressor with params + duration. +* *Automation*: condition-driven changes (thresholds, curves). +* *Event Chain*: causal graph of events and transitions. +* *Constraint*: the bottleneck (ToC) that governs overall scheduling. + +=== Phase 1 (MVP) — Timeline Scheduler + +*Deliverable:* `+panic-attack ambush --timeline timeline.yaml+` + +*Capabilities* - Run the target under ambient stressors (existing +ambush). - Timeline file schedules axis stressors with `+at+` + `+for+`. +- Events are independent; overlapping events run concurrently. - Output +is a standard assault report + timeline metadata. + +*Example YAML* + +[source,yaml] +---- +program: ./target/release/my-program +duration: 120s +tracks: + - axis: cpu + events: + - at: 0s + for: 30s + intensity: light + - at: 30s + for: 30s + intensity: heavy + - axis: memory + events: + - at: 10s + for: 40s + intensity: medium + - axis: disk + events: + - at: 60s + for: 20s + intensity: light +---- + +*CLI sketch* + +.... +panic-attack ambush ./my-program --timeline timeline.yaml +panic-attack ambush ./my-program --timeline timeline.yaml --source ./src +.... + +=== Phase 2 — Conditions & Event Chains + +*Capabilities* - Events may have conditions: - +`+start_when: { crashes >= 1 }+` - `+start_when: { cpu_load > 0.7 }+` - +Event chains allow `+eventA -> eventB+` dependencies. - Conditional +branching based on runtime signals. + +*Conceptual schema* + +[source,yaml] +---- +events: + - id: spike-1 + axis: cpu + at: 0s + for: 20s + intensity: heavy + - id: memory-followup + axis: memory + for: 30s + intensity: medium + start_when: + event: spike-1 + outcome: crash +---- + +=== Phase 3 — Theory of Constraints (ToC) + +*Capabilities* - Define a constraint axis (bottleneck). - Subordinate +other stressors when the constraint is saturated. - Apply ToC rules such +as: - "`Memory is constraint; throttle CPU when memory pressure > 80%.`" +- "`Disk is constraint; cap concurrency when IO latency spikes.`" + +*Sketch* + +[source,yaml] +---- +constraints: + bottleneck: memory + subordinate: + cpu: + if: { memory_pressure > 0.8 } + action: { intensity: light } +---- + +=== Phase 4 — Panll Integration + +*Direction A (export):* - Emit panll-compatible event chain + +constraints. - Use A2ML/Nickel to encode chain metadata alongside +assault reports. + +*Direction B (import):* - Accept panll models and execute them as +timelines. + +*Decision point:* choose which direction first (export or import). + +=== Data Model (Draft) + +Core structures: - `+Timeline+` - `+program+`, `+duration+`, `+tracks+` +- `+Track+` - `+axis+`, `+events+` - `+Event+` - `+id+`, `+at+`, +`+for+`, `+intensity+`, `+args+`, `+conditions+` - `+Constraint+` - +`+bottleneck+`, `+rules+` + +Serialization targets: JSON, YAML, Nickel. + +=== Execution Semantics (Draft) + +* Timeline time is wall-clock. +* Events can overlap (parallel stressors). +* Conditions are evaluated at a fixed cadence (e.g., 500ms). +* Failures are recorded in a timeline segment. +* Report preserves both "`global`" assault metrics and timeline segment +metrics. + +=== Platform Strategy (Cross-OS, RISC-V, Minix) + +*Portable baseline (always available):* - Internal stressors (CPU loops, +memory alloc, disk temp I/O, local TCP). + +*Optional OS backends (pluggable):* - Linux: cgroups + `+tc+`. - macOS: +`+taskpolicy+`, `+ulimit+`, `+pf/dummynet+`. - BSD: `+rctl+` + +`+pf/dummynet+`. - Windows: Job Objects + WFP. - Minix/RISC-V: baseline +stressors only unless platform hooks exist. + +Execution should autodetect available backend and fall back to portable +mode. + +=== Reporting & Storage + +* Attach timeline metadata to assault report. +* Export timeline + event chain summary to Nickel/A2ML. +* Preserve timeline-specific metrics for diffing. + +=== Implementation Checklist + +Phase 1: - [ ] Add timeline schema + parser. - [ ] Add +`+ambush --timeline+` CLI flag. - [ ] Run scheduled stressors +concurrently. - [ ] Capture per-event outputs in the report. + +Phase 2: - [ ] Add conditions (`+start_when+`, `+stop_when+`). - [ ] Add +event graph dependencies. + +Phase 3: - [ ] Add ToC engine (bottleneck + subordination). + +Phase 4: - [ ] Panll export/import adapters. + +''''' + +Status: Draft (2026-02-09). This document is the source of truth for the +timeline/event-chain direction and should be updated as implementation +lands. diff --git a/docs/ambush-timeline.md b/docs/ambush-timeline.md deleted file mode 100644 index a406540..0000000 --- a/docs/ambush-timeline.md +++ /dev/null @@ -1,194 +0,0 @@ - - - -# Ambush Timeline & Event-Chain Plan (DAW-style) - -This document captures the long-range design for a DAW-like timeline model that -drives `panic-attack` ambush runs. It is intentionally staged so the tool stays -simple while enabling deeper event-chain modelling (for panll integration). - -## Goals - -- Keep the default CLI simple (single command, predictable output). -- Add a DAW-style timeline that schedules stressors by axis over time. -- Model event chains with conditions and Theory of Constraints (ToC) controls. -- Export/import models for panll without forking core logic. -- Work cross-platform (Linux/macOS/BSD/Windows, RISC-V, Minix) via fallback - stressors and optional OS-specific backends. - -## Non-Goals (for MVP) - -- No mandatory kernel integrations. -- No blocking dependency on privileged operations (cgroups, PF, WFP). -- No requirement to modify the target program. - -## Terminology - -- **Axis**: stress dimension (cpu/memory/disk/network/concurrency/time). -- **Track**: an axis lane on the timeline. -- **Clip/Event**: a scheduled stressor with params + duration. -- **Automation**: condition-driven changes (thresholds, curves). -- **Event Chain**: causal graph of events and transitions. -- **Constraint**: the bottleneck (ToC) that governs overall scheduling. - -## Phase 1 (MVP) — Timeline Scheduler - -**Deliverable:** `panic-attack ambush --timeline timeline.yaml` - -**Capabilities** -- Run the target under ambient stressors (existing ambush). -- Timeline file schedules axis stressors with `at` + `for`. -- Events are independent; overlapping events run concurrently. -- Output is a standard assault report + timeline metadata. - -**Example YAML** -```yaml -program: ./target/release/my-program -duration: 120s -tracks: - - axis: cpu - events: - - at: 0s - for: 30s - intensity: light - - at: 30s - for: 30s - intensity: heavy - - axis: memory - events: - - at: 10s - for: 40s - intensity: medium - - axis: disk - events: - - at: 60s - for: 20s - intensity: light -``` - -**CLI sketch** -``` -panic-attack ambush ./my-program --timeline timeline.yaml -panic-attack ambush ./my-program --timeline timeline.yaml --source ./src -``` - -## Phase 2 — Conditions & Event Chains - -**Capabilities** -- Events may have conditions: - - `start_when: { crashes >= 1 }` - - `start_when: { cpu_load > 0.7 }` -- Event chains allow `eventA -> eventB` dependencies. -- Conditional branching based on runtime signals. - -**Conceptual schema** -```yaml -events: - - id: spike-1 - axis: cpu - at: 0s - for: 20s - intensity: heavy - - id: memory-followup - axis: memory - for: 30s - intensity: medium - start_when: - event: spike-1 - outcome: crash -``` - -## Phase 3 — Theory of Constraints (ToC) - -**Capabilities** -- Define a constraint axis (bottleneck). -- Subordinate other stressors when the constraint is saturated. -- Apply ToC rules such as: - - "Memory is constraint; throttle CPU when memory pressure > 80%." - - "Disk is constraint; cap concurrency when IO latency spikes." - -**Sketch** -```yaml -constraints: - bottleneck: memory - subordinate: - cpu: - if: { memory_pressure > 0.8 } - action: { intensity: light } -``` - -## Phase 4 — Panll Integration - -**Direction A (export):** -- Emit panll-compatible event chain + constraints. -- Use A2ML/Nickel to encode chain metadata alongside assault reports. - -**Direction B (import):** -- Accept panll models and execute them as timelines. - -**Decision point:** choose which direction first (export or import). - -## Data Model (Draft) - -Core structures: -- `Timeline` - - `program`, `duration`, `tracks` -- `Track` - - `axis`, `events` -- `Event` - - `id`, `at`, `for`, `intensity`, `args`, `conditions` -- `Constraint` - - `bottleneck`, `rules` - -Serialization targets: JSON, YAML, Nickel. - -## Execution Semantics (Draft) - -- Timeline time is wall-clock. -- Events can overlap (parallel stressors). -- Conditions are evaluated at a fixed cadence (e.g., 500ms). -- Failures are recorded in a timeline segment. -- Report preserves both “global” assault metrics and timeline segment metrics. - -## Platform Strategy (Cross-OS, RISC-V, Minix) - -**Portable baseline (always available):** -- Internal stressors (CPU loops, memory alloc, disk temp I/O, local TCP). - -**Optional OS backends (pluggable):** -- Linux: cgroups + `tc`. -- macOS: `taskpolicy`, `ulimit`, `pf/dummynet`. -- BSD: `rctl` + `pf/dummynet`. -- Windows: Job Objects + WFP. -- Minix/RISC-V: baseline stressors only unless platform hooks exist. - -Execution should autodetect available backend and fall back to portable mode. - -## Reporting & Storage - -- Attach timeline metadata to assault report. -- Export timeline + event chain summary to Nickel/A2ML. -- Preserve timeline-specific metrics for diffing. - -## Implementation Checklist - -Phase 1: -- [ ] Add timeline schema + parser. -- [ ] Add `ambush --timeline` CLI flag. -- [ ] Run scheduled stressors concurrently. -- [ ] Capture per-event outputs in the report. - -Phase 2: -- [ ] Add conditions (`start_when`, `stop_when`). -- [ ] Add event graph dependencies. - -Phase 3: -- [ ] Add ToC engine (bottleneck + subordination). - -Phase 4: -- [ ] Panll export/import adapters. - ---- - -Status: Draft (2026-02-09). This document is the source of truth for the -timeline/event-chain direction and should be updated as implementation lands. diff --git a/docs/attack-profiles.md b/docs/attack-profiles.adoc similarity index 52% rename from docs/attack-profiles.md rename to docs/attack-profiles.adoc index 601a5c0..5d8ab91 100644 --- a/docs/attack-profiles.md +++ b/docs/attack-profiles.adoc @@ -1,24 +1,24 @@ - - -# Attack Profiles +== Attack Profiles -Attack profiles let you pass custom arguments to target programs during assaults. Profiles are -JSON or YAML and can supply common arguments, axis-specific arguments, and probe mode. +Attack profiles let you pass custom arguments to target programs during +assaults. Profiles are JSON or YAML and can supply common arguments, +axis-specific arguments, and probe mode. -Ambush runs also accept profiles. The arguments are forwarded to the target program while the -ambient stressors run in parallel. +Ambush runs also accept profiles. The arguments are forwarded to the +target program while the ambient stressors run in parallel. -## Schema +=== Schema -- `common_args`: list of arguments added to every attack invocation. -- `axes`: map of axis names to argument lists. -- `probe_mode`: `auto`, `always`, or `never`. +* `+common_args+`: list of arguments added to every attack invocation. +* `+axes+`: map of axis names to argument lists. +* `+probe_mode+`: `+auto+`, `+always+`, or `+never+`. -Axis keys: `cpu`, `memory`, `disk`, `network`, `concurrency`, `time`. +Axis keys: `+cpu+`, `+memory+`, `+disk+`, `+network+`, `+concurrency+`, +`+time+`. -## JSON example +=== JSON example -``` +.... { "common_args": ["--config", "cfg.toml"], "axes": { @@ -27,11 +27,11 @@ Axis keys: `cpu`, `memory`, `disk`, `network`, `concurrency`, `time`. }, "probe_mode": "always" } -``` +.... -## YAML example +=== YAML example -``` +.... common_args: - --config - cfg.toml @@ -43,13 +43,13 @@ axes: - --allocate-mb - "512" probe_mode: always -``` +.... -## CLI usage +=== CLI usage -``` +.... panic-attack assault ./my-program --profile profiles/attack-profile.example.json panic-attack assault ./my-program --arg --config --arg cfg.toml panic-attack assault ./my-program --axis-arg cpu=--iterations --axis-arg cpu=5000 panic-attack assault ./my-program --probe always -``` +.... diff --git a/docs/campaigns/2026-05-26.adoc b/docs/campaigns/2026-05-26.adoc new file mode 100644 index 0000000..3da0cd2 --- /dev/null +++ b/docs/campaigns/2026-05-26.adoc @@ -0,0 +1,350 @@ +Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +j.d.a.jewell@open.ac.uk –> + +== Estate sweep campaign — 2026-05-26 + +*Owner*: @hyperpolymath *Tracker*: +https://github.com/hyperpolymath/panic-attack/issues/32[hyperpolymath/panic-attack#32] +*Tool*: `+panic-attack+` v2.5.0 built 2026-05-26 *Scope*: 369-repo +estate at `+~/developer/repos/+` *Outcome*: 16 narrow PRs + 1 real-bug +fix PR + 35+ tracking issues + 3 upstream bug reports + +=== Method + +Two-session campaign across 5 work tracks: + +[arabic] +. *Track A — FFI / fixture classification PRs*: per-repo +`+audits/assail-classifications.a2ml+` + `+audits/audit-*.md+` writing a +narrow allow-list for legitimate `+unsafe+` / fixture-context findings. +Each PR documents both the rationale and the anti-gameability mechanism +(registry is a separate file from the source under scan; new unsafe +inside a classified root requires a companion entry + doc edit, both +visible in the diff). +. *Track B — real-bug remainder*: after Track A’s classifications +drained ~500 FFI-shaped findings, the genuine code-bug remainder was +small. One critical fix landed (`+svalinn+` JWT signature verification). +. *Track C — per-repo tracking issues*: 35+ GitHub issues, one per repo, +listing the Critical/High findings by category for human triage. +Excludes Track A and Track D-coverage categories. +. *Track D / Phase 5 — proof-aware*: ProofDrift findings in 3 proof +repos (`+echidna+`, `+tropical-resource-typing+`, `+standards+`) +classified as legitimate axioms or detector false positives. *Zero +findings required actual proof discharge.* +. *Track E — bridge CVE triage*: 24 per-repo CVE tracking issues from +`+panic-attack bridge triage+` (RustSec advisory DB + reachability +analysis) across 29 of 58 Rust repos with non-zero advisories. + +==== Scan pipeline + +Initial attempt used `+panic-attack assemblyline+` (batch-scan a +directory of repos) but stalled on a single 7-min repo with +`+--parallel+` enabled. Pivoted to *per-repo +`+panic-attack assail --headless+` with a 90s timeout* so no single repo +can block the campaign. 349 of 368 repos scanned cleanly; 19 skipped +(content-only, no source). Plus a nested-repo pass for 6 container +directories (`+a2ml+`, `+awesome-projects+`, `+idaptik+`, `+isers+`, +`+julia-libraries+`, `+k9+`) covering ~90 sub-repos. + +==== Findings shape (post-scan, before any classification PRs) + +[cols=",",options="header",] +|=== +|Severity bucket |Count +|Critical/High `+UnsafeCode+` / `+UnsafeFFI+` |497 +|Critical/High `+SupplyChain+` |398 +|Critical/High `+UnboundedAllocation+` |516 +|Critical/High `+DynamicCodeExecution+` |472 +|Critical/High `+HardcodedSecret+` |122 +|Critical/High `+CommandInjection+` |113 +|Critical/High `+UnsafeDeserialization+` |73 +|Critical/High `+UnsafeTypeCoercion+` |32 +|Critical/High `+CryptoMisuse+` |28 +|Critical/High `+ProofDrift+` |219 +|Other (Low/Medium) |2,591 +|Already-suppressed |961 +|Worktree-path artefacts (skipped) |40 +|*Actionable this campaign* |*~2,477* +|=== + +=== Outputs + +==== Pull requests (17 narrow PRs) + +Track A — FFI / fixture classifications: + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Repo |PR |Findings |Pattern +|`+svalinn+` |https://github.com/hyperpolymath/svalinn/pull/11[#11] |4 +|test-context-fixture (JWT decode in bench/tests) + +|`+proven+` |https://github.com/hyperpolymath/proven/pull/67[#67] |150 +|legitimate-FFI (bindings/, ffi/) + protocol-type-identifier + +binding-wrapper-naming + +|`+gossamer+` |https://github.com/hyperpolymath/gossamer/pull/54[#54] +|24 |Zig FFI (GTK WebKit) + +|`+docudactyl+` +|https://github.com/hyperpolymath/docudactyl/pull/20[#20] |15 |Zig FFI + +|`+proven-servers+` +|https://github.com/hyperpolymath/proven-servers/pull/11[#11] |10 +|bindings/rust FFI + +|`+aerie+` |https://github.com/hyperpolymath/aerie/pull/35[#35] |10 |Zig +FFI + +|`+stapeln+` |https://github.com/hyperpolymath/stapeln/pull/62[#62] |10 +|eBPF + Zig FFI + Ada↔liboqs + +|`+ambientops+` +|https://github.com/hyperpolymath/ambientops/pull/102[#102] |10 |syscall ++ cross-subproject FFI + +|`+valence-shell+` +|https://github.com/hyperpolymath/valence-shell/pull/32[#32] |8 |POSIX +shell job-control libc + Zig FFI + +|`+panll+` |https://github.com/hyperpolymath/panll/pull/47[#47] |6 +|Idris2 Zig FFI + src-gossamer OS-FFI + +|`+linguist+` |https://github.com/hyperpolymath/linguist/pull/3[#3] |13 +|sample-reference-fixture (PA001+PA022) + vendored PCRE + +|`+boj-server+` +|https://github.com/hyperpolymath/boj-server/pull/154[#154] |119 |117 +MCP cartridge_shim + 2 backend FFI (supersedes #153) + +|`+idaptik+` |https://github.com/hyperpolymath/idaptik/pull/98[#98] |12 +|in-game password fixtures (game-content) +|=== + +Track D / Phase 5 — proof-aware: + +[width="100%",cols="25%,25%,25%,25%",options="header",] +|=== +|Repo |PR |Findings |Status +|`+tropical-resource-typing+` +|https://github.com/hyperpolymath/tropical-resource-typing/pull/4[#4] |4 +|merged — all PA021 detector false positives (comment-text matches in +Isabelle `+\...\+`) + +|`+echidna+` |https://github.com/hyperpolymath/echidna/pull/107[#107] |2 +|merged — `+funext+` (HoTT standard axiom) + `+Conflicts+` (intentional +design parameter) + +|`+standards+` +|https://github.com/hyperpolymath/standards/pull/184[#184] |1 file (4 +postulates) |open — justified real-analysis postulates per file’s own +comment +|=== + +Track B — real-bug fix: + +[width="100%",cols="34%,33%,33%",options="header",] +|=== +|Repo |PR / Issue |Type +|`+svalinn+` |https://github.com/hyperpolymath/svalinn/issues/12[#12], +fix https://github.com/hyperpolymath/svalinn/pull/14[#14] +|`+Jwt.verifyJwt+` now actually verifies signatures via Web Crypto (was +failing closed by accident on every call due to a chain of +`+%raw+`-opacity bugs) +|=== + +==== GitHub issues (62+) + +Per-repo Track C tracking issues filed across 35+ repos aggregating +~1,300 Critical/High findings (excluding PA001/PA007 covered by Track A +and ProofDrift covered by Track D). Full list in +https://github.com/hyperpolymath/panic-attack/issues/32[panic-attack#32] +comment thread. + +Track E bridge-triage CVE tracking issues filed across 24 of 29 +non-zero-CVE Rust repos. Full list in same tracker. + +Track D proof-aware tracking issues filed (then closed as superseded by +Track D classification PRs): echidna#105, tropical-resource-typing#3, +standards#181. + +==== Upstream bugs filed against panic-attack itself + +* https://github.com/hyperpolymath/panic-attack/issues/33[#33] — +*design*: VeriSimDB hexad persistence (JSON output schema doesn’t handle +multi-axis well; would enable real `+temporal diff+` coverage) +* https://github.com/hyperpolymath/panic-attack/issues/43[#43] — *bug*: +PA021 ProofDrift detector matches `+sorry+` / `+oops+` inside Isabelle +`+\...\+` and `+@{text ...}+` comment antiquotations; +Agda/Coq/Idris detectors likely have the same blind spot +* https://github.com/hyperpolymath/panic-attack/issues/47[#47] — *bug*: +`+bridge triage+`’s `+"Remove unused dependency from Cargo.toml"+` +action assumes direct dependency but fires on transitive deps (28/28 +phantoms in a 6-repo sample were transitive) + +==== Skipped / blocked + +[width="100%",cols="50%,50%",options="header",] +|=== +|Repo / scope |Reason +|`+polystack+` |Archived on GitHub (read-only) — 7 findings unclassified + +|`+hypatia+` |Active working tree with 280+ untracked files at session +start; deferred to avoid disturbing in-progress work + +|`+linguist+` / `+rescript+` / `+HOL+` |Forks with issues disabled on +GitHub — Track A PRs landed where possible, no Track C tracking issue + +|`+hyperpolymath-archive+`, `+standards-as-port+` |Deleted on GitHub; +local copies are orphans + +|`+julia-libraries/*.jl+` |Julia chapter closed per project memory; +covered only via container-level `+julia-ecosystem#6+` tracking issue + +|`+ephapax+` preservation (`+Semantics.v:3327+`) |Parked debt per +`+ephapax-preservation-closure-plan+` — not refiled + +|`+boj-server+` `+SafetyLemmas.idr+` (5 `+believe_me+`) |Parked class-J +primitive axioms (3-month dedicated harness) — not refiled + +|`+betlang+` `+substTop_preserves_typing+` |Parked axiom with discharge +recipe in betlang PR#27 — not refiled + +|`+agda-stdlib+` |Upstream agda/agda-stdlib clone; no `+hyperpolymath/+` +fork — out of scope +|=== + +=== Discoveries + +==== `+%raw+` opacity in ReScript (svalinn) + +The most surprising find of the campaign: `+svalinn+`’s +`+Jwt.verifyJwt+` was reported as a JWT-verify _bypass_ on reading the +ReScript source, but the compiled JS was actually compile-broken. +ReScript’s `+%raw("decoded.payload")+` block referenced a variable +`+decoded+` that the compiler optimised away (it can’t see references +inside `+%raw+` strings), so every call threw `+ReferenceError+`. The +catch-block in `+AuthMiddleware.authenticateBearerToken+` swallowed the +error and returned `+authenticated: false+` — so JWT auth was +*fail-closed by accident*, not by signature-skip. + +The same `+%raw+`-opacity pitfall was present in: - `+base64UrlDecode+` +(bound `+_i+`, `+%raw+` referenced `+i+` — different variable name in +compiled output) - `+OAuth2.generateState+` (`+array+` var elided across +`+%raw+` boundaries) - `+OAuth2+` module named `+URLSearchParams+` +(compiled to `+let URLSearchParams = {}+` which shadowed the global +constructor → `+getAuthorizationUrl+` non-functional) + +All four bugs were in code that _looked_ obviously correct on visual +inspection. Lesson: never trust a `+%raw+` block whose only "`use`" of a +binding is through the `+%raw+` string — ReScript will silently drop the +binding. + +PR https://github.com/hyperpolymath/svalinn/pull/14[`+svalinn#14+`] +fixes all four with proper Web Crypto wiring (`+importKey+` + `+verify+` +via JWK, signing input built from raw b64 segments via TextEncoder, +algorithm allow-list rejecting `+none+`). 29/29 auth tests now pass (was +17/12 split). + +==== Transitive-dep misclassification in `+bridge triage+` + +`+bridge triage+` reports `+"Remove unused dependency from Cargo.toml"+` +as the recommended action for every phantom-classified CVE. Audit across +6 repos found *28/28 phantom packages were transitive* (pulled in by +upstream crates, never declared in any local `+Cargo.toml+`). +`+cargo update+` doesn’t drop them because they’re already at the latest +crates.io version matching the upstream parent’s constraint. + +Net: Lane 1 of the planned remediation (small no-behaviour-change PRs +deleting unused deps) doesn’t apply estate-wide. The underlying +classification (`+informational+` + `+phantom+` = code unreachable) is +correct; only the action string is misleading. Filed as panic-attack#47. + +==== PA021 detector reads docstring text (tropical-resource-typing) + +Three of four PA021 ProofDrift findings on `+tropical-resource-typing+` +were the detector counting the literal word `+sorry+` inside Isabelle +`+\All proofs are complete — zero @{text sorry}.\+` header +docstrings. The fourth (`+Tropical_Ordinal.thy+`) matched `+oops+` +inside a docstring explaining echidna’s evaluation handoff +(`+with \oops\ are the ones we want ECHIDNA to evaluate+`). + +Filed as panic-attack#43. Same blind spot probably affects PA021’s +Agda/Coq/Idris equivalents (counting `+postulate+` / `+Admitted+` / +`+believe_me+` inside Haddock-style docstrings) and warrants a re-audit. + +==== Mid-campaign correction: file-overwrite mistake + +The first `+echidna+` PR (#107) initially overwrote 14 pre-existing +FFI-boundary classification entries on +`+audits/assail-classifications.a2ml+`. The driver script +(`+file-ffi-pr-v2.sh+`) did `+cat > audits/assail-classifications.a2ml+` +without checking for an existing file. Fixed in a follow-up commit on +the same branch +(`+fix: restore pre-existing FFI-boundary classifications+`); the PR now +sits at 16 entries (14 original + 2 new PA021). Future per-repo +classification PRs should +`+git show origin/main:audits/assail-classifications.a2ml+` before +truncating. + +=== Guardrails honoured throughout + +* All commits GPG-signed (key +`+4A03639C1EB1F86C7F0C97A91835A14A2867091E+`). +* Base = `+main+` for every PR — no stacked bases. +* Auto-merge disabled on every PR (estate-wide auto-merge is banned per +project memory). +* Never `+--no-verify+` / `+--no-gpg-sign+`. +* `+features/panic-attacker/+` stub dirs in other repos untouched (they +reference the canonical tool, not divergent copies). +* `+vcl-ut/_wt-vclut*+`, `+hypatia/.claude/worktrees/agent-*+`, ephapax +`+_wt-eph-*+` worktrees — all untouched (parallel sessions). +* Parked proof debts (`+ephapax+`, `+betlang+`, `+boj-server+` class-J) +— not refiled. +* Julia chapter closed — no per-`+.jl+` issues filed; container-level +only. +* `+valence-shell+`’s stray local `+main+` commit (workflow hardening, +unpushed) preserved by branching from `+origin/main+` not local +`+main+`. +* Same defence applied to standards (foreign parallel session on +`+claude/governance-allowlist-foundation+` branch left alone) and +panic-attack itself (foreign session on `+fix/idris-lang-chapel-not-c+` +left alone — this campaign-report branch was created from +`+origin/main+`). + +=== What remains + +Owner-side throughput now bounds the campaign: + +[arabic] +. *Review/merge the 15 open PRs* — all narrow, signed, small surface +area. +. *Triage the Track C tracking issues* (~1,300 findings) — separate real +bugs from false-positive patterns per repo. +. *Decide on the 3 upstream panic-attack bugs* filed (#33 design, #43 +detector, #47 bridge action). + +Deferred to follow-up sessions: + +* *hypatia* classification PR — re-attempt once the active session’s +untracked files have committed or cleared. +* *polystack* — owner action to unarchive on GitHub before any work can +land. +* *Track E `+assault+`* — heavyweight per-target work (each binary needs +build + manually-chosen long-running input). Not estate-wide +automatable. Smoke-tested on `+panic-attack+` self-binary (light +intensity, 5s/axis, cpu+memory): 0 crashes, 0 signatures, 100% +robustness — as expected for a fast-exit CLI. + +=== Campaign workspace + +Preserved at `+/tmp/panic-attack-campaign-2026-05-26/+`: + +* `+per-repo/*.json+` (349 assail reports, one per repo) +* `+bridge/*.json+` (58 Rust-repo bridge reports) +* `+02-plan.json+` (triage classification plan) +* `+assault/self-test.json+` (Track E smoke test) +* `+00-per-repo.sh+`, `+00b-nested.sh+`, `+01-triage.ts+`, +`+file-ffi-pr-v2.sh+`, `+file-track-c-issue.sh+` (driver scripts) +* `+TRACKER-UPDATE.md+` … `+TRACKER-UPDATE-V5.md+` (intermediate session +summaries posted on #32) diff --git a/docs/campaigns/2026-05-26.md b/docs/campaigns/2026-05-26.md deleted file mode 100644 index df2aa95..0000000 --- a/docs/campaigns/2026-05-26.md +++ /dev/null @@ -1,179 +0,0 @@ - -Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) ---> - -# Estate sweep campaign — 2026-05-26 - -**Owner**: @hyperpolymath -**Tracker**: [hyperpolymath/panic-attack#32](https://github.com/hyperpolymath/panic-attack/issues/32) -**Tool**: `panic-attack` v2.5.0 built 2026-05-26 -**Scope**: 369-repo estate at `~/developer/repos/` -**Outcome**: 16 narrow PRs + 1 real-bug fix PR + 35+ tracking issues + 3 upstream bug reports - -## Method - -Two-session campaign across 5 work tracks: - -1. **Track A — FFI / fixture classification PRs**: per-repo `audits/assail-classifications.a2ml` + `audits/audit-*.md` writing a narrow allow-list for legitimate `unsafe` / fixture-context findings. Each PR documents both the rationale and the anti-gameability mechanism (registry is a separate file from the source under scan; new unsafe inside a classified root requires a companion entry + doc edit, both visible in the diff). -2. **Track B — real-bug remainder**: after Track A's classifications drained ~500 FFI-shaped findings, the genuine code-bug remainder was small. One critical fix landed (`svalinn` JWT signature verification). -3. **Track C — per-repo tracking issues**: 35+ GitHub issues, one per repo, listing the Critical/High findings by category for human triage. Excludes Track A and Track D-coverage categories. -4. **Track D / Phase 5 — proof-aware**: ProofDrift findings in 3 proof repos (`echidna`, `tropical-resource-typing`, `standards`) classified as legitimate axioms or detector false positives. **Zero findings required actual proof discharge.** -5. **Track E — bridge CVE triage**: 24 per-repo CVE tracking issues from `panic-attack bridge triage` (RustSec advisory DB + reachability analysis) across 29 of 58 Rust repos with non-zero advisories. - -### Scan pipeline - -Initial attempt used `panic-attack assemblyline` (batch-scan a directory of repos) but stalled on a single 7-min repo with `--parallel` enabled. Pivoted to **per-repo `panic-attack assail --headless` with a 90s timeout** so no single repo can block the campaign. 349 of 368 repos scanned cleanly; 19 skipped (content-only, no source). Plus a nested-repo pass for 6 container directories (`a2ml`, `awesome-projects`, `idaptik`, `isers`, `julia-libraries`, `k9`) covering ~90 sub-repos. - -### Findings shape (post-scan, before any classification PRs) - -| Severity bucket | Count | -|---|---| -| Critical/High `UnsafeCode` / `UnsafeFFI` | 497 | -| Critical/High `SupplyChain` | 398 | -| Critical/High `UnboundedAllocation` | 516 | -| Critical/High `DynamicCodeExecution` | 472 | -| Critical/High `HardcodedSecret` | 122 | -| Critical/High `CommandInjection` | 113 | -| Critical/High `UnsafeDeserialization` | 73 | -| Critical/High `UnsafeTypeCoercion` | 32 | -| Critical/High `CryptoMisuse` | 28 | -| Critical/High `ProofDrift` | 219 | -| Other (Low/Medium) | 2,591 | -| Already-suppressed | 961 | -| Worktree-path artefacts (skipped) | 40 | -| **Actionable this campaign** | **~2,477** | - -## Outputs - -### Pull requests (17 narrow PRs) - -Track A — FFI / fixture classifications: - -| Repo | PR | Findings | Pattern | -|---|---|---|---| -| `svalinn` | [#11](https://github.com/hyperpolymath/svalinn/pull/11) | 4 | test-context-fixture (JWT decode in bench/tests) | -| `proven` | [#67](https://github.com/hyperpolymath/proven/pull/67) | 150 | legitimate-FFI (bindings/, ffi/) + protocol-type-identifier + binding-wrapper-naming | -| `gossamer` | [#54](https://github.com/hyperpolymath/gossamer/pull/54) | 24 | Zig FFI (GTK WebKit) | -| `docudactyl` | [#20](https://github.com/hyperpolymath/docudactyl/pull/20) | 15 | Zig FFI | -| `proven-servers` | [#11](https://github.com/hyperpolymath/proven-servers/pull/11) | 10 | bindings/rust FFI | -| `aerie` | [#35](https://github.com/hyperpolymath/aerie/pull/35) | 10 | Zig FFI | -| `stapeln` | [#62](https://github.com/hyperpolymath/stapeln/pull/62) | 10 | eBPF + Zig FFI + Ada↔liboqs | -| `ambientops` | [#102](https://github.com/hyperpolymath/ambientops/pull/102) | 10 | syscall + cross-subproject FFI | -| `valence-shell` | [#32](https://github.com/hyperpolymath/valence-shell/pull/32) | 8 | POSIX shell job-control libc + Zig FFI | -| `panll` | [#47](https://github.com/hyperpolymath/panll/pull/47) | 6 | Idris2 Zig FFI + src-gossamer OS-FFI | -| `linguist` | [#3](https://github.com/hyperpolymath/linguist/pull/3) | 13 | sample-reference-fixture (PA001+PA022) + vendored PCRE | -| `boj-server` | [#154](https://github.com/hyperpolymath/boj-server/pull/154) | 119 | 117 MCP cartridge_shim + 2 backend FFI (supersedes #153) | -| `idaptik` | [#98](https://github.com/hyperpolymath/idaptik/pull/98) | 12 | in-game password fixtures (game-content) | - -Track D / Phase 5 — proof-aware: - -| Repo | PR | Findings | Status | -|---|---|---|---| -| `tropical-resource-typing` | [#4](https://github.com/hyperpolymath/tropical-resource-typing/pull/4) | 4 | merged — all PA021 detector false positives (comment-text matches in Isabelle `\...\`) | -| `echidna` | [#107](https://github.com/hyperpolymath/echidna/pull/107) | 2 | merged — `funext` (HoTT standard axiom) + `Conflicts` (intentional design parameter) | -| `standards` | [#184](https://github.com/hyperpolymath/standards/pull/184) | 1 file (4 postulates) | open — justified real-analysis postulates per file's own comment | - -Track B — real-bug fix: - -| Repo | PR / Issue | Type | -|---|---|---| -| `svalinn` | [#12](https://github.com/hyperpolymath/svalinn/issues/12), fix [#14](https://github.com/hyperpolymath/svalinn/pull/14) | `Jwt.verifyJwt` now actually verifies signatures via Web Crypto (was failing closed by accident on every call due to a chain of `%raw`-opacity bugs) | - -### GitHub issues (62+) - -Per-repo Track C tracking issues filed across 35+ repos aggregating ~1,300 Critical/High findings (excluding PA001/PA007 covered by Track A and ProofDrift covered by Track D). Full list in [panic-attack#32](https://github.com/hyperpolymath/panic-attack/issues/32) comment thread. - -Track E bridge-triage CVE tracking issues filed across 24 of 29 non-zero-CVE Rust repos. Full list in same tracker. - -Track D proof-aware tracking issues filed (then closed as superseded by Track D classification PRs): echidna#105, tropical-resource-typing#3, standards#181. - -### Upstream bugs filed against panic-attack itself - -- [#33](https://github.com/hyperpolymath/panic-attack/issues/33) — **design**: VeriSimDB hexad persistence (JSON output schema doesn't handle multi-axis well; would enable real `temporal diff` coverage) -- [#43](https://github.com/hyperpolymath/panic-attack/issues/43) — **bug**: PA021 ProofDrift detector matches `sorry` / `oops` inside Isabelle `\...\` and `@{text ...}` comment antiquotations; Agda/Coq/Idris detectors likely have the same blind spot -- [#47](https://github.com/hyperpolymath/panic-attack/issues/47) — **bug**: `bridge triage`'s `"Remove unused dependency from Cargo.toml"` action assumes direct dependency but fires on transitive deps (28/28 phantoms in a 6-repo sample were transitive) - -### Skipped / blocked - -| Repo / scope | Reason | -|---|---| -| `polystack` | Archived on GitHub (read-only) — 7 findings unclassified | -| `hypatia` | Active working tree with 280+ untracked files at session start; deferred to avoid disturbing in-progress work | -| `linguist` / `rescript` / `HOL` | Forks with issues disabled on GitHub — Track A PRs landed where possible, no Track C tracking issue | -| `hyperpolymath-archive`, `standards-as-port` | Deleted on GitHub; local copies are orphans | -| `julia-libraries/*.jl` | Julia chapter closed per project memory; covered only via container-level `julia-ecosystem#6` tracking issue | -| `ephapax` preservation (`Semantics.v:3327`) | Parked debt per `ephapax-preservation-closure-plan` — not refiled | -| `boj-server` `SafetyLemmas.idr` (5 `believe_me`) | Parked class-J primitive axioms (3-month dedicated harness) — not refiled | -| `betlang` `substTop_preserves_typing` | Parked axiom with discharge recipe in betlang PR#27 — not refiled | -| `agda-stdlib` | Upstream agda/agda-stdlib clone; no `hyperpolymath/` fork — out of scope | - -## Discoveries - -### `%raw` opacity in ReScript (svalinn) - -The most surprising find of the campaign: `svalinn`'s `Jwt.verifyJwt` was reported as a JWT-verify *bypass* on reading the ReScript source, but the compiled JS was actually compile-broken. ReScript's `%raw("decoded.payload")` block referenced a variable `decoded` that the compiler optimised away (it can't see references inside `%raw` strings), so every call threw `ReferenceError`. The catch-block in `AuthMiddleware.authenticateBearerToken` swallowed the error and returned `authenticated: false` — so JWT auth was **fail-closed by accident**, not by signature-skip. - -The same `%raw`-opacity pitfall was present in: -- `base64UrlDecode` (bound `_i`, `%raw` referenced `i` — different variable name in compiled output) -- `OAuth2.generateState` (`array` var elided across `%raw` boundaries) -- `OAuth2` module named `URLSearchParams` (compiled to `let URLSearchParams = {}` which shadowed the global constructor → `getAuthorizationUrl` non-functional) - -All four bugs were in code that *looked* obviously correct on visual inspection. Lesson: never trust a `%raw` block whose only "use" of a binding is through the `%raw` string — ReScript will silently drop the binding. - -PR [`svalinn#14`](https://github.com/hyperpolymath/svalinn/pull/14) fixes all four with proper Web Crypto wiring (`importKey` + `verify` via JWK, signing input built from raw b64 segments via TextEncoder, algorithm allow-list rejecting `none`). 29/29 auth tests now pass (was 17/12 split). - -### Transitive-dep misclassification in `bridge triage` - -`bridge triage` reports `"Remove unused dependency from Cargo.toml"` as the recommended action for every phantom-classified CVE. Audit across 6 repos found **28/28 phantom packages were transitive** (pulled in by upstream crates, never declared in any local `Cargo.toml`). `cargo update` doesn't drop them because they're already at the latest crates.io version matching the upstream parent's constraint. - -Net: Lane 1 of the planned remediation (small no-behaviour-change PRs deleting unused deps) doesn't apply estate-wide. The underlying classification (`informational` + `phantom` = code unreachable) is correct; only the action string is misleading. Filed as panic-attack#47. - -### PA021 detector reads docstring text (tropical-resource-typing) - -Three of four PA021 ProofDrift findings on `tropical-resource-typing` were the detector counting the literal word `sorry` inside Isabelle `\All proofs are complete — zero @{text sorry}.\` header docstrings. The fourth (`Tropical_Ordinal.thy`) matched `oops` inside a docstring explaining echidna's evaluation handoff (`with \oops\ are the ones we want ECHIDNA to evaluate`). - -Filed as panic-attack#43. Same blind spot probably affects PA021's Agda/Coq/Idris equivalents (counting `postulate` / `Admitted` / `believe_me` inside Haddock-style docstrings) and warrants a re-audit. - -### Mid-campaign correction: file-overwrite mistake - -The first `echidna` PR (#107) initially overwrote 14 pre-existing FFI-boundary classification entries on `audits/assail-classifications.a2ml`. The driver script (`file-ffi-pr-v2.sh`) did `cat > audits/assail-classifications.a2ml` without checking for an existing file. Fixed in a follow-up commit on the same branch (`fix: restore pre-existing FFI-boundary classifications`); the PR now sits at 16 entries (14 original + 2 new PA021). Future per-repo classification PRs should `git show origin/main:audits/assail-classifications.a2ml` before truncating. - -## Guardrails honoured throughout - -- All commits GPG-signed (key `4A03639C1EB1F86C7F0C97A91835A14A2867091E`). -- Base = `main` for every PR — no stacked bases. -- Auto-merge disabled on every PR (estate-wide auto-merge is banned per project memory). -- Never `--no-verify` / `--no-gpg-sign`. -- `features/panic-attacker/` stub dirs in other repos untouched (they reference the canonical tool, not divergent copies). -- `vcl-ut/_wt-vclut*`, `hypatia/.claude/worktrees/agent-*`, ephapax `_wt-eph-*` worktrees — all untouched (parallel sessions). -- Parked proof debts (`ephapax`, `betlang`, `boj-server` class-J) — not refiled. -- Julia chapter closed — no per-`.jl` issues filed; container-level only. -- `valence-shell`'s stray local `main` commit (workflow hardening, unpushed) preserved by branching from `origin/main` not local `main`. -- Same defence applied to standards (foreign parallel session on `claude/governance-allowlist-foundation` branch left alone) and panic-attack itself (foreign session on `fix/idris-lang-chapel-not-c` left alone — this campaign-report branch was created from `origin/main`). - -## What remains - -Owner-side throughput now bounds the campaign: - -1. **Review/merge the 15 open PRs** — all narrow, signed, small surface area. -2. **Triage the Track C tracking issues** (~1,300 findings) — separate real bugs from false-positive patterns per repo. -3. **Decide on the 3 upstream panic-attack bugs** filed (#33 design, #43 detector, #47 bridge action). - -Deferred to follow-up sessions: - -- **hypatia** classification PR — re-attempt once the active session's untracked files have committed or cleared. -- **polystack** — owner action to unarchive on GitHub before any work can land. -- **Track E `assault`** — heavyweight per-target work (each binary needs build + manually-chosen long-running input). Not estate-wide automatable. Smoke-tested on `panic-attack` self-binary (light intensity, 5s/axis, cpu+memory): 0 crashes, 0 signatures, 100% robustness — as expected for a fast-exit CLI. - -## Campaign workspace - -Preserved at `/tmp/panic-attack-campaign-2026-05-26/`: - -- `per-repo/*.json` (349 assail reports, one per repo) -- `bridge/*.json` (58 Rust-repo bridge reports) -- `02-plan.json` (triage classification plan) -- `assault/self-test.json` (Track E smoke test) -- `00-per-repo.sh`, `00b-nested.sh`, `01-triage.ts`, `file-ffi-pr-v2.sh`, `file-track-c-issue.sh` (driver scripts) -- `TRACKER-UPDATE.md` ... `TRACKER-UPDATE-V5.md` (intermediate session summaries posted on #32) diff --git a/docs/campaigns/2026-05-26/01-triage.adoc b/docs/campaigns/2026-05-26/01-triage.adoc new file mode 100644 index 0000000..7790441 --- /dev/null +++ b/docs/campaigns/2026-05-26/01-triage.adoc @@ -0,0 +1,198 @@ +== 01-triage — algorithmic spec + +____ +Historical campaign snapshot from 2026-05-26. The original +`+01-triage.ts+` (183 lines, Deno TypeScript) is removed per the +standards#239 estate TypeScript → AffineScript migration. This document +preserves the algorithmic spec so a future AffineScript port can land +cleanly when the stdlib gaps surfaced below (feeding standards#242 STEP +3) close. +____ + +=== Purpose + +Reads per-repo `+AssailReport+` JSONs, classifies each weak-point +finding into one of six buckets, groups the actionable buckets by +`+(repo, file_dir, category)+`, and emits a JSON summary describing the +PR-candidate plan. + +=== Inputs + +* `++`: directory of `+.json+` files (one per repo), +each an `+AssailReport+` produced by `+panic-attack+` assail. +* `++`: output path for the summary. + +=== Domain types + +[source,text] +---- +Severity := Low | Medium | High | Critical + +WeakPoint := + { category: PA-code or alias + , file: optional source path + , line: optional line number + , severity: Severity + , description: free text + , suppressed: bool + } + +AssailReport := + { schema_version: semver + , program_path: path + , language: identifier + , weak_points: [WeakPoint] + , suppressed_count?: int + } + +PrCandidate := WeakPoint + repo + bucket + canonical category code +---- + +=== Static policy tables + +==== Proof-file extensions + +`+.lean, .agda, .lagda, .v, .idr, .idr2, .fst, .fsti, .thy, .spthy, .smt2, .tla+` + +==== Categories with reliable automated fixes (Critical / High only) + +`+PA001/UnsafeCode, PA006/PanicPath, PA022/CryptoMisuse+` + +==== Categories requiring human judgement (always → issue, never auto-fix) + +`+PA023/SupplyChain, PA024/InputBoundary, PA025/MutationGap, PA021/ProofDrift+` + +==== Parked proof debts (skip wholesale) + +* `+ephapax / formal/Semantics.v:3327+` (preservation, deferred per the +ephapax-preservation-closure-plan). +* `+betlang / *+` where description contains +`+substTop_preserves_typing+` (discharge recipe in PR#27 body). + +==== Category alias → canonical PA-code mapping + +Recognises both `+PA\d{3}+` codes (passed through) and the enum-name +aliases +`+UnsafeCode → PA001, PanicPath → PA006, CommandInjection → PA003, UnsafeDeserialization → PA004, AtomExhaustion → PA005, UnsafeFFI → PA007, PathTraversal → PA008, HardcodedSecret → PA009, ProofDrift → PA021, CryptoMisuse → PA022, SupplyChain → PA023, InputBoundary → PA024, MutationGap → PA025+`. +Unknown values pass through unchanged. + +=== Classification algorithm + +For each `+(repo, wp)+`: + +[arabic] +. `+wp.suppressed+` → `+skip-suppressed+`. +. severity not in `+{Critical, High}+` → `+skip-unknown-cat+` (out of +scope this wave; the bucket name is historical and load-bearing in +summaries). +. `+(repo, wp)+` matches a parked-debt row → `+skip-known+`. +. `+wp.file+` contains `+.claude/worktrees/+` or `+/_wt-+` → +`+skip-known+` (main checkout is the source of truth, not worktree +branches). +. `+wp.file+` extension in proof-file set → `+proof-draft+`. +. Canonical category code in `+issue_only+` set → `+issue+`. +. Canonical category code in `+autofix_ok+` set → `+autofix+`. +. Otherwise → `+issue+` (default conservative — needs human eye). + +=== PR grouping + +Group all non-skip candidates by the key +`+::::+`. `+file_dir+` is the parent directory +of `+wp.file+` (joined by `+/+`), so all findings under the same +directory and category collapse into one PR. + +=== Output summary shape + +[source,jsonc] +---- +{ + "generated_at": "", + "per_repo_scanned": , + "total_candidates": , + "by_bucket": { "": , ... }, + "by_repo": { "": , ... }, // only repos with >0 + "pr_groups": [ + { + "key": "::::", + "repo": "", + "file_dir": "", + "category": "", + "bucket": "", + "finding_count": , + "severities": ["", ...], + "examples": [, ...] // up to 3 + } + ] +} +---- + +=== Side-channel logs (stderr) + +.... +triage complete: candidates, PR groups → +buckets: { "": , ... } +.... + +=== Stdlib gaps surfaced for the AffineScript port (feeds standards#242 STEP 3) + +This script depends on the following Deno / TS-stdlib surfaces that have +no direct equivalent in `+stdlib/Deno.affine+` or `+stdlib/json.affine+` +today. Each gap is a candidate fill-in for STEP 3 (stdlib enrichment) +before the port can land cleanly. + +[arabic] +. *`+Set+` membership* — no native AS surface. Workaround: +`+[String]+` with linear-scan `+containsString+`. Acceptable for the +≤25-entry policy lists this script uses; not a general-purpose Set. +. *`+Map+` group-by* — no native AS surface. Workaround: +`+[(String, [PrCandidate])]+` association list. O(n²) but n is small +here. A real Map binding would be a broader stdlib win. +. *Async generators (`+async function* walk(...)+`)* — no AS surface. +Workaround: collapse to eager `+[String]+` list collection via +`+Deno::walkRecursive+` (already in `+Deno.affine+`). +. *`+JSON.parse+` returning a typed sum* — `+Deno::jsonParse+` returns +the opaque `+Deno.Json+`, with field access via discrete `+jsonGet*+` +externs. Reading nested `+AssailReport.weak_points[i].category+` is many +extern calls. A typed-decoder generator (`+json.affine+` style) is the +cleaner path. The `+json.affine+` v0.3 work (mentioned in RSR-stack +status memo) would close this. +. *Regex object construction* — TS uses `+new RegExp(pat).test(s)+` and +inline `+/^PA\d{3}/.test(cat)+`. `+Deno::regexMatch(s, pat)+` covers the +call shape but does not expose a constructed regex value — fine for this +script. +. *`+new Date().toISOString()+`* — needed for `+generated_at+` and the +per-PrCandidate `+lastProbe+` analogue. `+Deno.affine+` has `+dateNow+` +(returns ms) but no ISO8601 formatter. Would need `+dateNowIso+` extern. +. *`+Object.fromEntries(...)+` for dynamic object construction* — needed +for the `+by_bucket+` / `+by_repo+` summary objects. `+Deno.affine+` +exposes `+jsonNull+` / `+jsonStringify+` but no `+jsonObjectFromPairs+` +builder extern. Workaround: build the JSON string manually. +. *Optional chaining `+wp.file?.endsWith(...)+`* — explicit Option/match +on the AS side (`+wp.file != "" && Deno::endsWith(...)+`). Working as +intended; just verbose. +. *`+async / await+` on synchronous-effect FS calls* — `+Deno.affine+` +externs are all sync (per the `+Deno.affine+` header comment); the port +loses the async machinery, which is the right call for the Deno-ESM +backend. +. *Spread / rest patterns in destructuring* — TS uses +`+[...new Set(candidates.map(c => c.repo))].sort()+` etc. Each call site +needs an explicit `+unique_sort_string+` helper in AS. + +=== Reference: original implementation + +Removed in this PR — see git history for the full TS source. The +original referenced these external surfaces: + +* `+https://deno.land/std@0.224.0/fs/walk.ts+` +* `+https://deno.land/std@0.224.0/path/mod.ts+` +* `+Deno.{args, readTextFile, writeTextFile, exit}+` +* Built-ins: `+Set+`, `+Map+`, `+Date+`, `+Object+`, `+JSON+`, +`+RegExp+`, `+console+` + +=== Migration status + +* 🟡 Spec preserved (this document) — 2026-05-30. +* 🔴 `+.affine+` implementation pending stdlib fill-in per gaps 1–4, 6, +7 above. Tracking: standards#242 STEP 3. +* 🟢 `+01-triage.ts+` removed (campaign artefact; logic deferred to +future panic-attack runs once the AffineScript port lands). diff --git a/docs/campaigns/2026-05-26/01-triage.md b/docs/campaigns/2026-05-26/01-triage.md deleted file mode 100644 index 7db9a34..0000000 --- a/docs/campaigns/2026-05-26/01-triage.md +++ /dev/null @@ -1,197 +0,0 @@ - - - - -# 01-triage — algorithmic spec - -> Historical campaign snapshot from 2026-05-26. The original `01-triage.ts` -> (183 lines, Deno TypeScript) is removed per the standards#239 estate -> TypeScript → AffineScript migration. This document preserves the -> algorithmic spec so a future AffineScript port can land cleanly when the -> stdlib gaps surfaced below (feeding standards#242 STEP 3) close. - -## Purpose - -Reads per-repo `AssailReport` JSONs, classifies each weak-point finding into -one of six buckets, groups the actionable buckets by `(repo, file_dir, -category)`, and emits a JSON summary describing the PR-candidate plan. - -## Inputs - -- ``: directory of `.json` files (one per repo), each - an `AssailReport` produced by `panic-attack` assail. -- ``: output path for the summary. - -## Domain types - -```text -Severity := Low | Medium | High | Critical - -WeakPoint := - { category: PA-code or alias - , file: optional source path - , line: optional line number - , severity: Severity - , description: free text - , suppressed: bool - } - -AssailReport := - { schema_version: semver - , program_path: path - , language: identifier - , weak_points: [WeakPoint] - , suppressed_count?: int - } - -PrCandidate := WeakPoint + repo + bucket + canonical category code -``` - -## Static policy tables - -### Proof-file extensions -`.lean, .agda, .lagda, .v, .idr, .idr2, .fst, .fsti, .thy, .spthy, .smt2, .tla` - -### Categories with reliable automated fixes (Critical / High only) -`PA001/UnsafeCode, PA006/PanicPath, PA022/CryptoMisuse` - -### Categories requiring human judgement (always → issue, never auto-fix) -`PA023/SupplyChain, PA024/InputBoundary, PA025/MutationGap, PA021/ProofDrift` - -### Parked proof debts (skip wholesale) -- `ephapax / formal/Semantics.v:3327` (preservation, deferred per the - ephapax-preservation-closure-plan). -- `betlang / *` where description contains `substTop_preserves_typing` - (discharge recipe in PR#27 body). - -### Category alias → canonical PA-code mapping -Recognises both `PA\d{3}` codes (passed through) and the enum-name -aliases `UnsafeCode → PA001, PanicPath → PA006, CommandInjection → PA003, -UnsafeDeserialization → PA004, AtomExhaustion → PA005, UnsafeFFI → PA007, -PathTraversal → PA008, HardcodedSecret → PA009, ProofDrift → PA021, -CryptoMisuse → PA022, SupplyChain → PA023, InputBoundary → PA024, -MutationGap → PA025`. Unknown values pass through unchanged. - -## Classification algorithm - -For each `(repo, wp)`: - -1. `wp.suppressed` → `skip-suppressed`. -2. severity not in `{Critical, High}` → `skip-unknown-cat` (out of scope this - wave; the bucket name is historical and load-bearing in summaries). -3. `(repo, wp)` matches a parked-debt row → `skip-known`. -4. `wp.file` contains `.claude/worktrees/` or `/_wt-` → `skip-known` (main - checkout is the source of truth, not worktree branches). -5. `wp.file` extension in proof-file set → `proof-draft`. -6. Canonical category code in `issue_only` set → `issue`. -7. Canonical category code in `autofix_ok` set → `autofix`. -8. Otherwise → `issue` (default conservative — needs human eye). - -## PR grouping - -Group all non-skip candidates by the key -`::::`. `file_dir` is the parent directory of -`wp.file` (joined by `/`), so all findings under the same directory and -category collapse into one PR. - -## Output summary shape - -```jsonc -{ - "generated_at": "", - "per_repo_scanned": , - "total_candidates": , - "by_bucket": { "": , ... }, - "by_repo": { "": , ... }, // only repos with >0 - "pr_groups": [ - { - "key": "::::", - "repo": "", - "file_dir": "", - "category": "", - "bucket": "", - "finding_count": , - "severities": ["", ...], - "examples": [, ...] // up to 3 - } - ] -} -``` - -## Side-channel logs (stderr) - -``` -triage complete: candidates, PR groups → -buckets: { "": , ... } -``` - -## Stdlib gaps surfaced for the AffineScript port (feeds standards#242 STEP 3) - -This script depends on the following Deno / TS-stdlib surfaces that have no -direct equivalent in `stdlib/Deno.affine` or `stdlib/json.affine` today. -Each gap is a candidate fill-in for STEP 3 (stdlib enrichment) before the -port can land cleanly. - -1. **`Set` membership** — no native AS surface. Workaround: `[String]` - with linear-scan `containsString`. Acceptable for the ≤25-entry policy - lists this script uses; not a general-purpose Set. - -2. **`Map` group-by** — no native AS surface. Workaround: - `[(String, [PrCandidate])]` association list. O(n²) but n is small - here. A real Map binding would be a broader stdlib win. - -3. **Async generators (`async function* walk(...)`)** — no AS surface. - Workaround: collapse to eager `[String]` list collection via - `Deno::walkRecursive` (already in `Deno.affine`). - -4. **`JSON.parse` returning a typed sum** — `Deno::jsonParse` returns the - opaque `Deno.Json`, with field access via discrete `jsonGet*` externs. - Reading nested `AssailReport.weak_points[i].category` is many extern - calls. A typed-decoder generator (`json.affine` style) is the cleaner - path. The `json.affine` v0.3 work (mentioned in RSR-stack status memo) - would close this. - -5. **Regex object construction** — TS uses `new RegExp(pat).test(s)` and - inline `/^PA\d{3}/.test(cat)`. `Deno::regexMatch(s, pat)` covers the - call shape but does not expose a constructed regex value — fine for - this script. - -6. **`new Date().toISOString()`** — needed for `generated_at` and the - per-PrCandidate `lastProbe` analogue. `Deno.affine` has `dateNow` - (returns ms) but no ISO8601 formatter. Would need `dateNowIso` extern. - -7. **`Object.fromEntries(...)` for dynamic object construction** — needed - for the `by_bucket` / `by_repo` summary objects. `Deno.affine` exposes - `jsonNull` / `jsonStringify` but no `jsonObjectFromPairs` builder - extern. Workaround: build the JSON string manually. - -8. **Optional chaining `wp.file?.endsWith(...)`** — explicit Option/match - on the AS side (`wp.file != "" && Deno::endsWith(...)`). Working as - intended; just verbose. - -9. **`async / await` on synchronous-effect FS calls** — `Deno.affine` - externs are all sync (per the `Deno.affine` header comment); the port - loses the async machinery, which is the right call for the Deno-ESM - backend. - -10. **Spread / rest patterns in destructuring** — TS uses - `[...new Set(candidates.map(c => c.repo))].sort()` etc. Each call - site needs an explicit `unique_sort_string` helper in AS. - -## Reference: original implementation - -Removed in this PR — see git history for the full TS source. The original -referenced these external surfaces: - -- `https://deno.land/std@0.224.0/fs/walk.ts` -- `https://deno.land/std@0.224.0/path/mod.ts` -- `Deno.{args, readTextFile, writeTextFile, exit}` -- Built-ins: `Set`, `Map`, `Date`, `Object`, `JSON`, `RegExp`, `console` - -## Migration status - -- 🟡 Spec preserved (this document) — 2026-05-30. -- 🔴 `.affine` implementation pending stdlib fill-in per gaps 1–4, 6, 7 - above. Tracking: standards#242 STEP 3. -- 🟢 `01-triage.ts` removed (campaign artefact; logic deferred to future - panic-attack runs once the AffineScript port lands). diff --git a/docs/campaigns/2026-05-26/README.adoc b/docs/campaigns/2026-05-26/README.adoc new file mode 100644 index 0000000..7c1a8ce --- /dev/null +++ b/docs/campaigns/2026-05-26/README.adoc @@ -0,0 +1,80 @@ +Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +j.d.a.jewell@open.ac.uk –> + +== Campaign 2026-05-26 — driver scripts + +These are the driver scripts used to run the 2026-05-26 estate sweep. +They’re filed alongside the human + machine campaign reports so the +campaign is reproducible. See +link:../2026-05-26.md[`+../2026-05-26.md+`] for the report. + +=== Scripts + +[width="100%",cols="50%,50%",options="header",] +|=== +|Script |Purpose +|`+00-per-repo.sh+` |Iterates top-level dirs with `+.git/+` and runs +`+panic-attack assail --headless+` against each with a 90s timeout. +Writes per-repo JSON to +`+/tmp/panic-attack-campaign-/per-repo/.json+`. Pivot away +from `+assemblyline+` so no single slow repo can stall the whole batch. + +|`+00b-nested.sh+` |Same scan loop but for nested-repo containers +(`+a2ml+`, `+awesome-projects+`, `+idaptik+`, `+isers+`, +`+julia-libraries+`, `+k9+`). Output filenames use +`+parent__child.json+` to avoid collisions. + +|`+01-triage.ts+` |Deno script that reads per-repo JSONs and classifies +into autofix / issue / proof-draft / skip buckets. Writes +`+02-plan.json+`. + +|`+file-ffi-pr-v2.sh+` |Per-repo classification PR generator. Accepts +`+REPO_NAME+`, `+PREFIX_JSON+` (JSON array of path prefixes), +`+SHORT_RATIONALE+`, optional `+CLASSIFICATION+` (default +`+legitimate-ffi+`). Builds the `+audits/assail-classifications.a2ml+` + +audit doc, commits with the GPG override flags, pushes, opens a PR. *v2* +uses `+--argjson+` + `+any()+` for the prefix filter (the v1 chained-OR +form was broken under jq operator precedence). +|=== + +=== Known gotchas + +[arabic] +. `+file-ffi-pr-v2.sh+` does +`+cat > audits/assail-classifications.a2ml+` without checking whether +the file already exists on `+origin/main+`. If it does, the existing +entries get overwritten. *Always +`+git show origin/main:audits/assail-classifications.a2ml+` before +running the script*, and if entries exist, edit the script to preserve +them. +. Some repos are forks on GitHub with issues disabled (`+linguist+`, +`+rescript+`, `+HOL+`) — Track A PRs land, but Track C tracking issues +can’t be filed. +. Some repos are archived (`+polystack+`) or deleted +(`+hyperpolymath-archive+`); skip them. +. valence-shell-style local-only commits on `+main+` need branching from +`+origin/main+` (not local `+main+`) to preserve them. + +=== Re-running + +[source,sh] +---- +# Phase 1: per-repo scan (~10 min) +bash 00-per-repo.sh && bash 00b-nested.sh + +# Phase 1b: triage +deno run --allow-read --allow-write 01-triage.ts + +# Phase 2..N: per-repo PRs (one invocation per repo) +BRANCH=panic-fix/PA001-PA007-ffi-legitimate \ + bash file-ffi-pr-v2.sh \ + \ + '["src//", "ffi//"]' \ + "Rationale text..." \ + "legitimate-ffi" +---- + +The output JSONs and triage plan are NOT committed to the repo (they’re +ephemeral, scan-time-sensitive). See +link:../2026-05-26.md[`+../2026-05-26.md+`] for the persistent campaign +record. diff --git a/docs/campaigns/2026-05-26/README.md b/docs/campaigns/2026-05-26/README.md deleted file mode 100644 index 7bae53b..0000000 --- a/docs/campaigns/2026-05-26/README.md +++ /dev/null @@ -1,45 +0,0 @@ - -Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) ---> - -# Campaign 2026-05-26 — driver scripts - -These are the driver scripts used to run the 2026-05-26 estate sweep. They're filed alongside the human + machine campaign reports so the campaign is reproducible. See [`../2026-05-26.md`](../2026-05-26.md) for the report. - -## Scripts - -| Script | Purpose | -|---|---| -| `00-per-repo.sh` | Iterates top-level dirs with `.git/` and runs `panic-attack assail --headless` against each with a 90s timeout. Writes per-repo JSON to `/tmp/panic-attack-campaign-/per-repo/.json`. Pivot away from `assemblyline` so no single slow repo can stall the whole batch. | -| `00b-nested.sh` | Same scan loop but for nested-repo containers (`a2ml`, `awesome-projects`, `idaptik`, `isers`, `julia-libraries`, `k9`). Output filenames use `parent__child.json` to avoid collisions. | -| `01-triage.ts` | Deno script that reads per-repo JSONs and classifies into autofix / issue / proof-draft / skip buckets. Writes `02-plan.json`. | -| `file-ffi-pr-v2.sh` | Per-repo classification PR generator. Accepts `REPO_NAME`, `PREFIX_JSON` (JSON array of path prefixes), `SHORT_RATIONALE`, optional `CLASSIFICATION` (default `legitimate-ffi`). Builds the `audits/assail-classifications.a2ml` + audit doc, commits with the GPG override flags, pushes, opens a PR. **v2** uses `--argjson` + `any()` for the prefix filter (the v1 chained-OR form was broken under jq operator precedence). | - -## Known gotchas - -1. `file-ffi-pr-v2.sh` does `cat > audits/assail-classifications.a2ml` without checking whether the file already exists on `origin/main`. If it does, the existing entries get overwritten. **Always `git show origin/main:audits/assail-classifications.a2ml` before running the script**, and if entries exist, edit the script to preserve them. -2. Some repos are forks on GitHub with issues disabled (`linguist`, `rescript`, `HOL`) — Track A PRs land, but Track C tracking issues can't be filed. -3. Some repos are archived (`polystack`) or deleted (`hyperpolymath-archive`); skip them. -4. valence-shell-style local-only commits on `main` need branching from `origin/main` (not local `main`) to preserve them. - -## Re-running - -```sh -# Phase 1: per-repo scan (~10 min) -bash 00-per-repo.sh && bash 00b-nested.sh - -# Phase 1b: triage -deno run --allow-read --allow-write 01-triage.ts - -# Phase 2..N: per-repo PRs (one invocation per repo) -BRANCH=panic-fix/PA001-PA007-ffi-legitimate \ - bash file-ffi-pr-v2.sh \ - \ - '["src//", "ffi//"]' \ - "Rationale text..." \ - "legitimate-ffi" -``` - -The output JSONs and triage plan are NOT committed to the repo (they're ephemeral, scan-time-sensitive). See [`../2026-05-26.md`](../2026-05-26.md) for the persistent campaign record. diff --git a/docs/codebase-annotations.adoc b/docs/codebase-annotations.adoc new file mode 100644 index 0000000..0cf800e --- /dev/null +++ b/docs/codebase-annotations.adoc @@ -0,0 +1,140 @@ +== Codebase Annotation Map + +This document annotates the panic-attack codebase at an architectural +level so maintainers can trace data flow, intent, and operational +boundaries across modules. + +=== 1. Execution Topology + +* `+src/main.rs+` +** Owns CLI contract and command dispatch. +** Converts `+clap+` arguments into stable internal configs. +** Persists reports and decides user-facing output behavior. +* `+src/lib.rs+` +** Public module surface used by tests and external consumers. +** Keeps module-level integration boundaries explicit. + +=== 2. Analysis Pipeline + +* `+src/assail/+` +** Static source analysis over multiple language families. +** Produces `+AssailReport+` with weak points, recommendations, +dependency graph, and taint matrix. +** `+src/assail/analyzer.rs+`: decode + language-dispatch pipeline, +framework detection, dependency/taint overlays. +** `+src/assail/patterns.rs+`: language/framework attack pattern catalog +used by dynamic execution. +* `+src/attack/+` +** Dynamic axis execution (`+cpu+`, `+memory+`, `+disk+`, `+network+`, +`+concurrency+`, `+time+`). +** Handles probe mode and fallback behavior for unsupported target +flags. +** `+src/attack/executor.rs+`: strategy selection, timeout handling, +crash/signature extraction, probe-aware skip logic. +** `+src/attack/profile.rs+`: user profile ingestion (`+json+`/`+yaml+`) +for common and per-axis args. +* `+src/ambush/+` +** Timeline-driven ambient stress orchestration. +** Coordinates concurrent stressors with optional DAW-like event +scheduling. + +=== 3. Mutation and Isolation Surfaces + +* `+src/amuck/mod.rs+` +** Controlled mutation-combination runner. +** Writes per-combo artifacts and optional command outcomes. +** Never mutates target in place. +* `+src/abduct/mod.rs+` +** Isolated copy workspace and readonly lock-down. +** Optional dependency-neighborhood inclusion. +** mtime shifting and time metadata export for delayed-trigger +experiments. + +=== 4. Campaign Reasoning and Observation + +* `+src/adjudicate/mod.rs+` +** Aggregates `+assault+`, `+amuck+`, `+abduct+` artifacts. +** Asserts normalized facts then applies compact inference rules. +** Emits explainable campaign verdict (`+pass+`/`+warn+`/`+fail+`) plus +priorities. +* `+src/axial/mod.rs+` +** Observes target reactions from execution output and stored report +artifacts. +** Supports head/tail excerpts, exact/fuzzy pattern matches +(`+grep+`/`+agrep+`), aspell, i18n. +** Exports JSON + Markdown and optional Pandoc conversion. + +=== 5. Logic and Knowledge Layers + +* `+src/kanren/+` +** miniKanren-inspired term/fact/rule engine. +** Bridges static findings to derived facts via forward chaining. +** `+src/kanren/core.rs+`: unification, substitution, fact DB, fixpoint +forward-chaining. +** `+src/kanren/taint.rs+`: source/sink extraction and taint-propagation +rule loading. +** `+src/kanren/crosslang.rs+`: cross-language interaction facts and +boundary-risk inference. +** `+src/kanren/strategy.rs+`: risk-weighted file ordering heuristics +for verbose assail output. +** `+src/kanren/rules.rs+`: external rule-catalog loading and Nickel +export. +* `+src/signatures/+` +** Crash-signature detection and rule sets for known vulnerability +classes. + +=== 6. Reporting and Storage + +* `+src/report/+` +** Structured formatters, diff tools, TUI/GUI views, and serializers. +** Main conversion point for report presentation concerns. +** `+src/report/generator.rs+`: assault report synthesis and robustness +scoring heuristics. +** `+src/report/formatter.rs+`: summary/accordion/dashboard/matrix +terminal renderers. +** `+src/report/diff.rs+`: human-readable report delta generation for +regression review. +** `+src/report/output.rs+`: JSON/YAML/Nickel serialization contracts. +* `+src/storage/mod.rs+` +** Multi-target persistence logic (filesystem and VerisimDB-style cache +paths). + +=== 7. Manifest and Integration + +* `+src/a2ml/mod.rs+` +** Minimal A2ML parser for AI manifest ingestion. +** Nickel exporter for config interoperability. +** Includes schema-versioned A2ML report bundle import/export for +assail/attack/assault/ambush/amuck/abduct/adjudicate/axial. +* `+src/panll/mod.rs+` +** PanLL event-chain export adapter. + +=== 8. Cross-Cutting Contracts + +* Error strategy: +** `+anyhow+` with contextualized errors at IO/process boundaries. +* Serialization strategy: +** `+serde+` and JSON-first interchange, with YAML/Nickel where +relevant. +* Safety strategy: +** Copy-first workflows for destructive experimentation (`+amuck+`, +`+abduct+`). +** Timeouts on process execution paths to avoid hanging campaigns. + +=== 9. Extension Points + +* Add new inference rules: +** `+src/adjudicate/mod.rs+` for campaign-level verdict logic. +** `+src/kanren/+` for deeper relational inference. +* Add new observation signals: +** `+src/axial/mod.rs::detect_signals+`. +* Add new mutation primitives: +** `+src/amuck/mod.rs::MutationOperation+`. +* Add new isolation semantics: +** `+src/abduct/mod.rs+` dependency scope and workspace policies. + +=== 10. Annotation Conventions Used + +* Module docs describe responsibility boundaries. +* Function comments explain non-obvious decisions and invariants. +* Export docs highlight contract shape for downstream tooling. diff --git a/docs/codebase-annotations.md b/docs/codebase-annotations.md deleted file mode 100644 index 32e4bd6..0000000 --- a/docs/codebase-annotations.md +++ /dev/null @@ -1,117 +0,0 @@ - - - -# Codebase Annotation Map - -This document annotates the panic-attack codebase at an architectural level so maintainers can -trace data flow, intent, and operational boundaries across modules. - -## 1. Execution Topology - -- `src/main.rs` - - Owns CLI contract and command dispatch. - - Converts `clap` arguments into stable internal configs. - - Persists reports and decides user-facing output behavior. -- `src/lib.rs` - - Public module surface used by tests and external consumers. - - Keeps module-level integration boundaries explicit. - -## 2. Analysis Pipeline - -- `src/assail/` - - Static source analysis over multiple language families. - - Produces `AssailReport` with weak points, recommendations, dependency graph, and taint matrix. - - `src/assail/analyzer.rs`: decode + language-dispatch pipeline, framework detection, dependency/taint overlays. - - `src/assail/patterns.rs`: language/framework attack pattern catalog used by dynamic execution. -- `src/attack/` - - Dynamic axis execution (`cpu`, `memory`, `disk`, `network`, `concurrency`, `time`). - - Handles probe mode and fallback behavior for unsupported target flags. - - `src/attack/executor.rs`: strategy selection, timeout handling, crash/signature extraction, probe-aware skip logic. - - `src/attack/profile.rs`: user profile ingestion (`json`/`yaml`) for common and per-axis args. -- `src/ambush/` - - Timeline-driven ambient stress orchestration. - - Coordinates concurrent stressors with optional DAW-like event scheduling. - -## 3. Mutation and Isolation Surfaces - -- `src/amuck/mod.rs` - - Controlled mutation-combination runner. - - Writes per-combo artifacts and optional command outcomes. - - Never mutates target in place. -- `src/abduct/mod.rs` - - Isolated copy workspace and readonly lock-down. - - Optional dependency-neighborhood inclusion. - - mtime shifting and time metadata export for delayed-trigger experiments. - -## 4. Campaign Reasoning and Observation - -- `src/adjudicate/mod.rs` - - Aggregates `assault`, `amuck`, `abduct` artifacts. - - Asserts normalized facts then applies compact inference rules. - - Emits explainable campaign verdict (`pass`/`warn`/`fail`) plus priorities. -- `src/axial/mod.rs` - - Observes target reactions from execution output and stored report artifacts. - - Supports head/tail excerpts, exact/fuzzy pattern matches (`grep`/`agrep`), aspell, i18n. - - Exports JSON + Markdown and optional Pandoc conversion. - -## 5. Logic and Knowledge Layers - -- `src/kanren/` - - miniKanren-inspired term/fact/rule engine. - - Bridges static findings to derived facts via forward chaining. - - `src/kanren/core.rs`: unification, substitution, fact DB, fixpoint forward-chaining. - - `src/kanren/taint.rs`: source/sink extraction and taint-propagation rule loading. - - `src/kanren/crosslang.rs`: cross-language interaction facts and boundary-risk inference. - - `src/kanren/strategy.rs`: risk-weighted file ordering heuristics for verbose assail output. - - `src/kanren/rules.rs`: external rule-catalog loading and Nickel export. -- `src/signatures/` - - Crash-signature detection and rule sets for known vulnerability classes. - -## 6. Reporting and Storage - -- `src/report/` - - Structured formatters, diff tools, TUI/GUI views, and serializers. - - Main conversion point for report presentation concerns. - - `src/report/generator.rs`: assault report synthesis and robustness scoring heuristics. - - `src/report/formatter.rs`: summary/accordion/dashboard/matrix terminal renderers. - - `src/report/diff.rs`: human-readable report delta generation for regression review. - - `src/report/output.rs`: JSON/YAML/Nickel serialization contracts. -- `src/storage/mod.rs` - - Multi-target persistence logic (filesystem and VerisimDB-style cache paths). - -## 7. Manifest and Integration - -- `src/a2ml/mod.rs` - - Minimal A2ML parser for AI manifest ingestion. - - Nickel exporter for config interoperability. - - Includes schema-versioned A2ML report bundle import/export for assail/attack/assault/ambush/amuck/abduct/adjudicate/axial. -- `src/panll/mod.rs` - - PanLL event-chain export adapter. - -## 8. Cross-Cutting Contracts - -- Error strategy: - - `anyhow` with contextualized errors at IO/process boundaries. -- Serialization strategy: - - `serde` and JSON-first interchange, with YAML/Nickel where relevant. -- Safety strategy: - - Copy-first workflows for destructive experimentation (`amuck`, `abduct`). - - Timeouts on process execution paths to avoid hanging campaigns. - -## 9. Extension Points - -- Add new inference rules: - - `src/adjudicate/mod.rs` for campaign-level verdict logic. - - `src/kanren/` for deeper relational inference. -- Add new observation signals: - - `src/axial/mod.rs::detect_signals`. -- Add new mutation primitives: - - `src/amuck/mod.rs::MutationOperation`. -- Add new isolation semantics: - - `src/abduct/mod.rs` dependency scope and workspace policies. - -## 10. Annotation Conventions Used - -- Module docs describe responsibility boundaries. -- Function comments explain non-obvious decisions and invariants. -- Export docs highlight contract shape for downstream tooling. diff --git a/docs/json-schema.md b/docs/json-schema.adoc similarity index 73% rename from docs/json-schema.md rename to docs/json-schema.adoc index f55a189..acbaa0a 100644 --- a/docs/json-schema.md +++ b/docs/json-schema.adoc @@ -1,10 +1,11 @@ -# panic-attack JSON Output Schema +== panic-attack JSON Output Schema Version: 1.0 (stable as of v1.0.0) -## AssailReport +=== AssailReport -```json +[source,json] +---- { "program_path": "string (path)", "language": "string (rust|c|cpp|go|java|python|javascript|ruby|unknown)", @@ -14,11 +15,12 @@ Version: 1.0 (stable as of v1.0.0) "file_statistics": [FileStatistics], "recommended_attacks": ["string (cpu|memory|disk|network|concurrency|time)"] } -``` +---- -## WeakPoint +=== WeakPoint -```json +[source,json] +---- { "category": "string (uncheckedallocation|unboundedloop|blockingio|unsafecode|panicpath|racecondition|deadlockpotential|resourceleak)", "location": "string|null (file path)", @@ -26,11 +28,12 @@ Version: 1.0 (stable as of v1.0.0) "description": "string", "recommended_attack": ["string (cpu|memory|disk|network|concurrency|time)"] } -``` +---- -## ProgramStatistics +=== ProgramStatistics -```json +[source,json] +---- { "total_lines": "number", "unsafe_blocks": "number", @@ -40,11 +43,12 @@ Version: 1.0 (stable as of v1.0.0) "io_operations": "number", "threading_constructs": "number" } -``` +---- -## FileStatistics +=== FileStatistics -```json +[source,json] +---- { "file_path": "string", "lines": "number", @@ -55,11 +59,12 @@ Version: 1.0 (stable as of v1.0.0) "io_operations": "number", "threading_constructs": "number" } -``` +---- -## AssaultReport +=== AssaultReport -```json +[source,json] +---- { "assail_report": AssailReport, "attack_results": [AttackResult], @@ -68,11 +73,12 @@ Version: 1.0 (stable as of v1.0.0) "overall_assessment": OverallAssessment, "timeline": "TimelineReport|null" } -``` +---- -## AttackResult +=== AttackResult -```json +[source,json] +---- { "program": "string (path)", "axis": "string (cpu|memory|disk|network|concurrency|time)", @@ -83,11 +89,12 @@ Version: 1.0 (stable as of v1.0.0) "crashes": [CrashReport], "signatures_detected": [BugSignature] } -``` +---- -## CrashReport +=== CrashReport -```json +[source,json] +---- { "timestamp": "string (RFC3339)", "signal": "string|null", @@ -95,41 +102,45 @@ Version: 1.0 (stable as of v1.0.0) "stderr": "string", "stdout": "string" } -``` +---- -## BugSignature +=== BugSignature -```json +[source,json] +---- { "signature_type": "string (useafterfree|doublefree|memoryleak|deadlock|datarace|bufferoverflow|integeroverflow|nullpointerderef|unhandlederror)", "confidence": "number (0.0-1.0)", "evidence": ["string"], "location": "string|null" } -``` +---- -## OverallAssessment +=== OverallAssessment -```json +[source,json] +---- { "robustness_score": "number (0.0-100.0)", "critical_issues": ["string"], "recommendations": ["string"] } -``` +---- -## TimelineReport (optional) +=== TimelineReport (optional) -```json +[source,json] +---- { "duration": {"secs": "number", "nanos": "number"}, "events": [TimelineEventReport] } -``` +---- -## TimelineEventReport +=== TimelineEventReport -```json +[source,json] +---- { "id": "string", "axis": "string (cpu|memory|disk|network|concurrency|time)", @@ -140,20 +151,24 @@ Version: 1.0 (stable as of v1.0.0) "peak_memory": "number|null (bytes)", "ran": "boolean" } -``` +---- -## Version Compatibility +=== Version Compatibility -- **v0.1.0**: Initial schema (unstable) -- **v0.2.0**: Added `file_statistics` field to AssailReport, all locations guaranteed non-null -- **v1.0.0**: Schema stabilized, backwards-compatible changes only from here -- **Future**: New fields may be added, but existing fields will not change type or be removed +* *v0.1.0*: Initial schema (unstable) +* *v0.2.0*: Added `+file_statistics+` field to AssailReport, all +locations guaranteed non-null +* *v1.0.0*: Schema stabilized, backwards-compatible changes only from +here +* *Future*: New fields may be added, but existing fields will not change +type or be removed -## Consuming the Schema +=== Consuming the Schema -### Python +==== Python -```python +[source,python] +---- import json with open("assail-report.json") as f: @@ -161,11 +176,12 @@ with open("assail-report.json") as f: for wp in report["weak_points"]: print(f"{wp['severity']}: {wp['description']} @ {wp['location']}") -``` +---- -### Rust +==== Rust -```rust +[source,rust] +---- use panic_attacker::types::AssailReport; let json = std::fs::read_to_string("assail-report.json")?; @@ -174,11 +190,12 @@ let report: AssailReport = serde_json::from_str(&json)?; for wp in &report.weak_points { println!("{:?}: {} @ {:?}", wp.severity, wp.description, wp.location); } -``` +---- -### JavaScript/TypeScript +==== JavaScript/TypeScript -```typescript +[source,typescript] +---- import * as fs from 'fs'; const report = JSON.parse(fs.readFileSync('assail-report.json', 'utf8')); @@ -186,16 +203,15 @@ const report = JSON.parse(fs.readFileSync('assail-report.json', 'utf8')); report.weak_points.forEach((wp: any) => { console.log(`${wp.severity}: ${wp.description} @ ${wp.location}`); }); -``` +---- -## Breaking Changes Policy +=== Breaking Changes Policy -Starting with v1.0.0: -- **MAJOR version**: Breaking changes to schema (removed fields, changed types) -- **MINOR version**: Backwards-compatible additions (new fields, new enum values) -- **PATCH version**: No schema changes +Starting with v1.0.0: - *MAJOR version*: Breaking changes to schema +(removed fields, changed types) - *MINOR version*: Backwards-compatible +additions (new fields, new enum values) - *PATCH version*: No schema +changes -## SPDX License +=== SPDX License SPDX-License-Identifier: CC-BY-SA-4.0 - diff --git a/docs/panll-export.adoc b/docs/panll-export.adoc new file mode 100644 index 0000000..9cba099 --- /dev/null +++ b/docs/panll-export.adoc @@ -0,0 +1,88 @@ +== PanLL Export (Event-Chain Bridge) + +`+panic-attack+` can export an assault report into a lightweight +PanLL-compatible event-chain model. This gives PanLL a stable input +describing stress events, timing, and outcomes without forcing a heavy +schema dependency. + +=== Command + +[source,bash] +---- +panic-attack panll path/to/assault-report.json --output panll-event-chain.json +---- + +=== Format (v0) + +[source,json] +---- +{ + "format": "panll.event-chain.v0", + "generated_at": "2026-02-09T19:12:00Z", + "source": { + "tool": "panic-attack", + "report_path": "reports/assault-report.json" + }, + "summary": { + "program": "/path/to/target", + "weak_points": 7, + "critical_weak_points": 1, + "total_crashes": 2, + "robustness_score": 63.5 + }, + "timeline": { + "duration_ms": 120000, + "events": 5 + }, + "event_chain": [ + { + "id": "cpu-1", + "axis": "cpu", + "start_ms": 0, + "duration_ms": 30000, + "intensity": "Heavy", + "status": "ran", + "peak_memory": null, + "notes": null + } + ], + "constraints": [] +} +---- + +Notes: - If the report includes ambush timeline metadata, the +`+event_chain+` is derived from timeline events. - Otherwise, each +attack result becomes a single event entry with `+start_ms+` unset and +`+intensity = "unknown"+`. + +=== Next Steps + +Future versions can enrich this export with constraints, event +dependencies, and a full PanLL graph import/export pipeline. + +=== Groove discovery + +panic-attack also advertises its export capability through the Gossamer +groove protocol so PanLL and other groove-aware systems can discover it +automatically. Run `+panic-attack groove --port 7600+` and curl +`+http://localhost:7600/.well-known/groove+` to verify the manifest. The +minimal HTTP server answers `+/health+` for automated monitoring, and +gossamer/panll consumers can read the `+static_analysis+` capability +description to confirm the service identity. + +The JSON manifest mirrors the Idris-aligned semantics under +`+boj-server/src/interface/abi/Groove.idr+` and the shared +`+gossamer/schema+` definitions, so every consumer (Gossamer, PanLL, +Hypatia, or Burble) sees the same capability vocabulary and can +negotiate the link with confidence. + +=== Gossamer + Burble PanLL + +When Gossamer (or a Burble-powered PanLL UI) discovers panic-attack via +groove, PanLL panels can auto-bind the static analysis service into +PanLL’s event-chain flows. Those panels load the exported +`+panll.event-chain.v0+` artifacts documented here, referencing the same +VeriSimDB snapshot that supplies every proof and benchmark baseline. +VeriSimDB acts as the foundation dependency so the historical timeline +that PanLL renders stays aligned with the grooved manifest even after +panic-attack exits. diff --git a/docs/panll-export.md b/docs/panll-export.md deleted file mode 100644 index 9af0cd8..0000000 --- a/docs/panll-export.md +++ /dev/null @@ -1,87 +0,0 @@ - - - -# PanLL Export (Event-Chain Bridge) - -`panic-attack` can export an assault report into a lightweight PanLL-compatible -event-chain model. This gives PanLL a stable input describing stress events, -timing, and outcomes without forcing a heavy schema dependency. - -## Command - -```bash -panic-attack panll path/to/assault-report.json --output panll-event-chain.json -``` - -## Format (v0) - -```json -{ - "format": "panll.event-chain.v0", - "generated_at": "2026-02-09T19:12:00Z", - "source": { - "tool": "panic-attack", - "report_path": "reports/assault-report.json" - }, - "summary": { - "program": "/path/to/target", - "weak_points": 7, - "critical_weak_points": 1, - "total_crashes": 2, - "robustness_score": 63.5 - }, - "timeline": { - "duration_ms": 120000, - "events": 5 - }, - "event_chain": [ - { - "id": "cpu-1", - "axis": "cpu", - "start_ms": 0, - "duration_ms": 30000, - "intensity": "Heavy", - "status": "ran", - "peak_memory": null, - "notes": null - } - ], - "constraints": [] -} -``` - -Notes: -- If the report includes ambush timeline metadata, the `event_chain` is derived - from timeline events. -- Otherwise, each attack result becomes a single event entry with `start_ms` - unset and `intensity = "unknown"`. - -## Next Steps - -Future versions can enrich this export with constraints, event dependencies, -and a full PanLL graph import/export pipeline. - -## Groove discovery - -panic-attack also advertises its export capability through the Gossamer groove -protocol so PanLL and other groove-aware systems can discover it automatically. -Run `panic-attack groove --port 7600` and curl -`http://localhost:7600/.well-known/groove` to verify the manifest. The minimal -HTTP server answers `/health` for automated monitoring, and gossamer/panll -consumers can read the `static_analysis` capability description to confirm the -service identity. - -The JSON manifest mirrors the Idris-aligned semantics under -`boj-server/src/interface/abi/Groove.idr` and the shared `gossamer/schema` -definitions, so every consumer (Gossamer, PanLL, Hypatia, or Burble) sees the -same capability vocabulary and can negotiate the link with confidence. - -## Gossamer + Burble PanLL - -When Gossamer (or a Burble-powered PanLL UI) discovers panic-attack via groove, -PanLL panels can auto-bind the static analysis service into PanLL’s event-chain -flows. Those panels load the exported `panll.event-chain.v0` artifacts documented -here, referencing the same VeriSimDB snapshot that supplies every proof and -benchmark baseline. VeriSimDB acts as the foundation dependency so the historical -timeline that PanLL renders stays aligned with the grooved manifest even after -panic-attack exits. diff --git a/docs/patch-bridge-design.md b/docs/patch-bridge-design.adoc similarity index 59% rename from docs/patch-bridge-design.md rename to docs/patch-bridge-design.adoc index 2f5efa6..b289c9c 100644 --- a/docs/patch-bridge-design.md +++ b/docs/patch-bridge-design.adoc @@ -1,68 +1,81 @@ - - - -# Patch Bridge — Design Document - -**Status**: Draft v0.1.0 -**Author**: Jonathan D.A. Jewell -**Date**: 2026-03-21 -**Position**: Subcommand family within `panic-attack`, with PanLL panel and BoJ cartridge - ---- - -## 1. Problem Statement - -When a CVE is disclosed against an upstream dependency, developers face a gap between -disclosure and fix. Current tooling (Trivy, Grype, Snyk, OSV-Scanner, `cargo audit`) -detects the CVE but offers no systematic mitigation, no lifecycle management, and no -contextual risk assessment. Developers are left to: - -1. Manually search for workarounds -2. Assess severity using generic CVSS scores that ignore their specific code paths -3. Apply ad-hoc fixes with no proof of correctness -4. Forget to remove mitigations when upstream patches land -5. Miss concatenative risks where low-severity CVEs combine to create critical exposure - -**Patch Bridge** closes this gap by providing: - -- **Multi-source CVE intelligence** with bubble detection (the "Ground News" model) -- **Contextual risk assessment** using the existing miniKanren taint/crosslang engines -- **Formally verified mitigations** via Idris2 dependent types -- **Unmitigability proofs** — machine-checked evidence that no layered control suffices -- **Concatenative danger detection** — identifying CVE combinations that multiply risk -- **Lifecycle management** — apply, monitor, auto-retire when upstream fixes land -- **Developer interview mode** — guided flow-charting to build accurate data-flow models -- **Adoption gate** — risk assessment *before* adding a dependency -- **Upstream feedback** — contributing proven mitigations back to maintainers -- **Cross-domain translation** — explaining threats in the developer's own conceptual framework - ---- - -## 1a. Standalone Tool Principle - -**Patch Bridge is a CLI tool first.** It works entirely from the command line -as `panic-attack bridge `. No GUI, no PanLL, no BoJ required. - -The PanLL panel and BoJ cartridge are **optional integrations** that hook onto -the standalone tool via the existing PanLL clade system. This means: - -- **panic-attack** gains CVE mitigation without any PanLL dependency -- **PanLL** gains a security panel without any panic-attack code changes -- Either can be removed, upgraded, or disabled without breaking the other -- The clade inheritance system handles capability negotiation - -### How the hookup works (PanLL clade architecture) - -PanLL's existing infrastructure makes this clean: - -1. **Minter** creates the panel scaffolding (Model, Engine, Cmd, Component) -2. **Provisioner** adds it to the "security-ops" portfolio (or any custom portfolio) -3. **EnsaidConfig** enables/disables it per-repo via `[[panels.enabled]]` -4. **Clade Browser** shows it in the taxonomy with inherited traits +== Patch Bridge — Design Document + +*Status*: Draft v0.1.0 *Author*: Jonathan D.A. Jewell *Date*: 2026-03-21 +*Position*: Subcommand family within `+panic-attack+`, with PanLL panel +and BoJ cartridge + +''''' + +=== 1. Problem Statement + +When a CVE is disclosed against an upstream dependency, developers face +a gap between disclosure and fix. Current tooling (Trivy, Grype, Snyk, +OSV-Scanner, `+cargo audit+`) detects the CVE but offers no systematic +mitigation, no lifecycle management, and no contextual risk assessment. +Developers are left to: + +[arabic] +. Manually search for workarounds +. Assess severity using generic CVSS scores that ignore their specific +code paths +. Apply ad-hoc fixes with no proof of correctness +. Forget to remove mitigations when upstream patches land +. Miss concatenative risks where low-severity CVEs combine to create +critical exposure + +*Patch Bridge* closes this gap by providing: + +* *Multi-source CVE intelligence* with bubble detection (the "`Ground +News`" model) +* *Contextual risk assessment* using the existing miniKanren +taint/crosslang engines +* *Formally verified mitigations* via Idris2 dependent types +* *Unmitigability proofs* — machine-checked evidence that no layered +control suffices +* *Concatenative danger detection* — identifying CVE combinations that +multiply risk +* *Lifecycle management* — apply, monitor, auto-retire when upstream +fixes land +* *Developer interview mode* — guided flow-charting to build accurate +data-flow models +* *Adoption gate* — risk assessment _before_ adding a dependency +* *Upstream feedback* — contributing proven mitigations back to +maintainers +* *Cross-domain translation* — explaining threats in the developer’s own +conceptual framework + +''''' + +=== 1a. Standalone Tool Principle + +*Patch Bridge is a CLI tool first.* It works entirely from the command +line as `+panic-attack bridge +`. No GUI, no PanLL, no BoJ +required. + +The PanLL panel and BoJ cartridge are *optional integrations* that hook +onto the standalone tool via the existing PanLL clade system. This +means: + +* *panic-attack* gains CVE mitigation without any PanLL dependency +* *PanLL* gains a security panel without any panic-attack code changes +* Either can be removed, upgraded, or disabled without breaking the +other +* The clade inheritance system handles capability negotiation + +==== How the hookup works (PanLL clade architecture) + +PanLL’s existing infrastructure makes this clean: + +[arabic] +. *Minter* creates the panel scaffolding (Model, Engine, Cmd, Component) +. *Provisioner* adds it to the "`security-ops`" portfolio (or any custom +portfolio) +. *EnsaidConfig* enables/disables it per-repo via `+[[panels.enabled]]+` +. *Clade Browser* shows it in the taxonomy with inherited traits The Patch Bridge panel would register as: -``` +.... clade: patch-bridge kind: scanner parentCladeId: Some("scanner") // inherits scanner traits @@ -71,20 +84,20 @@ enhances: ["security", "provisioner"] protocols: [ProtoTauriIPC, ProtoREST] capabilities: [CapSecurityScan, CapNetwork, CapFilesystem] isolation: IsolationSoft // default, overridable per-repo -``` +.... -This inherits `hasBackend: true` and `hasWorkItems: true` from the scanner -parent clade via PanLL's trait inheritance (OR merge, line 449 of -`CladeBrowserEngine.res`). The clade permission system gates cross-panel -event delivery, so the Patch Bridge panel can receive events from -panic-attack and Hypatia panels but cannot modify the Workspace panel -without explicit permission. +This inherits `+hasBackend: true+` and `+hasWorkItems: true+` from the +scanner parent clade via PanLL’s trait inheritance (OR merge, line 449 +of `+CladeBrowserEngine.res+`). The clade permission system gates +cross-panel event delivery, so the Patch Bridge panel can receive events +from panic-attack and Hypatia panels but cannot modify the Workspace +panel without explicit permission. ---- +''''' -## 2. Architecture Overview +=== 2. Architecture Overview -``` +.... ┌──────────────────────────────────────┐ │ CVE INTELLIGENCE │ │ (Multi-Source Feeds) │ @@ -162,34 +175,54 @@ without explicit permission. │ - Attach Idris2 soundness proof │ │ - Track upstream adoption │ └──────────────────────────────────────┘ -``` +.... + +''''' + +=== 3. Integration with Existing panic-attack Infrastructure + +Patch Bridge is *not* a separate tool. It extends panic-attack’s +existing capabilities with new subcommands and new modules that compose +with the miniKanren engine, taint analysis, and cross-language +reasoning. + +==== 3.1 Existing infrastructure reused ---- +[width="100%",cols="26%,23%,51%",options="header",] +|=== +|Component |Location |Reuse in Patch Bridge +|miniKanren core |`+src/kanren/core.rs+` |FactDB for CVE facts, forward +chaining for concatenative analysis -## 3. Integration with Existing panic-attack Infrastructure +|Taint analysis |`+src/kanren/taint.rs+` |Source→sink tracking to +determine if a CVE is reachable -Patch Bridge is **not** a separate tool. It extends panic-attack's existing -capabilities with new subcommands and new modules that compose with the -miniKanren engine, taint analysis, and cross-language reasoning. +|Cross-language |`+src/kanren/crosslang.rs+` |FFI/NIF boundary analysis +for cross-language CVE chains -### 3.1 Existing infrastructure reused +|Search strategy |`+src/kanren/strategy.rs+` |Risk-weighted +prioritisation of which CVEs to assess first -| Component | Location | Reuse in Patch Bridge | -|-----------|----------|----------------------| -| miniKanren core | `src/kanren/core.rs` | FactDB for CVE facts, forward chaining for concatenative analysis | -| Taint analysis | `src/kanren/taint.rs` | Source→sink tracking to determine if a CVE is reachable | -| Cross-language | `src/kanren/crosslang.rs` | FFI/NIF boundary analysis for cross-language CVE chains | -| Search strategy | `src/kanren/strategy.rs` | Risk-weighted prioritisation of which CVEs to assess first | -| Signatures | `src/signatures/` | Bug signature patterns to match CVE vulnerability classes | -| Attestation | `src/attestation/` | Cryptographic proof chain for mitigation verification | -| VeriSimDB | `src/storage/` | Hexad persistence for mitigation registry | -| PanLL export | `src/panll/` | Event-chain model for panel visualisation | -| Assemblyline | `src/assemblyline.rs` | Batch CVE assessment across org repos | -| Notify | `src/notify.rs` | Alerts on unmitigable CVEs, upstream fix availability | +|Signatures |`+src/signatures/+` |Bug signature patterns to match CVE +vulnerability classes -### 3.2 New modules +|Attestation |`+src/attestation/+` |Cryptographic proof chain for +mitigation verification -``` +|VeriSimDB |`+src/storage/+` |Hexad persistence for mitigation registry + +|PanLL export |`+src/panll/+` |Event-chain model for panel visualisation + +|Assemblyline |`+src/assemblyline.rs+` |Batch CVE assessment across org +repos + +|Notify |`+src/notify.rs+` |Alerts on unmitigable CVEs, upstream fix +availability +|=== + +==== 3.2 New modules + +.... src/ ├── bridge/ # Patch Bridge core │ ├── mod.rs # Public API @@ -204,11 +237,11 @@ src/ │ ├── concatenate.rs # CVE×CVE interaction analysis │ ├── translate.rs # Cross-domain threat translation │ └── upstream.rs # Upstream feedback (PR generation, proof export) -``` +.... -### 3.3 New subcommands +==== 3.3 New subcommands -``` +.... panic-attack bridge # Full Patch Bridge assessment panic-attack bridge intel # Multi-source CVE intelligence report panic-attack bridge gate # Pre-adoption risk assessment @@ -218,52 +251,42 @@ panic-attack bridge mitigate # Generate + apply mitigations panic-attack bridge status # Active mitigation registry panic-attack bridge retire # Check for upstream fixes, retire mitigations panic-attack bridge upstream # Generate upstream contribution -``` - ---- - -## 4. Multi-Source CVE Intelligence - -### 4.1 Source tiers - -**Tier 1 — Standard advisories** (polled every 6 hours): -- National Vulnerability Database (NVD) via REST API -- GitHub Security Advisories (GHSA) via GraphQL -- Open Source Vulnerabilities (OSV) via API -- Vendor-specific: Microsoft, Red Hat, Canonical - -**Tier 2 — Community intelligence** (polled every 2 hours): -- VirusTotal file/hash reports + community comments (API v3) -- ExploitDB / Packet Storm (scrape or mirror) -- Language-ecosystem advisories: - - RustSec (rustsec-advisory-db) - - npm advisories (via registry API) - - Hex advisories (Elixir/Erlang) - - PyPI/safety-db (legacy, for migration tracking) - - Go vulndb -- Distro security trackers: - - Debian Security Tracker - - Fedora Bodhi - - Alpine SecDB - - SUSE/openSUSE - -**Tier 3 — Long tail** (polled daily): -- oss-security mailing list archive -- Full Disclosure mailing list -- arXiv cs.CR (security pre-prints) -- USENIX Security / IEEE S&P proceedings -- Upstream commit analysis: scan recent commits in dependency repos for - security-related keywords (`CVE`, `security`, `vulnerability`, `buffer`, - `overflow`, `injection`, `traversal`, `bypass`) — the fix often lands - before the CVE is assigned -- Bug bounty public disclosures (HackerOne, Bugcrowd public reports) -- CWE database (for vulnerability class mapping) - -### 4.2 Bubble rating - -Each CVE receives a **coverage vector** indicating which source tiers report it: - -``` +.... + +''''' + +=== 4. Multi-Source CVE Intelligence + +==== 4.1 Source tiers + +*Tier 1 — Standard advisories* (polled every 6 hours): - National +Vulnerability Database (NVD) via REST API - GitHub Security Advisories +(GHSA) via GraphQL - Open Source Vulnerabilities (OSV) via API - +Vendor-specific: Microsoft, Red Hat, Canonical + +*Tier 2 — Community intelligence* (polled every 2 hours): - VirusTotal +file/hash reports + community comments (API v3) - ExploitDB / Packet +Storm (scrape or mirror) - Language-ecosystem advisories: - RustSec +(rustsec-advisory-db) - npm advisories (via registry API) - Hex +advisories (Elixir/Erlang) - PyPI/safety-db (legacy, for migration +tracking) - Go vulndb - Distro security trackers: - Debian Security +Tracker - Fedora Bodhi - Alpine SecDB - SUSE/openSUSE + +*Tier 3 — Long tail* (polled daily): - oss-security mailing list archive +- Full Disclosure mailing list - arXiv cs.CR (security pre-prints) - +USENIX Security / IEEE S&P proceedings - Upstream commit analysis: scan +recent commits in dependency repos for security-related keywords +(`+CVE+`, `+security+`, `+vulnerability+`, `+buffer+`, `+overflow+`, +`+injection+`, `+traversal+`, `+bypass+`) — the fix often lands before +the CVE is assigned - Bug bounty public disclosures (HackerOne, Bugcrowd +public reports) - CWE database (for vulnerability class mapping) + +==== 4.2 Bubble rating + +Each CVE receives a *coverage vector* indicating which source tiers +report it: + +.... CVE-2026-XXXX Tier 1: ████░░ (NVD: yes, GHSA: yes, OSV: no, vendor: no) Tier 2: ██████ (VT: yes, ExploitDB: yes, RustSec: yes) @@ -273,20 +296,21 @@ CVE-2026-XXXX Bubble risk: MODERATE — you're missing upstream commit analysis and vendor advisory. VirusTotal community has 2 exploit PoCs not mentioned in NVD description. -``` +.... -**Bubble warnings** fire when: -- A CVE appears in Tier 2/3 but NOT Tier 1 (early warning) -- Exploit PoCs exist in community sources but official advisory says "no known exploits" -- Severity ratings diverge significantly between sources -- A vulnerability class has been discussed in academic literature but no CVE exists yet +*Bubble warnings* fire when: - A CVE appears in Tier 2/3 but NOT Tier 1 +(early warning) - Exploit PoCs exist in community sources but official +advisory says "`no known exploits`" - Severity ratings diverge +significantly between sources - A vulnerability class has been discussed +in academic literature but no CVE exists yet -### 4.3 Cross-domain translation +==== 4.3 Cross-domain translation -When reporting a CVE to a developer, Patch Bridge adapts the explanation to their -language ecosystem: +When reporting a CVE to a developer, Patch Bridge adapts the explanation +to their language ecosystem: -```rust +[source,rust] +---- /// Cross-domain threat translation /// /// Maps vulnerability classes to concepts familiar in the target language. @@ -299,27 +323,42 @@ pub struct ThreatTranslator { /// Known conceptual gaps for this ecosystem blind_spots: Vec, } -``` +---- + +*Translation examples:* + +[width="100%",cols="19%,21%,28%,32%",options="header",] +|=== +|Vuln class |To C developer |To Elixir developer |To ReScript developer +|Buffer overflow |"`You know this one — but did you know linear types +prevent this class entirely?`" |"`Your NIF dependency has this. BEAM +isolation does NOT help — NIFs run in scheduler threads.`" |"`Your JS +FFI calls a native module with this. ReScript’s type safety stops at the +FFI boundary.`" -**Translation examples:** +|Deserialization |"`Marshal/pickle equivalent — untrusted data becomes +executable.`" |"``+:erlang.binary_to_term+` with untrusted input. Use +`+:safe+` option or proven/binary_decoder.`" |"`JSON.parse is safe for +data, but your dep deserializes into executable structures.`" -| Vuln class | To C developer | To Elixir developer | To ReScript developer | -|------------|---------------|--------------------|-----------------------| -| Buffer overflow | "You know this one — but did you know linear types prevent this class entirely?" | "Your NIF dependency has this. BEAM isolation does NOT help — NIFs run in scheduler threads." | "Your JS FFI calls a native module with this. ReScript's type safety stops at the FFI boundary." | -| Deserialization | "Marshal/pickle equivalent — untrusted data becomes executable." | "`:erlang.binary_to_term` with untrusted input. Use `:safe` option or proven/binary_decoder." | "JSON.parse is safe for data, but your dep deserializes into executable structures." | -| Race condition | "You know mutexes. But your dep uses lock-free structures with a known ABA problem." | "Unusual here, but this dep uses a NIF with mutable global state — breaks your concurrency guarantees." | "Your ReScript is safe, but the JS interop target has shared mutable state in a worker." | +|Race condition |"`You know mutexes. But your dep uses lock-free +structures with a known ABA problem.`" |"`Unusual here, but this dep +uses a NIF with mutable global state — breaks your concurrency +guarantees.`" |"`Your ReScript is safe, but the JS interop target has +shared mutable state in a worker.`" +|=== ---- +''''' -## 5. Contextual Risk Assessment +=== 5. Contextual Risk Assessment -### 5.1 Reachability analysis (existing kanren taint engine) +==== 5.1 Reachability analysis (existing kanren taint engine) -The existing taint analysis in `src/kanren/taint.rs` already tracks -source→sink flows. Patch Bridge extends this by matching CVE vulnerability -classes to taint sink categories: +The existing taint analysis in `+src/kanren/taint.rs+` already tracks +source→sink flows. Patch Bridge extends this by matching CVE +vulnerability classes to taint sink categories: -``` +.... CVE vulnerability class → TaintSink mapping ─────────────────────────────────────────────── Command injection → ShellCommand, CodeExecution @@ -329,20 +368,20 @@ Deserialization attack → DeserializeSink XSS → NetworkWrite Buffer overflow → MemoryOperation, UnsafeCast Atom exhaustion → AtomCreation -``` +.... -If no taint flow reaches the CVE's vulnerability class sink, the CVE is -**contextually unreachable** — informational only. +If no taint flow reaches the CVE’s vulnerability class sink, the CVE is +*contextually unreachable* — informational only. -If a taint flow DOES reach it, Patch Bridge reports the exact source→sink -path through the developer's code. +If a taint flow DOES reach it, Patch Bridge reports the exact +source→sink path through the developer’s code. -### 5.2 Developer interview mode +==== 5.2 Developer interview mode Static taint analysis is imperfect. Patch Bridge supplements it with a -guided interview that builds a **flow chart artifact**: +guided interview that builds a *flow chart artifact*: -``` +.... $ panic-attack bridge flow Patch Bridge Flow Interview @@ -371,12 +410,13 @@ handle untrusted input. [2/5] You depend on `image` (v0.25.1). How does untrusted data reach image processing? ... -``` +.... -The interview produces a **flow chart artifact** stored in -`.machine_readable/patch-bridge/flows.scm`: +The interview produces a *flow chart artifact* stored in +`+.machine_readable/patch-bridge/flows.scm+`: -```scheme +[source,scheme] +---- (flow-chart (version "0.1.0") (project "my-project") @@ -394,48 +434,50 @@ The interview produces a **flow chart artifact** stored in (sources (file-upload)) (trust-level untrusted) (notes "User-uploaded avatars, max 5MB enforced at proxy")))) -``` +---- -This artifact persists across sessions. When new CVEs are disclosed, Patch -Bridge re-evaluates against the stored flows without re-interviewing. +This artifact persists across sessions. When new CVEs are disclosed, +Patch Bridge re-evaluates against the stored flows without +re-interviewing. -### 5.3 PanLL interview panel +==== 5.3 PanLL interview panel In PanLL, the interview mode becomes visual: developers drag-and-drop -data flow connections in the panel, and Patch Bridge overlays CVE exposure -on the resulting graph. See Section 9 for panel design. +data flow connections in the panel, and Patch Bridge overlays CVE +exposure on the resulting graph. See Section 9 for panel design. ---- +''''' -## 6. Mitigation Classification +=== 6. Mitigation Classification -### 6.1 Three-way triage +==== 6.1 Three-way triage Every CVE affecting a project is classified into exactly one category: -**MITIGABLE** — A layered control can prevent exploitation without -removing the dependency. Examples: -- Input validation before the vulnerable code path -- Sandboxing (seccomp, pledge, WASM isolation) -- Feature disabling (turn off the vulnerable parser option) -- Drop-in replacement from proven/ repository -- Configuration change (disable XXE, limit recursion depth) +*MITIGABLE* — A layered control can prevent exploitation without +removing the dependency. Examples: - Input validation before the +vulnerable code path - Sandboxing (seccomp, pledge, WASM isolation) - +Feature disabling (turn off the vulnerable parser option) - Drop-in +replacement from proven/ repository - Configuration change (disable XXE, +limit recursion depth) -**UNMITIGABLE** — No feasible mitigation exists given the project's +*UNMITIGABLE* — No feasible mitigation exists given the project’s constraints. The vulnerability is reachable, exploitable, and no control -can be layered between attacker-controlled input and the vulnerable code. -The only options are: replace the dependency, rearchitect, or accept the risk. +can be layered between attacker-controlled input and the vulnerable +code. The only options are: replace the dependency, rearchitect, or +accept the risk. -**CONCATENATIVE** — Two or more CVEs that are individually low/medium +*CONCATENATIVE* — Two or more CVEs that are individually low/medium severity combine to create a critical risk because they share a trust -boundary, data flow, or privilege escalation path in the project's +boundary, data flow, or privilege escalation path in the project’s specific architecture. -### 6.2 Formal classification (Idris2) +==== 6.2 Formal classification (Idris2) The classification is not heuristic — it is a type-level proof: -```idris +[source,idris] +---- -- src/abi/Bridge/Classify.idr ||| Result of attempting to mitigate a vulnerability in context @@ -472,21 +514,21 @@ NoMitigationExists vc ctx = (m : Mitigation vc) -> Either (input ** (Triggers input vc, Triggers (apply m input) vc)) (input ** Not (PreservesBehaviour (apply m input) ctx)) -``` +---- -When Patch Bridge says "unmitigable," it carries a proof. This is +When Patch Bridge says "`unmitigable,`" it carries a proof. This is fundamentally different from a heuristic severity score. ---- +''''' -## 7. Concatenative Danger Detection +=== 7. Concatenative Danger Detection -### 7.1 The problem +==== 7.1 The problem -Two CVEs scored "Medium" (CVSS 5.0) individually may be catastrophic -together if they share a trust boundary in the project's architecture: +Two CVEs scored "`Medium`" (CVSS 5.0) individually may be catastrophic +together if they share a trust boundary in the project’s architecture: -``` +.... CVE-A: Input parsing weakness in libfoo (Medium) CVE-B: Privilege escalation in libbar (Medium) @@ -498,39 +540,48 @@ privilege escalation → arbitrary code execution as service user. Individual CVSS: 5.0 + 5.0 Actual combined risk: 9.8 (Critical) -``` +.... -### 7.2 Detection mechanism +==== 7.2 Detection mechanism Patch Bridge extends the miniKanren FactDB with CVE interaction rules: -``` +.... Rule: concatenative_danger IF cve(A, lib_X, vuln_class_1) AND cve(B, lib_Y, vuln_class_2) AND data_flows(lib_X_output, lib_Y_input, context) AND vuln_class_chain(vuln_class_1, vuln_class_2, escalation) THEN concatenative_risk(A, B, context, escalation) -``` +.... + +*Vulnerability class chains* (non-exhaustive): + +[width="100%",cols="37%,38%,25%",options="header",] +|=== +|Class 1 (upstream) |Class 2 (downstream) |Chain effect +|Input validation bypass |Command injection |RCE + +|Input validation bypass |SQL injection |Data exfiltration -**Vulnerability class chains** (non-exhaustive): +|Path traversal |File write |Arbitrary file overwrite -| Class 1 (upstream) | Class 2 (downstream) | Chain effect | -|--------------------|---------------------|--------------| -| Input validation bypass | Command injection | RCE | -| Input validation bypass | SQL injection | Data exfiltration | -| Path traversal | File write | Arbitrary file overwrite | -| Deserialization | Code execution | RCE | -| Race condition | Privilege escalation | Privilege escalation | -| Buffer read overrun | Information disclosure | Memory leak → key extraction | -| Authentication bypass | Any | Unauthenticated exploitation | +|Deserialization |Code execution |RCE -### 7.3 Cross-language concatenation +|Race condition |Privilege escalation |Privilege escalation -Using the existing `CrossLangAnalyzer`, Patch Bridge detects chains that -cross language boundaries: +|Buffer read overrun |Information disclosure |Memory leak → key +extraction -``` +|Authentication bypass |Any |Unauthenticated exploitation +|=== + +==== 7.3 Cross-language concatenation + +Using the existing `+CrossLangAnalyzer+`, Patch Bridge detects chains +that cross language boundaries: + +.... CVE-A in C library (buffer overflow) ──────────┐ │ NIF boundary CVE-B in Elixir dep (atom exhaustion) ──────────┘ @@ -538,18 +589,20 @@ CVE-B in Elixir dep (atom exhaustion) ──────────┘ Chain: Malformed input overflows C buffer → corrupted return value reaches Elixir → dynamic atom creation from corrupted data → VM-wide atom table exhaustion → denial of service for ALL processes. -``` +.... ---- +''''' -## 8. Mitigation Lifecycle +=== 8. Mitigation Lifecycle -### 8.1 Registry +==== 8.1 Registry -Active mitigations are tracked in `.machine_readable/patch-bridge/registry.scm` -and persisted to VeriSimDB as hexads: +Active mitigations are tracked in +`+.machine_readable/patch-bridge/registry.scm+` and persisted to +VeriSimDB as hexads: -```scheme +[source,scheme] +---- (mitigation-registry (version "0.1.0") (project "my-project") @@ -571,11 +624,11 @@ and persisted to VeriSimDB as hexads: (review-by "2026-04-21") (files-modified ("src/api/handler.rs" "added depth limit check"))))) -``` +---- -### 8.2 Lifecycle stages +==== 8.2 Lifecycle stages -``` +.... ┌─────────┐ ┌─────────┐ ┌──────────┐ ┌─────────┐ │ APPLIED │────▶│ ACTIVE │────▶│ RETIRING │────▶│ RETIRED │ └─────────┘ └─────────┘ └──────────┘ └─────────┘ @@ -585,47 +638,49 @@ and persisted to VeriSimDB as hexads: ┌──────────┐ │ STALE │ (needs re-evaluation) └──────────┘ -``` - -- **APPLIED**: Mitigation just deployed. Proof attached. Tests pass. -- **ACTIVE**: Monitoring. Upstream fix watch running. -- **RETIRING**: Upstream fix released. Dependency updated. Verifying - that removing the mitigation is safe (run tests, check proof). -- **RETIRED**: Mitigation removed. Original code path restored. - Attestation sealed. -- **STALE**: Review date passed without upstream fix. Re-evaluate: - is the mitigation still sound? Has the threat landscape changed? - -### 8.3 panic-attack assail integration - -`panic-attack assail` (pre-commit hook) gains two new checks: - -1. **Mitigation presence**: If an active mitigation modifies file X, - and a commit removes or alters the mitigation code in file X, - `assail` blocks the commit with: - ``` - BLOCKED: Commit removes active Patch Bridge mitigation PB-2026-001 - for CVE-2026-XXXX. The upstream fix has not landed yet. - Run `panic-attack bridge status` for details. - ``` - -2. **Stale mitigation**: If a mitigation's `auto-retire-when` condition - is met (e.g., dependency version bumped past the fix), `assail` warns: - ``` - INFO: CVE-2026-XXXX is fixed in serde_json 1.0.129 (you have 1.0.129). - Mitigation PB-2026-001 can be retired. - Run `panic-attack bridge retire PB-2026-001` to remove safely. - ``` - ---- - -## 9. Adoption Gate - -### 9.1 Pre-dependency risk assessment +.... + +* *APPLIED*: Mitigation just deployed. Proof attached. Tests pass. +* *ACTIVE*: Monitoring. Upstream fix watch running. +* *RETIRING*: Upstream fix released. Dependency updated. Verifying that +removing the mitigation is safe (run tests, check proof). +* *RETIRED*: Mitigation removed. Original code path restored. +Attestation sealed. +* *STALE*: Review date passed without upstream fix. Re-evaluate: is the +mitigation still sound? Has the threat landscape changed? + +==== 8.3 panic-attack assail integration + +`+panic-attack assail+` (pre-commit hook) gains two new checks: + +[arabic] +. *Mitigation presence*: If an active mitigation modifies file X, and a +commit removes or alters the mitigation code in file X, `+assail+` +blocks the commit with: ++ +.... +BLOCKED: Commit removes active Patch Bridge mitigation PB-2026-001 +for CVE-2026-XXXX. The upstream fix has not landed yet. +Run `panic-attack bridge status` for details. +.... +. *Stale mitigation*: If a mitigation’s `+auto-retire-when+` condition +is met (e.g., dependency version bumped past the fix), `+assail+` warns: ++ +.... +INFO: CVE-2026-XXXX is fixed in serde_json 1.0.129 (you have 1.0.129). +Mitigation PB-2026-001 can be retired. +Run `panic-attack bridge retire PB-2026-001` to remove safely. +.... + +''''' + +=== 9. Adoption Gate + +==== 9.1 Pre-dependency risk assessment Before adding a dependency, developers query: -``` +.... $ panic-attack bridge gate serde_json Adoption Gate: serde_json @@ -658,37 +713,45 @@ Alternatives: simd-json: 0 CVEs, but no serde compatibility sonic-rs: 0 CVEs, serde-compatible, actively maintained proven/json: 0 CVEs, formally verified bounds, serde-compatible (recommended) -``` +.... -### 9.2 Pattern-based warnings +==== 9.2 Pattern-based warnings -The gate doesn't just check this dependency's CVE history — it checks the -**vulnerability class pattern** across similar libraries: +The gate doesn’t just check this dependency’s CVE history — it checks +the *vulnerability class pattern* across similar libraries: -``` +.... WARNING: 7 of 12 JSON parsing libraries have had stack overflow CVEs. This is a systemic vulnerability class in recursive descent parsers. Consider iterative parsers or proven/json (verified depth-bounded). -``` +.... + +''''' ---- +=== 10. PanLL Panel Design -## 10. PanLL Panel Design +==== 10.1 Panel identity -### 10.1 Panel identity +[width="100%",cols="50%,50%",options="header",] +|=== +|Field |Value +|Panel ID |`+PanelPatchBridge+` -| Field | Value | -|-------|-------| -| Panel ID | `PanelPatchBridge` | -| Name | "Patch Bridge" | -| Short name | "PB" | -| Icon | `shield-check` | -| Clade | `security` | -| Has backend | `true` (Tauri commands for CVE feeds, registry, flow persistence) | +|Name |"`Patch Bridge`" -### 10.2 Four-file structure +|Short name |"`PB`" -``` +|Icon |`+shield-check+` + +|Clade |`+security+` + +|Has backend |`+true+` (Tauri commands for CVE feeds, registry, flow +persistence) +|=== + +==== 10.2 Four-file structure + +.... src/ ├── model/PatchBridgeModel.res # Types: CVE, Mitigation, FlowChart, │ # BubbleRating, Classification @@ -698,11 +761,11 @@ src/ │ # persist flow charts, check upstream └── components/PatchBridge.res # View: dashboard, flow editor, # mitigation status, adoption gate -``` +.... -### 10.3 Panel layout +==== 10.3 Panel layout -``` +.... ┌─ Patch Bridge ──────────────────────────────────────────────┐ │ │ │ ┌─ Summary Bar ──────────────────────────────────────────┐ │ @@ -780,17 +843,17 @@ src/ │ └─────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ -``` +.... ---- +''''' -## 11. Upstream Feedback Loop +=== 11. Upstream Feedback Loop When Patch Bridge generates a proven mitigation, it can contribute back: -### 11.1 Automated upstream PR +==== 11.1 Automated upstream PR -``` +.... $ panic-attack bridge upstream CVE-2026-XXXX Generating upstream contribution for CVE-2026-XXXX... @@ -813,42 +876,46 @@ Draft PR: Generated by Patch Bridge (panic-attack). Open PR? [y/N] -``` +.... -### 11.2 Proof export format +==== 11.2 Proof export format Proofs are exported in a format that upstream maintainers can verify independently, even without Idris2: -``` +.... proof/ ├── depth-limit-soundness.idr # Idris2 source (machine-checkable) ├── depth-limit-soundness.md # Human-readable proof sketch ├── test-vectors.json # Concrete test cases derived from proof └── attestation.a2ml # Cryptographic attestation (Ed25519) -``` +.... -The test vectors are generated from the proof — if the upstream maintainer -doesn't use Idris2, they can at least run the test vectors to gain -confidence in the fix. +The test vectors are generated from the proof — if the upstream +maintainer doesn’t use Idris2, they can at least run the test vectors to +gain confidence in the fix. ---- +''''' -## 12. BoJ Cartridge +=== 12. BoJ Cartridge -A BoJ cartridge `patch-bridge` provides continuous monitoring: +A BoJ cartridge `+patch-bridge+` provides continuous monitoring: -### 12.1 Capabilities +==== 12.1 Capabilities -- **Scheduled CVE sweep**: Poll all source tiers on configurable intervals -- **Webhook receiver**: GitHub Security Advisory webhooks for instant notification -- **Registry sync**: Keep VeriSimDB hexads in sync with active mitigations -- **Upstream watch**: Monitor dependency release feeds for fix availability -- **Alert routing**: Push unmitigable/concatenative alerts to notification channels +* *Scheduled CVE sweep*: Poll all source tiers on configurable intervals +* *Webhook receiver*: GitHub Security Advisory webhooks for instant +notification +* *Registry sync*: Keep VeriSimDB hexads in sync with active mitigations +* *Upstream watch*: Monitor dependency release feeds for fix +availability +* *Alert routing*: Push unmitigable/concatenative alerts to notification +channels -### 12.2 Cartridge manifest +==== 12.2 Cartridge manifest -```json +[source,json] +---- { "name": "patch-bridge", "version": "0.1.0", @@ -857,16 +924,16 @@ A BoJ cartridge `patch-bridge` provides continuous monitoring: "outputs": ["panll:event-chain", "verisimdb:hexad", "notify:alert"], "dependencies": ["panic-attack >= 2.1.0"] } -``` +---- ---- +''''' -## 13. Proven Repository Integration +=== 13. Proven Repository Integration -The `proven/` repository contains formally verified implementations. -Patch Bridge uses it as a **mitigation source**: +The `+proven/+` repository contains formally verified implementations. +Patch Bridge uses it as a *mitigation source*: -``` +.... CVE vulnerability class → proven/ alternative ─────────────────────────────────────────────── JSON stack overflow → proven/json (depth-bounded parser) @@ -875,129 +942,176 @@ ECDSA timing leak → proven/ed25519 (constant-time, verified) Buffer overflow → proven/bounded-buffer (length-indexed) Path traversal → proven/safe-path (normalisation proof) Deserialization gadget → proven/safe-deserialize (type-restricted) -``` +.... When a CVE maps to a vulnerability class with a proven/ alternative, Patch Bridge recommends the replacement with a compatibility assessment. ---- +''''' + +=== 14. Implementation Priorities + +==== Phase 1 — Foundation (panic-attack extension) + +[arabic] +. `+src/bridge/mod.rs+` — Module structure and public API +. `+src/bridge/intelligence.rs+` — OSV API integration (simplest feed +first) +. `+src/bridge/classify.rs+` — Three-way triage using existing kanren +engine +. `+src/bridge/registry.rs+` — SCM file-based mitigation tracking +. New subcommands: `+bridge intel+`, `+bridge triage+`, +`+bridge status+` + +==== Phase 2 — Intelligence expansion + +[arabic, start=6] +. `+src/bridge/intelligence.rs+` — Add NVD, GHSA, RustSec feeds +. `+src/bridge/bubble.rs+` — Source coverage and divergence detection +. `+src/bridge/gate.rs+` — Pre-adoption risk assessment +. New subcommands: `+bridge gate+`, `+bridge bubble+` + +==== Phase 3 — Formal verification + +[arabic, start=10] +. `+src/abi/Bridge/Classify.idr+` — Idris2 mitigation soundness types +. `+src/abi/Bridge/Concatenate.idr+` — Multiplicative risk proofs +. `+ffi/zig/src/bridge.zig+` — FFI bridge for proof verification results +. Integration: Idris2 proof artifacts attached to mitigations + +==== Phase 4 — Developer experience + +[arabic, start=14] +. `+src/bridge/flow.rs+` — Developer interview mode (CLI) +. `+src/bridge/translate.rs+` — Cross-domain threat translation +. PanLL panel: four-file ReScript panel in PanLL repo +. `+panic-attack assail+` integration (mitigation presence + stale +checks) + +==== Phase 5 — Ecosystem integration + +[arabic, start=18] +. `+src/bridge/retire.rs+` — Upstream fix watch + auto-retirement +. `+src/bridge/upstream.rs+` — PR generation with proof export +. `+src/bridge/concatenate.rs+` — Full concatenative analysis engine +. BoJ cartridge for continuous monitoring +. VeriSimDB hexad persistence for mitigation registry +. Multi-source Tier 3 feeds (oss-security, academic, commit analysis) + +''''' + +=== 15. What Makes This Different + +[width="100%",cols="29%,38%,33%",options="header",] +|=== +|Capability |Existing tools |Patch Bridge +|Detect CVEs |✓ (Trivy, Grype, Snyk) |✓ + +|Suggest fix version |✓ |✓ + +|Multi-source intelligence |Partial (1–2 sources) |✓ (14+ sources, 3 +tiers) + +|Bubble detection |✗ |✓ + +|Contextual reachability |Partial (Snyk, some) |✓ (kanren taint engine) + +|Cross-language chains |✗ |✓ (kanren crosslang engine) + +|Concatenative danger |✗ |✓ (CVE×CVE interaction proofs) + +|Generate mitigation |✗ |✓ + +|Prove mitigation works |✗ |✓ (Idris2 dependent types) + +|Prove unmitigability |✗ |✓ (impossibility proofs) + +|Mitigation lifecycle |✗ |✓ (apply → monitor → retire) + +|Auto-retire on fix |✗ |✓ + +|Block mitigation removal |✗ |✓ (assail pre-commit) + +|Developer interview |✗ |✓ (flow chart artifacts) + +|Adoption gate |Partial (Snyk Advisor) |✓ (pattern + class analysis) + +|Cross-domain translation |✗ |✓ + +|Upstream feedback |✗ |✓ (proven PRs with proofs) + +|Visual panel (IDE) |✗ |✓ (PanLL panel) +|=== + +''''' + +=== 16. Open Questions + +[arabic] +. *Proof granularity*: How specific should Idris2 proofs be? Per-CVE +proofs are most valuable but most expensive. Per-vulnerability-class +proofs are reusable but less precise. Likely: class-level proofs with +CVE-specific test vectors. +. *VirusTotal API limits*: Free tier allows 4 requests/minute. May need +premium for continuous monitoring. Alternative: cache aggressively, +batch queries via BoJ cartridge. +. *Interview fatigue*: Developers won’t answer 47 questions. Prioritise +by: (a) dependencies with active CVEs, (b) dependencies that handle +untrusted input, (c) dependencies at trust boundaries. Target ≤10 +questions per session. +. *Upstream reception*: Will maintainers accept PRs with Idris2 proofs +they can’t read? Mitigate by: always include human-readable proof sketch ++ concrete test vectors. The proof is bonus, not requirement. +. *False positive management*: Contextual unreachability analysis may +have false negatives (says "`unreachable`" but isn’t). Conservative +default: if uncertain, classify as mitigable rather than informational. +kanren context-facts (planned) will reduce FP rate. + +''''' + +=== Appendix A: Glossary + +[width="100%",cols="36%,64%",options="header",] +|=== +|Term |Definition +|*Adoption gate* |Pre-dependency risk assessment + +|*Bubble rating* |Source coverage metric per CVE (like Ground News media +bias) + +|*Concatenative danger* |Risk multiplication when CVEs share trust +boundaries + +|*Flow chart artifact* |Persisted data-flow model from developer +interview + +|*Mitigation* |A layered control that prevents exploitation of a +specific CVE + +|*Patch Bridge* |This system — bridges the gap between CVE disclosure +and upstream fix + +|*Soundness proof* |Idris2 proof that a mitigation prevents exploitation + +|*Unmitigability proof* |Idris2 proof that no mitigation can prevent +exploitation + +|*Upstream feedback* |Contributing proven mitigations back to dependency +maintainers +|=== + +=== Appendix B: Related Work -## 14. Implementation Priorities - -### Phase 1 — Foundation (panic-attack extension) - -1. `src/bridge/mod.rs` — Module structure and public API -2. `src/bridge/intelligence.rs` — OSV API integration (simplest feed first) -3. `src/bridge/classify.rs` — Three-way triage using existing kanren engine -4. `src/bridge/registry.rs` — SCM file-based mitigation tracking -5. New subcommands: `bridge intel`, `bridge triage`, `bridge status` - -### Phase 2 — Intelligence expansion - -6. `src/bridge/intelligence.rs` — Add NVD, GHSA, RustSec feeds -7. `src/bridge/bubble.rs` — Source coverage and divergence detection -8. `src/bridge/gate.rs` — Pre-adoption risk assessment -9. New subcommands: `bridge gate`, `bridge bubble` - -### Phase 3 — Formal verification - -10. `src/abi/Bridge/Classify.idr` — Idris2 mitigation soundness types -11. `src/abi/Bridge/Concatenate.idr` — Multiplicative risk proofs -12. `ffi/zig/src/bridge.zig` — FFI bridge for proof verification results -13. Integration: Idris2 proof artifacts attached to mitigations - -### Phase 4 — Developer experience - -14. `src/bridge/flow.rs` — Developer interview mode (CLI) -15. `src/bridge/translate.rs` — Cross-domain threat translation -16. PanLL panel: four-file ReScript panel in PanLL repo -17. `panic-attack assail` integration (mitigation presence + stale checks) - -### Phase 5 — Ecosystem integration - -18. `src/bridge/retire.rs` — Upstream fix watch + auto-retirement -19. `src/bridge/upstream.rs` — PR generation with proof export -20. `src/bridge/concatenate.rs` — Full concatenative analysis engine -21. BoJ cartridge for continuous monitoring -22. VeriSimDB hexad persistence for mitigation registry -23. Multi-source Tier 3 feeds (oss-security, academic, commit analysis) - ---- - -## 15. What Makes This Different - -| Capability | Existing tools | Patch Bridge | -|-----------|---------------|-------------| -| Detect CVEs | ✓ (Trivy, Grype, Snyk) | ✓ | -| Suggest fix version | ✓ | ✓ | -| Multi-source intelligence | Partial (1–2 sources) | ✓ (14+ sources, 3 tiers) | -| Bubble detection | ✗ | ✓ | -| Contextual reachability | Partial (Snyk, some) | ✓ (kanren taint engine) | -| Cross-language chains | ✗ | ✓ (kanren crosslang engine) | -| Concatenative danger | ✗ | ✓ (CVE×CVE interaction proofs) | -| Generate mitigation | ✗ | ✓ | -| Prove mitigation works | ✗ | ✓ (Idris2 dependent types) | -| Prove unmitigability | ✗ | ✓ (impossibility proofs) | -| Mitigation lifecycle | ✗ | ✓ (apply → monitor → retire) | -| Auto-retire on fix | ✗ | ✓ | -| Block mitigation removal | ✗ | ✓ (assail pre-commit) | -| Developer interview | ✗ | ✓ (flow chart artifacts) | -| Adoption gate | Partial (Snyk Advisor) | ✓ (pattern + class analysis) | -| Cross-domain translation | ✗ | ✓ | -| Upstream feedback | ✗ | ✓ (proven PRs with proofs) | -| Visual panel (IDE) | ✗ | ✓ (PanLL panel) | - ---- - -## 16. Open Questions - -1. **Proof granularity**: How specific should Idris2 proofs be? Per-CVE - proofs are most valuable but most expensive. Per-vulnerability-class - proofs are reusable but less precise. Likely: class-level proofs with - CVE-specific test vectors. - -2. **VirusTotal API limits**: Free tier allows 4 requests/minute. May - need premium for continuous monitoring. Alternative: cache aggressively, - batch queries via BoJ cartridge. - -3. **Interview fatigue**: Developers won't answer 47 questions. Prioritise - by: (a) dependencies with active CVEs, (b) dependencies that handle - untrusted input, (c) dependencies at trust boundaries. Target ≤10 - questions per session. - -4. **Upstream reception**: Will maintainers accept PRs with Idris2 proofs - they can't read? Mitigate by: always include human-readable proof - sketch + concrete test vectors. The proof is bonus, not requirement. - -5. **False positive management**: Contextual unreachability analysis may - have false negatives (says "unreachable" but isn't). Conservative - default: if uncertain, classify as mitigable rather than informational. - kanren context-facts (planned) will reduce FP rate. - ---- - -## Appendix A: Glossary - -| Term | Definition | -|------|-----------| -| **Adoption gate** | Pre-dependency risk assessment | -| **Bubble rating** | Source coverage metric per CVE (like Ground News media bias) | -| **Concatenative danger** | Risk multiplication when CVEs share trust boundaries | -| **Flow chart artifact** | Persisted data-flow model from developer interview | -| **Mitigation** | A layered control that prevents exploitation of a specific CVE | -| **Patch Bridge** | This system — bridges the gap between CVE disclosure and upstream fix | -| **Soundness proof** | Idris2 proof that a mitigation prevents exploitation | -| **Unmitigability proof** | Idris2 proof that no mitigation can prevent exploitation | -| **Upstream feedback** | Contributing proven mitigations back to dependency maintainers | - -## Appendix B: Related Work - -- **Snyk**: Detection + curated patches (manual, no proofs, no lifecycle) -- **Trivy/Grype**: Detection only (no mitigation, no context) -- **OSV-Scanner**: Detection with OSV database (Google, comprehensive, no mitigation) -- **Renovate/Dependabot**: Automated version bumps (post-fix only, no bridge period) -- **ModSecurity/OWASP CRS**: Virtual patching at WAF level (network only, no compile-time) -- **RASP tools**: Runtime protection (overhead, no formal guarantees) -- **OSS-Fuzz/ClusterFuzz**: Fuzzing finds bugs (detection, not mitigation) -- **Semgrep**: Pattern-based scanning (detection, some autofix, no proofs) -- **EPSS**: Exploit probability scoring (better than CVSS, but still not contextual) +* *Snyk*: Detection + curated patches (manual, no proofs, no lifecycle) +* *Trivy/Grype*: Detection only (no mitigation, no context) +* *OSV-Scanner*: Detection with OSV database (Google, comprehensive, no +mitigation) +* *Renovate/Dependabot*: Automated version bumps (post-fix only, no +bridge period) +* *ModSecurity/OWASP CRS*: Virtual patching at WAF level (network only, +no compile-time) +* *RASP tools*: Runtime protection (overhead, no formal guarantees) +* *OSS-Fuzz/ClusterFuzz*: Fuzzing finds bugs (detection, not mitigation) +* *Semgrep*: Pattern-based scanning (detection, some autofix, no proofs) +* *EPSS*: Exploit probability scoring (better than CVSS, but still not +contextual) diff --git a/docs/release-prep.md b/docs/release-prep.adoc similarity index 72% rename from docs/release-prep.md rename to docs/release-prep.adoc index f9086b6..b6860b1 100644 --- a/docs/release-prep.md +++ b/docs/release-prep.adoc @@ -1,26 +1,27 @@ - - +== Release Prep Checklist -# Release Prep Checklist +This checklist is for shipping the +`+amuck+`/`+abduct+`/`+adjudicate+`/`+axial+` + A2ML report-bundle work +without pulling unrelated tree changes. -This checklist is for shipping the `amuck`/`abduct`/`adjudicate`/`axial` + A2ML report-bundle work without pulling unrelated tree changes. - -## 1. Validation Gates +=== 1. Validation Gates Run before tagging or publishing: -```bash +[source,bash] +---- cargo fmt --check cargo test -q cargo run --quiet -- help a2ml-export cargo run --quiet -- help a2ml-import -``` +---- -## 2. A2ML Roundtrip Smoke Tests +=== 2. A2ML Roundtrip Smoke Tests Minimal end-to-end checks: -```bash +[source,bash] +---- panic-attack a2ml-export --kind assail reports/assail.json --output /tmp/assail.a2ml panic-attack a2ml-import /tmp/assail.a2ml --output /tmp/assail.roundtrip.json --kind assail @@ -29,15 +30,17 @@ panic-attack a2ml-import /tmp/attack.a2ml --output /tmp/attack.roundtrip.json -- panic-attack a2ml-export --kind ambush reports/ambush.json --output /tmp/ambush.a2ml panic-attack a2ml-import /tmp/ambush.a2ml --output /tmp/ambush.roundtrip.json --kind ambush -``` +---- -Repeat for `assault`, `amuck`, `abduct`, `adjudicate`, and `axial` when test fixtures are available. +Repeat for `+assault+`, `+amuck+`, `+abduct+`, `+adjudicate+`, and +`+axial+` when test fixtures are available. -## 3. Curated Staging Set +=== 3. Curated Staging Set Stage only the feature/docs files for this stream: -```bash +[source,bash] +---- git add \ src/a2ml/mod.rs \ src/main.rs \ @@ -61,11 +64,12 @@ git add \ man/panic-attack.1 \ docs/codebase-annotations.md \ docs/release-prep.md -``` +---- Then verify: -```bash +[source,bash] +---- git diff --cached --stat git diff --cached -``` +---- diff --git a/docs/reports/audit/pillar-audit-2026-04-15.adoc b/docs/reports/audit/pillar-audit-2026-04-15.adoc new file mode 100644 index 0000000..55b6e89 --- /dev/null +++ b/docs/reports/audit/pillar-audit-2026-04-15.adoc @@ -0,0 +1,29 @@ +== Gemini Audit Report (M2: Pillar Repo Audits) + +Date: 2026-04-15 Repository: /var/mnt/eclipse/repos/panic-attacker + +=== Audit Criteria + +* *Dangerous Patterns*: +** `+believe_me+`, `+assert_total+`, `+Admitted+`, `+sorry+`, +`+unsafeCoerce+`, `+Obj.magic+`: *CLEAN* in own code (verified via +`+PROOF-NEEDS.md+`). +* *Standards Check*: +** `+.machine_readable/*.a2ml+`: `+CLADE.a2ml+`, `+STATE.a2ml+`, +`+META.a2ml+` present in `+6a2/+`. +** `+Justfile+`: *PRESENT*. +** `+K9.k9+` / `+coordination.k9+`: *MISSING* in root (exists as +`+k9iser.toml+`). +* *CI/CD Status*: `+.github/workflows+` *PRESENT*. +* *Documentation Parity*: +** Claims: 49 languages, 196 tests, v2.1.0. +** Actual: Matches implementation files and badges. +* *Template Residue*: +** `+{{PACKAGE_NAME}}+`, `+{{DEPS}}+`, `+{{BUILD_OUTPUT_PATH}}+` found +in `+QUICKSTART-MAINTAINER.adoc+`. + +=== Verdict + +* *CRG Grade*: B +* *Publishable?*: AFTER REPAIR (Fix template placeholders in maintainer +docs). diff --git a/docs/reports/audit/pillar-audit-2026-04-15.md b/docs/reports/audit/pillar-audit-2026-04-15.md deleted file mode 100644 index 079828d..0000000 --- a/docs/reports/audit/pillar-audit-2026-04-15.md +++ /dev/null @@ -1,24 +0,0 @@ - - -# Gemini Audit Report (M2: Pillar Repo Audits) -Date: 2026-04-15 -Repository: /var/mnt/eclipse/repos/panic-attacker - -## Audit Criteria - -- **Dangerous Patterns**: - - `believe_me`, `assert_total`, `Admitted`, `sorry`, `unsafeCoerce`, `Obj.magic`: **CLEAN** in own code (verified via `PROOF-NEEDS.md`). -- **Standards Check**: - - `.machine_readable/*.a2ml`: `CLADE.a2ml`, `STATE.a2ml`, `META.a2ml` present in `6a2/`. - - `Justfile`: **PRESENT**. - - `K9.k9` / `coordination.k9`: **MISSING** in root (exists as `k9iser.toml`). -- **CI/CD Status**: `.github/workflows` **PRESENT**. -- **Documentation Parity**: - - Claims: 49 languages, 196 tests, v2.1.0. - - Actual: Matches implementation files and badges. -- **Template Residue**: - - `{{PACKAGE_NAME}}`, `{{DEPS}}`, `{{BUILD_OUTPUT_PATH}}` found in `QUICKSTART-MAINTAINER.adoc`. - -## Verdict -- **CRG Grade**: B -- **Publishable?**: AFTER REPAIR (Fix template placeholders in maintainer docs). diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..24a468f --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,86 @@ +SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) –> + +== Tech-Debt Audit — panic-attack — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+LOW+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +Scanner counted the following markers in proof-bearing files of this +repo: + +.... +files= 3 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 9 +.... + +*Total markers:* 9. *Severity:* `+>09+`. + +*Marker types* (any non-zero counts above): - Coq `+Axiom+`/`+Admitted+` +— unconditional proof escapes. - Lean `+sorry+`/`+axiom+` — Lean’s +equivalent. - Agda `+postulate+` — accepted axiomatically. - Idris2 +`+believe_me+`/`+assert_total+` — runtime-safe coercion / totality +assumption. - Idris2 top-level `+partial+` — totality-check waived. - F* +`+assume val+`/`+admit_p+` — F* admit. - `+TODO PROOF+` / `+OWED:+` — +self-documented debt markers. - `+unsafePerformIO+`/`+unsafeCoerce+` — +soundness-relevant escape hatches in Haskell/Rust source. + +*Recommended next move:* triage each finding into one of: (a) discharge +by proof, (b) cover with property-tests + a documented refutation +budget, or (c) annotate as a known/necessary axiom (e.g. `+funExt+`) in +`+docs/proof-debt.md+`. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+Palimp-MPL-2.0+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |220 +|`+docs/+` files |12 +|`+docs/+` LoC |2839 +|CHANGELOG.md |Y +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+LOW+` +|=== + +*Recommended next move:* `+docs/+` has only 12 file(s). Aim for ≥10 +organised docs (architecture, usage, contributing-guide, +troubleshooting, design-decisions). The user’s bar for a +"`heavily-developed and well-organised wiki`" is ≥10 files with topical +organisation. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index ece33e3..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,72 +0,0 @@ - -SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath) ---> - -# Tech-Debt Audit — panic-attack — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `LOW`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -Scanner counted the following markers in proof-bearing files of this repo: - -``` -files= 3 | Coq-Axm/Adm= 0 | Lean-srry/ax= 0 | Agda-pst= 0 | Idr-blv= 0 | Idr-prtl= 0 | Fstr-asm= 0 | TODO= 0 | Unsafe= 9 -``` - -**Total markers:** 9. **Severity:** `>09`. - -**Marker types** (any non-zero counts above): -- Coq `Axiom`/`Admitted` — unconditional proof escapes. -- Lean `sorry`/`axiom` — Lean's equivalent. -- Agda `postulate` — accepted axiomatically. -- Idris2 `believe_me`/`assert_total` — runtime-safe coercion / totality assumption. -- Idris2 top-level `partial` — totality-check waived. -- F\* `assume val`/`admit_p` — F\* admit. -- `TODO PROOF` / `OWED:` — self-documented debt markers. -- `unsafePerformIO`/`unsafeCoerce` — soundness-relevant escape hatches in Haskell/Rust source. - -**Recommended next move:** triage each finding into one of: (a) discharge by proof, (b) cover with property-tests + a documented refutation budget, or (c) annotate as a known/necessary axiom (e.g. `funExt`) in `docs/proof-debt.md`. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `Palimp-MPL-2.0` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 220 | -| `docs/` files | 12 | -| `docs/` LoC | 2839 | -| CHANGELOG.md | Y | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `LOW` | - -**Recommended next move:** `docs/` has only 12 file(s). Aim for ≥10 organised docs (architecture, usage, contributing-guide, troubleshooting, design-decisions). The user's bar for a "heavily-developed and well-organised wiki" is ≥10 files with topical organisation. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..c859101 --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — panic-attack (Developer) + +=== What is panic-attack? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-dev.md b/llm-warmup-dev.md deleted file mode 100644 index a87c53e..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,18 +0,0 @@ - - -# LLM Warmup — panic-attack (Developer) - -## What is panic-attack? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.adoc b/llm-warmup-user.adoc new file mode 100644 index 0000000..495b5e5 --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — panic-attack (User) + +=== What is panic-attack? + +See README.adoc for overview. + +=== Key Commands + +* `+just setup+` — set up development environment +* `+just build+` — build the project +* `+just test+` — run tests +* `+just doctor+` — diagnose issues +* `+just heal+` — attempt auto-repair + +=== Quick Context + +* License: MPL-2.0 +* Part of hyperpolymath ecosystem +* See EXPLAINME.adoc for architecture diff --git a/llm-warmup-user.md b/llm-warmup-user.md deleted file mode 100644 index 5f1b043..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,18 +0,0 @@ - - -# LLM Warmup — panic-attack (User) - -## What is panic-attack? -See README.adoc for overview. - -## Key Commands -- `just setup` — set up development environment -- `just build` — build the project -- `just test` — run tests -- `just doctor` — diagnose issues -- `just heal` — attempt auto-repair - -## Quick Context -- License: MPL-2.0 -- Part of hyperpolymath ecosystem -- See EXPLAINME.adoc for architecture diff --git a/panic_attack_static_analysis_preparation.adoc b/panic_attack_static_analysis_preparation.adoc new file mode 100644 index 0000000..ac4736c --- /dev/null +++ b/panic_attack_static_analysis_preparation.adoc @@ -0,0 +1,313 @@ +== Panic-Attack Static Analysis Preparation + +=== Executive Summary + +This document outlines the preparation steps for performing static +analysis on the `+panic-attack+` tool. The tool is a comprehensive +stress testing and bug signature detection tool written in Rust. The +goal is to ensure the tool is ready for static analysis to identify +potential vulnerabilities, code quality issues, and compliance with best +practices. + +=== Table of Contents + +[arabic] +. link:#tool-overview[Tool Overview] +. link:#static-analysis-objectives[Static Analysis Objectives] +. link:#preparation-steps[Preparation Steps] +. link:#static-analysis-tools[Static Analysis Tools] +. link:#ethical-considerations[Ethical Considerations] +. link:#next-steps[Next Steps] + +=== Tool Overview + +==== Description + +The `+panic-attack+` tool is designed for stress testing programs across +multiple attack axes (CPU, memory, disk, network, concurrency) and +detecting bug signatures using logic programming techniques. It is +written in Rust and includes various modules for static analysis, +dynamic attacks, and reporting. + +==== Key Features + +* *Static Analysis*: The `+assail+` module performs static analysis on +target programs to identify weak points and recommend attacks. +* *Dynamic Attacks*: The `+attack+` module executes dynamic attacks on +target programs across various axes. +* *Reporting*: The `+report+` module generates detailed reports on the +findings from static and dynamic analysis. +* *Bug Signature Detection*: The `+signatures+` module detects bug +signatures in crash reports. +* *Multi-Language Support*: The tool supports multiple programming +languages and frameworks. + +==== Modules + +* `+a2ml+`: AI manifest handling. +* `+abduct+`: File isolation and time-skew testing. +* `+adjudicate+`: Aggregates reports into campaign-wide verdicts. +* `+ambush+`: Runs target programs with ambient stressors. +* `+amuck+`: Mutates files with dangerous combinations. +* `+assail+`: Static analysis. +* `+attack+`: Dynamic attack execution. +* `+axial+`: Observes target reactions across attack axes. +* `+diagnostics+`: Self-diagnostics for visibility. +* `+i18n+`: Internationalization support. +* `+kanren+`: Logic programming techniques. +* `+kin+`: Coordination and heartbeat mechanisms. +* `+panll+`: Event-chain modeling. +* `+report+`: Reporting functionalities. +* `+signatures+`: Bug signature detection. +* `+storage+`: Report storage and persistence. +* `+assemblyline+`: Batch scanning of directories. +* `+groove+`: Discovery server for service mesh integration. +* `+mass_panic+`: Mass panic orchestration. +* `+notify+`: Generates annotated findings summaries. +* `+types+`: Common types and structures. + +=== Static Analysis Objectives + +==== Goals + +[arabic] +. *Identify Vulnerabilities*: Detect potential security vulnerabilities +in the codebase. +. *Code Quality*: Ensure the code adheres to best practices and coding +standards. +. *Compliance*: Verify compliance with industry standards and +regulations. +. *Performance*: Identify potential performance bottlenecks. +. *Maintainability*: Assess the maintainability and readability of the +code. + +==== Scope + +* *Source Code*: All Rust source files in the `+src+` directory. +* *Dependencies*: All dependencies listed in the `+Cargo.toml+` file. +* *Configuration Files*: Configuration files such as `+Cargo.toml+`, +`+Cargo.lock+`, and any other relevant configuration files. + +=== Preparation Steps + +==== Step 1: Environment Setup + +[arabic] +. *Install Rust*: Ensure Rust is installed on the system. The tool is +written in Rust, and static analysis tools for Rust will be used. ++ +[source,bash] +---- +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +---- +. *Install Static Analysis Tools*: Install the necessary static analysis +tools. ++ +[source,bash] +---- +cargo install clippy +cargo install rustfmt +---- +. *Install Additional Tools*: Install additional tools for comprehensive +analysis. ++ +[source,bash] +---- +cargo install cargo-audit +cargo install cargo-deny +---- + +==== Step 2: Code Review + +[arabic] +. *Read the Code*: Familiarize yourself with the codebase to understand +its structure and functionality. +. *Identify Key Components*: Identify the key components and modules +that are critical to the tool’s functionality. +. *Review Documentation*: Review the documentation to understand the +intended use cases and functionalities. + +==== Step 3: Dependency Analysis + +[arabic] +. *Review Dependencies*: Review the dependencies listed in the +`+Cargo.toml+` file to identify potential vulnerabilities or outdated +libraries. +. *Update Dependencies*: Update dependencies to their latest versions to +ensure security patches are applied. ++ +[source,bash] +---- +cargo update +---- + +==== Step 4: Configuration Review + +[arabic] +. *Review Configuration Files*: Review configuration files to ensure +they are correctly set up and secure. +. *Check for Hardcoded Secrets*: Ensure there are no hardcoded secrets +or sensitive information in the configuration files. + +==== Step 5: Pre-Analysis Checks + +[arabic] +. *Run Tests*: Ensure all tests pass before performing static analysis. ++ +[source,bash] +---- +cargo test +---- +. *Build the Project*: Ensure the project builds successfully. ++ +[source,bash] +---- +cargo build +---- +. *Run Clippy*: Use Clippy to identify common mistakes and improve code +quality. ++ +[source,bash] +---- +cargo clippy +---- +. *Run Rustfmt*: Use Rustfmt to ensure the code is properly formatted. ++ +[source,bash] +---- +cargo fmt +---- + +=== Static Analysis Tools + +==== Clippy + +* *Description*: A collection of lints to catch common mistakes and +improve Rust code. +* *Usage*: ++ +[source,bash] +---- +cargo clippy +---- +* *Focus Areas*: +** Common mistakes and idiomatic Rust. +** Performance improvements. +** Security best practices. + +==== Rustfmt + +* *Description*: A tool for formatting Rust code according to style +guidelines. +* *Usage*: ++ +[source,bash] +---- +cargo fmt +---- +* *Focus Areas*: +** Code formatting and readability. +** Consistency in code style. + +==== Cargo Audit + +* *Description*: Audits Cargo.lock files for crates with security +vulnerabilities. +* *Usage*: ++ +[source,bash] +---- +cargo audit +---- +* *Focus Areas*: +** Security vulnerabilities in dependencies. +** Outdated dependencies. + +==== Cargo Deny + +* *Description*: Cargo plugin to lint and enforce dependency licensing, +security, and maintenance. +* *Usage*: ++ +[source,bash] +---- +cargo deny check +---- +* *Focus Areas*: +** License compliance. +** Security vulnerabilities. +** Dependency maintenance. + +==== Additional Tools + +* *SonarQube*: A platform for continuous inspection of code quality. +* *Coverity*: A static analysis tool for identifying defects and +security vulnerabilities. +* *Semgrep*: A lightweight static analysis tool for finding bugs and +enforcing code standards. + +=== Ethical Considerations + +==== Responsible Disclosure + +* *Vulnerability Reporting*: Ensure any vulnerabilities found are +reported responsibly to the tool’s maintainers. +* *Transparency*: Be transparent about the findings and provide clear +and actionable recommendations. + +==== Privacy + +* *Data Handling*: Ensure that any data collected during the analysis is +handled responsibly and in compliance with privacy regulations. +* *Confidentiality*: Maintain the confidentiality of any sensitive +information discovered during the analysis. + +==== Compliance + +* *Regulatory Compliance*: Ensure that the analysis complies with +relevant regulations and standards. +* *Industry Standards*: Adhere to industry best practices and standards +for static analysis. + +=== Next Steps + +==== Step 1: Perform Static Analysis + +[arabic] +. *Run Clippy*: Identify common mistakes and improve code quality. +. *Run Rustfmt*: Ensure the code is properly formatted. +. *Run Cargo Audit*: Audit dependencies for security vulnerabilities. +. *Run Cargo Deny*: Lint and enforce dependency licensing, security, and +maintenance. + +==== Step 2: Review Findings + +[arabic] +. *Analyze Results*: Review the results from the static analysis tools. +. *Prioritize Issues*: Prioritize the issues based on their severity and +impact. +. *Document Findings*: Document the findings and provide clear and +actionable recommendations. + +==== Step 3: Report and Remediate + +[arabic] +. *Report Findings*: Report the findings to the tool’s maintainers. +. *Remediate Issues*: Work with the maintainers to remediate the +identified issues. +. *Verify Fixes*: Verify that the fixes have been applied and the issues +have been resolved. + +==== Step 4: Continuous Improvement + +[arabic] +. *Integrate Tools*: Integrate static analysis tools into the CI/CD +pipeline to ensure continuous monitoring and improvement. +. *Regular Audits*: Conduct regular audits to ensure the codebase +remains secure and compliant. +. *Training*: Provide training to developers on best practices for +secure coding and static analysis. + +By following these steps, you can ensure that the `+panic-attack+` tool +is thoroughly analyzed and any potential issues are identified and +addressed. diff --git a/panic_attack_static_analysis_preparation.md b/panic_attack_static_analysis_preparation.md deleted file mode 100644 index 0f79988..0000000 --- a/panic_attack_static_analysis_preparation.md +++ /dev/null @@ -1,208 +0,0 @@ - - -# Panic-Attack Static Analysis Preparation - -## Executive Summary -This document outlines the preparation steps for performing static analysis on the `panic-attack` tool. The tool is a comprehensive stress testing and bug signature detection tool written in Rust. The goal is to ensure the tool is ready for static analysis to identify potential vulnerabilities, code quality issues, and compliance with best practices. - -## Table of Contents -1. [Tool Overview](#tool-overview) -2. [Static Analysis Objectives](#static-analysis-objectives) -3. [Preparation Steps](#preparation-steps) -4. [Static Analysis Tools](#static-analysis-tools) -5. [Ethical Considerations](#ethical-considerations) -6. [Next Steps](#next-steps) - -## Tool Overview - -### Description -The `panic-attack` tool is designed for stress testing programs across multiple attack axes (CPU, memory, disk, network, concurrency) and detecting bug signatures using logic programming techniques. It is written in Rust and includes various modules for static analysis, dynamic attacks, and reporting. - -### Key Features -- **Static Analysis**: The `assail` module performs static analysis on target programs to identify weak points and recommend attacks. -- **Dynamic Attacks**: The `attack` module executes dynamic attacks on target programs across various axes. -- **Reporting**: The `report` module generates detailed reports on the findings from static and dynamic analysis. -- **Bug Signature Detection**: The `signatures` module detects bug signatures in crash reports. -- **Multi-Language Support**: The tool supports multiple programming languages and frameworks. - -### Modules -- `a2ml`: AI manifest handling. -- `abduct`: File isolation and time-skew testing. -- `adjudicate`: Aggregates reports into campaign-wide verdicts. -- `ambush`: Runs target programs with ambient stressors. -- `amuck`: Mutates files with dangerous combinations. -- `assail`: Static analysis. -- `attack`: Dynamic attack execution. -- `axial`: Observes target reactions across attack axes. -- `diagnostics`: Self-diagnostics for visibility. -- `i18n`: Internationalization support. -- `kanren`: Logic programming techniques. -- `kin`: Coordination and heartbeat mechanisms. -- `panll`: Event-chain modeling. -- `report`: Reporting functionalities. -- `signatures`: Bug signature detection. -- `storage`: Report storage and persistence. -- `assemblyline`: Batch scanning of directories. -- `groove`: Discovery server for service mesh integration. -- `mass_panic`: Mass panic orchestration. -- `notify`: Generates annotated findings summaries. -- `types`: Common types and structures. - -## Static Analysis Objectives - -### Goals -1. **Identify Vulnerabilities**: Detect potential security vulnerabilities in the codebase. -2. **Code Quality**: Ensure the code adheres to best practices and coding standards. -3. **Compliance**: Verify compliance with industry standards and regulations. -4. **Performance**: Identify potential performance bottlenecks. -5. **Maintainability**: Assess the maintainability and readability of the code. - -### Scope -- **Source Code**: All Rust source files in the `src` directory. -- **Dependencies**: All dependencies listed in the `Cargo.toml` file. -- **Configuration Files**: Configuration files such as `Cargo.toml`, `Cargo.lock`, and any other relevant configuration files. - -## Preparation Steps - -### Step 1: Environment Setup -1. **Install Rust**: Ensure Rust is installed on the system. The tool is written in Rust, and static analysis tools for Rust will be used. - ```bash - curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - ``` - -2. **Install Static Analysis Tools**: Install the necessary static analysis tools. - ```bash - cargo install clippy - cargo install rustfmt - ``` - -3. **Install Additional Tools**: Install additional tools for comprehensive analysis. - ```bash - cargo install cargo-audit - cargo install cargo-deny - ``` - -### Step 2: Code Review -1. **Read the Code**: Familiarize yourself with the codebase to understand its structure and functionality. -2. **Identify Key Components**: Identify the key components and modules that are critical to the tool's functionality. -3. **Review Documentation**: Review the documentation to understand the intended use cases and functionalities. - -### Step 3: Dependency Analysis -1. **Review Dependencies**: Review the dependencies listed in the `Cargo.toml` file to identify potential vulnerabilities or outdated libraries. -2. **Update Dependencies**: Update dependencies to their latest versions to ensure security patches are applied. - ```bash - cargo update - ``` - -### Step 4: Configuration Review -1. **Review Configuration Files**: Review configuration files to ensure they are correctly set up and secure. -2. **Check for Hardcoded Secrets**: Ensure there are no hardcoded secrets or sensitive information in the configuration files. - -### Step 5: Pre-Analysis Checks -1. **Run Tests**: Ensure all tests pass before performing static analysis. - ```bash - cargo test - ``` - -2. **Build the Project**: Ensure the project builds successfully. - ```bash - cargo build - ``` - -3. **Run Clippy**: Use Clippy to identify common mistakes and improve code quality. - ```bash - cargo clippy - ``` - -4. **Run Rustfmt**: Use Rustfmt to ensure the code is properly formatted. - ```bash - cargo fmt - ``` - -## Static Analysis Tools - -### Clippy -- **Description**: A collection of lints to catch common mistakes and improve Rust code. -- **Usage**: - ```bash - cargo clippy - ``` -- **Focus Areas**: - - Common mistakes and idiomatic Rust. - - Performance improvements. - - Security best practices. - -### Rustfmt -- **Description**: A tool for formatting Rust code according to style guidelines. -- **Usage**: - ```bash - cargo fmt - ``` -- **Focus Areas**: - - Code formatting and readability. - - Consistency in code style. - -### Cargo Audit -- **Description**: Audits Cargo.lock files for crates with security vulnerabilities. -- **Usage**: - ```bash - cargo audit - ``` -- **Focus Areas**: - - Security vulnerabilities in dependencies. - - Outdated dependencies. - -### Cargo Deny -- **Description**: Cargo plugin to lint and enforce dependency licensing, security, and maintenance. -- **Usage**: - ```bash - cargo deny check - ``` -- **Focus Areas**: - - License compliance. - - Security vulnerabilities. - - Dependency maintenance. - -### Additional Tools -- **SonarQube**: A platform for continuous inspection of code quality. -- **Coverity**: A static analysis tool for identifying defects and security vulnerabilities. -- **Semgrep**: A lightweight static analysis tool for finding bugs and enforcing code standards. - -## Ethical Considerations - -### Responsible Disclosure -- **Vulnerability Reporting**: Ensure any vulnerabilities found are reported responsibly to the tool's maintainers. -- **Transparency**: Be transparent about the findings and provide clear and actionable recommendations. - -### Privacy -- **Data Handling**: Ensure that any data collected during the analysis is handled responsibly and in compliance with privacy regulations. -- **Confidentiality**: Maintain the confidentiality of any sensitive information discovered during the analysis. - -### Compliance -- **Regulatory Compliance**: Ensure that the analysis complies with relevant regulations and standards. -- **Industry Standards**: Adhere to industry best practices and standards for static analysis. - -## Next Steps - -### Step 1: Perform Static Analysis -1. **Run Clippy**: Identify common mistakes and improve code quality. -2. **Run Rustfmt**: Ensure the code is properly formatted. -3. **Run Cargo Audit**: Audit dependencies for security vulnerabilities. -4. **Run Cargo Deny**: Lint and enforce dependency licensing, security, and maintenance. - -### Step 2: Review Findings -1. **Analyze Results**: Review the results from the static analysis tools. -2. **Prioritize Issues**: Prioritize the issues based on their severity and impact. -3. **Document Findings**: Document the findings and provide clear and actionable recommendations. - -### Step 3: Report and Remediate -1. **Report Findings**: Report the findings to the tool's maintainers. -2. **Remediate Issues**: Work with the maintainers to remediate the identified issues. -3. **Verify Fixes**: Verify that the fixes have been applied and the issues have been resolved. - -### Step 4: Continuous Improvement -1. **Integrate Tools**: Integrate static analysis tools into the CI/CD pipeline to ensure continuous monitoring and improvement. -2. **Regular Audits**: Conduct regular audits to ensure the codebase remains secure and compliant. -3. **Training**: Provide training to developers on best practices for secure coding and static analysis. - -By following these steps, you can ensure that the `panic-attack` tool is thoroughly analyzed and any potential issues are identified and addressed. \ No newline at end of file diff --git a/panic_attack_static_analysis_results.adoc b/panic_attack_static_analysis_results.adoc new file mode 100644 index 0000000..ab89410 --- /dev/null +++ b/panic_attack_static_analysis_results.adoc @@ -0,0 +1,256 @@ +== Panic-Attack Static Analysis Results + +=== Executive Summary + +This document presents the results of the static analysis performed on +the `+panic-attack+` tool. The analysis includes findings from Clippy, +Rustfmt, and Cargo Audit, along with recommendations for addressing the +identified issues. + +=== Table of Contents + +[arabic] +. link:#clippy-findings[Clippy Findings] +. link:#rustfmt-findings[Rustfmt Findings] +. link:#cargo-audit-findings[Cargo Audit Findings] +. link:#summary-of-findings[Summary of Findings] +. link:#recommendations[Recommendations] + +=== Clippy Findings + +==== Overview + +Clippy identified several issues in the codebase, including redundant +code, complex types, and potential improvements. Below is a summary of +the key findings: + +==== Detailed Findings + +===== Redundant Locals + +* *File*: `+src/ambush/mod.rs:392:9+` +* *Issue*: Redundant redefinition of a binding `+addr+`. +* *Recommendation*: Remove the redundant redefinition. + +===== Missing Const for Thread Local + +* *File*: `+src/assail/analyzer.rs:23:68+` +* *Issue*: Initializer for `+thread_local+` value can be made `+const+`. +* *Recommendation*: Replace with `+const { RefCell::new(Vec::new()) }+`. + +===== Needless Range Loop + +* *File*: `+src/assail/analyzer.rs:900:30+` +* *Issue*: The loop variable `+k+` is only used to index `+chars+`. +* *Recommendation*: Consider using an iterator. + +===== Manual Repeat N + +* *File*: `+src/assail/analyzer.rs:906:32+` +* *Issue*: This `+repeat().take()+` can be written more concisely. +* *Recommendation*: Use `+repeat_n()+` instead. + +===== Collapsible If + +* *File*: `+src/assail/analyzer.rs:1403:9+` +* *Issue*: This `+if+` statement can be collapsed. +* *Recommendation*: Collapse nested if block. + +===== Doc Lazy Continuation + +* *Files*: +** `+src/attestation/chain.rs:37:5+` +** `+src/attestation/chain.rs:38:5+` +** `+src/attestation/chain.rs:39:5+` +** `+src/attestation/chain.rs:202:9+` +** `+src/attestation/chain.rs:203:9+` +* *Issue*: Doc list item without indentation. +* *Recommendation*: Indent the lines or add a blank line. + +===== Too Many Arguments + +* *File*: `+src/axial/mod.rs:359:1+` +* *Issue*: This function has too many arguments (9/7). +* *Recommendation*: Refactor the function to reduce the number of +arguments. + +===== Derivable Impls + +* *Files*: +** `+src/i18n/catalog.rs:114:1+` +** `+src/types.rs:520:1+` +** `+src/types.rs:599:1+` +* *Issue*: This `+impl+` can be derived. +* *Recommendation*: Replace the manual implementation with a derive +attribute. + +===== Needless Lifetimes + +* *File*: `+src/i18n/catalog.rs:165:17+` +* *Issue*: The following explicit lifetimes could be elided: ’a. +* *Recommendation*: Elide the lifetimes. + +===== New Without Default + +* *Files*: +** `+src/kanren/core.rs:390:5+` +** `+src/report/formatter.rs:25:5+` +* *Issue*: You should consider adding a `+Default+` implementation. +* *Recommendation*: Add a `+Default+` implementation. + +===== Redundant Closure + +* *File*: `+src/kanren/strategy.rs:89:14+` +* *Issue*: Redundant closure. +* *Recommendation*: Replace the closure with the function itself. + +===== Useless Format + +* *File*: `+src/panll/mod.rs:260:30+` +* *Issue*: Useless use of `+format!+`. +* *Recommendation*: Use `+.to_string()+` instead. + +===== Should Implement Trait + +* *File*: `+src/storage/mod.rs:33:5+` +* *Issue*: Method `+from_str+` can be confused for the standard trait +method `+std::str::FromStr::from_str+`. +* *Recommendation*: Consider implementing the trait +`+std::str::FromStr+` or choosing a less ambiguous method name. + +===== Upper Case Acronyms + +* *Files*: +** `+src/types.rs:87:5+` +** `+src/types.rs:88:5+` +** `+src/types.rs:235:5+` +* *Issue*: Name contains a capitalized acronym. +* *Recommendation*: Consider making the acronym lowercase, except the +initial letter. + +===== Type Complexity + +* *File*: `+src/main.rs:949:6+` +* *Issue*: Very complex type used. Consider factoring parts into +`+type+` definitions. +* *Recommendation*: Factor parts into `+type+` definitions. + +===== Print Literal + +* *File*: `+src/main.rs:2247:68+` +* *Issue*: Literal with an empty format string. +* *Recommendation*: Remove the empty format string. + +===== Single Component Path Imports + +* *Files*: +** `+src/a2ml/mod.rs:12:1+` +** `+src/storage/mod.rs:20:1+` +* *Issue*: This import is redundant. +* *Recommendation*: Remove the redundant import. + +==== Summary of Clippy Findings + +* *Total Warnings*: 24 warnings (17 duplicates). +* *Suggestions Applied*: 11 suggestions can be applied automatically +using `+cargo clippy --fix+`. + +=== Rustfmt Findings + +==== Overview + +Rustfmt did not identify any formatting issues in the codebase. The code +is properly formatted according to Rust style guidelines. + +==== Summary of Rustfmt Findings + +* *Total Issues*: 0. + +=== Cargo Audit Findings + +==== Overview + +Cargo Audit identified one security advisory in the dependencies of the +`+panic-attack+` tool. Below is a summary of the key findings: + +==== Detailed Findings + +===== Rand Unsound + +* *Crate*: `+rand+` +* *Version*: `+0.9.2+` +* *Warning*: Unsound +* *Title*: Rand is unsound with a custom logger using `+rand::rng()+` +* *Date*: 2026-04-09 +* *ID*: RUSTSEC-2026-0097 +* *URL*: https://rustsec.org/advisories/RUSTSEC-2026-0097 +* *Dependency Tree*: ++ +.... +rand 0.9.2 +└── proptest 1.11.0 + └── panic-attack 2.5.0 +.... + +==== Summary of Cargo Audit Findings + +* *Total Warnings*: 1 allowed warning found. + +=== Summary of Findings + +==== Clippy + +* *Total Warnings*: 24 warnings (17 duplicates). +* *Suggestions Applied*: 11 suggestions can be applied automatically. + +==== Rustfmt + +* *Total Issues*: 0. + +==== Cargo Audit + +* *Total Warnings*: 1 allowed warning found. + +=== Recommendations + +==== Clippy + +[arabic] +. *Apply Automatic Fixes*: Run `+cargo clippy --fix+` to apply the +suggested fixes automatically. +. *Refactor Complex Functions*: Refactor functions with too many +arguments to reduce complexity. +. *Improve Documentation*: Fix documentation formatting issues to ensure +clarity and consistency. +. *Use Derive Attributes*: Replace manual implementations with derive +attributes where possible. +. *Simplify Code*: Replace redundant closures and simplify complex +types. + +==== Rustfmt + +[arabic] +. *Maintain Formatting*: Continue to use Rustfmt to ensure consistent +code formatting. + +==== Cargo Audit + +[arabic] +. *Update Dependencies*: Update the `+rand+` crate to a version that +addresses the identified security issue. +. *Monitor Dependencies*: Regularly audit dependencies to ensure they +are up-to-date and secure. + +==== General Recommendations + +[arabic] +. *Integrate Tools*: Integrate Clippy, Rustfmt, and Cargo Audit into the +CI/CD pipeline to ensure continuous monitoring and improvement. +. *Regular Audits*: Conduct regular audits to ensure the codebase +remains secure and compliant. +. *Training*: Provide training to developers on best practices for +secure coding and static analysis. + +By addressing these findings and recommendations, the `+panic-attack+` +tool can be improved in terms of code quality, security, and +maintainability. diff --git a/panic_attack_static_analysis_results.md b/panic_attack_static_analysis_results.md deleted file mode 100644 index d75c1ec..0000000 --- a/panic_attack_static_analysis_results.md +++ /dev/null @@ -1,192 +0,0 @@ - - -# Panic-Attack Static Analysis Results - -## Executive Summary -This document presents the results of the static analysis performed on the `panic-attack` tool. The analysis includes findings from Clippy, Rustfmt, and Cargo Audit, along with recommendations for addressing the identified issues. - -## Table of Contents -1. [Clippy Findings](#clippy-findings) -2. [Rustfmt Findings](#rustfmt-findings) -3. [Cargo Audit Findings](#cargo-audit-findings) -4. [Summary of Findings](#summary-of-findings) -5. [Recommendations](#recommendations) - -## Clippy Findings - -### Overview -Clippy identified several issues in the codebase, including redundant code, complex types, and potential improvements. Below is a summary of the key findings: - -### Detailed Findings - -#### Redundant Locals -- **File**: `src/ambush/mod.rs:392:9` -- **Issue**: Redundant redefinition of a binding `addr`. -- **Recommendation**: Remove the redundant redefinition. - -#### Missing Const for Thread Local -- **File**: `src/assail/analyzer.rs:23:68` -- **Issue**: Initializer for `thread_local` value can be made `const`. -- **Recommendation**: Replace with `const { RefCell::new(Vec::new()) }`. - -#### Needless Range Loop -- **File**: `src/assail/analyzer.rs:900:30` -- **Issue**: The loop variable `k` is only used to index `chars`. -- **Recommendation**: Consider using an iterator. - -#### Manual Repeat N -- **File**: `src/assail/analyzer.rs:906:32` -- **Issue**: This `repeat().take()` can be written more concisely. -- **Recommendation**: Use `repeat_n()` instead. - -#### Collapsible If -- **File**: `src/assail/analyzer.rs:1403:9` -- **Issue**: This `if` statement can be collapsed. -- **Recommendation**: Collapse nested if block. - -#### Doc Lazy Continuation -- **Files**: - - `src/attestation/chain.rs:37:5` - - `src/attestation/chain.rs:38:5` - - `src/attestation/chain.rs:39:5` - - `src/attestation/chain.rs:202:9` - - `src/attestation/chain.rs:203:9` -- **Issue**: Doc list item without indentation. -- **Recommendation**: Indent the lines or add a blank line. - -#### Too Many Arguments -- **File**: `src/axial/mod.rs:359:1` -- **Issue**: This function has too many arguments (9/7). -- **Recommendation**: Refactor the function to reduce the number of arguments. - -#### Derivable Impls -- **Files**: - - `src/i18n/catalog.rs:114:1` - - `src/types.rs:520:1` - - `src/types.rs:599:1` -- **Issue**: This `impl` can be derived. -- **Recommendation**: Replace the manual implementation with a derive attribute. - -#### Needless Lifetimes -- **File**: `src/i18n/catalog.rs:165:17` -- **Issue**: The following explicit lifetimes could be elided: 'a. -- **Recommendation**: Elide the lifetimes. - -#### New Without Default -- **Files**: - - `src/kanren/core.rs:390:5` - - `src/report/formatter.rs:25:5` -- **Issue**: You should consider adding a `Default` implementation. -- **Recommendation**: Add a `Default` implementation. - -#### Redundant Closure -- **File**: `src/kanren/strategy.rs:89:14` -- **Issue**: Redundant closure. -- **Recommendation**: Replace the closure with the function itself. - -#### Useless Format -- **File**: `src/panll/mod.rs:260:30` -- **Issue**: Useless use of `format!`. -- **Recommendation**: Use `.to_string()` instead. - -#### Should Implement Trait -- **File**: `src/storage/mod.rs:33:5` -- **Issue**: Method `from_str` can be confused for the standard trait method `std::str::FromStr::from_str`. -- **Recommendation**: Consider implementing the trait `std::str::FromStr` or choosing a less ambiguous method name. - -#### Upper Case Acronyms -- **Files**: - - `src/types.rs:87:5` - - `src/types.rs:88:5` - - `src/types.rs:235:5` -- **Issue**: Name contains a capitalized acronym. -- **Recommendation**: Consider making the acronym lowercase, except the initial letter. - -#### Type Complexity -- **File**: `src/main.rs:949:6` -- **Issue**: Very complex type used. Consider factoring parts into `type` definitions. -- **Recommendation**: Factor parts into `type` definitions. - -#### Print Literal -- **File**: `src/main.rs:2247:68` -- **Issue**: Literal with an empty format string. -- **Recommendation**: Remove the empty format string. - -#### Single Component Path Imports -- **Files**: - - `src/a2ml/mod.rs:12:1` - - `src/storage/mod.rs:20:1` -- **Issue**: This import is redundant. -- **Recommendation**: Remove the redundant import. - -### Summary of Clippy Findings -- **Total Warnings**: 24 warnings (17 duplicates). -- **Suggestions Applied**: 11 suggestions can be applied automatically using `cargo clippy --fix`. - -## Rustfmt Findings - -### Overview -Rustfmt did not identify any formatting issues in the codebase. The code is properly formatted according to Rust style guidelines. - -### Summary of Rustfmt Findings -- **Total Issues**: 0. - -## Cargo Audit Findings - -### Overview -Cargo Audit identified one security advisory in the dependencies of the `panic-attack` tool. Below is a summary of the key findings: - -### Detailed Findings - -#### Rand Unsound -- **Crate**: `rand` -- **Version**: `0.9.2` -- **Warning**: Unsound -- **Title**: Rand is unsound with a custom logger using `rand::rng()` -- **Date**: 2026-04-09 -- **ID**: RUSTSEC-2026-0097 -- **URL**: [https://rustsec.org/advisories/RUSTSEC-2026-0097](https://rustsec.org/advisories/RUSTSEC-2026-0097) -- **Dependency Tree**: - ``` - rand 0.9.2 - └── proptest 1.11.0 - └── panic-attack 2.5.0 - ``` - -### Summary of Cargo Audit Findings -- **Total Warnings**: 1 allowed warning found. - -## Summary of Findings - -### Clippy -- **Total Warnings**: 24 warnings (17 duplicates). -- **Suggestions Applied**: 11 suggestions can be applied automatically. - -### Rustfmt -- **Total Issues**: 0. - -### Cargo Audit -- **Total Warnings**: 1 allowed warning found. - -## Recommendations - -### Clippy -1. **Apply Automatic Fixes**: Run `cargo clippy --fix` to apply the suggested fixes automatically. -2. **Refactor Complex Functions**: Refactor functions with too many arguments to reduce complexity. -3. **Improve Documentation**: Fix documentation formatting issues to ensure clarity and consistency. -4. **Use Derive Attributes**: Replace manual implementations with derive attributes where possible. -5. **Simplify Code**: Replace redundant closures and simplify complex types. - -### Rustfmt -1. **Maintain Formatting**: Continue to use Rustfmt to ensure consistent code formatting. - -### Cargo Audit -1. **Update Dependencies**: Update the `rand` crate to a version that addresses the identified security issue. -2. **Monitor Dependencies**: Regularly audit dependencies to ensure they are up-to-date and secure. - -### General Recommendations -1. **Integrate Tools**: Integrate Clippy, Rustfmt, and Cargo Audit into the CI/CD pipeline to ensure continuous monitoring and improvement. -2. **Regular Audits**: Conduct regular audits to ensure the codebase remains secure and compliant. -3. **Training**: Provide training to developers on best practices for secure coding and static analysis. - -By addressing these findings and recommendations, the `panic-attack` tool can be improved in terms of code quality, security, and maintainability. \ No newline at end of file diff --git a/panic_attack_static_analysis_summary.adoc b/panic_attack_static_analysis_summary.adoc new file mode 100644 index 0000000..0659ef9 --- /dev/null +++ b/panic_attack_static_analysis_summary.adoc @@ -0,0 +1,204 @@ +== Panic-Attack Static Analysis Summary + +=== Executive Summary + +This document summarizes the static analysis performed on the +`+panic-attack+` tool and the changes made to address the identified +issues. + +=== Table of Contents + +[arabic] +. link:#clippy-findings-and-fixes[Clippy Findings and Fixes] +. link:#rustfmt-findings[Rustfmt Findings] +. link:#cargo-audit-findings-and-fixes[Cargo Audit Findings and Fixes] +. link:#summary-of-changes[Summary of Changes] +. link:#next-steps[Next Steps] + +=== Clippy Findings and Fixes + +==== Overview + +Clippy identified several issues in the codebase, including redundant +code, complex types, and potential improvements. Below is a summary of +the key findings and the fixes applied: + +==== Detailed Findings and Fixes + +===== Redundant Locals + +* *File*: `+src/ambush/mod.rs:395:9+` +* *Issue*: Redundant redefinition of a binding `+addr+`. +* *Fix*: Removed the redundant redefinition. + +===== Needless Range Loop + +* *File*: `+src/assail/analyzer.rs:901:30+` +* *Issue*: The loop variable `+k+` is only used to index `+chars+`. +* *Fix*: Replaced the range loop with an iterator. + +===== Documentation Formatting + +* *Files*: `+src/attestation/chain.rs+` +* *Issue*: Doc list items without indentation. +* *Fix*: Added proper indentation to documentation list items. + +===== Too Many Arguments + +* *File*: `+src/axial/mod.rs:359:1+` +* *Issue*: The function `+run_once+` had too many arguments (9/7). +* *Fix*: Refactored the function to use a `+RunOnceConfig+` struct to +reduce the number of arguments. + +===== Derivable Impls + +* *Files*: +** `+src/i18n/catalog.rs:114:1+` +** `+src/types.rs:520:1+` +** `+src/types.rs:599:1+` +* *Issue*: Manual implementations that can be derived. +* *Fix*: Replaced manual implementations with derive attributes. + +===== Needless Lifetimes + +* *File*: `+src/i18n/catalog.rs:165:17+` +* *Issue*: Explicit lifetimes that could be elided. +* *Fix*: Elided the lifetimes. + +===== New Without Default + +* *Files*: +** `+src/kanren/core.rs:390:5+` +** `+src/report/formatter.rs:25:5+` +* *Issue*: Missing `+Default+` implementations. +* *Fix*: Added `+Default+` implementations. + +===== Redundant Closure + +* *File*: `+src/kanren/strategy.rs:89:14+` +* *Issue*: Redundant closure. +* *Fix*: Replaced the closure with the function itself. + +===== Useless Format + +* *File*: `+src/panll/mod.rs:260:30+` +* *Issue*: Useless use of `+format!+`. +* *Fix*: Used `+.to_string()+` instead. + +===== Should Implement Trait + +* *File*: `+src/storage/mod.rs:33:5+` +* *Issue*: Method `+from_str+` can be confused for the standard trait +method `+std::str::FromStr::from_str+`. +* *Fix*: Implemented the `+FromStr+` trait for `+StorageMode+`. + +===== Upper Case Acronyms + +* *Files*: +** `+src/types.rs:88:5+` +** `+src/types.rs:90:5+` +** `+src/types.rs:241:5+` +* *Issue*: Names containing capitalized acronyms. +* *Fix*: Added `+#[allow(clippy::upper_case_acronyms)]+` attributes to +the relevant enums. + +===== Type Complexity + +* *File*: `+src/main.rs:948:6+` +* *Issue*: Very complex type used. +* *Fix*: Defined a type alias `+AttackOverrides+` to simplify the return +type. + +==== Summary of Clippy Fixes + +* *Total Warnings*: 24 warnings (17 duplicates). +* *Suggestions Applied*: 11 suggestions applied automatically using +`+cargo clippy --fix+`. +* *Manual Fixes*: Applied manual fixes to address the remaining +warnings. + +=== Rustfmt Findings + +==== Overview + +Rustfmt did not identify any formatting issues in the codebase. The code +is properly formatted according to Rust style guidelines. + +==== Summary of Rustfmt Findings + +* *Total Issues*: 0. + +=== Cargo Audit Findings and Fixes + +==== Overview + +Cargo Audit identified one security advisory in the dependencies of the +`+panic-attack+` tool. Below is a summary of the key findings and the +fix applied: + +==== Detailed Findings and Fixes + +===== Rand Unsound + +* *Crate*: `+rand+` +* *Version*: `+0.9.2+` +* *Warning*: Unsound +* *Title*: Rand is unsound with a custom logger using `+rand::rng()+` +* *Date*: 2026-04-09 +* *ID*: RUSTSEC-2026-0097 +* *URL*: https://rustsec.org/advisories/RUSTSEC-2026-0097 +* *Fix*: Updated the `+rand+` crate to version `+0.9.4+`. + +==== Summary of Cargo Audit Fixes + +* *Total Warnings*: 1 allowed warning found. +* *Fix Applied*: Updated the `+rand+` crate to address the security +issue. + +=== Summary of Changes + +==== Clippy + +[arabic] +. *Applied Automatic Fixes*: Ran `+cargo clippy --fix+` to apply the +suggested fixes automatically. +. *Refactored Complex Functions*: Refactored the `+run_once+` function +to use a `+RunOnceConfig+` struct to reduce the number of arguments. +. *Improved Documentation*: Fixed documentation formatting issues to +ensure clarity and consistency. +. *Used Derive Attributes*: Replaced manual implementations with derive +attributes where possible. +. *Simplified Code*: Replaced redundant closures and simplified complex +types. +. *Implemented Traits*: Implemented the `+FromStr+` trait for +`+StorageMode+`. +. *Suppressed Warnings*: Added `+#[allow(clippy::upper_case_acronyms)]+` +attributes to suppress warnings for specific enums. + +==== Rustfmt + +[arabic] +. *Maintained Formatting*: Ensured the code is properly formatted +according to Rust style guidelines. + +==== Cargo Audit + +[arabic] +. *Updated Dependencies*: Updated the `+rand+` crate to version +`+0.9.4+` to address the identified security issue. + +=== Next Steps + +==== General Recommendations + +[arabic] +. *Integrate Tools*: Integrate Clippy, Rustfmt, and Cargo Audit into the +CI/CD pipeline to ensure continuous monitoring and improvement. +. *Regular Audits*: Conduct regular audits to ensure the codebase +remains secure and compliant. +. *Training*: Provide training to developers on best practices for +secure coding and static analysis. + +By addressing these findings and recommendations, the `+panic-attack+` +tool has been improved in terms of code quality, security, and +maintainability. diff --git a/panic_attack_static_analysis_summary.md b/panic_attack_static_analysis_summary.md deleted file mode 100644 index 75a2635..0000000 --- a/panic_attack_static_analysis_summary.md +++ /dev/null @@ -1,148 +0,0 @@ - - -# Panic-Attack Static Analysis Summary - -## Executive Summary -This document summarizes the static analysis performed on the `panic-attack` tool and the changes made to address the identified issues. - -## Table of Contents -1. [Clippy Findings and Fixes](#clippy-findings-and-fixes) -2. [Rustfmt Findings](#rustfmt-findings) -3. [Cargo Audit Findings and Fixes](#cargo-audit-findings-and-fixes) -4. [Summary of Changes](#summary-of-changes) -5. [Next Steps](#next-steps) - -## Clippy Findings and Fixes - -### Overview -Clippy identified several issues in the codebase, including redundant code, complex types, and potential improvements. Below is a summary of the key findings and the fixes applied: - -### Detailed Findings and Fixes - -#### Redundant Locals -- **File**: `src/ambush/mod.rs:395:9` -- **Issue**: Redundant redefinition of a binding `addr`. -- **Fix**: Removed the redundant redefinition. - -#### Needless Range Loop -- **File**: `src/assail/analyzer.rs:901:30` -- **Issue**: The loop variable `k` is only used to index `chars`. -- **Fix**: Replaced the range loop with an iterator. - -#### Documentation Formatting -- **Files**: `src/attestation/chain.rs` -- **Issue**: Doc list items without indentation. -- **Fix**: Added proper indentation to documentation list items. - -#### Too Many Arguments -- **File**: `src/axial/mod.rs:359:1` -- **Issue**: The function `run_once` had too many arguments (9/7). -- **Fix**: Refactored the function to use a `RunOnceConfig` struct to reduce the number of arguments. - -#### Derivable Impls -- **Files**: - - `src/i18n/catalog.rs:114:1` - - `src/types.rs:520:1` - - `src/types.rs:599:1` -- **Issue**: Manual implementations that can be derived. -- **Fix**: Replaced manual implementations with derive attributes. - -#### Needless Lifetimes -- **File**: `src/i18n/catalog.rs:165:17` -- **Issue**: Explicit lifetimes that could be elided. -- **Fix**: Elided the lifetimes. - -#### New Without Default -- **Files**: - - `src/kanren/core.rs:390:5` - - `src/report/formatter.rs:25:5` -- **Issue**: Missing `Default` implementations. -- **Fix**: Added `Default` implementations. - -#### Redundant Closure -- **File**: `src/kanren/strategy.rs:89:14` -- **Issue**: Redundant closure. -- **Fix**: Replaced the closure with the function itself. - -#### Useless Format -- **File**: `src/panll/mod.rs:260:30` -- **Issue**: Useless use of `format!`. -- **Fix**: Used `.to_string()` instead. - -#### Should Implement Trait -- **File**: `src/storage/mod.rs:33:5` -- **Issue**: Method `from_str` can be confused for the standard trait method `std::str::FromStr::from_str`. -- **Fix**: Implemented the `FromStr` trait for `StorageMode`. - -#### Upper Case Acronyms -- **Files**: - - `src/types.rs:88:5` - - `src/types.rs:90:5` - - `src/types.rs:241:5` -- **Issue**: Names containing capitalized acronyms. -- **Fix**: Added `#[allow(clippy::upper_case_acronyms)]` attributes to the relevant enums. - -#### Type Complexity -- **File**: `src/main.rs:948:6` -- **Issue**: Very complex type used. -- **Fix**: Defined a type alias `AttackOverrides` to simplify the return type. - -### Summary of Clippy Fixes -- **Total Warnings**: 24 warnings (17 duplicates). -- **Suggestions Applied**: 11 suggestions applied automatically using `cargo clippy --fix`. -- **Manual Fixes**: Applied manual fixes to address the remaining warnings. - -## Rustfmt Findings - -### Overview -Rustfmt did not identify any formatting issues in the codebase. The code is properly formatted according to Rust style guidelines. - -### Summary of Rustfmt Findings -- **Total Issues**: 0. - -## Cargo Audit Findings and Fixes - -### Overview -Cargo Audit identified one security advisory in the dependencies of the `panic-attack` tool. Below is a summary of the key findings and the fix applied: - -### Detailed Findings and Fixes - -#### Rand Unsound -- **Crate**: `rand` -- **Version**: `0.9.2` -- **Warning**: Unsound -- **Title**: Rand is unsound with a custom logger using `rand::rng()` -- **Date**: 2026-04-09 -- **ID**: RUSTSEC-2026-0097 -- **URL**: [https://rustsec.org/advisories/RUSTSEC-2026-0097](https://rustsec.org/advisories/RUSTSEC-2026-0097) -- **Fix**: Updated the `rand` crate to version `0.9.4`. - -### Summary of Cargo Audit Fixes -- **Total Warnings**: 1 allowed warning found. -- **Fix Applied**: Updated the `rand` crate to address the security issue. - -## Summary of Changes - -### Clippy -1. **Applied Automatic Fixes**: Ran `cargo clippy --fix` to apply the suggested fixes automatically. -2. **Refactored Complex Functions**: Refactored the `run_once` function to use a `RunOnceConfig` struct to reduce the number of arguments. -3. **Improved Documentation**: Fixed documentation formatting issues to ensure clarity and consistency. -4. **Used Derive Attributes**: Replaced manual implementations with derive attributes where possible. -5. **Simplified Code**: Replaced redundant closures and simplified complex types. -6. **Implemented Traits**: Implemented the `FromStr` trait for `StorageMode`. -7. **Suppressed Warnings**: Added `#[allow(clippy::upper_case_acronyms)]` attributes to suppress warnings for specific enums. - -### Rustfmt -1. **Maintained Formatting**: Ensured the code is properly formatted according to Rust style guidelines. - -### Cargo Audit -1. **Updated Dependencies**: Updated the `rand` crate to version `0.9.4` to address the identified security issue. - -## Next Steps - -### General Recommendations -1. **Integrate Tools**: Integrate Clippy, Rustfmt, and Cargo Audit into the CI/CD pipeline to ensure continuous monitoring and improvement. -2. **Regular Audits**: Conduct regular audits to ensure the codebase remains secure and compliant. -3. **Training**: Provide training to developers on best practices for secure coding and static analysis. - -By addressing these findings and recommendations, the `panic-attack` tool has been improved in terms of code quality, security, and maintainability. \ No newline at end of file