penthera 1.1.1 → 1.4.0

package/docs/evidence.md

@@ -0,0 +1,158 @@
+# Evidence bundles and audience reports
+
+Penthera can write the results of one scan as an **evidence bundle**: every
+report, a manifest with the SHA-256 of each file, and an optional SSH
+signature over the manifest. An auditor checks the bundle with one command.
+No hosted service is involved, and nothing needs to be installed beyond Node
+(or `shasum` and `jq`) and OpenSSH 8.0 or later.
+
+## For auditors: verify a bundle
+
+You need the bundle directory and an **allowed signers file** that names the
+key you expect the bundle to be signed with. Get that public key from the
+organisation through a channel other than the bundle itself (their security
+page, an email you can authenticate, or in person).
+
+```bash
+npx penthera evidence verify ./evidence --allowed-signers allowed_signers
+```
+
+Exit code `0` means every file matches the manifest and the manifest was signed
+by a key in `allowed_signers`. Exit code `1` means something changed, is
+missing, was added, or the signature does not check out; the output says which.
+
+An `allowed_signers` file is one line per key:
+
+```text
+security@example.com namespaces="penthera-evidence" ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA...
+```
+
+### Without Penthera
+
+The bundle does not depend on Penthera to be checked. With standard tools:
+
+```bash
+cd evidence
+# 1. The manifest was signed by the expected key (namespace penthera-evidence)
+ssh-keygen -Y verify -f ../allowed_signers -I security@example.com \
+  -n penthera-evidence -s manifest.json.sig < manifest.json
+# 2. Every artifact matches its hash in the manifest
+jq -r '.artifacts[] | "\(.sha256)  \(.path)"' manifest.json | shasum -a 256 -c -
+# 3. Nothing else is in the directory
+ls
+```
+
+`penthera evidence verify` does the same three checks, and also rejects
+manifest paths that would leave the directory (`../`, absolute paths) and
+symlinked files.
+
+### What the checks prove, and what they do not
+
+- **Hashes** prove that the files have not changed since the manifest was
+  written. Without a signature they prove nothing about who wrote it: anyone
+  can rewrite a file and its hash together.
+- **The signature** proves that the holder of the signing key produced this
+  manifest. It does not prove that the scan was run against the system you
+  care about, or with the options you expect. Read the manifest's `command`,
+  `target`, `scan` and `git` fields, and the auditor report's scope section.
+- Without `--allowed-signers`, `verify` still checks that the signature is
+  valid but cannot tell you whose key made it. It reports
+  `valid-unknown-signer` as a warning.
+- A scan is a snapshot. The bundle is evidence of what Penthera saw at
+  `generated_at`, not a statement that the system is secure.
+
+## For the team producing evidence
+
+```bash
+penthera https://staging.example.com --repo . --framework nis2 \
+  --evidence evidence/2026-10-19 --sign-key ~/.ssh/id_ed25519
+```
+
+- `--evidence <dir>` writes the bundle. The directory must be new or empty, so
+  a bundle never mixes two runs.
+- `--sign-key <key>` signs `manifest.json` with
+  `ssh-keygen -Y sign -n penthera-evidence`. Use the private key path, or the
+  `.pub` path when the key lives in `ssh-agent` or on a hardware token. A
+  passphrase prompt appears in the terminal.
+- `--sbom <file>` and `--readiness` add their outputs to the bundle.
+- Give auditors the public key out of band, as an `allowed_signers` line.
+
+### What is in a bundle
+
+| File | Contents |
+|------|----------|
+| `report.json` | The full scan result |
+| `report.md` | The default Markdown report |
+| `report.sarif` | SARIF 2.1.0 |
+| `report-developer.md` | Findings with file:line, fix recipe ids or diffs, and sources |
+| `report-owner.md` | Plain-language summary, what to do first, owner actions, trend |
+| `report-auditor.md` | Scope and method, confidence and provenance, egress, inconclusive probes, suppressions, fix timeline, NIS2 and OWASP mapping |
+| `report-custom.md` | Your `--report-template` output, when given |
+| `nis2-readiness.md` | With `--readiness` |
+| `sbom.cdx.json` | CycloneDX SBOM, with `--sbom` |
+| `manifest.json` | Tool version, command line (secrets redacted), timestamp, target, git commit, SHA-256 and size of every file above |
+| `manifest.json.sig` | SSH signature over `manifest.json`, with `--sign-key` |
+
+The command line in the manifest has the values of `--auth-cookie`,
+`--auth-bearer` and any token, secret or password flag replaced with
+`[REDACTED]`, and credentials in URLs masked.
+
+## Audience reports
+
+`--audience developer|owner|auditor` picks who the Markdown report is for. It
+applies to `--markdown <file>`; without `--markdown` the report goes to stdout.
+The default report (no `--audience`) is unchanged.
+
+```bash
+penthera https://example.com --repo . --audience owner > for-the-owner.md
+penthera https://example.com --repo . --audience auditor --markdown audit.md
+```
+
+When a scan used `--memory`, the owner report shows the trend across recent
+scans. When the result has an agent loop run (`loopRun`) or memory has fix
+events, the developer, owner and auditor reports show a fix timeline:
+found → fixed → verified, with time to fix.
+
+## Your own template
+
+`--report-template file.md` renders your own Markdown from the same data the
+audience reports use. The language is deliberately tiny:
+
+```markdown
+# Security status for {{summary.target}}
+
+{{summary.critical}} critical, {{summary.high}} high ({{summary.total}} total).
+
+{{#each findings}}
+- [{{severity}}] {{title}}{{#if location}} at {{location}}{{/if}} ({{confidence}})
+{{/each}}
+
+{{#if suppressed}}
+Set aside: {{#each suppressed}}{{title}} by {{actor}}: {{reason}}; {{/each}}
+{{else}}
+Nothing suppressed.
+{{/if}}
+```
+
+- `{{path.to.value}}` prints a value. Values are HTML- and Markdown-escaped,
+  and newlines become spaces, so a finding title cannot add HTML, a heading, a
+  list item or a table cell.
+- `{{#each list}}…{{/each}}` loops; inside, `{{this}}` is the item and
+  `{{@index}}` its 0-based index. Names not found on the item are looked up in
+  the enclosing scope.
+- `{{#if value}}…{{else}}…{{/if}}`; an empty list counts as false.
+
+There are no helpers, no expressions, no raw output, no partials and no file
+includes. Paths containing `__proto__`, `constructor` or `prototype` are
+rejected, and only own properties are read. A template that uses anything else
+fails with a line number before the scan starts.
+
+Top-level fields: `tool`, `target`, `timestamp`, `duration`, `modes`,
+`profile`, `offline`, `probes`, `summary` (`critical`, `high`, `medium`,
+`low`, `info`, `serious`, `total`, `suppressed`, `inconclusive`), `findings`
+(`fid`, `title`, `severity`, `confidence`, `source`, `method`, `collectedAt`,
+`category`, `location`, `file`, `line`, `url`, `description`, `recipe`,
+`fixText`, `sources`, `owasp`, `wstg`), `suppressed` (`title`, `severity`,
+`reason`, `actor`, `by`, `expires`), `inconclusive`, `egress`, `actions`,
+`topActions`, `ownerActions`, `nis2`, `owasp`, `trend` and `timeline`. The
+model is built in [`src/report/model.js`](../src/report/model.js).

