penthera 1.2.0 → 1.5.0

package/docs/funding/sponsor-tiers.md

@@ -0,0 +1,81 @@
+# GitHub Sponsors tiers (proposal)
+
+Status: proposal. The tiers below still need to be created on the GitHub
+Sponsors dashboard once the profile is approved. Prices are in US dollars
+because GitHub Sponsors tiers are priced in USD.
+
+## Tiers
+
+| Tier | Monthly | For | What you get |
+|------|---------|-----|--------------|
+| Individual | $5 | People who use Penthera on their own projects | Thanks, and your name on the sponsors list on GitHub if you want it. |
+| Supporter | $25 | Freelancers and consultants who use Penthera for clients | The above, plus a mention in the release notes of the next minor release. |
+| Startup | $100 | Small teams and startups | The above, plus your name and a link in the README under "Sponsors". |
+| Company | $500 | Companies that rely on Penthera or build on it | The above, plus your logo in the README under "Sponsors", and a 30-minute call per quarter to talk through the roadmap. |
+
+One-time sponsorships of any amount are also welcome.
+
+## What sponsorship pays for
+
+Maintainer time. Specifically, in rough order:
+
+1. Keeping detection rules current: new AI provider key formats, new
+   supply chain attack patterns, new checks for developer tooling.
+2. Security fixes and releases for Penthera itself.
+3. The roadmap in [ROADMAP.md](../../ROADMAP.md).
+
+## What sponsorship does not buy
+
+Written down so nobody is surprised:
+
+- **No influence over findings.** Sponsors' products are scanned and reported
+  the same way as everyone else's. A sponsor cannot have a rule removed or
+  softened.
+- **No roadmap control.** The quarterly call is a conversation, not a vote.
+  Priorities stay set by evidence of what users need.
+- **No support contract or SLA.** Penthera is maintained part-time. Bug reports
+  are handled in public issues, in the order the maintainer judges best.
+- **No early or private access to vulnerability information.** Security issues
+  follow [SECURITY.md](../../SECURITY.md) for everyone.
+- **No certification or endorsement.** A logo in the README means the company
+  supports the project. It does not mean Penthera has assessed or approved that
+  company's security, and the README will say so next to the logos.
+- **No change to the principles.** No telemetry, offline first, MIT licence.
+  Sponsorship will never add a feature that sends data off the user's machine.
+
+## Logo rules (Company tier)
+
+- One logo, at most 160 px wide, in the README "Sponsors" section, linked to the
+  company site.
+- Logos are listed in the order sponsorships started.
+- The logo is removed in the first README update after a sponsorship ends.
+- The maintainer may decline or end a sponsorship, for example for a company
+  whose product is malware or surveillance tooling. Any payment for a month not
+  yet started is then refunded.
+
+## Fees and money, for transparency
+
+From the GitHub Sponsors docs: GitHub charges no fees on sponsorships from
+personal accounts. Sponsorships from organisation accounts carry up to 6% in
+fees (3% card processing and 3% GitHub service fee; invoiced billing avoids the
+card fee). Tier prices cannot be edited after publishing; a tier has to be
+retired and replaced. Source:
+https://docs.github.com/en/sponsors/receiving-sponsorships-through-github-sponsors/about-github-sponsors-for-open-source-contributors
+
+The maintainer intends to publish a short yearly note on total sponsorship
+income and what it paid for.
+
+## Proposed edits in this PR
+
+- `.github/FUNDING.yml`: adds a `custom` link to this page, so the Sponsor
+  button explains the tiers before the GitHub Sponsors profile is live.
+- `README.md`, "Support Penthera": lists the tiers in short and links here.
+
+## Open questions for the maintainer
+
+- Are $100 and $500 right for startups and companies? They are deliberately
+  modest. Raise them if the first sponsors suggest so.
+- Is a quarterly call something you want to commit to? If not, drop it from the
+  Company tier before publishing, because published tiers cannot be edited.
+- Check with a tax adviser how sponsorship income should be reported in the
+  Netherlands before the first payout.

