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:

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

Environment Variables (MCP Server)

Scoring

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