medusa-security

Medusa 安全技能

身份

面向 AI 的安全扫描器集成技能。利用 Medusa 的 76 个扫描器和 3,000 多种检测模式，进行全面的安全分析，包括 AI/ML 专属漏洞检测。

功能

1. 完整扫描 — 使用全部 76 个扫描器，进行全面的安全分析
2. 仅 AI 扫描 — 提示词注入、MCP 安全、Agent 安全、RAG 安全
3. 快速扫描 — 仅扫描 Git 中已更改的文件，以便快速获取开发反馈
4. 定向扫描 — 指定扫描器类别（mcp、secrets、prompt-injection 等）
5. SARIF 输出解析 — 标准 SARIF v2.1.0 结构化发现结果
6. JSON 输出解析 — Medusa 原生 JSON 格式
7. OWASP 映射 — 将发现结果映射到 OWASP Agentic AI（ASI01-10）和 OWASP Top 10（A01-10）
8. 修复指南 — 将发现结果链接到 agent-studio 技能和 Agent
9. CI/CD 集成 — 失败阈值、用于 GitHub Code Scanning 的 SARIF 上传

前提条件

Python 3.10+
pip install medusa-security

检查安装情况：python -m medusa --version

工作流：完整安全扫描

# 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

工作流：仅 AI 扫描

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

仅扫描：提示词注入（800 多种模式）、MCP 安全（400 多种模式）、Agent 安全 （500 多种模式）、RAG 安全（300 多种模式）。

工作流：快速扫描（开发）

medusa scan . --format sarif --quick

仅扫描 Git 中已更改的文件。开发期间可使用此功能快速获取反馈。

工作流：定向扫描

# 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

输出处理

该技能使用位于 .claude/skills/medusa-security/scripts/ 的辅助脚本：

脚本	用途
sarif-parser.cjs	解析 SARIF v2.1.0 输出
json-parser.cjs	解析 Medusa JSON 输出
finding-formatter.cjs	根据 OWASP 映射格式化发现结果
main.cjs	编排完整流程
cli-wrapper.cjs	封装 Medusa CLI 调用
security-review.cjs	确定性报告编写器（不递归使用 Glob）

使用流水线

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

确定性安全审查（建议在 Claude 会话中使用）

需要生成最终安全审查报告，且希望避免递归 Glob 超时问题时，请使用此功能：

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

此操作会写入：

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

并对以下路径进行固定路径检查：

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

重要运行时防护措施

• 长时间会话中，避免使用 .claude/skills/medusa-security/**/* 之类的递归 glob 模式。
• 优先直接读取文件，并使用确定性的脚本入口。

OWASP 映射

发现结果会自动映射到：

• OWASP Agentic AI Top 10（ASI01-10）：目标劫持、工具滥用、上下文投毒等。
• OWASP Top 10（A01-10）：访问控制失效、注入、加密失效等。

严重性分级

严重性	操作	时间安排
CRITICAL	立即修复	在任何合并前
HIGH	发布前修复	同一冲刺周期
MEDIUM	下个冲刺周期修复	下个周期
LOW	跟踪并处理	待办事项

Agent 集成

Agent	用法
security-architect	主要使用者。用于全面的安全审查。
penetration-tester	经授权后，用于定向漏洞扫描。
code-reviewer	在代码审查工作流中使用仅 AI 扫描。

CI/CD 集成

# 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

铁律

1. 始终在扫描前验证 Medusa 是否已安装——先运行 python -m medusa --version；未安装时不会产生任何输出，而不是报错，因此会悄无声息地掩盖所有漏洞。
2. 绝不要将仅 AI 模式作为发布门禁——仅 AI 模式会漏掉传统 SAST 模式（SQLi、XSS、路径遍历）；发布门禁决策需要覆盖全部 76 个扫描器的完整扫描。
3. 在 CI/CD 流水线中始终设置 --fail-on high——若不设失败阈值，即使存在 CRITICAL 发现，流水线仍会通过，造成对安全态势的虚假信心。
4. 绝不要跳过将 SARIF 上传到 GitHub Code Scanning——仅保存在本地的 SARIF 会在构建结束后丢失；通过 github/codeql-action/upload-sarif@v3 上传，可保留发现结果，用于 PR 审查、趋势跟踪和合规审计记录。
5. 合并前始终修复 CRITICAL 和 HIGH 发现——带着未解决的高严重性发现进行部署会扩大攻击面，并抵消扫描带来的安全态势改善。

反模式

反模式	失败原因	正确做法
跳过安装检查	Medusa 未安装时不会产生任何输出，而不是报错——所有漏洞都会悄无声息地被漏掉	先运行 python -m medusa --version；非零退出时中止
将仅 AI 模式用作发布门禁	仅 AI 模式会漏掉传统 SAST 模式（SQLi、XSS、路径遍历）——完整覆盖需要 76 个扫描器	在 CI/CD 门禁中使用完整扫描模式；仅在开发期间使用仅 AI 模式快速反馈
CI 中未设置失败阈值	即使存在 CRITICAL 发现，流水线仍会通过——造成对安全态势的虚假信心	在 CI 流水线中始终使用 --fail-on high；对于高风险仓库，可调整为 --fail-on critical
忽略 MEDIUM 发现	与 HIGH 发现结合时，MEDIUM 发现会累积成可利用的攻击链	每个冲刺周期都对 MEDIUM 发现进行分类处理；绝不要让它们在没有跟踪问题的情况下不断累积
未将 SARIF 上传到 Code Scanning	发现结果仅保存在本地文件中，构建结束后便会丢失——无法进行 PR 级审查或趋势跟踪	在每次 CI 运行中通过 github/codeql-action/upload-sarif@v3 上传 SARIF

记忆协议

扫描后：

• 在 patterns.json 中记录新的漏洞模式
• 在 issues.md 中记录重要发现
• 跟踪扫描历史以分析趋势
• 对反复出现的误报使用 recordGotcha()

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',
});

相关技能

• security-architect — 威胁建模和 OWASP 分析
• static-analysis — CodeQL 和 Semgrep SARIF 分析
• semgrep-rule-creator — 创建自定义 Semgrep 规则
• insecure-defaults — 检测硬编码凭据
• variant-analysis — 发现漏洞变体