____         ____                       ____  _
    / __ \  ___  / __/___   ___   ___  ___  / ___|| | __ _ __      __
   / / / / / _ \/ /_// _ \ / _ \ / __|/ _ \| |    | |/ _` |\ \ /\ / /
  / /_/ / /  __/ __//  __/| | | |\__ \  __/| |___ | | (_| | \ V  V /
 /_____/  \___/_/   \___/ |_| |_||___/\___| \____||_|\__,_|  \_/\_/

DefenseClaw объединяет Python-оператор CLI, Go-промежуточный шлюз и OpenClaw TypeScript-плагин. Вместе они обеспечивают простое правило работы: непроверенные возможности агента сканируются, управляются, регистрируются и блокируются, когда политика считает их небезопасными.

Основные возможности

• Контроль допуска — сканирование навыков, MCP-серверов, плагинов и кода перед запуском.
• Ограничения времени выполнения — проверка промптов, завершений и вызовов инструментов с помощью правил регулярных выражений, политики, опционального LLM-судьи и проверки Cisco AI Defense.
• CodeGuard — встроенные статические проверки на секреты, опасное выполнение, небезопасную десериализацию, слабую криптографию, шаблоны инъекций и рискованный доступ к файлам.
• Поддержка песочницы OpenShell — настройка песочницы Linux с контролем сети, файловой системы, системных вызовов и политик.
• Реестры — импорт внешних каталогов навыков / MCP (корпоративные HTTPS YAML, smithery.ai, skills.sh, git, ClawHub) с защитой от SSRF, решениями на основе сканера и автоматическим продвижением в политику активов. См. docs/REGISTRIES.md.
• Аудит и наблюдаемость — единый граф config-v8 для сбора в корзины, обязательная история SQLite, централизованная редакция и независимые цели JSONL, OTLP, Prometheus, Splunk HEC, Galileo, HTTP, консоль и локальные пункты назначения Grafana/Splunk.
• UX оператора — CLI и TUI для настройки, проверок здоровья, оповещений, списков блокировки/разрешения, результатов сканирования и рабочих процессов политики.

Область применения и ограничения

DefenseClaw — это уровень обеспечения соблюдения правил и сбора доказательств для агентных AI-развертываний. Он повышает безопасность, комбинируя результаты сканирования, проверки во время выполнения, решения политик, контроль песочницы и аудиторские следы, но не доказывает, что взаимодействие агента, навыка, плагина или модели свободно от рисков.

Высокорисковые развертывания должны дополнять DefenseClaw ручной проверкой, минимальными привилегиями, песочницей, CI-шлюзами и мониторингом производства. В режиме наблюдения находки регистрируются без блокировки. В режиме действия настроенные находки HIGH и CRITICAL могут блокировать промпты, вызовы инструментов или допуск компонентов.

Документация

Проектная Markdown-документация централизована в docs/. Локальные README пакетов расположены рядом с пакетами или примерами, которым требуется локальный контекст.

Установка

Предварительные требования

Сборка из исходников (только для разработчиков)

Выберите команду по цели:

Целевые источники и `scripts/install-dev.sh` являются инструментарием для разработки, а не путём обновления. Прямые цели установки отказываются перезаписывать установку, управляемую релизом, или установку, принадлежащую другому рабочему каталогу (checkout). `make all` — это явный рабочий процесс переустановки на машине разработчика: когда установленный CLI уже указывает точно на текущий checkout, он может восстановить состояние исходного кода без маркеров или предыдущего релиза и записывает строгий маркер владения после пересборки. Это может запускать текущие миграции checkout'а в состояние разработчика и не должно использоваться как обновление релиза. Установки, управляемые релизом, должны использовать решатель `scripts/upgrade.sh` или `scripts/upgrade.ps1`, принадлежащий релизу. `make install`, `make dev-install` и `scripts/install-dev.sh` являются низкоуровневой строгой обвязкой для нового или изолированного окружения разработки; они не являются обычной командой повторной разработки.

