references/query-recipes.md
Query Recipes
Use these recipes after building a graph and running engine.preanalysis().
Feature-gate optional Trailmark 0.4 APIs with hasattr().
Build And Preanalyze
from trailmark.query.api import QueryEngine
engine = QueryEngine.from_directory("{targetDir}", language="auto")
engine.preanalysis()
If auto-detection is wrong, rerun with an explicit language or comma-separated language list.
Bind A File/Line Candidate
Prefer Trailmark or audit-augmentation matching helpers when available. If
working from exported JSON, match nodes whose location file equals the
candidate file and whose line span overlaps the candidate line range. Pick the
smallest span as primary.
Reachability
node_id = "{bound_node}"
entry_paths = engine.entrypoint_paths_to(node_id)
Classify paths as:
untrusted_externalsemi_trusted_externaltrusted_internalunknown
If no path exists, distinguish likely dead/internal code from parser, language, proxy, dynamic dispatch, or missing-entrypoint modeling gaps.
Taint And Privilege Boundaries
# Trailmark 0.5 returns node dicts from subgraph(), so compare ids; `set(engine.subgraph(...))`
# raises TypeError (unhashable dict). The helper also accepts plain id lists.
def ids(name):
return {n["id"] if isinstance(n, dict) else n for n in engine.subgraph(name)}
tainted = node_id in ids("tainted")
boundary = node_id in ids("privilege_boundary")
entry_reachable = node_id in ids("entrypoint_reachable")
When connect_subgraphs() exists, use it to find paths from tainted nodes to
privilege-boundary nodes and check whether the candidate sits on or near those
paths.
Blast Radius And Neighborhood
callers = engine.callers_of(node_id)
callees = engine.callees_of(node_id)
high_blast = node_id in ids("high_blast_radius")
downstream = engine.reachable_from(node_id)
Flag downstream sinks involving:
- value transfer
- authorization or role decisions
- persistence or state writes
- parsing or deserialization
- cryptographic keys, sessions, or signatures
- external process, network, or file operations
Evidence Limits
Always record:
- Trailmark version or feature probes
- unsupported languages or parser errors
- unresolved/proxy/dynamic call uncertainty
- unmatched or ambiguous graph binding
- missing entrypoint modeling
- places where manual security judgment is still required