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

• Full Scan — All 76 scanners, comprehensive security analysis

• AI-Only Scan — Prompt injection, MCP security, agent security, RAG security

• Quick Scan — Git-changed files only for rapid development feedback

• Targeted Scan — Specific scanner categories (mcp, secrets, prompt-injection, etc.)

• SARIF Output Parsing — Standard SARIF v2.1.0 structured findings

• JSON Output Parsing — Medusa-native JSON format

• OWASP Mapping — Maps findings to OWASP Agentic AI (ASI01-10) and OWASP Top 10 (A01-10)

• Remediation Guidance — Links findings to agent-studio skills and agents

• 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

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

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

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

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

• 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