### Установка с помощью скрипта релиза```bash
VERSION=0.8.6
INSTALL_URL="https://raw.githubusercontent.com/cisco-ai-defense/defenseclaw/${VERSION}/scripts/install.sh"
curl -LsSf "$INSTALL_URL" | VERSION="$VERSION" bash
defenseclaw init --enable-guardrail

Для получения инструкций по конкретной платформе смотрите docs/INSTALL.md.

В родной среде Windows x64 используйте нативный установочный EXE-файл и путь к коннектору только с хуком, описанный в руководстве по Windows. WSL не поддерживается. Codex CLI и Claude Code — единственные сертифицированные коннекторы для Windows.

Быстрый старт```bash

Check the local install and dependencies

defenseclaw doctor

Initialize config, scanner defaults, and guardrail plumbing

defenseclaw init --enable-guardrail

Scan installed agent capabilities

defenseclaw skill scan all defenseclaw mcp list defenseclaw plugin scan extensions/defenseclaw

Start the Go gateway sidecar

defenseclaw-gateway start

Open the operator dashboard

defenseclaw tui

Запустите ограничитель в режиме наблюдения во время настройки:```bash
defenseclaw setup guardrail --mode observe --restart

Переключиться в режим действий, когда политика готова к блокировке:```bash defenseclaw setup guardrail --mode action --restart

Смотрите [docs/QUICKSTART.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/QUICKSTART.md) для полного руководства.

---

## Архитектура

| Компонент | Среда выполнения | Роль |
|-----------|---------|------|
| Python CLI | Python | Команды оператора, оркестрация сканеров, настройка конфигурации, локальные пакеты |
| Gateway sidecar | Go | REST API, WebSocket мост, механизм политик, прокси-ограждения, хранилище аудита, телеметрия |
| OpenClaw plugin | TypeScript | Перехват Fetch, хуки инспекции вызовов инструментов, слэш-команды, интеграция с sidecar |
| Policies | YAML/Rego | Решения о допуске, действия ограждений, поведение песочницы/брандмауэра, профили сканеров |
| Documentation | Markdown/JSON | Централизованная документация, локальные README пакетов и конфигурация DeepWiki |

Шлюз предоставляет локальные REST API для CLI и плагина, подключается к OpenClaw через WebSocket, проверяет LLM-трафик через локальный прокси и записывает решения в долговечное хранилище аудита.```text
Agent runtime -> OpenClaw plugin -> DefenseClaw gateway -> policy + scanners + audit
                                    |
                                    +-> guardrail proxy -> LLM provider
                                    +-> OTLP / Splunk / webhooks / JSONL

Для диаграмм и подробных схем читайте docs/ARCHITECTURE.md.

Сканирование и ограничения

DefenseClaw оборачивает сканеры Cisco AI Defense и локальные политики в единый процесс допуска:

Политики сканеров находятся в policies/scanners/. Наборы правил шлюза — в policies/guardrail/.

Наблюдаемость

DefenseClaw записывает свидетельства применения правил и выполнения в нескольких каналах:

Конфиг v8 сохраняет исходный код кратким, компилируя пропуски в полный действующий план.```yaml config_version: 8 observability: {}

Этот набор по умолчанию собирает все зарегистрированные логи, трейсы и метрики и сохраняет каждый
собранный лог без редактирования в обязательной локальной SQLite. Удаленный экспорт не происходит до тех пор, пока
не будет добавлен пункт назначения. Включенный пункт назначения без параметров `send` или `routes` получает
каждое ведро и каждый сигнал, поддерживаемый его типом, в неотредактированном виде: общий OTLP получает
логи/трейсы/метрики, Splunk HEC получает логи, Prometheus получает метрики, а предустановка Galileo
получает трейсы. Несколько пунктов назначения получают независимые копии.

Просмотрите расширенную политику и неотредактированные ответвления с помощью:```bash
defenseclaw config show --effective --section observability
defenseclaw observability plan

Используйте централизованные профили редактирования none, sensitive, content, strict или пользовательские профили, учитывающие поля, для каждого bucket или назначения. Настройки по умолчанию с полной точностью воспроизведения могут включать запросы, выводы, аргументы/результаты инструментов, доказательства, пути и идентификаторы, поэтому настройте профиль редактирования перед экспортом через границу доверия, которая не должна получать этот контент.

