fullshield 0.3.0 → 1.0.0

package/models/index.json

@@ -0,0 +1,356 @@
+{
+  "fullshieldVersion": "1.0.0",
+  "entries": [
+    {
+      "package": "express",
+      "versionRange": "^4.0.0 || ^5.0.0",
+      "kind": "source",
+      "sinkClass": "sqli",
+      "memberPath": "req.get",
+      "argumentIndex": 0,
+      "reference": "https://expressjs.com/en/4x/api.html#req.get"
+    },
+    {
+      "package": "express",
+      "versionRange": "^4.0.0 || ^5.0.0",
+      "kind": "source",
+      "sinkClass": "sqli",
+      "memberPath": "req.body",
+      "argumentIndex": 0,
+      "reference": "https://expressjs.com/en/4x/api.html#req.body"
+    },
+    {
+      "package": "express",
+      "versionRange": "^4.0.0 || ^5.0.0",
+      "kind": "source",
+      "sinkClass": "sqli",
+      "memberPath": "req.query",
+      "argumentIndex": 0,
+      "reference": "https://expressjs.com/en/4x/api.html#req.query"
+    },
+    {
+      "package": "express",
+      "versionRange": "^4.0.0 || ^5.0.0",
+      "kind": "source",
+      "sinkClass": "sqli",
+      "memberPath": "req.params",
+      "argumentIndex": 0,
+      "reference": "https://expressjs.com/en/4x/api.html#req.params"
+    },
+    {
+      "package": "express-validator",
+      "versionRange": ">=6.0.0 <8.0.0",
+      "kind": "validator",
+      "sinkClass": "sqli",
+      "memberPath": "body().isInt",
+      "argumentIndex": 0,
+      "reference": "https://express-validator.github.io/docs/api/validation-chain/"
+    },
+    {
+      "package": "express-validator",
+      "versionRange": ">=6.0.0 <8.0.0",
+      "kind": "validator",
+      "sinkClass": "sqli",
+      "memberPath": "query().isInt",
+      "argumentIndex": 0,
+      "reference": "https://express-validator.github.io/docs/api/validation-chain/"
+    },
+    {
+      "package": "express-validator",
+      "versionRange": ">=6.0.0 <8.0.0",
+      "kind": "validator",
+      "sinkClass": "sqli",
+      "memberPath": "param().isInt",
+      "argumentIndex": 0,
+      "reference": "https://express-validator.github.io/docs/api/validation-chain/"
+    },
+    {
+      "package": "joi",
+      "versionRange": ">=17.0.0 <18.0.0",
+      "kind": "validator",
+      "sinkClass": "sqli",
+      "memberPath": "Joi.number().validate",
+      "argumentIndex": 0,
+      "reference": "https://joi.dev/api/?v=17.13.3#number"
+    },
+    {
+      "package": "yup",
+      "versionRange": ">=0.32.0 <2.0.0",
+      "kind": "validator",
+      "sinkClass": "sqli",
+      "memberPath": "yup.number().validate",
+      "argumentIndex": 0,
+      "reference": "https://github.com/jquense/yup#number"
+    },
+    {
+      "package": "zod",
+      "versionRange": ">=3.0.0 <5.0.0",
+      "kind": "validator",
+      "sinkClass": "sqli",
+      "memberPath": "z.number().parse",
+      "argumentIndex": 0,
+      "reference": "https://zod.dev/api"
+    },
+    {
+      "package": "validator",
+      "versionRange": ">=13.0.0 <14.0.0",
+      "kind": "validator",
+      "sinkClass": "sqli",
+      "memberPath": "validator.isInt",
+      "argumentIndex": 0,
+      "reference": "https://github.com/validatorjs/validator.js#validators"
+    },
+    {
+      "package": "dompurify",
+      "versionRange": ">=2.0.0 <4.0.0",
+      "kind": "sanitizer",
+      "sinkClass": "xss",
+      "memberPath": "DOMPurify.sanitize",
+      "argumentIndex": 0,
+      "reference": "https://github.com/cure53/DOMPurify#how-do-i-use-it"
+    },
+    {
+      "package": "sanitize-html",
+      "versionRange": ">=2.0.0 <3.0.0",
+      "kind": "sanitizer",
+      "sinkClass": "xss",
+      "memberPath": "sanitizeHtml",
+      "argumentIndex": 0,
+      "reference": "https://github.com/apostrophecms/sanitize-html#readme"
+    },
+    {
+      "package": "helmet",
+      "versionRange": ">=4.0.0 <8.0.0",
+      "kind": "sanitizer",
+      "sinkClass": "xss",
+      "memberPath": "helmet",
+      "argumentIndex": 0,
+      "reference": "https://helmetjs.github.io/"
+    },
+    {
+      "package": "pg",
+      "versionRange": ">=8.0.0 <9.0.0",
+      "kind": "sink",
+      "sinkClass": "sqli",
+      "memberPath": "query",
+      "argumentIndex": 0,
+      "reference": "https://node-postgres.com/apis/client"
+    },
+    {
+      "package": "mysql2",
+      "versionRange": ">=3.0.0 <4.0.0",
+      "kind": "sink",
+      "sinkClass": "sqli",
+      "memberPath": "query",
+      "argumentIndex": 0,
+      "reference": "https://sidorares.github.io/node-mysql2/docs"
+    },
+    {
+      "package": "sqlite3",
+      "versionRange": ">=5.0.0 <6.0.0",
+      "kind": "sink",
+      "sinkClass": "sqli",
+      "memberPath": "run",
+      "argumentIndex": 0,
+      "reference": "https://github.com/TryGhost/node-sqlite3/wiki/API"
+    },
+    {
+      "package": "better-sqlite3",
+      "versionRange": ">=9.0.0 <12.0.0",
+      "kind": "sink",
+      "sinkClass": "sqli",
+      "memberPath": "prepare",
+      "argumentIndex": 0,
+      "reference": "https://github.com/WiseLibs/better-sqlite3/blob/master/docs/api.md"
+    },
+    {
+      "package": "knex",
+      "versionRange": ">=2.0.0 <4.0.0",
+      "kind": "sink",
+      "sinkClass": "sqli",
+      "memberPath": "raw",
+      "argumentIndex": 0,
+      "reference": "https://knexjs.org/guide/raw.html"
+    },
+    {
+      "package": "sequelize",
+      "versionRange": ">=6.0.0 <7.0.0",
+      "kind": "sink",
+      "sinkClass": "sqli",
+      "memberPath": "query",
+      "argumentIndex": 0,
+      "reference": "https://sequelize.org/docs/v6/core-concepts/raw-queries/"
+    },
+    {
+      "package": "typeorm",
+      "versionRange": ">=0.3.0 <0.4.0",
+      "kind": "sink",
+      "sinkClass": "sqli",
+      "memberPath": "query",
+      "argumentIndex": 0,
+      "reference": "https://typeorm.io/docs/query-builder/select-query-builder/"
+    },
+    {
+      "package": "prisma",
+      "versionRange": ">=5.0.0 <7.0.0",
+      "kind": "sink",
+      "sinkClass": "sqli",
+      "memberPath": "$queryRawUnsafe",
+      "argumentIndex": 0,
+      "reference": "https://www.prisma.io/docs/orm/prisma-client/using-raw-sql/raw-queries"
+    },
+    {
+      "package": "mongoose",
+      "versionRange": ">=6.0.0 <9.0.0",
+      "kind": "sink",
+      "sinkClass": "nosqli",
+      "memberPath": "find",
+      "argumentIndex": 0,
+      "reference": "https://mongoosejs.com/docs/api/model.html#Model.find()"
+    },
+    {
+      "package": "mongodb",
+      "versionRange": ">=4.0.0 <7.0.0",
+      "kind": "sink",
+      "sinkClass": "nosqli",
+      "memberPath": "find",
+      "argumentIndex": 0,
+      "reference": "https://www.mongodb.com/docs/drivers/node/current/fundamentals/crud/read-operations/query-document/"
+    },
+    {
+      "package": "child_process",
+      "versionRange": ">=18.0.0",
+      "kind": "sink",
+      "sinkClass": "cmdi",
+      "memberPath": "exec",
+      "argumentIndex": 0,
+      "reference": "https://nodejs.org/api/child_process.html#child_processexeccommand-options-callback"
+    },
+    {
+      "package": "execa",
+      "versionRange": ">=8.0.0 <9.0.0",
+      "kind": "sink",
+      "sinkClass": "cmdi",
+      "memberPath": "execa",
+      "argumentIndex": 0,
+      "reference": "https://github.com/sindresorhus/execa#execafile-arguments-options"
+    },
+    {
+      "package": "axios",
+      "versionRange": ">=1.0.0 <2.0.0",
+      "kind": "sink",
+      "sinkClass": "ssrf",
+      "memberPath": "axios.get",
+      "argumentIndex": 0,
+      "reference": "https://axios-http.com/docs/api_intro"
+    },
+    {
+      "package": "node-fetch",
+      "versionRange": ">=3.0.0 <4.0.0",
+      "kind": "sink",
+      "sinkClass": "ssrf",
+      "memberPath": "fetch",
+      "argumentIndex": 0,
+      "reference": "https://github.com/node-fetch/node-fetch#fetchurl-options"
+    },
+    {
+      "package": "undici",
+      "versionRange": ">=6.0.0 <8.0.0",
+      "kind": "sink",
+      "sinkClass": "ssrf",
+      "memberPath": "undici.request",
+      "argumentIndex": 0,
+      "reference": "https://undici.nodejs.org/#/docs/api/Client"
+    },
+    {
+      "package": "got",
+      "versionRange": ">=14.0.0 <15.0.0",
+      "kind": "sink",
+      "sinkClass": "ssrf",
+      "memberPath": "got",
+      "argumentIndex": 0,
+      "reference": "https://github.com/sindresorhus/got#goturl-options"
+    },
+    {
+      "package": "fs",
+      "versionRange": ">=18.0.0",
+      "kind": "sink",
+      "sinkClass": "path",
+      "memberPath": "readFile",
+      "argumentIndex": 0,
+      "reference": "https://nodejs.org/api/fs.html#fsreadfilepath-options-callback"
+    },
+    {
+      "package": "fs-extra",
+      "versionRange": ">=11.0.0 <12.0.0",
+      "kind": "sink",
+      "sinkClass": "path",
+      "memberPath": "readFile",
+      "argumentIndex": 0,
+      "reference": "https://github.com/jprichardson/node-fs-extra"
+    },
+    {
+      "package": "path",
+      "versionRange": ">=18.0.0",
+      "kind": "sanitizer",
+      "sinkClass": "path",
+      "memberPath": "path.basename",
+      "argumentIndex": 0,
+      "reference": "https://nodejs.org/api/path.html#pathbasenamepath-suffix"
+    },
+    {
+      "package": "ejs",
+      "versionRange": ">=3.0.0 <4.0.0",
+      "kind": "sink",
+      "sinkClass": "xss",
+      "memberPath": "ejs.render",
+      "argumentIndex": 0,
+      "reference": "https://ejs.co/#docs"
+    },
+    {
+      "package": "pug",
+      "versionRange": ">=3.0.0 <4.0.0",
+      "kind": "sink",
+      "sinkClass": "xss",
+      "memberPath": "pug.render",
+      "argumentIndex": 0,
+      "reference": "https://pugjs.org/api/reference.html"
+    },
+    {
+      "package": "handlebars",
+      "versionRange": ">=4.0.0 <5.0.0",
+      "kind": "sink",
+      "sinkClass": "xss",
+      "memberPath": "Handlebars.compile",
+      "argumentIndex": 0,
+      "reference": "https://handlebarsjs.com/api-reference/compilation.html"
+    },
+    {
+      "package": "nunjucks",
+      "versionRange": ">=3.0.0 <4.0.0",
+      "kind": "sink",
+      "sinkClass": "xss",
+      "memberPath": "nunjucks.renderString",
+      "argumentIndex": 0,
+      "reference": "https://mozilla.github.io/nunjucks/api.html#renderstring"
+    },
+    {
+      "package": "jsonwebtoken",
+      "versionRange": ">=9.0.0 <10.0.0",
+      "kind": "sink",
+      "sinkClass": "jwt",
+      "memberPath": "jwt.verify",
+      "argumentIndex": 0,
+      "reference": "https://github.com/auth0/node-jsonwebtoken#jwtverifytoken-secretorpublickey-options-callback"
+    },
+    {
+      "package": "bcrypt",
+      "versionRange": ">=5.0.0 <6.0.0",
+      "kind": "sanitizer",
+      "sinkClass": "crypto",
+      "memberPath": "bcrypt.hash",
+      "argumentIndex": 0,
+      "reference": "https://github.com/kelektiv/node.bcrypt.js#hash-info"
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fullshield",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Full-cycle security scanner for Node.js/TypeScript backends: detect, classify, report, notify, fix, prevent.",
   "license": "MIT",
   "type": "module",
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/kathanp/fullshield.git"
   },
   "engines": {
-    "node": ">=20.11"
+    "node": ">=22.13"
   },
   "bin": {
     "fullshield": "dist/cli/index.js"
@@ -33,11 +33,13 @@
     "./package.json": "./package.json"
   },
   "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "express": "*",
     "fastify": "*",
-    "koa": "*",
     "hono": "*",
-    "@modelcontextprotocol/sdk": "^1.32.1",
+    "koa": "*",
+    "typescript": ">=5.0.0",
+    "yaml": "^2.8.0",
     "zod": "^4.6.7"
   },
   "peerDependenciesMeta": {
@@ -58,6 +60,12 @@
     },
     "zod": {
       "optional": true
+    },
+    "typescript": {
+      "optional": true
+    },
+    "yaml": {
+      "optional": true
     }
   },
   "files": [
@@ -67,13 +75,14 @@
     "LICENSE",
     "CHANGELOG.md",
     "templates",
-    "rules"
+    "rules",
+    "models"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsup",
+    "build": "node scripts/atomic-build.mjs",
     "typecheck": "tsc --noEmit",
     "lint": "eslint . --max-warnings 0",
     "test": "vitest run",
@@ -84,7 +93,8 @@
     "bench": "node scripts/bench.mjs",
     "bench:public": "node scripts/bench-public.mjs",
     "verify": "node scripts/verify.mjs",
-    "verify:phase": "node scripts/verify.mjs --phase"
+    "verify:phase": "node scripts/verify.mjs --phase",
+    "quality": "node scripts/quality.mjs"
   },
   "dependencies": {
     "@typescript-eslint/typescript-estree": "^8.71.2",
@@ -93,17 +103,22 @@
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
-    "@modelcontextprotocol/sdk": "^1.32.1",
     "@eslint/js": "^9.14.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@types/node": "^22.9.0",
     "@vitest/coverage-v8": "^2.1.4",
     "eslint": "^9.14.0",
     "express": "^4.22.3",
     "globals": "^15.12.0",
+    "knip": "^6.42.1",
     "tsup": "^8.3.5",
     "typescript": "^5.6.3",
     "typescript-eslint": "^8.13.0",
     "vitest": "^2.1.4",
+    "yaml": "^2.8.0",
     "zod": "^4.6.7"
+  },
+  "knip": {
+    "ignore": ["test/fixtures/**"]
   }
 }