package/docs/examples/github-actions-deps.yml

@@ -0,0 +1,105 @@
+# Example: comment a dependency capability diff on every PR that changes the lockfile.
+#
+# Copy this file into YOUR app's repo as `.github/workflows/penthera-deps.yml`.
+# It installs the base and PR dependency trees with `--ignore-scripts` (no
+# package code runs), then `penthera deps --diff` reports packages that are new
+# or that gained capabilities (network, shell, install scripts, whole
+# environment, dynamic code, ...) and posts that as one PR comment, updated in
+# place on every push. Penthera itself runs offline; nothing is sent anywhere
+# except the comment to your own PR.
+#
+# Pin PENTHERA_VERSION to a release you have reviewed (and, ideally, the actions
+# below to commit SHAs) so this job never runs code you have not looked at.
+#
+# Fork PRs get a read-only token, so the comment step is skipped for them; the
+# report is still uploaded as an artifact. Do not switch this to
+# `pull_request_target`: that would run with write access next to untrusted code.
+
+name: Dependency capability diff
+
+on:
+  pull_request:
+    paths:
+      - package-lock.json
+      - npm-shrinkwrap.json
+
+permissions:
+  contents: read
+
+jobs:
+  deps:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    env:
+      PENTHERA_VERSION: latest # pin, e.g. 1.3.0
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          path: head
+          persist-credentials: false
+
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.pull_request.base.sha }}
+          path: base
+          persist-credentials: false
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Install both trees without running install scripts
+        run: |
+          (cd head && npm ci --ignore-scripts --no-audit --no-fund)
+          (cd base && npm ci --ignore-scripts --no-audit --no-fund)
+
+      - name: Diff dependency capabilities
+        id: deps
+        # Run from the temp dir so `npx` can't pick up a `penthera` binary that
+        # the PR's own node_modules might provide.
+        working-directory: ${{ runner.temp }}
+        run: |
+          set +e
+          npx --yes "penthera@${PENTHERA_VERSION}" deps "$GITHUB_WORKSPACE/head" \
+            --diff "$GITHUB_WORKSPACE/base" \
+            --pr-comment "$RUNNER_TEMP/deps-comment.md" \
+            --sarif "$RUNNER_TEMP/deps.sarif" \
+            -o "$RUNNER_TEMP/deps.json"
+          code=$?
+          set -e
+          echo "code=$code" >> "$GITHUB_OUTPUT"
+          # 1 = critical/high findings (reported in the comment); 2 = scan error.
+          if [ "$code" -eq 2 ]; then exit 2; fi
+
+      - name: Comment on the PR (updated in place)
+        if: github.event.pull_request.head.repo.full_name == github.repository
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          PR: ${{ github.event.pull_request.number }}
+        run: |
+          body="$RUNNER_TEMP/deps-comment.md"
+          id=$(gh api "repos/$REPO/issues/$PR/comments" --paginate \
+            --jq '.[] | select(.body | startswith("<!-- penthera-deps -->")) | .id' | head -n1)
+          if [ -n "$id" ]; then
+            gh api -X PATCH "repos/$REPO/issues/comments/$id" -F body=@"$body" > /dev/null
+          else
+            gh pr comment "$PR" --repo "$REPO" --body-file "$body"
+          fi
+
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: penthera-deps
+          path: |
+            ${{ runner.temp }}/deps-comment.md
+            ${{ runner.temp }}/deps.json
+            ${{ runner.temp }}/deps.md
+            ${{ runner.temp }}/deps.sarif
+
+      # Optional: block the merge when critical or high findings appear.
+      # - name: Fail on critical/high
+      #   if: steps.deps.outputs.code == '1'
+      #   run: exit 1

