penthera 1.4.0 → 1.6.0

package/docs/evidence.md

@@ -14,7 +14,7 @@ organisation through a channel other than the bundle itself (their security
 page, an email you can authenticate, or in person).
 
 ```bash
-npx penthera evidence verify ./evidence --allowed-signers allowed_signers
+npx penthera evidence verify ./evidence --allowed-signers allowed_signers --require-signature
 ```
 
 Exit code `0` means every file matches the manifest and the manifest was signed
@@ -55,9 +55,13 @@ symlinked files.
   manifest. It does not prove that the scan was run against the system you
   care about, or with the options you expect. Read the manifest's `command`,
   `target`, `scan` and `git` fields, and the auditor report's scope section.
-- Without `--allowed-signers`, `verify` still checks that the signature is
-  valid but cannot tell you whose key made it. It reports
-  `valid-unknown-signer` as a warning.
+- A signed bundle only verifies with `--allowed-signers`. Without it,
+  `verify` cannot tell whose key made the signature (anyone can re-sign a
+  rewritten manifest with their own key), so it fails with status
+  `unverified`. A manifest that declares a signature with no `.sig` file
+  fails too.
+- An unsigned bundle passes with an `UNSIGNED` warning. Pass
+  `--require-signature` (with `--allowed-signers`) to make it fail.
 - A scan is a snapshot. The bundle is evidence of what Penthera saw at
   `generated_at`, not a statement that the system is secure.
 

package/docs/examples/github-actions-deps.yml

@@ -35,18 +35,18 @@ jobs:
     env:
       PENTHERA_VERSION: latest # pin, e.g. 1.3.0
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           path: head
           persist-credentials: false
 
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.base.sha }}
           path: base
           persist-credentials: false
 
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
         with:
           node-version: 22
 
@@ -89,7 +89,7 @@ jobs:
             gh pr comment "$PR" --repo "$REPO" --body-file "$body"
           fi
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         if: always()
         with:
           name: penthera-deps

package/docs/examples/github-actions-scan.yml

@@ -24,7 +24,7 @@ jobs:
       contents: read
       security-events: write
     steps:
-      - uses: actions/setup-node@v6
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
         with:
           node-version: 22
 
@@ -34,7 +34,7 @@ jobs:
         run: |
           mkdir -p reports
           set +e
-          npx --yes penthera@1.4.0 "$PENTEST_URL" \
+          npx --yes penthera@1.6.0 "$PENTEST_URL" \
             --profile standard \
             -o reports/scan.json \
             --sarif reports/scan.sarif
@@ -43,12 +43,12 @@ jobs:
           # Exit 1 = critical or high findings (reported via SARIF); only 2 (scan error) fails the job.
           if [ "$code" -eq 2 ]; then exit 2; fi
 
-      - uses: github/codeql-action/upload-sarif@v4
+      - uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
         if: always()
         with:
           sarif_file: reports/scan.sarif
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
         if: always()
         with:
           name: penthera-reports

package/docs/index.md

@@ -1,6 +1,6 @@
 # Penthera documentation
 
-The routine work of a security team, on your own machine: app scanning, dependency and install checks, an AI-tooling audit, a local fix loop, and auditor-grade reports. Offline, deterministic, free.
+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
 
