Medusa Security Skill

Identity

AI-first security scanner integration skill. Leverages Medusa's 76 scanners and 3,000+ detection patterns for comprehensive security analysis including AI/ML-specific vulnerability detection.

Capabilities

1. Full Scan — All 76 scanners, comprehensive security analysis
2. AI-Only Scan — Prompt injection, MCP security, agent security, RAG security
3. Quick Scan — Git-changed files only for rapid development feedback
4. Targeted Scan — Specific scanner categories (mcp, secrets, prompt-injection, etc.)
5. SARIF Output Parsing — Standard SARIF v2.1.0 structured findings
6. JSON Output Parsing — Medusa-native JSON format
7. OWASP Mapping — Maps findings to OWASP Agentic AI (ASI01-10) and OWASP Top 10 (A01-10)
8. Remediation Guidance — Links findings to agent-studio skills and agents
9. CI/CD Integration — Fail-on thresholds, SARIF upload for GitHub Code Scanning

Prerequisites

Python 3.10+
pip install medusa-security

Check installation: python -m medusa --version

Workflow: Full Security Scan

# Step 1: Verify installation
python -m medusa --version

# Step 2: Run scan
medusa scan . --format sarif --fail-on high

# Step 3: Parse output (use scripts/main.cjs)
node .claude/skills/medusa-security/scripts/main.cjs --mode full --target .

# Step 4: Review findings by severity
# CRITICAL → immediate fix required
# HIGH → fix before release
# MEDIUM → fix in next sprint
# LOW → track and address

Workflow: AI-Only Scan

medusa scan . --format sarif --ai-only

Scans only: prompt injection (800+ patterns), MCP security (400+ patterns), agent security (500+ patterns), RAG security (300+ patterns).

Workflow: Quick Scan (Development)

medusa scan . --format sarif --quick

Only scans git-changed files. Use during development for rapid feedback.

Workflow: Targeted Scan

# MCP security only
medusa scan . --format sarif --scanners mcp-server,mcp-config

# Secrets only
medusa scan . --format sarif --scanners secrets,gitleaks,env

# AI context files only
medusa scan . --format sarif --scanners ai-context

Output Processing

The skill uses helper scripts located at .claude/skills/medusa-security/scripts/:

Script	Purpose
sarif-parser.cjs	Parses SARIF v2.1.0 output
json-parser.cjs	Parses Medusa JSON output
finding-formatter.cjs	Formats findings with OWASP mapping
main.cjs	Orchestrates the full pipeline
cli-wrapper.cjs	Wraps Medusa CLI invocation
security-review.cjs	Deterministic report writer (no Glob recursion)

Using the Pipeline

# Full scan with structured output
node .claude/skills/medusa-security/scripts/main.cjs --mode full --target .

# AI-only scan
node .claude/skills/medusa-security/scripts/main.cjs --mode ai-only --target .

# Quick scan (git-changed files)
node .claude/skills/medusa-security/scripts/main.cjs --mode quick --target .

Deterministic Security Review (Recommended in Claude sessions)

Use this when you need the final security review report and want to avoid recursive Glob timeouts:

node .claude/skills/medusa-security/scripts/security-review.cjs

This writes:

/.claude/context/reports/security/security-review-medusa-scan-2026-02-17.md

and performs fixed-path checks on:

• .claude/hooks/
• .claude/lib/
• .claude/skills/medusa-security/scripts/
• .claude/CLAUDE.md

Important Runtime Guardrail

• Avoid recursive glob patterns like .claude/skills/medusa-security/**/* in long sessions.
• Prefer direct file reads and deterministic script entry points.

OWASP Mapping

Findings are automatically mapped to:

• OWASP Agentic AI Top 10 (ASI01-10): Goal Hijacking, Tool Misuse, Context Poisoning, etc.
• OWASP Top 10 (A01-10): Broken Access Control, Injection, Cryptographic Failures, etc.

Severity Triage

Severity	Action	Timeline
CRITICAL	Immediate fix	Before any merge
HIGH	Fix before release	Same sprint
MEDIUM	Fix in next sprint	Next cycle
LOW	Track and address	Backlog

Agent Integration

Agent	Usage
security-architect	Primary consumer. Use for comprehensive security reviews.
penetration-tester	Use for targeted vulnerability scanning with authorization.
code-reviewer	Use AI-only scan as part of code review workflow.

CI/CD Integration

# GitHub Actions example
- name: Security Scan
  run: |
    pip install medusa-security
    medusa scan . --format sarif --fail-on high -o reports/
- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: reports/medusa-results.sarif

Iron Laws

1. ALWAYS verify Medusa installation before scanning — python -m medusa --version first; a missing install produces no output instead of an error, silently masking all vulnerabilities.
2. NEVER rely on AI-only mode as the release gate — AI-only mode misses traditional SAST patterns (SQLi, XSS, path traversal); full scan covering all 76 scanners is required for release-gate decisions.
3. ALWAYS set --fail-on high in CI/CD pipelines — without a fail threshold, pipelines pass even when CRITICAL findings exist, creating false confidence in the security posture.
4. NEVER skip SARIF upload to GitHub Code Scanning — local-only SARIF is lost after the build; uploading via github/codeql-action/upload-sarif@v3 persists findings for PR review, trend tracking, and compliance audit trails.
5. ALWAYS fix CRITICAL and HIGH findings before merging — deploying with unresolved high-severity findings expands the attack surface and nullifies the security posture gain from scanning.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
Skipping installation check	Missing Medusa produces no output, not an error — all vulnerabilities silently missed	Run python -m medusa --version first; abort on non-zero exit
Using AI-only mode as a release gate	AI-only misses traditional SAST patterns (SQLi, XSS, path traversal) — 76 scanners needed for full coverage	Use full-scan mode for CI/CD gates; AI-only mode for rapid dev-time feedback only
No fail-on threshold in CI	Pipeline passes even when CRITICAL findings exist — false confidence in security posture	Always use --fail-on high in CI pipelines; adjust to --fail-on critical for high-risk repos
Ignoring MEDIUM findings	MEDIUM findings compound into exploitable chains when combined with HIGH findings	Triage MEDIUM findings each sprint; never allow them to accumulate without a tracking issue
Not uploading SARIF to Code Scanning	Findings live only in local files, lost after build — no PR-level review or trend tracking	Upload SARIF via github/codeql-action/upload-sarif@v3 in every CI run

Memory Protocol

After scanning:

• Record new vulnerability patterns in patterns.json
• Log significant findings in issues.md
• Track scan history for trend analysis
• Use recordGotcha() for recurring false positives

const manager = require('.claude/lib/memory/memory-manager.cjs');

manager.recordGotcha({
  text: 'False positive: medusa flags X pattern in Y context',
  area: 'security-scanning',
});

manager.recordPattern({
  text: 'Prompt injection found in CLAUDE.md context files',
  area: 'ai-security',
});

Related Skills

• security-architect — Threat modeling and OWASP analysis
• static-analysis — CodeQL and Semgrep SARIF analysis
• semgrep-rule-creator — Create custom Semgrep rules
• insecure-defaults — Detect hardcoded credentials
• variant-analysis — Discover vulnerability variants