package/docs/examples/github-actions-scan.yml

@@ -0,0 +1,55 @@
+# Example: scan your staging URL with Penthera on a schedule.
+#
+# Copy this file into YOUR app's repo as `.github/workflows/penthera.yml` and add
+# a `PENTEST_STAGING_URL` repository secret. Only point it at a URL you own or are
+# authorized to test. Findings appear under Security > Code scanning.
+#
+# Pin the Penthera version (and, ideally, the actions below to commit SHAs) so a
+# scheduled run never picks up code you have not reviewed.
+
+name: Penthera security scan
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1" # weekly, Monday 06:00 UTC
+
+permissions:
+  contents: read
+
+jobs:
+  penthera:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+
+      - name: Scan staging URL
+        env:
+          PENTEST_URL: ${{ secrets.PENTEST_STAGING_URL }}
+        run: |
+          mkdir -p reports
+          set +e
+          npx --yes penthera@1.4.0 "$PENTEST_URL" \
+            --profile standard \
+            -o reports/scan.json \
+            --sarif reports/scan.sarif
+          code=$?
+          set -e
+          # Exit 1 = critical or high findings (reported via SARIF); only 2 (scan error) fails the job.
+          if [ "$code" -eq 2 ]; then exit 2; fi
+
+      - uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: reports/scan.sarif
+
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: penthera-reports
+          path: reports/

