sfscanner 0.0.0-stage → 0.1.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,214 @@
-# Temporary Holding Version
+# sfscanner — The n8n-SecureFlow Command-Line Interface & Native AI MCP Server
 
-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.
+> **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).

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`.