fullshield 3.0.0 → 3.1.1

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to FullShield are documented here.
 
+## 3.1.1 — 2026-10-28
+
+### Dependency parity
+
+- Phase 557: `FULLSHIELD_EXPERIMENTAL_BUMP_PR` adds `bumps plan` and `bumps open` for reachable high and critical bumps. It does not merge.
+- Phase 558: `FULLSHIELD_EXPERIMENTAL_LICENSE_POLICY` adds `DEPS-LICENSE-002` for direct-dependency license deny and allow lists. The message is a license policy, not a vulnerability.
+- Phase 559: `FULLSHIELD_EXPERIMENTAL_PRIVATE_REG` stores `deps.registry` and reads `DEPS-ORG-ADV-001` from a local org advisory cache. The private host is not contacted.
+- Phase 560: `FULLSHIELD_EXPERIMENTAL_EPSS_LOCAL` enriches findings from a local EPSS file. It does not download EPSS or KEV.
+- Phase 561: README states FullShield does not scan container images or OS packages. Trivy SARIF goes to `ingest`.
+- Phase 562: `FULLSHIELD_EXPERIMENTAL_EXCEPTIONS` loads `fullshield.exceptions.json` with owner, reason, and a 365-day expiry.
+- Phase 563: `init --recommended` writes a `scan --diff` workflow. Default scan without `--diff` is unchanged.
+
 ## 3.0.0 — 2026-10-28
 
 ### Scheduler

package/README.md

@@ -1,6 +1,6 @@
 # FullShield
 
-**v3.0.0.** One install for Node.js/TypeScript backends: detect → classify → report → notify → fix → gate (CI `--fail-on` + runtime monitor). It does not stop attacks by itself. Scan when you want with `npx fullshield scan`, or install an every-2-hours timer with `npx fullshield schedule install`.
+**v3.1.1.** One install for Node.js/TypeScript backends: detect → classify → report → notify → fix → gate (CI `--fail-on` + runtime monitor). It does not stop attacks by itself. Scan when you want with `npx fullshield scan`, or install an every-2-hours timer with `npx fullshield schedule install`.
 
 **Headline: dependency reachability.** A lockfile CVE is not the same as an unused package. FullShield classifies each OSV hit as `reachable` (imported and called), `imported-not-called` (−1), `reachable-via-dependency` (lockfile path from an imported direct dep — **severity kept**, path shown, e.g. `express > body-parser > qs`), `not-imported` (−2, only when no such path exists), or `reachability-unknown` (severity kept) when the lockfile format has no parsed dependency edges. DevDependency-only vulns are `info` with a `dev-only` note unless production sources import the package. Pair it with `fullshield sbom --format cyclonedx`.
 
@@ -10,16 +10,16 @@ npx fullshield scan --json --fail-on high
 npx fullshield scan --sarif fullshield.sarif
 ```
 
-3.0.0 is the version of this tree. `schedule install` writes `fullShieldReport/fullShieldReport_YYYYMMDD_HHMM.md` every 2 hours and keeps 60 reports. `scan` does not create that folder. The stable contract is [docs/stability.md](docs/stability.md). The 1.0.1 release moved values that only experimental flags produce out of Stable. Experimental flags stay off unless you set them. Do not treat a scan as a penetration test. Reviewed recall for untouched apps is not published. From `bench/perf-v2.json` (`measured: true`, `label: unreviewed`), the stored Next.js cold p50 is 107.95 seconds — still above the 60-second target (target unmet). Default scans share one AST, run modules in parallel, and use lazy taint. Multi-workspace repos scan each workspace lockfile by default; single-package finding keys stay the same as 2.3.0.
+3.1.1 is the version of this tree. `schedule install` writes `fullShieldReport/fullShieldReport_YYYYMMDD_HHMM.md` every 2 hours and keeps 60 reports. `scan` does not create that folder. The stable contract is [docs/stability.md](docs/stability.md). The 1.0.1 release moved values that only experimental flags produce out of Stable. Experimental flags stay off unless you set them. Do not treat a scan as a penetration test. Reviewed recall for untouched apps is not published. From `bench/perf-v2.json` (`measured: true`, `label: unreviewed`), the stored Next.js cold p50 is 107.95 seconds — still above the 60-second target (target unmet). Default scans share one AST, run modules in parallel, and use lazy taint. Multi-workspace repos scan each workspace lockfile by default; single-package finding keys stay the same as 2.3.0.
 
 ## Verify in 60 seconds
 
 ```bash
 # fresh temp / empty cache is enough — no install-guard phones home