package/docs/examples/pr-dependency-review.yml

@@ -0,0 +1,56 @@
+# Example: comment a dependency capability diff on every PR that changes the lockfile.
+#
+# Copy this file into YOUR repo as `.github/workflows/pr-dependency-review.yml`.
+# The Penthera action reports packages that are new or that gained capabilities
+# (network, shell, install scripts, whole environment, dynamic code, ...) in one
+# PR comment, updated in place on every push, and uploads SARIF to code scanning.
+# Penthera runs offline from the action's own checkout: no npx, no registry
+# lookups, no telemetry. The only API call is the comment on your own PR.
+#
+# Pin the action to a release commit SHA. Find it with:
+#   git ls-remote https://github.com/danoszz/penthera refs/tags/v1.4.0
+#
+# Fork PRs get a read-only token: the comment is skipped and the diff goes to the
+# job summary instead. Do not switch this to `pull_request_target`; that would
+# run with write access next to untrusted code.
+
+name: Dependency review
+
+on:
+  pull_request:
+    paths:
+      - package-lock.json
+      - npm-shrinkwrap.json
+
+permissions:
+  contents: read
+  pull-requests: write
+  security-events: write
+
+jobs:
+  penthera:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0
+        with:
+          node-version: 22
+
+      # Optional but recommended: Penthera reads package code from node_modules
+      # and npm's cache. Installing both trees with --ignore-scripts (no package
+      # code runs) lets it inspect every changed version. Without this step the
+      # comment lists upgrades it could not compare.
+      - name: Install base and PR trees without running scripts
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        run: |
+          git fetch --no-tags --depth=1 origin "$BASE_SHA"
+          git worktree add --detach "$RUNNER_TEMP/base" "$BASE_SHA"
+          (cd "$RUNNER_TEMP/base" && npm ci --ignore-scripts --no-audit --no-fund)
+          npm ci --ignore-scripts --no-audit --no-fund
+
+      - uses: danoszz/penthera@0000000000000000000000000000000000000000 # v1.4.0 (replace with the release commit SHA)
+        with:
+          mode: deps
+          fail-on: none # or high / critical to block the merge

package/docs/funding/due-diligence-checklist.md