package/rules/DEPS-LOCKMISMATCH-001.md

@@ -0,0 +1,7 @@
+# DEPS-LOCKMISMATCH-001
+
+A locked version does not satisfy the range in `package.json`.
+
+## Remediation
+
+Regenerate the lockfile so the locked version satisfies the declared range. Do not guess a version.

package/rules/DEPS-PHANTOM-001.md

@@ -0,0 +1,7 @@
+# DEPS-PHANTOM-001
+
+An import names a package that is not in `dependencies`, `devDependencies`, `optionalDependencies`, or `peerDependencies`. Node built-ins and relative imports are not packages. An import under `test/`, `tests/`, `__tests__/`, `scripts/`, `seeds/`, or a `*.test.*` / `*.spec.*` file is severity low. Other paths stay medium. A package declared in `devDependencies` is not reported on those paths.
+
+## Remediation
+
+Add the package to `package.json`, or remove the import.

package/rules/README.md

@@ -1,5 +1,7 @@
 # FullShield rules
 
+New work is `SECURITY_SCANNER_SPEC.md` Section 32. These pages describe rules that already exist. They are not the Phase 46–59 designs.
+
 Each Core rule has a positive fixture in `test/fixtures/vulnerable-app` and a
 negative counterpart in `test/fixtures/clean-app`.
 
