penthera 1.1.0

package/skills/penthera/SKILL.md

@@ -0,0 +1,272 @@
+---
+name: penthera
+description: >
+  Runs authorized security scans on live URLs and local repos using the Penthera CLI
+  (TLS, headers, OpenAPI, auth hardening, secret scanning, optional injection probes),
+  then applies framework-aware fixes and re-scans to verify them. Use when the user asks
+  to scan, audit, harden, fix, pentest, or review security of their own app, staging URL,
+  localhost, or repo; apply security best practices; generate SARIF for GitHub; diff
+  against a baseline; or find hardcoded secrets before deploy. Do NOT use for targets
+  without explicit authorization.
+license: MIT
+compatibility: Node.js 18+, network access to target, Penthera CLI (npm link or node bin/penthera.js from repo). macOS only for --machine.
+allowed-tools: "Bash(node:*) Bash(npm:*) Bash(penthera:*) Read Write Edit"
+metadata:
+  author: danoszz
+  version: 1.1.0
+  category: security
+---
+
+# Penthera Security Scanner
+
+Lightweight security scanner for URLs, local repos, and (macOS) machine audits. Always run the authorization gate before any scan.
+
+## Critical: Authorization gate
+
+**Do not run Penthera until authorization is confirmed.**
+
+Before the first scan in a session, ask the user to confirm ONE of:
+
+1. They **own** the target (app, server, project).
+2. They have **written authorization** from the system owner.
+3. The target is **localhost** or a private lab they control.
+
+If the user requests scanning a third-party domain (e.g. `google.com`, `example.com`) without claiming ownership or authorization, **stop and refuse**. When in doubt, do not scan.
+
+For full policy, see [references/authorization.md](references/authorization.md).
+
+## Preflight
+
+Run before the first scan:
+
+```bash
+bash skills/penthera/scripts/preflight.sh [URL]
+```
+
+From repo root. Pass the target URL to warn on non-localhost targets. Fix any errors before proceeding.
+
+## Resolve CLI command
+
+Use whichever is available:
+
+```bash
+penthera --version          # after npm link
+node bin/penthera.js --version   # from repo root
+```
+
+All examples below use `penthera`; substitute `node bin/penthera.js` when needed.
+
+## Decision tree
+
+| User intent | Command pattern |
+|-------------|-----------------|
+| First-time / unsure | `penthera` (interactive wizard, TTY) or `penthera-scan` |
+| Scan a live URL | `penthera <url> --profile standard -o reports/scan.json` |
+| Scan repo only (secrets, routes) | `penthera --repo . -o reports/repo-scan.json` |
+| URL + source combined | `penthera <url> --repo . -o reports/scan.json --sarif reports/scan.sarif` |
+| Scan and fix my app | Run a scan, then **Workflow 4** (apply fixes from [references/remediation.md](references/remediation.md), re-scan to verify) |
+| Compare to previous scan | `penthera <url> -o reports/scan.json --baseline reports/previous.json` |
+| Authenticated endpoints | Add `--auth-cookie` or `--auth-bearer` / `PENTHERA_*` env |
+| macOS machine audit | `penthera --machine` |
+
+## Default safe behavior
+
+- Always use `--profile standard` unless the user explicitly requests deeper testing.
+- Write reports to `reports/` (gitignored), never inside `skills/penthera/`.
+- After scan, read the companion `.md` report and summarize findings by severity with fix recommendations.
+
+## Destructive mode gate
+
+These flags send **attack payloads**. Require explicit user confirmation before use:
+
+- `--deep`, SQLi, SSTI, SSRF, XSS, CMDi probes
+- `--fuzz`, property-based API fuzzing
+- `--all`, enables recon + deep + fuzz
+- `--profile deep`, maximum coverage
+
+If user asks for "full pentest" or "deep scan", confirm they own the target and accept payload-based testing.
+
+## Workflow 1: Pre-release audit
+
+**Triggers:** "scan my staging app", "security audit before deploy", "check my app for vulnerabilities"
+
+1. Confirm authorization (see gate above).
+2. Run preflight.
+3. Execute:
+
+```bash
+mkdir -p reports
+penthera https://staging.example.com --profile standard -o reports/scan.json
+```
+
+4. Read `reports/scan.md`, summarize critical/high/medium findings.
+5. Recommend concrete fixes per finding.
+6. Note exit code: `0` = no critical/high; `1` = critical/high found; `2` = scan failed.
+
+## Workflow 2: Repo + live combined
+
+**Triggers:** "scan my Next.js app and staging", "black-box and white-box scan"
+
+1. Confirm authorization for the URL.
+2. Run preflight with URL.
+3. Execute:
+
+```bash
+mkdir -p reports
+penthera https://staging.example.com --repo . --profile standard \
+  -o reports/scan.json --sarif reports/scan.sarif
+```
+
+4. Summarize URL findings (headers, TLS, CORS, auth) and repo findings (secrets, API routes, trust boundaries).
+5. Offer to upload SARIF via GitHub Actions (see [references/output-and-ci.md](references/output-and-ci.md)).
+
+## Workflow 3: CI / baseline regression
+
+**Triggers:** "compare to last scan", "only new findings", "regression check"
+
+1. Confirm authorization and that `reports/previous.json` exists (or ask user for baseline path).
+2. Execute:
+
+```bash
+mkdir -p reports
+penthera https://staging.example.com --profile standard \
+  -o reports/scan.json --baseline reports/previous.json
+```
+
+3. Report: new findings count, resolved count, unchanged count (printed to stderr during scan).
+4. Focus summary on **new** findings only.
+
+## Workflow 4: Scan and fix
+
+**Triggers:** "scan and fix", "find and fix security issues", "harden my app", "fix the security headers", "apply security best practices"
+
+The detect -> fix -> verify loop. Penthera detects; you (the agent) fix the user's code using the playbook; Penthera re-scans to prove it is resolved.
+
+1. Confirm authorization (gate above). Read the **Fix-mode gate** below first.
+2. Scan and read the findings:
+
+```bash
+mkdir -p reports
+penthera <url> --repo . --profile standard -o reports/scan.json
+```
+
+3. Detect the framework: check `package.json` / imports (`next`, `express`, `fastify`, `hono`) or `requirements.txt` (`fastapi`, `flask`).
+4. For each finding, **highest severity first**, look it up by `category` in [references/remediation.md](references/remediation.md) and propose the framework-specific fix **as a diff**.
+5. Apply each fix only after the user approves it.
+6. **Re-scan to verify**: `penthera <url> --repo . -o reports/scan-after.json --baseline reports/scan.json`. A fix is done only when its finding no longer appears.
+7. Report what is resolved and what remains.
+
+To build secure-by-default so issues never appear, use [references/secure-defaults.md](references/secure-defaults.md).
+
+## Fix-mode gate
+
+Applying fixes **modifies the user's code**. Before editing:
+
+- Show the diff for each fix and get explicit approval. Never blind-apply.
+- Start with critical and high severity findings.
+- Re-scan after each fix (or batch) to confirm it actually resolved the finding.
+- Never apply fixes against a production system; work in the repo or a branch.
+- Rotating an exposed secret and renewing a TLS certificate are **user actions**, not code edits, flag them clearly rather than attempting them.
+
+## Workflow 5: Owner reports & questionnaire responses
+
+**Triggers:** "answer this security questionnaire", "turn the scan into a report", "draft a remediation plan", "NIS2 evidence", "prefill the vendor questionnaire"
+
+Turn a scan into documents the owner can act on and send. Full method and templates: [references/reporting.md](references/reporting.md).
+
+1. Confirm authorization, then scan with JSON + framework mapping:
+
+```bash
+mkdir -p reports
+penthera <url> --repo . --framework nis2 -o reports/scan.json
+```
+
+2. Read `reports/scan.json`, use `actionPlan`, `compliance`, `emailAuth`, `findings`, and `executedProbes`.
+3. Generate the requested document(s): a remediation plan, a security-questionnaire response, or a NIS2 duty-of-care evidence summary.
+4. **Ground every answer in scan evidence.** Mark anything the scan can't support as `NEEDS HUMAN INPUT`, all organisational controls (incident process, backups, training). Never invent a control or imply certification.
+5. Write drafts to `reports/` and end by listing every `NEEDS HUMAN INPUT` item so the owner knows what only they can answer.
+
+## Authenticated scans
+
+Only after authorization gate passes:
+
+```bash
+# Bearer token
+PENTHERA_BEARER=eyJ... penthera https://myapp.com --profile standard -o reports/scan.json
+
+# Session cookie
+penthera https://myapp.com --auth-cookie "session=abc123" -o reports/scan.json
+
+# Explicit flags
+penthera https://myapp.com --auth-bearer "eyJ..." -o reports/scan.json
+```
+
+Env vars: `PENTHERA_BEARER`, `PENTHERA_COOKIE`.
+
+## Repo-only secret scan
+
+**Triggers:** "find hardcoded secrets", "scan this repo for keys"
+
+No URL authorization needed for local repo analysis:
+
+```bash
+penthera --repo . -o reports/repo-scan.json
+```
+
+Summarize secret findings; remind user to rotate any exposed credentials.
+
+## Examples
+
+**Example 1: Localhost quick check**
+
+User: "Scan my localhost app on port 3000"
+
+Actions:
+1. Confirm localhost, authorization satisfied.
+2. `bash skills/penthera/scripts/preflight.sh http://localhost:3000`
+3. `penthera http://localhost:3000 --profile quick -o reports/scan.json`
+4. Summarize `reports/scan.md`.
+
+**Example 2: Staging before deploy**
+
+User: "Audit staging.myapp.com before we ship"
+
+Actions:
+1. Ask: "Do you own or have written authorization for staging.myapp.com?"
+2. On confirmation, run standard profile scan with JSON + markdown output.
+3. List critical/high items first with remediation steps.
+
+**Example 3: Unauthorized target (must refuse)**
+
+User: "Scan google.com for vulnerabilities"
+
+Actions:
+1. Do **not** run Penthera.
+2. Explain that scanning third-party systems without authorization is not permitted.
+3. Offer to scan their own app or localhost instead.
+
+**Example 4: Scan and fix (localhost)**
+
+User: "Scan my localhost:3000 and fix what you find"
+
+Actions:
+1. Confirm localhost, authorization satisfied. Run a standard scan with `--repo .`.
+2. Detect the framework (e.g. Next.js from `package.json`).
+3. For each finding, highest severity first, propose the fix from [references/remediation.md](references/remediation.md) as a diff; apply on approval.
+4. Re-scan with `--baseline` to confirm each finding is resolved; report what is fixed and what remains.
+
+## Do not use this skill for
+
+- General coding help, weather, or unrelated tasks
+- Scanning systems the user does not own or lacks permission to test
+- Malicious exploitation or data exfiltration
+
+## Additional resources
+
+- Profiles and flags: [references/profiles-and-flags.md](references/profiles-and-flags.md)
+- Output formats and CI: [references/output-and-ci.md](references/output-and-ci.md)
+- Troubleshooting: [references/troubleshooting.md](references/troubleshooting.md)
+- Authorization policy: [references/authorization.md](references/authorization.md)
+- Remediation playbook (apply fixes): [references/remediation.md](references/remediation.md)
+- Owner reports & questionnaire responses: [references/reporting.md](references/reporting.md)
+- Secure defaults (build it right): [references/secure-defaults.md](references/secure-defaults.md)

