1. 基本信息
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | codeql-github-awesome-copilot | 合集子目录名+拥有者+仓库名 |
| 所属合集仓库 | github/awesome-copilot(GitHub 官方社区共享技能集合) | GitHub API |
| 作者/维护者 | GitHub Advanced Security 团队贡献(提交记录标注“GHAS Pack - Agent Skills for GitHub Advanced Security”),经官方仓库审核合并 | GitHub API(commits 记录) |
| 来源链接 | https://github.com/github/awesome-copilot/tree/main/skills/codeql | — |
| 许可证 | MIT | GitHub API |
| 合集仓库整体 Stars/Forks | 39,504 / 5,024(该数字属整个合集,不代表本技能自身热度) | GitHub API |
| 最新版本 | 无独立版本号,本子技能文件最近一次实质修改为 2026-03-18 | GitHub API(commits 接口) |
| 安装方式 | gh skills install github/awesome-copilot codeql(需 GitHub CLI v2.90.0+),或手动复制 SKILL.md 到本地 skills 目录 |
官方文档 docs/README.skills.md |
2. 功能介绍与亮点
codeql 把 GitHub 官方代码安全扫描工具 CodeQL 的配置与排障整理成一套可直接照做的操作手册,覆盖两条完整路径:
- GitHub Actions 工作流:从“默认设置”到“高级设置”的切换方式、触发条件(push/pull_request/schedule/merge_group)、最小权限配置、多语言矩阵扫描、
build-mode(none/autobuild/manual)选择、monorepo 按组件拆分 SARIF 结果 - CodeQL CLI 本地工作流:安装、建库、分析、上传结果到 GitHub 的完整命令链,以及避免重复 JVM 初始化的 server 模式
- 告警管理:标准严重度与安全严重度两套体系、Copilot Autofix 自动修复建议、PR 内告警分流与关闭留痕
- 详尽故障排查表:覆盖 12 类常见问题(触发不了、权限报错、autobuild 失败、扫描行数偏少、SARIF 超限等)及对应解法
- 自托管 Runner 硬件建议:按代码规模给出内存/CPU 配置参考
技能全文为程序性配置说明,正文之外另含 5 份按需加载的参考文档,不需要一次性读完全部细节。
3. 适用场景
固定分类:安全与合规
适用于用 Claude Code、Codex 等 Agent 协助写代码、且仓库托管在 GitHub 上的初中级开发者与安全负责人:
- 需要给仓库第一次接入自动化代码安全扫描,但不确定该用默认设置还是高级设置
- CodeQL 工作流跑不起来、autobuild 失败或扫描行数明显偏少,需要按图索骥排查
- 需要为 monorepo 的多个组件分别配置扫描并区分 SARIF 结果
- 需要为特定语言组合自定义查询包或调整扫描范围
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 标准 SKILL.md 格式(YAML front matter + 指令正文),无绑定资源、无 Copilot 专有语法,可直接复制进本地 skills 目录使用 |
| Codex | 需适配 | 同样遵循 Agent Skills 规范、无绑定资源,理论上可手动复制使用,但官方文档未见针对 Codex 的专门安装说明 |
| OpenClaw | 未验证 | 已抓取材料未提及 OpenClaw 支持情况 |
| Hermes Agent | 未验证 | 已抓取材料未提及 Hermes 支持情况 |
5. 推荐理由
代码安全扫描是几乎所有仓库都该做、但配置细节容易踩坑的一件事——GitHub Actions 该用默认设置还是高级设置、编译型语言的 build-mode 怎么选、monorepo 怎么拆 SARIF、autobuild 失败了怎么办。这个技能把这些散落在官方文档各处的知识点整理成一份可直接照做的操作手册,两条路径(Actions 与 CLI)都讲,还配了一张覆盖 12 类常见故障的排查表,公开仓库启用完全免费,不需要额外注册第三方安全账号。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | GitHub 官方仓库出品,提交记录明确标注 GHAS 团队贡献;该子技能自身尚无独立于官方合并记录之外的第三方讨论量化证据 |
| 可用性 | 8 | 两条路径(Actions/CLI)的配置步骤均清晰可循,含 12 类常见故障排查表;私有仓库要用到完整 CodeQL 能力需 GitHub Advanced Security(付费功能),公开仓库零成本;子技能文件最近一次实质更新为 2026-03-18(约 6 个多月前),所属合集仓库本身持续活跃(最近一次推送为 2026-09-29) |
| 安全性 | 9 | 见下方检查清单 |
| 综合评分 | 8.0 | 三项均值 |
安全检查清单:
| 检查项 | 结果 |
|---|---|
| ① Shell 命令与权限范围 | 不自动执行任何命令,仅提供 CodeQL CLI 命令示例与 GitHub Actions YAML 片段供用户自行加入仓库 |
| ② 运行时联网外发 | 文档中提到的 codeql github upload-results 会把扫描结果上传到 GitHub 自身的 Security 页面,目标透明且就是用户自己的仓库,非第三方外发 |
| ③ API Key/凭据 | 需要 GITHUB_TOKEN(Actions 运行时自动注入的标准凭据),配置为 security-events: write 权限,用途明确 |
| ④ 可疑指令排查 | 已完整阅读 SKILL.md 全文,未发现 prompt injection 或隐藏指令 |
| ⑤ 作者/组织信誉 | GitHub 官方仓库,内容由 GitHub Advanced Security 团队贡献 |
| ⑥ License | MIT,清晰明确 |
| ⑦ 最近维护 | 所属合集仓库持续活跃(2026-09-29 仍有提交),本子技能文件最近一次实质更新为 2026-03-18 |
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与本 skill 的差异 |
|---|---|---|
| static-analysis-trailofbits-skills | 把 CodeQL 污点追踪与 Semgrep 规则扫描接入 Agent,供 Agent 在对话中即时发起一次性漏洞查询 | 是“Agent 临场调用 CodeQL 做分析”,本 skill 讲的是“把 CodeQL 接入 CI/CD 持续自动运行”,两者面向的是查询与部署两个不同阶段 |
| sast-config-unitoneai-securityskills | 用 ASVS 与 CWE Top25 框架把 Semgrep/CodeQL 的配置调优成可审计合规流程 | 定位是合规框架层面的调优建议,本 skill 是具体到 YAML 字段与 CLI 参数的操作手册,两者可配合使用 |
| security-review-github-awesome-copilot | GitHub 官方出品,让 Agent 像安全研究员一样推理代码库、追踪数据流,人工发现模式匹配工具漏检的漏洞 | 是“用 LLM 推理代替工具扫描”的深度人工审查,本 skill 是“配置自动化工具持续扫描”,两者互补而非替代 |
| semgrep-semgrep-skills | Semgrep 官方出品,一条命令跑静态安全扫描并可定制检测规则 | 是另一款 SAST 引擎的使用指南,规则语法与生态都不同,团队可能同时用 CodeQL(GitHub 原生集成)与 Semgrep(规则更灵活) |
8. 用户评价
该技能目前在第三方平台尚无具名用户评价;其覆盖的底层工具 CodeQL 是 GitHub Advanced Security 的核心组件,长期作为 GitHub 平台原生代码扫描能力对外提供。
9. 其他补充
技能内含 5 份按需加载的参考文档(references/workflow-configuration.md、references/cli-commands.md、references/sarif-output.md、references/compiled-languages.md、references/troubleshooting.md、references/alert-management.md),分别覆盖工作流配置、CLI 命令、SARIF 格式、编译型语言构建、故障排查、告警管理,正文按需引用,不必一次性全部加载。
10. 安装使用方式
通过 GitHub CLI(推荐,需 v2.90.0+):
gh skills install github/awesome-copilot codeql
手动安装:
mkdir -p ~/.claude/skills/codeql
curl -sSL https://raw.githubusercontent.com/github/awesome-copilot/main/skills/codeql/SKILL.md \
-o ~/.claude/skills/codeql/SKILL.md
安装后注意事项:无绑定脚本,纯 Markdown 说明,安装后无需重启;对话中提及“配置 CodeQL”“设置代码扫描”“CodeQL 工作流跑不起来”等诉求即可触发,或显式引用技能名调用。
11. 注意事项
- 私有仓库要用到完整 CodeQL 扫描能力,需要开通 GitHub Advanced Security(Enterprise Cloud 付费功能);公开仓库可免费使用
- 技能本身不执行扫描,实际扫描能力由 CodeQL 引擎与 GitHub Actions/CLI 提供,技能定位是“教你怎么配置和排障”
- 自托管 Runner 跑大型代码库(>1M 行)建议至少 64GB 内存,资源不足会导致分析失败或异常缓慢
- 跨 Agent 兼容性中 Codex/OpenClaw/Hermes Agent 三项尚无可验证的官方材料,建议使用前自行测试