Назад к обновлениям
New releaseJul 24, 2026

trailmark v0.5.0

Создавайте и запрашивайте графовое представление исходного кода.

Поделиться

Trailmark

CI Mutation Testing

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"]

Категории