Medusa

Abstract

1. Introduction

MEDUSA is an AI-first security scanner with 40,000+ detection patterns that works out of the box. Simply install and scan - no external tool installation required. MEDUSA's built-in rules detect vulnerabilities in AI/ML applications, LLM agents, MCP servers, RAG pipelines, and traditional code.

2. Objective

AI-first security scanner. NEW in v2026.7: Claude Code compromise detection — vet .claude/ hooks, permissions & skills before you clone — plus an always-on AI attack-signature scanner and native Rust & PHP rules. Also: medusa scan --git to vet any repo, medusa secrets scan for leaked API keys. 40,000+ patterns, zero setup.

This project demonstrates how Python can be applied to a real-world Cybersecurity & Ethical Hacking problem.

3. Key Features / Modules

• medusa scan --git - Scan any GitHub repo for AI supply chain attacks in seconds
• 40,000+ AI Security Patterns - Industry-leading coverage for AI/ML, agents, and LLM applications
• Repo Poisoning Detection - Detects weaponized AI editor configs across 28+ file types (Cursor, Cline, Copilot, Claude Code, Gemini, Kiro, and more)
• Zero Setup Required - Works immediately after pip install - no tool installation needed
• 200 CVE Detections - Log4Shell, Spring4Shell, XZ Utils backdoor, LangChain RCE, MCP remote code execution, React2Shell, and more
• Parallel Processing - Multi-core scanning (10-40x faster than sequential), works on macOS/Windows/Linux
• Beautiful CLI - Rich terminal output with progress bars
• IDE Integration - Claude Code, Cursor, VS Code, Gemini CLI support
• Smart Caching - Skip unchanged files for lightning-fast rescans (content-hash keyed, correct in CI)
• Configurable - .medusa.yml for project-specific settings

4. Technology Stack

5. System Requirements

General requirements for this technology stack — check the README for exact versions.

• Python 3.8 or later
• pip / virtualenv for dependencies
• VS Code, PyCharm or Jupyter Notebook
• Git (to clone the repository)

6. Installation & Setup

git clone https://github.com/Pantheon-Security/medusa.git
cd medusa

1. Windows: Use py -m medusa if medusa command is not found
2. macOS/Linux: Should work out of the box

# Install MEDUSA (works on Windows, macOS, Linux)
pip install medusa-security

# Run your first scan - that's it!
medusa scan .

# Create and activate virtual environment
python3 -m venv medusa-env
source medusa-env/bin/activate  # On Windows: medusa-env\Scripts\activate

# Install and scan
pip install medusa-security
medusa scan .

# Check tool status
medusa install --check

# Install AI tools (modelscan for ML model scanning)
medusa install --ai-tools

# Show detailed output
medusa install --ai-tools --debug

# Setup for all IDEs (recommended)
medusa init --ide all

# Or select specific platforms
medusa init --ide claude-code --ide gemini-cli

Full setup instructions are in the project README.

7. Future Enhancements

Suggested extensions you can add to make this your own project.

• Add logging and alert notifications (email / Telegram)
• Write a threat model document for the tool
• Package it with Docker for safe lab testing

8. Viva / Review Questions

Common questions examiners ask for projects in this domain.

1. Which threat or attack does this project defend against?
2. What detection or protection technique is used and what are its limits?
3. How are false positives and false negatives handled?
4. Which cryptographic algorithms or security standards are involved?
5. What legal and ethical rules apply when testing a tool like this?

9. Source Code & License

This project is developed by Pantheon-Security and published on GitHub under the GNU Affero General Public License v3.0. Please follow the license terms and credit the original author when you use or modify this code.