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 that explores the codebase with tools (read files, search code, list directories) and produces an OWASP Top 10-aligned report. Two backends: any OpenAI-compatible LLM, or the Claude Code CLI driven in print mode

• 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

Related MCP server: shieldbot

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

Claude Code CLI backend

If the claude CLI is installed and logged in, the scanner can hand the review to it instead of calling an API directly. Claude explores the checkout with its own read-only tools (Read, Grep, Glob, LS); no API key is needed.

python scan_repo.py https://github.com/owner/repo --ai-backend claude-cli            # model: sonnet
python scan_repo.py https://github.com/owner/repo --ai-backend claude-cli --model opus
python scan_repo.py https://github.com/owner/repo --ai-backend claude-cli \
  --ai-timeout 900 --max-budget-usd 2 --json-out result.json

How the CLI is invoked, and why:

• claude -p --output-format json with the prompt on stdin; the JSON result carries the report plus cost and turn counts, which land in ScanResult.ai_cost_usd / ai_turns.

• Tools are restricted to Read,Grep,Glob,LS via --tools / --allowedTools, and Bash, Edit, Write, web and agent tools are disallowed, so the reviewer can only look.

• --setting-sources user and --strict-mcp-config stop a scanned repository's own .claude/settings.json, hooks or MCP config from being honoured. The system prompt also tells the model to treat CLAUDE.md, AGENTS.md and READMEs in the repo as untrusted evidence.

• --ai-timeout bounds the whole review for this backend (default 900s). --max-turns and --max-budget-usd are passed through when the installed CLI supports them.

• Nested-session environment variables (CLAUDECODE, CLAUDE_CODE_*) are stripped so a scan can be launched from inside a Claude Code session.

Set ORCORUS_AI_BACKEND=claude-cli (and optionally ORCORUS_CLAUDE_BIN, ORCORUS_MODEL, ORCORUS_MAX_BUDGET_USD) to use the same backend from the MCP server. The Docker image does not ship the Claude CLI; this backend is meant for host runs.

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 (only for the openai backend; imported lazily)

• Claude Code CLI — only for the claude-cli backend

• fastmcp — MCP server framework

• bandit — Python static analysis (optional, for security scanning)

• git — for cloning repositories