CIPHER MCP Scan

CIPHER is a local static scan for MCP-oriented codebases. It inspects a checked-out project locally and runs five focused static checks: authentication, over-privilege, CVE lookup, typosquatting, and tool poisoning.

The tool_poisoning check examines MCP JSON tool metadata for instruction overrides, data-exfiltration requests, dangerous URI schemes, and hidden Unicode control characters. It is always included with the four static checks; remote_oauth remains separate and opt-in through --remote-url.

Optional remote OAuth check

The fifth check is opt-in and runs only when an explicit remote URL is supplied. It probes OAuth well-known metadata, dynamic client registration, and a small set of redirect URI validation cases. It does not run during the normal cipher-scan . workflow or standard CI scans.

cipher-scan ./my-application --remote-url https://example.test/mcp --fail-on high

Remote connection failures are reported as low-severity transport results so static findings and the scan report are preserved. Only accepted dangerous redirect schemes produce high-severity remote findings. Use this check only against systems you are authorized to test; it is intended for lab and explicitly approved environments.

The remote OAuth probe is adapted from the concepts and minimal active probes in remote-mcp-scanner, copyright Nova Security, licensed under the MIT License. The reference project is not imported as a runtime dependency.

Install

pip install cipher-mcp-scan

Use CIPHER directly in the CLI

1. Install:

   pip install cipher-mcp-scan
   

2. Check it works:

   cipher-scan --help
   

3. Scan the current directory:

   cipher-scan . --fail-on high
   

4. Scan a specific project path:

   cipher-scan path/to/project --fail-on high
   

5. Report only without failing CI:

   cipher-scan . --fail-on none
   

6. Write a JSON report:

   cipher-scan . --fail-on high --format json --output cipher-report.json
   

7. Exit codes:
   • 0 = findings are below the selected threshold
   • 1 = findings are at or above the selected threshold
8. --fail-on values:
   • critical
   • high
   • medium
   • none

Use CIPHER in GitHub Actions

Add a workflow in your project under .github/workflows/ and run the scanner after checkout. This works for public and private repos because the scan is local to the checked-out code.

Point to the demo file in this repo at examples/github-actions-cipher-scan.yml. You can copy that file into your repo as .github/workflows/cipher-scan.yml, or paste the workflow block below.

name: CIPHER MCP Scan

on:
  pull_request:
  push:
    branches:
      - main
      - master
  workflow_dispatch:

jobs:
  cipher-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install CIPHER
        run: |
          python -m pip install --upgrade pip
          pip install cipher-mcp-scan

      - name: Run CIPHER scan
        env:
          GITHUB_STEP_SUMMARY: ${{ github.step_summary }}
        run: |
          cipher-scan . --fail-on high --summary github --output cipher-scan-report.json

      - name: Upload JSON report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: cipher-scan-report
          path: cipher-scan-report.json
          if-no-files-found: ignore

To use it in another repo:

1. Copy examples/github-actions-cipher-scan.yml to .github/workflows/cipher-scan.yml
2. Or paste the block above into that file
3. Open a PR or push to main/master to trigger the check

Optional flags

• --summary github writes a markdown summary to the Actions job summary when available
• --format text|json changes the output style
• --output REPORT.json saves the machine-readable report

Short note

v0.1 is limited to the built-in CIPHER checks. Optional third-party compare engines are future work and are not required for this package.

Longer internal notes are preserved in README_ARCHIVE.md.

CLI UX

The command-line tool has a short banner on --help / -h and no noisy startup banner on successful scans. Example help output includes the package name, version, example commands, and a one-line fail-on explanation.

Local verification

Run these locally without uploading anything:

pip install -e .
cipher-scan --help
cipher-scan ./test/Cipher-demo-main --fail-on high

The demo path is useful for a quick smoke test because it includes intentionally vulnerable MCP sample code.