Agent Reliability Analyzer — выявляйте и устраняйте проблемы надёжности AI-агентов

Agent Reliability Analyzer — это детерминированный сканер с открытым исходным кодом от Trustabl. Он выявляет и устраняет проблемы надёжности в коде AI-агентов до выхода в production. Узнайте, из-за чего ваш AI-агент может дать сбой, и устраните проблему одной командой.

Детерминированный статический анализ кода агентов для девяти SDK и семи языков программирования.

Сканер полностью работает на вашем компьютере: без облачного сканирования, учётной записи, загрузки кода и LLM.

По состоянию на октябрь 2026 года Agent Reliability Analyzer поддерживает надёжность агентов по 340+ правилам, 9 SDK, 7 языкам и 5 областям.

Если Agent Reliability Analyzer помог избежать инцидента в production, поставьте репозиторию ⭐ — так другие команды смогут его найти.

Партнёры Trustabl — устанавливайте инструмент из привычного каталога

Один движок для надёжности агентов — десять способов начать работу.

MCP Registry · mcprush Сканирование из любого клиента с поддержкой MCP	Claude Directory Skills, агент и сканер в Claude	npm · PyPI Инструмент, который вызывает ваш агент на базе AI SDK или Pydantic AI
VS Code Результаты проверки прямо в редакторе во время работы	Cursor Тот же сканер, подключённый как MCP-сервер	CLI Homebrew, Scoop, Docker или бинарный файл
GitHub Actions Проверка сборки по порогу серьёзности проблем	GitLab CI/CD Опубликованный компонент в каталоге	Bitbucket Официальный pipe, не требующий установки

Все эти варианты запускают один и тот же детерминированный сканер локально, на вашем компьютере.

Список поддерживаемых SDK для агентов см. в разделе [интеграции экосистемы](docs/integrations.md).

Trustabl сканирует репозиторий агента и выявляет проблемы, которые приводят к сбоям в production:

неясные описания инструментов, из-за которых модель не понимает, когда их использовать, отсутствие повторных попыток

и обработки тайм-аутов, нетипизированные параметры, отсутствие защитных ограничений, а также разрешения на вызов инструментов,

которые выходят за рамки заявленных задач агента. Затем сканер вносит исправления непосредственно в исходный код.

Все остальные сканеры агентов выдают отчёт. Trustabl предлагает готовый патч.

Надёжность закладывают до развёртывания, а не оценивают после него.

Сканирование полностью выполняется на вашем компьютере. Без облачного сканера, учётной записи,

загрузки кода и LLM — только детерминированный статический анализ.

docker run --rm -v "$PWD:/repo" ghcr.io/trustabl/trustabl:latest scan /repo   # try it, nothing installed

brew install trustabl/tap/trustabl                                            # macOS / Linux
scoop bucket add trustabl https://github.com/trustabl/scoop-bucket             # Windows
scoop install trustabl

trustabl scan .                                                               # find issues (fully local)
trustabl scan . --format json > scan.json
trustabl enrich --input scan.json --repo . --diff --apply                     # preview, then fix

9 SDK · 7 языков · вывод для человека, в JSON или SARIF 2.1.0 ·

коды завершения для CI · также работает как локальный MCP-сервер stdio (trustabl mcp).

Наиболее полное покрытие предусмотрено для Claude Agent SDK, OpenAI Agents SDK, Google ADK

и MCP-серверов. Сканер также поддерживает LangChain / LangGraph, CrewAI, AutoGen / AG2,

Pydantic AI и Vercel AI SDK. Полная матрица приведена в COVERAGE.md.

Для сканирования не нужны ключи и подключение к сети. Для применения исправлений используйте собственный ключ Anthropic,

OpenAI или Google.

Как выглядит сканирование надёжности агента

Пример реального результата сканирования репозитория с клиентом на Claude Agent SDK,

MCP-сервером, субагентом и двумя skills:

$ trustabl scan .

Scan summary
  Languages:          typescript, javascript
  SDKs:               claude_agent_sdk
  Tool definitions:   2    (custom tools with function bodies)
  Agent tool grants:  14   (tool names the agent may call)
  MCP servers:        1    (createSdkMcpServer)
  Subagents:          1    (inbox-searcher)
  Skills:             2    (action-creator, listener-creator)
  Findings:           14
  Overall score:      66%

Surface readiness
  skill:action-creator          45%  (5 findings)
  skill:listener-creator        54%  (4 findings)
  agent:AIClient.queryStream    64%  (2 findings)
  subagent:inbox-searcher       79%  (1 finding)
  tool:search_inbox             98%  (1 finding)
  tool:read_emails             100%  (0 findings)

Findings
  inbox-searcher
    [CSDK-201]  HIGH  Subagent is granted Bash  (agent/.claude/agents/inbox-searcher.md:1-5)
        A subagent with shell access can run arbitrary commands if it is
        compromised or misdirected.
        fix: Remove `Bash` from the subagent's `tools:` list unless shell access
        is essential. Prefer specific tools (Read, Grep, Glob) for read-only roles.

Обратите внимание на три особенности:

Отдельная оценка для каждой области. Общий показатель репозитория скрывает детали;

значение 45% для skill:action-creator сразу показывает, с чего начать проверку.

Для каждой проблемы предложено исправление, а не просто указано на недостаток. Команда

trustabl enrich --apply внесёт исправления в исходный код.

Код завершения служит порогом для CI. 0, если проблем средней серьёзности и выше нет,

1, если такие проблемы обнаружены. Благодаря этому pipeline может остановить выпуск ненадёжного агента.

AI-агенты успешно проходят демонстрацию, но дают сбой в production

Большинство проблем надёжности агентов несложные. Снова и снова встречается один и тот же набор недочётов:

У агента есть доступ к shell-инструментам, но нет ограничений на входные данные
Инструмент отправляет HTTP-запрос без тайм-аута и блокирует весь запуск
Параметры инструментов не типизированы, поэтому модель может угадать неверное значение
Наблюдаемость не настроена, поэтому невозможно изучить логи первых трёх проблем
Описание инструмента настолько расплывчато, что модель вызывает не тот инструмент: в 56% описаний инструментов MCP

неясно указано их назначение, а в 97,1% обнаружен как минимум один недостаток описания (Hasan et al., MCP Tool Descriptions Are Smelly!,

arXiv 2602.14878 — исследованы 856 инструментов на 103

серверах)

Субагенту выдано разрешение на Bash, хотя в описании указана только возможность чтения
Skill автоматически одобряет неограниченный доступ к shell
Нет обработки повторных попыток, поэтому задача завершается сбоем после временной ошибки 500
В цикле агента не ограничено число итераций, и он расходует токены, пока его не остановят
Управляемый пользователем URL передаётся в fetch — агент может стать источником SSRF

Каждую из этих проблем можно обнаружить в исходном коде ещё до запуска агента. Trustabl выявляет их за секунды, без подключения к сети и LLM, и предлагает исправления.

В остальных разделах документа объясняется, что именно анализирует Trustabl и как работает сканирование, а также описаны сборка и запуск. Полное описание реализации см. в ARCHITECTURE.md; краткая матрица поддержки SDK приведена в COVERAGE.md.

Что анализируется — надёжность агентов в пяти областях

Agent Reliability Analyzer не рассматривает репозиторий как единый недифференцированный массив данных. Каждое правило надёжности агентов относится ровно к одной из пяти областей, и каждая область получает входные данные своего типа:

