penthera 1.6.1 → 1.8.0-rc.1

package/CHANGELOG.md

@@ -4,6 +4,270 @@ All notable changes to Penthera are documented here. Versioning follows [SemVer]
 
 ## [Unreleased]
 
+## [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:
+it detects what is there, asks what to check, runs it offline and offers the
+hook, the PR workflow and the dashboard. `penthera ui` is a single view with
+side panels. The README is rewritten, and the methodology and references
+follow APA 7.
+
+### Added
+
+- **`penthera init`, the setup wizard** (also `npx penthera` with no arguments
+  in a terminal). It detects the project offline (git, framework, npm and
+  Python lockfiles, agent config, a dev server on localhost, an existing hook
+  or workflow), asks one checklist question, runs the code, dependency and AI
+  tooling checks (and the running app, only after you confirm it is yours),
+  then shows the grade per area, the three things to fix first and one report
+  folder, `reports/penthera-<date>/`. It then offers, one yes/no each, the
+  pre-commit hook, a `.github/workflows/penthera.yml` pinned to the release
+  commit SHA (shown as a diff first), `reports/` in `.gitignore`, the fix loop
+  and the dashboard. `--yes` takes the safe defaults and never scans a URL,
+  runs the fix loop or opens the dashboard; `--dry-run` prints the plan.
+  Nothing is committed or pushed. See [docs/commands/init.md](docs/commands/init.md).
+
+### Changed
+
+- **`penthera ui` is one view, like the Claude Code desktop app.** A
+  collapsible left sidebar lists projects (grade, open findings, last scan)
+  and recent runs grouped by project, with "+ New scan" on top and settings
+  behind a gear. The centre is one scrolling stream: the selected project's
+  header (grade, severity bar, trend sparkline), what changed since the last
+  scan, "Fix first" and the findings; a running scan or fix loop streams there
+  as a transcript with Apply / Skip / Stop inline on each diff. A prompt-style
+  bar starts scans, dependency checks, AI tooling audits and the fix loop. The
+  collapsible right panel stacks Environment (egress, folder, git branch),
+  Memory, Dependencies, AI tooling, Evidence and Changes cards, and shows a
+  finding's detail when you pick one. `[` and `]` toggle the side panels, which
+  become drawers at narrow widths. Calmer chrome, one primary action at a time;
+  the themes, `--demo` and every security property are unchanged. New
+  `GET /api/env` reads the branch through the agent's hardened git runner.
+- `penthera-scan` keeps the URL-first wizard that `penthera` used to open.
+
+### Docs
+
+- README rewritten in the voice of "Penthera: Cyber Security Agent". The
+  dashboard screenshots now sit directly under the demo GIF; "Get started" leads
+  with one command (`npx penthera`); features are grouped as before you deploy,
+  what you build with, and after you ship; and a new "Research and
+  methodology" section gives the method, the benchmark numbers, and how to cite
+  Penthera. About 12 KB, down from 19 KB.
+- `docs/references.md` is rendered in APA 7th edition style from
+  `docs/references.bib`, sorted by first author within each topic, with an
+  anchor per BibTeX key. Editors for the three Springer proceedings and the NDSS
+  proceedings titles were added from Crossref. A test covers the formatter.
+- `docs/METHODOLOGY.md` uses APA in-text citations, opens with an abstract and
+  a "How to cite" block that mirrors `CITATION.cff`, and now cites every
+  reference. A test fails if a citation does not resolve or a reference is
+  never cited, and the internal audit checks the "How to cite" version.
+
 ## [1.6.1] - 2026-10-19
 
 The GitHub Action gets its Marketplace name. Nothing else changes.
@@ -82,6 +346,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,