痕迹结构
- 作者仓库星标 0
- 作者更新于 2026年8月24日 23:09
- 作者仓库 skills
- 领域
- 人工智能
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @trailofbits · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- macOS · Linux · Windows
- 运行环境要求
- Node.js · Python
- 检测到的文件与系统行为
-
- 只读
- 命令执行
- 网络行为
- 仅限本地
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Trailmark Structural Analysis
Builds a Trailmark graph and runs `engine.preanalysis()` to compute all
four pre-analysis passes. The core workflow is v0.2-safe; v0.4-only details
are included only after checking method availability, and newer builds
enrich the same output (0.5.0+ adds an `attributes` key to attack-surface
entries and `proxy.external:*` nodes from `.trailmark/links.toml`) without
any workflow change.
## When to Use
- Vivisect Phase 1 needs full structural data (hotspots, taint, blast radius, privilege boundaries)
- Detailed pre-analysis passes for a specific target scope
- Generating complexity and taint data for audit prioritization
- Inspecting proxy/unresolved-call counts, subgraph edges, or type-reference
summaries when Trailmark 0.4.0+ is installed
## When NOT to Use
- Quick overview only (use `trailmark-summary` instead)
- Ad-hoc code graph queries (use the main `trailmark` skill directly)
- Target is a single small file where structural analysis adds no value
## Rationalizations to Reject
| Rationalization | Why It's Wrong | Required Action |
|-----------------|----------------|-----------------|
| "Summary analysis is enough" | Summary skips taint, blast radius, and privilege boundary data | Run full structural analysis when detailed data is needed |
| "One pass is sufficient" | Passes cross-reference each other — taint without blast radius misses critical nodes | Run all four passes |
| "Tool isn't installed, I'll analyze manually" | Manual analysis misses what tooling catches | Report "trailmark is not installed" and return |
| "Empty pass output means the pass failed" | Some passes produce no data for some codebases (e.g., no privilege boundaries) | Return full output regardless |
| "A v0.4 field is always present" | Users may still have Trailmark 0.2.x installed | Probe with `hasattr()` before querying v0.4-only methods |
## Usage
The target directory is passed via the `args` parameter.
## Execution
**Step 1: Check that trailmark is available.**
```bash
trailmark analyze --help 2>/dev/null || \
uv run trailmark analyze --help 2>/dev/null
```
If neither command works, report "trailmark is not installed"
and return. Do NOT run `pip install`, `uv pip install`,
`git clone`, or any install command. The user must install
trailmark themselves.
Optionally record the version:
```bash
trailmark --version 2>/dev/null || uv run trailmark --version 2>/dev/null || true
```
Do not fail if this command is missing; use API feature probes below.
**Step 2: Detect languages with Trailmark's parse API.**
```bash
python3 - "{args}" <<'PY'
import json
import sys
try:
from trailmark.parse import detect_languages # canonical location since 0.3.x
except ModuleNotFoundError:
# v0.2.x predates trailmark.parse; the same function lives in query.api
from trailmark.query.api import detect_languages
print(json.dumps(detect_languages(sys.argv[1])))
PY
```
If the import fails, rerun the same snippet with `uv run --with trailmark python - "{args}"`.
If the result is `[]`, report "Trailmark found no supported languages under
target" and return.
**Step 3: Run the full structural analysis via `QueryEngine`.**
Run this snippet with `python3`. If the import fails, rerun the same snippet
under `uv run --with trailmark python - "{args}"`.
```bash
python3 - "{args}" <<'PY'
import json
import sys
try:
from trailmark.parse import detect_languages # canonical location since 0.3.x
except ModuleNotFoundError:
# v0.2.x predates trailmark.parse; the same function lives in query.api
from trailmark.query.api import detect_languages
from trailmark.query.api import QueryEngine
target = sys.argv[1]
languages = detect_languages(target)
engine = QueryEngine.from_directory(target, language="auto")
preanalysis = engine.preanalysis()
def summarize_subgraph(name: str, limit: int = 25) -> dict[str, object]:
nodes = engine.subgraph(name)
summary = {
"count": len(nodes),
"sample_ids": [node["id"] for node in nodes[:limit]],
}
if hasattr(engine, "subgraph_edges"):
summary["edge_count"] = len(engine.subgraph_edges(name))
return summary
graph = json.loads(engine.to_json())
nodes = graph.get("nodes", {})
proxy_nodes = [
node_id for node_id, node in nodes.items()
if node.get("kind") == "proxy" or node.get("origin") == "proxy"
]
payload = {
"languages": languages,
"summary": engine.summary(),
"preanalysis": preanalysis,
"attack_surface": engine.attack_surface()[:25],
"hotspots": engine.complexity_hotspots(10)[:25],
"proxy_nodes": proxy_nodes[:25],
"subgraphs": {
name: summarize_subgraph(name)
for name in engine.subgraph_names()
},
}
if hasattr(engine, "type_references"):
payload["type_reference_samples"] = {
node_id: engine.type_references(node_id)[:10]
for node_id in list(nodes)[:25]
}
print(json.dumps(payload, indent=2))
PY
```
**Step 4: Verify the output.**
The output should include:
- `languages`
- `summary`
- `preanalysis`
- `hotspots` (possibly empty)
- `proxy_nodes` (empty on v0.2.x or when there are no unresolved calls; on
0.5.0+ may include `proxy.external:*` entries declared in
`.trailmark/links.toml`)
- `subgraphs` with counts and sample IDs
On Trailmark 0.5.0+, `attack_surface` entries may carry an `attributes`
object (e.g. `solidity_visibility`, `solidity_overridden_by`). Pass it
through unchanged — downstream consumers use it to rank entrypoints.
Some subgraphs may have zero nodes for some codebases (this is
normal). Return the full JSON payload regardless.
章节与文件索引
按说明文件中的顺序排列。
何时使用
何时不使用
拒绝的理由
用途
执行
文件/命令 -> engine.preanalysis() · attributes · proxy.external:* · .trailmark/links.toml · trailmark-summary · trailmark · hasattr() · args
内容校验值 -> e84cfe1a1504
当前原文的自动摘译,尚未人工审校。
何时使用
Vivisect 第 1 阶段需要完整的结构数据(热点、污点、爆炸半径、特权边界) 针对特定目标范围的详细预分析过程 生成复杂性和污点数据以进行审核优先级 安装 Trailmark 0.4.0+ 时检查代理/未解析调用计数、子图边缘或类型引用摘要
何时不使用
仅快速概述(使用
trailmark-summary代替) 特别代码图查询(直接使用主要的trailmark技能) 目标是单个小文件,结构分析不会增加任何价值拒绝的理由
合理化 · 为什么错误 · 所需的操作 “摘要分析就足够了” · 摘要跳过污点、爆炸半径和权限边界数据 · 在需要详细数据时运行完整的结构分析 “一次传递就足够了” · 传递相互交叉引用 — 没有爆炸半径的污点会错过关键节点 · 运行所有四个传递 “工具未安装,我将手动分析” · 手动分析错过了工具捕获的内容 · 报告“未安装跟踪标记”并返回
用途
目标目录通过
args参数传递。执行
第 1 步:检查跟踪标记是否可用。如果这两个命令都不起作用,则报告“未安装跟踪标记”并返回。不要运行
pip install、uv pip install、git clone或任何安装命令。用户必须自行安装 Trailmark。