mcp-audit - GitLite

KO | EN

gitlite — search

#react #ai #typescript #rust #docker #nodejs #macos #windows #awesome #cli #kubernetes #vue #security #open-source

mcp-audit

(★ 154)

See what your AI agents can access. Scan MCP configs for exposed secrets, shadow APIs, and AI models. Generate AI-BOMs for compliance.

File Explorer

Download Latest Version (.zip)

- - mcp-audit.yml
- - report.ts
- - email.ts
  - pdf.tsx
- .gitignore
- package-lock.json
- package.json
- README.md
- tsconfig.json
- vercel.json
- collector.ps1
- collector.sh
- 01-functional-capabilities.md
- 02-architecture-technical-design.md
- 03-implementation-plan.md
- CLAUDE_CODE_PROMPTS.md
- mcp-audit-lead-capture-prompt-removelocalpdf.md
- mcp-audit-lead-capture-prompt.md
- mcp-audit-model-detection-ai-bom-prompt.md
- MCP-AUDIT-PRODUCT-STRATEGY.md
- mcp-audit-ui-color-redesign-prompt.md
- MCP-SECURITY-TESTING-STRATEGY.md
- privacy-qa.md
- RISK_SCORING.md
- SOURCE_SCAN.md
- USER_GUIDE.md
- verified-mcp-registry-qa.md
- - __init__.py
  - analyze.py
  - policy.py
  - registry.py
  - scan.py
  - source_scan.py
  - trust.py
- - __init__.py
  - allowlist_bypass_binaries.py
  - api_patterns.py
  - known_mcps.json
  - model_patterns.py
  - owasp_llm.py
  - risk_definitions.py
  - secret_patterns.py
- - __init__.py
  - cyclonedx.py
  - formatter.py
  - pdf_report.py
  - sarif.py
- - __init__.py
  - claude.py
  - cursor.py
  - docker.py
  - project.py
  - source.py
  - vscode.py
  - windsurf.py
  - zed.py
- __init__.py
- cli.py
- models.py
- enterprise.yaml
- permissive.yaml
- strict.yaml
- build-cli-zip.sh
- dev-server.sh
- generate-checksums.sh
- - claude_desktop_config.json
  - collected_config.json
  - cursor_mcp.json
  - package.json