package/docs/index.md

@@ -1,6 +1,6 @@
 # Penthera documentation
 
-Security scanner for developers: scan live URLs, local repos, or macOS machines from your AI agent or the CLI.
+Open-source security for the apps and AI systems you ship: check it before you deploy, vet what you build with, keep watching after you ship. Offline, deterministic, free.
 
 ## Getting started
 
@@ -9,6 +9,7 @@ Security scanner for developers: scan live URLs, local repos, or macOS machines
 | [README](../README.md) | Install, quick start, ethical use |
 | [Run it](../README.md#run-it) | Install + first-time wizard (`penthera` with no args) |
 | [CHANGELOG](../CHANGELOG.md) | Version history |
+| [Roadmap](../ROADMAP.md), [plan to v2.0](./plan.md) and [release plan](./release-plan.md) | What ships next, in what order, and how quality is measured |
 
 ## Scanning
 
@@ -34,10 +35,20 @@ Security scanner for developers: scan live URLs, local repos, or macOS machines
 |-------|------|
 | OWASP WSTG mapping | [owasp-wstg-coverage.md](./owasp-wstg-coverage.md) |
 | NIS2 compliance guide | [compliance-nis2.md](./compliance-nis2.md) |
+| Local loop and learning store | [local-loop.md](./local-loop.md) |
 | Scan your app in GitHub Actions | [examples/github-actions-scan.yml](./examples/github-actions-scan.yml), set `PENTEST_STAGING_URL` |
 | Penthera's own CI | `.github/workflows/ci.yml` (full tests + mock scan), `codeql.yml`, `scorecard.yml` |
 | Docker | `docker build -t penthera . && docker run penthera https://localhost:3000` |
 
+## Methodology & research
+
+| Topic | Link |
+|-------|------|
+| How detection works, confidence model, limits | [METHODOLOGY.md](./METHODOLOGY.md) |
+| Cited research and standards | [references.md](./references.md) ([BibTeX](./references.bib)) |
+| Accuracy benchmark (`npm run bench`) | [bench/README.md](../bench/README.md), latest [results](../bench/RESULTS.md) |
+| Citing Penthera | [CITATION.cff](../CITATION.cff) |
+
 ## Agent skill
 
 | Topic | Location |

package/docs/local-loop.md

@@ -0,0 +1,276 @@
+# The local loop
+
+Penthera v1.4 adds a loop that runs entirely on your machine: scan, fix on a
+local branch, verify, learn, repeat. Nothing in it talks to a Penthera server,
+because there isn't one. This page covers the loop itself (`penthera agent
+--loop`) and the part that makes it improve over time: the local learning store.
+
+## The agent loop
+
+```bash
+penthera agent --loop --repo . --url http://localhost:3000 -o reports/loop.json
+penthera agent --loop --repo . --run-tests          # also run the project's test script
+penthera agent --loop --repo . --auto low           # auto-apply only recipes memory has proven
+```
+
+One iteration:
+
+1. **Scan** the repo (white-box scan plus the fix recipes' static probes) and,
+   with `--url`, the running app.
+2. **Triage**: drop findings suppressed in memory or `penthera.suppress.json`,
+   and rank the rest with memory (severity always first).
+3. **Plan**: a deterministic recipe first. The local model is asked only with
+   `--fix-model <name>`, and only for findings no recipe matches.
+4. **Patch** on a local branch `penthera/fix-<yyyymmdd-hhmm>`, created from the
+   current HEAD when the run starts.
+5. **Verify**: re-scan. A fix passes when the findings it targeted are gone from
+   the repo scan, no new finding appeared, and, with `--run-tests`, the
+   project's `test` script exits 0 (`node --run test`).
+6. **Learn**: `scan`, `fix_applied` and `fix_verified` or `fix_failed` go to
+   memory.
+7. **Commit** each verified fix on its own, with a message that lists the
+   findings, the recipe, and how it was verified. A fix that fails is reverted
+   (`git checkout` of the files it changed; files it created are removed).
+
+Plans are applied one at a time and re-planned against the tree after each
+fix, since two recipes can touch the same file. The loop repeats until nothing
+fixable is left, `--max-iterations` (default 5) is reached, or you stop it.
+A fix you decline (`n`) or that fails verification is not proposed again in
+the same run; `s` skips it until the next iteration.
+
+A live URL serves the code it was started with, so a fix to response headers
+shows up in the URL scan only after the app restarts. The loop counts those as
+`liveRemaining` in the fix's `verify` block, not as a failure; the repo scan
+decides whether the fix landed.
+
+### What it guarantees
+
+Each of these has a test in `tests/agent.test.js`.
+
+- **No remote operations.** All git goes through `src/agent/git.js`, an
+  allow-list of local subcommands (`rev-parse`, `symbolic-ref`, `status`,
+  `diff`, `log`, `show-ref`, `checkout`, `add`, `commit`, `config --get`).
+  `push`, `fetch`, `pull`, `remote`, `clone`, `ls-remote`, `submodule` and
+  everything else are refused before a process starts, as are URL arguments
+  and `-c` overrides. Every call also runs with `protocol.allow=never` and
+  `GIT_NO_LAZY_FETCH=1`, so no transport can work. The loop never runs `gh`
+  and never opens a pull request.
+- **The repo's hooks never run.** Git runs with `core.hooksPath=/dev/null`,
+  `core.fsmonitor=false` and `commit --no-verify`: a scanned repo can ship hooks
+  that run anything.
+- **Network.** The whole run is one W1 egress context with `--offline` always
+  on: the URL target is the only host. Loopback is added only when
+  `--fix-model` is set, and the model client then accepts only
+  `http://127.0.0.1:11434`.
+- **Clean start.** A dirty tree (untracked files included), a detached HEAD, a
+  repo without commits, or a directory that is not a git repo is refused.
+  `--allow-dirty` lets the loop start anyway, but it never patches a file that
+  had uncommitted changes.
+- **Approval.** Every diff is shown, secrets masked, with
+  `[y]es / [n]o / [s]kip / [q]uit`. When input runs out (piped stdin), the
+  answer is `n`. `--auto low` applies a diff without asking only when it comes
+  from a recipe (not the model), its confidence is not `needs-human-review`,
+  memory's chain verifies, and memory shows that recipe with at least 3
+  verified fixes and no failures for this framework.
+- **Interruption.** The first Ctrl-C lets the fix in flight finish: it is
+  verified and committed, or reverted. The loop then stops on the fix branch,
+  which holds only verified commits. A second Ctrl-C reverts the fix in flight
+  at once and exits.
+
+`--run-tests` runs the project's own code, so it can do anything that code
+does, including network calls. It is off by default for that reason.
+
+### The loopRun object
+
+`-o <file>` writes `{ "loopRun": { ... } }`. W6's report timeline renders it.
+Every step carries `startedAt` and `durationMs`.
+
+```js
+{
+  schema: "penthera.loopRun/1",
+  id, startedAt, finishedAt, durationMs,
+  target: { repo, url },
+  branch: { base, baseSha, fix },            // base is null on a detached HEAD
+  options: { maxIterations, auto: "off" | "low", runTests, fixModel, offline: true, allowDirty },
+  stopReason: "no-fixable-findings" | "declined-or-failed-left" | "max-iterations"
+            | "user-quit" | "interrupted" | "error",
+  error,                                     // message when stopReason is "error"
+  findings: { initial, final },              // non-info, unsuppressed
+  totals: { iterations, planned, applied, verified, failed, declined, skipped, commits: [sha] },
+  memory: { projectId, chain: "ok" | "broken", eventsAppended },
+  iterations: [{
+    n, startedAt, durationMs,
+    findings: { total, suppressed, fixable },
+    steps: [{ step: "scan" | "triage" | "plan", startedAt, durationMs }],
+    fixes: [{
+      planId, recipe, title, framework, source: "recipe" | "local-model", confidence,
+      files, findings: [{ fid, title, severity, category }],
+      memory: { verified, failed } | null,   // recipe history when the plan was ranked
+      decision: "approved" | "auto" | "declined" | "skipped" | "quit" | "obsolete",
+      status: "verified" | "failed" | "not-applied",
+      reason, commit,
+      verify: { targetedRemaining, newFindings, liveRemaining, tests: { ok, exitCode, durationMs } | null } | null,
+      testOutput,                            // tail of the test output, only when tests failed
+      steps: [{ step: "approve" | "patch" | "learn" | "verify" | "commit" | "revert", startedAt, durationMs }],
+    }],
+  }],
+}
+```
+
+`obsolete` means an earlier fix in the same iteration already covered the plan.
+The same object, without `testOutput` and with finding ids in place of finding
+objects, is appended to memory as a `loop_run` event.
+
+Exit codes: `0` nothing fixable left, `1` fixable findings remain (declined,
+failed, or out of iterations), `2` the loop could not start (dirty tree,
+detached HEAD, bad options), `130` interrupted.
+
+## The learning store
+
+Scans run with `--memory` record what happened, and the next scan uses that
+record to rank and suppress findings.
+
+```bash
+penthera --repo . --memory            # scan, apply memory, record this scan
+penthera memory show                  # what memory knows about this project
+penthera memory verify                # check the hash chain
+penthera memory suppress <id> --reason "set by the CDN" [--expires 2027-01-01]
+penthera memory forget                # delete this project's memory
+penthera memory forget --all          # delete all memory
+```
+
+`<id>` is the 16-character `fid` shown next to each finding in a `--memory`
+report.
+
+### Where it lives
+
+```
+~/.penthera/memory/<project-id>/events.jsonl   the event log
+~/.penthera/memory/<project-id>/head.json      count and hash of the last event
+~/.penthera/memory/<project-id>/meta.json      the project's path or origin, for `memory show`
+```
+
+`<project-id>` is a SHA-256 of the repo's absolute path plus its git remote URL,
+or of the target origin for URL-only scans. Set `PENTHERA_HOME` to move the
+root (the tests do). Penthera reads the remote from `.git/config` itself rather
+than running `git`, because running git inside an untrusted repo can execute
+that repo's hooks or `core.fsmonitor` command.
+
+### What it records
+
+One JSON event per line, append-only:
+
+```json
+{ "v": 1, "ts": "...", "type": "scan", "data": { ... }, "prev": "<hash of previous line>", "hash": "..." }
+```
+
+`hash = sha256(prev + canonical JSON of { v, ts, type, data })`, with object
+keys sorted. The first line's `prev` is derived from the project id.
+
+| Type | Data |
+| --- | --- |
+| `scan` | stack, modes, counts by severity, ids of the actionable findings |
+| `probe_yield` | probe id, stack, findings count |
+| `fix_applied` | finding id, recipe id, framework, category, diff SHA-256 |
+| `fix_verified` / `fix_failed` | finding id (recipe and framework are joined from `fix_applied`) |
+| `fp_suppressed` | finding id, reason, actor, optional expiry |
+| `loop_run` | one `penthera agent --loop` run: the [loopRun](#the-looprun-object) without test output, finding ids only |
+
+From these, `penthera memory show` derives four views: recipe success rate per
+framework, active suppressions, probe ranking by yield per stack, and median
+time to fix (first seen in a scan to `fix_verified`).
+
+### How a scan uses it
+
+Memory can do two things to a report, and nothing else:
+
+1. **Suppress** a finding the user (or the loop, on the user's behalf) marked as
+   a false positive, with a reason. Suppressed findings move to a separate
+   "Suppressed" section in the terminal and Markdown reports, each with who
+   suppressed it and why. They do not count toward the exit code.
+2. **Re-order** findings within a severity: categories with a fix recipe that
+   has worked on this framework come first, then findings that have shown up in
+   more past scans. Severity is never changed and no finding is dropped.
+
+## Threat model
+
+The learning store is an attack surface. An agent loop that learns from its own
+past is open to memory poisoning (OWASP Agentic Security Initiative, ASI06): if
+an attacker can write to what the loop remembers, they can steer what it does
+next. In Penthera's case the obvious targets are hiding a real finding and
+getting the loop to run something. The store is designed so neither works
+quietly.
+
+### Why it never executes
+
+Memory is data. No value read from it is ever executed, evaluated, imported,
+used as a file path, or passed to a shell. A recipe id in memory is only a
+string that gets counted; the recipe code lives in Penthera's own source
+(`lib/fix/`) and is chosen by Penthera, not by the log. Every field a view reads
+is type- and length-checked, and an event that fails a check is ignored rather
+than interpreted. Strings shown in the terminal have control characters stripped,
+so a stored reason cannot inject ANSI escape sequences.
+
+The worst a fully poisoned memory can do is hide findings, and hidden findings
+are listed, with their reason, in every report.
+
+### Why it is hash-chained
+
+The chain makes tampering visible. Editing a line, reordering lines, deleting a
+line from the start or middle, or splicing in another project's log all break
+the chain, and `penthera memory verify` names the first broken line. `head.json`
+records the count and hash of the last event, so cutting lines off the end is
+caught too.
+
+When the chain is broken, scans **fail closed**: memory suppressions and
+ranking are not applied, nothing new is appended, and the scan prints a warning
+telling you to run `penthera memory verify`. You can then inspect the log or
+start over with `penthera memory forget`.
+
+What the chain does not do: it is tamper-evident, not tamper-proof. Anyone who
+can write to your home directory can rewrite the whole log and recompute every
+hash. Keying the chain would not help, since the key would sit in the same home
+directory. The chain is there to catch a partial edit, an accidental truncation,
+or a tool that writes where it should not; it is not a defence against malware
+already running as you.
+
+### Why it lives in your home directory
+
+Memory is never read from the scanned repo. If it were, a repo could ship
+pre-poisoned memory, for example a suppression for the secret it is about to
+leak. Keeping memory under `~/.penthera` means only runs on your machine, as
+you, write to it.
+
+### The one thing a repo can say: `penthera.suppress.json`
+
+Teams do need to share decisions like "this key is a revoked test fixture". For
+that a repo may contain `penthera.suppress.json`:
+
+```json
+{
+  "version": 1,
+  "suppress": [
+    { "id": "16e06eb3fd94664b", "reason": "test fixture, revoked", "expires": "2027-01-01" }
+  ]
+}
+```
+
+It is held to a stricter standard than memory:
+
+- Every entry needs a reason. Entries without one, with a malformed id or date,
+  or past their expiry are dropped with a warning.
+- Every finding it hides is listed in the report as **suppressed by repo file**
+  with the reason, so a reviewer sees both the file change in the PR and its
+  effect in the report.
+- It only applies with `--memory`, and a local suppression for the same finding
+  takes precedence.
+
+Treat a change to `penthera.suppress.json` in a pull request like a change to
+CI config: it decides what the scanner reports.
+
+### Concurrency
+
+Two scans of the same project can run at once. Each append takes an exclusive
+lock file (`events.lock`, created with `O_EXCL`), reads the tip, and writes one
+line with a single `O_APPEND` write. Lines never interleave and the chain never
+forks. A lock older than 30 seconds is treated as stale and removed.

package/docs/plan.md

@@ -0,0 +1,100 @@
+# Plan to v2.0
+
+How Penthera gets from "many features, shipped fast" to a tool a team can rely
+on without thinking about it. Written 2026-10-19. The [roadmap](../ROADMAP.md)
+says *what* ships; this says *how well*, and in what order.
+
+Penthera is maintained part-time alongside a PhD, so the plan is built around
+small, finishable pieces and automation that keeps quality from depending on
+anyone's free evenings.
+
+## The problem we solve
+
+Teams ship apps and AI agents faster than anyone can secure them. Penthera is
+the open-source security team for teams that don't have one, in three moments:
+
+1. **Before you deploy.** Test the app on localhost or a preview URL, fix what
+   it finds on a local branch, and prove the fix.
+2. **What you build with.** Vet dependencies, installs, and AI tooling (skills,
+   MCP servers, hooks) before they get access to your machine and credentials.
+3. **After you ship.** Keep watching your own production for drift, and produce
+   the reports and evidence that customers and regulators ask for.
+
+All of it local, deterministic, and free. Anything that doesn't serve one of
+these three moments is out of scope.
+
+## Milestones
+
+| Release | Theme | Done when |
+|---------|-------|-----------|
+| v1.5.0 | AI apps and compliance | Pre-commit hook, license policy, CRA helper, AI-BOM, signed rule packs, Python `deps`, dashboard, internal audit all merged and passing the audit |
+| v1.6.0 | Before you deploy | `penthera ship` and preview-deployment scanning work on a real Vercel and Netlify project |
+| v1.7.0 | After you ship | `penthera watch` runs weekly on three real production apps for a month without a false alarm anyone complained about |
+| v2.0.0 | Stable | Public interfaces frozen (CLI flags, JSON report schema, policy file, rule-pack format), documented, and covered by compatibility tests |
+
+## What "perfect" means, concretely
+
+Quality is measured, not felt. Each item below has a gate that the internal
+audit (`npm run audit:internal`) or CI checks automatically.
+
+### 1. Accuracy
+- Benchmark precision and recall never drop between releases (the audit fails
+  on a drop of more than 0.02).
+- Expand the benchmark beyond the mock server: OWASP Juice Shop, crAPI, a
+  deliberately vulnerable Next.js app, and fixture sets for `agents` and `deps`.
+- Every false positive reported by a user becomes a regression test before it
+  is fixed.
+
+### 2. First-run experience
+- From `npx penthera` to a useful result in under two minutes on a fresh Next.js
+  or Express app, measured on a clean machine each release.
+- Every error message says what happened and what to do next. No stack traces
+  for expected failures.
+- Works on macOS, Linux, and Windows (add a Windows CI job; the symlinked Cursor
+  skill and path handling are the known risks).
+
+### 3. Documentation
+- The README stays a front page: problem, what it does, install, trust. Feature
+  detail moves into a docs site (`docs/`), one page per command, each with a
+  copy-paste example and its real output.
+- Every command's `--help` and its docs page are generated from or tested
+  against the same source, so they never drift.
+
+### 4. Stability of interfaces
+- A versioned JSON schema for reports, the policy file, and rule packs, checked
+  in CI.
+- A deprecation policy: one minor release of warnings before anything breaks.
+
+### 5. Security of Penthera itself
+- Self-scan clean on every release (`--repo`, `agents`, `deps`, the dashboard).
+- Anything that parses untrusted input (packages, configs, scan responses, rule
+  packs) has a fuzz or hostile-input test. The ReDoS fixed in `deps` is the
+  reason why.
+- An external review before v2.0: ask an academic security group or a volunteer
+  from the OWASP community to look at the fix loop, the install firewall, and
+  the dashboard, the three parts that write files or run commands.
+
+### 6. Real-world proof
+- Three pilot projects (friendly teams, a student project, one of the
+  maintainer's own) run Penthera before each deploy for a month. Their feedback
+  sets the priorities for the next release.
+- Publish what Penthera found and fixed, with permission, as short case studies.
+
+## Working rhythm
+
+- One release every two to three weeks, each with a single theme.
+- The internal audit runs weekly and before every tag; a red audit blocks the
+  release.
+- Issues labelled `good first issue` are kept stocked (three to five open at a
+  time), so contributors can help without needing the maintainer's time.
+- Anything that needs judgement (a new probe that sends payloads, anything
+  touching third parties) gets a short design note in `docs/` before code.
+
+## Explicitly not doing
+
+- A hosted service, telemetry, or an update channel that fetches rules at run
+  time.
+- Offensive tooling for targets the user does not own, and attack-payload
+  generation for AI systems.
+- An LLM as the judge of what is malicious. Models may help write fixes,
+  locally, and always labelled as such.