AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

trailmark

Builds and queries multi-language source and binary code graphs for security analysis. Includes pre-analysis passes for blast radius, taint propagation, privilege boundaries, entry point enumeration, proxy/unresolved-call tracking, type/reference queries, structural traversal, graph diffs, audit augmentation, declared cross-language/FFI/external links via `.trailmark/links.toml`, and SQL schema graphs. Use when analyzing call paths, mapping attack surface, finding complexity hotspots, enumerating entry points, tracing taint propagation, measuring blast radius, importing SARIF/weAudit/binary findings, linking source graphs across language or RPC boundaries, or building a code graph for audit prioritization. Feature-gate version-specific Trailmark APIs before using them; prefer `trailmark.parse.detect_languages()` or `--language auto` when the target language is unknown or polyglot.

Original source
trailofbits
License
CC-BY-SA-4.0
Pinned revision
2be6433b39e009cd2b6fd3be1895f6b1faa5af9a

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read trailofbits--trailmark at revision 2be6433b39e009cd2b6fd3be1895f6b1faa5af9a, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 3

references/preanalysis-passes.md

Pre-Analysis Passes

Four passes that enrich the code graph before downstream skills (genotoxic, diagramming-code) consume it. Run via engine.preanalysis().

Contents

  • Blast radius estimation
  • Entry point enumeration
  • Privilege boundary detection
  • Taint propagation
  • Subgraph reference
  • Annotation reference

1. Blast Radius Estimation

Counts how many nodes are reachable downstream (descendants) and upstream (ancestors) from each function. High blast radius means a bug in that function affects many others.

Annotation: AnnotationKind.BLAST_RADIUS on every node.

"12 downstream, 3 upstream; critical: db_query, auth_check"

Subgraph: high_blast_radius — nodes with >= 10 downstream descendants.

engine.preanalysis()

# All high-blast-radius nodes
high = engine.subgraph("high_blast_radius")
for node in high:
    print(f"{node['id']}: CC={node['cyclomatic_complexity']}")

# Per-node annotation
for ann in engine.annotations_of("handler",
                                  kind=AnnotationKind.BLAST_RADIUS):
    print(ann["description"])

2. Entry Point Enumeration

Collects all entrypoints, groups them by trust level, and computes the full set of reachable nodes from any entrypoint.

Subgraphs:

| Name | Contents | |------|----------| | entrypoints | All entrypoint nodes | | entrypoint_reachable | Every node reachable from any entrypoint | | entrypoints:untrusted_external | Entrypoints at untrusted level | | entrypoints:semi_trusted_external | Entrypoints at semi-trusted level | | entrypoints:trusted_internal | Entrypoints at trusted level |

import json

engine.preanalysis()

# Nodes NOT reachable from any entrypoint (potential dead code)
reachable_ids = {n["id"] for n in engine.subgraph("entrypoint_reachable")}
graph = json.loads(engine.to_json())
all_ids = set(graph["nodes"])
dead_ids = sorted(all_ids - reachable_ids)

On Trailmark 0.5.0+, Solidity entrypoints come from parser metadata rather than signature-line regexes: interface members are excluded, external/public visibility is read from solidity_visibility, and base implementations shadowed by a derived contract carry a solidity_overridden_by attribute. engine.attack_surface() surfaces these via each entry's optional attributes key (0.5.0+).


3. Privilege Boundary Detection

Finds call edges where the source and target are reachable from entrypoints at different trust levels. These boundaries are where untrusted data crosses into trusted zones.

Annotation: AnnotationKind.PRIVILEGE_BOUNDARY on boundary nodes.

"trust transition across call: untrusted_external -> trusted_internal"

Subgraph: privilege_boundary — all nodes sitting on a trust boundary.

engine.preanalysis()

boundary = engine.subgraph("privilege_boundary")
for node in boundary:
    anns = engine.annotations_of(
        node["id"], kind=AnnotationKind.PRIVILEGE_BOUNDARY)
    for a in anns:
        print(f"{node['id']}: {a['description']}")

4. Taint Propagation

Propagates taint from every untrusted and semi-trusted entrypoint through call edges. Trusted entrypoints do not generate taint. Each tainted node is annotated with the entrypoint(s) that reach it.

Annotation: AnnotationKind.TAINT_PROPAGATION on tainted nodes.

"tainted via: handle_request, parse_input"

Subgraph: tainted — all nodes reachable from any non-trusted entrypoint.

This is call-graph reachability used as a coarse taint signal, not interprocedural data-flow analysis. Membership in tainted means an untrusted entrypoint can reach the node, not that attacker-controlled data demonstrably flows into it — verify data flow manually before claiming it.

engine.preanalysis()

tainted = engine.subgraph("tainted")
for node in tainted:
    anns = engine.annotations_of(
        node["id"], kind=AnnotationKind.TAINT_PROPAGATION)
    print(f"{node['id']}: {anns[0]['description']}")

Subgraph Reference

All subgraphs created by engine.preanalysis():

| Subgraph | Pass | Description | |----------|------|-------------| | high_blast_radius | Blast radius | Nodes with >= 10 downstream descendants | | entrypoints | Entry point enum | All entrypoint nodes | | entrypoint_reachable | Entry point enum | Union of all entrypoint-reachable nodes | | entrypoints:{trust_level} | Entry point enum | Entrypoints grouped by trust level | | privilege_boundary | Privilege boundary | Nodes on trust-level transitions | | tainted | Taint propagation | All nodes reachable from non-trusted entrypoints |

Query any subgraph:

nodes = engine.subgraph("tainted")
names = engine.subgraph_names()

# Trailmark 0.4.0+
if hasattr(engine, "subgraph_edges"):
    tainted_call_edges = engine.subgraph_edges("tainted", edge_kinds=("calls",))

Use subgraph_edges() only after checking for Trailmark 0.4.0+ or probing the method. On v0.2.x, export engine.to_json() and filter edges whose endpoints are both in engine.subgraph(name).


Annotation Reference

Annotations added by pre-analysis (source = "preanalysis"):

| Kind | Pass | Description format | |------|------|--------------------| | blast_radius | Blast radius | "N downstream, M upstream; critical: ..." | | privilege_boundary | Privilege boundary | "trust transition across call: X -> Y" | | taint_propagation | Taint propagation | "tainted via: ep1, ep2" |

Query annotations:

from trailmark.models import AnnotationKind

engine.annotations_of("func", kind=AnnotationKind.BLAST_RADIUS)
engine.annotations_of("func", kind=AnnotationKind.PRIVILEGE_BOUNDARY)
engine.annotations_of("func", kind=AnnotationKind.TAINT_PROPAGATION)