/trailmark

name: trailmark
description: "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."

Trailmark

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

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
• Importing external binary-analysis graphs to connect source and binary views
• Querying transitive slices, entrypoint paths, subgraph edges, or type references
• Producing graph evidence for one suspicious function or candidate finding
• 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

| Rationalization | Why It's Wrong | Required Action | |-----------------|----------------|-----------------| | "I'll just read the source files manually" | Manual reading misses call paths, blast radius, and taint data | Install trailmark and use the API | | "Pre-analysis isn't needed for a quick query" | Blast radius, taint, and privilege data are only available after `preanalysis()` | Always run `engine.preanalysis()` before handing off to other skills | | "The graph is too large, I'll sample" | Sampling misses cross-module attack paths | Build the full graph; use subgraph queries to focus | | "Uncertain edges don't matter" | Dynamic dispatch is where type confusion bugs hide | Account for `uncertain` edges in security claims | | "Single-language analysis is enough" | Polyglot repos have FFI boundaries where bugs cluster | Use the correct `--language` flag per component | | "Complexity hotspots are the only thing worth checking" | Low-complexity functions on tainted paths are high-value targets | Combine complexity with taint and blast radius data | | "The docs mention a version-gated method, so I can call it anywhere" | Many environments still have Trailmark 0.2.x installed | Check the installed version or probe feature availability before using v0.4+/v0.5+ features |

---

Installation

**MANDATORY:** If `trailmark` is not found, install the CLI before doing anything else:

uv tool install trailmark

A tool install provides the CLI only — it does not make `import trailmark` resolvable. Run the Python snippets in this skill with `uv run --with trailmark python -`; that, not installation, is the fix for an import error or ModuleNotFoundError in a snippet.

**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.

Version Gate

Trailmark 0.4.0 expands the graph model and query surface, and 0.5.0 adds a SQL parser, repository-link configuration, and richer entrypoint metadata. Before using a feature listed as **v0.4+** or **v0.5+**, check the installed version:

trailmark --version 2>/dev/null || uv run trailmark --version 2>/dev/null

Compare the reported version numerically (not lexically). `0.4.0` or newer means the full v0.4 surface is available. The version command itself was added in 0.2.2, so a failure means either a pre-0.2.2 install or trailmark missing entirely — distinguish with `trailmark analyze --help`. When working programmatically, probe with `hasattr()` and fall back instead of assuming a v0.4-only method exists:

if hasattr(engine, "subgraph_edges"):
    edges = engine.subgraph_edges("tainted")
else:
    # v0.2 fallback: filter engine.to_json() edges whose endpoints
    # are both in engine.subgraph("tainted")
    edges = []

**v0.2-safe baseline:** CLI `analyze`, `diff`, `entrypoints`, `augment`, and `--language auto`; `QueryEngine.from_directory()`, `callers_of()`, `callees_of()`, `paths_between()`, `ancestors_of()`, `reachable_from()`, `entrypoint_paths_to()`, `complexity_hotspots()`, `attack_surface()`, `summary()`, `to_json()`, `preanalysis()`, `annotate()`, `annotations_of()`, `nodes_with_annotation()`, `clear_annotations()`, `findings()`, `subgraph()`, `subgraph_names()`, `diff_against()`, `augment_sarif()`, and `augment_weaudit()`.

**Added in 0.2.2:** CLI `--version` flag and `version` subcommand.

**Added in 0.3.x:** the `trailmark.parse` module with module-level `detect_languages()` and `supported_languages()`. `detect_languages()` itself is v0.2-safe via `from trailmark.query.api import detect_languages` (kept as a deprecated alias in 0.3+); `supported_languages()` has no 0.2.x equivalent.

**