Skip to content

Commit c3bfa3a

Browse files
hyperpolymathhyperpolymath
committed
Snapshot local work before sync
1 parent 2f280f1 commit c3bfa3a

5 files changed

Lines changed: 262 additions & 0 deletions

File tree

‎.github/workflows/casket-pages.yml‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# SPDX-License-Identifier: PMPL-1.0-or-later
2+
name: GitHub Pages
3+
4+
on:
5+
push:
6+
branches: [main, master]
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: read
11+
pages: write
12+
id-token: write
13+
14+
concurrency:
15+
group: "pages"
16+
cancel-in-progress: false
17+
18+
jobs:
19+
build:
20+
runs-on: ubuntu-latest
21+
steps:
22+
- name: Checkout
23+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
24+
25+
- name: Checkout casket-ssg
26+
uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4
27+
with:
28+
repository: hyperpolymath/casket-ssg
29+
path: .casket-ssg
30+
31+
- name: Setup GHCup
32+
uses: haskell-actions/setup@ec49483bfc012387b227434aba94f59a6ecd0900 # v2
33+
with:
34+
ghc-version: '9.8.2'
35+
cabal-version: '3.10'
36+
37+
- name: Cache Cabal
38+
uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4
39+
with:
40+
path: |
41+
~/.cabal/packages
42+
~/.cabal/store
43+
.casket-ssg/dist-newstyle
44+
key: ${{ runner.os }}-casket-${{ hashFiles('.casket-ssg/casket-ssg.cabal') }}
45+
46+
- name: Build casket-ssg
47+
working-directory: .casket-ssg
48+
run: cabal build
49+
50+
- name: Prepare site source
51+
shell: bash
52+
run: |
53+
set -euo pipefail
54+
rm -rf .site-src _site
55+
56+
if [ -d site ]; then
57+
cp -R site .site-src
58+
else
59+
mkdir -p .site-src
60+
TODAY="$(date +%Y-%m-%d)"
61+
REPO_NAME="${{ github.event.repository.name }}"
62+
REPO_URL="https://github.com/${{ github.repository }}"
63+
README_URL=""
64+
65+
if [ -f README.md ]; then
66+
README_URL="${REPO_URL}/blob/${{ github.ref_name }}/README.md"
67+
elif [ -f README.adoc ]; then
68+
README_URL="${REPO_URL}/blob/${{ github.ref_name }}/README.adoc"
69+
fi
70+
71+
{
72+
echo "---"
73+
echo "title: ${REPO_NAME}"
74+
echo "date: ${TODAY}"
75+
echo "---"
76+
echo
77+
echo "# ${REPO_NAME}"
78+
echo
79+
echo "Static documentation site for ${REPO_NAME}."
80+
echo
81+
echo "- Source repository: [${{ github.repository }}](${REPO_URL})"
82+
if [ -n "${README_URL}" ]; then
83+
echo "- README: [project README](${README_URL})"
84+
fi
85+
if [ -d docs ]; then
86+
echo "- Docs directory: [docs/](${REPO_URL}/tree/${{ github.ref_name }}/docs)"
87+
fi
88+
echo
89+
echo "Project-specific site content can be added later under site/."
90+
} > .site-src/index.md
91+
fi
92+
93+
- name: Build site
94+
run: |
95+
mkdir -p _site
96+
cd .casket-ssg && cabal run casket-ssg -- build ../.site-src ../_site
97+
touch ../_site/.nojekyll
98+
99+
- name: Setup Pages
100+
uses: actions/configure-pages@983d7736d9b0ae728b81ab479565c72886d7745b # v5
101+
102+
- name: Upload artifact
103+
uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa # v3
104+
with:
105+
path: '_site'
106+
107+
deploy:
108+
environment:
109+
name: github-pages
110+
url: ${{ steps.deployment.outputs.page_url }}
111+
runs-on: ubuntu-latest
112+
needs: build
113+
steps:
114+
- name: Deploy to GitHub Pages
115+
id: deployment
116+
uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4

‎README.adoc‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,44 @@ It is designed to be **trustworthy**.
141141

142142
---
143143