Отредактируйте bucket и политику редактирования в исходном файле, проверьте его до того, как он будет обработан шлюзом, и просмотрите скомпилированный результат, а не копируйте сгенерированный эталон целиком.```bash umask 077 cp "$HOME/.defenseclaw/config.yaml"
"$HOME/.defenseclaw/config.yaml.before-observability-edit" ${EDITOR:-vi} "$HOME/.defenseclaw/config.yaml"

defenseclaw config validate &&
defenseclaw config show --effective --section observability &&
defenseclaw observability plan &&
defenseclaw-gateway restart &&
defenseclaw doctor

Не перезапускайте после неудачной проверки. Восстановите частную резервную копию, исправьте источник и проверьте снова. Глобальный профиль редактирования или профиль корзины также применяется к созданной локальной проекции SQLite. Чтобы сохранить локальную историю с полной точностью, редактируя только удаленную границу доверия, оставьте глобальный/корзинный профиль как `none` и установите `send.redaction_profile` или маршрутный профиль на этом удаленном назначении.

Запустите локальное наблюдение с помощью:```bash
defenseclaw setup local-observability up
defenseclaw-gateway start
defenseclaw setup local-observability status

Пустота панели управления — это не одно состояние: 0 означает, что инструментированный сигнал не содержал соответствующих событий; No data — что для выбранного диапазона и фильтров не существует соответствующих рядов/логов/трейсов; а Not reported — что коннектор/провайдер не предоставил необязательное значение, такое как токены или стоимость. Условные панели, такие как HITL, представления только с ошибками и водопад трейсов до выбора идентификатора трейса, должны показывать No data. Тест назначения проверяет только подключение и не создает обычный трафик панели управления; сгенерируйте новый реальный шаг агента, вызов инструмента, сканирование или подтверждение для проверки соответствующих панелей.

Граф узлов Agent360 — это DAG жизненного цикла на основе Loki: создание сессии является отдельной точкой привязки; один узел Prompt inputs на корень подсчитывает уникальные факты model.request нулевой глубины в диапазоне, а делегирование от родителя к ребенку передает сводки по модели, инструменту, подтверждению, обновлению, результату шага и терминалу для каждого агента. Входные данные подсказок дедуплицируются по шагу, запросу модели, запросу, операции, а затем идентификатору события; упорядоченные/сырые представления сохраняют отдельные начальные и последующие записи. Точки привязки сессии и порождения могут быть восстановлены за предыдущие 24 часа, чтобы граничные окна оставались отображаемыми; восстановленное порождение сохраняется только если у этого дочернего элемента есть активность, подходящая для графа, в выбранном диапазоне. Повторные вызовы модели группируются по владельцу-агенту, провайдеру и модели. Повторные вызовы инструментов группируются по владельцу-агенту в Bash, MCP, Skills, Collaboration, File edits, Web/browser, Visual или Task control; нераспознанный инструмент сохраняет свое заявленное имя. Точные запросы collaboration.send_message исключаются из общего семейства Collaboration, поэтому они отображаются только как группы сообщений; другие инструменты совместной работы остаются в этом семействе. Записи запросов включаются, даже если нет соответствующего терминального события. Их сгруппированная сумма — это количество запросов, а не утверждение, что каждый запрос все еще ожидает выполнения; терминальный статус остается доступным в связанных сырых записях. Глубина 0 является корнем, а рекурсивные дочерние элементы могут быть отражены до глубины 64; щелчок по детализации показывает, была ли каждая линия происхождения сообщена коннектором или выведена DefenseClaw. Щелчки по узлам раскрывают точные количества и стабильную идентичность агента/корня/родителя с фильтрованными ссылками на сырые OTEL события, стоящие за каждой группой. Необязательные поля сессии текущей/корневой/родительской остаются на поверхностях жизненного цикла, сессии, упорядоченных и сырых; они не являются ключами группировки узлов агента, поэтому отсутствие или опоздание метаданных сессии не может разделить суммарные показатели одного агента.

