Agent Safe GitHub Lab

Сначала изучи источник. Зафиксируй находки. Решение о запуске принимай отдельно.

Практическая учебная лаборатория для людей, работающих с AI-агентами. На инертных примерах разбираем, как внешние инструкции, зависимости и CI могут изменить цель агента или открыть доступ к данным.

Быстрый старт · Упражнения · Модель угроз · English

Осмотр → отчёт → ревью

Шаг	Что происходит
Осмотр	Локальный scanner читает выбранный каталог и ищет опасные признаки
Отчёт	Receipt сохраняет категории, относительные пути, номера строк и digest
Ревью	Человек оценивает находки, пробелы и условия дальнейшего допуска

Обложка показывает приёмную кузни Адептус Механикус: внешний груз исследуют до открытия ворот. Мягкая рисованная подача подчёркивает обучение и внимательность. Об иллюстрации.

Что делает лаборатория

Учебная лаборатория о том, как дать агенту безопасный первый контакт с внешним GitHub-репозиторием, skill, пакетом, архивом или веб-инструкцией.

Она учит не «доверять репозиторию», а собирать ограниченный статический receipt: какие опасные признаки найдены, что ещё неизвестно и почему это не является разрешением на запуск. Лаборатория не скачивает, не клонирует, не устанавливает, не запускает код и не делает сетевых запросов.

Receipt намеренно не включает исходные строки: даже статический фрагмент может содержать секрет, персональные данные или новую инъекцию. Он содержит только категорию, относительный путь, номер строки (если есть) и digest прочитанного контента. CLI возвращает 0 лишь при STATIC_REVIEW_COMPLETE; STOP и REVIEW_REQUIRED возвращают 1 после печати receipt.

Относительный путь тоже может содержать чувствительное имя. Не публикуйте receipt автоматически: сначала проверьте его как отдельный артефакт.

Быстрый старт

Нужен только Python 3.11+ из стандартной библиотеки:

python3 -m unittest discover -s tests -v
python3 -m gate fixtures/clean --json

Затем сравните с подозрительным примером:

python3 -m gate fixtures/second-stage --json

Для этого примера код возврата 1 ожидаем: он сообщает о находках, требующих ревью.

Сканируйте только каталог нужного упражнения. Никогда не выполняйте его файлы: они намеренно содержат подозрительные, но инертные фрагменты текста.

Что студент освоит

• распознавать prompt injection и подмену цели агента;
• замечать вторую стадию: догрузку инструмента, mutable ref и «самообновление»;
• строить цепочку секрет → сеть и не печатать секрет в receipt;
• проверять CI: привилегированные события, широкие permissions и неприбитые SHA;
• видеть lifecycle scripts пакетов как сигнал к отдельному допуску;
• повторно проверять источник, когда меняются commit, URL, зависимости, permissions или инструмент.

Пять практических упражнений

Упражнение	Что разбираем
1. Receipt вместо доверия	Чистый источник и prompt injection; границы статической проверки
2. Вторая стадия и эксфильтрация	Догрузки, mutable refs и цепочка «секрет → сеть»
3. CI и lifecycle	Привилегии workflow и исполнение при установке
4. Повторный допуск	Что пересматривать при изменении источника
5. Скрытые источники	Submodules, LFS, build sources и обфускация

Читать результат

Verdict	Exit code	Как понимать
STATIC_REVIEW_COMPLETE	0	Ограниченный статический осмотр завершён; запуск отдельно
REVIEW_REQUIRED	1	Нужен разбор найденных признаков или неполного покрытия
STOP	1	Найдены признаки, останавливающие дальнейший допуск

Ошибка входных данных CLI возвращает 2. Исходные строки в receipt не копируются.

Границы

Это учебный статический сканер эвристик. Он может ошибаться, не доказывает безопасность, не заменяет изолированное выполнение и не блокирует операции рантайма. Подключение к Claude Code, OpenClaw или Hermes должно отдельно проверять фактический охват, режим блокировки, исключения, rollback и невозможность агента ослабить собственные ограничения.

Digest receipt не является Git provenance: сканер не читает .git, не хеширует обычные permissions и не является защищённой границей для дерева, которое одновременно меняет атакующий. Для допуска нужен зафиксированный upstream commit и повторная проверка неизменяемого snapshot.

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

См. модель угроз, упражнения, источники и правила публикации.

Лицензия

Apache-2.0. Copyright 2026 kostyaP-hub.