penthera 1.1.1 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,272 @@ All notable changes to Penthera are documented here. Versioning follows [SemVer]
 
 ## [Unreleased]
 
+## [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,
+harden Penthera's own supply chain, and make CI test what it says it tests. The
+[roadmap](ROADMAP.md) now sets out the AI supply-chain and local agent-loop
+tracks.
+
+### Added
+
+- **AI provider key detection** in repo scans: Anthropic, OpenAI project and
+  service-account keys, OpenRouter, Google (Gemini / Firebase), Groq, Hugging
+  Face, Replicate, xAI, Perplexity, LangSmith, and Pinecone. Jupyter notebooks
+  (`.ipynb`) are now scanned too. A provider key inside an `api_key = "..."`
+  assignment is reported once, under its provider, instead of twice
+- `findSecretsInText()` exported from `lib/whitebox/secrets.js`, so the same
+  rules can run on any text (groundwork for scanning JS bundles)
+- CodeQL and OpenSSF Scorecard workflows, Dependabot for npm and GitHub Actions
+  (with a 7-day cooldown before adopting new releases)
+- CI check that `package.json`, the lockfile, the skill, and both plugin
+  manifests carry the same version
+- Roadmap: AI supply-chain audit (`penthera agents`), a fully local
+  scan → fix → verify → learn loop, and LLM-endpoint probes. Principles now
+  state no telemetry, no auto-push, and no remote learning
+
+### Fixed
+
+- **Modern OpenAI keys were missed.** The old pattern stopped at the hyphen in
+  `sk-proj-...` and `sk-svcacct-...`, so the key format OpenAI has issued since
+  2024 never matched
+- The example scan workflow lived in `.github/workflows/`, so it ran on its
+  weekly cron and failed every Monday. It moved to
+  `docs/examples/github-actions-scan.yml` and now uses `npx penthera@<version>`,
+  so it works when copied into your own repo
+- CI ran only 4 of 24 test files; it now runs the full `npm test`
+- Removed `tests/pentest-static.test.js`, which tested functions defined inside
+  the test file rather than anything Penthera ships
+- `.claude-plugin/plugin.json` still said 1.0.0
+- `SECURITY.md` listed 1.0.x as supported. It now covers 1.2.x and gives response
+  times, scope, and safe-harbor terms
+
+### Changed
+
+- **Node.js 22 or newer is now required.** Node 18 and 20 are end-of-life, and
+  the test toolchain (vitest 5) needs 22. CI runs on Node 22 and 24
+- GitHub Actions are pinned to commit SHAs, and every workflow declares
+  least-privilege `permissions`
+- Releases use npm trusted publishing (OIDC, no stored token) and **staged
+  publishing**: CI stages each version, and it only goes live after a
+  maintainer approves it with 2FA. The workflow also creates the GitHub Release
+- The Docker image runs as the unprivileged `node` user on `node:22-alpine`
+- README reordered so install and quick start come before compliance. The full
+  NIS2 guide moved to [`docs/compliance-nis2.md`](docs/compliance-nis2.md)
+- vitest 3 → 5 (clears 8 dev-only advisories), yaml 2.8 → 2.9
+
 ## [1.1.1] - 2026-08-16
 
 A correctness release. One of these was a live outage: if you are on 1.1.0,
@@ -176,7 +442,7 @@ and generated documents.
   live integration tests report as skipped (not passed) without a running target
 - Corrected the built-in template count (14, not 17) in docs and progress output
 
-## [1.0.0], 2026-06-30
+## [1.0.0] - 2026-06-30
 
 First production-ready release.
 
@@ -201,11 +467,11 @@ First production-ready release.
 
 - URL trailing-slash normalization (double-slash 404 bug)
 
-## [0.2.0], 2026-04
+## [0.2.0] - 2026-04
 
 - Markdown reports, scan profiles, auth tooling, expanded API discovery
 
-## [0.1.x], 2026-04
+## [0.1.x] - 2026-04
 
 - Initial CLI: URL, repo, and machine scan modes
 - Built-in templates, TLS, CORS, SARIF export