144+
== CLI & Automation
145+
146+
`panic-attack` is a Clap-powered CLI. Each subcommand inherits a shared set of knobs so the UX is consistent whether developers run `assail`, `attack`, `assault`, `temporal`, `panll`, `groove`, or another entry point.
147+
148+
=== Global options
149+
150+
Globally applied flags let automation pipelines control verbosity, output format, storage location, and presentation. Current defaults are:
151+
152+
[cols="1,1,6",options="header"]
153+
|===
154+
| Flag | Default | Description
155+
| `--report-view` | `Accordion` | Controls the presentation mode (`Accordion`, `Summary`, `Timeline`) that the CLI writes and that PanLL mirrors.
156+
| `--expand-sections` | `false` | Expands extra detail blocks in the formatted report.
157+
| `--output-format` | `json` | Chooses how the artifact is serialized (`json`, `markdown`, or `text`); the CLI reuses this when it writes PanLL exports or temporal diffs.
158+
| `--pivot` | `false` | Rotates the narrative axis for boards that expect events-first storytelling.
159+
| `--store` | unset | Directory where generated reports, exports, and artifacts should land.
160+
| `--quiet` | `false` | Suppresses informational log lines for automation.
161+
| `--parallel` | `false` | Enables threaded execution when commands support it (assault, image, mass-panic).
162+
|===
163+
164+
Consult `man/panic-attack.1` or `panic-attack help` for every command, and use `panic-attack completions --shell <fish|zsh|bash|powershell|nushell>` to bootstrap automation-friendly helpers.
165+
166+
=== Automation readiness
167+
168+
`panic-attack diagnostics` validates AI manifests, VeriSimDB caches, Hypatia and gitbot-fleet watchers, and the docs PanLL expects (`docs/ambush-timeline.md`, `docs/panll-export.md`). `docs/patch-bridge-design.md` details how the patch-bridge subcommands plug into BoJ cartridges, CVE workflows, and the PanLL panel.
169+
170+
`just test-elixir` runs the Elixir harnesses that cover the CLI surface so documentation, help text, and automation flags stay aligned.
171+
172+
== Integration & Groove
173+
174+
panic-attack can emit PanLL-friendly exports (event chains, system images, temporal diffs) per `docs/panll-export.md`, and it also advertises its static-analysis capability via the Gossamer groove protocol. Start the discovery endpoint with `panic-attack groove --port 7600` and check the JSON manifest by curling `http://localhost:7600/.well-known/groove` (the health endpoint sits at `/health`).
175+
176+
The manifest follows the Idris-aligned semantics that live in `boj-server/src/interface/abi/Groove.idr` and the `gossamer` schema references. As a result, any groove-aware consumer—PanLL event-chain panels, the Burble voice platform, Hypatia, or other automation fabrics—sees the same capability vocabulary and can attach its own UI (Groove + Burble PanLL) confidently.
177+
178+
VeriSimDB remains the foundation dependency for these exports, so every snapshot recorded for PanLL, Gossamer, or Burble can be replayed, inspected, and audited even after the CLI process exits.
179+
180+
---
181+
144182
== Status
145183

146184
Current state: **v2.1.0**

‎docs/panll-export.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,28 @@ Notes:
5959

6060
Future versions can enrich this export with constraints, event dependencies,
6161
and a full PanLL graph import/export pipeline.
62+
63+
## Groove discovery
64+
65+
panic-attack also advertises its export capability through the Gossamer groove
66+
protocol so PanLL and other groove-aware systems can discover it automatically.
67+
Run `panic-attack groove --port 7600` and curl
68+
`http://localhost:7600/.well-known/groove` to verify the manifest. The minimal
69+
HTTP server answers `/health` for automated monitoring, and gossamer/panll
70+
consumers can read the `static_analysis` capability description to confirm the
71+
service identity.
72+
73+
The JSON manifest mirrors the Idris-aligned semantics under
74+
`boj-server/src/interface/abi/Groove.idr` and the shared `gossamer/schema`
75+
definitions, so every consumer (Gossamer, PanLL, Hypatia, or Burble) sees the
76+
same capability vocabulary and can negotiate the link with confidence.
77+
78+
## Gossamer + Burble PanLL
79+
80+
When Gossamer (or a Burble-powered PanLL UI) discovers panic-attack via groove,
81+
PanLL panels can auto-bind the static analysis service into PanLL’s event-chain
82+
flows. Those panels load the exported `panll.event-chain.v0` artifacts documented
83+
here, referencing the same VeriSimDB snapshot that supplies every proof and
84+
benchmark baseline. VeriSimDB acts as the foundation dependency so the historical
85+
timeline that PanLL renders stays aligned with the grooved manifest even after
86+
panic-attack exits.