@@ -29,6 +31,7 @@ negative counterpart in `test/fixtures/clean-app`.
 | [DEPS-TYPOSQUAT-001](DEPS-TYPOSQUAT-001.md) | Direct dep 1 edit from a popular name |
 | [DEPS-DEPRECATED-001](DEPS-DEPRECATED-001.md) | Lockfile `deprecated` field |
 | [DEPS-NOLOCK-001](DEPS-NOLOCK-001.md) | package.json without a lockfile |
+| [SUPPLY-PROV-001](SUPPLY-PROV-001.md) | Experimental: provenance regression, publisher change, or new release |
 | [SUPPLY-WORM-001](SUPPLY-WORM-001.md) | Experimental: token read + publish/registry/GitHub/workflow write |
 | [SUPPLY-WORKFLOW-001](SUPPLY-WORKFLOW-001.md) | Experimental: dep writes `.github/` / git hooks / CI config |
 

package/rules/SECRET-AWS-001.md

@@ -2,6 +2,12 @@
 
 **AWS access key.** CWE-798.
 
+## Placeholder
+
+`FULLSHIELD_EXPERIMENTAL_SECRET_CHECK` treats the documented example access key ID `AKIAIOSFODNN7EXAMPLE` as a placeholder. Confidence is lowered. The finding stays, and severity is unchanged.
+
+https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html
+
 ## Remediation
 
 Rotate the key. Load it from the environment. Removing it from the file is not enough — it stays in git history.

