| name | spirit-eye |
| description | 灵眸·天鉴（SpiritEye）——AI 驱动的通用静态应用安全测试（SAST）技能，用于代码漏洞分析。 SpiritEye is a general-purpose Static Application Security Testing (SAST) skill for code vulnerability analysis. 触发场景：用户要求"分析代码漏洞"、"审查代码安全"、"查找安全缺陷"、"执行 SAST 扫描"、 "检查代码中的[某类漏洞]"、"审计源代码"，或对任意语言/框架请求安全代码审查。 覆盖 Web、API、认证授权、移动端、业务逻辑等 35 类漏洞。
|
| metadata | {"version":"0.1.0","domain":"application-security","references":"35 vulnerability knowledge bases"} |
SAST 漏洞分析（灵眸·天鉴 SpiritEye）
目标
使用结构化的 Source→Sink 污点追踪、模式匹配与漏洞类专属检测规则，系统性地分析源代码中的安全漏洞。输出可落地的发现结果，包含严重性评级、受影响代码位置（文件+行号）与修复建议。
授权与合规边界
- 仅审计授权目标：默认只审计用户明确有权测试 / 审查的源代码。对外部组织或个人代码的审计，需具备书面授权（渗透测试授权书、安全评估委托等）
- 只读分析：本技能进行静态分析，不执行破坏性操作；渗透测试 payload 验证仅限已授权的靶场 / 测试环境（如 pikachu-master）
- 数据合规：审计结果可能含敏感信息，报告须妥善保管；OSS 上传仅在用户配置凭证并明确要求时进行，凭证一律走环境变量
- 禁止滥用：不得将本技能用于未授权入侵、规避安全防护或其他不当用途
覆盖范围
支持语言
本技能可审计以下语言，通过"通用漏洞类 + 语言适配检测规则 + 平台特有知识库"三层方式覆盖：
| 支持语言 | 审计方式 |
|---|
| Java | 通用 35 类漏洞 + Spring/Struts 等框架特定 Source/Sink 模式（反序列化链、JNDI、SpEL 等） |
| Python | 通用 35 类漏洞 + Django/Flask/FastAPI 等框架特定模式（pickle/yaml.load、模板注入等） |
| JavaScript / TypeScript | 通用 35 类漏洞 + Node.js/浏览器端特定模式（原型污染、NoSQL 注入等） |
| PHP | 通用 35 类漏洞 + php_security.md 平台特有知识库（eval/assert、allow_url_include 等） |
| .NET | 通用 35 类漏洞 + ASP.NET 框架特定模式（反序列化、视图注入等） |
漏洞覆盖
本技能覆盖以下 35 类漏洞。每一类都有独立的参考文档，按需加载：
| 类别 | 漏洞 |
|---|
| 注入类（Injection） | SQL 注入、XSS、SSTI、NoSQL 注入、GraphQL 注入、XXE、RCE / 命令注入、表达式语言注入 |
| 访问控制与认证（Access Control & Auth） | IDOR、越权、认证/JWT、默认凭据、暴力破解、业务逻辑、HTTP 方法篡改、验证码滥用、会话固定 |
| 数据暴露与加密（Data Exposure & Crypto） | 弱加密/弱哈希、信息泄露、不安全的 Cookie 属性、信任边界 |
| 服务端（Server-Side） | SSRF、路径穿越/LFI/RFI、不安全反序列化、任意文件上传、JNDI 注入、竞态条件 |
| 协议与基础设施（Protocol & Infrastructure） | CSRF、开放重定向、HTTP 请求走私/失步、拒绝服务、CVE 模式、供应链攻击（supply_chain） |
| 语言/平台（Language/Platform） | PHP 安全、移动端安全（Android/iOS） |
说明："语言/平台"类别仅收录平台特有漏洞知识库（PHP 安全、移动端安全）。Java、Python、JavaScript/TypeScript、.NET 的漏洞检测由上方 33 类通用漏洞知识库 + 各语言适配规则完成，并非仅能审计 PHP 与移动端。
工作流程
第 1 步：明确审计范围
确定：
- 目标：单个文件、目录、API 端点、模块或整个仓库
- 使用中的语言与框架
- 用户目标：快速扫描、深度审计、特定漏洞类型或完整报告
第 2 步：加载相关漏洞知识库
根据被审查的代码，从 references/ 加载对应的参考文档：
references/sql_injection.md — SQL / ORM 注入
references/xss.md — 跨站脚本
references/ssrf.md — 服务端请求伪造
references/rce.md — 远程代码执行
references/idor.md — 不安全的直接对象引用
references/authentication_jwt.md — 认证缺陷、JWT 弱点
references/csrf.md — 跨站请求伪造
references/path_traversal_lfi_rfi.md — 路径穿越、LFI/RFI
references/ssti.md — 服务端模板注入
references/xxe.md — XML 外部实体
references/insecure_deserialization.md — 不安全反序列化
references/arbitrary_file_upload.md — 任意文件上传
references/privilege_escalation.md — 越权提升
references/nosql_injection.md — NoSQL 注入
references/graphql_injection.md — GraphQL 注入
references/weak_crypto_hash.md — 弱加密 / 弱哈希
references/information_disclosure.md — 信息泄露
references/insecure_cookie.md — 不安全的 Cookie 属性
references/open_redirect.md — 开放重定向
references/trust_boundary.md — 信任边界破坏
references/race_conditions.md — 竞态条件 / TOCTOU
references/brute_force.md — 暴力破解 / 撞库
references/default_credentials.md — 默认 / 硬编码凭据
references/verification_code_abuse.md — 验证码滥用
references/business_logic.md — 业务逻辑缺陷
references/http_method_tamper.md — HTTP 方法篡改
references/smuggling_desync.md — HTTP 请求走私 / 失步
references/cve_patterns.md — 已知 CVE 模式
references/supply_chain.md — 供应链攻击（依赖投毒 / CI-CD 可变标签 / SBOM）
references/expression_language_injection.md — 表达式语言注入（SpEL / OGNL）
references/jndi_injection.md — JNDI 注入（Log4Shell 类）
references/denial_of_service.md — 拒绝服务 / 资源耗尽
references/php_security.md — PHP 特定安全问题
references/mobile_security.md — 移动端安全（Android / iOS）
references/session_fixation.md — 会话固定
加载策略：
- 定向审查（如"检查 SQL 注入"）：只加载相关参考文档
- 完整审计：加载全部 35 份参考文档，系统化扫描
- 即使未被明确要求，也应加载 OWASP Top 风险对应的参考文档
第 3 步：分析代码 — Source→Sink 污点追踪
对每一类已加载的漏洞，执行污点分析：
-
识别 Source（污点源） — 用户可控输入的入口点：
- HTTP 参数、请求头、Cookie、请求体
- 文件上传
- WebSocket 消息
- 环境变量
- 从数据库读取的用户数据、反序列化对象
-
追踪数据流 — 沿以下路径跟踪数据：
- 变量赋值、函数参数、返回值
- 框架辅助函数、ORM 调用、模板渲染
- 跨模块 / 跨服务边界
-
检查 Sink（汇聚点） — 接收污点数据的危险操作：
- 查询执行（SQL、NoSQL、LDAP、XPath）
- Shell / 操作系统命令执行
- 文件系统操作
- HTTP 客户端调用
- 模板渲染 / eval / 表达式解析
- 序列化 / 反序列化
-
评估净化措施 — 在 Source 与 Sink 之间，检查是否存在：
- 输入校验（白名单 vs 黑名单）
- 上下文适配的编码 / 转义
- 参数化（预处理语句）
- 框架原生防护
-
给出初步判定：
- VULN（漏洞）：污点到达 Sink 且无有效净化
- LIKELY VULN（疑似漏洞）：存在净化但按参考文档启发式规则可被绕过
- SAFE（安全）：存在有效净化或不存在污点路径
第 4 步：业务逻辑与认证授权分析
除污点追踪外，还需检查：
- 敏感端点缺少认证 / 授权
- 不安全的状态机迁移
- 并发操作中的竞态条件
- 组件之间不恰当的信任边界
- JWT 算法混淆、令牌固定、会话问题
- 默认 / 硬编码凭据
- 通过响应时间或响应差异进行的用户枚举
第 5 步：Judge — 有效性复核
上报之前，每条初步发现（VULN 或 LIKELY VULN）必须通过 Judge 复核。Judge 扮演对抗性第二意见，用于消除误报。
对每条候选发现，逐项回答以下问题：
可达性检查
净化措施重新评估
可利用性检查
Judge 判定
| 判定 | 含义 | 处理 |
|---|
| CONFIRMED（确认） | 可达性 / 净化 / 可利用性检查全部通过 | 纳入报告 |
| LIKELY（疑似） | 大部分检查通过，仅剩一处不确定 | 纳入报告，标注不确定项 |
| NEEDS CONTEXT（需上下文） | 缺少运行时行为 / 配置 / 附加文件无法确定 | 标注为"缺少 X 无法验证" |
| FALSE POSITIVE（误报） | 找到防护的正面证据——引用净化、白名单检查、守卫或框架级自动防护的确切 文件+行号，证明 Sink 安全 | 静默丢弃 |
仅 CONFIRMED 与 LIKELY 级别的发现会被上报。
误报举证责任：任何一项检查结果为 UNCERTAIN（不确定）都不足以判定为 FALSE POSITIVE。若检查完 Sink、其调用方及框架内部后仍为 UNCERTAIN，应使用 NEEDS CONTEXT。只有找到并引用路径受到保护的正面证据时，才可使用 FALSE POSITIVE。
Judge 输出格式（内部使用，上报前）
Finding: VULN-NNN — <漏洞类别>
Reachability: PASS / FAIL / UNCERTAIN — <原因>
Sanitization: PASS / FAIL / UNCERTAIN — <原因>
Exploitability: PASS / FAIL / UNCERTAIN — <原因>
Judge Verdict: CONFIRMED / LIKELY / NEEDS CONTEXT / FALSE POSITIVE
误报防护护栏
标签（Tags）
default_credentials：需存在接受该硬编码凭据的可达认证路径weak_crypto_hash：需直接使用弱加密/弱哈希——仅引入或使用第三方组件不算。涵盖弱算法（DES、RC4、ECB）与弱哈希（MD5、SHA-1 存密码）；不要单独使用 weak_crypto 标签rce：直接执行 shell/进程时优先使用 command_injection；不要用 rce/command_injection 替代 spel_injection- 演示代码中的
jndi_injection：仅当 JNDI Sink 是主要利用路径时才报
- 宽泛标签（
trust_boundary、authentication、privilege_escalation）：优先使用最窄的有效标签（xff_spoofing、session_fixation、verification_code）
open_redirect：仅当攻击者可控的重定向是主要利用方式（非基础设施/解析器配置错误）csrf：对无状态、仅 Bearer Token 的 API（SessionCreationPolicy.STATELESS）跳过insecure_deserialization：若 component_vulnerability 已覆盖同一 Sink 则跳过arbitrary_file_upload：对有限制类型且存储于 Web 根目录之外的头像/资料上传跳过session_fixation：Spring Security 默认会话管理生效时跳过information_disclosure：对配置文件中的数据库凭据跳过——属部署问题而非应用层问题
范围（Scope）
- 演示/示例代码：唯一漏洞路径位于
examples/、demo/、sample/（或类似目录）时跳过；仅当缺陷位于库/SDK 自身时才上报
- 非默认配置：上报前先验证 DEFAULT 值。需要非默认/已弃用配置 → 上限为
Low；代码/文档明确标注 legacy 或弃用 → 上限为 Informational
信任边界（Trust Boundary）
- 操作者自伤：当"攻击者"输入来自操作者自己编写的配置文件（YAML/JSON/TOML）、操作者自行提供的 CLI 参数（
--file、--url、--chain-id）或操作者必须显式运行的命令时，跳过
- 受信任的管理员角色：对
onlyAdmin/onlyOwner/onlyPoolAdmin 保护的操作跳过 privilege_escalation/business_logic（该角色按设计受信任）；仅当非特权用户也能到达同一路径时才上报
- 仅内部服务：整个代码库零认证且引用内部基础设施（VPC 变量、
EC2_INSTANCE_ID、Eureka、Consul）时，跳过 authentication 与 information_disclosure——认证在网络层完成
- 代码生成器：对输入来自开发者控制的源码注释、注解或本地配置的代码生成工具（
protoc、swagger-codegen 等）跳过 injection/path_traversal/rce
协议与架构（Protocol & Architecture）
- 协议设计性 SSRF：当按规范要求获取对等方提供的 URL 时（LNURL、UMA、OAuth discovery、WebFinger、OIDC discovery）跳过
ssrf；仅当实现允许协议不需要的 scheme（如 file://）或跳过了必需的域名校验时才上报
- 盲 SSRF：当以下三条全部成立时降级为
Informational：(a) 响应永远不会到达攻击者；(b) 对目标无有意义的副作用；(c) 无错误预言
- 有界 DoS：除非迭代/分配数据的上限由攻击者可控且无界，否则跳过
denial_of_service。天然有界的数据（区块链验证者集合、gas 限制、etcd/请求体大小上限）→ 不构成发现
- 暴力破解：仅当代码、框架配置或仓库引用的中间件中可见限流时才跳过
brute_force；不要假设基础设施层有限流
- 幂等重放：当操作幂等且参数经密码学签名（不可篡改）时，跳过重放/
business_logic
- 库的死路径：代码库中没有真实调用方触发该漏洞参数组合，且该路径有告警日志 →
NEEDS CONTEXT，不算发现
平台（Platform）
- Android 应用私有存储：生产 manifest 无
android:allowBackup="true" 时，对应用私有存储中的 SharedPreferences/DataStore 跳过 insecure_storage/information_disclosure
- Terraform state：属性标记
Sensitive: true 时，对向 state 写入密钥的 provider 跳过 information_disclosure
- 组织内 CI/CD：可变 action 标签（如
@v3）的 action 组织与仓库组织相同时跳过 supply_chain；仅上报第三方组织的 action
- 本地开发工具：README 描述为本地开发工具且无生产文档时跳过
authentication。例外：工具未绑定 localhost、在 API 响应中暴露 token 或允许破坏性操作时，上报（降级严重性）
上报前检查清单
第 6 步：输出漏洞发现
严重性分级
| 严重性 | 判定标准 |
|---|
| Critical（严重） | 直接 RCE、认证绕过、未认证数据暴露 |
| High（高危） | SQLi、SSRF、涉敏感数据的 IDOR、存储型 XSS、越权提升 |
| Medium（中危） | 反射型 XSS、CSRF、路径穿越、不安全反序列化 |
| Low（低危） | 信息泄露、开放重定向、弱加密、不安全 Cookie |
| Info（提示） | 缺少安全响应头、详细错误回显、纵深防御缺口 |
严重性降级规则： 当利用需要认证、特定非默认配置、链式前置条件，或仅能通过内部/管理员专属路径到达时，在类别默认级别基础下降一级；LIKELY 判定且可利用性标记为 UNCERTAIN 的发现，无论漏洞类型如何，一律封顶在类别默认级别之下的一级。
发现格式
[SEVERITY] VULN-NNN — <漏洞类别> [CONFIRMED | LIKELY]
File: <路径>:<行号>
Description: <一句话——漏洞是什么>
Impact: <攻击者能达成什么>
Evidence:
<相关代码片段>
Judge: <一句话——为何通过复核>
Remediation: <具体修复方案——非泛泛建议>
Reference: references/<漏洞>.md
NEEDS CONTEXT 类发现的格式：
[UNVERIFIABLE] VULN-NNN — <漏洞类别>
File: <路径>:<行号>
Blocked by: <需要什么附加上下文>
报告结构
报告输出采用双轨制，避免中间产物不一致：
- 对话内摘要：在回复中直接给出 markdown 摘要（下方结构），供用户即时阅读；不落盘、不生成
sast_report.md
- 结构化落盘：正式数据一律按第 7 步的
<project>_report.json schema 落盘，由报告生成器产出 docx/html——sast_report.md 不再作为中间产物
对话内摘要格式：
# SAST 安全报告 — <目标>
Date: <日期>
Analyzer: 灵眸·天鉴（SpiritEye）v0.1.0
## 摘要
<2-3 句：按严重性统计发现总数、最严重问题>
## 严重发现（Critical）
## 高危发现（High）
## 中危发现（Medium）
## 低危发现（Low）
## 提示（Informational）
## 无法验证的发现（Unverifiable）
## 修复优先级
<有序修复清单>
第 7 步：生成并上传报告
每次审计都必须产出标准化报告并上传至 OSS。使用 reports/ 中的报告生成器：
- 整理结构化数据 — 将审计结果按
reports/pikachu_report.json 的 schema 组织为 <project>_report.json（报告元信息、目标、方法、含严重性统计/P0/P1 的摘要、章节、含描述/证据/利用/修复的发现列表、整改跟踪表）
- 环境准备（首次使用） — 安装报告生成器依赖：
python -m pip install -r reports/requirements.txt
依赖：python-docx（Word 报告，必装）、oss2（OSS 上传，仅 --upload 时需要）
- 生成并上传 — 运行：
python reports/generate_report.py reports/<project>_report.json --upload
该命令在 JSON 所在目录生成 <date>_<project>_安全自查报告.docx 与 .html，并将两者上传至 OSS（目标地址由环境变量 OSS_BUCKET / OSS_ENDPOINT 指定，不在代码或文档中写死）。
- OSS 凭证从环境变量
OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET 读取（切勿硬编码）
- 跳过上传：去掉
--upload；重新生成 Word 占位符模板：加 --make-template
- 回报结果 — 向用户提供本地文件路径与 OSS 公网 URL
核心原则
- 证据优先于断言：始终展示漏洞代码路径，而非仅给出模式名称
- 上下文决定一切：只有当 Sink 能收到用户可控数据时才成立
- 避免误报：若存在净化，先验证其可绕过性再标记 VULN
- 精确表达：包含确切文件路径与行号——绝不模糊
- 修复重于标记：始终提供具体修复方案，而非只描述问题
- 语言感知：将 Sink/Source 模式适配到具体语言与框架
