Metadata-Version: 2.4
Name: cipher-mcp-scan
Version: 0.1.2
Summary: Local security scan CLI for Cipher checks
Author: Cipher
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: requests<3.0.0,>=2.31.0

# 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.

```bash
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](https://github.com/novasecuritynz/remote-mcp-scanner), copyright Nova Security, licensed under the MIT License. The reference project is not imported as a runtime dependency.

## Install

```bash
pip install cipher-mcp-scan
```

## Use CIPHER directly in the CLI

1. Install:
   ```bash
   pip install cipher-mcp-scan
   ```
2. Check it works:
   ```bash
   cipher-scan --help
   ```
3. Scan the current directory:
   ```bash
   cipher-scan . --fail-on high
   ```
4. Scan a specific project path:
   ```bash
   cipher-scan path/to/project --fail-on high
   ```
5. Report only without failing CI:
   ```bash
   cipher-scan . --fail-on none
   ```
6. Write a JSON report:
   ```bash
   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](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.

```yaml
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](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](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:

```bash
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.