package/rules/SECRET-GITHUB-001.md

@@ -2,6 +2,12 @@
 
 **GitHub token.** CWE-798.
 
+## Checksum
+
+`FULLSHIELD_EXPERIMENTAL_SECRET_CHECK` validates the public CRC-32 suffix for `ghp_`, `gho_`, `ghu_`, `ghs_`, `ghr_`, and `github_pat_` tokens. The checksum is CRC-32/IEEE of the token body excluding the last six characters, written as six base62 characters (`0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz`). A failed check lowers confidence only. It does not raise severity or remove the finding. Other issuers have no checksum logic here.
+
+https://github.blog/2021-04-05-behind-githubs-new-authentication-token-formats/
+
 ## Remediation
 
 Revoke the token and store a new one in env/CI secrets.

package/rules/SUPPLY-CAP-001.md

@@ -0,0 +1,17 @@
+# SUPPLY-CAP-001
+
+**Dependency capability denied by policy (static).** CWE-829.
+
+Experimental (`FULLSHIELD_EXPERIMENTAL_CAPABILITIES=1`). A `deps.capabilityPolicy` `deny` rule matched a capability read from already-installed package files. High. Never executes package code and never runs install scripts. Absent from the default scan.
+
+Capabilities: `child_process`, `net` (`net` / `http` / `https` / `dgram` / `fetch`), `fs_write`, `env` (`process.env`), `eval` (`eval`, `new Function`, `vm`), `native` (`.node`, `binding.gyp`), `dynamic_require`, `install_script` (`preinstall` / `install` / `postinstall`), `obfuscation` (Phase 70 `eval` of a decoded string, a 64+ hex run, an 80+ base64 run, or eight `\xNN` escapes).
+
+`fullshield deps --capabilities` prints each direct dependency's own capabilities plus those of its transitive packages, with the package version that introduces each one. `deps-diff` adds `newCapabilities` only when this flag is also set. A bump is reported only when the previous integrity is already in the capability cache.
+
+## False-positive risk
+
+The check is textual. A comment, string, or example that mentions `process.env`, `writeFile`, or `require('net')` is counted. The negative fixture is a package that only calls `fs.readFileSync` and whose `scripts.test` is not an install script. `warn` policy does not emit this rule. A deny glob that names a capability the package does not have does not emit it.
+
+## Remediation
+
+Remove the package, or change `deps.capabilityPolicy` if the capability is expected. Do not run the package's install script to investigate it.

