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