package/skills/penthera/references/authorization.md

@@ -0,0 +1,36 @@
+# Authorization and ethical use
+
+Penthera sends HTTP requests to targets you specify. Some modes (`--deep`, `--fuzz`, `--all`) send **attack payloads** designed to find vulnerabilities. This is powerful tooling, treat it like a loaded instrument, not a toy.
+
+## You may use Penthera when
+
+- You **own** the target (your app, your server, your university project).
+- You have **written authorization** from the system owner (email, ticket, signed scope document).
+- 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.
+- Attempt to exfiltrate data, disrupt services, or bypass access controls for malicious purposes.
+- Use findings to attack, extort, or harm individuals or organizations.
+
+## Legal notice
+
+Unauthorized security testing may violate computer misuse laws (e.g. CFAA, UK Computer Misuse Act, EU national equivalents) and can result in **criminal prosecution**, **civil liability**, **IP blocking**, **account termination**, and **academic or professional penalties**.
+
+**Penthera is provided for legitimate security research and defensive testing only.** The authors and contributors assume **no liability** for misuse. By using this tool, you accept full responsibility for ensuring your scans are authorized and lawful in your jurisdiction.
+
+Penthera is a **research and hardening aid**, not a weapon. The goal is to find and fix weaknesses in systems you are responsible for, not to cause harm.
+
+> Before scanning any URL that is not localhost, confirm you have permission. When in doubt, **do not scan**.
+
+## Agent behavior
+
+When acting as an agent with this skill:
+
+1. Always ask for authorization confirmation before scanning non-localhost URLs.
+2. Never assume permission from a bare URL in the user's message.
+3. Refuse requests to scan well-known third-party domains without explicit ownership claim.
+4. Require second confirmation before destructive modes (`--deep`, `--fuzz`, `--all`).