@@ -0,0 +1,79 @@
+# Due diligence checklist
+
+What a funder, sponsor or acquirer is likely to check, what is already in
+place, and what is still open. Checked on 2026-10-19 against the `main` branch
+at commit 156eda6.
+
+Legend: **Done**, **Open** (needs action), **Decide** (maintainer's call).
+
+## 1. Contributions and sign-off (DCO)
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Contributors are all known | Done | `git shortlog -sne --all`: 54 commits as "Daan van der Zwaag <daan@devign.it>", 6 as "Daan <daan@devign.it>" (same person, commits made in the GitHub web UI), 1 from dependabot. No outside human contributors. All 8 pull requests so far were opened by the maintainer or dependabot. |
+| DCO sign-off required | Open | The Developer Certificate of Origin 1.1 (https://developercertificate.org/) lets a contributor certify they have the right to submit their code under the project licence. This PR adds a DCO section to CONTRIBUTING.md. Enforcement is not on yet. To enforce, install a DCO check app on the repo, or turn on "Require contributors to sign off on web-based commits" in repository settings. |
+| Past commits | Decide | Past commits are not signed off, but all are by the maintainer, so no outside rights are in question. A short statement in the README or this file is enough; rewriting history is not worth it. |
+| Author identity | Open | Add a `.mailmap` mapping "Daan" to "Daan van der Zwaag" so tools show one author. |
+| AI-assisted commits | Done | 45 commit messages carry `Co-Authored-By: Claude ...` trailers, recording which work was AI-assisted. NLnet's GenAI policy names commit messages as one acceptable way to log this (https://nlnet.nl/foundation/policies/generativeAI/). |
+
+## 2. Licence and copyright
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Project licence | Done | MIT, in `LICENSE`, `package.json` and `.claude-plugin/plugin.json`. |
+| Copyright line | Open | `LICENSE` says "Copyright (c) 2026 daan". Change to the full legal name, or to a company if the maintainer moves the project into one: "Copyright (c) 2026 Daan van der Zwaag". |
+| Runtime dependencies | Done | One: `yaml` (ISC). Dev dependency: `vitest` (MIT). Both permissive. |
+| Third-party data in the source | Open | `lib/params.js` has a parameter wordlist with the comment "Curated from SecLists, Arjun defaults, and CommonCrawl analysis." SecLists is MIT and Arjun is AGPL-3.0 (GitHub licence metadata for both repositories). A list of common parameter names like `id` and `page` is unlikely to carry copyright on its own, but an acquirer's lawyer will ask. Options: document which entries came from where, or rebuild the list from MIT sources only and change the comment. Add a `THIRD_PARTY_NOTICES` file crediting SecLists. |
+| Other inspiration notes | Decide | The same file says "Inspired by: Arjun (6.2k stars), ParamSpider". Inspiration for an algorithm is fine; make sure no code was copied, and keep the note. |
+| Copyright of AI-assisted code | Decide | The US Copyright Office's report "Copyright and Artificial Intelligence, Part 2: Copyrightability" (29 January 2025, https://www.copyright.gov/ai/) addresses protection for AI-generated material. It is a US source; EU and Dutch law may differ. This matters little for an MIT project but may come up in an acquisition. Keep the co-author trailers as the record of human direction and review. Not legal advice. |
+| Assets | Done | `assets/` holds the project's own logo, social image and demo GIF. Confirm the logo was made by the maintainer or under a licence that allows transfer. |
+
+## 3. Name and trademark
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Existing "Penthera" company | Decide | Penthera (penthera.com) is a US company, founded around 2004 to 2005, that sells a video download SDK for mobile apps and describes itself as a SaaS company for streaming providers (https://www.penthera.com/about, https://pitchbook.com/profiles/company/61416-37). Different field (video delivery, not security), but the same word. A search found no registered PENTHERA mark; that search was not exhaustive. |
+| Similar name in security | Decide | Pentera (pentera.io), formerly Pcysys, sells automated security validation and pentesting software (https://en.wikipedia.org/wiki/Pentera). Pentera Security Ltd. has filed US trademark applications for PENTERA covering security software (https://trademarks.justia.com/owners/pentera-security-ltd-5403910). "Penthera" and "Pentera" differ by one letter in the same product category. This is the bigger risk: an acquirer will notice, and a confusion claim is plausible. |
+| Recommended next steps | Open | 1. Search EUIPO eSearch plus, TMview and the BOIP register for PENTHERA and PENTERA in classes 9 and 42. 2. Ask an IP lawyer for a short clearance opinion before spending on a filing or a brand. 3. If cleared, a Benelux filing at BOIP costs EUR 244 for one class (https://boip.int/en/node/2163, verify before filing); an EU trade mark at EUIPO costs more. 4. If not cleared, a rename is cheapest now, while adoption is small. |
+| npm and GitHub names | Done | `penthera` on npm and `danoszz/penthera` on GitHub are held by the maintainer. |
+
+## 4. Security posture of the project itself
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Pinned GitHub Actions | Done | Every `uses:` in `.github/workflows/` is pinned to a full commit SHA with the version in a comment. Dependabot proposes updates (an update to `actions/setup-node` is open as pull request #11). |
+| Staged npm publishing with 2FA | Done | `publish.yml` runs `npm stage publish`; nothing goes live until the maintainer approves the staged version with 2FA on npmjs.com. A hijacked workflow can stage, never ship. Merged in pull request #13. |
+| Trusted publishing, no stored token | Done | Publishing uses npm trusted publishing (OIDC). No npm token is stored in the repo or in secrets. |
+| npm provenance | Done | `--provenance` links each tarball to the workflow run and commit. |
+| CodeQL | Done | `.github/workflows/codeql.yml`. |
+| OpenSSF Scorecard | Done | Runs weekly and on push. Score 6.3 / 10 on 2026-10-19 (https://scorecard.dev/viewer/?uri=github.com/danoszz/penthera). |
+| Scorecard: Token-Permissions 0 | Open | Scorecard reports workflow tokens with excessive permissions. `publish.yml` grants `contents: write` and `id-token: write` at the top level; move them to the job and set `permissions: read-all` or `{}` at the top. Check the other workflows the same way. |
+| Scorecard: Code-Review 0 | Decide | 0 of 15 changesets were reviewed by a second person. Expected for a solo project. A second maintainer or an outside reviewer would fix it. |
+| Scorecard: Signed-Releases 0 | Open | Scorecard looks for signatures or provenance attached to GitHub Releases. npm provenance exists, but the GitHub Release has no signed artefact. Attaching the packed tarball with a provenance attestation (for example `actions/attest-build-provenance`) would cover it. |
+| Scorecard: CII-Best-Practices 0 | Open | Apply for the OpenSSF Best Practices badge (https://www.bestpractices.dev/). Most criteria are already met. |
+| Scorecard: Fuzzing 0 | Decide | Penthera has property-based API fuzzing as a feature, but the project's own code is not fuzzed. Low priority. |
+| Scorecard: Branch-Protection not scored | Open | Scorecard could not read branch protection (needs an admin token). Check that `main` requires PRs and passing CI. |
+| Security policy | Done | `SECURITY.md` with private advisory reporting, response times and safe harbour. |
+| Offline tests | Done | Tests do not reach the internet (CONTRIBUTING.md). |
+| No telemetry | Done | Stated in README "Privacy". An acquirer may want to verify it; the egress guard on the roadmap would make it testable. |
+
+## 5. Business and governance
+
+| Item | Status | Notes |
+|------|--------|-------|
+| Legal entity | Decide | The project is held by an individual. Funders such as NLnet accept individuals. An acquisition is simpler if the code, names and accounts sit in one entity. |
+| Accounts that would transfer | Open | List them: GitHub repo, npm package and its trusted publisher config, skills.sh listing, plugin marketplace entries, domain (if any), GitHub Sponsors profile. Make sure each has 2FA and a recovery path. |
+| Bus factor | Open | One maintainer. A documented release runbook exists (CONTRIBUTING.md, "Cutting a release"). Consider a second npm owner with 2FA for continuity. |
+| Funding history | Done | None so far. Keep a simple record of any grant or sponsorship income from the start. |
+| Claims in public material | Done | README and docs say "readiness" and "evidence", never "certified" or "compliant". Keep it that way in pitches. |
+
+## Sources
+
+- DCO 1.1: https://developercertificate.org/
+- NLnet GenAI policy: https://nlnet.nl/foundation/policies/generativeAI/
+- US Copyright Office AI reports: https://www.copyright.gov/ai/
+- Penthera (video SDK company): https://www.penthera.com/about , https://pitchbook.com/profiles/company/61416-37
+- Pentera: https://en.wikipedia.org/wiki/Pentera , https://trademarks.justia.com/owners/pentera-security-ltd-5403910
+- BOIP fees: https://boip.int/en/node/2163
+- OpenSSF Scorecard result: https://api.scorecard.dev/projects/github.com/danoszz/penthera
+- Arjun licence: https://github.com/s0md3v/Arjun ; SecLists licence: https://github.com/danielmiessler/SecLists