GitHub - danoszz/penthera: Lightweight website/app cyber security scanner:: run it from your AI agent (Cursor/Claude Code) or the CLI. Black-box + white-box, OWASP-mapped, SARIF-ready. Authorized testing only.

Penthera, a security scanner for Claude, Cursor and CLI

Penthera running an interactive security scan in the terminal

Two ways to use it

As an Agent Skill (recommended). Most people start here. Let Cursor or Claude Code drive it: install once, then ask it to "scan my app for security issues." The agent picks the scan, runs it, and gives you the fixes.

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

Why Penthera

You shipped something fast: vibecoded, AI-assisted, already live. The same models that helped you build it also make it easy for someone to probe it. Exposed API routes, missing security headers, weak auth, a hardcoded key in the repo. These are the common mistakes that get apps broken into.

Penthera is the check you run before you launch. Ask your agent to "scan my app for security issues" and it runs an authorized, non-destructive scan, then lists the top fixes in priority order. You do not need a DAST suite or a security background to use it.

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. Offline, no accounts. 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.

What it does

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

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

How it works

flowchart LR
    U["You / your AI agent"] -->|scan request| P((Penthera))

    P --> BB["Black-box<br/>TLS, headers, CORS<br/>endpoint + OpenAPI discovery<br/>JWT, auth, IDOR/OAuth<br/>injection, fuzzing"]
    P --> WB["White-box<br/>API routes<br/>secret scanning<br/>trust boundaries"]
    P --> MA["Machine audit<br/>(macOS)"]

    BB --> F[["Findings<br/>scored by severity"]]
    WB --> F
    MA --> F

    F --> T["Terminal summary<br/>+ top 3 fixes"]
    F --> MD["Markdown report"]
    F --> J["JSON"]
    F --> S["SARIF to GitHub Security"]

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

Compliance: NIS2 and the cyberwetgeving

The EU NIS2 directive and its national transpositions (the Cyberbeveiligingswet in the Netherlands, the NIS2-wet in Belgium) put a duty of care, the zorgplicht, on in-scope organisations. That duty is the set of risk-management measures in Article 21(2) of the directive. Most of them are organisational. Some are technical and testable, and that is the part Penthera helps with.

Penthera does not make you compliant and does not certify anything. What it gives you is automated, repeatable technical evidence for the measures a scanner can honestly verify: the kind of artefact you can attach to a risk file, show an auditor, or run in CI so a regression shows up before it ships.

Art. 21(2) measure	What Penthera does	Coverage
(a) Risk analysis & information-security policy	Findings, severity, and baseline history feed your risk analysis	Evidence
(b) Incident handling	`--incident` drafts the 24h / 72h / 1-month reports against your authority's required content	Partial
(c) Business continuity, backup, crisis management	Organisational; outside a scanner's reach	Out of scope
(d) Supply-chain security	Known-CVE checks on JS dependencies, leaked credentials, a CycloneDX SBOM (`--sbom`), and passive supplier rating (`--suppliers`)	Partial
(e) Security in acquisition, development & maintenance; vulnerability handling	The core: black- + white-box scanning mapped to OWASP WSTG, SARIF → GitHub, baseline regression, scan-and-fix loop	Strong
(f) Assessing the effectiveness of measures	Baseline diff, re-scan-to-verify, and `--history` tracking of time-to-fix, ageing, and drift	Partial
(g) Cyber hygiene & training	Remediation playbook + secure-defaults guidance (guidance, not a training programme)	Partial
(h) Cryptography & encryption	TLS protocol/cipher/certificate audit, HSTS, cookie `Secure` (transport layer only)	Partial
(i) HR security, access control, asset management	Access control tested: JWT, IDOR/BOLA, OAuth redirect, client-side-auth, trust-boundary mapping	Partial
(j) Multi-factor authentication & secure communications	MFA probe (on the roadmap)	Planned

Coverage key: Strong = automated technical testing · Partial = part of the measure · Evidence = output feeds the measure, no direct test · Planned = on the roadmap · Out of scope = organisational or physical.