package/rules/SUPPLY-CHAINC2-001.md

@@ -0,0 +1,3 @@
+# SUPPLY-CHAINC2-001
+
+A package file names a public blockchain RPC method (`getSignaturesForAddress` or `eth_getLogs`) and also fetches or evaluates a value. Either signal alone is not a finding. Experimental: `FULLSHIELD_EXPERIMENTAL_SUPPLY=1`. Static only. Fixtures use `example.invalid`.

package/rules/SUPPLY-PLATFORMGATE-001.md

@@ -0,0 +1,3 @@
+# SUPPLY-PLATFORMGATE-001
+
+A `process.platform === 'win32'` or `os.platform()` check, a download, and a process spawn or executable write all appear in the same file. One of those signals alone is not a finding. Experimental: `FULLSHIELD_EXPERIMENTAL_SUPPLY=1`. Fixtures use `example.invalid`.

package/rules/SUPPLY-PROV-001.md

@@ -0,0 +1,15 @@
+# SUPPLY-PROV-001
+
+Experimental (`FULLSHIELD_EXPERIMENTAL_PROVENANCE=1`). Informational registry signal for an installed package version. Severity is medium. The finding does not say the package is malicious. `DEPS-MALICIOUS-001` still comes only from an OSV `MAL-` advisory.
+
+The registry host is `registry.npmjs.org` only. One packument request per package, at most 8 at a time, and `Retry-After` is honored. Results are stored in the Phase 62 registry cache (`<cache>/registry/<name>.json`). `--offline` reads that cache only.
+
+Signals, when the packument lists the installed version:
+
+- **provenance-regression** — an earlier version has `dist.attestations` and the installed version does not.
+- **publisher-change** — the publishing user (`_npmUser` or `npmUser`) published none of the previous 10 versions.
+- **new-release** — the same age check as Phase 62 (`releaseAgeLabel`, default 72 hours).
+
+Missing cache data, a missing version, or an offline miss stays `unknown` and produces no finding.
+
+False-positive risk: a maintainer can publish a young release, rotate the npm user, or drop attestations without anything being wrong. The negative fixture is an aged version that still has attestations and the same publisher as the previous versions; it produces no finding.

package/rules/SUPPLY-SECHOLDER-001.md

@@ -0,0 +1,3 @@
+# SUPPLY-SECHOLDER-001
+
+The registry `latest` dist-tag for a locked package is npm's removed-for-security placeholder `0.0.1-security`, and the locked version is not that placeholder. Missing registry data produces no finding. `--offline` reads the cache only. Critical. Not downgraded by reachability. Remove the package, delete `node_modules`, reinstall from a clean lockfile, and rotate credentials the machine could read.

package/rules/SUPPLY-STEALER-001.md

@@ -0,0 +1,3 @@
+# SUPPLY-STEALER-001
+
+A package file names a browser, Discord, or wallet store path and also makes a network call. A path alone, or a network call alone, is not a finding. Experimental: `FULLSHIELD_EXPERIMENTAL_SUPPLY=1`. Critical. Not downgraded by reachability.