sfscanner 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 n8n-secureflow contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# sfscanner 🔍
+
+**Deterministic, offline security scanning for n8n workflows** — JSON, NDJSON, a table, or SARIF 2.1.0. The workflow never leaves your machine.
+
+> **Licensing:** MIT for this package's code and scanner tooling. The catalogue dataset has separate Personal / Non-Commercial terms; see https://github.com/jitwark/n8n-Secureflow/blob/main/docs/LICENSING.md.
+
+```bash
+npx sfscanner scan my-workflow.json
+```
+
+> This package is the scanner. The workflow **catalogue** — 11,464 public n8n workflows, their
+> provenance and how much of each one the scanner could actually read — lives on the website:
+> <https://n8n-enterprise-1.web.app>.
+
+---
+
+## ⚡ Quickstart
+
+```bash
+# one file, human-readable
+npx sfscanner --schema v2 scan workflow.json --format table
+
+# a directory, SARIF for GitHub code scanning
+npx sfscanner --schema v2 scan ./workflows --format sarif > results.sarif
+
+# pipe a workflow straight from a clipboard or curl
+cat workflow.json | npx sfscanner scan -
+
+# see the rules, then read one in full
+npx sfscanner --schema v2 rules --format table
+npx sfscanner --schema v2 explain N8N_EXECUTE_COMMAND
+```
+
+Node **22** is the only supported line (`engines: >=22 <23`). The CLI is ESM-only and no CommonJS artifact is shipped; `require('sfscanner')` is not supported. Runs have been verified on Windows; Linux and macOS are not yet a verified matrix.
+
+---
+
+## 🧠 What it actually checks
+
+Seven admitted rules in the `beta-default` profile. Every row carries a severity, a confidence and a
+CWE: these are deterministic pattern and configuration matches, **not** a safety guarantee, and not a
+verdict about whether a workflow is safe to run.
+
+| Rule | Severity | Confidence | CWE |
+| --- | --- | --- | --- |
+| `N8N_EXECUTE_COMMAND` | CRITICAL | HIGH | CWE-78 |
+| `N8N_CODE_NODE` | LOW | HIGH | CWE-94 |
+| `RAW_AUTH_HEADER` | HIGH | MEDIUM | CWE-522, CWE-798 |
+| `RAW_SECRET_INDICATOR` | HIGH | MEDIUM | CWE-798 |
+| `UNAPPROVED_DOMAIN` | MEDIUM | HIGH | — |
+| `UNKNOWN_NODE_PACKAGE` | LOW | MEDIUM | CWE-1357 |
+| `WEBHOOK_EXPOSURE` | MEDIUM | MEDIUM | CWE-306 |
+
+The `beta-hardened` profile is **defined but not admitted** — `sfscanner --schema v2 profiles` says
+so, and selecting it fails instead of silently running something weaker.
+
+---
+
+## 📤 Output and exit codes
+
+Formats: `json` (default), `ndjson`, `sarif`, `table`. SARIF is 2.1.0 with CWE tags, so GitHub,
+GitLab and VS Code can read it directly.
+
+| Exit | Meaning |
+| :---: | --- |
+| `0` | Clean — nothing met the `--fail-on` threshold. |
+| `1` | Findings at or above `--fail-on`, or a degraded result under `--require-complete`. |
+| `2` | Usage or configuration error. |
+| `3` | Malformed input, a failed/timed-out input, or an `INDETERMINATE` result — unless a finding at/above `--fail-on` already decided exit 1. |
+| `4` | Internal error or a memory ceiling. |
+| `130` | Interrupted. |
+
+`--fail-on <CRITICAL|HIGH|MEDIUM|LOW|INFO>` (Default: `INFO`). `--schema v2` is required for
+directory scans, `--output` and `--fail-on`; without it those are usage errors by design.
+
+---
+
+## 🤖 MCP server
+
+The package ships `sfscanner-mcp` — a stdio JSON-RPC MCP server with **one** tool, `n8n_scan`. It
+scans local workflow files with the same engine and returns the same structured output, so an agent
+can read a workflow before it imports it.
+
+```json
+{
+  "mcpServers": {
+    "sfscanner": {
+      "command": "node",
+      "args": ["<npm-root>/sfscanner/dist/mcp.js"]
+    }
+  }
+}
+```
+
+`<npm-root>` is `npm root -g`. The single tool takes `inputs` (local paths; stdin `-` is refused
+because the transport owns stdin), plus optional `format`, `failOn`, `profile`, `include`, `exclude`.
+Invalid arguments answer JSON-RPC `-32602` without running a scan.
+
+---
+
+## 🛡️ Limits, honestly
+
+- Inputs are bounded: 1,536,000 bytes per file by default, 5,000 nodes, 10,000 edges, a 30 s worker
+  deadline, and a validated `--limits` document can tighten or raise the byte ceiling.
+- The scan runs in a worker; if the worker cannot be terminated the item is reported `FAILED` rather
+  than "probably fine".
+- Node types the scanner does not model are reported as **unknown**, not as safe. Version ranges are
+  matched as catalogued; there is no nearest-neighbour guess.
+- Coverage of the published corpus lives on the website, with explicit counts for bodies that are
+  missing, source-unavailable, degraded and indeterminate.
+
+---
+
+## 📚 Documentation
+
+- [`docs/scanner/cli-v2.md`](../../docs/scanner/cli-v2.md) — v2 admission rules and Windows example
+- [`docs/scanner/limitations.md`](../../docs/scanner/limitations.md) — what the scanner does not do
+- [`docs/scanner/rule-reference.md`](../../docs/scanner/rule-reference.md) — every rule and remediation
+- [`docs/scanner/migration-v1-v2.md`](../../docs/scanner/migration-v1-v2.md) — v1 remains supported
+- [`docs/LICENSING.md`](../../docs/LICENSING.md) — licence terms
+
+v1 (`sfscanner scan file.json`) still works for one input with the `beta-default` profile.
+
+---
+
+## ⚖️ Licence
+
+MIT for this package's code and scanner tooling. The catalogue dataset has separate Personal /
+Non-Commercial terms; see https://github.com/jitwark/n8n-Secureflow/blob/main/docs/LICENSING.md.
+The dataset is not shipped in this package. A finding tells you what to read before importing a
+workflow; it does not make one safe.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,48 @@
+# Third-party notices
+
+This package ships a built CLI bundle plus its own documentation. The package's own code is licensed
+under [`LICENSE`](LICENSE) (MIT). No workflow corpus, private repository data, or runtime network
+client is included in this package.
+
+The classification below is derived from the packed artifact, not from declared intent: a module
+counts as shipped only when the bundle's shipped `dist/*.js.map` sources name it. The same split is
+machine-readable in `outputs/distribution/scanner-sbom.cyclonedx.json`
+(`scope` plus the `sfscanner:observed-in-packed-artifact` property).
+
+## Inlined in the packed bundle
+
+| Component | Version | License |
+| --- | --- | --- |
+| `@humanwhocodes/momoa` | 3.3.10 | Apache-2.0 |
+| `@noble/hashes` | 2.3.0 | MIT |
+| `@hub/contracts` | 0.1.0 | MIT — this project's workspace package |
+| `@hub/scanner-core` | 0.1.0 | MIT — this project's workspace package |
+
+`@hub/contracts` and `@hub/scanner-core` are this project's own MIT-licensed workspace packages. Their
+code is compiled into `dist/main.js` and `dist/mcp.js`; they are not runtime package dependencies.
+
+## Declared runtime dependencies this build does not ship
+
+These packages are installed as runtime dependencies of `@hub/scanner-core` and are imported by its
+optional code-analysis modules, but they are unreachable from this CLI's admitted profile
+(`beta-default` only, `packages/scanner-cli/src/v2/commands.ts`), so they are tree-shaken out of the
+packed bundle. They are listed because their absence is a verified property of this artifact: the
+string `acorn` / `@lezer` occurs zero times anywhere under `packages/scanner-cli/dist`, and the
+shipped source maps name none of their modules.
+
+| Component | Version | License |
+| --- | --- | --- |
+| `acorn` | 8.17.0 | MIT |
+| `@lezer/common` | 1.5.2 | MIT |
+| `@lezer/highlight` | 1.2.3 | MIT |
+| `@lezer/lr` | 1.4.10 | MIT |
+| `@lezer/python` | 1.1.19 | MIT |
+
+The scanner package's build/test-only tooling (`esbuild`, `typescript`, `vitest`, `@types/node` and
+their transitive dependencies) is likewise absent from the packed artifact and carries no notice
+obligation for it.
+
+This is a prepared dependency inventory, not a claim that the release's notice obligations are
+complete. A release owner must reconcile these versions against the exact lockfile, attach the
+verbatim upstream license texts, and complete the legal review (`PENDING_OWNER`). This package is
+published on npm as `sfscanner`.

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { parseCliArguments } from './v2/arguments.js';
+export { runCliV2, type PublicRunOptionsV2, type PublicRunResultV2, type PublicScanCommandV2, } from './v2/cli-runner.js';
+export { getHelpV2 } from './v2/help.js';
+export { emitMetadataCommandResultV2 } from './v2/metadata-output.js';