# MCP Secret Scan

[![CI](https://github.com/KaryawanSurga/mcp-secret-scan/actions/workflows/ci.yml/badge.svg)](https://github.com/KaryawanSurga/mcp-secret-scan/actions/workflows/ci.yml)
[![Node](https://img.shields.io/badge/node-%3E%3D20-339933)](package.json)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

**Find secrets before they reach a commit.**

MCP Secret Scan checks staged diffs, files, directories, and raw text for API keys, tokens, private keys, passwords, and high-entropy strings — with masked findings and severity-based exit codes that work as a pre-commit or CI gate. Use it as an MCP tool so an agent can scan its own work before committing, or straight from the terminal. Fully offline: nothing you scan leaves your machine.

Fifth tool in the TokenSaver family: [TokenSaver MCP](https://github.com/KaryawanSurga/TokenSaverMcp) maps repositories, [MCP Context Budget](https://github.com/KaryawanSurga/mcp-context-budget) audits tool costs, [MCP Web Snapshot](https://github.com/KaryawanSurga/mcp-web-snapshot) reads the web, [MCP Log Tail](https://github.com/KaryawanSurga/mcp-log-tail) summarizes logs, and Secret Scan guards commits.

> Product requirements: [PRD.md](PRD.md) · [PRD.id.md](PRD.id.md) (Bahasa Indonesia)

## Why

Secrets leak through commits far more often than through breaches: an `.env` pasted into a config, a token in a test fixture, credentials in a database URL. Linters and tests do not catch them, and by the time a scanner runs in CI the secret is already in history. The cheapest fix is a gate right before the commit — and that gate should be callable by the agent doing the work.

## Quick start

CLI, no install needed. Scan staged changes:

```sh
npx -y mcp-secret-scan scan --staged
```

Example output:

```text
# Secret scan: staged changes

2 finding(s) in 1 file(s) — CRITICAL 1, HIGH 1

CRITICAL src/config.ts:12:15  aws-access-key — AWS access key id
  const key = "AKIA…MPLE";
HIGH     src/db.ts:4:20        uri-credentials — Password embedded in a URI
  const url = "postgres://admin:****@db.example.com/app";

All secrets are masked. Nothing leaves your machine.
Gate: FAILED — this would block a commit.
```

Other modes:

```sh
npx -y mcp-secret-scan scan ./src --strict
npx -y mcp-secret-scan text --content "AWS_KEY=AKIAIOSFODNN7EXAMPLE"
npx -y mcp-secret-scan scan --range main..HEAD --json
```

Exit codes: `0` clean, `1` findings at or above the threshold (critical/high by default, medium with `--strict`), `2` usage error. That makes it a drop-in pre-commit hook.

## MCP server

Add it to any MCP-compatible client:

```json
{
  "mcpServers": {
    "secretscan": {
      "command": "npx",
      "args": ["-y", "mcp-secret-scan", "serve"]
    }
  }
}
```

From a local checkout, point `command` at `node` and `args` at the built entry point:

```json
{
  "mcpServers": {
    "secretscan": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-secret-scan/dist/index.js", "serve"]
    }
  }
}
```

## Tools

| Tool | What it scans |
| --- | --- |
| `scan_text` | Arbitrary text before it is written anywhere. |
| `scan_diff` | Staged or working-tree git changes, with exact file and line numbers. |
| `scan_path` | A file or directory tree, skipping dependencies, binaries, and oversized files. |

Every tool returns masked findings classified as `critical`, `high`, `medium`, or `low`. The full secret is never printed.

## What it detects

- **Cloud and platform keys**: AWS access key ids, Google API keys.
- **Developer tokens**: GitHub (`ghp_`, `gho_`, `github_pat_`), npm, PyPI, Slack, Stripe, SendGrid, Twilio.
- **AI provider keys**: OpenAI (`sk-`), Anthropic (`sk-ant-`).
- **Credentials**: private key blocks, passwords embedded in URIs, JWTs.
- **Unlabeled secrets**: high-entropy strings with mixed character classes.
- **Generic assignments**: `api_key = "..."`, `password: "..."`, and similar patterns.

## False positives are first-class

- Inline `// secret-scan:ignore` (or `# secret-scan:ignore`) skips a line.
- `.secretscanignore` in the working directory holds allowlist regexes, one per line.
- `--allow <regex>` adds allowlist patterns per run; repeatable.
- Placeholders like `your_api_key_here`, `example`, `xxxx`, or `changeme` are ignored.
- Generic matches are `medium` and never block unless `--strict` is set.

## Design principles

- **Offline**: no network, no telemetry, no secret ever transmitted or logged in full.
- **Bounded**: file size caps, directory ignore list, binary detection, and a findings cap.
- **Read-only**: never edits files, never writes history.
- **Fast**: pure regex and entropy checks, no model calls.
- **Gate-friendly**: severity thresholds and exit codes designed for hooks and CI.

## CLI reference

| Option | Meaning |
| --- | --- |
| `--staged` / `--unstaged` / `--range <ref>` | Scan git changes instead of the filesystem |
| `--strict` | Also block on medium severity findings |
| `--max-findings <n>` | Maximum findings to report (default 200) |
| `--allow <regex>` | Allowlist pattern, repeatable |
| `--json` | Machine-readable output |

## Pre-commit example

```yaml
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: secret-scan
        name: secret scan
        entry: npx -y mcp-secret-scan scan --staged
        language: system
        pass_filenames: false
```

## Roadmap

- Custom rule files per project.
- Baseline mode: accept existing findings and only block new ones.
- Git history scan for auditing past commits.
- SARIF output for code scanning integrations.
- Configurable entropy thresholds.

## Development

```sh
npm install
npm run typecheck
npm run build
npm test
```

The suite covers every rule, masking, entropy detection, allowlists, git diff parsing with real repositories, directory walking, CLI behavior, and MCP round trips.

## License

MIT — see [LICENSE](LICENSE).