
trailmark v0.5.0
स्रोत कोड के ग्राफ डेटाबेस प्रतिनिधित्व का निर्माण और क्वेरी करें
Trailmark
Trailmark स्रोत कोड को फ़ंक्शन, टाइप, कॉल और अन्य संबंधों के ग्राफ़ में पार्स करता है, और फिर आपको इसके बारे में संरचनात्मक प्रश्न पूछने देता है:
- कौन से एंट्रीपॉइंट इस फ़ंक्शन तक पहुँच सकते हैं, और किन कॉल पथों से?
- दो कमिट्स के बीच अटैक सरफ़ेस में क्या बदला?
- कौन से फ़ंक्शन इस Solidity स्टोरेज वेरिएबल को लिखते हैं?
- कॉल रिज़ॉल्यूशन कहाँ रुका, जिससे रीचेबिलिटी परिणाम अपूर्ण हैं?
यह समर्थित भाषाओं को tree-sitter के माध्यम से पार्स करता है, ग्राफ़ को rustworkx में संग्रहीत करता है, और इसे एक कमांड-लाइन टूल और एक Python API के माध्यम से उजागर करता है। Trailmark को सुरक्षा समीक्षा के लिए बनाया गया था: प्रत्येक एज रिकॉर्ड करता है कि वह सीधे सिंटैक्स से आया है या किसी ह्यूरिस्टिक से, और जिन कॉल्स को यह रिज़ॉल्व नहीं कर सका वे ग्राफ़ में बने रहते हैं।
दीर्घकालिक दृष्टि इस ग्राफ़ को म्यूटेशन टेस्टिंग और कवरेज-गाइडेड फ़ज़िंग के साथ जोड़कर उन अंतरालों की पहचान करना है जो मान्यताओं और टेस्ट कवरेज के बीच हैं और जो उपयोगकर्ता इनपुट से पहुँच योग्य हैं।
विशेषताएँ
- कोड ग्राफ़। फ़ंक्शन, मेथड, क्लास, स्ट्रक्ट, ट्रेट, कॉन्ट्रैक्ट और
मॉड्यूल, जो कॉल, इनहेरिटेंस, कंटेनमेंट और टाइप उपयोग द्वारा जुड़े होते हैं।
--language autoकिसी ट्री में समर्थित प्रत्येक भाषा को एक ही ग्राफ़ में मिला देता है। - अटैक सरफ़ेस। फ़्रेमवर्क-जागरूक एंट्रीपॉइंट डिटेक्शन (Flask, FastAPI,
Spring, ASP.NET Core, actix-web, NestJS, Elysia HTTP रजिस्ट्रेशन, Solidity विज़िबिलिटी, और अधिक), प्रत्येक
ट्रस्ट लेवल और एसेट वैल्यू के साथ टैग किया गया।
.trailmark/entrypoints.tomlके साथ डिटेक्शन को ओवरराइड या विस्तारित करें। - एंट्रीपॉइंट साक्ष्य। सोर्स प्रोवेनेंस के साथ कॉलेबल और डिक्लेरेटिव रेफ़रेंस, निष्पादन योग्य फ़ाइल बॉडी, और अनसुलझे उम्मीदवारों का निरीक्षण करें। रेफ़रेंस निष्पादन से अलग रहते हैं। स्पष्ट अपवर्जन के साथ अतिरिक्त सोर्स रूट चुनें।
- रीचेबिलिटी। प्रत्यक्ष कॉलर और कैली, ट्रांज़िटिव स्लाइस, और एंट्रीपॉइंट से किसी लक्ष्य तक सीमित कॉल पाथ।
- स्ट्रक्चरल डिफ़। दो डायरेक्टरी या git ref की तुलना करें और जोड़े या हटाए गए डिक्लेरेशन, सिग्नेचर और टाइप परिवर्तन, कॉल-एज कॉन्फ़िडेंस परिवर्तन, और एंट्रीपॉइंट की रिपोर्ट करें।
- डायग्राम। Mermaid कॉल ग्राफ़, क्लास पदानुक्रम, मॉड्यूल निर्भरताएँ, कंटेनमेंट व्यू, कॉम्प्लेक्सिटी मैप, और एंट्रीपॉइंट-से-लक्ष्य फ़्लो।
- ग्राफ़ पर फ़ाइंडिंग्स। SARIF और weAudit परिणाम आयात करें, अपने स्वयं के एनोटेशन संलग्न करें, और प्रीएनालिसिस पास (ब्लास्ट रेडियस, प्रिविलेज बाउंड्रीज़, कॉर्स टेन्ट) चलाएँ जो अपने परिणाम एनोटेशन और नामित सबग्राफ़ के रूप में संग्रहीत करते हैं।
- दृश्यमान अंतराल। जिन कॉल को सुलझाया नहीं जा सकता, वे गायब होने के बजाय
प्रॉक्सी नोड बन जाते हैं, और
trailmark analyze --resolutionउन्हें गिनता है। - अपवाद साक्ष्य।
exception_events()के साथ सोर्स-स्थित throws, rethrows, handlers और cleanup सिंटैक्स का निरीक्षण करें; अज्ञात थ्रोन ऑपरेंड दृश्यमान रहते हैं। फ़्रंटएंड कवरेज और इस सिंटैक्स साक्ष्य की सीमाओं के लिए ग्राफ़ मॉडल देखें। - वे लिंक जो Trailmark नहीं देख सकता।
.trailmark/links.tomlमें RPC, FFI, और सबप्रोसेस एज घोषित करें, या किसी बाइनरी-विश्लेषण टूल द्वारा उत्पादित कॉल ग्राफ़ आयात करें। - कंपाइल्ड बाइनरी साक्ष्य। लिंक्ड ELF,
Mach-O, और PE इमेज का स्पष्ट रूप से निरीक्षण करें, सोर्स फ़ंक्शन और लाइनों को कंपाइल्ड रेंज से जोड़ें,
बाइनरी कॉल और अनुमानित टेल ट्रांसफ़र पुनःप्राप्त करें, और 15 आर्किटेक्चर/मोड केसों में
सीमित डिसअसेम्बली क्वेरी करें। इसमें स्ट्रिप्ड-कोड मैपिंग, यूनिवर्सल
स्लाइस, सत्यापित लोकल डीबग साथी, फ़ोल्डेड उपनाम, और नामित इम्पोर्ट
एंट्री शामिल हैं। वैकल्पिक
trailmark[binary]एक्स्ट्रा और होस्ट-टूल आवश्यकताओं के लिए बाइनरी साक्ष्य देखें। - Solidity स्टोरेज एक्सेस। फ़ंक्शन और उनके द्वारा स्पर्श किए जाने वाले
कॉन्ट्रैक्ट स्टेट वेरिएबल के बीच
readsऔरwritesएज।
इंस्टॉल
uv tool install trailmark # the CLI
uv add trailmark # the library, in a uv-managed project
Python ≥ 3.12 आवश्यक है। CI, Python 3.12 से 3.15 तक का परीक्षण करता है।
Nix के साथ, nix run github:trailofbits/trailmark CLI को सीधे चलाता है।
यह README और गाइड main ब्रांच को ट्रैक करते हैं।
changelog
सूचीबद्ध करता है कि प्रत्येक प्रकाशित रिलीज़ में क्या शामिल है, और CLI तथा Python API गाइड
उस संस्करण को नोट करते हैं जिसने प्रत्येक नए फ़ीचर को जोड़ा।
अधिकांश grammars पहले उपयोग पर डाउनलोड और कैश किए जाते हैं। Bundled grammars पहले उपयोग पर संकलित किए जाते हैं, जिसके लिए C कंपाइलर आवश्यक है। ऑफ़लाइन मशीनों, TLS-निरीक्षण करने वाले proxies, और checkout से बिल्ड करने के लिए Installation देखें।
Skills integrators: schema, identity, state, और reachability जाँचों के लिए v0.7 compatibility देखें।
त्वरित शुरुआत
# Node and edge counts for a Python project (Python is the default language)
trailmark analyze --summary path/to/project
# The same summary as JSON, including source-file counts per language (v0.7+)
trailmark analyze --summary --json --language auto path/to/project
# Full JSON graph of every supported language in the tree
trailmark analyze --language auto path/to/project > graph.json
# Detected entrypoints with trust level and asset value
trailmark entrypoints --language auto path/to/project
# How the attack surface changed between two git refs
trailmark diff --repo . main HEAD
# Mermaid call graph around one function
trailmark diagram -t path/to/project -T call-graph -f handle_request
# How many call sites could not be resolved, grouped by callee name
trailmark analyze --language rust --resolution path/to/project
डायरेक्टरी विश्लेषण अनुपस्थित रूट्स और शून्य मिलान वाली स्रोत फ़ाइलों को अस्वीकार करता है। सारांश में चयनित भाषाएँ और निरीक्षित फ़ाइल गणनाएँ शामिल हैं; जानबूझकर खाली इनपुट के लिए --allow-empty का उपयोग करें।
ग्राफ़ JSON में निर्यात करने वाला Trailmark संस्करण और एक निर्यात स्कीमा संस्करण (v0.7+) शामिल है; समान Trailmark संस्करण और भाषाओं के साथ बनाए गए स्नैपशॉट की तुलना करें।
Python से वही प्रश्न:
from trailmark.query.api import QueryEngine
engine = QueryEngine.from_directory("path/to/project", language="auto")
engine.attack_surface() # entrypoints and their trust levels
engine.callers_of("verify_signature") # direct callers
engine.ancestors_of("verify_signature") # everything that can reach it
engine.entrypoint_paths_to("verify_signature")
engine.complexity_hotspots(10) # cyclomatic complexity >= 10
नाम बेयर (verify_signature), क्वालिफाइड (Auth.verify), या पूर्ण नोड
ID (auth:Auth.verify) हो सकते हैं। क्वेरी परिणाम सादे dict और list होते हैं जो
सीधे JSON में सीरियलाइज़ होते हैं।
यह कैसे काम करता है
flowchart LR
A["Source files"] --> B["tree-sitter parsers"]
B --> C["CodeGraph"]
C --> D["GraphStore (rustworkx)"]
D --> E["QueryEngine"]
E --> F["CLI / Python API"]
classDef src fill:#007bff26,stroke:#007bff,color:#007bff
classDef parse fill:#28a74526,stroke:#28a745,color:#28a745
classDef data fill:#6f42c126,stroke:#6f42c1,color:#6f42c1
classDef query fill:#ffc10726,stroke:#e6a817,color:#e6a817
class A src
class B parse
class C,D data
class E,F query