OgunScan documentation

OgunScan audits Model Context Protocol (MCP) server configs for prompt injection, exposed credentials, suspicious server origins, and supply-chain risks. The CLI is free, open source, and has zero runtime dependencies.

1. Installation

Requires Python 3.9 or newer.

Free CLI

pip install ogunscan

The free CLI has no dependencies beyond the Python standard library.

With Shield

pip install "ogunscan[shield]"

The shield extra adds watchdog, which the Shield daemon uses to watch config files for changes. Keep the quotes: some shells (zsh included) treat the square brackets as a pattern otherwise.

Check the install

ogunscan --version
ogunscan --help

2. Usage

# Auto-detect known MCP config locations (Claude Desktop, Cursor, and others)
ogunscan scan

# Scan a specific file
ogunscan scan ~/.cursor/mcp.json

# Scan a directory, recursively
ogunscan scan ./configs --recursive

# Path-first shorthand (the scan verb is optional)
ogunscan ~/.cursor/mcp.json

# JSON output for scripts
ogunscan scan ~/.cursor/mcp.json --json

# SARIF 2.1.0 output for the GitHub Security tab
ogunscan scan . --recursive --sarif > ogunscan.sarif

# Suppress specific rules (repeatable)
ogunscan scan . --ignore OGN-500 --ignore OGN-100

# List every detection rule
ogunscan rules

Scan options

3. CI and exit codes

The CLI exits 1 when any CRITICAL or HIGH finding is reported and 0 otherwise, so it can gate a pipeline directly.

name: Security
on: [push, pull_request]
jobs:
  mcp-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install ogunscan
      - run: ogunscan scan . --recursive --json > ogunscan-report.json
      - if: always()
        uses: actions/upload-artifact@v4
        with:
          name: ogunscan-report
          path: ogunscan-report.json

4. Detection rules

The config rules (OGN-1xx to OGN-5xx) run on every scan. The remote endpoint rules (OGN-6xx) run when Shield monitors a remote MCP server registered with ogunscan shield add --remote. Run ogunscan rules for the list that ships with your installed version.

5. Shield: continuous monitoring

The free CLI scans on demand. Shield runs in the background, rescans your registered configs when they change and on a schedule (every 6 hours by default), checks remote MCP endpoints, and alerts you when a new risk appears. Shield is $9/month and is activated with a license key.

Set up

# 1. Install with the Shield extra
pip install "ogunscan[shield]"

# 2. Activate with the license key from your purchase email
ogunscan shield activate YOUR-LICENSE-KEY

# 3. Register what to watch
ogunscan shield add ~/.cursor/mcp.json
ogunscan shield add --remote https://mcp.example.com/mcp

# 4. Start monitoring
ogunscan shield start              # foreground
ogunscan shield install-launchd    # macOS: run unattended under launchd

Shield commands

Alerts

New and resolved findings are always recorded in Shield's event history (ogunscan shield logs) and printed to the daemon's output. Email and Slack alerts switch on when their environment variables are set in the daemon's environment:

A Shield setup guide is also available as a PDF: OgunScan Shield setup guide.

6. Help and issues

• Source and issues: github.com/Ten30studio/ogunscan
• Package: pypi.org/project/ogunscan
• Contact: admin@ten30studio.com