Trailmark

Parses source code into a directed graph of functions, classes, calls, and semantic metadata for security analysis. Supports 16 languages.

When to Use

• Mapping call paths from user input to sensitive functions
• Finding complexity hotspots for audit prioritization
• Identifying attack surface and entrypoints
• Understanding call relationships in unfamiliar codebases
• Security review or audit preparation across polyglot projects
• Adding LLM-inferred annotations (assumptions, preconditions) to code units
• Pre-analysis before mutation testing (genotoxic skill) or diagramming

When NOT to Use

• Single-file scripts where call graph adds no value (read the file directly)
• Architecture diagrams not derived from code (use the

  diagramming-code

  skill or draw by hand)
• Mutation testing triage (use the genotoxic skill, which calls trailmark internally)
• Runtime behavior analysis (trailmark is static, not dynamic)

Rationalizations to Reject

preanalysis()

engine.preanalysis()

uncertain

--language

Installation

MANDATORY: If

uv run trailmark

uv pip install trailmark

DO NOT fall back to "manual verification", "manual analysis", or reading source files by hand as a substitute for running trailmark. The tool must be installed and used programmatically. If installation fails, report the error to the user instead of silently switching to manual code reading.

Quick Start

# Python (default)
uv run trailmark analyze --summary {targetDir}

# Other languages
uv run trailmark analyze --language rust {targetDir}
uv run trailmark analyze --language javascript {targetDir}
uv run trailmark analyze --language go --summary {targetDir}

# Complexity hotspots
uv run trailmark analyze --complexity 10 {targetDir}

Programmatic API

from trailmark.query.api import QueryEngine

# Specify language (defaults to "python")
engine = QueryEngine.from_directory("{targetDir}", language="rust")

engine.callers_of("function_name")
engine.callees_of("function_name")
engine.paths_between("entry_func", "db_query")
engine.complexity_hotspots(threshold=10)
engine.attack_surface()
engine.summary()
engine.to_json()

# Run pre-analysis (blast radius, entrypoints, privilege
# boundaries, taint propagation)
result = engine.preanalysis()

# Query subgraphs created by pre-analysis
engine.subgraph_names()
engine.subgraph("tainted")
engine.subgraph("high_blast_radius")
engine.subgraph("privilege_boundary")
engine.subgraph("entrypoint_reachable")

# Add LLM-inferred annotations
from trailmark.models import AnnotationKind

engine.annotate("function_name", AnnotationKind.ASSUMPTION,
                "input is URL-encoded", source="llm")

# Query annotations (including pre-analysis results)
engine.annotations_of("function_name")
engine.annotations_of("function_name",
                       kind=AnnotationKind.BLAST_RADIUS)
engine.annotations_of("function_name",
                       kind=AnnotationKind.TAINT_PROPAGATION)

Pre-Analysis Passes

Always run

engine.preanalysis()

diagramming-code

1. Blast radius estimation — counts downstream and upstream nodes per function, identifies critical high-complexity descendants
2. Entry point enumeration — maps entrypoints by trust level, computes reachable node sets
3. Privilege boundary detection — finds call edges where trust levels change (untrusted -> trusted)
4. Taint propagation — marks all nodes reachable from untrusted entrypoints

Results are stored as annotations and named subgraphs on the graph.

For detailed documentation, see references/preanalysis-passes.md.

Supported Languages

--language

python

.py

javascript

.js

.jsx

typescript

.ts

.tsx

php

.php

ruby

.rb

c

.c

.h

cpp

.cpp

.hpp

.cc

.hh

.cxx

.hxx

c_sharp

.cs

java

.java

go

.go

rust

.rs

solidity

.sol

cairo

.cairo

haskell

.hs

circom

.circom

erlang

.erl

Graph Model

Node kinds:

function

method

class

module

struct

interface

trait

enum

namespace

contract

library

Edge kinds:

calls

inherits

implements

contains

imports

Edge confidence:

certain

self.method()

inferred

uncertain

Per Code Unit

• Parameters with types, return types, exception types
• Cyclomatic complexity and branch metadata
• Docstrings
• Annotations:

  assumption

  ,

  precondition

  ,

  postcondition

  ,

  invariant

  ,

  blast_radius

  ,

  privilege_boundary

  ,

  taint_propagation

Per Edge

• Source/target node IDs, edge kind, confidence level

Project Level

• Dependencies (imported packages)
• Entrypoints with trust levels and asset values
• Named subgraphs (populated by pre-analysis)

Key Concepts

Declared contract vs. effective input domain: Trailmark separates what a function declares it accepts from what can actually reach it via call paths. Mismatches are where vulnerabilities hide:

• Widening: Unconstrained data reaches a function that assumes validation
• Safe by coincidence: No validation, but only safe callers exist today

Edge confidence: Dynamic dispatch produces

uncertain

Subgraphs: Named collections of node IDs produced by pre-analysis. Query with

engine.subgraph("name")

engine.preanalysis()

Query Patterns

See references/query-patterns.md for common security analysis patterns.

See references/preanalysis-passes.md for pre-analysis pass documentation.