Metadata-Version: 2.4
Name: cipher-mcp-scan
Version: 0.1.1
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 four focused checks: authentication, over-privilege, CVE lookup, and typosquatting.

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