Orcorus Repository Scanner

A repository security scanner for GitHub repositories, available as both an MCP server and a CLI tool. Orcorus clones a repo, runs static analysis, detects hardcoded secrets, verifies the build, and performs an AI-powered OWASP-aligned security code review — producing a scored SECURITY.md report.

Features

• Static analysis — Runs Bandit on Python code to detect common vulnerabilities
• Secrets detection — Pattern-based scanning for API keys, tokens, private keys, and credentials
• Build verification — Attempts to build/install the project (supports Python, Node, Go, Rust)
• Test detection — Identifies test frameworks (pytest, jest, mocha, vitest, unittest)
• AI security review — Agentic, multi-turn code review using an OpenAI-compatible LLM that explores the codebase with tools (read files, search code, list directories) and produces an OWASP Top 10-aligned report
• Scoring & tiering — Assigns a 0–100 security score and classifies repos as Gold / Silver / Bronze / Reject
• MCP server — Exposes scan_repo, get_report, and list_reports tools via FastMCP

Project Structure

src/                   # Core library
  __init__.py          # Public API: Scanner, ScanConfig, ScanResult
  models.py            # Data models (ScanConfig, ScanResult)
  scanner.py           # Main scanning pipeline
  analyzers.py         # Bandit, secrets, build, test, and quality checks
  ai_review.py         # Agentic AI security review loop
  report.py            # SECURITY.md report generation
server.py              # MCP server (FastMCP)
scan_repo.py           # CLI client

Quick Start

CLI

# With AI review (GitHub repo)
python scan_repo.py https://github.com/owner/repo --api-key sk-...

# Without AI review
python scan_repo.py https://github.com/owner/repo --skip-ai

# Scan a local directory in-place (absolute --subdir path)
python scan_repo.py --name SSH-Command \
  --subdir /srv/docker/orcorus-integrations/ssh-command \
  --api-key sk-... --model gpt-5.4 --base-url https://api.cometapi.com/v1

# Scan current directory
python scan_repo.py .

# Custom model / provider
python scan_repo.py https://github.com/owner/repo \
  --model gpt-5.2 \
  --base-url https://api.openai.com/v1 \
  --api-key sk-...

MCP Server

python server.py
# or
fastmcp run server.py

The server exposes three tools:

| Tool | Description | |------|-------------| | scan_repo | Scan a GitHub repo (runs as a background task) | | get_report | Retrieve a completed SECURITY.md report by name | | list_reports | List all available scan reports with scores |

MCP Client Setup

VS Code / Claude Code (settings.json)

Add the following to your MCP settings.json to run Orcorus as a Docker container:

{
  "mcpServers": {
    "scanner": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPENAI_API_KEY=sk-your-api-key-here",
        "-e", "ORCORUS_MODEL=gpt-5.2",
        "-e", "OPENAI_BASE_URL=https://api.openai.com/v1",
        "-e", "ORCORUS_REPORTS_DIR=/app/reports",
        "-e", "ORCORUS_WORK_DIR=/app/repos",
        "-e", "ORCORUS_AI_TIMEOUT=300",
        "-e", "ORCORUS_MAX_TURNS=40",
        "orcorus/security_scanner:latest"
      ]
    }
  }
}

To persist reports between runs, mount a volume:

{
  "mcpServers": {
    "scanner": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPENAI_API_KEY=sk-your-api-key-here",
        "-e", "ORCORUS_MODEL=gpt-5.2",
        "-e", "OPENAI_BASE_URL=https://api.openai.com/v1",
        "-v", "/path/to/local/reports:/app/reports",
        "orcorus/security_scanner:latest"
      ]
    }
  }
}

To skip AI review (static analysis only), add -e, "ORCORUS_SKIP_AI=true" to the args.

Configuration

CLI Arguments

| Argument | Default | Description | |----------|---------|-------------| | repo_url | . | GitHub repository URL or local path (ignored when --subdir is absolute) | | --name | auto-detected | Display name for the report | | --commit | HEAD | Specific commit to checkout | | --subdir | (none) | Subdirectory scope, or an absolute path to scan a directory in-place without cloning | | --api-key | $OPENAI_API_KEY | API key for the LLM provider | | --model | gpt-5.2 | Model to use for AI review | | --base-url | https://api.openai.com/v1 | OpenAI-compatible API base URL | | --reports-dir | ./reports | Directory to save reports | | --ai-timeout | 300 | Timeout per AI call (seconds) | | --max-turns | 40 | Max agentic review turns | | --skip-ai | false | Skip the AI review step | | --keep-repo | false | Keep the cloned repo after scanning |

Environment Variables (MCP Server)

| Variable | Default | Description | |----------|---------|-------------| | OPENAI_API_KEY | (none) | API key for AI review | | ORCORUS_MODEL | gpt-5.2 | LLM model name | | OPENAI_BASE_URL | https://api.openai.com/v1 | API base URL | | ORCORUS_REPORTS_DIR | ./reports | Reports output directory | | ORCORUS_WORK_DIR | ./repos | Temporary clone directory | | ORCORUS_AI_TIMEOUT | 300 | Timeout per AI call (seconds) | | ORCORUS_MAX_TURNS | 40 | Max agentic review turns | | ORCORUS_SKIP_AI | false | Set to 1 or true to skip AI review | | ORCORUS_ALLOW_LOCAL_PATHS | false | Set to 1 or true to allow scanning local filesystem paths via MCP |

Scoring

| Score | Tier | |-------|------| | 90–100 | Gold | | 75–89 | Silver | | 60–74 | Bronze | | 0–59 | Reject |

Deductions are applied for high/medium/low Bandit findings, hardcoded secrets, build failures, missing tests, missing README, missing dependency files, and critical/high severity issues found during AI review.

Dependencies

• Python 3.10+
• openai — LLM client
• fastmcp — MCP server framework
• bandit — Python static analysis (optional, for security scanning)
• git — for cloning repositories