From 415c47c10e3e3ea98a5ea305fbe73c22ac482cd0 Mon Sep 17 00:00:00 2001 From: "Jonathan D.A. Jewell" <6759885+hyperpolymath@users.noreply.github.com> Date: Mon, 24 Aug 2026 08:33:50 +0100 Subject: [PATCH] refactor: migrate repository documentation from Markdown to AsciiDoc --- ARCHITECTURE.adoc | 48 + ARCHITECTURE.md | 47 - CHANGELOG.adoc | 9 + CHANGELOG.md | 11 - CODE_OF_CONDUCT.adoc | 24 + CODE_OF_CONDUCT.md | 27 - CONTRIBUTING.adoc | 71 ++ CONTRIBUTING.md | 66 -- GOVERNANCE.adoc | 60 + GOVERNANCE.md | 60 - PROOF-NEEDS.adoc | 53 + PROOF-NEEDS.md | 32 - README.adoc.invariants.adoc | 1 + README.adoc.invariants.md | 2 - SECURITY.adoc | 16 + SECURITY.md | 20 - TEST-NEEDS.adoc | 97 ++ TEST-NEEDS.md | 64 -- TOPOLOGY.adoc | 25 + TOPOLOGY.md | 24 - ...dge-design.md => patch-bridge-design.adoc} | 1017 +++++++++-------- llm-warmup-dev.adoc | 19 + llm-warmup-dev.md | 16 - llm-warmup-user.adoc | 19 + llm-warmup-user.md | 16 - 25 files changed, 1008 insertions(+), 836 deletions(-) create mode 100644 ARCHITECTURE.adoc delete mode 100644 ARCHITECTURE.md create mode 100644 CHANGELOG.adoc delete mode 100644 CHANGELOG.md create mode 100644 CODE_OF_CONDUCT.adoc delete mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.adoc delete mode 100644 CONTRIBUTING.md create mode 100644 GOVERNANCE.adoc delete mode 100644 GOVERNANCE.md create mode 100644 PROOF-NEEDS.adoc delete mode 100644 PROOF-NEEDS.md create mode 100644 README.adoc.invariants.adoc delete mode 100644 README.adoc.invariants.md create mode 100644 SECURITY.adoc delete mode 100644 SECURITY.md create mode 100644 TEST-NEEDS.adoc delete mode 100644 TEST-NEEDS.md create mode 100644 TOPOLOGY.adoc delete mode 100644 TOPOLOGY.md rename docs/{patch-bridge-design.md => patch-bridge-design.adoc} (59%) create mode 100644 llm-warmup-dev.adoc delete mode 100644 llm-warmup-dev.md create mode 100644 llm-warmup-user.adoc delete mode 100644 llm-warmup-user.md 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..ca1c652 --- /dev/null +++ b/CHANGELOG.adoc @@ -0,0 +1,9 @@ +== Changelog + +All notable changes to this project will be documented in this file. + +The format is based on https://keepachangelog.com/en/1.1.0/[Keep a +Changelog], and this project adheres to +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. + +=== [Unreleased] diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index 8109476..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,11 +0,0 @@ -# Changelog - -All notable changes to this project will be documented in this file. - -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - - - - -## [Unreleased] diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..bd2a83c --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,24 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We pledge to make participation a harassment-free experience for +everyone. + +=== Our Standards + +*Positive behavior:* * Using welcoming language * Being respectful of +differing viewpoints * Accepting constructive criticism * Focusing on +what is best for the community + +*Unacceptable behavior:* * Harassment, trolling, or personal attacks * +Publishing private information without permission + +=== Enforcement + +Report issues to the maintainers. All complaints will be reviewed. + +=== Attribution + +Adapted from https://www.contributor-covenant.org/[Contributor Covenant] +v2.1. diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index caeda1c..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,27 +0,0 @@ - -# Contributor Covenant Code of Conduct - -## Our Pledge - -We pledge to make participation a harassment-free experience for everyone. - -## Our Standards - -**Positive behavior:** -* Using welcoming language -* Being respectful of differing viewpoints -* Accepting constructive criticism -* Focusing on what is best for the community - -**Unacceptable behavior:** -* Harassment, trolling, or personal attacks -* Publishing private information without permission - -## Enforcement - -Report issues to the maintainers. All complaints will be reviewed. - -## Attribution - -Adapted from [Contributor Covenant](https://www.contributor-covenant.org/) v2.1. - diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc new file mode 100644 index 0000000..858f44f --- /dev/null +++ b/CONTRIBUTING.adoc @@ -0,0 +1,71 @@ +== Contributing + +Thank you for your interest in contributing! We follow a "`Dual-Track`" +architecture where human-readable documentation lives in the root and +machine-readable policies live in `+.machine_readable/+`. + +=== How to Contribute + +We welcome contributions in many forms: + +* *Code:* Improving the core stack or extensions +* *Documentation:* Enhancing docs or AI manifests +* *Testing:* Adding property-based tests or formal proofs +* *Bug reports:* Filing clear, reproducible issues + +=== Getting Started + +[arabic] +. *Read the AI Manifest:* Start with `+0-AI-MANIFEST.a2ml+` (if present) +to understand the repository structure. +. *Environment:* Use `+nix develop+` or `+direnv allow+` to set up your +tools. +. *Task Runner:* Use `+just+` to see available commands +(`+just --list+`). + +=== Development Workflow + +==== Branch Naming + +.... +docs/short-description # Documentation +test/what-added # Test additions +feat/short-description # New features +fix/issue-number-description # Bug fixes +refactor/what-changed # Code improvements +security/what-fixed # Security fixes +.... + +==== Commit Messages + +We follow https://www.conventionalcommits.org/[Conventional Commits]: + +.... +(): + +[optional body] + +[optional footer] +.... + +Types: `+feat+`, `+fix+`, `+docs+`, `+test+`, `+refactor+`, `+ci+`, +`+chore+`, `+security+` + +=== Reporting Bugs + +Before reporting: 1. Search existing issues 2. Check if it’s already +fixed in `+main+` + +When reporting, include: - Clear, descriptive title - Environment +details (OS, versions, toolchain) - Steps to reproduce - Expected vs +actual behaviour + +=== Code of Conduct + +All contributors are expected to adhere to our +link:CODE_OF_CONDUCT.md[Code of Conduct]. + +=== License + +By contributing, you agree that your contributions will be licensed +under the same license as the project (see LICENSE). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index 80ecdac..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,66 +0,0 @@ - -# Contributing - -Thank you for your interest in contributing! We follow a "Dual-Track" architecture where human-readable documentation lives in the root and machine-readable policies live in `.machine_readable/`. - -## How to Contribute - -We welcome contributions in many forms: - -- **Code:** Improving the core stack or extensions -- **Documentation:** Enhancing docs or AI manifests -- **Testing:** Adding property-based tests or formal proofs -- **Bug reports:** Filing clear, reproducible issues - -## Getting Started - -1. **Read the AI Manifest:** Start with `0-AI-MANIFEST.a2ml` (if present) to understand the repository structure. -2. **Environment:** Use `nix develop` or `direnv allow` to set up your tools. -3. **Task Runner:** Use `just` to see available commands (`just --list`). - -## Development Workflow - -### Branch Naming - -``` -docs/short-description # Documentation -test/what-added # Test additions -feat/short-description # New features -fix/issue-number-description # Bug fixes -refactor/what-changed # Code improvements -security/what-fixed # Security fixes -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): - -``` -(): - -[optional body] - -[optional footer] -``` - -Types: `feat`, `fix`, `docs`, `test`, `refactor`, `ci`, `chore`, `security` - -## Reporting Bugs - -Before reporting: -1. Search existing issues -2. Check if it's already fixed in `main` - -When reporting, include: -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour - -## Code of Conduct - -All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). - -## License - -By contributing, you agree that your contributions will be licensed under the same license as the project (see [LICENSE](LICENSE)). 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..9c518ae --- /dev/null +++ b/PROOF-NEEDS.adoc @@ -0,0 +1,53 @@ +== PROOF-NEEDS.md — patch-bridge + +=== Current State + +* *src/abi/*: YES — directory exists but is EMPTY +* *Dangerous patterns*: 0 in own code (6 references are in K9 +contractile guards that define ceilings) +* *LOC*: ~4,500 (Rust) +* *ABI layer*: Empty — needs Idris2 definitions + +=== What Needs Proving + +[width="100%",cols="51%,27%,22%",options="header",] +|=== +|Component |What |Why +|CVE classify correctness |Classification assigns correct severity and +category |Wrong classification leads to wrong mitigation priority + +|Lockfile parsing |Parser extracts correct dependency versions from all +lockfile formats |Wrong version extraction means wrong CVE matching + +|Reachability analysis |Analysis correctly determines if vulnerable code +is reachable |False reachable = wasted effort; false unreachable = +missed vulnerability + +|Registry lookup |CVE registry queries return correct, complete results +|Incomplete results miss known vulnerabilities + +|Patch adoption gate |Gate decision (adopt/defer/reject) is sound |Wrong +gate decision either blocks good patches or admits bad ones +|=== + +=== Recommended Prover + +*Idris2* — Populate empty `+src/abi/+` with types for CVE +classification, reachability analysis soundness, and adoption gate +decision correctness. Small enough codebase to achieve high proof +coverage. + +=== Priority + +*HIGH* — Patch Bridge is the CVE mitigation lifecycle tool. Incorrect +classification or reachability analysis directly impacts security +posture. The empty ABI directory signals this work was planned but never +started. + +=== Template ABI Cleanup (2026-03-29) + +Template ABI removed – was creating false impression of formal +verification. The removed files (Types.idr, Layout.idr, Foreign.idr) +contained only RSR template scaffolding with unresolved +PATCH_BRIDGE/Jonathan D.A. Jewell placeholders and no domain-specific +proofs. diff --git a/PROOF-NEEDS.md b/PROOF-NEEDS.md deleted file mode 100644 index cec24f3..0000000 --- a/PROOF-NEEDS.md +++ /dev/null @@ -1,32 +0,0 @@ -# PROOF-NEEDS.md — patch-bridge - -## Current State - -- **src/abi/**: YES — directory exists but is EMPTY -- **Dangerous patterns**: 0 in own code (6 references are in K9 contractile guards that define ceilings) -- **LOC**: ~4,500 (Rust) -- **ABI layer**: Empty — needs Idris2 definitions - -## What Needs Proving - -| Component | What | Why | -|-----------|------|-----| -| CVE classify correctness | Classification assigns correct severity and category | Wrong classification leads to wrong mitigation priority | -| Lockfile parsing | Parser extracts correct dependency versions from all lockfile formats | Wrong version extraction means wrong CVE matching | -| Reachability analysis | Analysis correctly determines if vulnerable code is reachable | False reachable = wasted effort; false unreachable = missed vulnerability | -| Registry lookup | CVE registry queries return correct, complete results | Incomplete results miss known vulnerabilities | -| Patch adoption gate | Gate decision (adopt/defer/reject) is sound | Wrong gate decision either blocks good patches or admits bad ones | - -## Recommended Prover - -**Idris2** — Populate empty `src/abi/` with types for CVE classification, reachability analysis soundness, and adoption gate decision correctness. Small enough codebase to achieve high proof coverage. - -## Priority - -**HIGH** — Patch Bridge is the CVE mitigation lifecycle tool. Incorrect classification or reachability analysis directly impacts security posture. The empty ABI directory signals this work was planned but never started. - -## Template ABI Cleanup (2026-03-29) - -Template ABI removed -- was creating false impression of formal verification. -The removed files (Types.idr, Layout.idr, Foreign.idr) contained only RSR template -scaffolding with unresolved PATCH_BRIDGE/Jonathan D.A. Jewell placeholders and no domain-specific proofs. diff --git a/README.adoc.invariants.adoc b/README.adoc.invariants.adoc new file mode 100644 index 0000000..80a5d0e --- /dev/null +++ b/README.adoc.invariants.adoc @@ -0,0 +1 @@ +== Invariant Path Scan: README.adoc diff --git a/README.adoc.invariants.md b/README.adoc.invariants.md deleted file mode 100644 index e9ccff7..0000000 --- a/README.adoc.invariants.md +++ /dev/null @@ -1,2 +0,0 @@ -# Invariant Path Scan: README.adoc - diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..e47fdd9 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,16 @@ +== Security Policy + +=== Reporting a Vulnerability + +If you discover a security vulnerability, please report it responsibly. + +*Email:* j.d.a.jewell@open.ac.uk + +*Please include:* - Description of the vulnerability - Steps to +reproduce - Potential impact + +*Response timeline:* - Acknowledgement within 48 hours - Initial +assessment within 7 days - Fix or mitigation within 90 days + +*Safe harbour:* We will not pursue legal action against security +researchers who follow responsible disclosure. diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5c4d5e9..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,20 +0,0 @@ - -# Security Policy - -## Reporting a Vulnerability - -If you discover a security vulnerability, please report it responsibly. - -**Email:** j.d.a.jewell@open.ac.uk - -**Please include:** -- Description of the vulnerability -- Steps to reproduce -- Potential impact - -**Response timeline:** -- Acknowledgement within 48 hours -- Initial assessment within 7 days -- Fix or mitigation within 90 days - -**Safe harbour:** We will not pursue legal action against security researchers who follow responsible disclosure. diff --git a/TEST-NEEDS.adoc b/TEST-NEEDS.adoc new file mode 100644 index 0000000..c525a94 --- /dev/null +++ b/TEST-NEEDS.adoc @@ -0,0 +1,97 @@ +== TEST-NEEDS.md — patch-bridge + +=== CRG Grade: C — ACHIEVED 2026-04-04 + +____ +Generated 2026-03-29 by punishing audit. +____ + +=== Current State + +[width="100%",cols="50%,25%,25%",options="header",] +|=== +|Category |Count |Notes +|Unit tests |14 |bridge: classify(4), intelligence(2), lockfile(2), +reachability(4), registry(2) + +|Integration |1 |src/interface/ffi/test/build.zig + +|E2E |11 |tests/e2e_test.rs + +|Property |12 |tests/property_test.rs + +|Aspect |8 |tests/aspect_test.rs + +|Benchmarks |1 |benches/bridge_bench.rs +|=== + +*Source modules:* ~11 Rust source files in src/bridge/ + 3 Idris2 ABI + +1 Zig FFI. + +=== What’s Missing + +==== P2P (Property-Based) Tests + +* [ ] CVE classification: property tests for severity scoring +consistency +* [ ] Lockfile parsing: arbitrary lockfile format fuzzing (Cargo.lock, +package-lock.json, mix.lock, etc.) +* [ ] Reachability: property tests for call graph analysis correctness +* [ ] Registry: property tests for advisory lookup consistency + +==== E2E Tests + +* [ ] Full CVE lifecycle: detect -> classify -> assess reachability -> +recommend mitigation -> verify fix +* [ ] Multi-format: lockfile parsing across all supported package +managers +* [ ] Intelligence: advisory fetch -> parse -> match to dependencies +* [ ] Adoption gate: recommend patch -> apply -> verify -> close + +==== Aspect Tests + +* *Security:* A CVE mitigation tool needs security testing: false +negative detection (missed CVEs), advisory tampering, lockfile injection +— ZERO security tests +* *Performance:* No benchmarks for lockfile parsing speed, CVE database +lookup time, reachability analysis scaling +* *Concurrency:* No tests for parallel vulnerability assessment, +concurrent advisory fetches +* *Error handling:* No tests for malformed lockfiles, unreachable +registries, invalid CVE identifiers, network timeouts + +==== Build & Execution + +* [ ] `+cargo test+` +* [ ] Zig FFI test execution +* [ ] CLI smoke tests with real lockfiles + +==== Benchmarks Needed + +* [ ] Lockfile parsing time per format +* [ ] Reachability analysis time vs dependency graph size +* [ ] Advisory lookup latency +* [ ] Full assessment pipeline throughput + +==== Self-Tests + +* [ ] Assess its own Cargo.lock for vulnerabilities +* [ ] Registry connectivity health check +* [ ] Classification model consistency verification + +=== Priority + +*CRITICAL.* A CVE mitigation lifecycle tool with 14 inline unit tests +and ZERO E2E tests. The reachability and classification modules have the +most tests (good). But no integration testing means the pieces are never +validated together. A security tool that cannot test its own security +posture is self-refuting. No benchmarks for what should be a +performance-sensitive pipeline. + +=== FAKE-FUZZ ALERT + +* `+tests/fuzz/placeholder.txt+` is a scorecard placeholder inherited +from rsr-template-repo — it does NOT provide real fuzz testing +* Replace with an actual fuzz harness (see +rsr-template-repo/tests/fuzz/README.adoc) or remove the file +* Priority: P2 — creates false impression of fuzz coverage diff --git a/TEST-NEEDS.md b/TEST-NEEDS.md deleted file mode 100644 index 0599b26..0000000 --- a/TEST-NEEDS.md +++ /dev/null @@ -1,64 +0,0 @@ -# TEST-NEEDS.md — patch-bridge - -## CRG Grade: C — ACHIEVED 2026-04-04 - -> Generated 2026-03-29 by punishing audit. - -## Current State - -| Category | Count | Notes | -|-------------|-------|-------| -| Unit tests | 14 | bridge: classify(4), intelligence(2), lockfile(2), reachability(4), registry(2) | -| Integration | 1 | src/interface/ffi/test/build.zig | -| E2E | 11 | tests/e2e_test.rs | -| Property | 12 | tests/property_test.rs | -| Aspect | 8 | tests/aspect_test.rs | -| Benchmarks | 1 | benches/bridge_bench.rs | - -**Source modules:** ~11 Rust source files in src/bridge/ + 3 Idris2 ABI + 1 Zig FFI. - -## What's Missing - -### P2P (Property-Based) Tests -- [ ] CVE classification: property tests for severity scoring consistency -- [ ] Lockfile parsing: arbitrary lockfile format fuzzing (Cargo.lock, package-lock.json, mix.lock, etc.) -- [ ] Reachability: property tests for call graph analysis correctness -- [ ] Registry: property tests for advisory lookup consistency - -### E2E Tests -- [ ] Full CVE lifecycle: detect -> classify -> assess reachability -> recommend mitigation -> verify fix -- [ ] Multi-format: lockfile parsing across all supported package managers -- [ ] Intelligence: advisory fetch -> parse -> match to dependencies -- [ ] Adoption gate: recommend patch -> apply -> verify -> close - -### Aspect Tests -- **Security:** A CVE mitigation tool needs security testing: false negative detection (missed CVEs), advisory tampering, lockfile injection — ZERO security tests -- **Performance:** No benchmarks for lockfile parsing speed, CVE database lookup time, reachability analysis scaling -- **Concurrency:** No tests for parallel vulnerability assessment, concurrent advisory fetches -- **Error handling:** No tests for malformed lockfiles, unreachable registries, invalid CVE identifiers, network timeouts - -### Build & Execution -- [ ] `cargo test` -- [ ] Zig FFI test execution -- [ ] CLI smoke tests with real lockfiles - -### Benchmarks Needed -- [ ] Lockfile parsing time per format -- [ ] Reachability analysis time vs dependency graph size -- [ ] Advisory lookup latency -- [ ] Full assessment pipeline throughput - -### Self-Tests -- [ ] Assess its own Cargo.lock for vulnerabilities -- [ ] Registry connectivity health check -- [ ] Classification model consistency verification - -## Priority - -**CRITICAL.** A CVE mitigation lifecycle tool with 14 inline unit tests and ZERO E2E tests. The reachability and classification modules have the most tests (good). But no integration testing means the pieces are never validated together. A security tool that cannot test its own security posture is self-refuting. No benchmarks for what should be a performance-sensitive pipeline. - -## FAKE-FUZZ ALERT - -- `tests/fuzz/placeholder.txt` is a scorecard placeholder inherited from rsr-template-repo — it does NOT provide real fuzz testing -- Replace with an actual fuzz harness (see rsr-template-repo/tests/fuzz/README.adoc) or remove the file -- Priority: P2 — creates false impression of fuzz coverage diff --git a/TOPOLOGY.adoc b/TOPOLOGY.adoc new file mode 100644 index 0000000..7e6e049 --- /dev/null +++ b/TOPOLOGY.adoc @@ -0,0 +1,25 @@ +== Architecture Topology + +=== Component Overview + +[cols=",,",options="header",] +|=== +|Component |Language |Purpose +|\{\{COMPONENT}} |\{\{LANGUAGE}} |\{\{PURPOSE}} +|=== + +=== Data Flow + +.... +[Input] → [Processing] → [Output] +.... + +=== Integration Points + +* *Upstream*: \{\{UPSTREAM_DEPS}} +* *Downstream*: \{\{DOWNSTREAM_CONSUMERS}} + +=== Deployment + +* Container: Stapeln Six ecosystem +* CI/CD: GitHub Actions → Hypatia scan → Mirror diff --git a/TOPOLOGY.md b/TOPOLOGY.md deleted file mode 100644 index b2bf854..0000000 --- a/TOPOLOGY.md +++ /dev/null @@ -1,24 +0,0 @@ - -# Architecture Topology - -## Component Overview - -| Component | Language | Purpose | -|-----------|----------|---------| -| {{COMPONENT}} | {{LANGUAGE}} | {{PURPOSE}} | - -## Data Flow - -``` -[Input] → [Processing] → [Output] -``` - -## Integration Points - -- **Upstream**: {{UPSTREAM_DEPS}} -- **Downstream**: {{DOWNSTREAM_CONSUMERS}} - -## Deployment - -- Container: Stapeln Six ecosystem -- CI/CD: GitHub Actions → Hypatia scan → Mirror 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 7335a50..8597d8f 100644 --- a/docs/patch-bridge-design.md +++ b/docs/patch-bridge-design.adoc @@ -1,72 +1,86 @@ - - -# 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 - -**Audit note (2026-03-30)**: This document is aspirational. References below -to proofs, formal verification, lifecycle automation, and upstream integration -describe intended architecture unless separately evidenced by checked artefacts -in the repository. - ---- - -## 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 + +*Audit note (2026-03-30)*: This document is aspirational. References +below to proofs, formal verification, lifecycle automation, and upstream +integration describe intended architecture unless separately evidenced +by checked artefacts in the repository. + +''''' + +=== 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 @@ -75,20 +89,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) │ @@ -166,34 +180,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 + +|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 -## 3. Integration with Existing panic-attack Infrastructure +|VeriSimDB |`+src/storage/+` |Hexad persistence for mitigation registry -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. +|PanLL export |`+src/panll/+` |Event-chain model for panel visualisation -### 3.1 Existing infrastructure reused +|Assemblyline |`+src/assemblyline.rs+` |Batch CVE assessment across org +repos -| 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 | +|Notify |`+src/notify.rs+` |Alerts on unmitigable CVEs, upstream fix +availability +|=== -### 3.2 New modules +==== 3.2 New modules -``` +.... src/ ├── bridge/ # Patch Bridge core │ ├── mod.rs # Public API @@ -208,11 +242,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 @@ -222,52 +256,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) @@ -277,20 +301,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. @@ -303,27 +328,42 @@ pub struct ThreatTranslator { /// Known conceptual gaps for this ecosystem blind_spots: Vec, } -``` +---- + +*Translation examples:* -**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.`" -| 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." | +|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.`" +|=== -## 5. Contextual Risk Assessment +''''' -### 5.1 Reachability analysis (existing kanren taint engine) +=== 5. Contextual Risk Assessment -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: +==== 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: + +.... CVE vulnerability class → TaintSink mapping ─────────────────────────────────────────────── Command injection → ShellCommand, CodeExecution @@ -333,20 +373,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 @@ -375,12 +415,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") @@ -398,48 +439,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 @@ -476,21 +519,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) @@ -502,39 +545,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 -**Vulnerability class chains** (non-exhaustive): +|Input validation bypass |SQL injection |Data exfiltration -| 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 | +|Path traversal |File write |Arbitrary file overwrite -### 7.3 Cross-language concatenation +|Deserialization |Code execution |RCE -Using the existing `CrossLangAnalyzer`, Patch Bridge detects chains that -cross language boundaries: +|Race condition |Privilege escalation |Privilege escalation -``` +|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) ──────────┘ @@ -542,18 +594,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") @@ -575,11 +629,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 │ └─────────┘ └─────────┘ └──────────┘ └─────────┘ @@ -589,47 +643,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 @@ -662,37 +718,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 -| 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) | +[width="100%",cols="50%,50%",options="header",] +|=== +|Field |Value +|Panel ID |`+PanelPatchBridge+` -### 10.2 Four-file structure +|Name |"`Patch Bridge`" -``` +|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 @@ -702,11 +766,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 ──────────────────────────────────────────┐ │ @@ -784,17 +848,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... @@ -817,42 +881,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", @@ -861,16 +929,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) @@ -879,129 +947,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/llm-warmup-dev.adoc b/llm-warmup-dev.adoc new file mode 100644 index 0000000..53a88aa --- /dev/null +++ b/llm-warmup-dev.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — rsr-template-repo (Developer) + +=== What is rsr-template-repo? + +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 e616c99..0000000 --- a/llm-warmup-dev.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — rsr-template-repo (Developer) - -## What is rsr-template-repo? -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..c13529e --- /dev/null +++ b/llm-warmup-user.adoc @@ -0,0 +1,19 @@ +== LLM Warmup — rsr-template-repo (User) + +=== What is rsr-template-repo? + +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 18a327e..0000000 --- a/llm-warmup-user.md +++ /dev/null @@ -1,16 +0,0 @@ -# LLM Warmup — rsr-template-repo (User) - -## What is rsr-template-repo? -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