做代码安全分析需要调用路径、攻击面…

在审计陌生或多语言代码库、需要从入口点追踪到敏感函数、枚举攻击面、定位复杂度热点、计算爆炸半径或跨 FFI/RPC 边界关联源码与二进制图时，用 Trailmark 构建并查询代码图。

适用场景

解决思路

1. 若 `trailmark` 未安装，先执行 `uv tool install trailmark` 安装 CLI；注意工具安装只提供 CLI，并不能让 `import trailmark` 可解析，运行 Python 片段必须用 `uv run --with trailmark python -`，这才是修复 import/ModuleNotFoundError 的办法。
2. 不要因导入失败就退回手工读源码或“手动验证”，必须安装并以编程方式使用该工具；若安装失败，向用户报告错误而不是静默改成人工读代码。
3. 使用标为 v0.4+ / v0.5+ 的特性前先查版本：`trailmark --version 2>/dev/null || uv run trailmark --version 2>/dev/null`，按数值而非字典序比较；若版本命令失败，用 `trailmark analyze --help` 区分是 pre-0.2.2 安装还是根本没装。
4. 程序化探测特性时用 `hasattr(engine, "方法名")` 判断并回退（例如 `hasattr(engine, "subgraph_edges")` 否则从 `engine.to_json()` 的边里筛选两端都在 `engine.subgraph("tainted")` 中的边）；注意 v0.5.0 没有新增 QueryEngine 方法，`hasattr` 无法探测 v0.5 特性。
5. 门控 v0.5 特性时改用版本号或结构化探测，例如 `from trailmark.models.nodes import NodeKind` 后判断 `"SCHEMA" in NodeKind.__members__`。
6. 语言未知或仓库为多语言时优先用 `--language auto`（CLI）或 `trailmark.parse.detect_languages()`；已知多语言目标用显式逗号列表：`uv run trailmark analyze --language python,rust {targetDir}`。
7. 不要在下游流程里硬编码语言表，先调用 `supported_languages()` 向已安装的 Trailmark 构建询问支持哪些解析器。
8. 构建图与摘要：`uv run trailmark analyze --language auto --summary {targetDir}`；查复杂度热点：`uv run trailmark analyze --language auto --complexity 10 {targetDir}`；枚举入口点：`uv run trailmark entrypoints --language auto {targetDir}`；结构 diff：`uv run trailmark diff --language auto --repo {repoDir} main HEAD --json`。
9. v0.4+ 可用原生图命令：`uv run trailmark diagram -t {targetDir} -T call-graph -f main --depth 2`。
10. 程序化建图：`QueryEngine.from_directory("{targetDir}", language="auto")` 或 `language="python,rust"`。
11. 做基础查询：`engine.callers_of()`、`callees_of()`、`paths_between()`、`complexity_hotspots(threshold=10)`、`attack_surface()`、`summary()`、`to_json()`。
12. 做传递切片与入口路径查询：`engine.ancestors_of("sensitive_sink")`、`engine.reachable_from("entry_func")`、`engine.entrypoint_paths_to("sensitive_sink")`。
13. v0.4+ 下需要连接命名子图时，先 `hasattr(engine, "connect_subgraphs")` 再调用 `engine.connect_subgraphs("tainted", "privilege_boundary")`。
14. 始终先运行 `result = engine.preanalysis()` 再做其他技能的交接（genotoxic、diagramming-code）；它会加入四类处理：爆炸半径估计、按信任级别枚举入口点并计算可达集、检测信任级别变化的特权边界调用边、标记从不可信入口点可达节点的污点传播。
15. 查询 pre-analysis 产生的命名子图：`engine.subgraph_names()`、`engine.subgraph("tainted")`、`engine.subgraph("high_blast_radius")`、`engine.subgraph("privilege_boundary")`、`engine.subgraph("entrypoint_reachable")`；v0.4+ 用 `engine.subgraph_edges("tainted")`。
16. 添加 LLM 推断注解：`engine.annotate("function_name", AnnotationKind.ASSUMPTION, "input is URL-encoded", source="llm")`（从 `trailmark.models` 导入 `AnnotationKind`）。
17. 查询与清理注解：`engine.annotations_of("function_name")`、按类型 `engine.annotations_of("function_name", kind=AnnotationKind.BLAST_RADIUS)` 或 `TAINT_PROPAGATION`、`engine.nodes_with_annotation(AnnotationKind.FINDING)`、`engine.clear_annotations("function_name", kind=AnnotationKind.ASSUMPTION)`。
18. v0.4+ 的泛型/类型引用与二进制增强：`engine.generic_parameters("GenericTypeOrFunction")`、`engine.type_references("function_name")`、`engine.augment_binary("binary_graph.json")`（仅导入外部二进制分析图 JSON，工具自身不做反汇编）。
19. v0.5+ 跨语言/FFI/RPC 边界：在分析根目录写 `.trailmark/links.toml` 声明边，字段含 `source`、`target`、`kind`（任意 EdgeKind，默认 calls）、`confidence`（certain|inferred|uncertain，默认 inferred）、`description`；目标未解析时加 `target_external = true`（源未解析用 `source_external = true`），会生成 `proxy.external:<symbol>` 节点；先声明边界边再做路径与污点查询。
20. `.trailmark/links.toml` 校验是 fail-closed 的：引用有歧义、内部端点未知、枚举值非法、TOML 格式错误都会抛 `ValueError`；配置产生的边带 `configured_by = .trailmark/links.toml` 属性，可与解析器派生边区分。
21. 查询时要考虑边的置信度：`certain`（直接调用、`self.method()`）、`inferred`（非 self 对象属性访问）、`uncertain`（动态分发）；在安全结论中必须计入 `uncertain` 边，因为类型混淆类漏洞常藏在动态分发处。
22. 把 `proxy.unresolved:<symbol>` 等代理节点当成分辨解析缺口、动态分发、外部 API 或二进制链接候选的信号，不要当源码函数使用。
23. 不要做图采样，构建完整图后用子图查询聚焦，否则会漏掉跨模块攻击路径；同时把复杂度与 taint、爆炸半径数据结合看，低复杂度但位于污点路径上的函数是高价值目标。
24. 不要把可达性当污点：`entrypoint_paths_to()` 报告的是调用图可达性，preanalysis 的 taint 子图只是“从不可信入口点可达”的粗粒度信号，Trailmark 不做过程间污点分析，二者都不能当作攻击者可控数据到达 sink 的证明。
25. 多语言仓库按组件使用正确的 `--language`，跨 FFI 边界先声明 `.trailmark/links.toml` 再跨边界查询；需要单个可疑函数/候选发现的证据包时交给 `trailmark-finding-triage`，已有种子问题需要图派生的变体候选时交给 `trailmark-variant-neighborhood`。

适用边界 · 注意事项

• 单文件脚本这类调用图没有价值的场景，直接读文件即可。
• 基于代码推导之外的架构图，改用 diagramming-code 技能或手绘。
• 运行时行为分析：Trailmark 是静态分析，不做动态行为分析。