Панели управления снова не редактируют, не маскируют и не скрывают поля. DefenseClaw применяет централизованное редактирование v8 перед каноническим экспортом OTEL; Grafana показывает или ссылается на каждое поле, фактически присутствующее в этой проекции, включая содержимое, когда производитель экспортировал его. Поле, удаленное или преобразованное до экспорта, не может быть восстановлено локальным стеком. Ребра обновлений поступают только из фактических записей инструмента collaboration.send_message. Для каждого отправителя цели /root и /root/* сворачиваются в один узел Messages to root, чей идентификатор целевого агента разрешается в экспортированный корень. Точные пути корневых задач и вызовы остаются в упорядоченных/сырых детализациях. Некорневые цели остаются явно сгруппированными по точному пути задачи и не придумываются как непрозрачные объединения идентификаторов агентов, когда коннектор не сообщил это сопоставление. События общей совместимости никогда не переименовываются в обновления.

Необязательные назначения владеют независимыми ограниченными очередями. По умолчанию 2 048 записей и 64 МиБ на очередь; пакетные отправки по умолчанию — 512 записей, 8 МиБ и 5 секунд (1 секунда для пропущенной задержки Galileo preset). Переполнение очереди отбрасывает самую новую попытку постановки в очередь без вытеснения более старой работы FIFO и без влияния на обязательные SQLite и смежные назначения. Точные поля, границы и различия адаптеров указаны в docs/OBSERVABILITY.md.

Добавьте Galileo Cloud или самостоятельно размещенный Galileo без замены локального маршрута:```bash export GALILEO_API_KEY='...' defenseclaw setup galileo --project defenseclaw --logstream production defenseclaw setup galileo test

См. [docs/OBSERVABILITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/OBSERVABILITY.md), руководство по [Galileo](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs-site/content/docs/observability/galileo.mdx) и [карту владения схемами](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/schemas/README.md). Информация по настройке Splunk содержится в [docs/SPLUNK_APP.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/SPLUNK_APP.md).

Каждая поддерживаемая существующая установка POSIX, включая ту, что уже на версии `0.8.4`, пересекает жёсткую границу `0.8.5` с помощью аутентифицированного актива целевого релиза `defenseclaw-upgrade.sh` в режиме последней версии, без переопределения версии. Неизменяемый встроенный парсер версии `0.8.4` не может обработать достоверный целевой манифест, матрица моста Windows которого пуста. Не выполняйте никаких устаревших подсказок сырой сети, выводимых замороженным встроенным CLI. Резолвер, принадлежащий релизу, выполняет `source → 0.8.4 bridge → fresh 0.8.4 controller → 0.8.5 hard cut` как одну транзакцию. Миграция делает резервную копию и атомарно преобразует конфигурацию, сохраняет суженное поведение маршрутизации/редактирования и совместимость root/subagent Agent360, обновляет принадлежащие локальные панели мониторинга без сброса томов и никогда не требует отдельной команды apply. См. [CLI Reference — upgrade](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CLI.md#upgrade) для начальной загрузки аутентифицированного резолвера.

Для Splunk Observability Cloud используйте набор панелей мониторинга по адресу [bundles/splunk_o11y_dashboards/README.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/bundles/splunk_o11y_dashboards/README.md):```bash
defenseclaw setup splunk dashboards apply \
  --api-url <api-endpoint> \
  --o11y-api-token <api-access-token> \
  --with-detectors \
  --enable-detectors \
  --yes

Разработка```bash

Build all components

make build

Run primary test suites

make test

Run lint checks

make lint

Целенаправленные руководства по тестированию и разработке находятся в [docs/TESTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/TESTING.md) и [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md).

---

## Участие в разработке

Вклады приветствуются. Начните с [CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/CONTRIBUTING.md), [docs/CONTRIBUTING.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/docs/CONTRIBUTING.md) и целевых документов для области, которую вы изменяете.

## Безопасность

Пожалуйста, сообщайте об уязвимостях через процесс, описанный в [SECURITY.md](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/SECURITY.md).

## Лицензия

Apache 2.0 – смотрите [LICENSE](https://github.com/cisco-ai-defense/defenseclaw/blob/HEAD/LICENSE).

Copyright 2026 Cisco Systems, Inc. и её аффилированные лица.