@@ -8,8 +8,11 @@ The routine work of a security team, on your own machine: app scanning, dependen
 |-------|-------------|
 | [README](../README.md) | Install, quick start, ethical use |
 | [Run it](../README.md#run-it) | Install + first-time wizard (`penthera` with no args) |
+| [Use cases](./use-cases/README.md) | By situation: [before launch](./use-cases/solo-founder.md), [AI-coding teams](./use-cases/ai-coding-teams.md), [maintainers](./use-cases/open-source-maintainers.md), [EU SMEs](./use-cases/eu-sme-compliance.md), [agencies](./use-cases/agencies.md) |
+| [Comparisons](./compare/README.md) | Using Penthera with [Socket](./compare/socket.md), [Snyk](./compare/snyk.md), [GitHub](./compare/github.md), [ZAP](./compare/zap.md), [Semgrep](./compare/semgrep.md) |
+| [Commands](./commands/README.md) | One page per command: [scan](./commands/scan.md), [agents](./commands/agents.md), [deps](./commands/deps.md), [install](./commands/install.md), [fix](./commands/fix.md), [hook](./commands/hook.md), [action](./commands/action.md), [skill](./commands/skill.md) |
 | [CHANGELOG](../CHANGELOG.md) | Version history |
-| [Roadmap](../ROADMAP.md) and [release plan](./release-plan.md) | What ships next, in what order |
+| [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
 
@@ -36,6 +39,10 @@ The routine work of a security team, on your own machine: app scanning, dependen
 | 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) |
+| CRA reporting and AI-BOM | [compliance-cra.md](./compliance-cra.md) |
+| Reports and evidence bundles | [evidence.md](./evidence.md) |
+| Privacy, network use, `--offline` | [privacy.md](./privacy.md) |
+| Local dashboard (`penthera ui`) | [dashboard.md](./dashboard.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` |
@@ -48,6 +55,8 @@ The routine work of a security team, on your own machine: app scanning, dependen
 | 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) |
+| Refresh the README's numbers | `npm run docs:numbers` (`-- --tests` to count tests) |
+| How Socket positions itself, and what Penthera took from it | [research/socket-positioning-notes.md](./research/socket-positioning-notes.md) |
 
 ## Agent skill
 

package/docs/internal-audit.md

@@ -0,0 +1,83 @@
+# Internal testing audit
+
+Penthera is a security tool, so its own release bar has to be easy to check.
+The internal audit is that bar: one command that runs every check a release
+needs and writes the result to [`audit/REPORT.md`](../audit/REPORT.md).
+
+```bash
+npm run audit:internal
+```
+
+It exits 1 if any gate fails. A release is only tagged from a commit whose
+audit passed (see the release checklist in
+[CONTRIBUTING.md](../CONTRIBUTING.md#cutting-a-release)). The same audit runs
+every Monday in CI ([`internal-audit.yml`](../.github/workflows/internal-audit.yml))
+so drift shows up between releases.
+
+## The gates
+
+| Gate | What it checks | Fails when |
+|---|---|---|
+| Test suite | `npm test`, with the live suites pointed at the bundled mock server (`PENTEST_BASE_URL`) | Any test fails |
+| Benchmark | `npm run bench` (offline, seeded) against the **Total** row of the committed [`bench/RESULTS.md`](../bench/RESULTS.md) | Precision or recall drops by more than 0.02, or any request leaves loopback |
+| Self-scan | `penthera --repo .`, `penthera agents .`, `penthera deps .`, and `penthera hook run` on a copy of the tree with every file staged | A high or critical finding is not in [`audit/baseline.json`](../audit/baseline.json), or a baseline entry has no reason |
+| CLI smoke | `--help` for every subcommand, plus a fixture run of each: a mock-server scan in every report format, `agents` on a clean and a malicious fixture, `deps`, `install --dry-run`, `fix --plan`, an evidence bundle and its `verify`, one `agent --loop` iteration (every diff declined), `hook install/uninstall` and `memory show/verify` | Any command exits with an unexpected code or produces the wrong output |
+| Packaging | `npm pack --dry-run` | A file outside the allow-list ships, anything that looks like tests, fixtures, reports or secrets ships, or the package exceeds its size budget |
+| Offline | A full `--all --adaptive --offline` scan of the mock server | The report's `egress` field shows any third-party host |
+| Supply chain | `npm audit --omit=dev`; sha512 integrity for every lockfile entry; install scripts in runtime dependencies (via `penthera deps --prod`); every `uses:` in `.github/workflows`, `action.yml` and `docs/examples` | Any vulnerability, missing integrity, runtime install script, typosquat, action not pinned by commit SHA, or workflow without top-level `permissions:` |
+| Versions and docs | The version in `package.json`, the lockfile, the plugin manifests, `SKILL.md` and `CITATION.cff`; a `CHANGELOG.md` section for it; every relative link in `README.md` and `docs/` | Any mismatch or broken link |
+
+Everything runs on this machine against this repo or `127.0.0.1`. The only
+network use is `npm audit` (the npm registry) and, with `--with-docker`,
+pulling the Juice Shop image.
+
+## Options
+
+| Flag | Effect |
+|---|---|
+| `--only bench,versions-docs` | Run some gates (ids: `tests`, `bench`, `self-scan`, `smoke`, `packaging`, `offline`, `supply-chain`, `versions-docs`, `docker`). Prints results and writes nothing. |
+| `--update-baseline` | Rewrite `audit/baseline.json` from this run's self-scan. New entries get a `TODO` reason, which fails the gate until a person writes one. |
+| `--with-docker` | Add the optional heavier targets below. |
+| `--no-write` | Leave `audit/` untouched. |
+
+Command output from each run goes to `audit/logs/` (ignored by git, uploaded
+with the report as the CI artifact).
+
+## Optional targets: Juice Shop and crAPI
+
+`--with-docker` starts [OWASP Juice Shop](https://github.com/juice-shop/juice-shop)
+on `127.0.0.1:3300`, scans it with the benchmark's `juice-shop` target, and
+removes the container. Pin the image for reproducible numbers with
+`JUICE_SHOP_IMAGE=bkimminich/juice-shop@sha256:...`.
+
+[OWASP crAPI](https://github.com/OWASP/crAPI) needs its own Docker Compose
+stack, so the audit scans it only if it is already running at `CRAPI_URL`
+(default `http://127.0.0.1:8888`). Start it with the project's compose file
+first.
+
+Both are skipped by default. Neither has labelled ground truth yet, so the
+report lists their finding counts and shows precision and recall as
+"unlabelled" until they are labelled in `bench/ground-truth.json` (see
+[bench/README.md](../bench/README.md#optional-targets)).
+
+## When a gate fails
+
+- **Tests, smoke, offline, packaging, supply chain, versions:** fix the cause.
+  These describe what Penthera promises its users.
+- **Benchmark:** if the change is intended (a new rule that trades a little
+  precision for recall, a relabelled target), run `npm run bench`, commit the
+  new `bench/RESULTS.md`, and say why in the PR.
+- **Self-scan:** fix the finding. If it is a deliberate fixture, run
+  `--update-baseline` and replace the `TODO` with the reason, so the
+  acceptance is reviewed like any other change.
+
+Thresholds (the 0.02 benchmark drop, the package size budget, the allow-list)
+live at the top of [`scripts/audit/run.mjs`](../scripts/audit/run.mjs).
+Change them in their own PR, never to make a release pass.
+
+## The report
+
+`audit/REPORT.md` has a pass/fail table with the numbers behind each gate,
+the changes since the previous report (read from a data block at the end of
+the previous file), and per-gate details. Commit it with each release so the
+history of the gate lives in git.

package/docs/marketing.md

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

@@ -0,0 +1,101 @@
+# 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 | Before you deploy | `penthera ship` and preview-deployment scanning work on a real Vercel and Netlify project |
+| v1.8.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.

package/docs/privacy.md

@@ -0,0 +1,38 @@
+# 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).

package/docs/references.bib

@@ -537,3 +537,13 @@
   urldate      = {2026-10-19},
   note         = {standards}
 }
+
+@misc{spdxlicenselist,
+  shorthand    = {SPDX License List},
+  author       = {{SPDX Workgroup, The Linux Foundation}},
+  title        = {{SPDX} License List},
+  howpublished = {Standardized short identifiers for open source licenses, used by package manifests and SBOMs},
+  url          = {https://spdx.org/licenses/},
+  urldate      = {2026-10-19},
+  note         = {standards}
+}

package/docs/references.md

@@ -75,3 +75,4 @@ Every entry was checked against the publisher or standards body (Crossref DOI me
 - `oasis2023sarif`: Fanning, Michael C.; Golding, Laurence J. (2023). *Static Analysis Results Interchange Format (SARIF) Version 2.1.0 Plus Errata 01*. OASIS Standard incorporating Approved Errata, 28 August 2023. <https://docs.oasis-open.org/sarif/sarif/v2.1.0/errata01/os/sarif-v2.1.0-errata01-os-complete.html>
 - `eu2022nis2`: European Parliament; Council of the European Union (2022). *Directive (EU) 2022/2555 of the European Parliament and of the Council of 14 December 2022 on measures for a high common level of cybersecurity across the Union, amending Regulation (EU) No 910/2014 and Directive (EU) 2018/1972, and repealing Directive (EU) 2016/1148 (NIS 2 Directive)*. Official Journal of the European Union, L 333, 27.12.2022, p. 80. <https://eur-lex.europa.eu/eli/dir/2022/2555/oj>
 - `mitrecwe`: The MITRE Corporation. *CWE: Common Weakness Enumeration*. Community-developed list of software and hardware weakness types, sponsored by CISA. <https://cwe.mitre.org/>
+- `spdxlicenselist`: SPDX Workgroup, The Linux Foundation. *SPDX License List*. Standardized short identifiers for open source licenses, used by package manifests and SBOMs. <https://spdx.org/licenses/>