codeinspectus

# CodeInspectus, by Synvoya

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg)](package.json)
[![npm downloads](https://img.shields.io/npm/dm/codeinspectus)](https://www.npmjs.com/package/codeinspectus)
![MCP-ready](https://img.shields.io/badge/MCP-ready-blue.svg)
![Local-first](https://img.shields.io/badge/local--first-yes-brightgreen.svg)
![No telemetry](https://img.shields.io/badge/telemetry-none-brightgreen.svg)
[![Official MCP Registry](https://img.shields.io/badge/Official_MCP_Registry-listed-blue.svg)](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.Synvoya%2Fcodeinspectus)
[![codeinspectus MCP server](https://glama.ai/mcp/servers/Synvoya/codeinspectus/badges/score.svg)](https://glama.ai/mcp/servers/Synvoya/codeinspectus)
[![GitHub stars](https://img.shields.io/github/stars/Synvoya/codeinspectus?style=social)](https://github.com/Synvoya/codeinspectus)

**A local-first, privacy-preserving security MCP server.** Any AI coding agent
(Claude Code, Cursor, Codex, Windsurf, Cline, Aider) can invoke CodeInspectus to
scan AI-generated / "vibe-coded" code for real vulnerabilities, map findings to
compliance frameworks as honest code-level coverage, and drive a **scan → fix →
rescan** loop — fully on your machine, with **no account** and **zero network
egress at scan time**.

![CodeInspectus demo](assets/codeinspectus-demo.gif)

**Reproduce the proof:** the shipped intentionally vulnerable fixture produces
**18 normalized findings across all four engines** with v0.3.1 (4 critical, 8 high,
5 medium, 1 low). Inspect the [fixture](fixtures/vulnerable-app), read the
[full scanner-derived report](examples/reports/vulnerable-app-v0.3.1.md), or run the
[36-case eval suite](evals/run-evals.ts). Dependency findings can change as the local
Trivy database updates; the report records the exact engine and database versions used.

If CodeInspectus is useful, [star the repository](https://github.com/Synvoya/codeinspectus)
so other AI-app builders can find it.

CodeInspectus orchestrates three best-in-class OSS engines behind one normalized,
CWE-keyed schema, and adds its own **AI-code-specific checks** that generic
scanners miss:

- **Opengrep** — SAST / OWASP Top 10 (SARIF)
- **Gitleaks** — secrets
- **Trivy** — dependency CVEs (SCA), IaC misconfig, secrets, license, SBOM
- **CodeInspectus Pub** — first-party, exact-version Dart/Flutter dependency matching and
  CycloneDX/SPDX inventory from `pubspec.lock`, backed by a bundled offline OSV Pub snapshot
- **CodeInspectus native checks** — client-side secret/bundle exposure, Supabase
  RLS / inverted-auth (the CVE-2025-48757 class), prompt-injection sinks,
  client-writable `user_metadata` authorization, and unsanitized model/user output
  rendered via `dangerouslySetInnerHTML` (XSS / LLM05), plus explicit API-boundary
  leaks, raw request-to-database writes, sensitive logging, and evidence-gated
  security-header/CSP/session-cookie/Supabase-CAPTCHA configuration checks. Separate
  first-party packs cover six narrow Flutter/Dart source failure modes and eight bounded
  Android/iOS repository-configuration failures, plus four React Native and two Expo
  framework-specific mobile failures. A bounded Python AI/API pack covers six narrow
  Django, Flask, FastAPI, Starlette, Jinja, OpenAI, and Anthropic source failures.

The shipped manifest contains **70 curated detections**: **49 first-party native rule
IDs** (21 JavaScript/TypeScript, 6 Flutter/Dart, 4 Android, 4 iOS, 4 React Native, and
2 Expo, plus 6 Python AI/API and 2 JavaScript baseline SAST rules), 18 Opengrep-owned
SAST rules, and 3 custom Gitleaks rules. All 20 Opengrep YAML rules remain physically active:
the two native-owned rules reconcile exact results and fall back to Opengrep on mismatch or
native unavailability. Opengrep, Gitleaks, and Trivy remain installed and additive.

> CodeInspectus bundles the official, **SHA-pinned** engine binaries and calls
> them as local subprocesses. It does **not** fork them.

## Why CodeInspectus?

AI-generated apps often ship with security mistakes that generic scanners miss: exposed
client-side secrets, weak Supabase auth patterns, unsafe HTML rendering, prompt-injection
sinks, and insecure agent/tool integrations.

CodeInspectus combines proven local scanners with AI-app-specific rules, then exposes the
workflow through an MCP server so coding agents can scan, explain, and help fix issues
before shipping.

## Install

**Prerequisites:** **Node.js ≥22**. Node 24 LTS is recommended. Also install
[**cosign**](https://github.com/sigstore/cosign)
on your `PATH` when Opengrep or Trivy binaries need installation. Signature verification is
**fail-closed**: those binaries are never installed without publisher verification. **Gitleaks**
verifies by checksum and needs no cosign; a DB-only Trivy refresh reuses the already SHA-verified
local Trivy binary.

```bash
# Register once per machine with your agent (see "Client registration"), then:
npx codeinspectus repair-engines
```

`repair-engines` first checks local state without network access. It downloads only missing,
mismatched, or newly pinned binaries, verifies them against the immutable lockfile shipped in the
npm package, and atomically installs them under `~/.codeinspectus/`. It refreshes the offline
Trivy vulnerability DB only when it is missing, lacks rescan provenance, or is more than seven
days old. Rule-only CodeInspectus upgrades therefore download nothing. After setup, **scans
perform zero network I/O.**

Every scan and `codeinspectus_list_rules` response includes structured `engine_setup` state:
`ready`, `repair_required`, `db_refresh_recommended`, or `unsupported_platform`. MCP agents are
instructed to explain non-ready state and obtain approval before running the repair command—there
is no silent npm `postinstall` download. The older `install-engines` command remains supported as
a compatibility alias and explicitly refreshes the Trivy DB.

If a Trivy DB was installed before 0.3.2, scan output tells your agent that CVE rescan
tracking is not yet enabled. The agent should run `npx codeinspectus repair-engines`
once; this re-fetches the DB through the verified install path and records its provenance.
Until then, vanished CVEs conservatively report `not_rechecked`; current scan findings
remain complete and unaffected.

Re-verify your pinned binaries any time:

```bash
npx codeinspectus verify-engines
```

An MCP server is installed **once per machine** and shared across all your
projects — it is **not** a per-repo `npm install` dependency.

## Client registration

The server command is the same across clients, but each client uses its own
configuration format. Clients with JSON MCP configuration use:

```jsonc
{
  "mcpServers": {
    "codeinspectus": { "command": "npx", "args": ["-y", "codeinspectus"] }
  }
}
```

| Client | How |
|--------|-----|
| **Claude Code** | `claude mcp add-json codeinspectus '{"command":"npx","args":["-y","codeinspectus"]}'` |
| **Cursor** | add to `~/.cursor/mcp.json` (or project `.cursor/mcp.json`) |
| **VS Code** | `code --add-mcp '{"name":"codeinspectus","command":"npx","args":["-y","codeinspectus"]}'` |
| **Codex** | use one of the Codex-specific options below |
| **Windsurf / Cline / Aider** | add the JSON block above to that client's MCP configuration |

For **Codex**, choose one registration method:

```bash
# Codex CLI
codex mcp add codeinspectus -- npx -y codeinspectus
```

- **Codex app or IDE extension:** open **Settings → MCP servers → Add server**,
  choose **STDIO**, set the command to `npx` and arguments to `-y`,
  `codeinspectus`, then restart.
- **Codex configuration file:** add this to global `~/.codex/config.toml` or a
  trusted project's `.codex/config.toml`:

```toml
[mcp_servers.codeinspectus]
command = "npx"
args = ["-y", "codeinspectus"]
tool_timeout_sec = 600
```

Codex defaults MCP tool calls to 60 seconds. CodeInspectus runs multiple security
engines concurrently and permits up to five minutes per engine, so 600 seconds
avoids premature client timeouts on larger repositories. This is a Codex client
timeout only; it does not change engine limits or other clients' configurations.

Optional: drop in the ready-made [`agent-rules/`](agent-rules/) so your agent
auto-runs the scan → fix → rescan loop.

MCP clients that support server instructions, including Codex, also receive the
safe workflow automatically: show findings first, obtain granular approval before
fixes, and rescan before claiming an issue is resolved. The agent-rule files remain
useful when you want the same policy persisted explicitly in a repository.

## Tools

| Tool | Purpose |
|------|---------|
| `codeinspectus_scan` | Full local scan of a path (engines + AI checks). Returns CWE-keyed findings, detected technologies, exact native-pack and Pub dependency coverage, remediations, framework tags, and three-state repository evidence for supported runtime controls. |
| `codeinspectus_rescan` | Re-scan after fixes; diffs vs a prior scan → resolved / remaining / introduced, with fresh technology and pack coverage. |
| `codeinspectus_compliance_report` | Per-framework **code-level control coverage** (not certification). |
| `codeinspectus_explain_finding` | Deep explanation + full remediation for one finding. |
| `codeinspectus_generate_sbom` | CycloneDX/SPDX SBOM using Trivy plus native Pub inventory/fallback (written to the managed dir by default, or a path you choose). |
| `codeinspectus_list_rules` | Active detectors, native-pack inventory/rule ownership, engine versions, detection-DB + Trivy/Pub DB provenance and freshness, and structured machine setup/repair state. |

CodeInspectus **never edits or deletes your source code or repository** — it reads and
reports; your agent applies the fixes. It stores engine data and scan history under
`~/.codeinspectus`; the only file it writes is an optional S