
trailmark v0.5.0
Создавайте и запрашивайте графовое представление исходного кода.
Trailmark
Trailmark разбирает исходный код в граф функций, типов, вызовов и других связей, а затем позволяет задавать о нём структурные вопросы:
- Какие точки входа могут достичь этой функции и по каким путям вызовов?
- Что изменилось в поверхности атаки между двумя коммитами?
- Какие функции записывают в эту переменную хранилища Solidity?
- Где разрешение вызовов остановилось, из-за чего результаты анализа достижимости неполны?
Он разбирает поддерживаемые языки с помощью tree-sitter, хранит граф в rustworkx и предоставляет его через инструмент командной строки и Python API. Trailmark создан для проверки безопасности: каждое ребро фиксирует, получено ли оно напрямую из синтаксиса или из эвристики, а неразрешённые вызовы остаются в графе.
Долгосрочная цель — объединить этот граф с мутационным тестированием и фаззингом с покрытием, чтобы выявлять пробелы между предположениями и покрытием тестами, достижимые из пользовательского ввода.
Возможности
- Графы кода. Функции, методы, классы, структуры, трейты, контракты и
модули, связанные вызовами, наследованием, вложенностью и использованием типов.
--language autoобъединяет все поддерживаемые языки в дереве в один граф. - Поверхность атаки. Обнаружение точек входа с учётом фреймворков (Flask, FastAPI,
Spring, ASP.NET Core, actix-web, NestJS, HTTP-регистрации Elysia, видимость в Solidity и другое), каждая
помечается уровнем доверия и ценностью актива. Переопределяйте или расширяйте обнаружение с помощью
.trailmark/entrypoints.toml. - Свидетельства точек входа. Изучайте вызываемые и декларативные ссылки, тела исполняемых файлов и неразрешённые кандидаты с указанием источника. Ссылки остаются отдельно от исполнения. Выбирайте дополнительные корневые каталоги исходников с явными исключениями.
- Достижимость. Прямые вызывающие и вызываемые, транзитивные срезы и ограниченные пути вызовов от точек входа к цели.
- Структурные диффы. Сравнивайте два каталога или git-ссылки и получайте отчёт о добавленных или удалённых объявлениях, изменениях сигнатур и типов, изменениях уверенности рёбер вызовов и точках входа.
- Диаграммы. Графы вызовов Mermaid, иерархии классов, зависимости модулей, представления вложенности, карты сложности и потоки от точек входа к целям.
- Находки на графе. Импортируйте результаты SARIF и weAudit, добавляйте собственные аннотации и запускайте проходы предварительного анализа (радиус поражения, границы привилегий, грубый анализ заражения), которые сохраняют результаты в виде аннотаций и именованных подграфов.
- Видимые пробелы. Вызовы, которые не удаётся разрешить, становятся прокси-узлами вместо
того, чтобы исчезнуть, а
trailmark analyze --resolutionподсчитывает их. - Свидетельства исключений. Изучайте привязанные к исходникам throw, rethrow, обработчики и
синтаксис очистки с помощью
exception_events(); неизвестные выбрасываемые операнды остаются видимыми. См. модель графа для информации о покрытии фронтендов и ограничениях этих синтаксических свидетельств. - Связи, невидимые для Trailmark. Объявляйте рёбра RPC, FFI и подпроцессов в
.trailmark/links.tomlили импортируйте граф вызовов, созданный инструментом бинарного анализа. - Свидетельства скомпилированных бинарников. Явно изучайте связанные образы 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.
Список изменений
перечисляет, что включает каждый опубликованный релиз, а руководства по CLI и Python API
отмечают версию, в которой появилась каждая новая функция.
Большинство грамматик скачиваются и кэшируются при первом использовании. Встроенные грамматики компилируются при первом использовании, для чего нужен компилятор C. См. Установка для офлайн-машин, прокси с инспекцией TLS и сборки из рабочей копии.
Интеграторам навыков: см. совместимость с v0.7 для проверок схемы, идентичности, состояния и достижимости.
Быстрый старт
# 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 для намеренно пустого ввода.
Graph 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) или полными идентификаторами узлов (auth:Auth.verify). Результаты запросов представляют собой обычные словари и списки, которые напрямую сериализуются в 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"]