cpg-analysis

cpg-analysis 技能概览

cpg-analysis 是一项用于深度代码分析的技能，适合普通仓库快速浏览已经不够用的场景。它帮助你借助 Joern CPG 和 CodeQL 推理控制流、数据流、程序依赖、taint 路径以及安全问题。如果你在做安全审计、跨函数追踪 bug，或者要证明输入如何到达 sink，那么就该用 cpg-analysis 技能。

最适合的场景：安全审计与流向追踪

在 Security Audit 工作中，cpg-analysis 尤其适合回答这类问题： “这个输入能不能到达危险的 sink？”或者“一个 source 到 sink 的路径在多个文件之间是怎么连起来的？”当任务需要有证据支撑的分析，而不是停留在表层代码解释时，它最有价值。

它的不同之处

cpg-analysis 不像通用提示那样只是泛泛分析，而是围绕图谱推理来设计：用 AST 看结构，用 CFG 看执行顺序，用 data-flow graph 看传播路径。它带来的实际区别，是在安全性和正确性问题上可追溯性更强，尤其在大型代码库里，简单的 grep 或摘要往往会错过真正的路径。

什么时候值得安装

如果你预期会反复做深度静态分析、taint 跟踪或漏洞排查，就值得安装 cpg-analysis。若你只是需要快速导航代码，一级记忆类工具通常已经够用，而且运行成本更低。

如何使用 cpg-analysis 技能

安装 cpg-analysis 并确认运行环境

先通过仓库的 skill manager 安装 cpg-analysis 技能，然后确认你准备使用的分析路径所需的运行环境。基于 Joern 的工作流通常需要 Docker 和 JVM；基于 CodeQL 的工作流则需要 CodeQL CLI。如果你在本地或当前环境里无法运行这些工具，那么无论提示词写得多好，技能能力都会受到限制。

从正确的文件开始读起

先阅读 SKILL.md，再看其中关于 tier 选择、何时使用 Joern，以及关键 MCP tools 的部分。这些内容会先告诉你该选哪条分析路径，再决定是否值得花时间生成 query。如果技能引用了特定的 repository tree，优先按那张地图走，不要只凭记忆猜目录结构。

把模糊需求改写成可用提示词

cpg-analysis 想要发挥效果，起点应该是具体的分析目标，而不是一句“帮我分析这个仓库”。建议明确写出：

• 仓库或子目录
• 语言或框架（如果已知）
• 安全问题或 bug 假设
• 你关心的 source、sink 或功能点
• 任何约束，例如“不要运行时执行”或“重点看 auth flow”

提示词示例：
Use cpg-analysis to trace whether user-controlled input from the API reaches command execution in src/ without sanitization. Focus on interprocedural paths and show the key nodes and files.

采用分阶段工作流

高质量的 cpg-analysis 指南通常最好分两步：先把相关面铺开，再去深挖路径。先广泛定位入口点和候选 sink，再收窄到具体函数或文件。这样可以减少过早下结论的风险，也能让输出真正贴合实际 data flow，而不是停留在表面关联。

cpg-analysis 技能 FAQ

cpg-analysis 只适合安全工作吗？

不是。安全审计当然是最典型的用途，但这项技能同样适合 bug 排查、执行路径推理，以及理解值在复杂代码库中如何移动。只要问题依赖控制流或数据流，而不是简单的文本匹配，它就很有价值。

每次都需要 Joern 和 CodeQL 吗？

不一定。通常来说，Joern 更适合作为基于 CPG 的探索起点；而当你需要跨函数的安全查询或漏洞模式时，CodeQL 往往更强。要按问题选工具，不要默认两个都跑。

cpg-analysis 对新手友好吗？

它对新手是可用的，但前提是任务要具体。问题太模糊，分析结果也会很模糊。如果你能说清文件、输入来源和有风险的 sink，cpg-analysis 会更容易用好。

什么时候不该用 cpg-analysis？

如果你只是想查文档、做基础重构建议，或者快速总结单个文件，就不要优先用 cpg-analysis。它是安装成本较高的技能，只有当分析深度足以证明图谱工具的价值时，才真正划算。

如何改进 cpg-analysis 技能

把分析目标收得更窄

最重要的改进，是缩小范围。“找安全问题”太宽泛；“追踪 routes/ 里的 request params 是否能到达 exec 或 SQL query construction”就具体得多。明确 source 和 sink，能让 cpg-analysis 的输出更可操作，也能减少无效遍历。

把关键约束说清楚

如果你的环境禁止 Docker、代码库是 polyglot，或者你只想做静态分析，要一开始就说明。约束会改变可行的工作流，也能避免技能建议你根本无法运行的路径。对于 cpg-analysis 的安装决策来说，这往往就是“有用”和“没法用”的分界线。

要求给出证据，而不是结论

在反复迭代时，要求它给出链路：入口点、中间函数、图节点，以及最终 sink。这样才能迫使结果展示出在 Security Audit 里真正重要的推理过程。如果第一轮太宽，就通过指定文件集合或下一步想看的 query 类型来收窄。

用更好的假设重新跑一遍

如果第一次结果噪声很大，不要只说“再来一遍”，而是把假设改得更好。比如，把“找 auth 问题”改成“追踪从 router 到敏感 handler 的未认证访问，排除测试代码和 mock”。更强的假设，通常也是拿到更高信噪比 cpg-analysis 结果最快的方法。