penthera 1.4.0 → 1.6.0

package/docs/research/socket-positioning-notes.md

@@ -0,0 +1,183 @@
+# How Socket positions itself: notes for Penthera's docs
+
+*Read on 2026-10-19. Everything below is paraphrased; the few quoted words are
+marked. Socket's pages change often, so treat numbers as a snapshot.*
+
+[Socket](https://socket.dev) is a well-funded supply-chain security company and
+one of the clearest communicators in the field. These notes look at how it
+explains itself, so Penthera can learn from the craft without copying the claims
+or picking a fight. Penthera is a complement to Socket, not a rival: Socket
+watches the registries from the cloud; Penthera checks your app and your machine
+offline.
+
+## 1. The headline promise
+
+- The hero line is about securing software at "AI speed", with a sub-line that
+  promises to stop malicious packages before they reach your code
+  ([home](https://socket.dev/)). The tab title frames it as blocking zero-day
+  supply-chain attacks.
+- The core argument is one contrast, repeated on nearly every page: a CVE
+  database lists accidental vulnerabilities after disclosure, while a malicious
+  package is intentional and has to be stopped before install. Socket claims the
+  second half that CVE scanners miss
+  ([features](https://socket.dev/features),
+  [supply-chain attack prevention](https://socket.dev/use-case/supply-chain-attack-prevention)).
+- AI is the urgency: coding agents pull in dependencies faster than people can
+  review them, so the attack surface grows
+  ([features](https://socket.dev/features), [Series C post](https://socket.dev/blog/series-c)).
+- A speed claim backs the promise: malicious packages flagged within minutes of
+  publication ([home](https://socket.dev/)).
+
+**Takeaway.** One sentence of promise, one contrast that explains why existing
+tools are not enough, and one reason it matters now. Penthera's equivalent: one
+promise (check, vet, keep watching, on your machine), one contrast (rules you can
+read versus a verdict from a service), and the same "now" (AI writes the code and
+picks the packages).
+
+## 2. Who they sell to
+
+- **Buyers are security leaders.** The case-study quotes come from a CISO
+  (Anthropic), a head of security (Vercel), senior security engineers (MetaMask,
+  Drata) ([customers](https://socket.dev/customers)).
+- **Developers are the way in.** The free GitHub app, the CLI and the `sfw`
+  firewall are the self-serve entry points, and comparison pages carry a wall of
+  developer tweets ([vs Snyk](https://socket.dev/compare/socket-vs-snyk)).
+- **AI-native companies** are named prominently: Anthropic, Cursor, Replit,
+  Vercel and others ([Series C post](https://socket.dev/blog/series-c)).
+- **Credibility from the team**: the founders present themselves as open-source
+  maintainers whose packages are downloaded at very large scale
+  ([FAQ](https://socket.dev/faq)).
+- **Pricing** is per developer seat ([pricing](https://socket.dev/pricing)):
+  a free plan for one seat with 1,000 scans a month and a lot included (GitHub
+  app, AI analysis, MCP server, install firewall); Team at $25 a seat a month
+  with a 5-seat minimum (adds reachability); Business at $50 with a 20-seat
+  minimum (adds SBOM, SSO, AI-model and Actions scanning); Enterprise on quote
+  (adds self-hosting options, other SCMs, and SAST, secrets and container scanning
+  under "Socket Basics").
+- **Open source**: public OSI-licensed projects can get the Business plan free
+  as of August 2026
+  ([announcement](https://socket.dev/blog/free-business-plan-upgrades-for-open-source)).
+  The pricing page still mentions the older free Team offer.
+
+**Takeaway.** Socket speaks to the person who signs off and lets the developer
+install it. Penthera has no buyer. Its audiences are people doing the work with
+no security team behind them: a founder before launch, a team adopting coding
+agents, a maintainer, a small EU company, an agency. So Penthera's use-case pages
+are organised by situation, not by job title.
+
+## 3. How use cases and comparisons are structured
+
+**Comparison pages** ([Snyk](https://socket.dev/compare/socket-vs-snyk),
+[Dependabot](https://socket.dev/compare/socket-vs-dependabot),
+[Semgrep](https://socket.dev/compare/socket-vs-semgrep)) share one template:
+
+1. "Socket vs X" with a benefit subtitle.
+2. Two paragraphs placing the competitor in the "known vulnerabilities only" box.
+3. Install and contact-sales buttons.
+4. A feature table of 8 or 9 rows with checks and dashes.
+5. A second row of buttons, then a tweet wall, then a footer call to action.
+
+They concede little. Snyk gets checks for known vulnerabilities, licence
+enforcement and an API; Dependabot only for known vulnerabilities. Categories
+where the competitor is stronger (SAST depth, containers, IaC, DAST) do not
+appear. There are no prices, benchmarks or third-party sources in the tables.
+
+**Use-case pages** ([open source](https://socket.dev/use-case/open-source-security),
+[SCA](https://socket.dev/use-case/sca),
+[supply-chain attack prevention](https://socket.dev/use-case/supply-chain-attack-prevention))
+mix an SEO definition ("what is SCA"), a problem framing, a feature checklist and
+a live feed of recently blocked packages. The feed is the most persuasive
+element: it shows the product working today.
+
+There is no standalone "Why Socket" page; it is a menu that groups the case
+studies and comparisons. The closest page is
+[features](https://socket.dev/features).
+
+**Takeaway.** Copy the shape (one page per audience, one per alternative, a
+table that is quick to scan), not the tone. Penthera's comparison pages say
+"use together", name where the other tool goes further, link every claim to the
+vendor's own docs, and carry a last-checked date. That honesty is the
+differentiator Penthera can afford and a funded vendor often cannot.
+
+## 4. How they use proof
+
+- **Big numbers** on the home page: about 11.6 million commits secured a month, 1.5 million repositories, 27,000
+  organisations, 10,000 attacks blocked a week ([home](https://socket.dev/)).
+  The same metric differs across pages (risk signals: 70, 80 or 85; unique threat
+  detections: 26,000 on [features](https://socket.dev/features) versus 300,000 on
+  the home page).
+- **Logos and case studies.** The strongest one, Anthropic, gives an outcome:
+  most dependency reviews automated and hours saved each week per engineer
+  ([Anthropic](https://socket.dev/case-study/anthropic)). Vercel and Drata
+  describe workflow and hygiene rather than numbers
+  ([Vercel](https://socket.dev/case-study/vercel), [Drata](https://socket.dev/case-study/drata)).
+  MetaMask's engineer says openly that some false positives are an acceptable
+  price for early warning ([MetaMask](https://socket.dev/case-study/metamask)).
+  The Replit story was not retrievable (HTTP 403); its index card is about
+  reducing false positives.
+- **Funding and badges**: total raised, a $1 billion valuation, SOC 2 Type 2, a
+  Fortune list, and an OpenAI early-access programme
+  ([home](https://socket.dev/), [Series C post](https://socket.dev/blog/series-c)).
+- **Research as proof**: threat write-ups with timestamps showing when the AI
+  scanner flagged an attack, plus downloadable indicators
+  ([Rust crates post](https://socket.dev/blog/popular-rust-crates-compromised)).
+- **No accuracy numbers.** No false-positive rate for malware verdicts is
+  published; false-positive language appears only for reachability cutting CVE
+  noise.
+
+**Takeaway.** Penthera has no logos, no funding and no usage telemetry (by
+design, it has no way to count users). What it can show is what a reader can
+check: benchmark precision and recall with every miss listed, rule and test
+counts generated from the code, a cited methodology, an OpenSSF Scorecard, and
+2FA-approved releases with provenance. That is the "By the numbers" block in the
+README, refreshed by `npm run docs:numbers`.
+
+## 5. Calls to action
+
+- Every page pairs a free self-serve action (install the GitHub app) with a sales
+  action (book a demo or contact sales) ([home](https://socket.dev/), compare and
+  use-case pages).
+- Product pages lead with the install command
+  ([CLI](https://socket.dev/features/cli),
+  [firewall](https://socket.dev/features/firewall)); every blog post ends with a
+  free firewall card.
+- An urgency line: a phone number for teams under active attack.
+
+**Takeaway.** Penthera has no sales step, so its call to action is the command
+itself. The README opens with three `npx` commands that each take under a
+minute and need no account.
+
+## 6. What they leave unsaid
+
+| Topic | What Socket's pages say | Room for Penthera |
+|---|---|---|
+| Offline use | No offline or air-gapped mode documented. Even self-hosted firewall modes check packages against Socket's API ([firewall free](https://docs.socket.dev/docs/socket-firewall-free), [pricing](https://socket.dev/pricing)). Only manifests and lockfiles are sent, not source ([FAQ](https://socket.dev/faq)) | Everything runs locally; `--offline` limits traffic to the named target |
+| Deterministic verdicts | Static analysis first, then an LLM stage, then human review before a package is labelled known malware ([AI alert](https://socket.dev/alerts/gptMalware)). No claim of reproducible results | Same input, same output, with the rule and `file:line` for each finding |
+| App and runtime security | No DAST or live-URL testing; first-party SAST and secrets only on Enterprise | URL and repo scans, fix recipes, verification |
+| AI tooling | Covers it as packages: an MCP server for package lookups ([MCP guide](https://docs.socket.dev/docs/guide-to-socket-mcp)), firewall ecosystems that include agent skills and models ([firewall](https://socket.dev/features/firewall)), research on malicious MCP servers ([labs](https://socket.dev/labs)). Nothing found that audits a repo's own agent config | `penthera agents`: CLAUDE.md, `.mcp.json`, hooks, permissions, plugins, rule files |
+| EU compliance | SBOM export (CycloneDX, SPDX, OpenVEX) on Business and up; no NIS2 or CRA page found; compliance messaging is SOC 2 and Vanta-style integrations | NIS2 readiness, CRA Article 14 drafts, SBOM and AI-BOM, signable evidence, free |
+
+Two cautions. Socket does cover parts of AI tooling, and says so; Penthera's docs
+should not claim it does not. And the AI-versus-rules point should be made
+calmly: Socket's AI scanner once flagged Penthera itself as malware because the
+repository contains real test payloads. That is a fair example of the trade-off,
+not a gotcha. AI stages catch novel attacks that no rule anticipated; rules
+explain themselves and do not misread intent. Running both is reasonable.
+
+## 7. What Penthera's docs take from this
+
+1. **A three-command "Try it in 60 seconds" block** near the top of the README,
+   as the call to action.
+2. **Use-case pages by situation**, each with the problem, what to run, real
+   example output, and what Penthera does not do
+   ([docs/use-cases/](../use-cases/README.md)).
+3. **Comparison pages framed as "use together"**, with factual tables, where the
+   other tool goes further, links to the vendor's docs, and a last-checked date
+   ([docs/compare/](../compare/README.md)).
+4. **Proof without logos**: a short "By the numbers" block in the README, every
+   number checkable and refreshable.
+5. **A shorter README** that points to per-command pages instead of carrying
+   every flag.
+
+Things deliberately not copied: inflated or inconsistent numbers, tweet walls,
+competitor tables that only list the author's strengths, and urgency language.

package/docs/use-cases/README.md

@@ -0,0 +1,14 @@
+# Use cases
+
+Each page starts from a situation, not a feature: the problem, what to run, what
+the output looks like, and what Penthera does not do for you.
+
+| You are | Page |
+|---|---|
+| A solo founder or vibecoder about to launch | [Before launch](solo-founder.md) |
+| A team adopting Claude Code or Cursor | [The AI-tooling supply chain](ai-coding-teams.md) |
+| An open-source maintainer | [For maintainers](open-source-maintainers.md) |
+| An EU SME with NIS2 or CRA duties | [Evidence for NIS2 and the CRA](eu-sme-compliance.md) |
+| An agency shipping client apps | [A repeatable handover check](agencies.md) |
+
+Using another security tool already? See [how Penthera fits with it](../compare/README.md).

package/docs/use-cases/agencies.md

@@ -0,0 +1,71 @@
+# A repeatable handover check: for agencies shipping client apps
+
+## The problem
+
+An agency ships many similar apps for clients who assume security was handled.
+Each project has a different team, a different deadline and a launch date that
+does not move. A security review by a person for every launch is too expensive,
+and "we followed best practice" does not survive a client's procurement
+questionnaire or an incident.
+
+## What to run
+
+The same three steps on every project, in CI or before handover:
+
+```bash
+npx penthera https://preview.client.example --repo . --profile standard \
+  --sarif reports/scan.sarif -o reports/scan.json
+npx penthera deps --license-policy permissive     # dependency capabilities and licences
+npx penthera agents                               # the agent config left in the repo
+```
+
+At handover, give the client a report written for them and a bundle they can
+keep:
+
+```bash
+npx penthera https://client.example --repo . --audience owner > security-summary.md
+npx penthera https://client.example --repo . --audience auditor \
+  --evidence handover/2026-10-19 --sign-key ~/.ssh/agency_ed25519
+```
+
+Pin the Penthera version in CI so every project is checked by the same rules,
+and use `--baseline` to show only what is new since the last scan.
+
+## What you get
+
+The owner report is in plain language. From Penthera's own mock target:
+
+```markdown
+# Security summary
+
+## In short
+
+Penthera checked http://localhost:8765 and found **2 serious problems** to fix
+this week, 5 moderate, 2 minor, 2 notes. The serious ones are things an attacker
+could use today.
+
+## What to do first
+
+1. **Harden authentication and access control** (involved, a developer can do this). ...
+2. **Remove the exposed file or interface from production** (quick, a developer can do this). ...
+3. **Add a Content-Security-Policy header** (moderate, a developer can do this). ...
+```
+
+The auditor version covers scope and method, every finding with its evidence and
+confidence, the hosts contacted, and the probes that could not run. The evidence bundle hashes every file in a
+signed manifest, so the client can check later that nothing was edited.
+`--report-template` puts the same data into your own Markdown template.
+[More on reports and evidence](../evidence.md).
+
+## What it does not do
+
+- It does not replace a penetration test where a contract or a regulator asks for
+  one. It makes that test cheaper, because the routine findings are already gone.
+- It only scans what you point it at, with the client's permission. Get the scope
+  in writing.
+- Fix recipes cover common JavaScript and TypeScript frameworks. Other stacks get
+  findings and guidance, not diffs.
+- It does not monitor client production after handover yet. That is on the
+  [roadmap](../../ROADMAP.md).
+
+[All use cases](README.md) · [Back to the README](../../README.md)

package/docs/use-cases/ai-coding-teams.md

@@ -0,0 +1,81 @@
+# The AI-tooling supply chain: for teams adopting Claude Code or Cursor
+
+## The problem
+
+A coding agent runs with your developer's permissions. What it can do is decided
+by files that rarely get reviewed: `.mcp.json`, `.claude/settings.json`, hooks,
+skills, plugins, `CLAUDE.md`, `AGENTS.md` and `.cursor/` rules. Some of these
+arrive from a teammate's pull request, some from a marketplace, some from a
+blog post. In 2025 and 2026 attackers used exactly these paths: skills with
+instructions hidden from human reviewers, MCP servers launched with `npx -y` on
+whatever version was latest, and npm worms that wrote to `~/.claude` and ran the
+`claude` CLI on the victim's machine.
+
+## What to run
+
+```bash
+npx penthera agents --home         # this repo plus your user-level Claude Code, Cursor and Claude Desktop config
+npx penthera agents ./some-skill   # vet a downloaded skill before you install it
+npx penthera agents --pin          # record hashes in penthera.lock; later runs show what changed
+```
+
+For a team, add the pre-commit hook so agent-config changes are checked before
+they are committed, and the GitHub Action in `agents` mode on pull requests:
+
+```bash
+npx penthera hook install
+```
+
+```yaml
+- uses: danoszz/penthera@<release-commit-sha>
+  with:
+    mode: agents
+```
+
+## What you get
+
+From Penthera's own test fixture of a deliberately bad setup (abridged):
+
+```
+  Grade       F  (0/100)
+  Found      1 skills · 4 MCP servers · 3 hooks · 0 plugins · 1 rule files
+  Lock       none (run with --pin)
+
+  CRIT  MCP server "installer" launches by downloading and running code
+         .mcp.json
+  CRIT  SessionStart hook downloads and runs code
+         .claude/settings.json
+  HIGH  Instructions hidden in an HTML comment
+         skills/helper/SKILL.md
+  HIGH  Text addressed to a security scanner
+         skills/helper/SKILL.md
+  HIGH  PreToolUse (*) hook auto-approves tool calls
+         .claude/settings.json
+  HIGH  Permission allow-list grants `Bash(*)`
+         .claude/settings.json
+  MED   MCP server "filesystem" runs an unpinned package via npx
+         .mcp.json
+```
+
+Each finding names the OWASP MCP Top 10 and Agentic Top 10 ids it maps to, and
+the rule that fired is readable in [`lib/agents/`](../../lib/agents/). The audit
+is offline and read-only: no model judges the skill, so a skill cannot talk its
+way past it. [More on `penthera agents`](../commands/agents.md).
+
+`penthera deps` also flags packages that write to `~/.claude`, `~/.cursor` or
+`.mcp.json`, or run the `claude`, `gemini` or `q` CLIs, which is how the
+s1ngularity attack used local AI tools. [More on `penthera deps`](../commands/deps.md).
+
+## What it does not do
+
+- It reads configuration and files on disk. It does not watch what an agent does
+  at run time, and it does not sandbox anything.
+- It does not know whether a remote MCP server is trustworthy. It checks how the
+  server is launched and configured, not what the service behind it does.
+- It does not check the registries for newly published malicious skills or
+  packages. A registry-watching service such as
+  [Socket](../compare/socket.md) covers that.
+- Its rules cover the patterns in the [methodology](../METHODOLOGY.md). A new
+  trick needs a new rule and a release.
+
+[All use cases](README.md) · [Back to the README](../../README.md)

package/docs/use-cases/eu-sme-compliance.md

@@ -0,0 +1,68 @@
+# Evidence for NIS2 and the CRA: for EU SMEs
+
+## The problem
+
+NIS2 puts a duty of care on in-scope organisations, written into national law
+(the Cyberbeveiligingswet in the Netherlands, the NIS2-wet in Belgium). The
+Cyber Resilience Act adds reporting duties for manufacturers of products with
+digital elements, with deadlines measured in hours. Large customers now send
+security questionnaires as part of procurement. A small company has to show
+that it tests, fixes and records, without a compliance team or a budget for a
+platform.
+
+## What to run
+
+```bash
+penthera --assessment-init assessment.json          # once: the organisational measures a scanner cannot test
+penthera https://staging.example.com --repo . \
+  --framework nis2 --readiness --assessment assessment.json \
+  --sbom sbom.cdx.json --evidence evidence/2026-10-19 --sign-key ~/.ssh/id_ed25519
+```
+
+That run writes the scan, an Article 21(2) coverage table, a readiness report
+with every measure marked met, partial, gap or not applicable, a CycloneDX SBOM,
+and a hashed, SSH-signed evidence bundle an auditor can verify with standard
+tools.
+
+Around it:
+
+```bash
+penthera --policy-pack ./policies --org "Your Company" --readiness --assessment assessment.json
+penthera https://example.com --readiness --assessment assessment.json --questionnaire questions.txt
+penthera --cra-init cra.json && penthera --cra cra.json   # CRA Article 14 timeline and drafts
+penthera --repo . --aibom aibom.cdx.json                  # CycloneDX 1.6 AI-BOM
+```
+
+## What you get
+
+The CRA helper prints the deadlines and writes draft reports, marking every fact
+it still needs:
+
+```
+CRA Article 14 report drafts written to cra-reports.md
+  Early warning (24 hours): n/a, set aware_at
+  Vulnerability notification (72 hours): n/a, set aware_at
+  Final report (14 days after a corrective or mitigating measure is available): ...
+  ⚠️ No valid `aware_at` timestamp, so deadlines can't be computed. Set when you became aware (ISO 8601) and re-run.
+```
+
+The questionnaire helper answers each question from your scan and
+self-assessment, cites the evidence, and marks anything it cannot map as
+`NEEDS HUMAN INPUT` instead of guessing. Guides:
+[NIS2](../compliance-nis2.md), [CRA](../compliance-cra.md),
+[evidence bundles](../evidence.md).
+
+## What it does not do
+
+- It is readiness tooling, not a certification and not legal advice. Whether you
+  are in scope, and what is proportionate for you, is for you and your advisers
+  to decide.
+- It covers the technical, testable part of the duty of care. Policies,
+  training, backups and MFA come from your self-assessment; Penthera records
+  what you attest, it cannot check it.
+- It does not file anything. Reports to a CSIRT or ENISA are drafts for you to
+  review and submit.
+- Jurisdiction details ship for the Netherlands today; other member states are
+  configuration still to be added.
+
+[All use cases](README.md) · [Back to the README](../../README.md)

package/docs/use-cases/open-source-maintainers.md

@@ -0,0 +1,75 @@
+# For open-source maintainers
+
+## The problem
+
+Your project is someone else's dependency. A compromised maintainer account, a
+malicious contributor pull request that bumps a lockfile, or a leaked publish
+token can turn it into the attack. Most maintainers do this unpaid, without a
+security budget, and many cannot send their dependency list or code to a vendor
+service, or would rather not sign up for one.
+
+## What to run
+
+On every pull request that touches the lockfile, comment what the change lets
+code do:
+
+```yaml
+- uses: danoszz/penthera@<release-commit-sha> # pin to a release commit
+  with:
+    mode: deps
+    fail-on: none
+```
+
+The full workflow, with permissions and a paths filter, is in
+[`docs/examples/pr-dependency-review.yml`](../examples/pr-dependency-review.yml).
+The action runs Penthera from its own checkout: no install from npm and no
+registry lookups. On pull requests from forks the token is read-only, so the
+diff goes to the job summary instead of a comment.
+
+Locally, before you cut a release:
+
+```bash
+npx penthera deps --base origin/main   # what changed in the tree since main
+npx penthera --repo .                  # secrets, including AI provider keys
+npx penthera agents                    # the agent config you ship (CLAUDE.md, .mcp.json, skills/)
+npx penthera hook install              # block secrets and risky config at commit time
+```
+
+## What you get
+
+```
+  ▲ 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);
+```
+
+A patch release that starts reading the whole environment next to a network call
+is the shape of most credential-stealing packages. The diff shows it with
+`file:line` evidence, whether or not an advisory exists yet.
+[More on `penthera deps`](../commands/deps.md) and [the action](../commands/action.md).
+
+If your project ships agent skills or MCP configuration, `penthera agents` on
+your own repo is a reasonable release check too: it is what your users' tools
+will load.
+
+## How Penthera handles its own releases
+
+The same practices are worth copying. Penthera releases are published with npm
+provenance through trusted publishing and are staged: each version waits on npm
+until a maintainer approves it with 2FA. CI actions are pinned by SHA, CodeQL
+runs on every push, and the
+[OpenSSF Scorecard](https://scorecard.dev/viewer/?uri=github.com/danoszz/penthera)
+is public. See [`.github/workflows/publish.yml`](../../.github/workflows/publish.yml).
+
+## What it does not do
+
+- Dependency analysis covers npm and Python. The install firewall and the
+  `--online` registry checks are npm only for now.
+- It does not track CVEs in your dependencies. Keep Dependabot or a similar
+  service on for that ([how they fit](../compare/github.md)).
+- It does not watch the registry for your package being republished by someone
+  else. Enable 2FA and trusted publishing on npm for that.
+- A capability is what code *can* do, not proof of intent. Many good packages
+  use the network; the diff is there so a person can look.
+
+[All use cases](README.md) · [Back to the README](../../README.md)

package/docs/use-cases/solo-founder.md

@@ -0,0 +1,65 @@
+# Before launch: for solo founders and vibecoders
+
+## The problem
+
+You built the app in weeks, much of it with an AI assistant. It works. You have
+not had time to check the things that tend to go wrong in AI-written apps: an
+API route that returns any user's data if you change the id, an OpenAI key in a
+client bundle, a missing security header, a CORS policy of `*`, a login with no
+rate limit. Nobody on the team does security, because there is no team.
+
+## What to run
+
+Start the app locally, then:
+
+```bash
+npx penthera http://localhost:3000 --repo .   # the running app and its source, together
+npx penthera fix --plan --repo .              # fixes for what it can fix, as diffs
+npx penthera hook install                     # stop secrets at commit time from now on
+```
+
+Or ask your coding agent, with the [Agent Skill](../commands/skill.md)
+installed: "scan my app on localhost:3000 and fix what you find".
+
+Before you deploy, run the same scan against your preview URL. Only scan systems
+you own.
+
+## 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
+```
+
+`penthera fix --plan` then prints a unified diff per fix it knows (security
+headers, cookie flags, a CORS allowlist, a login rate limit, moving a
+hardcoded secret to an environment variable) for Next.js, Express, Fastify and
+Hono. Nothing is written until you apply a plan by id, and the repo is
+re-scanned afterwards to confirm the finding is gone.
+[More on fixes](../commands/fix.md).
+
+## What it does not do
+
+- It is not a penetration test by a person. It checks known classes of problem;
+  it will not find a flaw in your business logic, such as a coupon that can be
+  applied twice.
+- It does not fix IDOR or auth design for you. It points at the route; the fix
+  is yours.
+- It does not watch production yet. Scheduled checks are on the
+  [roadmap](../../ROADMAP.md).
+- A clean scan is not proof of safety. Every finding has a confidence label, and
+  probes that could not run are listed as inconclusive rather than passed.
+
+[All use cases](README.md) · [Back to the README](../../README.md)

package/lib/blackbox/email-dns.js

@@ -13,6 +13,7 @@
  * live DNS.
  */
 import { resolveTxt as dnsResolveTxt, resolveMx as dnsResolveMx } from "node:dns/promises";
+import { currentEgress } from "../../src/utils/http.js";
 
 const DEFAULT_RESOLVER = { resolveTxt: dnsResolveTxt, resolveMx: dnsResolveMx };
 
@@ -98,6 +99,10 @@ export function evaluateDmarc(txtRecords) {
  * @param {object} opts - { resolver }
  */
 export async function probeEmailDns(domain, opts = {}) {
+  // DNS queries go to resolvers, not the target: --offline forbids them.
+  if (currentEgress()?.offline) {
+    return { domain, spf: null, dmarc: null, dmarcPolicy: null, mxCount: 0, findings: [], skipped: "offline" };
+  }
   const resolver = opts.resolver || DEFAULT_RESOLVER;
   const findings = [];