penthera 1.7.0 → 1.8.0

package/CHANGELOG.md

@@ -4,6 +4,289 @@ All notable changes to Penthera are documented here. Versioning follows [SemVer]
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-10-21
+
+1.8.0 is 1.8.0-rc.1 plus the changes below; there was no separate rc.2
+release. Highlights across both: fixes from a second independent security
+review, a fix loop that cannot edit the tests that judge it, the redesigned
+dashboard (Simple and Advanced mode), release checks on Linux, macOS and
+Windows, and now runtime advisories, starting with PHP's critical security
+release of 21 October 2026, in a new signed `advisories` rule pack (1.8.0-rc.1
+cannot load it). The benchmark gained two PHP cases: precision 0.88 (95% CI
+0.69 to 0.96) and recall 0.91 (0.73 to 0.98) on 24 scored findings.
+
+### Added
+
+- **Runtime advisories: is the PHP, Apache, nginx, Node.js, Python or OpenSSL
+  you run affected?** URL scans read `Server` and `X-Powered-By` banners, the
+  `PHPSESSID` cookie name and `.php` pages. Repo scans read Dockerfile and
+  compose images, `.tool-versions`, `.php-version`, `.nvmrc`,
+  `.python-version`, `runtime.txt` and `composer.json`. Each product and
+  version gets one answer: affected, end of life with no fix, check on server,
+  or has the fix (as advertised). A hidden version is never reported as safe.
+  A distribution build (`8.1.2-1ubuntu2.19`, or any version behind a `Server`
+  header that names a distribution) is never reported as affected, because
+  distributions backport fixes under the same version number. Advisories that
+  need more than a version (Windows, CGI) stay `potential`. See
+  [docs/runtime-advisories.md](docs/runtime-advisories.md).
+- **Two rule-pack kinds, `runtime-advisory` and `runtime-eol`**, so a new
+  advisory ships as a signed data pack (`--rules`) the same day, without a
+  release. End of life is judged by the pack's date, not the scan's clock.
+- **A bundled `advisories` pack** with the PHP security release of 21 October
+  2026 (CVE-2026-109618 and CVE-2026-109619, both Critical, CVSS 4.0 9.2,
+  fixed in 8.2.35, 8.3.36, 8.4.27 and 8.5.12, from the php-src advisories),
+  vendor-checked worked examples (CVE-2024-4577 and CVE-2024-8926 for PHP-CGI on Windows, CVE-2021-41773 and
+  CVE-2021-42013 for Apache HTTP Server 2.4.49 and 2.4.50) and end-of-life
+  release lines. Benchmark cases for both URL and repo scans.
+
+### Site
+
+- **A landing page in `site/`**, a static site for Vercel: the positioning,
+  `npx penthera`, prompts for Claude Code, Cursor and Codex, the hero loop and
+  the walkthrough, the limits and the research plan. No third-party scripts,
+  analytics or cookies; fonts are self-hosted or system fonts.
+- **A check in the browser.** Drop or paste a `package.json`, `.mcp.json`,
+  `.claude/settings.json`, `CLAUDE.md` or `AGENTS.md` and Penthera's own
+  `lib/` code runs in the tab: the agent-config rules, the secret patterns,
+  install scripts, typosquats against the vendored popular list, and the
+  bundled IOC pack. `site/build.mjs` bundles `lib/` at build time, so the site
+  and the CLI run the same rules; `tests/site.test.js` holds the page to the
+  CLI on the agents and deps fixtures. The page is served with
+  `connect-src 'none'`, so it cannot send the files anywhere.
+- **Runtime advisories in the browser check.** Drop a `Dockerfile`,
+  `compose.yaml`, `.php-version`, `.tool-versions` or `composer.json`, or
+  paste the response headers `curl -sI` printed for your site (the page never
+  contacts it), and `lib/advisories` runs on them: the same findings and
+  confidence as the CLI, with "check on the server: distributions backport
+  fixes" next to every version-only verdict. `tests/site.test.js` compares
+  pasted headers with a URL scan of a loopback server sending the same
+  headers, and runtime pins with `runtimeAdvisoriesForRepo`.
+- `penthera deps` findings are built in `lib/deps/findings.js` (moved from
+  `lib/deps/index.js`, no behaviour change), so the browser check uses the
+  same wording.
+- `scripts/docs-commands.mjs` also checks every command the site shows.
+
+### Docs
+
+- **New title for the launch:** "Penthera: your open-source cyber security
+  agent", in the README, docs index, `penthera --help`, the GitHub Action name
+  (which renames its Marketplace listing), the dashboard and the report
+  footer.
+
+- **README hero is a 12-second loop** of the terminal and the dashboard
+  (setup, an offline scan, Simple and Advanced mode, a fix approved), cut from
+  the walkthrough video by `scripts/media/hero-gif.sh`, and it loops without a
+  jump. The terminal-only scan clip is now `assets/demo-scan.gif`. The Demo
+  media workflow re-cuts the loop on every release.
+- **The README diagram is back**, updated: what Penthera checks, where the
+  findings go, and that the fix loop asks first and cannot edit its own tests.
+
+## [1.8.0-rc.1] - 2026-10-20
+
+Release candidate for 1.8.0, published on npm's `next` dist-tag
+(`npm install penthera@next`). It becomes 1.8.0 on `latest` after it has run
+on real projects without a blocking issue.
+
+### Security
+
+Fixes from a second independent review. Most also apply to 1.7.0; upgrading
+is recommended.
+
+- **Dependency scans fail closed.** An npm or Python package that could not be
+  read in full (a code file over 64 MB, more files than the reader takes, an
+  archive with inconsistent sizes or other structural anomalies, a matched
+  artifact that cannot be opened) is now `unscanned`: a high "could not be
+  scanned" finding that `penthera install` always holds for approval. The
+  Python scanner gained this state. Wheels are capped on the bytes actually
+  inflated. Pax global headers that set a size or path are refused. Deeply
+  nested `uv.lock`/`poetry.lock` files are a parse error, not a crash.
+- **The fix loop and `fix --apply` run git hardened.** Commit and tag signing,
+  signing programs, attribute files and every configured filter driver are
+  overridden on every call (`--attr-source` on git 2.40+). Pathspecs are
+  literal. Writes are refused when the repository's own config sets
+  `filter.*`, `gpg.*` or `include.*`, or on git older than 2.31; the loop then
+  does not start, and its one message names the key and how to go on.
+- **The fix loop keeps your uncommitted work.** Dirty files are read with
+  `status -z` and re-checked right before every write and commit. Reverts
+  restore the exact bytes from before the fix, and only while the file still
+  holds what penthera wrote (otherwise the fix is a `conflict` and the file is
+  left alone). Commits use `--only`. Plans that touch untracked or ignored
+  files are skipped, and every revert step runs even when one fails.
+- **`applyDiff` is all-or-nothing and writes only regular files in the repo.**
+  Duplicate and nested paths are refused, a failed apply puts back what it
+  wrote, files are replaced through a temp file (never written through a hard
+  link), NTFS stream names and 8.3 aliases are refused, and added lines may not
+  contain control characters. Approval prompts show control characters as
+  escapes.
+- **The pre-commit hook checks everything it should.** Staged content is read
+  by object id from NUL-separated output, type changes are included, files
+  with NUL bytes are scanned, and a staged file over 16 MB blocks the commit
+  (or warns, with `"largeFiles": "warn"`). `hook install` no longer writes
+  through a symlinked `pre-commit`.
+- **Secret scanning checks every match.** A placeholder no longer hides a real
+  secret of the same rule later in the file. Only regular files are read, with
+  a per-file size cap.
+- **Dashboard sessions are bound to the page.** The one-time token travels in
+  the URL fragment and is exchanged for a per-tab session sent as an
+  `Authorization` header; no cookie is set or accepted. Approvals carry the
+  sha256 of the diff shown, and a cut diff says so and needs an explicit
+  acknowledgement. A symlinked default `reports/` is refused and every write
+  re-checks the folder. Event ids keep counting past the buffer; requests,
+  bodies (413), finished runs and open streams are bounded. `--open` no
+  longer puts the token on a command line.
+- **Evidence bundles** are built in a private folder and renamed into place,
+  and verification never follows a symlinked folder and caps what it reads.
+- **HTTP responses are bounded.** Every body is read with a size cap (counted
+  after decompression) and a deadline that covers the body, not just the
+  headers. `--offline` compares host and port, and cross-origin redirects drop
+  credentials and do not replay request bodies.
+- **Linear-time matching on untrusted text.** Agent-config exec patterns and
+  other agent and hook checks no longer backtrack on long input. The rule-pack
+  regex guard refuses ambiguous alternation and optional items inside repeated
+  groups and end-anchored rescans; community templates use the same guard.
+- **Hostile repos no longer hang or crash scans**: a FIFO is never read, and
+  deeply nested JSON is handled; one unreadable agent config becomes a finding
+  instead of aborting the run.
+- `--fix-model` never sends a file from outside the repo as context.
+- Installing the hook through pre-commit.com no longer runs the test suite:
+  the `prepack` script is gone (publishing still runs `npm test`).
+- Workflows that push or only read no longer keep credentials in the checkout.
+- **The fix loop cannot game its own checker.** A fix diff, from a local
+  model or a recipe, may not edit tests, test runner config or the test
+  script, Penthera's policy, suppressions, baseline, lock or memory, CI
+  workflows, git hooks or lockfiles; `applyDiff` refuses it with `PROTECTED`
+  and says to make that change by hand. The loop verifies only against the
+  checker the run began with. "Could not fix" is now a recorded outcome
+  (`gave_up` in memory, `loopRun.gaveUp`, a summary line): the finding is not
+  retried in that run, and a give-up never counts against a recipe. Older
+  Penthera versions report a memory chain with `gave_up` events as malformed.
+
+### Added
+
+- Release checks in CI (`.github/workflows/install-matrix.yml`): the packed
+  tarball is installed into an empty project and run with `npx penthera` on
+  Linux, macOS and Windows with Node 22 and 24 (setup wizard dry run, deps,
+  agents, repo scan, the pre-commit hook on a real commit, the dashboard's
+  token check, bundled rule pack signatures). An upgrade job installs 1.7.0
+  from npm, writes memory and dashboard state, upgrades to the tarball and
+  checks the old memory chain still verifies and grows. All of it runs under a
+  network guard that fails on anything past loopback.
+- Docs as tests: `scripts/docs-commands.mjs` checks every command in the
+  README, `docs/` and the skill against `--help` and runs the offline ones on a
+  fixture, in `npm test` and against the installed package.
+- Provenance check in CI (`scripts/ci/provenance.mjs`): every commit in a pull
+  request that names an AI co-author must carry an `AI-Assisted` line, and the
+  other way round.
+
+### Fixed
+
+- Windows: `npx penthera` / `penthera init` in a git repository failed with
+  "Refusing to write outside the project" for its own `reports/` folder, because
+  git prints the repo root with forward slashes. Git roots are now native paths.
+  Found by the new Windows install checks.
+- `penthera --help` lists `--rules-signers` and `--allow-unsigned-rules`. Both
+  worked and were documented in `docs/rule-packs.md`, but the help left them
+  out.
+- `penthera ui`, Advanced mode: a run's transcript no longer shows a stray
+  "null" under its title.
+
+### Changed
+
+- **`penthera ui` redesigned for people who are not programmers.** A first
+  visit runs a three-screen setup (what Penthera does, Simple or Advanced, the
+  project and a first check). Simple mode, the default, leads every project
+  with a one-sentence verdict ("Not ready to ship: 1 critical problem to fix
+  first."), lists problems in plain words, explains each one as what is wrong,
+  how sure and what to do, and tells a run as one sentence. Advanced keeps
+  everything, now as project tabs (Findings, Dependencies, AI tooling, History,
+  Proof) with a severity by confidence triage matrix. A menu bar replaces the
+  prompt bar and carries every action with its shortcut and the run status;
+  runs start from a New scan window; every change waits in its own window
+  (`y`, `n`, `q`). New look: a 1-bit "System" register of tiled windows, dither
+  patterns instead of greys, `#0000ed` as the one accent, Departure Mono (OFL,
+  self-hosted) for chrome, the serif Penthera wordmark, and a halftone field
+  whose density is the open risk. Both themes pass WCAG AA in every state.
+  `scripts/dashboard-screenshots.mjs` regenerates the docs screenshots.
+- Smaller npm package: 797 kB to 657 kB packed, 2.3 MB to 1.7 MB unpacked. The
+  package ships only `docs/examples/` (the documentation lives on GitHub, and
+  README links resolve there), and the popular-package lists for the typosquat
+  check are stored gzipped. No behaviour change.
+- Code cleanup, no behaviour change: one git runner (`lib/git.js`), one
+  temp-folder helper, one Markdown table-cell escape and one JSON fetch
+  helper replace their copies; unused exports and helpers are gone. CI now
+  runs `npm run lint` (ESLint, dev-only, minimal rules). Still one runtime
+  dependency.
+
+### Docs
+
+- **Penthera is described as an open R&D project with a usable tool:** "an
+  open-source cyber security agent you can use today, and verify yourself."
+  The README, `docs/index.md`, `package.json`, the plugin and marketplace
+  manifests, the Agent Skill (trigger phrases kept), the GitHub Action and the
+  repository description carry the approved wording. The README has a "How it
+  is measured" section (method, evidence, tool) with Wilson intervals next to
+  the benchmark numbers, and stays under 14 KB.
+- **One roadmap, one research plan.** `ROADMAP.md` now says what ships next,
+  starting with the 1.8.0 feature freeze. `docs/vision-2.0.md` is the research
+  plan and holds the quality gates from `docs/plan.md`. `docs/plan.md`,
+  `docs/release-plan.md` (v1.2 to v1.4) and the Socket positioning notes moved
+  to `docs/archive/`.
+- **Every user-facing page names the question it answers**, for a starter ("is
+  my app safe to ship?") or a pro ("how do I put it in CI?"), and
+  `docs/index.md` has a Start here path from starter to pro.
+- **Voice guide** (`docs/voice.md`): plain words, short sentences, numbers with
+  intervals over adjectives, limits next to claims, no hype. Every user-facing
+  page was edited against it.
+- **Release cadence** in CONTRIBUTING: at most one minor release every 2 to 4
+  weeks, always through an `-rc.N` on npm's `next` tag, patches for fixes only,
+  and a feature freeze before each minor. Current freeze: 1.8.0 = main + #63.
+- Fixed stale facts: SECURITY.md's supported versions (1.2.x to 1.7.x), README
+  anchors that no longer existed, Agent Skill links into `docs/` that broke in
+  the npm package since the docs stopped shipping there, and the partner brief
+  and due diligence notes that still called shipped features "in review".
+- Limitations stated in full: the methodology's "Known limitations" now covers
+  every module (deps, AI tooling, fix loop), the evidence (small sample, wide
+  intervals, same-team benchmark, single labeller, uncalibrated confidence
+  labels), reproducibility, AI-assisted development, and compliance output. The
+  2.0 research program adds "Threats to validity".
+- GenAI disclosure: `docs/genai.md` states how Penthera is built with
+  generative AI (models, scale, review gates, licensing, logs), the README has a
+  short "How Penthera is built" section (107 of 117 non-merge commits up to
+  v1.7.0 written with Claude), and CONTRIBUTING requires an
+  `AI-Assisted` trailer on AI-assisted commits. Follows NLnet's generative AI
+  policy.
+- `docs/MANIFESTO.md`: what Penthera is today (and is not), seven design
+  decisions with their costs and what would change them, and an FAQ. Written to
+  be challenged in Discussions.
+- **After the 2026 agent incidents:** `docs/research/agent-incidents-2026.md`
+  says what the OpenAI–Hugging Face and Anthropic evaluation incidents mean
+  for Penthera, with sources and caveats. `docs/agents-safely.md` is a
+  one-page checklist for running AI agents. `docs/research/spec-harness-rules.md`
+  specifies planned `harness-*`, `sandbox-*` and `scorer-*` rules (not built
+  yet), and the research plan adds E7 and a draft pre-registration for E8
+  (do harness guardrails reduce judge tampering?).
+- README: a "Building in public" section linking the CHANGELOG, the freeze, the
+  research in progress and the roadmap. Counts refreshed (57 references);
+  `npm run docs:numbers` now also counts the secret patterns in the core rule
+  pack (20, as the README says, not 8).
+- `docs/genai.md` covers commits since v1.7.0 and how the agents that build
+  Penthera are contained; the manifesto says the fix loop cannot edit what
+  judges it.
+- `docs/vision-2.0.md`: the plan for 2.0, covering the biggest gaps, an AI roadmap
+  (models propose, deterministic checks decide; local models first) and a
+  pre-registered research program with sample sizes and safety rules.
+- **An 80-second walkthrough video** (`assets/walkthrough.mp4`, with a poster
+  and `walkthrough.vtt` captions) shows `npx penthera`, an offline scan of the
+  mock server, `penthera ui --demo` in Simple and Advanced mode, one fix
+  approved and the owner report. It is linked from the README and
+  `docs/index.md`. `scripts/media/walkthrough.mjs` renders it from demo data
+  only, and the Demo media workflow re-renders it on every release.
+- **The terminal GIFs are re-rendered** in the dashboard's black and white
+  look. `scan.tape` now writes the README hero (`assets/demo.gif`) directly
+  and scans with `--offline`. The `agents` and `deps --diff` tapes rendered a
+  "Cannot find module" error, because they ran `bin/penthera.js` by a
+  relative path after changing folder; they use an absolute path now.
+
 ## [1.7.0] - 2026-10-19
 
 One view and one command. `npx penthera` now sets Penthera up in a project:
@@ -140,6 +423,38 @@ reproduced; each fix has a regression test that fails without it.
 
 ### Added
 
+- **Signed rule packs** (`lib/rules/`, [docs/rule-packs.md](docs/rule-packs.md)):
+  detection data (secret formats, hidden-instruction and exec patterns, IOC
+  lists, typosquat targets, Nuclei-compatible templates) ships as versioned
+  directories. Each pack has a `pack.json` index of SHA-256 hashes, signed
+  with `ssh-keygen -Y sign -n penthera-rules`. Penthera verifies the signature
+  (in Node; ssh-keygen is not needed at run time), then every hash, the schema
+  and every regex, before it loads anything. Packs arrive bundled in a release,
+  or by path with `--rules <dir>` (plus `--rules-signers <file>` for your own
+  keys). Unsigned packs are refused unless `--allow-unsigned-rules`, which
+  warns loudly. Nothing is ever fetched
+- `penthera rules list` and `penthera rules verify <dir>`; tooling in
+  `scripts/rules/` (`build-pack.mjs`, maintainer-only `sign-pack.sh`,
+  `check-bundled.mjs`). The publish workflow now refuses to stage a release
+  whose bundled packs are not signed by a key in `lib/rules/allowed_signers`
+- ReDoS guard for data-supplied regexes (`lib/rules/regex-guard.js`): length
+  cap, no backreferences or lookaround, no nested quantifiers, no alternation
+  under unbounded repeats, no unbounded quantifier that every start position
+  can rescan, and a backtracking budget for overlapping quantifier chains.
+  Fuzz-tested: everything it accepts runs in milliseconds on adversarial
+  input. The v1.1.1 template guard moved here too, rewritten from a regex
+  (itself polynomial on hostile pattern strings, flagged by CodeQL) into a
+  linear scan that also catches deeper nesting
+- Bundled `core` pack: 12 AI-provider key formats, the credential-path
+  instruction pattern, two exec patterns and the `.env` template moved out of
+  code. Behaviour is identical; a test compares against a snapshot of the old
+  built-ins
+- Bundled `ioc-2025-2026` pack (**unsigned in this PR; the maintainer signs it
+  before release**): s1ngularity/nx versions (GHSA-cxm3-wv7p-598c), Shai-Hulud
+  (StepSecurity's list, exfil URL, `bundle.js` by hash), Shai-Hulud 2.0 (Wiz
+  Research's CSV, loader file names) and postmark-mcp 1.0.16 to 1.0.18 with its
+  exfil domain. `penthera deps` reports hits as critical `deps-ioc` findings
+  that cite the source, wherever the package sits in the tree, installed or not
 - **Internal testing audit** (`npm run audit:internal`), the release gate:
   tests, benchmark drift, a self-scan against `audit/baseline.json`, a CLI
   smoke matrix, package contents and size, zero third-party egress offline,

package/README.md

@@ -1,10 +1,12 @@
 <div align="center">
 
-<img src="assets/penthera-social.jpg" alt="Penthera: Cyber Security Agent" width="840">
+<img src="assets/penthera-social.jpg" alt="Penthera: your open-source cyber security agent" width="840">
 
 <br/><br/>
 
-**Penthera: Cyber Security Agent. Open-source security for the apps and AI systems you ship.**
+**Penthera: your open-source cyber security agent**
+
+The security review you never had time for. Offline, rule-based, and you can verify every finding yourself.
 
 <br/>
 
@@ -16,27 +18,37 @@
 
 <br/>
 
-<img src="assets/demo.gif" alt="Penthera running an interactive security scan in the terminal" width="760">
+<img src="assets/demo.gif" alt="A 12-second loop: npx penthera sets up a project, an offline scan runs in the terminal, the dashboard shows the verdict in Simple mode and the triage matrix in Advanced mode, and a fix is approved" width="760">
 
 <br/><br/>
 
-| `penthera ui`, dark | `penthera ui`, light |
+| `penthera ui`, Simple, dark | `penthera ui`, Advanced, light |
 |---|---|
-| ![The dashboard in the dark theme: projects, findings, and a finding's detail](assets/dashboard/ui-dark.jpg) | ![The dashboard in the light theme: all projects and the side cards](assets/dashboard/ui-light.jpg) |
+| ![The dashboard in Simple mode, dark: the verdict, problems in plain words and one problem open](assets/dashboard/ui-dark.jpg) | ![The dashboard in Advanced mode, light: a project's tabs, the triage matrix and a finding open](assets/dashboard/ui-light.jpg) |
+
+<a href="assets/walkthrough.mp4"><img src="assets/walkthrough-poster.jpg" alt="Walkthrough video: setup, a scan, the dashboard in Simple and Advanced mode, one fix approved, the report" width="760"></a>
+
+[Watch the 80-second walkthrough](assets/walkthrough.mp4): setup, a scan, the dashboard, a fix approved, the report. Demo data, no sound, captions in the video.
 
 </div>
 
 ---
 
-## The problem
+## What Penthera is
+
+Teams ship apps and AI agents faster than anyone can check them, and most
+security scanners offer no evidence of how well they actually work. Penthera is
+an open-source R&D project that tackles both.
+
+**Use it today.** A cyber security agent for your coding tools that runs
+offline on your own machine: it checks your app, its dependencies and your AI
+tooling, and fixes what it can with your approval, through a dashboard that
+works for first-timers and pros alike.
 
-Teams now ship apps and AI agents faster than anyone can secure them. AI writes
-much of the code and pulls in the packages, MCP servers, and skills, and on most
-teams nobody works on security full time. Attackers have adapted: 2025 and 2026
-brought self-spreading npm worms that hijacked AI coding tools, malicious MCP
-servers, poisoned agent skills, and leaked AI provider keys. Penthera does the
-repeatable security work on your own machine, with rules you can read, so the
-people you have can spend their time on judgement.
+**Trust it because it's measured.** Every check is tested in public,
+pre-registered experiments, and the results are published, good or bad. What
+holds up ships in the next release, so Penthera keeps pace with new attacks and
+with EU rules such as NIS2 and the Cyber Resilience Act.
 
 ## Get started
 
@@ -79,6 +91,29 @@ Penthera needs Node.js 22 or later. To run it in a container:
 
 ## What it does
 
+```mermaid
+flowchart LR
+    U["You or your AI agent"] --> P(("Penthera<br/>on your machine"))
+
+    P --> APP["Your app<br/>URL scan, repo scan"]
+    P --> DEP["Your dependencies<br/>capabilities, install firewall<br/>typosquats, upgrade diff"]
+    P --> AI["Your AI tooling<br/>skills, MCP, hooks<br/>plugins, rule files"]
+
+    APP --> F[["Findings<br/>severity, confidence<br/>evidence at file:line"]]
+    DEP --> F
+    AI --> F
+
+    F --> FIX["Fix loop<br/>asks first, local branch<br/>cannot edit its own tests"]
+    FIX -. "re-scan proves it" .-> F
+    F --> R["Reports and dashboard<br/>terminal, Markdown, SARIF<br/>penthera ui"]
+    F --> E["Evidence<br/>signed bundle<br/>NIS2 and CRA drafts"]
+
+    classDef core fill:#0000ed,stroke:#0000ed,color:#ffffff
+    classDef box fill:#ffffff,stroke:#000000,color:#000000
+    class P core
+    class U,APP,DEP,AI,F,FIX,R,E box
+```
+
 ### Before you deploy
 
 | Job | What Penthera does | Command |
@@ -101,7 +136,7 @@ Penthera needs Node.js 22 or later. To run it in a container:
 | Job | What Penthera does | Command |
 |---|---|---|
 | Report and prove | Writes reports for developers, owners, and auditors; a hashed, signable evidence bundle; NIS2 and CRA readiness reports and drafts | [`penthera <url> --audience auditor --evidence out/`](docs/evidence.md) |
-| See it all | A local dashboard on 127.0.0.1: one view with your projects, findings in plain words, history, side panels for dependencies, AI tooling and evidence, and the fix loop with Apply, Skip, and Stop per diff | [`penthera ui`](docs/dashboard.md) |
+| See it all | A local dashboard on 127.0.0.1 with a Simple mode for non-programmers: a one-sentence verdict, problems in plain words, a guided setup, and the fix loop with Apply, Skip, and Stop per change. Advanced adds dependencies, AI tooling, history and evidence | [`penthera ui`](docs/dashboard.md) |
 | Keep watching | Scheduled checks of your production for drift: certificates, headers, new endpoints, keys in bundles, new CVEs in your SBOM | on the [roadmap](ROADMAP.md) |
 
 Every finding carries a severity, a confidence label (`confirmed`, `likely`,
@@ -110,60 +145,69 @@ Reports come out as Markdown, JSON, and SARIF for GitHub code scanning. Exit
 code `1` means critical or high findings. Every command and flag is in
 [docs/commands/](docs/commands/README.md).
 
-Penthera is not a human pentester, a 24/7 SOC, or incident response. It does
-the checks that can be automated reliably and says plainly which ones need a
-person.
+## How it is measured
+
+Each feature goes through the same path: **method → evidence → tool.**
+
+- **Method.** The [methodology](docs/METHODOLOGY.md) states the threat model,
+  what black-box (HTTP) and white-box (source) analysis can and cannot see, the
+  confidence model, and the false-positive controls on each probe. Each design
+  choice cites the research or standard it rests on: 92 verified references, in
+  APA style, in [docs/references.md](docs/references.md).
+- **Evidence.** A benchmark runs on every release, and the release gate fails
+  if precision or recall drops by more than 0.02. Experiments that decide what
+  ships next are pre-registered in [docs/research/prereg/](docs/research/prereg/)
+  before any data is collected, and the results are published either way.
+- **Tool.** What holds up ships in a reviewed, signed release. What does not
+  hold up is dropped, and the rules stay.
+
+| Measure | Result today |
+|---|---|
+| Precision on the bundled benchmark | 0.88, 95% CI 0.69 to 0.96 (21 true positives, 3 false positives) |
+| Recall on the bundled benchmark | 0.91, 95% CI 0.73 to 0.98 (2 misses, [each one explained](bench/RESULTS.md)) |
+| Requests to non-loopback hosts during the benchmark | 0 |
+| Detection rules, all readable | 14 URL scan templates, 20 secret and AI-key patterns, 15 dependency capabilities, 39 AI-tooling rules, 5 fix recipes |
+
+These numbers come from 24 findings in small labs that we wrote ourselves, so
+they catch regressions; they do not measure real-world accuracy. Measuring that
+on real projects is experiment E1, the first step of the
+[research plan](docs/vision-2.0.md). Intervals are Wilson. What Penthera cannot
+see is listed under [Known limitations](docs/METHODOLOGY.md#known-limitations).
+Counts as of 2026-10-21; refresh them with `npm run docs:numbers` and
+`npm run bench`.
+
+**Cite this repository** with the button on GitHub or
+[CITATION.cff](CITATION.cff). APA and BibTeX forms are in the
+[methodology](docs/METHODOLOGY.md#how-to-cite).
 
 ## Why you can trust it
 
 - **Local and offline.** No account, no telemetry, no cloud. `--offline` limits
   network traffic to the target you named, and every report lists the hosts it
-  contacted.
-- **Deterministic.** Rules you can read, with `file:line` evidence. No model
-  decides what is malicious.
+  contacted ([network use](docs/privacy.md)).
+- **Deterministic.** Rules you can read, with `file:line` evidence. A local
+  model may propose a fix; a deterministic re-scan and your tests decide.
 - **Non-destructive by default.** The default scan sends only requests a
   browser would send. Payload testing (`--deep`, `--fuzz`, `--all`) is opt-in
   and asks for confirmation.
-- **Never acts behind your back.** The fix loop works on a local branch, asks
-  before every change by default, and never pushes or opens pull requests.
+- **Asks before it changes anything.** The fix loop works on a local branch,
+  asks before every change by default, and never pushes or opens pull requests.
 - **No update channel to hijack.** Detection rules ship inside reviewed
-  releases. Nothing is downloaded and executed at run time.
+  releases as signed, versioned [rule packs](docs/rule-packs.md). You can add
+  your own by path (`--rules <dir>`). Nothing is downloaded and run at run time.
 - **Releases you can verify.** npm provenance through trusted publishing, a
   maintainer approval with 2FA for every version, SHA-pinned CI, CodeQL, and
   OpenSSF Scorecard. Every release passes an
   [internal audit](docs/internal-audit.md) of eight gates
   ([latest report](audit/REPORT.md)).
 
-## Research and methodology
-
-Penthera's method is written down and tied to the literature. The
-[methodology](docs/METHODOLOGY.md) states the threat model, separates what
-black-box (HTTP) and white-box (source) analysis can and cannot observe, and
-defines a confidence model that keeps heuristics from posing as facts. Each
-probe has explicit false-positive controls, such as randomized canaries and
-repeated timing measurement, and each design choice cites the research or
-standard it rests on: 49 verified references, listed in APA style in
-[docs/references.md](docs/references.md).
-
-| Measure | Result |
-|---|---|
-| Precision on the bundled benchmark | 0.86 (19 true positives, 3 false positives) |
-| Recall on the bundled benchmark | 0.90 (2 misses, [each one explained](bench/RESULTS.md)) |
-| Requests to non-loopback hosts during the benchmark | 0 |
-| Detection rules, all readable | 14 URL scan templates, 20 secret and AI-key patterns, 15 dependency capabilities, 39 AI-tooling rules, 5 fix recipes |
-
-The benchmark targets are small and were written by the same people as the
-scanner, so the numbers catch regressions rather than measure real-world
-accuracy ([limits](bench/RESULTS.md#limits-of-these-numbers)). Counts as of
-2026-10-19; refresh them with `npm run docs:numbers` and `npm run bench`.
-
-**Cite this repository.** Use the button on GitHub, or the metadata in
-[CITATION.cff](CITATION.cff). The APA and BibTeX forms are in the
-[methodology](docs/METHODOLOGY.md#how-to-cite).
+Penthera finds known classes of problems, not novel ones, and it does not
+replace a human pentester or incident response. The decisions behind it, its
+limits, and how to challenge them are in the [manifesto and FAQ](docs/MANIFESTO.md).
 
 ## How it fits with other tools
 
-Penthera works next to the tools you already use. Its SARIF output goes
+Penthera works next to the tools you already use; its SARIF output goes
 straight into GitHub code scanning, for example. Each comparison page says where
 the other tool goes further and how to run the two together.
 
@@ -176,29 +220,19 @@ the other tool goes further and how to run the two together.
 | [OWASP ZAP](docs/compare/zap.md) | Dynamic testing of web apps | Your machine or CI | Active and passive scan rules |
 | [Semgrep](docs/compare/semgrep.md) | Static analysis of your own code | Your machine, CI, cloud platform | Pattern rules, plus a paid cross-file engine |
 
-All comparisons: [docs/compare/](docs/compare/README.md). Corrections are
-welcome by pull request.
-
-## Use cases
+## Start here
 
-| You are | Start here |
+| You want to know | Read |
 |---|---|
-| A solo founder or vibecoder about to launch | [Before launch](docs/use-cases/solo-founder.md) |
-| A team adopting Claude Code or Cursor | [The AI-tooling supply chain](docs/use-cases/ai-coding-teams.md) |
-| An open-source maintainer | [For maintainers](docs/use-cases/open-source-maintainers.md) |
-| An EU SME with NIS2 or CRA duties | [Evidence for NIS2 and the CRA](docs/use-cases/eu-sme-compliance.md) ([NIS2 guide](docs/compliance-nis2.md), [CRA guide](docs/compliance-cra.md)) |
-| An agency shipping client apps | [A repeatable handover check](docs/use-cases/agencies.md) |
+| Is my app safe to ship? | [Before launch](docs/use-cases/solo-founder.md), then [scan](docs/commands/scan.md) |
+| Is this package or MCP server safe? | [deps](docs/commands/deps.md), [install](docs/commands/install.md), [agents](docs/commands/agents.md) |
+| How do I put it in CI? | [The GitHub Action](docs/commands/action.md), [scan in CI](docs/commands/scan.md#ci-integration) |
+| What do I give my auditor? | [Evidence bundles](docs/evidence.md), [NIS2](docs/compliance-nis2.md), [CRA](docs/compliance-cra.md) |
+| How do I run the fix loop? | [Fix and verify](docs/commands/fix.md), [the local loop](docs/local-loop.md) |
 
-Compliance output is readiness tooling. It is not a certification and not
-legal advice.
-
-## Privacy
-
-Penthera has no telemetry and does not phone home. Scan traffic goes to the
-target you name, reports stay on your machine, and every scan lists any
-third-party host it contacted. With `--offline`, the HTTP client refuses every
-host except the target. Which hosts a normal scan may contact, and why, is in
-[docs/privacy.md](docs/privacy.md).
+The full map, by situation and from first scan to pro use, is in
+[docs/index.md](docs/index.md). Compliance output is readiness tooling. It is
+not a certification and not legal advice.
 
 ## Ethics and authorization
 
@@ -210,17 +244,46 @@ or harm anyone. Unauthorized testing may break computer-misuse laws such as the
 US CFAA, the UK Computer Misuse Act, and their EU equivalents. When in doubt, do
 not scan.
 
-The software is provided "as is", without warranty, for defensive testing of
-systems you own or are authorized to test. The author accepts no liability for
-misuse, and you are responsible for making sure every scan you run is lawful.
+The software is provided "as is", without warranty. The author accepts no
+liability for misuse, and you are responsible for making sure every scan you
+run is lawful.
+
+## How Penthera is built
+
+Penthera is developed with substantial help from generative AI: 91% of the
+commits up to v1.7.0 were written with Claude (Anthropic) through Claude Code,
+directed and reviewed by the maintainer, and marked with a co-author trailer.
+Generated code passes the same gates as any change: tests, CodeQL, an
+independent review, the internal audit, and a 2FA-approved release. Inside the
+product, models only ever propose; deterministic checks decide. The full
+disclosure, and the rules for AI-assisted contributions, are in
+[docs/genai.md](docs/genai.md).
+
+## Building in public
+
+What changed, what we are measuring, and what comes next, in one place.
+
+| | Where it stands | Read more |
+|---|---|---|
+| **Latest release** | 1.8.0 (2026-10-21): runtime advisories starting with PHP's critical release, fixes from a second security review, a fix loop that cannot edit its own tests, the redesigned dashboard | [CHANGELOG](CHANGELOG.md) |
+| **On main, unreleased** | Whatever lands after 1.8.0 | [Unreleased](CHANGELOG.md#unreleased) |
+| **Now** | Toward 1.9: accuracy on real code (E1) and an MCP server, so coding agents can call Penthera | [Roadmap](ROADMAP.md#next) |
+| **Research** | E1, accuracy on real code, is pre-registered; the benchmark tooling is in review. After the 2026 agent incidents: a checklist for running agents safely and a draft experiment (E8) | [E1 pre-registration](docs/research/prereg/E1-real-world-accuracy.md), [agents safely](docs/agents-safely.md), [what the incidents mean](docs/research/agent-incidents-2026.md) |
+| **Next** | Real-world precision and recall with intervals, published whatever the result | [Roadmap: next](ROADMAP.md#next), [research plan](docs/vision-2.0.md) |
+
+Releases are deliberately slow: a feature freeze, an independent review, the
+release checks, and a release candidate before any new minor version. To
+follow along, watch the repository for releases or join the
+[Discussions](https://github.com/danoszz/penthera/discussions).
 
 ## Contributing and support
 
 Clone the repository and run `npm install`, then `npm test` for the suite and
 `npm run bench` for precision and recall.
-[CONTRIBUTING.md](CONTRIBUTING.md) covers the project layout and the release
-checklist, and the [roadmap](ROADMAP.md) shows what is next. Issues and pull
-requests are welcome.
+[CONTRIBUTING.md](CONTRIBUTING.md) covers the project layout, the release
+cadence and the release checklist. The [roadmap](ROADMAP.md) shows what ships
+next, and the [research plan](docs/vision-2.0.md) what we measure. Issues and
+pull requests are welcome.
 
 Penthera is free. If it caught something before you shipped it, you can
 [sponsor its maintenance](https://github.com/sponsors/danoszz). Sponsorship pays