- __init__.py
- conftest.py
- test_models.py
- test_outputs.py
- test_owasp_llm.py
- test_policy.py
- test_registry.py
- test_scanners.py
- test_source_scanner.py
- test_trust.py
.gitignore
.nojekyll
action.yml
app.js
BUG_TRACKER.md
CHANGELOG.md
CHECKSUMS.txt
CONTRIBUTING.md
demo-data.json
deploy.sh
Dockerfile
getting-started.html
google-apps-script.js
index.html
LICENSE
mcp-audit-cli.zip
PR-FAQ.md
pyproject.toml
README.md
RELEASE_NOTES.md
RELEASE_v1.0.0.md
screenshot.png
Screenshot2.png
SECURITY-ADVISORY-2025-001.md
SECURITY.md
styles.css

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MCP Audit

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![GitHub release](https://img.shields.io/github/v/release/apisec-inc/mcp-audit)](https://github.com/apisec-inc/mcp-audit/releases)

**See what your AI agents can access - before they go live.**

**Web App**
![MCP Audit Web App](https://apisec-inc.github.io/mcp-audit/screenshot.png)

**CLI**
![MCP Audit CLI](https://apisec-inc.github.io/mcp-audit/Screenshot2.png)

## Quick Start

```bash
# Install
pip install -e .

# Scan your machine
mcp-audit scan

# Or try the web app (no install)
# https://apisec-inc.github.io/mcp-audit/?demo=true
```

## What It Does

MCP Audit scans your AI development tools (Claude Desktop, Cursor, VS Code) and reveals:

- **Secrets** - Exposed API keys, tokens, database passwords
- **APIs** - Every endpoint your AI agents connect to
- **AI Models** - Which LLMs are configured (GPT-4, Claude, Llama)
- **Risk Flags** - Shell access, filesystem access, unverified sources

```
⚠️  2 SECRET(S) DETECTED - IMMEDIATE ACTION REQUIRED

[CRITICAL] GitHub Personal Access Token
  Location: github-tools → env.GITHUB_TOKEN
  Remediation: https://github.com/settings/tokens → Delete → Recreate

[HIGH] Database Connection String
  Location: postgres-mcp → env.DATABASE_URL
  Remediation: Rotate credentials, use secrets manager
```

## Source-level Scanning (new in v1.1)

`mcp-audit scan` inventories MCP server **configurations**. The new `mcp-audit source-scan` command goes one level deeper — it reads the MCP server's own **source code** and flags code-level vulnerabilities the server author may have introduced.

Today it catches the **"Prompt In, Shell Out"** attack chain: an MCP server that pipes an LLM-controlled tool argument into a shell-spawning API (`child_process.exec`, `util.promisify(exec)`, `subprocess.run(shell=True)`, `os.system`, `os.popen`) without sanitization. An attacker controlling the LLM input can inject shell metacharacters and execute arbitrary code on the host running the MCP server.

```bash
$ mcp-audit source-scan ./packages/my-mcp-server

MCP source-scan: packages/my-mcp-server
1 critical · 0 high · 1 finding(s) total

Severity  Conf  File:Line      API                                          Snippet
  CRITICAL  high  server.js:19   util.promisify(child_process.exec) ...       const { stdout } = await execAsync(
```

Outputs:

- `--format table` (default, human-readable)
- `--format json` (CI integrations, jq pipelines)
- `--format sarif` (upload to GitHub code-scanning / GitLab / similar)

Gate merges on critical findings:

```bash
mcp-audit source-scan ./my-mcp --exit-code
```

The scanner is intentionally narrow — it only opens files that look like MCP server source (imports an MCP SDK). It won't try to find shell-injection bugs in random Node / Python code; that's not the job.

After running `mcp-audit scan`, you'll see a nudge in the summary suggesting `source-scan` against any in-house or unverified servers it discovers.

## What It Finds (and Doesn't Find)

### What It Finds

| Scan Type | Finds |
|-----------|-------|
| **GitHub Scan** | MCP configs committed to repositories (`mcp.json`, `.mcp/`, `claude_desktop_config.json`, etc.) |
| **Local Scan** | MCP configs on your machine (Claude Desktop, Cursor, VS Code, Windsurf, Zed) |
| **Source Scan** (v1.1) | Code-level vulnerabilities in MCP server source (JS/TS/Python): shell-injection sinks (`child_process.exec`, `util.promisify(exec)`, `subprocess.run(shell=True)`, `os.system`, `os.popen`) called with interpolated tool arguments |

### What It Won't Find

| Blind Spot | Why |
|------------|-----|
| **Secrets in environment variables at runtime** | We scan config files, not running processes |
| **Configs pulled from secrets managers** | Vault, AWS Secrets Manager, etc. are not scanned |
| **Dynamically generated configs** | Configs created at runtime aren't in files |
| **MCPs installed but not configured** | No config file = nothing to scan |
| **Private repos you don't have access to** | GitHub scan is limited by your PAT scope |
| **Encrypted or obfuscated secrets** | Pattern matching won't catch encoded values |
| **Non-standard config locations** | Custom paths outside known locations |

### Important

**A clean scan does not mean zero risk.**

- Developers may have MCPs configured on machines you haven't scanned
- Configs may exist in repos outside your GitHub org
- Runtime behavior may differ from static configuration

MCP Audit provides visibility, not guarantees. Use alongside runtime monitoring and security reviews.

## CI/CD Integration

Fail builds on critical risks:

```yaml
# .github/workflows/mcp-audit.yml
name: MCP Security Audit
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

- name: Install MCP Audit
        run: pip install mcp-audit

- name: Run Security Scan
        run: mcp-audit scan --path . --format json -o mcp-report.json

- name: Fail on Critical
        run: |
          CRITICAL=$(jq '[.mcps[] | select(.risk == "critical")] | length' mcp-report.json)
          if [ "$CRITICAL" -gt 0 ]; then
            echo "❌ Found $CRITICAL critical-risk MCPs"
            exit 1
          fi

- name: Upload AI-BOM
        uses: actions/upload-artifact@v4
        with:
          name: ai-bom
          path: mcp-report.json
```

### Source-level scan in CI (v1.1)

If you ship an in-house MCP server, gate merges on critical code-level findings:

```yaml
# .github/workflows/mcp-source-scan.yml
name: MCP Source Scan
on: [pull_request]

jobs:
  source-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install mcp-audit

# Fail the PR if any critical shell-injection findings are detected.
      - name: Source-scan in-house MCP server
        run: mcp-audit source-scan ./packages/my-mcp-server --exit-code

# OR: upload findings to GitHub code-scanning instead of failing.
      - name: Source-scan -> SARIF
        run: mcp-audit source-scan ./packages/my-mcp-server --format sarif --output mcp.sarif
      - uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: mcp.sarif
```

## Export Formats

```bash
# JSON (for CI/CD)
mcp-audit scan --format json -o report.json

# AI-BOM (CycloneDX 1.6)
mcp-audit scan --format cyclonedx -o ai-bom.json

# SARIF (GitHub Security integration)
mcp-audit scan --format sarif -o results.sarif

# CSV / Markdown
mcp-audit scan --format csv -o report.csv
mcp-audit scan --format markdown -o report.md

# PDF Report via Email
mcp-audit scan --email security@company.com
```

---

## Key Features

| Feature | Description |
|---------|-------------|
| **MCP Discovery** | Find MCPs in Claude Desktop, Cursor, VS Code, Windsurf, Zed |
| **Secrets Detection** | 25+ secret patterns with provider-specific remediation |
| **API Inventory** | Database, REST, SSE, SaaS, Cloud endpoints |
| **AI Model Detection** | OpenAI, Anthropic, Google, Meta, Mistral, Ollama |
| **OWASP LLM Top 10** | Maps findings to OWASP LLM Top 10 (2025) framework |
| **AI-BOM Export** | CycloneDX 1.6 for supply chain compliance |
| **SARIF Output** | GitHub Security integration with OWASP tags |
| **Registry** | 50+ known MCPs with risk classifications |

## Two Ways to Use

| | **Web App** | **CLI Tool** |
|---|-------------|--------------|
| **Scans** | GitHub repositories | Local machine |
| **Install** | None (browser) | Python 3.9+ |
| **Best for** | Org-wide visibility | Deep local analysis |
| **Privacy** | Token stays in browser | 100% local |

**Web App:** [https://apisec-inc.github.io/mcp-audit/](https://apisec-inc.github.io/mcp-audit/)

---

## CLI Reference

### Scan Commands

```bash
mcp-audit scan                    # Full inventory scan
mcp-audit scan --secrets-only     # Only secrets
mcp-audit scan --apis-only        # Only API endpoints
mcp-audit scan --models-only      # Only AI models
mcp-audit scan --verbose          # Detailed output
mcp-audit scan --path ./project   # Specific directory
```

### Source-level Scan Commands (new in v1.1)

`source-scan` is a separate command from `scan`. `scan` inventories MCP configurations; `source-scan` reads MCP server source code and flags code-level vulnerabilities. See [docs/SOURCE_SCAN.md](docs/SOURCE_SCAN.md) for the full guide.

```bash
mcp-audit source-scan ./my-mcp                         # Table output (default)
mcp-audit source-scan ./my-mcp --format json           # JSON for jq pipelines
mcp-audit source-scan ./my-mcp --format sarif          # SARIF for code-scanning
mcp-audit source-scan ./my-mcp --output mcp.sarif      # Write to file
mcp-audit source-scan ./my-mcp --exit-code             # CI gate (non-zero on critical)
mcp-audit source-scan ./my-mcp --explain               # Inline remediation guidance
```

### Export Options

```bash
mcp-audit scan --format json -o report.json       # JSON output
mcp-audit scan --format csv -o report.csv         # CSV output
mcp-audit scan --format markdown -o report.md     # Markdown output
mcp-audit scan --format cyclonedx -o ai-bom.json  # CycloneDX 1.6 AI-BOM
mcp-audit scan --format sarif -o results.sarif    # SARIF for GitHub Security
mcp-audit scan --email security@company.com       # PDF report via email
```

### Registry Commands

```bash
mcp-audit registry                    # List all known MCPs
mcp-audit registry --risk critical    # Filter by risk
mcp-audit registry lookup "stripe"    # Search registry
```

### Explain a Risk Flag

```bash
mcp-audit explain shell-injection-in-source   # Full remediation guidance
mcp-audit explain --list                      # All known risk flags
```

---

## Risk Levels

| Level | Meaning | Examples |
|-------|---------|----------|
| 🔴 **CRITICAL** | Full system access | Database admin, shell access, cloud IAM |
| 🟠 **HIGH** | Write access | Filesystem write, API mutations |
| 🟡 **MEDIUM** | Read + limited write | SaaS integrations, read-only DB |
| 🟢 **LOW** | Read-only | Public APIs, memory storage |

## Detected Secrets

| Severity | Types |
|----------|-------|
| 🔴 Critical | AWS Keys, GitHub PATs, Stripe Live Keys, DB Credentials |
| 🟠 High | Slack Tokens, OpenAI Keys, Anthropic Keys, SendGrid |
| 🟡 Medium | Webhooks, Generic API Keys |

---

## Privacy

- **Web App**: GitHub token never leaves your browser
- **CLI**: Runs 100% locally, no telemetry
- **PDF Reports**: Only summary data sent (no secrets)

---

## Installation

### Option 1: Python (pip)

```bash
# Clone and install
git clone https://github.com/apisec-inc/mcp-audit.git
cd mcp-audit
pip install -e .

# Verify
mcp-audit --help
```

Requires Python 3.9+

### Option 2: Docker

```bash
# Build image
docker build -t mcp-audit .

# Scan current directory
docker run -v $(pwd):/scan mcp-audit scan

# Scan with JSON output
docker run -v $(pwd):/scan mcp-audit scan --format json -o /scan/report.json
```

---

## Verify Download Integrity

All MCP Audit releases include SHA256 checksums.

### Verify CLI Download

```bash
# Download the checksum file
curl -O https://github.com/apisec-inc/mcp-audit/releases/latest/download/CHECKSUMS.txt

# Verify the zip file
shasum -a 256 -c CHECKSUMS.txt --ignore-missing
```

Expected output:
```
mcp-audit-cli.zip: OK
```

### Current Release Checksum

| File | SHA256 |
|------|--------|
| `mcp-audit-cli.zip` | `4917a451742038355265b0d9a74c0bb2b3a5ada28798ce3dd43238a8defcaa73` |

Full checksums: [CHECKSUMS.txt](CHECKSUMS.txt)

---

## Documentation

- **[Risk Scoring](docs/RISK_SCORING.md)** - How risk levels and flags are assigned
- **[Contributing](CONTRIBUTING.md)** - Guidelines for contributors

## License

MIT - see [LICENSE](LICENSE)

---

Built by [APIsec](https://apisec.ai)