Nullsec S1 MCP

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:

npx -y s1-mcp

Or install it in a project:

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:

{
  "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:

{
  "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.

{
  "filePath": "app/api/admin/route.ts"
}

s1_gate

Evaluates production readiness from existing findings or scans a target first.

{
  "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.

{
  "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.

{
  "target": "circuits",
  "deep": true,
  "format": "json"
}

Behavior:

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.

{
  "ruleId": "NS-H2-005"
}

s1_zk_rules

List supported Nullsec S1-ZK rules.

{}

Examples

Next.js API route scan:

Use s1_scan_file on app/api/admin/route.ts and explain any production blockers.

Base/EVM contract scan:

Use s1_scan_repo on contracts/ and then run s1_gate with blockHigh enabled.

ZK circuit scan:

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

npm install
npm run build
npm test

Run the MCP server locally:

npm run dev