s1-mcp

# Nullsec S1 MCP [](https://www.npmjs.com/package/s1-mcp) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](LICENSE) Security scanning tools for MCP-compatible coding agents. `s1-mcp` brings Nullsec S1-style security checks into Cursor, Claude Desktop, and other MCP clients. General app/repo scanning is deterministic and local-first: it does not call a hosted S1 API, does not require an LLM, and does not claim a project is secure just because no supported files were found. The server also keeps the existing `s1_zk_*` tools for Circom and Halo2 circuits through `@trynullsec/s1-zk`. ## Install Use it directly with `npx`: ```sh npx -y s1-mcp ``` Or install it in a project: ```sh npm install --save-dev s1-mcp npx s1-mcp ``` Requires Node.js 20 or newer. ## MCP Config Add this server to Cursor or Claude Desktop: ```json { "mcpServers": { "nullsec-s1": { "command": "npx", "args": ["-y", "s1-mcp"] } } } ``` Once connected, ask your agent to run `s1_scan_repo`, `s1_scan_file`, `s1_gate`, `s1_explain_finding`, or the ZK-specific `s1_zk_*` tools. ## General App Tools ### `s1_scan_repo` Recursively scans supported app files under a target path. Supported files: - `.ts`, `.tsx`, `.js`, `.jsx`, `.mjs`, `.cjs` - `.json` - `.env.example` for key-name exposure checks - `.sol` for Base/EVM Solidity checks Ignored by default: `node_modules`, `.git`, `.next`, `dist`, `build`, `coverage`, generated lockfile internals, `pnpm-lock.yaml`, and `yarn.lock`. Input: ```json { "target": "app", "ruleCategories": ["auth", "secrets", "dangerous_exec"] } ``` Output includes: - `target` - `filesScanned` - `rulesExecuted` - severity `summary` - `issues` - `productionGate` - `unsupported` when no supported files are found ### `s1_scan_file` Scans one supported file with the same deterministic rules. Unsupported extensions return an explicit unsupported result instead of a pass/secure verdict. ```json { "filePath": "app/api/admin/route.ts" } ``` ### `s1_gate` Evaluates production readiness from existing findings or scans a target first. ```json { "target": "app", "policy": { "blockCritical": true, "blockHigh": true, "requireDimensions": ["auth", "secrets", "rate_limits"] } } ``` Blocks by default on critical findings, high findings, secret exposure, dangerous execution with user input, live Base/EVM deploy key patterns, and unauthenticated admin routes with dangerous behavior. ### `s1_explain_finding` Explains a finding for a developer, founder, or auditor using local templates. ```json { "findingId": "S1-EXEC-005", "audience": "developer" } ``` You can also pass a full finding object returned by `s1_scan_repo` or `s1_scan_file`. ## Deterministic Rule Coverage General scanning catches common AI-generated app risks: - Secrets: hardcoded OpenAI/Anthropic/Stripe-style keys, `sk_live_`, bearer tokens, private keys, seed phrases, database URLs, webhook secrets, secrets returned in JSON, and secret-like `NEXT_PUBLIC_` variables. - Dangerous execution: `child_process.exec`, `execSync`, `spawn` with `shell: true`, user input flowing into command execution, `eval`, and `new Function`. - Auth: admin API routes without visible session/role checks, admin responses without auth, and mutation endpoints without visible auth. - Input validation: `await req.json()` without visible schema validation. - Rate limits: mutation API routes without visible rate limiting. - Environment exposure: returning `process.env`, logging secrets, and concrete `.env` files if scanned. - Dependency risk: install lifecycle scripts, git/http dependencies, and suspicious package scripts. - Base/EVM Solidity: `tx.origin`, `delegatecall`, `selfdestruct`, unrestricted mint patterns, low-level calls, deploy private keys, live broadcast/deploy command patterns, and detectable hidden fee/drain controls. No Solana assumptions are made by default; web3 wording and rules use Base/EVM terminology. ## ZK Tools ### `s1_zk_scan` Scan Circom or Halo2-style ZK circuits using Nullsec S1-ZK. ```json { "target": "circuits", "deep": true, "format": "json" } ``` Behavior: ```sh npx @trynullsec/s1-zk scan <target> --format json --no-banner ``` When `deep` is true, the server adds `--deep`. ### `s1_zk_explain` Explain a Nullsec S1-ZK rule. ```json { "ruleId": "NS-H2-005" } ``` ### `s1_zk_rules` List supported Nullsec S1-ZK rules. ```json {} ``` ## Examples Next.js API route scan: ```text Use s1_scan_file on app/api/admin/route.ts and explain any production blockers. ``` Base/EVM contract scan: ```text Use s1_scan_repo on contracts/ and then run s1_gate with blockHigh enabled. ``` ZK circuit scan: ```text Use s1_zk_scan on circuits/ with deep mode enabled. ``` ## Security Notes - General scanning is deterministic and local-only. - Target paths must stay within the server working directory. - General scanning performs no shell execution. - ZK tools invoke `@trynullsec/s1-zk` through argv arrays with `shell: false`. - The server does not send code to remote APIs. - Evidence is sanitized to avoid returning full secrets in MCP responses. ## Development ```sh npm install npm run build npm test ``` Run the MCP server locally: ```sh npm run dev ```