tool — срабатывает один раз для каждого определения инструмента. На вход получает ToolDef — функцию @function_tool / @tool / @claude_tool, вызов фабрики Claude TS tool(name, description, schema, handler), обёртку ADK FunctionTool(fn), регистрацию MCP @server.tool или функцию, непосредственно вызывающую shell, — а также файл, в котором этот инструмент разобран. Позволяет обнаружить отсутствие docstring, HTTP-вызов без тайм-аута, нетипизированные параметры или путь, передаваемый в open() без нормализации. Размещённые инструменты, такие как WebSearchTool(), относятся к данным связей на уровне агента: они представлены как HostedToolDef, а не ToolDef.
agent — срабатывает один раз для каждого объявления агента. На вход получает AgentDef: вызов Python Agent(...) / SandboxAgent(...) / AgentDefinition(...), типизированную константу Claude TS AgentDefinition, встроенный субагент Claude TS в options.agents или основной агент потока Claude TS query(...) (QueryMainAgent). При этом фиксируются все аргументы конструктора и разрешаются связи с инструментами, передачами управления и защитными механизмами. Позволяет обнаружить агента с shell-инструментами, но без input_guardrails, сочетание tool_use_behavior="stop_on_first_tool" с инструментами, обращающимися к файловой системе, а также основного агента потока с неограниченным allowedTools.
subagent — срабатывает один раз для каждого объявления субагента Claude Code в Markdown. Поиск работает в гибридном режиме: используются как стандартные файлы .claude/agents/*.md на любой глубине вложенности (подходит для монорепозиториев), так и резервный поиск по структуре frontmatter во всех Markdown-файлах. Последний запускается при наличии name и tools/model и находит субагентов в репозиториях с плоской структурой, например в categories/*.md, plugins//agents/*.md и других похожих каталогах. На вход получает SubagentDef, извлечённый из frontmatter: name, description, tools[] (без изменений) и ToolGrants[] (разобранная грамматика разрешений), disallowedTools, model, permissionMode (включая bypassPermissions), mcpServers, skills, isolation, hasHooks. Позволяет обнаружить субагента, которому предоставлен встроенный инструмент Bash, несмотря на описание с указанием только чтения (CSDK-110). Сам факт наличия субагента добавляет claude_agent_sdk в SDKsDetected, поэтому загружается набор правил Claude и CSDK-110 срабатывает даже в репозитории, состоящем только из Markdown-файлов с описаниями субагентов.
skill — срабатывает один раз для каждого навыка Claude Code (SKILL.md) на любой глубине вложенности. На вход получает SkillDef, извлечённый из frontmatter: name, description, allowed-tools → ToolGrants[], disable-model-invocation, а также факты из тела файла: команды выполнения динамического контекста, внешние URL, маркеры prompt injection и перечень вложенных файлов. Позволяет обнаружить навык, который автоматически одобряет неограниченный Bash (CSKILL-001), выполняет команду динамического контекста, обращающуюся к сети или читающую секреты до того, как модель получит их (CSKILL-003), либо доступен для вызова моделью и при этом предоставляет инструменты с побочными эффектами (CSKILL-050). Навыки описываются в Markdown, поэтому в правилах для них нет language:; набор правил claude_skill загружается при наличии любого SKILL.md.
repo — срабатывает один раз за сканирование, проверяя весь инвентарь. Позволяет обнаружить общие для проекта проблемы, например наличие OpenAI Agents SDK без настроенного пользовательского обработчика трассировки.

Единица анализа — агент, а не репозиторий

В репозитории может быть объявлено ноль, один или несколько агентов, использующих один или несколько SDK. Два агента в одном репозитории могут иметь совершенно разный уровень защищённости: у одного могут быть настроены входные и выходные защитные механизмы, а у другого — нет.

Поэтому результаты на уровне агента относятся к конкретному агенту и месту вызова его конструктора. Если свести их к единой оценке репозитория, эта связь будет утрачена, а сама оценка окажется некорректной. При поиске компонентов строится небольшой граф репозитория: инструменты, агенты, субагенты и связи между ними. Он позволяет правилам для агентов и субагентов запрашивать нужные данные.

Каждое правило относится к одному SDK и одному языку

Правило для Claude SDK и правило для OpenAI Agents SDK, обнаруживающие одну и ту же концептуальную проблему — например, отсутствие тайм-аута, — считаются отдельными правилами. У них свои объяснения и рекомендации по исправлению; перенос результатов между SDK не выполняется.

Если в репозитории одновременно объявлены агенты на разных SDK, каждый агент проверяется только по правилам SDK, на котором он создан. То же относится к языкам: правило с language: python не сработает для агента на TypeScript.

Как выполняется анализ — конвейер сканирования

Agent Reliability Analyzer (CLI trustabl) сканирует репозиторий за четыре шага. Каждый шаг передаёт типизированные выходные данные следующему; между запусками общее состояние не сохраняется. Инвентарь, сформированный на ранних шагах, позволяет выбирать набор правил на основе данных, а не статической конфигурации.

В бинарный файл не встроено ни одного правила. Перед запуском конвейера Trustabl получает правила обнаружения из отдельного git-репозитория agent-reliability-rules: загружает последнюю версию, сохраняет локальную копию и при отсутствии сети использует кэш. Благодаря этому правила можно обновлять независимо от выпусков бинарного файла: добавлять и менять их можно без пересборки сканера. Идентификатор полученного коммита с правилами записывается в результат и включается в ScanID, поэтому в отчёте точно указано, какие именно правила использовались.

Если загрузить правила не удалось и кэш отсутствует, сканирование завершается с кодом 2 и рекомендацией выполнить trustabl rules pull. Trustabl никогда не запускается без правил.

flowchart LR
    target[("Agent repo<br/>(local path or GitHub URL)")]
    recon["Recon<br/>files · SDK deps"]
    inv["Inventory<br/>Python + TS AST:<br/>tools · agents ·<br/>subagents · MCP servers"]
    pol["Policy selection<br/>load rules per<br/>detected SDK ·<br/>META findings"]
    ana["Analysis<br/>tool · agent · subagent ·<br/>repo detectors"]
    score["Scoring<br/>per-surface score ·<br/>overall readiness"]
    out[("ScanResult<br/>findings · scores<br/>(human / JSON / SARIF)")]

    target --> recon --> inv --> pol --> ana --> score --> out

Разведка — быстро просматривает репозиторий и определяет, «что в нём есть», не разбирая исходный код: присутствующие языки (по расширениям файлов), зависимости SDK, объявленные в манифестах (pyproject.toml / requirements.txt / Pipfile / poetry.lock / package.json), для поиска которых используются claude-agent-sdk / @anthropic-ai/claude-agent-sdk / openai-agents / @openai/agents / google-adk / @google/adk, перечень файлов и обнаруженные компоненты агентов: конфигурации MCP, скрипты хуков, файлы с инструкциями CLAUDE.md и AGENTS.md, субагенты .claude/agents/*.md на любой глубине вложенности, навыки SKILL.md, slash-команды в .claude/commands/*.md и /commands/*.md, манифесты .claude-plugin/{plugin,marketplace}.json, политики песочницы и рабочие процессы GitHub Actions .github/workflows/*.yml в корне репозитория. На этом шаге tree-sitter не используется: сначала определяется, стоит ли вообще запускать ресурсоёмкий разбор AST.
Инвентаризация — для каждого языка, выявленного на этапе разведки, выполняется разбор AST и формируется типизированный инвентарь: ToolDef с конфигурацией и фактами из тела кода, AgentDef со всеми сохранёнными аргументами, SubagentDef / SkillDef / SlashCommandDef / PluginManifest, разобранные из Markdown и frontmatter JSON, MCPServerDef, защитные механизмы, сессии и разрешённые связи между агентами и используемыми ими инструментами и защитными механизмами. Детекторы обращаются к полям этих структур и не разбирают исходный код повторно.
Выбор правил — загружаются только наборы правил для SDK, фактически обнаруженных в коде. Если SDK найден в коде, но для него нет опубликованного набора правил, появляется информационное замечание META-001 («Trustabl пока не проверяет этот SDK»). Молчание в отношении неизвестного SDK — не корректный результат. Если зависимость объявлена, но нигде не используется в коде, выводится другое информационное замечание, указывающее на это расхождение.
Анализ — выбранные детекторы, учитывающие область проверки, запускаются для инвентаря. Результаты содержат сведения об области, в которой сработало правило, и относятся к правильному месту: файлу и строке инструмента, месту вызова конструктора агента, Markdown-файлу субагента или манифесту.

Такое разделение даёт три предусмотренных проектом преимущества:

Производительность. Если в репозитории нет Python, разбор Python AST пропускается. Если в нём есть только код Claude TS, пропускаются и разбор Python AST, и загрузка правил OpenAI.
Достоверное представление охвата. Информационное замечание «SDK не проверяется» заметнее, чем отчёт об отсутствии проблем для SDK, который Trustabl не знает. Результат META-004 дополнительно различает ситуации «SDK проверен, проблем нет» и «проверить не удалось — при поиске не найдено данных, охватываемых правилами».
Детерминированность — обязательное условие. Одинаковые входные данные дают одинаковый ScanID, а отчёт остаётся неизменным побайтно между запусками. Результаты сортируются по (RuleID, FilePath, Line), а срезы инвентаря упорядочиваются детерминированно.

Это позволяет потребителям в CI сравнивать результаты сканирования без случайных различий.

Полную схему с типизированными входными данными для каждого шага см. в ARCHITECTURE.md, раздел 2.

Что уже реализовано

Поиск инструментов и агентов в AST реализован для следующих языков и SDK:

Python — Claude Agent SDK (декораторы), OpenAI Agents SDK, Google ADK, LangChain / LangGraph, CrewAI, AutoGen / AG2 и Pydantic AI.

Поиск извлекает определения инструментов, конструкторы агентов, встроенные инструменты, серверы MCP, защитные механизмы и сессии. Общий конструктор Agent(...), используемый в OpenAI / ADK / CrewAI / Pydantic AI, привязан к импорту конкретного SDK, поэтому классы не сопоставляются с чужими SDK. Общий декоратор @tool связывается с нужным SDK по импорту.

TypeScript — Claude Agent SDK (фабрика tool(), основной поток query() с QueryMainAgent, подагенты, объявленные внутри query(), типизированные AgentDefinition, createSdkMcpServer и четыре конфигурационных литерала options.mcpServers); OpenAI Agents SDK (фабрика tool({...}), new Agent({...}) и Agent.create({...}), 9 фабрик встроенных инструментов, классы серверов MCP для 3 транспортов и обёртка MCPServers, 4 фабрики защитных механизмов defineX, а также классы сессий MemorySession / OpenAIConversationsSession / OpenAIResponsesCompactionSession — поиск выполняется только при наличии импортов из @openai/agents, @openai/agents-core или @openai/agents-openai); Google ADK (конструктор new FunctionTool({...}), 5 конструкторов агентов — new LlmAgent({...}) / SequentialAgent / ParallelAgent / LoopAgent / RoutedAgent, 13 классов встроенных инструментов и связи subAgents — поиск выполняется только при наличии импортов из @google/adk); LangChain / LangGraph (фабрика tool(fn, {...}), DynamicStructuredTool / DynamicTool и createReactAgent / createAgent / new AgentExecutor — поиск выполняется только в экосистеме @langchain/* / langchain / langgraph); Vercel AI SDK (фабрики с одним объектом tool({...}) / dynamicTool({...}), агенты на основе вызовов generateText / streamText / generateObject / streamObject и классы ToolLoopAgent / Experimental_Agent; поле tools обходится как объект/запись, также обнаруживаются встроенные инструменты .tools.*() — поиск выполняется только при наличии импорта ai).

Поддерживаются файлы .ts / .tsx / .mts / .cts, а также JavaScript-файлы .js / .jsx / .mjs / .cjs с грамматиками tree-sitter-typescript и tree-sitter-tsx (для JavaScript используется грамматика tsx — надмножество JavaScript; анализ выполняют те же наборы правил language: typescript).

Для TypeScript поставляются наборы правил Claude Agent SDK (правила для инструментов CSDK-010/011/012/013/014/016; правила для агентов CSDK-120/130/131), OpenAI Agents SDK (правила для инструментов OAI-016/017/019/022/024; правила для агентов OAI-105/116), Google ADK (правила для инструментов ADK-013/015/016; правило для агентов ADK-109), MCP (правила для инструментов MCP-011/012/013/014), LangChain (правила для инструментов LC-010/011/012/013/014; правило для агентов LC-111) и Vercel AI SDK (правила для инструментов и агентов VAI-001..008; правило для репозитория VAI-012). Репозитории на TS с любым из этих SDK больше не получают общего результата META-004; полная таблица приведена в COVERAGE.md.

JavaScript (.js / .jsx / .mjs / .cjs) разбирается как AST в рамках общей процедуры обработки семейства TypeScript: инструменты и агенты обнаруживаются, получают метку javascript и проверяются наборами правил language: typescript (распознаются привязки как через ES import, так и через CommonJS require()).

Для MCP-инструментов в Go реализован поиск на основе tree-sitter-go: поддерживаются mark3labs/mcp-go и официальный modelcontextprotocol/go-sdk. Проверка выполняется правилами language: go из набора MCP. Для C# реализован поиск на основе tree-sitter-c-sharp: обнаруживаются методы официального SDK ModelContextProtocol с атрибутом [McpServerTool], проверка выполняется правилами language: csharp. Для PHP реализован поиск на основе tree-sitter-php: обнаруживаются методы с атрибутом #[McpTool] из официального mcp/sdk и community php-mcp/server, проверка выполняется правилами language: php. Для Rust реализован поиск на основе tree-sitter-rust: обнаруживаются методы официального crate rmcp с атрибутом #[tool]; описания извлекаются из аргумента description = "..." или комментария документации ///, проверка выполняется правилами language: rust. Другие SDK для Go, .NET, PHP и Rust Recon распознаёт как файлы, но пока не разбирает на уровне AST.

Поле language: в схеме правил определяет, какие наборы правил применяются к конкретному языку.

Границы возможностей

Обогащение с помощью LLM выполняется отдельно после сканирования (trustabl enrich). При обнаружении проблем на основе правил (trustabl scan) сетевые запросы не выполняются — само сканирование не использует LLM. Команда trustabl enrich читает результаты сканирования и обращается к настроенному провайдеру LLM (Anthropic, OpenAI или Google Gemini), используя BYOK (ключ сохраняется командой trustabl llm key set в ~/.config/trustabl/keys.json с правами доступа 0600). Для каждого запроса задан тайм-аут. Файл переписывается с помощью --apply, только если его текущее содержимое по-прежнему совпадает с тем, которое проверяла модель; перед изменением создаётся резервная копия .trustabl.bak. Устаревшие результаты сканирования пропускаются и никогда не применяются к изменившемуся файлу. При включённом --langsmith (требуется LANGSMITH_API_KEY) результаты для инструментов дополнительно сопоставляются с данными трассировки во время выполнения, выбранными из проекта LangSmith: долей ошибок, задержкой и недавними сообщениями об ошибках для каждого отмеченного инструмента. Эти сведения передаются в результатах как trace_evidence и направляются в LLM вместе со статическим фрагментом кода. Если для инструмента нет истории трассировок, для соответствующего результата используется только статическое обогащение.
Оценки уверенности основаны на эвристиках, а не на оценке LLM; они пока не откалиброваны по размеченному корпусу реальных агентов. Рассматривайте результаты как повод для дополнительной проверки.
Основной интерфейс — CLI. Веб-приложения, API-сервера или размещённого сервиса нет: передавайте результаты в формате --format json или --format sarif в собственные средства автоматизации. Для GitHub Actions действие trustabl/trustabl-action запускает сканирование и загружает SARIF на вкладку Security. В других CI команда с параметрами --format sarif --output формирует отчёт SARIF 2.1.0, который можно передать в github/codeql-action/upload-sarif или любой другой шаг с поддержкой SARIF.
Trustabl использует модель open core. Всё, что описано здесь, распространяется по лицензии Apache-2.0 и полностью покрывает свою задачу: для сканирования не нужен ни ключ, ни сетевое подключение, а для автоматического исправления используется ваш собственный ключ LLM. Генерация политик, сопоставление с требованиями соответствия и подписанные снимки управления входят в Trustabl Console — отдельный коммерческий продукт. Полное описание различий приведено в docs/open-source-vs-console.md.

Результаты работы

Команда trustabl scan обнаруживает проблемы и формирует отчёт: она не записывает и не изменяет файлы в сканируемом репозитории. Исправления применяются только по вашему запросу с помощью trustabl enrich --apply. Каждый запуск формирует ScanResult, содержащий:

Результаты проверок — по одному на каждое срабатывание правила. Для каждого указываются severity, confidence, explanation, suggested_fix и место срабатывания (файл/строка инструмента, место вызова агента, файл подагента или манифест). Для результата в файле, расположенном по тестовому пути, указывается "origin": "test"; по умолчанию он не учитывается при подсчёте оценок и формировании кода завершения. См. раздел «Результаты для тестовых путей» ниже.
Оценки готовности для каждой поверхности (по одной для каждого обнаруженного инструмента, агента, подагента или репозитория в целом) и общая оценка — среднее, учитывающее широту охвата и взвешенное по степени проблемности. Слабые поверхности сильнее снижают оценку, но одна проблемная поверхность не обнуляет её. Эта оценка помогает определить приоритет проверки, а не служит порогом для CI.
Список обнаруженных сущностей — инструменты, агенты, встроенные инструменты, серверы MCP, подагенты, навыки, slash-команды, манифесты плагинов и настройки Claude. Они доступны на верхнем уровне результата для систем CI.
Сигналы наблюдаемости (observability) — обнаруженные в коде инструменты инструментирования, по одной записи на каждый факт: поставщик (OpenTelemetry, Langfuse, Logfire, Phoenix/OpenInference, OpenLLMetry, Braintrust, Weave, AgentOps, MLflow, Datadog LLM Observability, LangSmith) и статус — только импортирован или действительно инициализирован; также указываются файл и строка. Это различие важно: если репозиторий импортирует SDK трассировки, но не запускает его, манифест может указывать на наличие инструментирования, хотя трассировки фактически не создаются. Статическое обнаружение поддерживается только для Python и TypeScript/JavaScript; Trustabl не собирает трассировки во время выполнения.
Метки процесса (otel_labels) — найденные в коде вызовы agent-reliability-otel-labels (импорт, создание Run, запуск выполнения, метка диапазона инструмента, завершение выполнения) и заданные вручную ключи меток trustabl.*. Для каждой записи указываются файл, строка и факты, используемые правилами OBS-006..012: является ли объект Run общим, выполняется ли установка метки при ошибке инструмента, задано ли для attempt фиксированное число, а также буквальные значения side_effect / exit_reason. Поддерживаются только Python и TypeScript/JavaScript. Не учитывается при формировании ID сканирования.
Точки входа сервера (entrypoints, поле опускается, если таких точек нет) — функции Python, которые серверный фреймворк вызывает в ответ на внешний запрос или задачу: обработчики маршрутов FastAPI и Flask (kind: http, с буквальным значением route, если оно указано), а также задачи Celery / акторы Dramatiq (kind: worker). Это только сведения о найденных точках входа: правила пока их не используют. Точки входа в каталогах examples/, demo/, docs/ и подобных не записываются.

Состав доступных инструментов в сводке по категориям

Человеко-читаемый формат разделяет три категории, которые часто

путают между собой:

Tool definitions:   2  (custom tools with function bodies — scored below)
Agent tool grants: 14  (tool names the agent may call — audited by agent-scope rules)
Hosted tools:       1  (...)

Только категория «Tool definitions» проходит через правила для области

действия инструментов: в ней есть тела функций, которые правила могут

анализировать. Предоставленные агенту разрешения и размещённые инструменты

обрабатываются правилами для области действия агента, а не остаются без

анализа — просто они не отображаются в таблице готовности по отдельным

категориям.

Режимы вывода

--format human (по умолчанию) выводит человеко-читаемую сводку в stdout,

а текущий ход выполнения — в stderr: на интерактивном терминале отображаются

анимированный индикатор выполнения и шкала прогресса, а при перенаправлении

вывода — обычные строки формата [phase] summary, удобные для CI.

--format json сериализует полный объект ScanResult, чтобы передать его

в собственную систему автоматизации.

--format sarif формирует документ SARIF 2.1.0, подходящий для

github/codeql-action/upload-sarif и других инструментов, поддерживающих

SARIF. Предлагаемое исправление указывается на уровне правила в help.text;

Trustabl не формирует fixes[] для отдельных результатов. Благодаря этому

документ проходит проверку схемы GitHub Code Scanning, которая отклоняет

fix без artifactChanges.

--json-out и --sarif-out записывают документ JSON / SARIF в файл

независимо от значения --format: один запуск сканирования может вывести

человеко-читаемую сводку в stdout и одновременно сохранить оба машинных

артефакта. Содержимое файлов побайтно совпадает с соответствующим выводом

--format в stdout.

--bom-out дополнительно формирует побайтно стабильный BOM CycloneDX 1.5

с зависимостями, объявленными в репозитории для всех поддерживаемых языков:

requirements.txt / pyproject.toml / Pipfile (pip), package.json (npm),

go.mod (Go), composer.json (Composer), *.csproj (NuGet), Cargo.toml

(Cargo). Это только перечень объявленных прямых зависимостей; сетевые запросы

не выполняются. Если в манифесте есть поле license (package.json,

Cargo.toml, composer.json, pyproject.toml), идентификатор SPDX включается

в массив licenses[] соответствующего компонента в BOM.

Флаг --vuln-scan превращает этот BOM в оценку уязвимостей: закреплённые

версии зависимостей репозитория сопоставляются с зафиксированным снимком

OSV. Для каждого затронутого пакета формируется результат

с идентификатором рекомендации (CVE / GHSA / PYSEC / …), уровнем серьёзности,

определённым на основе CVSS, и первой исправленной версией. Поэтому уязвимая

зависимость приводит к сбою сканирования через обычный порог серьёзности

и коды завершения, а сведения о ней добавляются в JSON / SARIF наряду

с результатами проверки правил — в ScanResult.vulnerabilities. В отличие

от остальных этапов сканирования, эта проверка **не включена по умолчанию

и требует подключения к сети**: при первом запуске снимок OSV загружается

с osv.dev и сохраняется в каталоге пользовательского кэша. При последующих

запусках --vuln-scan сначала использует кэш и не загружает данные повторно,

пока кэшу не исполнится 24 часа. Это ускоряет повторные проверки и позволяет

выполнять их без подключения к сети. Команда trustabl vulndb pull обновляет

кэш по запросу; флаг --no-rules-update использует кэш независимо от его

возраста, обеспечивая полностью автономную работу.

Сопоставляются только версии, закреплённые конкретным номером: диапазон

вроде ^1.0 или >=2 нельзя свести к одной версии без lockfile, поэтому

он остаётся без сопоставления, а не получает предположительную версию.

Версия снимка включается в ScanID только при использовании --vuln-scan.

Так результат указывает, на основе каких данных об уязвимостях он получен,

а результат обычного сканирования остаётся побайтно неизменным.

При совместном использовании --vuln-scan и --bom-out документ CycloneDX

расширяется: вместо простого перечня зависимостей он становится BOM и VEX.

Сопоставленные рекомендации добавляются в массив vulnerabilities[] формата

CycloneDX 1.5. Для каждой указываются идентификатор рекомендации, источник OSV

в поле source, уровень серьёзности в rating, рекомендация по обновлению

в recommendation и ссылка affects[] на bom-ref затронутого компонента.

Таким образом, одна команда trustabl scan ./repo --vuln-scan --bom-out bom.json

создаёт артефакт, соответствующий стандарту и доступный для обработки любым

инструментом с поддержкой CycloneDX. Без --vuln-scan массив

vulnerabilities[] не добавляется, и BOM содержит только перечень

зависимостей.

--format json и --format sarif не выводят сведения о ходе выполнения

и побайтно стабильны при повторных запусках с одинаковыми входными данными:

результат полностью определяется объектом ScanResult. Человеко-читаемый

формат намеренно не является побайтно стабильным: наличие цвета ANSI

определяется автоматически с учётом типа вывода (TTY или перенаправление)

и переменной NO_COLOR, поэтому один и тот же результат может отображаться

как с цветом, так и без него. Если важна побайтная стабильность, используйте

--no-color или сравнивайте вывод JSON / SARIF.

Результаты для тестовых путей

Результат, файл которого расположен в тестовом пути (tests/, __tests__/,

testdata/, test_*.py, *_test.go, *.spec.ts и т. д.), отображается

во всех форматах — ничего не скрывается. Однако по умолчанию такой результат

не учитывается при расчёте готовности и не приводит к сбою сборки:

WebSearchTool, объявленный в tests/test_adapter.py, — это не то же самое,

что инструмент, включённый в рабочий агент. Одинаковая оценка таких случаев

делала отчёт непригодным для практического применения. Для каждого подобного

результата в JSON указывается "origin": "test", а в SARIF добавляются

свойство origin и запись result.suppressions. Такие результаты исключены

из стандартного представления оповещений GitHub code scanning, но остаются

в исходном журнале. В человеко-читаемом выводе они помещаются в отдельный

раздел «Результаты для тестовых путей (не учитываются при оценке)» в конце,

а не смешиваются с группами выше, которые участвуют в оценке.

Передайте флаг --include-test-paths, чтобы учитывать такие результаты

при оценке и завершать проверку с ошибкой на тех же условиях, что и для

любых других результатов. Это полезно, если проект действительно включает

код, расположенный в путях с названием tests/.

Диагностика (`--verbose` / `--debug`)

Флаг --verbose (-v) выводит сведения о ходе сканирования в stderr:

источник правил (репозиторий, ref, разрешённый SHA и сведения об использовании

резервной копии кэша, если она применялась), количество обнаруженных объектов

на каждом этапе (языки, инструменты, агенты, обнаруженные SDK, загруженные

детекторы, SDK без аудита), пути вывода и итоговую сводку (идентификатор

сканирования, оценка, результаты по уровням серьёзности и код завершения).

Флаг --debug включает всё содержимое --verbose, а также время выполнения

каждого этапа и ограниченный объём подробностей об отдельных сущностях

и результатах: для каждого обнаруженного инструмента и агента, а также для

каждого результата указывается file:line.

Это глобальные флаги: они работают с командами scan, mcp и rules pull

и могут указываться до или после подкоманды (trustabl -v scan … или

trustabl scan -v …). Флаг --debug подразумевает --verbose. Оба флага

выводят данные только в stderr, поэтому не влияют на отчёт в stdout

и побайтную стабильность JSON / SARIF. Например, команда

--format json --debug по-прежнему выводит в stdout чистый документ,

а диагностические сведения отправляет в stderr. Цвет диагностики подчиняется

тем же правилам, что и цвет отчёта: он отключается при --no-color,

переменной NO_COLOR или если stderr не связан с терминалом.

Анимированная панель прогресса и строки журнала, выводимые вперемешку,

мешали бы друг другу в stderr. Поэтому при использовании --verbose /

--debug вместо анимированного индикатора автоматически выводятся обычные

строки [phase].

Сохранение диагностики в файл. Специального флага --log-file нет:

диагностические сведения выводятся в отдельный поток stderr, поэтому для их

сохранения используется перенаправление stderr:

report.json 2>diagnostics.log

Human report on screen, diagnostics to a file

trustabl scan ./repo --debug 2>diagnostics.log

Отчёт и диагностика в одном файле

trustabl scan ./repo --debug &>everything.log">

# Report and diagnostics to separate files (stdout vs stderr)
trustabl scan ./repo --debug --format json >report.json 2>diagnostics.log

# Human report on screen, diagnostics to a file
trustabl scan ./repo --debug 2>diagnostics.log

# Everything (report + diagnostics) in one file
trustabl scan ./repo --debug &>everything.log

При использовании --format json или sarif индикатор выполнения отключён, поэтому в файле stderr содержится

только диагностика. При --format human в нём также выводятся строки с этапами выполнения в формате [phase].

Коды завершения (результат проверки пути теста не учитывается, если не задан параметр

--include-test-paths — см. раздел «Результаты проверки путей тестов» выше):

0 — нет результатов с уровнем серьёзности не ниже среднего (либо результатов нет вообще).
1 — есть хотя бы один результат с уровнем серьёзности не ниже среднего ИЛИ при заданном параметре --strict обнаружен любой результат.
2 — ошибка сканера или ввода-вывода, либо не найдены доступные правила и не удалось загрузить новые

(выполните trustabl rules pull), либо не прошла проверка подлинности подписанного канала (--rules-source): неверная подпись, недоверенный или просроченный ключ, несоответствие канала, просроченное или откаченное заявление либо несовпадение дайджеста. Trustabl отказывается работать с непроверенными правилами.

Поверхности риска OpenShell по-прежнему обнаруживаются (функции, запускающие оболочку,

политики openshell/*.yaml) и отображаются в формате для человека в блоке Risk surfaces: openshell. В блоке указывается количество функций, запускающих оболочку, первые три местоположения в формате «файл:строка» (в детерминированном порядке), строка why: с описанием модели угроз (агент, на запрос которого повлияла внедрённая подсказка и которому доступен один из таких инструментов, может выполнять произвольные команды) и строка fix: с конкретными мерами исправления (использовать песочницу и список разрешений, убрать shell=True, не размещать логику работы с оболочкой в коде, доступном агенту). Правила обнаружения OSH-*, проверявшие эти поверхности риска, перенесены в закрытый проект-компаньон. Поскольку правила OSH не поставляются, в таких репозиториях не срабатывают ни правила, ни проверка META. Этот блок делает видимым непроверенный риск, не утверждая, что аудит проводился. OpenShell — это поверхность риска, а не SDK, поэтому он не помечается как «не прошедший аудит», в отличие от неизвестного SDK.

Установка

Установите Agent Reliability Analyzer (CLI trustabl) с помощью Homebrew, Scoop, Docker или прямой загрузки.

Homebrew (macOS, Linux)

brew install trustabl/tap/trustabl

Scoop (Windows)

scoop bucket add trustabl https://github.com/trustabl/scoop-bucket
scoop install trustabl

Docker

docker run --rm -v "$PWD:/repo" ghcr.io/trustabl/trustabl:latest scan /repo

Прямая загрузка

Загрузите готовый архив для своей платформы со страницы

Releases. В каждый выпуск входят файл checksums.txt и аттестация происхождения сборки. Проверьте её с помощью:

--repo trustabl/agent-reliability-analyzer">

gh attestation verify <archive> --repo trustabl/agent-reliability-analyzer

Для архивов, выпущенных до переименования репозитория, при проверке нужно указывать старый идентификатор репозитория (--repo trustabl/trustabl): сертификат Sigstore привязывает путь к репозиторию на момент подписания, поэтому зафиксированная идентичность не меняется вслед за переименованием.

Плагин Claude Code

Плагин устанавливает два навыка (trustabl-scan и trustabl-enrich), хук

SessionStart и встроенный MCP-сервер. При первом запуске сессии он автоматически загружает закреплённый CLI-бинарный файл: права sudo не нужны, доступ к данным за пределами каталога данных плагина Claude Code не выполняется.

Установите плагин из сессии Claude Code с помощью слеш-команды /plugin:

/plugin install trustabl@claude-plugins-official

Затем перезагрузите плагины, чтобы активировать его:

/reload-plugins

После установки инструмент mcp__trustabl__scan будет доступен для прямого вызова, навыки trustabl-scan и trustabl-enrich появятся в списке навыков, а хук подтвердит готовность бинарного файла при запуске сессии. Чтобы удалить плагин, выполните /plugin uninstall trustabl.

Агент Claude Code

Автономный субагент (trustabl) в интерактивном режиме выполняет полный цикл: сканирование → обогащение → проверка → применение исправлений. Плагин для этого не нужен — достаточно, чтобы бинарный файл trustabl был доступен через PATH. Скопируйте файл агента в настройки проекта или пользователя:

# Project-level (scoped to this repo)
curl -fsSL https://raw.githubusercontent.com/trustabl/agent-reliability-analyzer/main/agents/trustabl.md \
  -o .claude/agents/trustabl.md

# Global (available in every project)
curl -fsSL https://raw.githubusercontent.com/trustabl/agent-reliability-analyzer/main/agents/trustabl.md \
  -o ~/.claude/agents/trustabl.md

После установки вызовите агента с помощью @trustabl в Claude Code или выберите его в списке субагентов. Агент уточнит, какой каталог нужно просканировать, выполнит trustabl scan и trustabl enrich, а затем предложит пошагово рассмотреть каждое исправление в виде diff.

Для этапа обогащения требуется API-ключ Anthropic. Установите его до вызова агента:

export ANTHROPIC_API_KEY=sk-ant-api03-...   # or: trustabl llm key set

Сборка из исходного кода

Требуется CGO_ENABLED=1, поскольку AST-парсеры используют tree-sitter

(биндинги для Python + TypeScript + TSX), написанный на C:

# macOS / Linux
CGO_ENABLED=1 go build -o trustabl ./cmd/trustabl

# Cross-compile: pick a C toolchain for the target. zig is the easiest.
CGO_ENABLED=1 CC="zig cc -target x86_64-linux-gnu" \
  GOOS=linux GOARCH=amd64 go build -o trustabl-linux ./cmd/trustabl

Это необходимая плата за точный разбор AST с помощью tree-sitter. Если в будущем станет обязательным распространение в виде одного бинарного файла без CGO, для Python можно перейти на github.com/go-python/gpython (с меньшей точностью при разборе современных версий Python). Для TypeScript потребуется отдельная замена.

Аттестация

Пример использования: тестирование

Требования и настройка:

Установите cosign (любую версию 2.x или 3.x — Trustabl адаптируется к установленной версии)

Добавьте путь к целевой папке:

export PATH=":$PATH"

Экспортируйте переменную и создайте пару ключей:

export COSIGN_PASSWORD=""

пропускает запрос парольной фразы (для реального ключа не указывайте это значение)

cosign generate-key-pair

создаёт cosign.key (закрытый ключ) и cosign.pub (открытый ключ)

Выполните сканирование и создайте аттестацию с помощью Trustabl:

./trustabl.exe scan https://github.com/google/adk-samples --json-out report.json --attest --attest-key cosign.key --attest-bundle att.bundle.json --attest-no-tlog

ПРОВЕРКА

./trustabl.exe verify report.json --key cosign.pub --bundle att.bundle.json --no-tlog

Подписание без ключа (CI / без необходимости управлять ключами)

При подписании без ключа используется текущая идентичность OIDC вместо пары ключей — ничего не нужно создавать или хранить. В CI (GitHub Actions) автоматически используется идентичность среды выполнения; на ноутбуке откроется браузер для входа. В обоих случаях событие подписания записывается в общедоступный журнал прозрачности Rekor. Если такой уровень видимости неприемлем, используйте описанный выше режим с ключом. Здесь не используется --no-tlog (подписание без ключа всегда предполагает работу с журналом прозрачности), поэтому различия между cosign v2 и v3 не имеют значения.

Сканирование и создание аттестации без ключа:

./trustabl.exe scan https://github.com/google/adk-python --json-out report.json --attest --attest-bundle att.bundle.json

ПРОВЕРКА (подписание без ключа — необходимо указать, кто подписал, и издателя):

./trustabl.exe verify report.json --bundle att.bundle.json --certificate-identity "" --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

В GitHub Actions идентичностью служит ссылка на workflow, например:

https://github.com/OWNER/REPO/.github/workflows/scan.yml@refs/heads/main.

cosign (необязательно — требуется только для аттестации результатов сканирования)

Команды Trustabl attest и verify, а также scan --attest вызывают CLI

cosign. За подписание и проверку отвечает cosign; Trustabl не содержит собственных ключей. cosign нужен только при использовании аттестации: обычная команда scan его не вызывает.

# macOS / Linux
brew install cosign
# Windows
scoop install cosign

В CI устанавливать cosign вручную не нужно: Trustabl GitHub Action и компонент GitLab сделают это за вас с помощью sigstore/cosign-installer.

Сканирование с аттестацией — пошаговая инструкция (режим ключа, офлайн)

В режиме ключа подпись создаётся локальной парой ключей, а публичный журнал прозрачности не используется. Браузер и сеть не нужны — этот режим подходит для ноутбука и изолированной среды.

Версия cosign: поддерживаются cosign 2.x и 3.x — Trustabl автоматически выбирает подходящий механизм без журнала прозрачности в зависимости от версии (--tlog-upload=false для v2; --signing-config без Rekor для v3+, где этот флаг удалён). При установке в PATH команда называется trustabl; для локальной сборки Windows используйте .\trustabl.exe.

Уровни аттестации: это базовая аттестация бесплатного уровня — она подписывает происхождение сканирования (ID сканирования, версию правил, оценку надёжности, вердикт и количество проблем по уровням серьёзности). Аттестации с учётом поведения и политик запланированы для платной версии.

Шаг 0 — установите cosign (команды для вашей ОС приведены выше).

Шаг 1 — создайте пару ключей для подписи:

export COSIGN_PASSWORD=""        # skip the passphrase prompt (omit for a real key)
cosign generate-key-pair         # writes cosign.key (private) + cosign.pub (public)

Шаг 2 — выполните сканирование и подпишите результат одной командой:

trustabl scan https://github.com/google/adk-samples \
  --json-out report.json \
  --attest --attest-key cosign.key --attest-bundle att.bundle.json --attest-no-tlog

Команда создаёт report.json (результат сканирования), trustabl-predicate.json и подписанный файл att.bundle.json. Код завершения 1 означает только то, что при сканировании найдены проблемы: файл с аттестацией всё равно будет создан, поскольку в нём подписывается вердикт — как положительный, так и отрицательный.

Шаг 3 — проверьте результат (на стороне потребителя):

trustabl verify report.json --key cosign.pub --bundle att.bundle.json --no-tlog

Verified OK, код завершения 0 — отчёт подлинный и не изменён.

Шаг 4 — (необязательно) проверьте обнаружение изменений:

report.json trustabl verify report.json --key cosign.pub --bundle att.bundle.json --no-tlog">

echo '{"tampered":true}' >> report.json
trustabl verify report.json --key cosign.pub --bundle att.bundle.json --no-tlog

Теперь проверка НЕ ПРОЙДЁТ (код завершения 1): подпись связана с точным содержимым отчёта, поэтому будет обнаружено любое изменение.

По умолчанию в CI используется подписание без ключа: отдельным закрытым ключом управлять не нужно, поскольку среда предоставляет OIDC-идентификацию. Кроме того, событие подписания записывается в публичный журнал прозрачности Rekor. Полный список команд см. в разделе «Использование».

Использование — первое сканирование надёжности агента

trustabl.sarif

Write the report to a file instead of stdout (any format). --output writes

the file even when the scan exits 1 on findings, so a CI step can upload it.

trustabl scan ./repo --format sarif --output trustabl.sarif

One scan, both machine artifacts written to files (human summary to stdout)

trustabl scan ./repo --json-out trustabl.json --sarif-out trustabl.sarif

Exit 1 on any finding regardless of severity

trustabl scan ./repo --strict

--- Attestation (opt-in; requires the cosign CLI on PATH) -------------------

Sign the JSON report into a cosign attestation of the SCANNED repo's result.

Keyless by default: in CI it uses the runner's ambient OIDC identity (no keys

to manage) and logs the signing event to the PUBLIC Rekor transparency log.

trustabl scan ./repo --json-out trustabl.json --attest trustabl attest trustabl.json # same, as a separate step

Offline / private signing with a key (no public transparency log):

trustabl attest trustabl.json --key cosign.key --no-tlog

Verify (run where you CONSUME the attestation). Keyless pins who signed + issuer:

trustabl verify trustabl.json
--certificate-identity https://github.com/OWNER/REPO/.github/workflows/scan.yml@refs/heads/main
--certificate-oidc-issuer https://token.actions.githubusercontent.com trustabl verify trustabl.json --key cosign.pub --no-tlog # key-mode, offline

Download / refresh the detection rule packs into the local cache

trustabl rules pull

Validate a local rule-pack directory against this build's schema (CI gate

for the agent-reliability-rules repo — strict-loads every pack, fails on the first error)

trustabl rules validate ./agent-reliability-rules

Use a custom rules repo, or pin a specific released ruleset (env: TRUSTABL_RULES_REPO).

Default pulls the latest reviewed rules from agent-reliability-rules main; pin a tag for stability.

trustabl scan ./repo --rules-repo https://github.com/org/my-rules trustabl scan ./repo --rules-ref v0.1.0

Air-gapped / offline: skip the network fetch, use the cached rules only

trustabl scan ./repo --no-rules-update

Progress output (human format): animated on a terminal, plain lines when piped

trustabl scan ./repo # spinner + bars on a TTY; "[phase] summary" lines when piped trustabl scan ./repo --no-progress # disable progress entirely

Diagnostics on stderr (global flags; stdout/report unaffected)

trustabl scan ./repo --verbose # -v: rule provenance, discovery counts, result summary trustabl scan ./repo --debug # + per-phase timing and per-entity/per-finding detail trustabl scan ./repo --debug --format json > out.json # clean JSON on stdout, diagnostics on stderr

Run as a stdio MCP server so an MCP client (Claude Code, Cursor, Claude

Desktop) can scan code an agent just wrote (see "Run as an MCP server" below)

trustabl mcp

Configure LLM provider, then enrich a scan result with AI explanations and fixes

export ANTHROPIC_API_KEY=sk-ant-api03-... # preferred: env var (works in CI, no setup) trustabl llm list # show configured providers with masked keys trustabl llm key set # prompt securely for an API key (persistent) trustabl llm key set sk-ant-api03-... # set key non-interactively trustabl llm key get # show masked key for active provider trustabl llm key delete # delete key with confirmation prompt trustabl llm model set claude-sonnet-4-6 # change model for active provider trustabl llm base-url set http://host:4000 # set API base URL (only meaningful for "custom") trustabl llm provider set openai # switch active provider (auto-creates entry) trustabl llm provider list # list configured providers

Self-hosted / local model server (any OpenAI-compatible endpoint, e.g. a

LiteLLM or vLLM gateway). Two ways to configure it:

1. Env vars — no persistent config, works in CI:

OPENAI_BASE_URL alone activates "custom", ahead of a plain OPENAI_API_KEY.

No default model, so TRUSTABL_LLM_MODEL is required. OPENAI_API_KEY is

optional: only set it if the endpoint actually checks it.

export OPENAI_BASE_URL=http://localhost:4000 export TRUSTABL_LLM_MODEL=qwen-32b

2. Persistent config — same three fields, saved to ~/.config/trustabl/keys.json:

trustabl llm provider set custom trustabl llm base-url set http://localhost:4000 trustabl llm model set qwen-32b

trustabl llm key set is optional — skip it if the endpoint needs no key

Enrich a scan result (requires any configured LLM provider — a custom

endpoint may not need a key, every other provider does)

trustabl scan ./myrepo --format json | trustabl enrich --repo ./myrepo # pipe scan into enrich (stdout) trustabl enrich --input scan.json --repo ./myrepo --output enriched.json # file in, file out trustabl enrich --input scan.json --repo ./myrepo --diff # preview proposed fixes as a unified diff (stderr) trustabl enrich --input scan.json --repo ./myrepo --diff --apply # preview and apply fixes trustabl enrich --input scan.json --repo ./myrepo --apply # apply fixes without previewing trustabl enrich --input scan.json --repo ./myrepo --rule CSDK-010 # focus on one rule trustabl enrich --input scan.json --repo ./myrepo --only-enriched # CI: only enriched findings

Ground tool findings in LangSmith runtime traces (opt-in; error rates, latency,

недавние ошибки собираются отдельно для каждого помеченного инструмента и передаются LLM как подтверждающие данные

export LANGSMITH_API_KEY=lsv2_... # BYOK; LANGSMITH_ENDPOINT overrides for self-hosted trustabl enrich --input scan.json --repo ./myrepo --langsmith # project: $LANGSMITH_PROJECT or "default" trustabl enrich --input scan.json --repo ./myrepo --langsmith --langsmith-project prod">

# Local repo
trustabl scan ./path/to/agent-repo

# GitHub repo (shallow clone to temp dir, removed on exit)
trustabl scan https://github.com/org/repo

# Restrict detectors
trustabl scan ./repo --detectors claude_sdk
trustabl scan ./repo --detectors openai_sdk
trustabl scan ./repo --detectors google_adk
trustabl scan ./repo --detectors claude_sdk,openai_sdk,google_adk
# --detectors openshell is accepted but selects zero rules (pack is closed-source now)

# Agent Skill security (SKILL.md) — flags unrestricted allowed-tools (a bare
# `Bash` grant), pre-model dynamic-context exec, bundled-script network egress /
# secret reads, committed secrets, hidden-Unicode prompt injection, and a
# description that claims read-only while granting side-effecting tools (the
# CSKILL-* rules). Skills are discovered and scanned automatically.
trustabl scan ./repo                              # scans skills alongside tools/agents/MCP
trustabl scan ./repo --detectors claude_skill     # only the Agent Skill (CSKILL-*) rules
trustabl scan ./path/to/my-skill                  # point straight at one skill's directory

# Dependency BOM (supply chain): export the repo's DECLARED deps across all
# supported languages (pip / npm / Go / Composer / NuGet / Cargo manifests) as a
# CycloneDX SBOM, to hand to OSV-Scanner / Dependabot / syft. Pure inventory —
# the scan itself does no CVE lookup.
trustabl scan ./repo --bom-out sbom.json

# Vulnerability scan (opt-in, online): match the repo's pinned deps against the
# OSV database and FAIL on known CVEs — advisory id, CVSS severity, fixed version.
trustabl vulndb pull                              # pre-download OSV (optional; --vuln-scan auto-fetches)
trustabl scan ./repo --vuln-scan                  # BOM inventory + CVE verdict in one pass
trustabl scan ./repo --vuln-scan --bom-out bom.json  # CycloneDX BOM + VEX (vulnerabilities[]) in one file

# License scan (opt-in): flag dependencies with copyleft licenses (GPL-2.0,
# GPL-3.0, AGPL-3.0, LGPL-2.1, SSPL-1.0) as medium-severity findings.
# License data is read from the manifest at parse time — no network call.
trustabl scan ./repo --license-scan
trustabl scan ./repo --license-scan --bom-out bom.json  # findings + BOM with licenses[]

# Secret scan (opt-in): walk all text files in the repo for hardcoded
# credential literals (SECRET-LIT-001, high) and scripts that read
# credential environment variables (SECRET-ENV-001, medium).
trustabl scan ./repo --secret-scan

# Test-path findings (a tests/ agent, test_*.py, *.spec.ts, …) are always
# reported but excluded from scoring and the exit code by default — see
# "Test-path findings" below. --include-test-paths scores and fails on them
# like any other finding.
trustabl scan ./repo --include-test-paths

# JSON output for CI piping
trustabl scan ./repo --format json

# SARIF output for GitHub Code Scanning / SARIF-aware tools
trustabl scan ./repo --format sarif > trustabl.sarif

# Write the report to a file instead of stdout (any format). --output writes
# the file even when the scan exits 1 on findings, so a CI step can upload it.
trustabl scan ./repo --format sarif --output trustabl.sarif

# One scan, both machine artifacts written to files (human summary to stdout)
trustabl scan ./repo --json-out trustabl.json --sarif-out trustabl.sarif

# Exit 1 on any finding regardless of severity
trustabl scan ./repo --strict

# --- Attestation (opt-in; requires the cosign CLI on PATH) -------------------
# Sign the JSON report into a cosign attestation of the SCANNED repo's result.
# Keyless by default: in CI it uses the runner's ambient OIDC identity (no keys
# to manage) and logs the signing event to the PUBLIC Rekor transparency log.
trustabl scan ./repo --json-out trustabl.json --attest
trustabl attest trustabl.json                       # same, as a separate step
# Offline / private signing with a key (no public transparency log):
trustabl attest trustabl.json --key cosign.key --no-tlog
# Verify (run where you CONSUME the attestation). Keyless pins who signed + issuer:
trustabl verify trustabl.json \
  --certificate-identity https://github.com/OWNER/REPO/.github/workflows/scan.yml@refs/heads/main \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com
trustabl verify trustabl.json --key cosign.pub --no-tlog   # key-mode, offline

# Download / refresh the detection rule packs into the local cache
trustabl rules pull

# Validate a local rule-pack directory against this build's schema (CI gate
# for the agent-reliability-rules repo — strict-loads every pack, fails on the first error)
trustabl rules validate ./agent-reliability-rules

# Use a custom rules repo, or pin a specific released ruleset (env: TRUSTABL_RULES_REPO).
# Default pulls the latest reviewed rules from agent-reliability-rules main; pin a tag for stability.
trustabl scan ./repo --rules-repo https://github.com/org/my-rules
trustabl scan ./repo --rules-ref v0.1.0

# Air-gapped / offline: skip the network fetch, use the cached rules only
trustabl scan ./repo --no-rules-update

# Progress output (human format): animated on a terminal, plain lines when piped
trustabl scan ./repo                 # spinner + bars on a TTY; "[phase] summary" lines when piped
trustabl scan ./repo --no-progress   # disable progress entirely

# Diagnostics on stderr (global flags; stdout/report unaffected)
trustabl scan ./repo --verbose       # -v: rule provenance, discovery counts, result summary
trustabl scan ./repo --debug         # + per-phase timing and per-entity/per-finding detail
trustabl scan ./repo --debug --format json > out.json   # clean JSON on stdout, diagnostics on stderr

# Run as a stdio MCP server so an MCP client (Claude Code, Cursor, Claude
# Desktop) can scan code an agent just wrote (see "Run as an MCP server" below)
trustabl mcp

# Configure LLM provider, then enrich a scan result with AI explanations and fixes
export ANTHROPIC_API_KEY=sk-ant-api03-...  # preferred: env var (works in CI, no setup)
trustabl llm list                          # show configured providers with masked keys
trustabl llm key set                       # prompt securely for an API key (persistent)
trustabl llm key set sk-ant-api03-...      # set key non-interactively
trustabl llm key get                       # show masked key for active provider
trustabl llm key delete                    # delete key with confirmation prompt
trustabl llm model set claude-sonnet-4-6   # change model for active provider
trustabl llm base-url set http://host:4000 # set API base URL (only meaningful for "custom")
trustabl llm provider set openai           # switch active provider (auto-creates entry)
trustabl llm provider list                 # list configured providers

# Self-hosted / local model server (any OpenAI-compatible endpoint, e.g. a
# LiteLLM or vLLM gateway). Two ways to configure it:
#
# 1. Env vars — no persistent config, works in CI:
#    OPENAI_BASE_URL alone activates "custom", ahead of a plain OPENAI_API_KEY.
#    No default model, so TRUSTABL_LLM_MODEL is required. OPENAI_API_KEY is
#    optional: only set it if the endpoint actually checks it.
export OPENAI_BASE_URL=http://localhost:4000
export TRUSTABL_LLM_MODEL=qwen-32b
#
# 2. Persistent config — same three fields, saved to ~/.config/trustabl/keys.json:
trustabl llm provider set custom
trustabl llm base-url set http://localhost:4000
trustabl llm model set qwen-32b
# trustabl llm key set is optional — skip it if the endpoint needs no key

# Enrich a scan result (requires any configured LLM provider — a custom
# endpoint may not need a key, every other provider does)
trustabl scan ./myrepo --format json | trustabl enrich --repo ./myrepo        # pipe scan into enrich (stdout)
trustabl enrich --input scan.json --repo ./myrepo --output enriched.json      # file in, file out
trustabl enrich --input scan.json --repo ./myrepo --diff                      # preview proposed fixes as a unified diff (stderr)
trustabl enrich --input scan.json --repo ./myrepo --diff --apply              # preview and apply fixes
trustabl enrich --input scan.json --repo ./myrepo --apply                     # apply fixes without previewing
trustabl enrich --input scan.json --repo ./myrepo --rule CSDK-010             # focus on one rule
trustabl enrich --input scan.json --repo ./myrepo --only-enriched             # CI: only enriched findings

# Ground tool findings in LangSmith runtime traces (opt-in; error rates, latency,
# recent errors are fetched per flagged tool and fed to the LLM as evidence)
export LANGSMITH_API_KEY=lsv2_...          # BYOK; LANGSMITH_ENDPOINT overrides for self-hosted
trustabl enrich --input scan.json --repo ./myrepo --langsmith                  # project: $LANGSMITH_PROJECT or "default"
trustabl enrich --input scan.json --repo ./myrepo --langsmith --langsmith-project prod

Правила кэшируются в каталоге кэша вашей ОС (os.UserCacheDir(), например,

%LocalAppData%\trustabl\rules\ в Windows, ~/.cache/trustabl/rules/

в Linux). При первом сканировании (или явном запуске trustabl rules pull)

кэш заполняется. Перед каждым последующим сканированием проверяется наличие

обновлений (если не указан параметр --no-rules-update); если получить их

не удаётся, используются правила из кэша.

Каналы подписанных правил (по умолчанию). При обычном запуске trustabl scan

правила загружаются из канала релизов production, подлинность которого

подтверждается цифровой подписью: Trustabl проверяет подписанное описание

канала с помощью встроенного набора доверенных ключей, загружает указанный в нём

пакет правил и прекращает работу с кодом завершения 2 при любой ошибке

проверки, вместо того чтобы запускать непроверенные правила. Параметр

--rules-source git явно выбирает неподписанный источник git; параметры

--rules-repo и --rules-ref также подразумевают его. Чтобы тестировать

подписанный форк, можно указать нестандартный канал с помощью параметров

--rules-source --rules-repo .

(--channel — устаревший псевдоним для --rules-source .) **Теперь при

сканировании по умолчанию используется подписанный канал production**. В CI

установите TRUSTABL_REQUIRE_SIGNED=1 (или укажите --require-signed), чтобы

полностью запретить переход к неподписанному источнику git. Это изменение не

затрагивает уже выпущенные до перехода бинарные файлы: значения по умолчанию и

набор доверенных ключей встроены в них. После обновления ScanID изменится один

раз: вместо origin tag и git-SHA в нём будет использоваться дайджест пакета

канала. Если при сканировании не применялись утверждённые правила production

(например, использовался канал предварительного выпуска или пользовательский

источник --rules-repo), в отчёте и в поле JSON rules_origin появится

соответствующая отметка, а сведения о происхождении будут включены в ScanID.

В эту сборку встроен открытый ключ для проверки подписей правил, поэтому при

использовании подписанного --rules-source запускается процедура проверки. Она

прерывает работу с кодом завершения 2 только при реальной ошибке проверки:

неверной подписи, недоверенном или просроченном ключе, несоответствии канала,

просроченном или откаченном описании канала либо несовпадении дайджеста.

Ограничения до написания кода (`trustabl forge`)

trustabl forge дополняет trustabl scan: вместо проверки уже написанного кода команда создаёт объединённый файл SKILL.md для подготовки к написанию кода. Он заранее сообщает агенту, каких шаблонов следует избегать. Правила сгруппированы по SDK и области действия (инструмент, агент, субагент, репозиторий, навык) и упорядочены по степени серьёзности: ограничения с наибольшим риском идут первыми.

Как определяется SDK. Forge анализирует файлы манифестов зависимостей целевого проекта —

pyproject.toml, requirements.txt, Pipfile, poetry.lock, package.json

и go.mod — чтобы определить, какие наборы политик SDK включить. Это тот же быстрый анализ файлов зависимостей, который trustabl scan выполняет на этапе разведки: без разбора AST, быстро и безопасно для любого репозитория. Если манифесты не найдены или ни в одном из них не указан поддерживаемый SDK, forge завершает работу с кодом 1 и подсказывает, что передать через --policy.

Определение языка. По тем же манифестам forge определяет язык, для которого объявлен каждый SDK: pyproject.toml, requirements.txt, Pipfile и poetry.lock означают Python, package.json — TypeScript, go.mod — Go. На основе этого выбираются языковые блоки раздела Runtime Tracing. Чтобы добавить язык, передайте --lang python,typescript,go. Параметр --lang не выбирает набор правил, поэтому новому репозиторию без манифеста понадобится также --policy (см. последний пример ниже). По этим же языкам отбираются разделы с правилами: если SDK объявлен только в go.mod, будут включены только правила для Go и правила, применимые ко всем языкам. Поэтому для репозитория Google ADK только с Go появится рецепт трассировки для Go, языконезависимые правила ADK и примечание об отсутствии правил ADK, специфичных для Go. Для категории, переданной только через --policy или объявленной в манифесте, который forge не может обработать (например, composer.json), сохраняются все правила.

# Автоматически определить SDK по текущему каталогу
trustabl forge

# Автоматически определить SDK по указанному пути к репозиторию
trustabl forge /path/to/repo

# Добавить политику к автоматически определённым SDK — полезно при подключении нового
# SDK, который ещё не указан в манифесте зависимостей
trustabl forge --policy openai_sdk
trustabl forge /path/to/repo --policy claude_sdk,mcp

# Записать сгенерированный SKILL.md в файл, а не в stdout
trustabl forge -o .claude/skills/trustabl-pre-coding/SKILL.md

# Указать конкретную версию правил (аналогично trustabl scan --rules-ref)
trustabl forge --rules-ref v0.3.0

# Для обратной совместимости: сгенерировать только правила Agent Skill (CSKILL-*)
trustabl forge --policy claude_skill

# Новый репозиторий Go, в котором ещё нет go.mod
trustabl forge --policy google_adk --lang go

Доступные категории политик (передаются через --policy):

Категория	SDK / фреймворк
`claude_sdk`	Claude Agent SDK (Python + TypeScript)
`openai_sdk`	OpenAI Agents SDK (Python + TypeScript)
`google_adk`	Google Agent Development Kit (Python + TypeScript)
`mcp`	Серверы Model Context Protocol
`langchain`	LangChain / LangGraph (Python + TypeScript)
`crewai`	CrewAI (Python)
`pydantic_ai`	Pydantic AI (Python)
`vercel_ai`	Vercel AI SDK (TypeScript)
`autogen`	AutoGen / AG2 (Python)
`claude_skill`	Навыки Claude Code (`SKILL.md`)
`raw_llm_sdk`	Циклы вызова инструментов с базовыми клиентами `anthropic` / `openai` (не агентский фреймворк)
`agent_config`	Конфигурация harness, добавленная в репозиторий, которая выполняет код или предоставляет полномочия до проверки доверенности каталога (`.claude/settings.json`, `.mcp.json`, `.gemini/.env`, `.vscode/settings.json`, `.codex/config.toml`)
`ci`	Агент для написания кода запускается из workflows GitHub Actions (`.github/workflows/*.yml`) в ответ на события, инициировать которые может любой пользователь GitHub
`openshell`	Инструменты для вызова оболочки (в текущем наборе правил правил нет)

Несколько категорий указываются через запятую: --policy openai_sdk,mcp.

Что содержит результат. Сгенерированный файл — это корректный SKILL.md, включающий:

Блок frontmatter (name: trustabl-pre-coding, allowed-tools: Read,

disable-model-invocation: false).

Комментарий-метку, содержащий SHA правил, дату, версию схемы,

версию шаблона (структуры) и список обнаруженных SDK. Это позволяет точно

узнать, какой набор правил и какая структура использовались при создании файла,

а также когда его следует обновить.

Раздел ## How to Apply These Constraints со структурой цикла применения,

сразу после метки: статическая процедура из четырёх шагов, которая предписывает

модели сверять каждое созданное ею определение с соответствующими ограничениями,

указывать нарушенное правило по ID, выполнять предписание этого правила

и регистрировать исправление. Это самопроверка модели — она не запускает

trustabl scan самостоятельно; проверка созданного кода остаётся отдельным шагом.

Раздел ## Tool-Call Claims: каждый вызов инструмента с побочным эффектом

сопровождается небольшим типизированным утверждением

(ToolInvocationExplanation: класс намерения, выбранный инструмент,

ожидаемый эффект, уровень риска, неопределённость, зависимости от недоверенного

контекста, дайджесты доказательств). До того как вызов возымеет эффект, этап

посредничества вне модели сверяет утверждение с фактами, хранящимися на сервере.

Конфликты приводят к отказу, неизвестные случаи направляются на проверку,

а при выборе результата применяется наиболее ограничительный вариант;

утверждение никогда не предоставляет полномочий. Этот механизм следует

принципу Explanation-Bound Tool Execution (EBTE) и указывает, где именно

размещается соответствующий этап в каждом обнаруженном SDK. Раздел не включается,

если выбрана только категория claude_skill.

Раздел ## Runtime Tracing: инструкции по настройке агента для отправки

спанов OpenTelemetry и их последующей маркировке с помощью

agent-reliability-otel-labels (идентификатор запуска, порядок шагов,

отпечатки вызовов инструментов, число повторных попыток, класс побочного эффекта,

причина завершения). В разделе есть блок для каждого выбранного языка

(Python, TypeScript, Go), а также проверенные настройки для Google ADK

(Python, Go), Vercel AI SDK (TypeScript), Pydantic AI (Python),

OpenAI Agents SDK (Python, TypeScript), LangChain / LangGraph (Python),

CrewAI (Python), AutoGen (Python) и клиентских сессий MCP (Python).

Для остальных фреймворков приводится только блок языка. Системы трассировки,

не использующие OpenTelemetry, не рассматриваются. Раздел не включается,

если поддерживаемый язык не обнаружен или выбрана только категория

claude_skill (Agent Skills — это файлы SKILL.md, а не код агента,

который нужно трассировать).

Отдельный раздел ## SDK Name для каждого обнаруженного SDK. В каждом разделе

есть подразделы ### Tool Rules, ### Agent Rules, ### Subagent Rules,

### Repo Rules и ### Skill Rules; пустые подразделы опускаются.

Блоки для каждого правила: Directive (исправление, первое предложение),

Why (объяснение, первое предложение), When this applies, уровень

серьёзности и уровень уверенности.

Поместите результат в .claude/skills/trustabl-pre-coding/SKILL.md в репозитории агента, и Claude Code будет автоматически применять его перед написанием любого кода агента. Повторно запускайте trustabl forge после добавления зависимости нового SDK, получения обновлённых правил или перехода на версию forge с более новым шаблоном. Команда trustabl forge check сообщает об устаревании файла в обоих случаях.

Непрерывная интеграция

Поддерживаются два варианта интеграции с CI; их можно использовать вместе:

Блокировать сборку. Условием блокировки служит код завершения: 0 — проблем не найдено, 1 — найдено нарушение средней или более высокой степени серьёзности (параметр --strict снижает порог до любого нарушения), 2 — операционная ошибка. Если запустить в шаге задачи обычную команду trustabl scan ./repo, задача завершится ошибкой при обнаружении проблем.
Публиковать результаты в GitHub Code Scanning. В GitHub Actions действие

trustabl/trustabl-action

выполняет сканирование и загружает SARIF в раздел Security репозитория одним шагом (upload-sarif по умолчанию равен true). Действие добавляет оповещения непосредственно в PR и позволяет задать порог блокировки — это рекомендуемый вариант и единый источник истины для workflow. Вне GitHub Actions параметр --format sarif --output записывает отчёт SARIF 2.1.0, который можно опубликовать с помощью github/codeql-action/upload-sarif или любого шага с поддержкой SARIF. Поскольку --output записывает файл до применения кода завершения, зависящего от найденных проблем, для шага сканирования можно установить continue-on-error: true, а для загрузки — if: always(). Тогда сканирование, обнаружившее проблемы, всё равно опубликует результаты, а не прервёт запуск без загрузки отчёта.

Документ SARIF формируется исключительно на основе результатов сканирования: для одинаковых входных данных он побайтово совпадает между запусками, содержит URI файлов относительно репозитория и стабильное значение partialFingerprints для каждого нарушения. Благодаря этому Code Scanning объединяет оповещения между запусками, а не создаёт их повторно.

Запуск в качестве MCP-сервера

Команда trustabl mcp запускает сервер Model Context Protocol (MCP), который взаимодействует через stdio. MCP-клиент (Claude Code, Cursor, Claude Desktop) может просканировать каталог, недавно изменённый агентом, и получить результаты проверки. Это тот же процесс сканирования, что и при запуске trustabl scan, но доступный как инструмент MCP. Сервер не открывает сетевой порт. Он передаёт данные в формате JSON-RPC через stdout и не выводит туда ничего другого; строки состояния и диагностические сообщения направляются в stderr.

Сервер предоставляет два инструмента:

scan — принимает { "path": "", "rules_ref": ""?, "vuln_scan": true? }.

Сканирует каталог path и возвращает полный результат проверки в формате JSON: обнаруженные проблемы, оценки и найденные компоненты. Структура результата совпадает с форматом --format json. Укажите vuln_scan: true, чтобы дополнительно сверить объявленные зависимости с закреплённой версией снимка OSV и сообщить об известных CVE. По умолчанию эта проверка отключена; параметр соответствует --vuln-scan.

version — сообщает версию сборки, коммит и дату.

Чтобы зарегистрировать сервер в MCP-клиенте, укажите путь к исполняемому файлу и передайте ему аргумент mcp через stdio. Для Claude Code:

claude mcp add trustabl -- trustabl mcp

Для Gemini CLI добавьте следующую конфигурацию в ~/.gemini/settings.json:

{
  "mcpServers": {
    "trustabl": {
      "command": "trustabl",
      "args": ["mcp"]
    }
  }
}

Для OpenAI Codex добавьте в ~/.codex/config.toml:

[mcp_servers.trustabl]
command = "trustabl"
args = ["mcp"]

Также сервер можно настроить непосредственно в конфигурации MCP-клиента, используя формат stdio mcpServers, который применяют Claude Desktop и Cursor:

{
  "mcpServers": {
    "trustabl": {
      "command": "trustabl",
      "args": ["mcp"]
    }
  }
}

Флаги для настройки источника правил (--rules-repo, --rules-ref, --no-rules-update) работают с trustabl mcp так же, как с trustabl scan. Кроме того, клиент может передать параметр rules_ref для отдельного вызова инструмента scan. В этом случае он переопределит переданный на уровне команды --rules-ref для данного вызова.

Плагин Claude Code (самопроверка во время генерации кода)

В состав Trustabl входит плагин Claude Code в каталоге .claude-plugin/. В нём есть два навыка, которые вместе образуют цикл сканирования и исправления:

trustabl-scan — запускается сразу после создания или изменения кода агента, инструмента, субагента или MCP-сервера и вызывает инструмент scan из Trustabl (встроенный MCP-сервер, mcp__trustabl__scan), чтобы проверить изменения до коммита и до этапа CI.
trustabl-enrich — принимает результаты запуска trustabl scan в формате JSON, SARIF или в виде вставленного текста из терминала и вносит целевые изменения в код для устранения каждой обнаруженной проблемы. При этом навык опирается исключительно на поля explanation и suggested_fix из результатов сканирования. Он не запускает сканер повторно: сначала используйте trustabl-scan, а затем вызовите trustabl-enrich и передайте ему результаты.

Сканирование выполняется через встроенный MCP-сервер. Файл .mcp.json регистрирует сервер trustabl, команда которого запускает скрипт (scripts/trustabl-mcp.sh) и предоставляет инструмент mcp__trustabl__scan. Скрипт запуска и хук SessionStart (hooks/hooks.json → scripts/check-trustabl.sh) используют общую логику установки (scripts/lib-trustabl.sh). Она загружает закреплённую версию CLI из GitHub Releases, проверяет её по файлу checksums.txt из релиза и устанавливает в закрытый каталог данных плагина ($CLAUDE_PLUGIN_DATA). Для этого не нужны права sudo, и никакие файлы за пределами этого каталога не затрагиваются. Установка идемпотентна: она повторяется только при изменении закреплённой версии либо при отсутствии или повреждении установленной копии. Скрипт запуска выполняет установку до старта сервера, поэтому при первом запуске сеанса гонки не возникает. Тот же исполняемый файл доступен по пути $TRUSTABL_BIN для прямого вызова CLI из навыка trustabl-enrich. Если автоматическая установка невозможна (например, при отсутствии сети во время первого сеанса, на неподдерживаемой платформе или без curl/tar), используется команда trustabl, найденная в PATH. Установка на уровне системы остаётся отдельным шагом, требующим согласия, и выполняется через trustabl-scan. Плагин не запускает собственные сетевые службы и не изменяет ничего за пределами каталога, который сканируется.

Расширение Gemini CLI (самопроверка во время генерации кода)

В состав Trustabl входит расширение Gemini CLI, описанное в файле gemini-extension.json. Оно включает те же два навыка, что и плагин Claude Code.

Предварительные требования. Сначала установите исполняемый файл Trustabl. В отличие от плагина Claude Code, расширение не устанавливает его автоматически, поскольку у Gemini CLI нет отдельного закрытого каталога данных плагинов:

# macOS / Linux
brew install trustabl/tap/trustabl

# Windows
scoop bucket add trustabl https://github.com/trustabl/scoop-bucket
scoop install trustabl

Установка расширения:

gemini extensions install https://github.com/trustabl/agent-reliability-analyzer

Регистрация MCP-сервера позволяет Gemini CLI вызывать mcp__trustabl__scan. Добавьте следующую конфигурацию в ~/.gemini/settings.json:

{
  "mcpServers": {
    "trustabl": {
      "command": "trustabl",
      "args": ["mcp"]
    }
  }
}

Принцип работы. При запуске сеанса Gemini CLI расширение добавляет в контекст файл GEMINI.md, который подключает полное содержимое навыков trustabl-scan и trustabl-enrich с помощью импортов @. Gemini использует эти навыки так же, как и любой другой загруженный контекст: запускает сканирование после создания или изменения кода агента, инструмента или MCP-сервера и предлагает применить исправления с помощью trustabl-enrich. Инструмент MCP называется mcp__trustabl__scan — так же, как в Claude Code.

Обновление расширения:

gemini extensions update trustabl

Плагин OpenAI Codex (самопроверка во время генерации кода)

В состав Trustabl входит плагин OpenAI Codex в каталоге .codex-plugin/. В нём доступны те же два навыка.

Предварительные требования. Сначала установите исполняемый файл Trustabl:

# macOS / Linux
brew install trustabl/tap/trustabl

# Windows
scoop bucket add trustabl https://github.com/trustabl/scoop-bucket
scoop install trustabl

Установка плагина. В Codex CLI откройте интерфейс поиска плагинов и выполните поиск по запросу trustabl:

/plugins

Найдите trustabl и выберите Install Plugin. В Codex App откройте раздел Plugins на боковой панели, найдите Trustabl в категории Security и нажмите +.

Регистрация MCP-сервера позволяет Codex вызывать mcp__trustabl__scan. Добавьте следующую конфигурацию в ~/.codex/config.toml:

[mcp_servers.trustabl]
command = "trustabl"
args = ["mcp"]

Принцип работы. Codex читает файл .codex-plugin/plugin.json, в котором указано "skills": "./skills/". Codex автоматически загружает из этого каталога навыки trustabl-scan и trustabl-enrich — запускать их вручную не нужно. Навыки срабатывают при создании или изменении кода агента, инструмента или MCP-сервера, а Codex применяет найденные исправления с помощью trustabl-enrich. Инструмент MCP называется mcp__trustabl__scan — так же, как в Claude Code и Gemini CLI.

Чтобы включить делегирование субагентам в Codex (оно используется в trustabl-enrich для параллельного редактирования файлов), задайте multi_agent = true в ~/.codex/config.toml.

«Правила новее, чем поддерживает эта сборка Trustabl»

Trustabl загружает правила с обратной совместимостью. Если разрешённый набор правил рассчитан на более новую версию схемы, чем понимает ваш бинарный файл, сканирование всё равно выполняется: Trustabl проверяет все правила, которые понимает ваша сборка, а остальные пропускает, выводя предупреждение в stderr и записывая идентификаторы пропущенных правил в ScanResult.RulesSkipped:

warning: the rules target schema version 13 but this Trustabl build supports up to 12; 2 rule(s) newer than this build were skipped. Upgrade Trustabl to evaluate them.

Так же обрабатываются отдельные правила, в которых указаны неизвестные вашей сборке scope, значение applies_to или предикат: такое правило пропускается, а остальные продолжают выполняться. Поэтому выпуск новой версии правил не требует одновременного обновления бинарного файла. О каждом пропуске также сообщается в самом отчёте: добавляется одна информационная находка META-005 («N правил требуют более новой версии движка Trustabl»). Это позволяет отличить неполное сканирование от чистого результата. Если правило некорректно, но при этом ваша сборка его понимает (например, в нём отсутствует поле или указано недопустимое значение), оно не будет пропущено из-за обратной совместимости: загрузка завершится ошибкой. Таким образом, реальные ошибки при создании правил не остаются незамеченными.

Чтобы выполнить пропущенные правила, обновите Trustabl до сборки, в которой SupportedSchemaVersion (см. internal/rules/schema_version.go) соответствует версии схемы набора. Если вас устраивает выполнение только поддерживаемых правил, никаких действий не требуется.

Сканирование завершается с ошибкой (код выхода 2), только если не осталось ни одного пригодного для выполнения правила:

«all rules require a newer engine schema» — каждое правило рассчитано на более новую версию схемы, чем поддерживает ваша сборка, поэтому запускать нечего. Обновите Trustabl или выберите более старую ветку или тег с правилами, которые ваша сборка полностью поддерживает (--rules-ref разрешает только ветки и теги, но не необработанные commit SHA, поэтому совместимая ссылка уже должна существовать):

trustabl scan ./repo --rules-ref <branch-or-tag>

«no usable rules manifest» — файл manifest.yaml отсутствует, не удаётся разобрать его содержимое или в нём указана неположительная версия. Это означает, что набор повреждён или загружен не полностью. Выполните trustabl rules pull, чтобы обновить его.
«no usable rules found» — в кэше нет правил, и загрузить их тоже не удалось (например, при отсутствии подключения к сети и пустом кэше). Подключитесь к сети и выполните trustabl rules pull.

Где находится код

Узел конвейера	Путь к коду
Импортёр	`internal/ingestion/importer.go`
Нормализатор (recon)	`internal/ingestion/normalizer.go`
Обнаружение (Python AST + markdown/JSON)	`internal/analysis/discovery.go`, `agents.go`, `hosted_tools.go`, `mcp_servers.go`, `adk_agents.go` (Python AST); `subagents.go`, `markdown_agents.go`, `skills.go`, `slash_commands.go` (markdown frontmatter); `plugins.go`, `claude_settings.go` (JSON)
Обнаружение TypeScript	`internal/analysis/ts_discovery.go`, `ts_agents.go`, `ts_mcp_servers.go`, `ts_handler_facts.go`, `ts_openai_tools.go`, `ts_openai_agents.go`, `ts_openai_hosted_tools.go`, `ts_openai_mcp_servers.go`, `ts_openai_guardrails.go`, `ts_openai_sessions.go`, `ts_adk_tools.go`, `ts_adk_agents.go`, `ts_adk_hosted_tools.go`, `astutil/ts.go`
Среда выполнения детекторов	`internal/analysis/detectors/`
Источник правил	`internal/rulesource/` (получение из git + кэширование + проверка версии схемы)
Правила детекторов	внешний репозиторий `agent-reliability-rules` (тесты: `testdata/rules-fixture/`)
Движок правил	`internal/rules/{schema,loader,evaluator,predicates,rule_detector}.go`
Движок оценки	`internal/analysis/scoring.go`
Формирование отчётов	`internal/review/diff.go` (для пользователя), `internal/sarif/render.go` (SARIF), сериализация JSON в `cmd/trustabl`
Конфигурация LLM	`internal/llm/` (хранение ключей · маскирование · проверка)

Наборы правил хранятся в отдельном git-репозитории agent-reliability-rules (по каталогам {claude_sdk,openai_sdk,google_adk,mcp}) и выбираются во время сканирования, а не встраиваются в бинарный файл. Используются следующие соглашения об именовании: CSDK-NNN для правил Claude Agent SDK (CSDK-0xx — область действия инструментов, CSDK-1xx — область действия агентов и подчинённых агентов), OAI-NNN для правил OpenAI Agents SDK, ADK-NNN для правил Google ADK, MCP-NNN для отдельного набора правил MCP для области действия инструментов.

См. ARCHITECTURE.md § 2 — этапы 3–4: там приведена таблица поставляемых правил. Подробности об обнаружении для каждого SDK см. в COVERAGE.md.

Тестирование

В testdata/corpus/ собран код реальных агентов: демонстрационные примеры Claude SDK, OpenAI Agents SDK и Google ADK, а также тестовый пример для Claude SDK на TypeScript. Это набор реальных примеров, а не контролируемая тестовая выборка, поэтому хорошо написанные агенты не должны срабатывать на большинстве правил — и это ожидаемое поведение. Информация об источниках и лицензиях каждого примера приведена в testdata/corpus/PROVENANCE.md. Корректность срабатывания и отсутствия срабатывания для каждого правила проверяется в internal/rules/policies_test.go; сквозная проверка в internal/scanner/scanner_test.go подтверждает только то, что сканер не падает на реальных входных данных. Целевой набор для оценки качества обнаружения — 20–40 размеченных репозиториев реальных агентов (см. ARCHITECTURE.md § 10). Текущие тесты предназначены для предотвращения регрессий, а не для измерения качества обнаружения.

Конфиденциальность и телеметрия

Trustabl может собирать анонимные данные об использовании: какие SDK проверяются, сколько длится сканирование и какие правила срабатывают. Эти сведения помогают определять направление развития продукта. Исходный код, пути к файлам, названия репозиториев и подробности находок никогда не отправляются. По умолчанию телеметрия отключена; при первом интерактивном сканировании Trustabl предложит выбрать уровень.

В случае паники Trustabl сохраняет очищенный от конфиденциальных данных отчёт о сбое в ~/.config/trustabl/crash-.log. Только в интерактивном терминале программа предложит анонимно отправить отчёт или открыть предварительно заполненную форму GitHub issue — в остальных случаях ничего не передаётся. Автоматической отправки нет: по умолчанию данные не отправляются, а решение об отправке принимается отдельно для каждого сбоя. Отчёт содержит сообщение о панике (с наиболее распространёнными форматами секретов, удалёнными по возможности) и кадры стека вызовов. В нём нет исходного кода, содержимого файлов или значений аргументов.

Доступны три уровня:

Отключено — данные не отправляются (по умолчанию)
Минимальный — только версия CLI и результат сканирования
Полный — анонимная статистика использования

trustabl telemetry off          # disable
trustabl telemetry minimal      # version and outcome only
trustabl telemetry full         # full anonymous usage stats
export TRUSTABL_TELEMETRY=0     # or disable for the current shell session
trustabl telemetry status       # show current level and its source

Полная схема событий — все названия событий и все свойства без изменений — приведена в TELEMETRY.md и на странице trustabl.ai/docs/telemetry. Документация на этой странице поддерживается в соответствии с кодом; устаревшая документация считается дефектом.

Часто задаваемые вопросы

Что такое Agent Reliability Analyzer?

Это детерминированный сканер с открытым исходным кодом от Trustabl. Он выявляет и помогает устранять проблемы надёжности AI-агентов в коде до выхода в production. Поддерживается девять SDK для агентов и семь языков программирования.

Как проверить надёжность AI-агента до выхода в production?

Запустите trustabl scan ./your-agent-repo локально или в CI. Сканер проверяет инструменты, агентов, подчинённых агентов, навыки и MCP-серверы на соответствие правилам надёжности агентов. При находках среднего уровня и выше команда завершает работу с ненулевым кодом возврата, поэтому задание CI завершается ошибкой, если это необходимо.

Заменяет ли он LangSmith, Langfuse, Braintrust или Arize?

Нет. Эти инструменты наблюдают за работой агентов и оценивают их во время выполнения, а Agent Reliability Analyzer выявляет дефекты в коде до его запуска. Используйте их вместе.

Передаёт ли он мой код куда-либо?

Нет. Сканирование выполняется локально и детерминированно: LLM не используется, код не загружается. По умолчанию Trustabl загружает актуальные правила и данные об уязвимостях; параметр --no-rules-update позволяет работать полностью офлайн, используя локальный кэш. Команда trustabl enrich запускается только по желанию и использует ваш собственный ключ LLM. Телеметрия по умолчанию отключена.

Какие фреймворки для агентов поддерживаются?

Поддерживается девять SDK, включая Claude Agent SDK, OpenAI Agents SDK, Google ADK, LangChain / LangGraph, CrewAI, AutoGen / AG2 и Pydantic AI. Полный список см. в COVERAGE.md.

Часть набора инструментов Trustabl с открытым исходным кодом для повышения надёжности агентов

Agent Reliability Analyzer — один из инструментов с открытым исходным кодом, созданных Trustabl для повышения надёжности агентов:

agent-reliability-rules — детерминированные правила обнаружения проблем с надёжностью агентов, которые загружает анализатор
trustabl-action — запуск анализатора как GitHub Action
agent-opentelemetry-rules — специальные правила OpenTelemetry для наблюдаемости агентов
trustabl-aws — анализатор для AWS CodePipeline и CodeCatalyst

Проверки реализуют концепции Agent Reliability Engineering (ARE) — открытой дисциплины, посвящённой созданию надёжных и управляемых AI-агентов. Trustabl связан с автором ARE.

Сообщество

Присоединяйтесь к Discord-сообществу Trustabl, чтобы задавать вопросы, делиться отзывами и следить за развитием проекта.

Лицензия

Apache-2.0. См. файл LICENSE.