sfscanner 0.1.0 → 0.2.1

package/README.md

@@ -1,214 +1,141 @@
-# sfscanner — The n8n-SecureFlow Command-Line Interface & Native AI MCP Server
-
-> **CLI Executable:** `sfscanner`
-> **Native AI MCP Server:** `sfscanner-mcp` (`dist/mcp.js`)
-> **Licensing:** MIT for this package's code and scanner tooling. The catalogue dataset has separate Personal / Non-Commercial terms; see the [canonical policy](https://github.com/jitwark/n8n-Secureflow/blob/main/docs/LICENSING.md).
-
----
-
-## 1. Overview
-
-`sfscanner` is a high-performance, deterministic offline command-line scanner and native **Model Context Protocol (MCP)** server for n8n workflows. Built directly on `@hub/scanner-core`, it allows individual developers, DevOps engineers, and autonomous AI coding agents to audit workflow security without uploading workflow JSON to external servers.
-
-### Core Highlights
-* ⚡ **Sub-15ms Latency:** Audits typical workflows in ~12–15 milliseconds on modern CPUs.
-* 🛡️ **Zero Network Telemetry:** Operates 100% offline; zero outbound calls or analytics pings.
-* 📊 **Enterprise SARIF 2.1.0:** Generates standard SARIF reports that integrate directly with GitHub Code Scanning, GitLab Security Dashboards, and VS Code.
-* 🤖 **Built-In AI MCP Server:** Connects directly to Claude Desktop, Cursor, and agentic workflows to inspect workflows before importing.
-
----
-
-## 2. Installation & Quickstart
-
-### Personal Use Installation
-```bash
-# The repository is private: cloning requires access you have been granted.
-git clone https://github.com/jitwark/n8n-community.git
-cd n8n-community/community-hub
-
-# Install dependencies and build CLI & MCP binaries
-npm install
-npm run build --workspace=sfscanner
-
-# Link globally for local personal use
-npm link --workspace=sfscanner
-```
-
-`sfscanner` is published on the public npm registry. `private: false` in this package's manifest is a
-packaging flag, not an availability claim. To install the tarball instead of the registry copy, use
-`npm pack --workspace sfscanner`, or run the workspace build above. v2 inputs must be
-selection-root-relative paths; [docs/scanner/cli-v2.md](../../docs/scanner/cli-v2.md) states that rule
-and carries a verified Windows example.
-
-### Basic Command-Line Usage
-```bash
-# Scan a single workflow
-sfscanner scan path/to/workflow.json
-
-# Scan a directory of workflows with SARIF output
-sfscanner scan ./workflows --format sarif > results.sarif
-
-# Scan via standard input (piped from curl or cat)
-cat my-workflow.json | sfscanner scan -
-
-# Inspect admitted security policies
-sfscanner rules --format table
-
-# Explain a specific rule and its remediation
-sfscanner explain TAINTED_COMMAND
-```
-
----
-
-## 3. CLI Command Reference & Grammar
-
-```text
-sfscanner --schema v2 scan <file|directory|-> [options]
-sfscanner --schema v2 rules [--format json|table]
-sfscanner --schema v2 explain <rule-id> [--format json|table]
-sfscanner --schema v2 profiles [--format json|table]
-sfscanner --schema v2 validate-config <config-file> [--format json|table]
-sfscanner --schema v2 version [--format json|table]
-```
-
-`--schema v2` is **required for `--fail-on`, `--output` and directory scans**. Omitting it
-runs only the single-document form: `--fail-on` and `--output` then exit `2`, and a directory
-argument exits `3`. Pass it explicitly.
-
-### Command Options for `scan`
-* `--format <json|ndjson|sarif|table>`: Choose output format (Default: `json`). The CLI does not
-  detect a terminal, so `table` is never selected for you — pass `--format table` to get it.
-* `--fail-on <CRITICAL|HIGH|MEDIUM|LOW|INFO>`: Set exit-code failure threshold (Default: `HIGH`).
-* `--profile <beta-default>`: Select scanning profile (Default: `beta-default@2.0.0`).
-* `--include <glob>` / `--exclude <glob>`: Filter workflow paths during directory scans.
-* `--output <file>`: Atomic write destination using temporary files to prevent partial file corruption.
-
-### Supported platforms
-
-**Node 22 is the only supported line**, and it has only been verified on Windows; Linux and
-macOS runs are pending. `engines.node` accepts `>=22 <23`, so the installer admits the 22
-series and refuses 23 and 24 outright rather than admitting lines that were never run. Pin
-Node 22 in CI until a matrix result exists for another line.
-
----
-
-## 4. Exit Code Lattice
-
-The CLI uses a deterministic exit code lattice to communicate scan results to CI/CD pipelines:
-
-| Exit Code | Classification | Meaning |
-| :---: | :--- | :--- |
-| `0` | **CLEAN / SUCCESS** | Scan completed; no findings met or exceeded the `--fail-on` threshold. |
-| `1` | **FINDINGS_EXCEEDED** | One or more findings met or exceeded the configured threshold. |
-| `2` | **USAGE_OR_CONFIG_ERROR** | Invalid CLI arguments, bad config file, or unknown rule profile. |
-| `3` | **INPUT_OR_INDETERMINATE** | Input JSON is malformed, or missing dependencies forced an `INDETERMINATE` state under strict mode. |
-| `4` | **INTERNAL_ERROR** | Uncaught scanner error or memory ceiling violation. |
-| `130` | **INTERRUPTED** | Execution cancelled via SIGINT (Ctrl+C). |
-
----
-
-## 5. Continuous Integration (CI/CD) Integration
-
-### GitHub Actions Workflow
-Export SARIF 2.1.0 reports directly into the GitHub Repository **Security** tab:
-
-```yaml
-name: n8n Workflow Security Scan
-
-on:
-  push:
-    paths: ['**.json']
-  pull_request:
-
-jobs:
-  scan:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout Code
-        uses: actions/checkout@v4
-
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: 22
-
-      - name: Install sfscanner
-        run: |
-          cd community-hub && npm ci && npm run build --workspace=sfscanner
-          npm link --workspace=sfscanner
-
-      - name: Run Scan
-        run: |
-          sfscanner scan ./workflows --format sarif > sfscanner.sarif
-
-      - name: Upload SARIF to GitHub Security Tab
-        uses: github/codeql-action/upload-sarif@v3
-        with:
-          sarif_file: sfscanner.sarif
-```
-
----
-
-## 6. Native AI MCP Server (`sfscanner-mcp`)
-
-`sfscanner` includes a production-ready, native **Model Context Protocol (MCP)** server (`dist/mcp.js`) running over standard I/O JSON-RPC 2.0. It gives AI coding assistants the power to audit n8n workflows before executing or importing them.
-
-```mermaid
-graph LR
-    User["Developer / Operator"] --> Agent["AI Assistant (Claude / Cursor)"]
-    Agent -->|MCP stdio JSON-RPC| Server["sfscanner-mcp (dist/mcp.js)"]
-    Server -->|Static In-Memory Scan| Core["@hub/scanner-core Engine"]
-    Core -->|SARIF / JSON Finding| Server
-    Server -->|Diagnostic Report| Agent
-    Agent -->|Safe Workflow Advice| User
-```
-
-### Tool Definition
-* **Tool Name:** `n8n_scan`
-* **Description:** *"Scan local n8n workflow JSON with the admitted deterministic offline v2 profile."*
-* **Parameters:**
-  * `inputs` (array of strings, required): Local workflow file paths.
-  * `format` (optional string): `'json' | 'ndjson' | 'sarif' | 'table'`.
-  * `failOn` (optional string): `'CRITICAL' | 'HIGH' | 'MEDIUM' | 'LOW' | 'INFO'`.
-
-### Connecting to Claude Desktop
-Add this entry to your `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "sfscanner": {
-      "command": "node",
-      "args": [
-        "/absolute/path/to/n8n-community/community-hub/packages/scanner-cli/dist/mcp.js"
-      ]
-    }
-  }
-}
-```
-
-### Connecting to Cursor
-Add this entry to your Cursor Settings (`.cursor/mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "sfscanner": {
-      "command": "node",
-      "args": [
-        "d:/projects/n8n-community/community-hub/packages/scanner-cli/dist/mcp.js"
-      ]
-    }
-  }
-}
-```
-
-### Example AI Prompting
-Once configured, you can prompt your AI agent:
-> *"Before we deploy this automation, use the `n8n_scan` tool to check `workflows/lead-sync.json` for prompt injection or leaked credentials."*
-
----
-
-## 7. Licensing Terms
-
-`sfscanner` code and scanner tooling are MIT-licensed; see [`LICENSE`](LICENSE). The aggregated workflow catalogue dataset (`data/`) has separate Personal / Non-Commercial terms and is not included in this package. See the [canonical licensing policy](https://github.com/jitwark/n8n-Secureflow/blob/main/docs/LICENSING.md).
+# 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/sfscanner/blob/main/docs/LICENSING.md.
+
+> Release candidate: the supported profile is `beta-default`; experimental hardened analysis is not publicly admitted. Supply-chain opt-in reports canonical advisory state and unknown coverage when no snapshot is admitted. See the [CLI guide](https://github.com/jitwark/sfscanner/blob/main/docs/scanner/cli-v2.md) for supported contracts and limits.
+```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://jitwark.github.io/sfscanner/>.
+
+---
+
+## ⚡ 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.
+
+Every one of these is a first-class surface, and none is deprecated: the JSON result, NDJSON
+streaming, SARIF 2.1.0 and the table stay supported for the scanner, while the published dataset
+bundle keeps its NDJSON shards, SQLite database and Excel workbook. Removing a format needs usage or
+cost evidence, an owner decision, migration or export access and explicit documentation — a research
+note is not enough. See [Preflight and handover](../../docs/scanner/preflight-handover.md#preserved-product-formats).
+
+| 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.
+
+Optional readiness assessment: `--include-readiness` (default `false`) extends `json`, `ndjson`, or `table` output with offline preflight checks (completeness status, declared credentials, integrations, and subworkflows). SARIF format combined with `--include-readiness` is rejected.
+
+---
+
+## 🤖 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/preflight-handover.md`](../../docs/scanner/preflight-handover.md) — offline preflight and handover: prerequisite and target checks, opt-in privacy preparation, preserved output formats, bounded catalogue expansion
+- [`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/sfscanner/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.