penthera 1.2.0 → 1.5.0

package/CHANGELOG.md

@@ -4,6 +4,275 @@ All notable changes to Penthera are documented here. Versioning follows [SemVer]
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-10-19
+
+Blocks problems at commit time, adds license policy, and extends the EU
+evidence to the Cyber Resilience Act. The GitHub Action is now ready for the
+Marketplace as "Penthera Security Review". Penthera also has a clearer
+problem statement: open-source security for the apps and AI systems you ship.
+
+### Docs
+
+- Problem statement: "open-source security for the apps and AI systems you
+  ship", organised around three moments (before you deploy, what you build
+  with, after you ship). README, package, plugin, skill and repository
+  descriptions updated. Roadmap gains v1.6.0 "Before you deploy" (preview
+  deployment scanning, `penthera ship`) and v1.7.0 "After you ship"
+  (`penthera watch`). New `docs/plan.md` sets measurable quality gates to v2.0.
+
+### Added
+
+- **`penthera hook install|uninstall|run`**: a pre-commit hook that checks
+  staged content only (the git index): secrets and AI provider keys, the
+  `penthera agents` rules on staged `.mcp.json`, `CLAUDE.md`, `AGENTS.md`,
+  `.cursor/`, `.claude/` and `skills/`, and, when `package-lock.json` is staged,
+  the capability diff against HEAD plus the license policy for the packages the
+  commit adds. Blocks on high and critical by default; one line per finding with
+  a fix hint and a `penthera.suppress.json` id. An existing hook is kept as
+  `pre-commit.pre-penthera`, runs first, and is restored by `uninstall`. Refuses
+  to write into a `core.hooksPath` managed by husky or lefthook without `--force`.
+  `.pre-commit-hooks.yaml` for pre-commit.com. Configured by a new `hook`
+  section in `penthera.policy.json` (`blockOn`, `checks`, `ignore`)
+- **License policy**: `penthera deps --license-policy <preset|file>` and a
+  `licenses` section in `penthera.policy.json` (`preset`, `allow`, `deny`,
+  `allowPackages`, `unknown`). Presets `permissive`, `weak-copyleft-ok` and
+  `no-agpl`. A small SPDX expression parser handles `AND`/`OR`/`WITH`,
+  parentheses, `+` and `LicenseRef-`, and matches deprecated ids (`GPL-3.0`) to
+  their current form. Breaches and `UNLICENSED` are high; missing, custom and
+  non-SPDX licenses are medium. Findings use category `license`; the SPDX id
+  list is vendored (`lib/deps/spdx.json`). CycloneDX SBOM components now carry
+  their license
+- **CRA Article 14 reporting helper** (`penthera --cra-init cra.json`,
+  `penthera --cra cra.json`, `lib/compliance/cra.js`): for an actively exploited
+  vulnerability (24h early warning, 72h notification, final report 14 days after
+  a fix is available) or a severe incident (24h, 72h, final report one month
+  after the notification). Computes due dates in UTC and local time (hours
+  elapsed, days and months on the calendar, DST-safe), flags overdue and late
+  reports, drafts each report against Art. 14(2)/(4) with `NEEDS INPUT` for
+  missing facts, adds an Art. 14(8) user advisory, and can prefill the affected
+  component, purl and CVEs from a Penthera SBOM and scan JSON. NL profile names
+  NCSC-NL and the ENISA Single Reporting Platform. Drafts, not the official
+  form, not legal advice. Guide: `docs/compliance-cra.md`
+- **CycloneDX 1.6 AI-BOM** (`penthera --repo . --aibom aibom.cdx.json`,
+  `lib/whitebox/aibom.js`): AI SDK dependencies, model identifiers in code as
+  `machine-learning-model` components with `modelCard` and file:line evidence,
+  MCP servers as `services`, and Agent Skills and prompt files as hashed `data`
+  components. Offline. Tests validate the output against the official
+  CycloneDX 1.6 schema, vendored in `tests/fixtures/cyclonedx/` (new dev
+  dependency: `ajv`)
+
+## [1.4.0] - 2026-10-19
+
+The biggest release so far, covering the v1.3.0 "AI toolchain" and v1.4.0
+"Local loop" milestones together. Penthera now does the routine work of a small
+security team on your own machine:
+- tests your app;
+- vets and guards your dependencies;
+- audits your AI tooling;
+- fixes what it finds on a local branch and verifies each fix;
+- writes reports and evidence for auditors.
+
+It still runs offline, with no telemetry. The first outside contribution, from
+@Nurana100, is in this release.
+
+Requires Node 22+. Upgrading from 1.1.x or 1.2.x needs no config changes.
+
+### Added
+
+- **GitHub Action** (`uses: danoszz/penthera@<sha>`, `action.yml`): on PRs that
+  change the lockfile it runs `penthera deps --base <PR base>`, upserts one PR
+  comment marked `<!-- penthera-deps -->` (edited in place on every push), and
+  uploads SARIF. Runs from the action's own checkout with no npx or npm install.
+  Fork PRs get the diff in the job summary. Also `mode: agents` and `mode: scan`,
+  plus `fail-on`. Example: `docs/examples/pr-dependency-review.yml`
+- **`penthera agents [path] [--home] [--pin]`**: an offline, deterministic audit
+  of AI developer tooling. It finds and parses `.mcp.json`, `.cursor/`,
+  `.claude/`, `.vscode/mcp.json`, `AGENTS.md`, `CLAUDE.md`, `.cursorrules`,
+  `.github/copilot-instructions.md` and skill folders; with `--home` also
+  `~/.claude` (settings, hooks, permissions, plugins, skills), `~/.claude.json`,
+  `~/.cursor/mcp.json` and the Claude Desktop config. Read-only, no network, no
+  LLM judge
+- Hidden-content engine (`lib/agents/hidden-content.js`): Unicode tag
+  characters (decoded), zero-width and bidi controls, variation-selector
+  smuggling, whitespace inflation, instructions in HTML comments, text aimed at
+  a scanner, base64 blobs (decoded and classified), binaries and archives in
+  skill folders by magic bytes, symlinks that leave a skill, and `curl | sh` /
+  `eval` style remote execution
+- Risky-config rules: unpinned `npx -y` / `uvx` / `bunx` / `pnpm dlx` MCP
+  servers, inline secrets in server env/headers/args (via `findSecretsInText()`),
+  plain-HTTP remote servers, hooks that auto-approve or pipe to a shell,
+  `Bash(*)` and other wildcard permissions, `bypassPermissions`, credential-file
+  allows, wildcard `allowed-tools`, and unpinned plugin marketplaces
+- `penthera.lock`: `--pin` records SHA-256 hashes of every skill folder, MCP
+  server definition, hook and installed plugin; later runs report changed (rug
+  pull), new and removed entries
+- A–F grade for the agent setup in the terminal and Markdown reports. Findings
+  use category `agent-config`, map to OWASP MCP Top 10 and Agentic (ASI) ids,
+  and get per-rule SARIF ids (`agents/<rule>`)
+- Agent Skill: Workflow 6 ("audit my MCP servers / skills / agent config")
+- `docs/METHODOLOGY.md`: threat model, what black-box and white-box scanning
+  can and cannot find, the confidence model, false-positive controls, the
+  non-destructive default, offline operation, and how new attack techniques
+  are adopted (reviewed rules in releases, never fetched at run time). Design
+  choices cite published research and standards
+- `docs/references.bib` and `docs/references.md`: 48 references, each checked
+  against the publisher or standards body, grouped by topic
+- Per-finding citations: `lib/references.json` maps each finding category to
+  1-3 references. The Markdown report adds a "Why this matters / Sources" line
+  per finding and a "Sources" line per action-plan item; SARIF rules get
+  `helpUri`, `help` and `properties.references`
+- Accuracy benchmark: `npm run bench` scans the mock server, two new local lab
+  targets (vulnerable and decoy) and a generated repo fixture, scores precision
+  and recall against `bench/ground-truth.json`, and writes `bench/RESULTS.md`.
+  Offline and seeded; `npm test` fails if it drops below the CI floor.
+  Optional Juice Shop and crAPI targets are documented
+- `CITATION.cff`, so GitHub shows "Cite this repository"
+- **`penthera deps [path]`**: offline, deterministic dependency risk scanning
+  for npm. Reads `package-lock.json` (v1-v3), statically scans every installed
+  package and reports what it can do, with `file:line` evidence: install
+  scripts (including implicit `node-gyp`), shell, network, writes outside its
+  folder, environment reads and bulk access, `eval` / `new Function` / `vm`,
+  computed `require`/`import`, native binaries, and obfuscation signals
+- **Capability diff** (`--diff <lockfile|dir>`, `--base <git-ref>`): packages
+  that are new or that gained capabilities in an upgrade. Old versions come
+  from the base tree or npm's local content cache, verified against the
+  lockfile integrity, so the diff works offline
+- Attack indicators: writes to `~/.claude`, `~/.cursor`, `.mcp.json` or the
+  Claude Desktop config, running the `claude` / `gemini` / `q` CLIs (the
+  s1ngularity pattern), GitHub token harvesting, and the whole environment
+  serialised next to network code
+- Typosquat / slopsquat check against a vendored list of ~7,800 popular npm
+  names (`lib/deps/popular-packages.json`, from npm-high-impact), refreshed at
+  release time by `npm run refresh:popular`. Nothing is fetched at runtime
+- `--online` (off by default, the only network use): npm registry metadata for
+  fresh versions, brand-new packages, publisher changes and deprecations
+- `--pr-comment <file>` and an example workflow
+  ([`docs/examples/github-actions-deps.yml`](docs/examples/github-actions-deps.yml))
+  that comments the capability diff on PRs that change the lockfile
+- Findings use category `dependency-risk` and source `deps-scan`; SARIF
+  results now carry a start line when a finding has one
+- **`penthera install [pkg...]`**: an install firewall on the `deps` engine.
+  npm resolves the new tree in a temporary copy with scripts off
+  (`--package-lock-only --ignore-scripts`), new tarballs are fetched with
+  `npm cache add` and read back only after an integrity check, and the
+  capability diff, new install scripts (with their commands) and typosquats
+  are shown before anything in the project changes. `penthera.policy.json`
+  (`allow` names/globs, `deny` and `requireApproval` capabilities) decides;
+  by default new install scripts, AI-config writes, AI CLI invocation, token
+  harvesting, obfuscation, typosquats and unreadable packages need approval.
+  Interactive by default, `--yes` for CI (installs only when nothing breaches
+  the policy), `--dry-run` to report. On approval the reviewed lockfile is
+  installed as is, with `--ignore-scripts` unless the scripts were approved
+  (on npm 12+, approved scripts are pinned in `package.json` `allowScripts`).
+  An abort leaves the project byte for byte unchanged. npm's registry traffic
+  is the only egress, and it is printed
+- `scanDeps()` accepts `treeRoot` and a list of cache dirs; the diff output
+  carries each changed package's install scripts
+- **Fix recipes** (`lib/fix/`, `penthera fix`): deterministic, local fixes for
+  common findings, printed as unified diffs. `penthera fix --plan` plans fixes
+  for a fresh repo scan or an earlier `-o` report; `penthera fix --apply <id>`
+  applies one after a y/N prompt (or `--yes`), then re-scans to verify. Recipes:
+  security headers (Next.js, Express, Fastify, Hono), cookie flags, CORS
+  wildcard to an allowlist from `CORS_ALLOWED_ORIGINS`, a rate-limit stub on
+  login/auth routes, and a hardcoded secret moved to an env var with
+  `.env.example` updated (always with the owner action to rotate it)
+- `applyDiff()` refuses paths outside the repo (symlinks included), `.git`,
+  and dirty or non-git trees unless `--allow-dirty`, and writes nothing unless
+  every hunk applies. Planning never writes; nothing is committed or pushed
+- Recipes edit only at exact anchors and return no plan when the anchor is
+  missing, instead of a risky diff
+- Optional `--fix-model <name>` fallback for findings no recipe matches. It
+  talks only to Ollama on `127.0.0.1:11434`, is off by default, and labels its
+  output `confidence: "needs-human-review"`, `source: "local-model"`
+- Fixtures for Next.js, Express, Fastify and Hono under `tests/fixtures/fix/`
+- `detectFramework()` is now exported from `lib/whitebox/frameworks.js`
+- **Audience reports** (`--audience developer|owner|auditor`): developer gets
+  findings with file:line, fix recipe ids or diffs, and sources; owner gets a
+  plain-language summary, what to do first, owner actions and the trend from
+  memory; auditor gets scope and method (linking `docs/METHODOLOGY.md`),
+  confidence labels with provenance per finding, egress and inconclusive
+  probes, suppressions with who and why, and NIS2 and OWASP mapping tables.
+  The default report is unchanged
+- **User templates** (`--report-template file.md`): `{{a.b}}`,
+  `{{#each}}`, `{{#if}}`/`{{else}}`, nothing else. Values are HTML- and
+  Markdown-escaped; no helpers, code, includes or prototype access. Written from
+  scratch (`src/report/template.js`) and fuzz-tested against injection
+- **Fix timeline** in the audience reports: found → fixed → verified with time
+  to fix, from an agent loop run (`loopRun`) or memory fix events
+  (`lib/memory/history.js`, also the owner report's trend)
+- **Evidence bundle** (`--evidence <dir>`, `--sign-key <ssh-key>`): JSON,
+  Markdown, SARIF, the three audience reports, a custom template report, the
+  readiness report and SBOM when requested, and `manifest.json` (tool version,
+  command line with secrets redacted, timestamp, target, git commit, SHA-256 of
+  every file). Signing uses `ssh-keygen -Y sign -n penthera-evidence`; no new
+  dependency. `penthera evidence verify <dir> [--allowed-signers <file>]`
+  recomputes every hash, rejects changed, missing, extra and symlinked files,
+  and checks the signature. See `docs/evidence.md`
+- **`penthera agent --loop`** (`src/agent/`): the local scan → triage → plan →
+  patch → verify → learn loop. Fixes are applied one at a time on a local
+  branch `penthera/fix-<yyyymmdd-hhmm>`, verified by a re-scan (and the
+  project's tests with `--run-tests`), committed when verified and reverted
+  when not. Every diff needs `y/n/skip/quit` approval; `--auto low` auto-applies
+  only recipes memory shows verified 3+ times with no failures on the
+  framework. Stops when nothing fixable is left or at `--max-iterations`
+  (default 5). `-o` writes a `loopRun` JSON (iterations, fixes, time per step),
+  also appended to memory as a new `loop_run` event
+- The loop runs git only through an allow-list of local subcommands with
+  `protocol.allow=never`, no lazy fetch and the repo's hooks disabled; it never
+  pushes, fetches or opens pull requests. Scans run in one offline egress
+  context (the `--url` host only; Ollama on 127.0.0.1 only with
+  `--fix-model`). It refuses a dirty tree or detached HEAD unless
+  `--allow-dirty`, and Ctrl-C leaves only verified commits on the fix branch
+
+### Docs
+
+- Sharper positioning: "the routine work of a security team, on your own
+  machine". The README now opens with what Penthera does for you, why you can
+  trust it, and a factual table of how it fits next to Socket, Snyk, GitHub,
+  OWASP ZAP and Anthropic's OSS Scanner. The package, plugin, skill and
+  repository descriptions match.
+- Funding and partnership drafts under `docs/funding/`: an NLnet application
+  draft, GitHub Sponsors tiers, a partner brief, and a due diligence checklist.
+- CONTRIBUTING: commits are signed off under the Developer Certificate of Origin.
+- **`--offline`**: the scan contacts only the target. Recon is skipped, the
+  Retire.js check uses the vendored database snapshot, and every other host is
+  refused by the HTTP client (redirects may stay within the target's
+  registrable domain). Groundwork for the local agent loop.
+- **Vendored Retire.js database** (`lib/data/retire-jsrepository.json.gz`,
+  72 KB gzipped) with source URL, date and SHA-256 in a meta file.
+  `npm run refresh:retire-db` updates it at release time, and
+  `npm run refresh:retire-db -- --check` reports drift from upstream. Online
+  scans fall back to it when the live download fails.
+- **Third-party egress report**: every scan lists the hosts it contacted
+  besides the target, in the terminal summary and in a "Network egress" section
+  of the Markdown report (`result.egress` in JSON).
+- **`--user-agent <ua>`** to override the new default User-Agent.
+
+### Changed
+
+- Every request now sends `User-Agent: penthera/<version>
+  (+https://github.com/danoszz/penthera)` instead of Node's default (#7;
+  first added by @Nurana100 in #20, our first outside contribution).
+- Probe failures (timeouts, connection errors, refused hosts) are recorded as
+  `result.errors[]` (`{ probe, url, message, count }`). The terminal summary
+  shows "N probes inconclusive", and the Markdown report lists them under
+  "Inconclusive probes" (#8).
+- All network calls go through one client in `src/utils/http.js`, which owns
+  timeouts, the User-Agent and egress policy. The per-module fetch wrappers in
+  the crawler, injection, fuzzer, template, recon, parameter, Retire.js and
+  adaptive-probe modules are gone.
+- **Local learning store** (`lib/memory/`), the memory behind the v1.4 local
+  loop. `--memory` records each scan under `~/.penthera/memory/<project-id>/`
+  (or `PENTHERA_HOME`) as an append-only, hash-chained event log, then uses it
+  to suppress findings marked as false positives and to rank findings within a
+  severity. Suppressed findings are listed in their own section with who
+  suppressed them and why. Memory is never read from the scanned repo and
+  nothing in it is ever executed; a broken chain means memory is not applied.
+  See [docs/local-loop.md](docs/local-loop.md) for the threat model
+- `penthera memory show | verify | forget [--all] | suppress <id> --reason <text>`
+- Optional repo file `penthera.suppress.json` for shared suppressions. Every
+  finding it hides is labelled "suppressed by repo file" with its reason
+
 ## [1.2.0] - 2026-10-19
 
 The first step toward securing the AI toolchain itself: catch AI provider keys,