1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | codeql-trailofbits-skills |
| 作者/维护者 | Trail of Bits(官方) |
| 来源链接 | https://github.com/trailofbits/skills/tree/main/plugins/static-analysis/skills/codeql |
| 许可证 | CC-BY-SA-4.0 |
| GitHub Stars / Forks | 7,948 / 686(所属仓库整体数字,不代表本技能自身热度;GitHub API,2026-11-02 读取) |
| 最新版本 | 无版本标签;仓库主分支最近一次提交 2026-10-28 |
| 安装方式 | 把技能目录复制进 agent 的 skills 目录;另需 CodeQL CLI、jq、uv 与可构建的代码库 |
数据来源:上述数字取自 GitHub API;功能与评分依据来自技能正文与官方文档。
2. 功能介绍与亮点
一句话:把 CodeQL 的构建、建库、查询、结果核对做成一条可复现的 SAST 流程,而不是敲一条命令然后相信「0 findings」。
- 先验库质量,再信结果:建库成功不等于抽取成功;技能要求跑库质量检查,确认真的抽到了代码。
- 数据扩展模型:Django、Spring、Express 这类项目常在框架里二次封装数据库与请求解析,内置模型覆盖不到,技能教你怎么补 source/sink。
- 避免查询被静默丢弃:坚持生成明确的查询套件,而不是直接把 pack 名丢给
codeql database analyze。 - 零发现要排查:找不到不等于没有,技能把「抽取差、模型缺、套件过滤」列为必须排除的几种可能。
- 覆盖九种语言:Python、JS/TS、Go、Java/Kotlin、C/C++、C#、Ruby、Swift;另含 macOS Apple Silicon 的已知坑与绕法。
3. 适用场景
所属分类:安全与合规。
- 在合并前给仓库跑一遍跨函数污点分析的安全团队;
- 需要把 SAST 接进 CI、又不想被「建库成功但零抽取」骗过的工程团队;
- 审计第三方代码、想快速定位注入与反序列化链路的评估人员;
- 已有 CodeQL 但结果噪声大、需要补数据扩展模型的团队。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 技能目录安装,按描述触发 |
| Codex | 需适配 | 技能正文通用,命令与工作目录约定需按平台调整 |
| OpenClaw | 需适配 | 需要平台支持技能目录并允许执行本地命令 |
| Hermes Agent | 未验证 | 未找到该平台的接入示例 |
5. 推荐理由
CodeQL 本身很强,难的是让它在这个仓库上真的跑出东西:库建起来了但抽不到代码、查询套件被静默过滤、零发现被当成干净——这三件事它都给了明确的检查和处置。对要把 SAST 当门禁用的团队,这比一条命令的封装更有价值。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Trail of Bits 官方出品;所属仓库 7,948 stars 是整个合集热度,不代表本技能自身热度 |
| 可用性 | 7 | 文档与工作流完整,但前置较重:CodeQL CLI、jq、uv,编译型语言还要可构建的环境 |
| 安全性 | 8 | 见下方清单;本地执行 CodeQL 与检查脚本,不联网外发 |
安全性检查清单:
| 项 | 结果 |
|---|---|
| ① 执行 shell 与权限 | 通过本地 CodeQL 与辅助脚本建库、分析;作用域限于代码库与工作目录 |
| ② 联网外发 | 只在首次安装 CodeQL 时需要网络;分析过程不外发代码 |
| ③ 凭据 | 不需要 API key;私有仓库的 CodeQL 授权由用户自己的 GitHub 许可决定 |
| ④ 可疑指令 | 未见注入或夹带推广 |
| ⑤ 作者信誉 | Trail of Bits 是公开的安全研究机构,仓库提交历史完整 |
| ⑥ License | CC-BY-SA-4.0,全文可查(注意 share-alike) |
| ⑦ 维护时间 | 2026-10-28 仍在更新 |
扣分点:环境门槛高;macOS Apple Silicon 上编译型语言还要额外绕坑;CC-BY-SA 对二次分发有约束。
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与本技能的差异 |
|---|---|---|
| static-analysis-trailofbits-skills | 静态分析的入口与工具选择 | 负责「选哪把刀」;本技能负责把 CodeQL 这把刀真正跑通 |
| semgrep-rule-creator-trailofbits-skills | 写 Semgrep 规则做快速模式匹配 | 单文件、无需构建;本技能做跨函数污点分析,需要建库 |
| differential-review-trailofbits-skills | 审查一次改动引入的风险 | 面向 diff;本技能面向整个仓库的污点链 |
核心差异:同类多给规则或视角,它给的是「让 CodeQL 在这个仓库上产出可信结果」的完整流程。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价(2026-11-02)。
9. 其他补充
- 属于
trailofbits/skills合集(近百个技能),可按需只装这一条。 - 技能自带库质量检查与查询套件校验脚本,建议按文档顺序执行,不要跳步。
10. 安装使用方式
git clone https://github.com/trailofbits/skills
mkdir -p ~/.claude/skills
cp -r skills/plugins/static-analysis/skills/codeql ~/.claude/skills/
# 另需:CodeQL CLI、jq、uv(安装方式见技能正文)
装好后说「给这个仓库跑 CodeQL,重点看注入与反序列化」,它会先确认数据库质量再给结果。
11. 注意事项
- 编译型语言需要可构建的环境,否则只能退回
build-mode=none,覆盖面会下降。 - 私有仓库使用 CodeQL 受 GitHub 许可约束,商用前先确认授权。
- 零发现不等于安全,报告里必须包含库质量与套件校验的结论。
- CC-BY-SA-4.0:再分发或改写要保留署名并以相同许可共享。