‎docs/reports/audit/2026-03-30-panic-attack-audit.adoc‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
// SPDX-License-Identifier: PMPL-1.0-or-later
2+
= panic-attack Audit 2026-03-30
3+
:revdate: 2026-03-30
4+
5+
== Summary
6+
7+
Status: `fail` (implementation strong, publication blocked)
8+
9+
panic-attack is a mature security analysis suite: the README lists 196 passing
10+
tests, 47 supported languages, and multiple CLI modes. That makes it one of the
11+
headline wish-list tools for the estate, but the release gate still requires
12+
proof closure, green builds, and traceable invariants before any v1/stable
13+
claims get restored.
14+
15+
== Evidence log
16+
17+
* README claims: multi-language static analysis (47 langs), 20 weakness
18+
categories, attack simulation, system imaging, attestation, plus the
19+
event-chain export described in `panll-event-chain.json`.
20+
* `PROOF-NEEDS.md` records the current proof debt: analyzer soundness/completeness,
21+
SARIF correctness, CVE classification accuracy, reachability/taint invariants,
22+
attestation chain integrity, and lockfile parsing. Idris2 types exist only in
23+
`src/abi/Types.idr` and are minimal; large portions of the logic remain
24+
informal and would benefit from an Agda/Idris session.
25+
* `just test` runs `cargo test` but the build stops at `src/attestation/intent.rs:59`
26+
because `getrandom::getrandom` cannot be found in the version of the `getrandom`
27+
crate currently pulled in. The nightly compile log ends with `rustc` error
28+
E0425 (`cannot find function getrandom in crate getrandom`), so every test
29+
target fails before exercising anything beyond the first module.
30+
* `PROOF-NEEDS` also records 282 `unwrap()` calls scattered across the analyzer
31+
(already noted in the README as “dangerous patterns: 0 in our code but there
32+
are many `unwrap()`s because panic-attack hunts for them).
33+
34+
== Confirmed blockers
35+
36+
* `just test` fails immediately because `src/attestation/intent.rs` calls
37+
`getrandom::getrandom` but Rust cannot resolve that symbol in the dependency
38+
graph; until the crate dependency or feature set is corrected, there is no
39+
build/test evidence.
40+
* The proof debt is wide open: the analyzer’s detection/completeness invariants,
41+
the SARIF/attestation outputs, the miniKanren taint engine, and the bridge
42+
classification logic all have entries in `PROOF-NEEDS.md` and lack machine-checked
43+
scripts.
44+
* Template metadata such as `panic-attacker.toml.example`, `contractiles`
45+
scaffolding, and `docs/` narratives still expose TODOs about future
46+
system-level features, so the release gate sees residual preflight noise.
47+
48+
== Containment actions taken
49+
50+
* The README/ROADMAP/VISION files already insist the tool is for analysis and
51+
visibility, not for quiet operation; the gate now treats panic-attack as a
52+
research-grade scanner until the proofs and build-green status is restored.
53+
* `reports/` capture the latest assemblyline/adjudicate runs, so reviewers can
54+
see the operational output even though the upstream proofs remain untracked.
55+
* The `PROOF-NEEDS` document surfaced the high-priority invariants, so the next
56+
proof sessions have a defined backlog.
57+
58+
== Immediate next actions
59+
60+
* Fix the `getrandom` linkage: verify the `getrandom` dependency exposes `getrandom`
61+
or replace the call with a supported API (e.g., `rand::random`, `secrecy`
62+
wrappers, or a custom randomizer) so `cargo test`/`just test` can finish.
63+
* Schedule Claude-level proof sessions to mechanize analyzer soundness,
64+
taint propagation, SARIF validity, reachability accuracy, and the attestation
65+
chain described in `docs/assemblyline` outputs. Each theorem should produce a
66+
machine-checked Idris2/Agda file with zero `believe_me`.
67+
* Clean up the remaining template placeholders in the `contractiles`/`docs`
68+
directories so the release preflight does not flag `TODO` noise as proof debt.
69+
* Document the `self-*` reports (`self-a2ml.a2ml`, `self-roundtrip.json`) so
70+
reviewers can reproduce the scans and verify the attestation/assemblyline
71+
pipelines.
72+
73+
== Invitation for review
74+
75+
If you disagree with these blockers or can help close one, annotate this file
76+
or open an issue. We intentionally accept challenge; the goal is to make every
77+
release claim fact-based before we call it stable or publishable.

‎man/panic-attack.1‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -60,6 +60,12 @@ Encodes a report artifact as a schema-versioned A2ML report bundle (supports ass
6060
.B a2ml-import INPUT --output OUT [--kind KIND]
6161
Decodes an A2ML report bundle back into JSON (optionally assert expected kind).
6262
.TP
63+
.B completions --shell SHELL
64+
Generates shell tab-completion helpers for the CLI (fish, zsh, bash, powershell, and nushell). Use this before wiring automation so every flag and subcommand can be discovered programmatically.
65+
.TP
66+
.B groove [--port PORT]
67+
Starts a minimal HTTP groove discovery endpoint (default port 7600). The server answers `/.well-known/groove` with the manifest defined in `src/groove.rs` and `/health` for service monitors; Gossamer, PanLL, Hypatia, or Burble-aware clients can curl the manifest to see the `static_analysis` capability and fetch the exports documented in `docs/panll-export.md`.
68+
.TP
6369
.B panll REPORT [--out OUT]
6470
Converts an assault report into a PanLL event-chain JSON for Pane-W import.
6571
.TP

0 commit comments

Comments
 (0)