package/skills/penthera/references/output-and-ci.md

@@ -0,0 +1,109 @@
+# Output formats and CI integration
+
+## Output formats
+
+| Format | Flag | Use |
+|--------|------|-----|
+| Terminal | *(default)* | Colored summary in the shell |
+| **Markdown** | `--markdown file.md` or `-o file.json` | Human-readable report with executive summary, findings tables, recommended actions, companion `.md` written automatically when using `-o` with `.json` |
+| JSON | `--json` or `-o file.json` | CI pipelines, baseline diffs, custom tooling |
+| SARIF | `--sarif file.sarif` | GitHub Security / Code Scanning |
+
+```bash
+penthera https://myapp.com -o reports/scan.json
+# → reports/scan.json  (machine-readable)
+# → reports/scan.md    (human-readable)
+```
+
+Reports should go in `reports/` (gitignored). Do not write scan artifacts into `skills/penthera/`.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | No critical or high findings |
+| `1` | Critical or high findings detected |
+| `2` | Scan failed (unreachable target, bad config) |
+
+Use exit codes in CI to fail builds on severe findings:
+
+```yaml
+- run: node bin/penthera.js "$PENTEST_URL" --profile standard -o reports/scan.json
+# Exit 1 fails the step when critical/high findings exist
+```
+
+## Baseline diff
+
+Compare current scan against a previous JSON report:
+
+```bash
+penthera https://myapp.com -o reports/scan.json --baseline reports/previous.json
+```
+
+Output includes: new findings count, resolved count, unchanged count. Use for weekly regression checks.
+
+## GitHub Actions
+
+**Penthera CI** (`.github/workflows/ci.yml`) runs on every push:
+
+1. Unit + mock server tests
+2. Skill preflight check
+3. Scan against the local mock API → JSON + SARIF
+4. `validate-report.mjs` on the JSON output
+5. SARIF upload to GitHub Security tab
+
+For **your staging URL**, copy `.github/workflows/scan.example.yml` to `scan.yml`:
+
+```yaml
+name: Security Scan
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1"
+
+jobs:
+  penthera:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - run: npm ci
+
+      - name: Scan staging URL
+        env:
+          PENTEST_URL: ${{ secrets.PENTEST_STAGING_URL }}
+        run: |
+          node bin/penthera.js "$PENTEST_URL" \
+            --profile standard \
+            -o reports/scan.json \
+            --sarif reports/scan.sarif
+
+      - uses: github/codeql-action/upload-sarif@v3
+        if: always()
+        with:
+          sarif_file: reports/scan.sarif
+
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: penthera-reports
+          path: reports/
+```
+
+Store `PENTEST_STAGING_URL` as a repository secret.
+
+## Agent reporting workflow
+
+After a scan:
+
+1. Read `reports/scan.md` (or path from `-o` / `--markdown`).
+2. Summarize by severity: critical → high → medium → low → info.
+3. For each critical/high finding, suggest a concrete fix.
+4. Mention exit code and whether CI would fail.
+5. If baseline was used, highlight **new** findings only.