-npx fullshield@3.0.0 --version
+npx fullshield@3.1.1 --version
 ```
 
-Package page: [npmjs.com/package/fullshield](https://www.npmjs.com/package/fullshield). Release tag: [v3.0.0](https://github.com/kathanp/fullshield/releases/tag/v3.0.0). Publish stages with npm provenance (OIDC). After install, the stranger checks in the build spec (scan / json / sarif / fail-on / fix / init / sbom) are the post-publish gate — no Rekor/sigstore SaaS dependency in the CLI.
+Package page: [npmjs.com/package/fullshield](https://www.npmjs.com/package/fullshield). Release tag: [v3.1.1](https://github.com/kathanp/fullshield/releases/tag/v3.1.1). Publish stages with npm provenance (OIDC). After install, the stranger checks in the build spec (scan / json / sarif / fail-on / fix / init / sbom) are the post-publish gate — no Rekor/sigstore SaaS dependency in the CLI.
 
 ## GitHub Action
 
@@ -28,7 +28,7 @@ Copy `templates/action/` into your repo (or use `kathanp/fullshield-action` once
 ```yaml
 - uses: your-org/your-repo/.github/actions/fullshield@<commit-sha>
   with:
-    version: '3.0.0'
+    version: '3.1.1'
 ```
 
 Or run `npx fullshield init --recommended` to write `profile: "recommended"` and a workflow that calls `./templates/action`. The Action runs `fullshield scan`, uploads SARIF, and may cache the baseline. It does not post a pull-request comment, open issues, or phone home.
@@ -86,6 +86,7 @@ Contributor quality gate: [docs/QUALITY.md](docs/QUALITY.md) (`npm run quality`)
 - Cross-file taint follows `require`/`import` and method calls up to 5 hops and records a `trace` (also SARIF `codeFlows`). Nested closures and some dynamic dispatch are still missed.
 - Runtime v1 is **signature-based** (payload regex + rate limit + body-size guard). It is a **stopgap monitor**, not a WAF. Prefer **`mode: 'monitor'`** in production until you have measured false-positive rate. Sink-hooking RASP is **experimental** (off by default; see below) and does not claim to prevent attacks.
 - Only scan hosts and repos you own or are authorized to test.
+- Does **not** scan container images or OS packages. Pass a Trivy SARIF file you already produced to `fullshield ingest`. FullShield does not pretend to be a container scanner.
 - **Experimental features are off by default and are not product claims:**
   - RASP / virtual patches / honeytokens / threat auto-block: fail-open hooks; decoy-route hits are low and never auto-block; auto-block is opt-in (shared-IP / NAT risk).
   - `install` / supply-chain: static heuristics only; never a substitute for `npm audit` policy or a malware sandbox.
@@ -261,7 +262,12 @@ app.use(shieldGuard({ mode: 'monitor', authRoutes: ['/login'] }));
 | `iac` | **Experimental** light IaC (`FULLSHIELD_EXPERIMENTAL_IAC=1`): GHA, Terraform, Kubernetes, docker-compose. Not a full IaC scanner. |
 | `agent` | **Experimental** remediation agent (`FULLSHIELD_EXPERIMENTAL_AGENT=1`). Mock/localhost GitHub API + local git remote only — never a real network. Never merges, never pushes to `main`/`master`. `--max-prs` (default 3). |
 | `scan --changed` / `--since` | **Experimental** incremental scan (`FULLSHIELD_EXPERIMENTAL_PLATFORM=1`). |
-| `scan --diff` | **Experimental** (`FULLSHIELD_EXPERIMENTAL_DIFFSCAN=1` or `--experimental-diffscan`). Scans git-changed JS/TS files, the files they import by a relative literal, and the files that import them the same way. One hop. A sink in an unchanged importer still reports when the changed file returns the request value. A git failure is `FS-E018` and does not scan the rest of the tree. Off, or `scan` without `--diff`, matches today's scan. |
+| `scan --diff` | **Experimental** (`FULLSHIELD_EXPERIMENTAL_DIFFSCAN=1` or `--experimental-diffscan`). Scans git-changed JS/TS files, the files they import by a relative literal, and the files that import them the same way. One hop. A sink in an unchanged importer still reports when the changed file returns the request value. A git failure is `FS-E018` and does not scan the rest of the tree. Off, or `scan` without `--diff`, matches today's scan. `init --recommended` writes `.github/workflows/fullshield-diff.yml`, which sets `FULLSHIELD_EXPERIMENTAL_DIFFSCAN=1` and runs `scan --diff`. |
+| `bumps plan` / `bumps open` | **Experimental** (`FULLSHIELD_EXPERIMENTAL_BUMP_PR=1`). Ranks reachable high and critical `DEPS-VULN-001` bumps from a local `scan --json` file (`--from`). `open` runs `gh pr create` once per row and never merges. Not-imported and below-high rows are omitted. `templates/fullshield-bumps.yml` is a nightly copy-in workflow. |
+| License policy | **Experimental** (`FULLSHIELD_EXPERIMENTAL_LICENSE_POLICY=1`). `deps.licenseDeny` and `deps.licenseAllow` match the installed direct dependency `license` string. `DEPS-LICENSE-002` is a license policy, not a vulnerability. A missing license stays silent. |
+| Private registry | **Experimental** (`FULLSHIELD_EXPERIMENTAL_PRIVATE_REG=1`). `deps.registry` must be https with no userinfo. The host is not contacted and is not added to the allowlist. Org advisories are read from `<cacheDir>/org-advisories.json` (`DEPS-ORG-ADV-001`), at most 1000000 bytes. |
+| Local EPSS / KEV | **Experimental** (`FULLSHIELD_EXPERIMENTAL_EPSS_LOCAL=1`). `deps.epssFile` is local JSON. `epss` is from 0 to 1. Sets `epss`, `kev`, and `epssPriority` = `(kev ? 1000 : 0) + round(epss * 100) + (reachable ? 10 : 0) + severity points` (critical 4, high 3, medium 2, low 1, info 0). No download. EPSS and CISA hosts stay blocked. |
+| Exceptions file | **Experimental** (`FULLSHIELD_EXPERIMENTAL_EXCEPTIONS=1`). `fullshield.exceptions.json` rows need `owner`, `reason`, and ISO `expires` within 365 days. Expired rows fail CI and do not suppress. There is no forever exception. |
 | `scan --experimental-flow2` | **Stable.** One object field (`obj.a`) and one nested function are part of the default scan. `FULLSHIELD_EXPERIMENTAL_FLOW2` and this flag stay accepted and do not turn that off. `obj.b` stays clean. `JSON.parse` does not clear taint. Handlebars `{{ }}`, `res.json`, and a `url.includes` allowlist helper stay unflagged. |
 | `dev` | **Experimental** save loop (`FULLSHIELD_EXPERIMENTAL_DEV=1`). Watches the project and prints only new and resolved findings. |
 | `scan --experimental-sast-gaps` | **Stable.** ORM raw SQL, `spawn('sh', ['-c'])`, execa `shell: true`, and zx `$.raw` are part of the default scan. `FULLSHIELD_EXPERIMENTAL_SAST_GAPS` and this flag stay accepted and do not turn that off. |