22
33## Overview
44
5- Static analysis and bug signature detection tool. Scans source code for weak points (unwrap/expect, unsafe blocks, panic sites, error handling gaps) across multiple languages.
5+ Static analysis and bug signature detection tool. Scans source code for weak points (unwrap/expect, unsafe blocks, panic sites, error handling gaps, command injection, unsafe deserialization, FFI boundaries, atom exhaustion, and more ) across 47 programming languages.
66
77** Position in AmbientOps ecosystem** : Part of the hospital model, loosely affiliated. Sits alongside the Operating Room as a diagnostic tool for software health (while hardware-crash-team handles hardware health). Independent top-level repo, but feeds findings to the hospital's Records system via verisimdb.
88
@@ -11,6 +11,8 @@ Static analysis and bug signature detection tool. Scans source code for weak poi
1111** IMPORTANT: This tool was renamed on 2026-02-08:**
1212- Binary: ` panic-attacker ` → ` panic-attack `
1313- Subcommand: ` xray ` → ` assail `
14+ - Module: ` src/xray/ ` → ` src/assail/ `
15+ - Type: ` XRayReport ` → ` AssailReport `
1416- Report header: ` X-RAY ` → ` ASSAIL `
1517
1618## Architecture
@@ -19,12 +21,26 @@ Static analysis and bug signature detection tool. Scans source code for weak poi
1921src/
2022├── main.rs # CLI entry point (clap)
2123├── lib.rs # Library API
22- ├── types.rs # Core types (ScanResult, WeakPoint, etc.)
23- ├── xray/mod.rs # Assail analyzer (renamed from xray internally)
24- ├── attacks/ # 6-axis stress testing
25- ├── signatures/ # Logic-based bug signatures (Datalog-inspired)
26- ├── patterns/ # Language-specific pattern matching
24+ ├── types.rs # Core types (AssailReport, WeakPoint, etc.)
25+ ├── assail/ # Static analysis engine
26+ │ ├── mod.rs # Public API: analyze(), analyze_verbose()
27+ │ ├── analyzer.rs # 47-language analyzer with per-file detection
28+ │ └── patterns.rs # Language-specific attack patterns
29+ ├── kanren/ # miniKanren-inspired logic engine (v2.0.0)
30+ │ ├── mod.rs # Module entry, re-exports
31+ │ ├── core.rs # Term, Substitution, unification, FactDB, forward chaining
32+ │ ├── taint.rs # TaintAnalyzer: source→sink tracking
33+ │ ├── crosslang.rs # CrossLangAnalyzer: FFI boundary detection
34+ │ └── strategy.rs # SearchStrategy: risk-weighted file prioritisation
35+ ├── attack/ # 6-axis stress testing
36+ │ ├── executor.rs # Attack execution engine
37+ │ └── strategies.rs # Per-axis attack strategies
38+ ├── signatures/ # Logic-based bug signature detection
39+ │ ├── engine.rs # SignatureEngine (use-after-free, deadlock, etc.)
40+ │ └── rules.rs # Detection rules
2741└── report/
42+ ├── mod.rs # Report generation API
43+ ├── generator.rs # AssaultReport builder
2844 └── formatter.rs # Output formatting (text + JSON)
2945```
3046
@@ -36,18 +52,31 @@ cargo test
3652
3753# Run scan:
3854panic-attack assail /path/to/repo
39- panic-attack assail /path/to/repo --format json --output report.json
40- panic-attack assail self-test # Self-scan for validation
55+ panic-attack assail /path/to/repo --output report.json
56+ panic-attack assail /path/to/repo --verbose
57+
58+ # Install:
59+ cp target/release/panic-attack ~ /.asdf/installs/rust/nightly/bin/
4160```
4261
4362## Key Design Decisions
4463
45- - ** 5 language analyzers** : Rust, C/C++, Go, Python, generic fallback
46- - ** Weak point categories** : unwrap/expect, unsafe blocks, panic sites, todo/fixme, error suppression
47- - ** Per-file statistics** : Each file gets individual risk scoring
64+ - ** 47 language analyzers** : Rust, C/C++, Go, Python, JavaScript, Ruby, Elixir, Erlang, Gleam, ReScript, OCaml, SML, Scheme, Racket, Haskell, PureScript, Idris, Lean, Agda, Prolog, Logtalk, Datalog, Zig, Ada, Odin, Nim, Pony, D, Nickel, Nix, Shell, Julia, Lua, + 12 nextgen DSLs
65+ - ** 20 weak point categories** : UnsafeCode, PanicPath, CommandInjection, UnsafeDeserialization, AtomExhaustion, UnsafeFFI, PathTraversal, HardcodedSecret, etc.
66+ - ** Per-file language detection** : Each file analyzed with its own language-specific patterns
67+ - ** miniKanren logic engine** : Relational reasoning for taint analysis, cross-language vulnerability chains, and search strategy optimisation
4868- ** Latin-1 fallback** : Non-UTF-8 files handled gracefully
4969- ** JSON output** : Machine-readable for pipeline integration
5070
71+ ## miniKanren Logic Engine (v2.0.0)
72+
73+ The kanren module provides:
74+ - ** Taint analysis** : Tracks data flow from sources (user input, network, deserialization) to sinks (eval, shell commands, SQL queries)
75+ - ** Cross-language reasoning** : Detects vulnerability chains across FFI/NIF/Port/subprocess boundaries
76+ - ** Search strategies** : Auto-selects RiskWeighted, BoundaryFirst, LanguageFamily, BreadthFirst, or DepthFirst based on project characteristics
77+ - ** Forward chaining** : Derives new vulnerability facts from rules applied to existing facts
78+ - ** Backward queries** : Given a vulnerability type, finds which files could cause it
79+
5180## Planned Features (Next Priorities)
5281
53821 . ** ` sweep ` subcommand** : Scan entire directory of git repos in one go
@@ -64,62 +93,9 @@ panic-attack assail self-test # Self-scan for validation
6493- ** sustainabot** : Ecological/economic code health metrics
6594- ** hardware-crash-team** : Sibling tool (hardware diagnostics vs software analysis)
6695
67- ## Sweep Subcommand (Priority - Sonnet Task)
68-
69- Add a ` sweep ` subcommand that scans an entire directory of git repos in one pass.
70-
71- ### Design
72-
73- ```
74- panic-attack sweep /path/to/repos/ [options]
75- --format json|text|sarif Output format (default: text)
76- --output report.json Save aggregate report
77- --push-to-verisimdb URL Push each result to verisimdb API
78- --push-to-data-repo PATH Write each result to verisimdb-data repo
79- --min-risk medium Only report repos at or above this risk level
80- --parallel N Number of concurrent scans (default: 4)
81- ```
82-
83- ### Implementation Steps
84-
85- 1 . Add ` Sweep ` variant to the ` Commands ` enum in main.rs
86- 2 . Walk the directory looking for ` .git/ ` subdirectories (use walkdir, already a dependency)
87- 3 . For each repo found, call the existing ` assail ` scan logic
88- 4 . Aggregate results into a summary report
89- 5 . Optionally push each result to verisimdb-data repo as JSON files
90- 6 . Print aggregate summary (total repos, total weak points, top offenders)
91-
92- ### verisimdb-data Integration
93-
94- When ` --push-to-data-repo ` is specified:
95- - Write each scan result to ` {data-repo}/scans/{repo-name}.json `
96- - Update ` {data-repo}/index.json ` with summary entry
97- - Git add + commit with message "scan: update {repo-name} results"
98-
99- ### GitHub Actions Reusable Workflow
100-
101- Create ` .github/workflows/scan-and-report.yml ` as a reusable workflow:
102- ``` yaml
103- # Other repos call this:
104- # uses: hyperpolymath/panic-attacker/.github/workflows/scan-and-report.yml@main
105- # This runs panic-attack assail on the calling repo
106- # and dispatches results to verisimdb-data
107- ```
108-
109- ## Scan Results from 2026-02-08 Session
110-
111- 21 repos scanned, 118 total weak points, zero critical, 17 high:
112- - protocol-squisher: 39 weak points (highest)
113- - echidna: 15 weak points
114- - verisimdb: 12 weak points
115- - Most high-severity findings are expected unsafe blocks in FFI/GC code
116-
117- Results loaded into verisimdb as hexads (verified working with text search).
118-
11996## Code Style
12097
12198- SPDX headers on all files: ` PMPL-1.0-or-later `
12299- Author: Jonathan D.A. Jewell <jonathan.jewell@open.ac.uk >
123100- Use anyhow::Result for error handling
124- - Zero compiler warnings policy
125101- Serde derive on public types for JSON serialization
0 commit comments