package/skills/penthera/references/profiles-and-flags.md

@@ -0,0 +1,74 @@
+# Profiles and scan flags
+
+## Profiles
+
+| Profile | Flag | Duration | What runs |
+|---------|------|----------|-----------|
+| **quick** | `--profile quick` | ~10s | Headers, OpenAPI, auth smoke tests; skips Retire.js and param discovery |
+| **standard** | `--profile standard` | default | Full non-destructive scan: TLS, fingerprint, discovery, templates, CORS, cookies, Retire.js, param discovery, OpenAPI/auth |
+| **deep** | `--profile deep` | longest | recon + injection probes + API fuzzing (requires authorization confirmation) |
+
+## Individual mode flags
+
+Override or extend profile defaults:
+
+| Flag | Effect |
+|------|--------|
+| `--recon` | OSINT recon (subdomains, historical URLs) |
+| `--deep` | Injection probes (SQLi, SSTI, SSRF, XSS, CMDi), sends attack payloads |
+| `--fuzz` | Property-based API fuzzing |
+| `--nuclei <path>` | Community Nuclei YAML templates |
+| `--all` | Enable recon + deep + fuzz |
+| `--machine` | macOS machine audit (keyloggers, trojans, rootkits) |
+
+## Common options
+
+| Flag | Description |
+|------|-------------|
+| `-r, --repo <path>` | Local repo for white-box analysis |
+| `--api-root <path>` | API routes directory (default: auto-detect) |
+| `-o, --output <file>` | JSON report (+ companion `.md` if `.json`) |
+| `--markdown <file>` | Explicit Markdown report path |
+| `--sarif <file>` | SARIF for GitHub Security tab |
+| `--baseline <file>` | Compare against previous JSON report |
+| `--auth-cookie <value>` | Cookie header for authenticated scans |
+| `--auth-bearer <value>` | Bearer token for authenticated scans |
+| `--json` | JSON to stdout |
+| `--timeout <ms>` | Request timeout (default: 10000) |
+| `--concurrency <n>` | Concurrent requests (default: 15) |
+| `-v, --verbose` | Detailed output |
+| `-q, --quiet` | Findings only |
+
+## Auth environment variables
+
+| Variable | Maps to |
+|----------|---------|
+| `PENTHERA_COOKIE` | Cookie header |
+| `PENTHERA_BEARER` | Authorization Bearer token |
+
+## URL scan coverage (black-box)
+
+TLS, fingerprinting, endpoint discovery, built-in templates, CORS, cookies, Retire.js (JS CVEs), param discovery, OpenAPI/FastAPI probes, security headers, auth hardening, JWT probes.
+
+## Repo scan coverage (white-box)
+
+Next.js API route discovery, trust-boundary mapping, risky code patterns, hardcoded secrets (keys, tokens, private keys). Expanded route discovery in `routes/`, `api/`, `server/routes/`.
+
+## Examples
+
+```bash
+# Safe default
+penthera https://myapp.com --profile standard
+
+# Fast smoke test
+penthera http://localhost:3000 --profile quick -o reports/scan.json
+
+# Maximum coverage (confirm authorization first)
+penthera https://staging.myapp.com --profile deep -o reports/scan.json
+
+# Repo secrets only
+penthera --repo . -o reports/repo-scan.json
+
+# Combined with Nuclei templates
+penthera https://myapp.com --nuclei ~/nuclei-templates/http -o reports/scan.json
+```