penthera 1.7.0 → 1.8.0

package/docs/local-loop.md

@@ -1,276 +0,0 @@
-# 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/marketing.md

@@ -1,151 +0,0 @@
-# Marketing automation
-
-Penthera is maintained by one person with no budget, so the routine parts of
-getting the word out run by themselves. The rule is simple: **automation drafts
-and collects, a person posts.**
-
-- No social-media API tokens and no auto-posting. Every post is copied and
-  pasted by a person.
-- No analytics, tracking pixels or telemetry. The numbers come from public
-  pages and APIs that anyone can read.
-- Every workflow is SHA-pinned and has least-privilege permissions. Workflows
-  that write only open issues (`issues: write`). Only the demo-media workflow
-  pushes, and only to a `media/*` branch for a PR.
-- Nothing can embarrass the project without a person in the loop: drafts land
-  in issues, job summaries, a collapsed release section or a PR.
-
-## What runs
-
-| Automation | When | Output | Workflow / script |
-|------------|------|--------|-------------------|
-| Release post drafts | Every `v*` tag | LinkedIn (~600 chars) and X/Bluesky (≤280) drafts in the job summary and under "Share this release" in the GitHub Release (the read-only publish job drafts; the release job, which has no checkout, only attaches them) | `publish.yml` → `scripts/marketing/release-post.mjs` |
-| Incident radar | Daily 06:00 UTC | One issue per new malware advisory for a popular npm package (max 5 per run); every other new advisory as a comment on one standing batch issue | `incident-radar.yml` → `scripts/marketing/incident-radar.mjs` |
-| Product-led footer | Every report | One line at the end of Markdown reports, audience reports, the PR comment and the evidence bundle README | `src/report/footer.js` |
-| Demo media | Every published release, on demand | A PR with re-rendered GIFs from `assets/tapes/*.tape` | `demo-media.yml` |
-| Monthly stats | 1st of the month, 07:00 UTC | Issue "Penthera this month: <Month YYYY>" with a table, month-over-month changes and a draft post | `monthly-stats.yml` → `scripts/marketing/monthly-stats.mjs` |
-| Contributor flywheel | When an issue closes | If fewer than 3 `good first issue` issues are open: one reminder issue listing `TODO(good-first-issue)` markers | `contributor-flywheel.yml` → `scripts/marketing/contributor-flywheel.mjs` |
-
-### Release post drafts
-
-Built from the CHANGELOG section for the tag: the first sentence of the
-summary paragraph, then three bullets (bold-titled entries first, Added before
-Fixed), then the npm and GitHub release links. The X/Bluesky post is counted
-the way Bluesky counts (every character), which also fits X. Run it locally:
-
-```bash
-node scripts/marketing/release-post.mjs --tag v1.4.0
-```
-
-The npm release is staged, not live, until a maintainer approves it. Post after
-approving.
-
-### Incident radar
-
-Reads `/advisories?type=malware&ecosystem=npm` and `ecosystem=pip` from the
-public GitHub Advisory Database, published in the last 48 hours. About 20
-malware advisories appear every day and most are typosquats nobody installs,
-so by default only advisories for packages in `lib/deps/popular-packages.json`
-get their own issue (with the checklist and a draft "check if you're affected
-with one command" post). The rest go into one standing issue, "Incident radar:
-other new malware advisories", one comment per run. Set `mode: all` on a manual
-run to open one issue per advisory instead (still at most 5).
-
-State is the issues themselves: an advisory counts as seen when its GHSA id is
-in an `incident-radar` issue or a radar batch comment from the look-back
-window. There is no state file or branch.
-
-Each issue's checklist: add the IOCs to a rule pack in `lib/rules/` (or the
-deps rules until rule packs exist), verify `penthera deps` flags a fixture
-lockfile with the package, then post. Do not post before detection is
-verified.
-
-### Product-led footer
-
-Human-readable Markdown ends with:
-
-> Checked by Penthera, open-source security for the apps and AI systems you ship · https://github.com/danoszz/penthera
-
-It is never added to SARIF or JSON. Users turn it off with `--no-footer` (CLI)
-or `footer: "false"` (GitHub Action).
-
-### Demo media
-
-Tapes live in `assets/tapes/` (see its README). The workflow installs
-[VHS](https://github.com/charmbracelet/vhs) with `charmbracelet/vhs-action`,
-renders every tape, uploads the GIFs as a workflow artifact and, unless it is a
-dry run, opens a PR from a `media/*` branch. It needs **Settings → Actions →
-General → Allow GitHub Actions to create and approve pull requests**. PRs
-opened by `GITHUB_TOKEN` do not trigger CI; close and reopen the PR to run it.
-
-### Monthly stats
-
-Public sources only:
-
-- npm downloads for the calendar month (`api.npmjs.org`);
-- stars and forks at run time and PRs merged that month (GitHub API);
-- installs from the public skills.sh skill page;
-- dependent repositories from GitHub's dependents page.
-
-Each page is parsed strictly: if the markup changed, the number shows as
-`n/a`, never a guess. The issue keeps its numbers in a hidden JSON comment,
-and next month's issue reads them back for the change column.
-
-### Contributor flywheel
-
-Write `TODO(good-first-issue): <what to do>` in a comment next to a small,
-well-scoped change. When the open `good first issue` count drops below 3, the
-reminder issue lists these markers with links. Turn one or two into issues,
-then close the reminder. Closing the reminder itself never triggers a new one.
-
-## Dry runs
-
-Every scheduled workflow has a `workflow_dispatch` trigger whose `dry-run`
-input defaults to **on**: it prints what it would open to the job summary and
-writes nothing.
-
-| Workflow | Dry run |
-|----------|---------|
-| Incident radar | Actions → Incident radar → Run workflow (`dry-run` checked; optional `mode`, `since-hours`) |
-| Monthly stats | Actions → Monthly stats → Run workflow (`dry-run` checked; optional `month`, e.g. `2026-09`) |
-| Contributor flywheel | Actions → Contributor flywheel → Run workflow (`dry-run` checked) |
-| Demo media | Actions → Demo media → Run workflow (`dry-run` checked: GIFs as an artifact, no PR) |
-| Release posts | `node scripts/marketing/release-post.mjs --tag vX.Y.Z` locally |
-
-From a terminal with the GitHub CLI:
-
-```bash
-gh workflow run incident-radar.yml -f dry-run=true
-```
-
-The scripts also run locally with `--dry-run` (they use your `gh` login for
-reads only):
-
-```bash
-node scripts/marketing/incident-radar.mjs --repo danoszz/penthera --dry-run
-```
-
-## Turning things off
-
-- **One workflow:** Actions → the workflow → "…" → Disable workflow. Or delete
-  its file.
-- **Release drafts:** remove the "Draft release posts" and "Keep the drafts" steps (publish job) and the two share steps (release job) from `publish.yml`.
-- **Footer, for one run:** `--no-footer` or `footer: "false"` in the Action.
-  To drop it for everyone, make `footerLines()` in `src/report/footer.js`
-  return `[]`.
-- **Labels** (`incident-radar`, `monthly-stats`, `contributor-flywheel`) are
-  created on the first real run and can be deleted afterwards.
-
-## The weekly 30-minute routine
-
-1. **Incident radar (10 min).** Open the `incident-radar` issues. For a
-   popular package: add the IOCs, check `penthera deps` flags a fixture, post
-   the draft (LinkedIn, X, Bluesky), close the issue. Skim the batch issue for
-   names you recognise, then close it if it is long.
-2. **A clip (5 min).** If a demo-media PR is open, watch the GIFs, merge, and
-   post the best one as a short clip (Instagram, LinkedIn, X).
-3. **Contributors (5 min).** If the flywheel reminder is open, turn one or two
-   markers into `good first issue` issues. Reply to new contributors.
-4. **Release (5 min, when there is one).** Approve the staged npm package, then
-   copy the "Share this release" drafts from the GitHub Release, edit, post.
-5. **Monthly (5 min, first week).** Fill in "what shipped" in the stats issue,
-   post it, close it.

package/docs/owasp-wstg-coverage.md

@@ -1,79 +0,0 @@
-# OWASP WSTG coverage map
-
-Penthera maps its probes to the [OWASP Web Security Testing Guide (WSTG) v4.2](https://owasp.org/www-project-web-security-testing-guide/). This document is the canonical reference; scan reports include a summary table generated from `lib/owasp-wstg.js`.
-
-## Coverage by profile
-
-| Profile | Penthera probes | WSTG areas | Destructive payloads |
-|---------|-----------------|------------|----------------------|
-| **quick** | Headers, OpenAPI, auth smoke | INFO, CONF, ATHN | No |
-| **standard** | Full non-destructive black-box + repo | INFO, CONF, CRYP, ATHN, ATHZ, SESS, CLNT | No |
-| **deep** | standard + recon + injections + fuzz | All above + INPV, BUSL | Yes |
-
-## Probe → WSTG mapping
-
-| Penthera probe | WSTG IDs | Profiles | Mode |
-|----------------|----------|----------|------|
-| Reachability & fingerprint | WSTG-INFO-02, WSTG-INFO-04 | quick, standard, deep | URL |
-| Endpoint discovery | WSTG-INFO-06, WSTG-INFO-07 | standard, deep | URL |
-| TLS / certificate audit | WSTG-CRYP-01, WSTG-CRYP-02 | standard, deep | URL |
-| Security headers | WSTG-CONF-12, WSTG-CONF-13, WSTG-CONF-14 | quick, standard, deep | URL |
-| OpenAPI / Swagger exposure | WSTG-INFO-09, WSTG-CONF-02 | quick, standard, deep | URL |
-| Sensitive file templates | WSTG-CONF-02, WSTG-CONF-04 | standard, deep | URL |
-| CORS validation | WSTG-CLNT-07 | standard, deep | URL |
-| Cookie security | WSTG-SESS-02 | standard, deep | URL |
-| Auth endpoint hardening | WSTG-ATHN-03, WSTG-ATHN-10 | quick, standard, deep | URL |
-| Client-side-only auth | WSTG-ATHZ-02, WSTG-CLNT-01 | standard, deep | URL |
-| JWT probes | WSTG-ATHN-04, WSTG-SESS-10 | standard, deep | URL |
-| IDOR / BOLA | WSTG-ATHZ-04, WSTG-ATHZ-05 | standard, deep | URL |
-| OAuth open redirect | WSTG-ATHN-11, WSTG-CLNT-04 | standard, deep | URL |
-| Retire.js (JS CVEs) | WSTG-CONF-04, WSTG-CLNT-02 | standard, deep | URL |
-| Parameter discovery | WSTG-INFO-06 | standard, deep | URL |
-| OSINT recon | WSTG-INFO-01, WSTG-INFO-07 | deep | URL |
-| SQL injection | WSTG-INPV-05 | deep | URL |
-| SSTI | WSTG-INPV-18 | deep | URL |
-| SSRF | WSTG-INPV-19 | deep | URL |
-| Reflected XSS | WSTG-INPV-01, WSTG-CLNT-01 | deep | URL |
-| Command injection | WSTG-INPV-12 | deep | URL |
-| Open redirect (injection suite) | WSTG-CLNT-04 | deep | URL |
-| API fuzzing | WSTG-INPV-11, WSTG-BUSL-05 | deep | URL |
-| Secret scanning | WSTG-CONF-02, WSTG-CONF-05 | quick, standard, deep | Repo |
-| Route / trust-boundary analysis | WSTG-ATHZ-02, WSTG-CONF-02 | quick, standard, deep | Repo |
-| Risky code patterns | WSTG-INPV-01, WSTG-INPV-12 | standard, deep | Repo |
-
-## WSTG categories not covered (yet)
-
-Penthera does **not** currently automate these WSTG areas:
-
-| Category | Examples | Planned |
-|----------|----------|---------|
-| WSTG-IDNT | Registration, username policy | v0.4 |
-| WSTG-ERRH | Verbose stack traces in all contexts | Partial (template scans) |
-| WSTG-BUSL | Full business-logic workflows | Partial (fuzz only) |
-| WSTG-APIT | GraphQL-specific tests | v0.4 |
-| Manual / social | Phishing, physical access | Out of scope |
-
-## Finding category → WSTG
-
-When a finding is reported, Penthera tags it with relevant WSTG IDs in JSON (`finding.wstg[]`), SARIF (`properties.tags`), and Markdown reports.
-
-| Finding category | WSTG IDs |
-|------------------|----------|
-| `tls` | WSTG-CRYP-01, WSTG-CRYP-02 |
-| `exposure` | WSTG-CONF-02, WSTG-CONF-04 |
-| `cors` | WSTG-CLNT-07 |
-| `cookie` | WSTG-SESS-02 |
-| `auth` | WSTG-ATHN-03, WSTG-ATHN-04 |
-| `secrets` | WSTG-CONF-02, WSTG-CONF-05 |
-| `sqli` | WSTG-INPV-05 |
-| `xss` | WSTG-INPV-01, WSTG-CLNT-01 |
-| `ssrf` | WSTG-INPV-19 |
-| `cmdi` | WSTG-INPV-12 |
-| `open-redirect` | WSTG-CLNT-04, WSTG-ATHN-11 |
-| `rate-limiting` | WSTG-ATHN-10 |
-
-## References
-
-- [OWASP WSTG on GitHub](https://github.com/OWASP/wstg)
-- Penthera implementation: `lib/owasp-wstg.js`
-- Report integration: `src/report/markdown.js`, `src/reporter.js`

package/docs/plan.md

@@ -1,102 +0,0 @@
-# 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 | Tagged with the pre-commit hook, license policy, CRA helper and AI-BOM; held back from npm and shipped inside 1.6.0 |
-| v1.6.0 | Hardening and the rest of AI apps | Released with the 360 security review fixes, Python `deps`, the internal audit gate and the dashboard. Signed rule packs follow once the maintainer's key is set up |
-| v1.7.0 | One view, one command | The single-view dashboard, the `npx penthera` setup wizard, and an APA-cited methodology. Released |
-| Next | Before you deploy | `penthera ship` and preview-deployment scanning work on a real Vercel and Netlify project |
-| After that | 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.

package/docs/privacy.md

@@ -1,38 +0,0 @@
-# Privacy and network use
-
-Penthera has no telemetry. It does not collect, store, or transmit any usage data, analytics, or personal information to the author or any third party. It does not phone home.
-
-- **Scan traffic goes to the target you specify.** Auth tokens passed via `--auth-bearer`, `--auth-cookie`, or `PENTHERA_*` env vars are sent only to that target.
-- **Every request identifies itself** as `penthera/<version> (+https://github.com/danoszz/penthera)`, so a target's operator can tell where the traffic comes from. Override it with `--user-agent`.
-- **Reports stay local.** Output is written to `reports/` (gitignored) on your machine.
-- **Every scan lists the third-party hosts it contacted** besides the target, in the terminal summary and in the report's "Network egress" section.
-
-Without `--offline`, a scan may contact these third parties:
-
-| Host | When | What it learns |
-|---|---|---|
-| `raw.githubusercontent.com`, `cdn.jsdelivr.net` | Retire.js check (standard and deep profiles) | That someone downloaded the public database. Nothing about your target. |
-| `crt.sh`, `web.archive.org`, `otx.alienvault.com` | `--recon` only | The target domain. |
-| CDN hosts serving your page's `<script src>` | Retire.js check, when a script's version can only be read from its contents | That someone fetched that public script. |
-
-### Fully local: `--offline`
-
-```bash
-penthera http://localhost:3000 --offline
-```
-
-With `--offline`, the HTTP client refuses every host except the scan target. A redirect may only move to a host on the target's registrable domain (`example.com` to `www.example.com`). In practice:
-
-- **Recon is skipped.** No queries go to crt.sh, the Wayback Machine or OTX.
-- **The Retire.js database comes from the snapshot vendored in the package** (`lib/data/retire-jsrepository.json.gz`), refreshed at each release by `scripts/refresh-retire-db.mjs`. The source URL, fetch date and SHA-256 sit next to it in `retire-jsrepository.meta.json`, so you can check it against upstream. Online scans fall back to the snapshot too when the live download fails.
-- **Third-party scripts are not fetched.** A refused request is listed in the report as an inconclusive probe, not passed over silently.
-- **`--suppliers` is refused**, because it rates third-party domains.
-- **DNS:** reaching a remote target needs DNS. For non-local targets, the email-authentication check also looks up the target domain's SPF/DMARC/MX records through your system resolver. A `localhost` or IP target needs no DNS at all.
-
-Penthera never fetches rules or code at runtime: templates, wordlists and the vulnerability database ship in the package.
-
-### Inconclusive probes
-
-When a probe's requests time out, fail, or are refused by `--offline`, the scan records `{ probe, url, message }` in `result.errors`. The terminal summary shows "N probes inconclusive", and the Markdown report lists each one. A probe that could not run is not a clean result.
-
-You are responsible for ensuring you are authorized to scan any target. See [Ethical use](../README.md#ethical-use--authorization).