trailmark-structural

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Trailmark Structural Analysis

Trailmark 结构分析

Runs

trailmark analyze

with all four pre-analysis passes.

运行

trailmark analyze

命令，执行全部四个预分析阶段。

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

Vivisect第一阶段需要完整结构数据（热点、污点、影响范围、权限边界）
需要对特定目标范围执行详细的预分析阶段
需要生成复杂度和污点数据，用于审计优先级排序

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

仅需要快速概览（请改用
```
trailmark-summary
```
）
临时代码图查询（请直接使用核心
```
trailmark
```
技能）
目标为单个小文件，结构分析没有额外价值

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

驳回理由	错误原因	所需操作
「摘要分析就足够了」	摘要分析会跳过污点、影响范围和权限边界数据	需要详细数据时，请运行完整结构分析
「只跑一个阶段就够了」	各阶段会相互交叉引用——缺少影响范围数据的污点分析会遗漏关键节点	请运行全部四个阶段
「工具没安装，我手动分析」	手动分析会遗漏工具可捕获的问题	上报「trailmark未安装」并返回
「阶段输出为空意味着运行失败」	部分阶段对某些代码库不会产生任何数据（例如没有权限边界）	无论是否有输出都返回完整结果

Usage

使用方法

The target directory is passed via the

args

parameter.

目标目录通过

args

参数传入。

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.

Step 2: Detect the primary language.

bash

find {args} -type f \( -name '*.rs' -o -name '*.py' \
  -o -name '*.go' -o -name '*.js' -o -name '*.jsx' \
  -o -name '*.ts' -o -name '*.tsx' -o -name '*.sol' \
  -o -name '*.c' -o -name '*.h' -o -name '*.cpp' \
  -o -name '*.hpp' -o -name '*.hh' -o -name '*.cc' \
  -o -name '*.cxx' -o -name '*.hxx' \
  -o -name '*.rb' -o -name '*.php' -o -name '*.cs' \
  -o -name '*.java' -o -name '*.hs' -o -name '*.erl' \
  -o -name '*.cairo' -o -name '*.circom' \) 2>/dev/null | \
  sed 's/.*\.//' | sort | uniq -c | sort -rn | head -5

Map the most common extension to a language flag:

```
.rs
```
->
```
--language rust
```
```
.py
```
-> (no flag, Python is default)
```
.go
```
->
```
--language go
```
```
.js
```
/
```
.jsx
```
->
```
--language javascript
```
```
.ts
```
/
```
.tsx
```
->
```
--language typescript
```
```
.sol
```
->
```
--language solidity
```
```
.c
```
/
```
.h
```
->
```
--language c
```
```
.cpp
```
/
```
.hpp
```
/
```
.hh
```
/
```
.cc
```
/
```
.cxx
```
/
```
.hxx
```
->
```
--language cpp
```
```
.rb
```
->
```
--language ruby
```
```
.php
```
->
```
--language php
```
```
.cs
```
->
```
--language c_sharp
```
```
.java
```
->
```
--language java
```
```
.hs
```
->
```
--language haskell
```
```
.erl
```
->
```
--language erlang
```
```
.cairo
```
->
```
--language cairo
```
```
.circom
```
->
```
--language circom
```

Step 3: Run the full structural analysis.

bash

trailmark analyze \
  --passes blast_radius,taint,privilege_boundary,complexity \
  {language_flag} {args} 2>&1 || \
uv run trailmark analyze \
  --passes blast_radius,taint,privilege_boundary,complexity \
  {language_flag} {args} 2>&1

Step 4: Verify the output.

The output should include:

Hotspot scores (complexity data)
Tainted node list (taint propagation data)
Blast radius data
Privilege boundary information

Some passes may produce no data for some codebases (this is normal). Return the full output regardless.

步骤1：检查trailmark是否可用。

bash

trailmark analyze --help 2>/dev/null || \
  uv run trailmark analyze --help 2>/dev/null

如果两条命令都无法运行，上报「trailmark未安装」并返回。不要运行

pip install

、

uv pip install

、

git clone

或任何安装命令。用户必须自行安装trailmark。

步骤2：检测主开发语言。

bash

find {args} -type f \( -name '*.rs' -o -name '*.py' \
  -o -name '*.go' -o -name '*.js' -o -name '*.jsx' \
  -o -name '*.ts' -o -name '*.tsx' -o -name '*.sol' \
  -o -name '*.c' -o -name '*.h' -o -name '*.cpp' \
  -o -name '*.hpp' -o -name '*.hh' -o -name '*.cc' \
  -o -name '*.cxx' -o -name '*.hxx' \
  -o -name '*.rb' -o -name '*.php' -o -name '*.cs' \
  -o -name '*.java' -o -name '*.hs' -o -name '*.erl' \
  -o -name '*.cairo' -o -name '*.circom' \) 2>/dev/null | \
  sed 's/.*\.//' | sort | uniq -c | sort -rn | head -5

将出现次数最多的扩展名映射为对应的语言参数：

```
.rs
```
->
```
--language rust
```
```
.py
```
-> (无参数，Python为默认语言)
```
.go
```
->
```
--language go
```
```
.js
```
/
```
.jsx
```
->
```
--language javascript
```
```
.ts
```
/
```
.tsx
```
->
```
--language typescript
```
```
.sol
```
->
```
--language solidity
```
```
.c
```
/
```
.h
```
->
```
--language c
```
```
.cpp
```
/
```
.hpp
```
/
```
.hh
```
/
```
.cc
```
/
```
.cxx
```
/
```
.hxx
```
->
```
--language cpp
```
```
.rb
```
->
```
--language ruby
```
```
.php
```
->
```
--language php
```
```
.cs
```
->
```
--language c_sharp
```
```
.java
```
->
```
--language java
```
```
.hs
```
->
```
--language haskell
```
```
.erl
```
->
```
--language erlang
```
```
.cairo
```
->
```
--language cairo
```
```
.circom
```
->
```
--language circom
```

步骤3：运行完整结构分析。

bash

trailmark analyze \
  --passes blast_radius,taint,privilege_boundary,complexity \
  {language_flag} {args} 2>&1 || \
uv run trailmark analyze \
  --passes blast_radius,taint,privilege_boundary,complexity \
  {language_flag} {args} 2>&1

步骤4：校验输出。

输出应包含：

热点得分（复杂度数据）
污点节点列表（污点传播数据）
影响范围数据
权限边界信息

部分阶段对某些代码库可能不会产生任何数据（属于正常情况）。无论如何都请返回完整输出。