In practice, Penthera today gives you solid automated evidence for the secure-development and vulnerability-handling duty (e), which is the technical heart of the zorgplicht, plus meaningful coverage of supply chain (d), cryptography in transit (h), access control (i), and effectiveness testing (f). That is not the whole duty of care, but it is a real, defensible start you can run today and re-run on every deploy.

Not legal advice, not a certification, not a guarantee of compliance. Penthera automates the technical-testing part of the duty of care. The directive's organisational duties (governance, risk-management policy, incident-notification processes, supply-chain contracts, staff training) need human process and, where it matters, review by a qualified advisor. For an authoritative reading, consult your national authority (the NCSC in the Netherlands, the CCB and its CyFun framework in Belgium) or a specialised jurist.

Generate this mapping for your own scan with --framework nis2. It adds a per-run coverage table (which measures this scan actually exercised, driven by the probes that ran) to the terminal, Markdown, and JSON reports:

penthera https://myapp.com --framework nis2 -o reports/scan.json

Readiness report (clone → report in two commands)

Go further than the mapping: combine the scan with a short offline self-assessment (the organisational measures a scanner can't test, like policies, backups, training, and MFA) into a full NIS2 readiness report. Every Article 21 measure is marked met / partial / gap / n-a, with proportionality notes, your incident-reporting deadlines, and provenance on every piece of evidence.

# 1. Create your self-assessment (offline, one-time). Fill in yes | partial | no | na.
penthera --assessment-init assessment.json

# 2. Scan + self-assessment → readiness report (writes reports/scan-readiness.md)
penthera https://myapp.com --repo . --readiness --assessment assessment.json -o reports/scan.json

The readiness report is evidence and self-assessment tooling, not a certification. It is provenance-linked (source, method, collected_at, confidence) and reproducible, and it lists exactly what only you can attest to. Jurisdiction specifics live in lib/jurisdictions/nl.json (NL today; BE and others are just added config).

Answer a customer's security questionnaire

The questionnaire blocking your deal, drafted from evidence you already have:

# one question per line, pasted from the customer's form
penthera https://myapp.com --readiness --assessment assessment.json --questionnaire questions.txt

Each question is mapped to the Article 21 measure it belongs to and answered from the scan and your self-assessment, with the backing evidence cited. Anything Penthera can't map is marked NEEDS HUMAN INPUT instead of guessed. Review every answer before you send it.

Policy pack

Generate the proportionate written policies NIS2 expects, pre-filled from your readiness gaps and the NL incident deadlines:

penthera --policy-pack ./policies --org "Your Company" --readiness --assessment assessment.json

Writes editable Markdown starting points: information security, access control, incident response, backup/continuity, acceptable use, supplier security, and vulnerability management. Templates, not legal advice. Keep them short and used. A two-page policy that genuinely exists is what "proportionate" means.

Incident-report helper

NIS2 has hard reporting deadlines (24h early warning, 72h notification, 1-month final report). If something happens, get the timeline and draft reports:

penthera --incident-init incident.json   # fill in what happened (set aware_at)
penthera --incident incident.json        # writes incident-reports.md

It computes your three deadlines from when you became aware, flags anything overdue, and drafts the early-warning, notification, and final report against the required content, with NEEDS INPUT where you still have to fill in facts. These are drafts to help you meet the deadlines, not a substitute for your authority's official form.

Software bill of materials (SBOM)

Emit a standard CycloneDX SBOM of your dependencies. It's what enterprises increasingly require of suppliers, and direct evidence for supply-chain security (measure d):

penthera --repo . --sbom sbom.cdx.json

Parses package-lock.json / package.json / requirements.txt offline (no network), with resolved versions and package URLs (purls).

Remediation tracking (the audit loop)

Closing findings matters more than finding them. Track them over time: time-to-fix, ageing of open items, and what changed since the last scan (evidence for measure f, effectiveness):

penthera https://myapp.com --history reports/history.json -o reports/scan.json

Each run folds the current findings into a small history keyed by a stable fingerprint (so a re-worded or re-counted finding isn't mistaken for a new one), then reports open vs resolved, median time-to-fix, and ageing buckets. Re-run on a cadence to watch the trend.

Supplier rating (passive)

Assess your suppliers' public security posture for supply-chain risk (measure d):

printf 'supplier1.com\nsupplier2.com\n' > suppliers.txt
penthera --suppliers suppliers.txt

Strictly passive and public-data-only. One homepage GET (security headers), a TLS handshake (certificate), and public DNS lookups (SPF/DMARC/MX) per domain. No endpoint discovery, no auth probes, no intrusive testing. You get a red/amber/green rating per supplier. It's a screening aid for your own vendor risk assessment, not an authorised penetration test of the supplier.

Because the mapping targets the NIS2 directive itself, it applies across the national transpositions; jurisdiction-specific profiles (NL, BE) are on the roadmap.

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.

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.

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 18+ 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

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

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

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"

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.

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.

CI integration

# Scan a staging URL on a schedule and upload results to GitHub Security.
# Set the PENTEST_STAGING_URL secret to enable. Full example: .github/workflows/scan.yml
- run: npx penthera "$PENTEST_URL" --profile standard --sarif reports/scan.sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: reports/scan.sarif

The repo's own CI (.github/workflows/ci.yml) runs the offline suites on Node 18, 20, and 22, and self-scans a mock vulnerable API on every push.

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

Status

v1.0, production-ready. URL, repo, and machine scanning, scan profiles, Markdown, JSON, and SARIF reports, session-aware auth, JWT, IDOR, OAuth, and header probes, adaptive knowledge-graph probing, a plugins and templates API, Docker, CI, and the Agent Skill are all shipped. See the CHANGELOG for the full history.

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 funds new probes, broader framework coverage, and keeping the suite current with new attack patterns. Thank you.

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 only to the target you specify. Auth tokens passed via --auth-bearer, --auth-cookie, or PENTHERA_* env vars are sent only to that target.
Reports stay local. Output is written to reports/ (gitignored) on your machine.
JS vulnerability checks download a public database (Retire.js) from GitHub to compare your app's libraries against known CVEs locally. No details about your target are sent.
Recon mode (--recon) queries public OSINT sources (crt.sh, web.archive.org, AlienVault OTX) with the target domain to find subdomains and historical URLs. This shares the target domain with those third-party services. Omit --recon to avoid it.

You are responsible for ensuring you are authorized to scan any target. See Ethical use.

License & disclosure

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

Name		Name	Last commit message	Last commit date
.claude-plugin		.claude-plugin
.cursor/skills		.cursor/skills
.github		.github
assets		assets
bin		bin
docs		docs
lib		lib
scripts		scripts
skills/penthera		skills/penthera
src		src
tests		tests
.dockerignore		.dockerignore
.gitignore		.gitignore
.nvmrc		.nvmrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
install.sh		install.sh
package-lock.json		package-lock.json
package.json		package.json
pentest.config.example.js		pentest.config.example.js
vitest.config.mjs		vitest.config.mjs

Navigation Menu

Uh oh!

Repository files navigation

Two ways to use it

Why Penthera

What you get

Run it

What it does

How it works

Compliance: NIS2 and the cyberwetgeving

Readiness report (clone → report in two commands)

Answer a customer's security questionnaire

Policy pack

Incident-report helper

Software bill of materials (SBOM)

Remediation tracking (the audit loop)

Supplier rating (passive)

Ethical use & authorization

Disclaimer

Install

Quick start

Exit codes

Output

For your AI coding agent

Scan and fix

CI integration

Configuration

Testing & contributing

Status

Support Penthera

Privacy

License & disclosure

About

Releases

Sponsor this project

Packages

Used by

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

Two ways to use it

Why Penthera

What you get

Run it

What it does

How it works

Compliance: NIS2 and the cyberwetgeving

Readiness report (clone → report in two commands)

Answer a customer's security questionnaire

Policy pack

Incident-report helper

Software bill of materials (SBOM)

Remediation tracking (the audit loop)

Supplier rating (passive)

Ethical use & authorization

Disclaimer

Install

Quick start

Exit codes

Output

For your AI coding agent

Scan and fix

CI integration

Configuration

Testing & contributing

Status

Support Penthera

Privacy

License & disclosure

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Sponsor this project

Packages

Used by

Contributors

Languages