agentsh

Примечание для macOS: Нативная поддержка macOS через ESF (Endpoint Security Framework) + NE (Network Extension) находится в статусе Alpha. Она работает по всей цепочке — события файлов, процессов и сети проходят через системное расширение в policy-движок Go — но ожидайте шероховатостей и ломающих изменений между релизами. Для промышленного использования сегодня рекомендуем Linux.

Примечание для Windows: Мы работаем над получением подписи для minifilter-драйверов. До этого момента для промышленного использования полностью поддерживается только режим Windows WSL2.

Безопасный шлюз выполнения с применением политик для ИИ-агентов.

agentsh находится под вашим агентом/инструментарием — перехватывает действия с файлами, сетью, процессами и сигналами (включая деревья подпроцессов), применяет определённую вами политику и генерирует структурированные события аудита.

Примечание о платформах: Linux обеспечивает полное применение политик (оценка безопасности 100%). macOS ESF+NE (оценка 90%) находится в статусе Alpha — функционален, но не готов к промышленному использованию. Windows WSL2 обеспечивает полное применение политик, эквивалентное Linux (оценка 100%); нативная Windows через minifilter-драйвер + AppContainer (оценка 85%) ожидает подписания драйвера. Подробности см. в Матрице сравнения платформ.

Что такое agentsh?

Готовый shell/exec endpoint, который превращает каждую команду (и её подпроцессы) в события аудита.
Policy-движок для каждой операции: allow, deny, approve (одобрение человеком), soft_delete или redirect.
Полная видимость ввода/вывода:
- открытие/чтение/запись/удаление файлов
- сетевые подключения + DNS
- запуск/завершение процессов
- активность PTY
- запросы к LLM API с DLP и отслеживанием использования
- трафик к базам данных семейства Postgres через объявленные db_services
- отправка/блокировка сигналов (применяется на Linux, аудит на macOS/Windows)
- запросы к базам данных через встроенный PostgreSQL-прокси — классификация и политика для каждого оператора
- маршрутизация исходящих HTTP API-вызовов через объявленные сервисы (http_services) с правилами по методам и путям, гейтингом одобрений и принудительным контролем хостов в режиме fail-closed
Два режима вывода:
- вывод в терминал, удобный для человека
- компактные JSON-ответы для агентов/инструментов

Зачем нужен agentsh?

В рабочих процессах агентов рано или поздно выполняется произвольный код (pip install, make test, python script.py). Традиционные механизмы контроля «запросить одобрение перед запуском команды» останавливаются на границе инструмента и не видят, что происходит внутри этой команды.

agentsh применяет политику в рантайме, поэтому скрытая работа, выполняемая подпроцессами, по-прежнему управляется, логируется и (при необходимости) требует одобрения.

Осмысленные блокировки: deny → redirect (суперспособность «направления»)

Большинство систем могут заблокировать действие. agentsh также может перенаправить его.

Это означает, что когда агент пробует неверный подход (или грубые обходные пути), политика может направить его на правильный путь, подменяя команду и возвращая подсказку — удерживая агента на проторенной дороге и сокращая количество бесполезных повторных попыток.

Пример: перенаправление curl на аудируемую обёртку```yaml command_rules:

name: redirect-curl commands: [curl, wget] decision: redirect message: "Downloads routed through audited fetch" redirect_to: command: agentsh-fetch args: ["--audit"]

**Пример: перенаправление записей за пределы рабочей области обратно внутрь**```yaml
file_rules:
  - name: redirect-outside-writes
    paths: ["/home/**", "/tmp/**"]
    operations: [write, create]
    decision: redirect
    redirect_to: "/workspace/.scratch"
    message: "Writes outside workspace redirected to /workspace/.scratch"

Агент видит успешную операцию (не ошибку), но вы управляете тем, куда на самом деле всё попадает.

Контейнеры + agentsh: вместе лучше

Контейнеры изолируют поверхность хоста; agentsh добавляет видимость и политику во время выполнения внутри контейнера.

Пооперационный аудит (файлы, сеть, команды) показывает, что происходило во время установок/сборок/тестов.
Одобрения и правила действуют в долгоживущих оболочках и деревьях подпроцессов, а не только в первой команде.
Управление на уровне путей для смонтированных рабочих областей/кэшей/учётных данных; контейнеры изначально не дают такой детализации.
Одинаковое поведение на хосте и в контейнерах, поэтому CI и локальная разработка видят одинаковые результаты применения политик.

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

Установка

macOS (Homebrew)```bash brew tap canyonroad/tap brew install --cask agentsh

Это устанавливает пакет приложения AgentSH с системным расширением ESF+NE. После установки вам будет предложено одобрить системное расширение в **Системные настройки > Основные > Объекты входа и расширения**.

**Linux (из релиза GitHub)**

Загрузите `.deb`, `.rpm` или `.apk` для вашей платформы со [страницы релизов](https://github.com/erans/agentsh/releases).```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

Из исходников (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

**Из исходников (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

См. Руководство по сборке macOS для получения подробных инструкций по сборке на macOS.

Запуск локально```bash

Start the server (optional if using autostart)

./bin/agentsh server --config configs/server-config.yaml

Create a session and run a command (shell output)

SID=$(./bin/agentsh session create --workspace . --json | jq -r .id) ./bin/agentsh exec "$SID" -- ls -la

Structured output for agents

./bin/agentsh exec --output json --events summary "$SID" -- curl https://example.com

---
### Проверка того, что применяется

`agentsh detect` проверяет хост и сообщает, какие примитивы принуждения реально доступны — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — сгруппированные в оценки защиты по доменам, а также выбранный режим безопасности. На ограниченных хостах (Daytona, E2B, Firecracker-class), где слушатель seccomp user-notify установить невозможно, он сообщает режим, который будет *фактически* применяться, а не то, что ядро просто поддерживает.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

См. Режимы безопасности — матрицу режимов и параметры настройки.

Скажите агенту, чтобы он использовал это (фрагмент AGENTS.md / CLAUDE.md)```md

Shell access

Run commands via agentsh, not directly in bash/zsh.
Use: agentsh exec $SID -- <your-command-here>
For structured output: agentsh exec --output json --events summary $SID -- <your-command-here>
Get session ID first: SID=$(agentsh session create --workspace . --json | jq -r .id)

---

### Автозапуск (без ручного запуска демона)

Вам **не** нужно запускать `agentsh server` самостоятельно.

* Первый `agentsh exec` (или любой `/bin/sh`/`/bin/bash` с шимом) автоматически запустит локальный сервер, используя `configs/server-config.yaml` (или `AGENTSH_CONFIG`, если задан).
* Этот сервер поддерживает FUSE-слой и механизм политик активными на протяжении всей сессии; последующие команды переиспользуют его.
* Установите `AGENTSH_NO_AUTO=1`, если хотите управлять жизненным циклом сервера вручную.

---

## Использование в Docker (с шимом оболочки)

Смотрите `Dockerfile.example` для минимального образа на базе Debian.

Внутри образа установите релизный пакет (или скопируйте свою сборку), затем активируйте шим:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

Направьте шим на ваш сервер (сайдкар или хост):```dockerfile ENV AGENTSH_SERVER=http://127.0.0.1:18080

Теперь любой `/bin/sh -c ...` или `/bin/bash -lc ...` в контейнере направляется через agentsh.

### Принудительное применение в неинтерактивном режиме

По умолчанию шим обходит политику, когда stdin не является TTY (сохраняя двоичные данные для конвейерных команд). На платформах, где команды всегда неинтерактивны, но всё равно требуют контроля (например, exe.dev, sandbox APIs), добавьте `--force`:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --force \
  --i-understand-this-modifies-the-host

Это записывает /etc/agentsh/shim.conf с force=true, который shim считывает при запуске. Файл конфигурации работает независимо от того, как запускается оболочка (в отличие от переменных окружения или скриптов профиля). AGENTSH_SHIM_FORCE=1 в окружении процесса достигает того же эффекта для каждого процесса.

Рекомендуемый подход: запускайте agentsh как sidecar (или PID 1) в том же поде/сервисе и используйте общий том рабочей области; shim гарантирует, что каждый переход оболочки остаётся в рамках политики.

Модель политики

Решения

allow
deny
approve (подтверждение человеком)
redirect (подмена команды)
audit (разрешить + записать в журнал)
soft_delete (карантин для удалений с восстановлением)

Области действия

операции с файлами
команды
переменные окружения
сеть (DNS/подключение)
база данных (SQL-запросы через PostgreSQL-прокси)
настройки PTY/сеанса
объявленные HTTP-сервисы

Оценка

выигрывает первое подходящее правило

Правила находятся в именованной политике; сессии выбирают политику.

Значения по умолчанию:

пример конфигурации: configs/server-config.yaml
политика по умолчанию: configs/policies/default.yaml
переопределение через env: установите AGENTSH_POLICY_NAME в разрешённое имя политики (без суффикса). Если не задано/недействительно/запрещено, используется политика по умолчанию.
политика env: настройте policies.env_policy (allow/deny, max_bytes, max_keys, block_iteration) и покомандные переопределения env_* в файлах политик. Пустой список разрешённого по умолчанию даёт минимальный PATH/LANG/TERM/HOME со встроенным списком запрещённых секретов; установите block_iteration, чтобы скрыть перечисление env (требуется env shim).
список разрешённых: настройте policies.allowed в config.yml; пустое значение означает, что разрешена только политика по умолчанию.
необязательная целостность: укажите policies.manifest_path на SHA256-манифест для проверки файлов политик при загрузке.

Краткая справка по политике окружения

По умолчанию: Без env_allow agentsh создаёт минимальное окружение (PATH/LANG/TERM/HOME) и удаляет встроенные секретные ключи.
Переопределения: Покомандные env_allow/env_deny плюс env_max_keys/env_max_bytes ограничивают и фильтруют окружение дочернего процесса при исполнении.
Блокировка перечисления: env_block_iteration: true (глобально или для отдельного правила) скрывает перечисление окружения; укажите policies.env_shim_path на libenvshim.so, чтобы agentsh внедрял LD_PRELOAD + AGENTSH_ENV_BLOCK_ITERATION=1.
Лимиты: Ошибки при превышении лимитов; построитель окружения применяется перед exec для каждой команды.
env_inject: Доверенные оператором переменные окружения внедряются во все команды, минуя фильтрацию политик. Основное применение: BASH_ENV для отключения встроенных функций оболочки, обходящих seccomp. Настройте в (глобально) или на уровне политики (переопределяет глобальную).

Примеры правил (сокращено)```yaml

version: 1 name: default

file_rules:

name: allow-workspace paths: ["/workspace", "/workspace/**"] operations: [read, open, stat, list, write, create, mkdir, chmod, rename] decision: allow
name: approve-workspace-delete paths: ["/workspace", "/workspace/**"] operations: [delete, rmdir] decision: approve message: "Delete {{.Path}}?" timeout: 5m
name: deny-ssh-keys paths: ["/home//.ssh/", "/root/.ssh/**"] operations: ["*"] decision: deny

network_rules:

name: allow-api domains: ["api.example.com"] ports: [443] decision: allow

command_rules:

name: block-dangerous commands: ["rm", "shutdown", "reboot"] decision: deny

---

### Использование политики```bash
# Start the server with your policy
./bin/agentsh server --config configs/server-config.yaml

# Create a session pinned to a policy
SID=$(./bin/agentsh session create --workspace /workspace --policy default --json | jq -r .id)

# Exec commands; responses include decision + guidance when blocked/approved
./bin/agentsh exec "$SID" -- rm -rf /workspace/tmp

Аутентификация

agentsh поддерживает несколько методов аутентификации:

Тип	Сценарий использования
`api_key`	Простые развертывания со статическими ключами
`oidc`	Корпоративный SSO (Okta, Azure AD и т. д.)
`hybrid`	Принимаются оба метода

Режимы утверждения для проверки с участием человека (human-in-the-loop):

local_tty — Запрос в терминале (по умолчанию)
totp — Коды из приложения-аутентификатора
webauthn — Аппаратные ключи безопасности (YubiKey)
api — Удалённое утверждение через REST

Подробности настройки см. в SECURITY.md.

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

Белый список инструментов: управляйте тем, какие инструменты MCP могут вызываться, с помощью политик allowlist/denylist
Фиксация версий: обнаружение изменений определений инструментов (защита от rug pull) с настраиваемыми реакциями
Обнаружение межсерверных действий: блокировка сценариев эксфильтрации данных (чтение с Сервера A → отправка через Сервер B)
Ограничение частоты запросов: ограничение частоты по алгоритму token bucket для MCP-серверов и сетевых доменов

Полные параметры конфигурации см. в SECURITY.md или запустите демо защиты MCP, чтобы увидеть эти механизмы обнаружения в действии.

60-секундное демо

Самый быстрый способ «освоиться» — запустить что-то, что порождает дочерние процессы и обращается к файловой системе/сети.```bash

1) Create a session in your repo/workspace

SID=$(agentsh session create --workspace . --json | jq -r .id)

2) Run something simple (human-friendly output)

agentsh exec "$SID" -- uname -a

→ prints system info, just like normal

3) Run something that hits the network (JSON output + event summary)

agentsh exec --output json --events summary "$SID" -- curl -s https://example.com

→ JSON response includes: exit_code, stdout, and events[] showing dns_query + net_connect

4) Trigger a policy decision - try to delete something

agentsh exec "$SID" -- rm -rf ./tmp

→ With default policy: prompts for approval or denies based on your rules

5) See what happened (structured audit trail)

agentsh exec --output json --events all "$SID" -- ls

→ events[] shows every file operation, even from subprocesses

**Что вы увидите в JSON-выводе:**
- `exit_code`: статус выхода команды
- `stdout` / `stderr`: захваченный вывод
- `events[]`: каждая операция с файлами/сетью/процессами с решениями политик
- `policy.decision`: `allow`, `deny`, `approve` или `redirect`

Совет: держите открытым терминал с `--output json` при тестировании политик — так сразу видно, что затрагивается.

---

### Отчёты о сеансах

Создавайте markdown-отчёты, обобщающие активность сеанса:```bash
# Quick summary
agentsh report latest --level=summary

# Detailed investigation
agentsh report <session-id> --level=detailed --output=report.md

Отчеты включают:

Сводка решений (разрешено, заблокировано, перенаправлено)
Автоматическое обнаружение находок (нарушения, аномалии)
Разбивка активности по категориям
Полная временная шкала событий (подробный режим)

См. Руководство по интеграции CI/CD для примеров пайплайнов.

Контрольные точки рабочей области

Создавайте снимки состояния рабочей области для восстановления после разрушительных операций:```bash

Create a checkpoint before risky operations

agentsh checkpoint create --session $SID --workspace /workspace --reason "before cleanup"

List checkpoints for a session

agentsh checkpoint list --session $SID

Show what changed since a checkpoint

agentsh checkpoint show --session $SID --workspace /workspace --diff

Preview what rollback would restore (dry-run)

agentsh checkpoint rollback --session $SID --workspace /workspace --dry-run

Restore workspace to checkpoint state

agentsh checkpoint rollback --session $SID --workspace /workspace

Clean up old checkpoints

agentsh checkpoint purge --session $SID --older-than 24h --keep 5

**Auto-checkpoint:** Когда эта функция включена, agentsh автоматически создаёт контрольные точки перед рискованными командами (`rm`, `mv`, `git reset`, `git checkout` и т.д.). Настраивается в `sessions.checkpoints.auto_checkpoint`.

Полные параметры конфигурации см. в [SECURITY.md](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#checkpoint-and-rollback).

---

### LLM-прокси и DLP

agentsh включает встроенный прокси, который перехватывает все запросы к LLM API от агентов:```bash
# Check proxy status for a session
agentsh proxy status <session-id>

# View LLM-specific events
agentsh session logs <session-id> --type=llm

Возможности:

Автоматическая маршрутизация: Устанавливает ANTHROPIC_BASE_URL и OPENAI_BASE_URL, чтобы SDK агентов направляли трафик через прокси
Пользовательские провайдеры: Маршрутизация через LiteLLM, Azure OpenAI, vLLM или корпоративные шлюзы
DLP-редактирование: PII (адреса электронной почты, номера телефонов, API-ключи и т. д.) редактируется до отправки LLM-провайдерам
Пользовательские шаблоны: Определение специфических для организации шаблонов конфиденциальных данных
Отслеживание использования: Подсчёт количества токенов и их логирование для распределения затрат
Журнал аудита: Все запросы/ответы логируются в сессионное хранилище

Конфигурация провайдера:```yaml proxy: mode: embedded providers: anthropic: https://api.anthropic.com # Default Anthropic API openai: https://api.openai.com # Default OpenAI API

# Or use alternative providers:
# openai: http://localhost:8000         # LiteLLM / vLLM
# openai: https://your-resource.openai.azure.com  # Azure OpenAI
# anthropic: https://llm.corp.example.com         # Corporate gateway

**Конфигурация DLP:**```yaml
dlp:
  mode: redact
  patterns:
    email: true
    api_keys: true
  custom_patterns:
    - name: customer_id
      display: identifier
      regex: "CUST-[0-9]{8}"

См. Документацию LLM Proxy для полных параметров конфигурации.

Тот же прокси также обслуживает объявленные записи http_services — именованные API-апстримы с правилами для каждого метода и каждого пути. Подробнее см. Объявленные HTTP-сервисы и Поваренную книгу HTTP-сервисов.

Контроль доступа к базе данных (пока только Postgres)

agentsh может применять политики к объявленным сервисам баз данных через db_services, database_connection_rules и database_rules. Текущая реализация поддерживает только семейство Postgres: целевой СУБД является PostgreSQL, Aurora Postgres использует тот же путь, а Redshift/CockroachDB рассматриваются как совместимые с Postgres диалекты с бета-поддержкой. MySQL, MongoDB, Snowflake, BigQuery, Databricks, ClickHouse, MSSQL, Cassandra, Redis и Oracle находятся в дорожной карте, но не поддерживаются в текущей версии.

Текущая поддержка Postgres включает:

Решения о подключении: разрешить/запретить/одобрить/аудит.
Классификация операторов для wire-протокола PostgreSQL v3, включая Simple Query, Extended Query, SQL-подготовленные операторы, COPY, запрет FunctionCall, состояние транзакции и сопоставление CancelRequest.
Строгое покрытие политиками на уровне объектов с приоритетом deny.
Селекторы отношений/функций на основе системного каталога для политик разрешённых объектов.
Безопасный рантайм-redirect для замены отношений Postgres только для чтения.
Обнаружение обхода и E2E-покрытие с реальным Postgres в Docker в CI.

Среда выполнения Postgres-прокси сегодня — это код, работающий только в Linux внутри процесса. Используйте нативный Linux, WSL2 или виртуальную машину Linux для применения политик к базе данных.

См. Контроль доступа к базе данных и Документацию по политикам.

Генерация политик

Создание ограничительных политик на основе наблюдаемого поведения сеансов (рабочий процесс «profile-then-lock»):```bash

Generate policy from latest session

agentsh policy generate latest --output=ci-policy.yaml

Generate with custom name and threshold

agentsh policy generate abc123 --name=production-build --threshold=10

Quick preview to stdout

agentsh policy generate latest

Сгенерированная политика:
- Разрешает только операции, наблюдавшиеся в ходе сеанса
- Группирует пути в glob-шаблоны, когда в одном каталоге много файлов
- Сворачивает поддомены в подстановочные знаки (например, `*.github.com`)
- Помечает опасные команды (curl, wget, rm) с шаблонами аргументов
- Включает заблокированные операции как закомментированные правила для проверки

**Варианты использования:**
- **Изоляция CI/CD**: профилируйте сборку/тестовый прогон и ограничивайте будущие запуски этим поведением
- **Песочница для агентов**: позвольте ИИ-агенту выполнить задачу, сгенерируйте политику для будущих запусков
- **Профилирование контейнеров**: профилируйте рабочую нагрузку, сгенерируйте минимальную политику для продакшена

---

## Доступ к базе данных (PostgreSQL)

agentsh включает встроенный **прокси PostgreSQL**, который делает доступ к базе данных агент-ориентированным и управляемым политикой. Он использует сетевой протокол Postgres, классифицирует каждый оператор в список *эффектов* (чтения, записи, DDL, DCL, управление транзакциями/сеансами, массовое `COPY`/экспорт, …) и оценивает каждый эффект по `database_rules` перед пересылкой вышестоящему серверу — так что `UPDATE`, `DROP` или `DELETE` без ограничения области действия регулируются так же, как запись файла или сетевое подключение.

- **Поэффектная многобъектная оценка** — правила работают как «собрать все» / **«любой запрет побеждает»** (решает наиболее ограничивающий глагол), а не первое совпадение.
- **Решения:** `allow`, `deny`, `approve` (одобрение человеком), `audit` и `redirect` на уровне операторов.
- **Ограничитель `require_where`** — отклоняет `UPDATE`/`DELETE` верхнего уровня без предложения `WHERE`.
- **Правила уровня соединения** (`database_connection_rules`) определяют, какие сеансы могут получить доступ к каким объявленным `db_service`.
- **События аудита аутентификации и операторов** для каждого соединения и запроса; логирование текста операторов настраивается (`policies.db.log_statements: none | parameters_redacted | full`).

Фаза 1 охватывает сетевой протокол PostgreSQL v3 (диалекты: `postgres`, `aurora_postgres`; `redshift` / `cockroachdb` в бете). Репликация и соединения, зашифрованные через GSSAPI, по умолчанию отклоняются.```yaml
database_rules:
  # normal reads + updates on the declared service
  - name: app-read-and-update
    db_service: appdb
    operations: [READ, UPDATE]
    decision: allow

  # allow UPDATE/DELETE only when scoped by a WHERE clause
  - name: app-guard-unscoped-dml
    db_service: appdb
    operations: [UPDATE, DELETE]
    require_where: true
    decision: allow

  # block schema/DDL mutations; terminate the transaction on violation
  - name: app-deny-ddl
    db_service: appdb
    operations: [CREATE, DROP, ALTER, EXPORT]
    decision: deny
    deny_mode_in_tx: terminate
    message: "appdb is read+update only. Requested: {{.Operation}}"

См. спецификацию контроля доступа к базе данных для полной таксономии операций, модели эффектов, правил подключения и модели угроз неизбежности.

Сетевое перенаправление

agentsh может прозрачно перенаправлять DNS- и TCP-соединения, что позволяет, например, направлять вызовы API через корпоративные прокси или переключать поставщиков ИИ без изменения кода.

Перенаправление DNS

Перехватывайте разрешение DNS и возвращайте настроенные IP-адреса:```yaml dns_redirect:

match: "api.anthropic.com" redirect_ip: "10.0.0.50" visibility: audit_only on_failure: fail_closed
match: ".*\.openai\.com" # Regex pattern redirect_ip: "10.0.0.51" visibility: warn

### Перенаправление подключений

Перенаправляет TCP-соединения на разные адреса назначения с необязательной обработкой TLS:```yaml
connect_redirect:
  - match: "api.anthropic.com:443"
    redirect_to: "vertex-proxy.internal:8443"
    tls_mode: passthrough          # Forward encrypted traffic unchanged
    visibility: silent

  - match: "api.openai.com:443"
    redirect_to: "azure-proxy.internal:443"
    tls_mode: rewrite_sni          # Modify SNI in TLS ClientHello
    rewrite_sni: "azure-openai.example.com"
    visibility: audit_only

Options

Поддержка платформ

Варианты использования

Маршрутизация API-шлюза: Направлять вызовы Anthropic/OpenAI через корпоративный LLM-шлюз
Смена провайдера: Перенаправлять Claude API на GCP Vertex AI или Azure OpenAI
Тестирование: Перенаправлять продакшн API на mock-серверы
Соответствие требованиям: Принудительно пропускать весь LLM-трафик через прокси аудита

Фильтрация сигналов

agentsh перехватывает сигналы (kill, SIGTERM и т.д.), отправляемые между процессами, обеспечивая управление на основе политик над тем, какие сигналы могут достигать каких целей.

Поддержка платформ

Пример правил сигналов```yaml

signal_rules:

Allow signals to self and children

name: allow-self signals: ["@all"] target: type: self decision: allow
name: allow-children signals: ["@all"] target: type: children decision: allow

Redirect SIGKILL to graceful SIGTERM

name: graceful-kill signals: ["SIGKILL"] target: type: children decision: redirect redirect_to: SIGTERM

Block fatal signals to external processes

name: deny-external-fatal signals: ["@fatal"] target: type: external decision: deny

### Signal Groups

- `@all` - All signals (1-31)
- `@fatal` - SIGKILL, SIGTERM, SIGQUIT, SIGABRT
- `@job` - SIGSTOP, SIGCONT, SIGTSTP, SIGTTIN, SIGTTOU
- `@reload` - SIGHUP, SIGUSR1, SIGUSR2

### Target Types

- `self` - Process signaling itself
- `children` - Direct child processes
- `descendants` - All descendant processes
- `session` - Any process in the agentsh session
- `external` - PIDs outside the session
- `system` - PID 1 and kernel threads

See [Policy Documentation](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#signal-rules) for full configuration options.

---

## macOS File I/O Monitoring

On macOS, agentsh monitors file I/O using the Endpoint Security Framework (ESF), subscribing to both AUTH and NOTIFY events. Tracked operations include file open, create, delete, rename, write (detected via close-modified), and on macOS 26+, chmod and chown via attribute change events. Every file event is attributed to the originating session and command through PID-based resolution, providing full audit trails across subprocess trees.

ESF provides kernel-level allow/deny enforcement but does not support transparent file interception like Linux FUSE. Policy actions that require interception -- such as `redirect` (path rewriting) and `soft_delete` (quarantine) -- are implemented as deny + guidance: the operation is blocked at the ESF level and the agent receives instructions to retry with the correct path or to acknowledge that the file is protected. See the [macOS ESF+NE architecture doc](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) for event stream details and the [policy documentation](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#file-rule-actions-on-macos-esf) for per-action behavior.

---

## Starter policy packs

You already have a default policy (`configs/policies/default.yaml`). These opinionated packs are available as separate files so teams can pick one:

* **[`policies/dev-safe.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/dev-safe.yaml)**: safe for local development
  * allow workspace read/write
  * approve deletes in workspace
  * deny `~/.ssh/**`, `/root/.ssh/**`
  * restrict network to allowlisted domains/ports

* **[`policies/ci-strict.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/ci-strict.yaml)**: safe for CI runners
  * deny anything outside workspace
  * deny outbound network except artifact registries
  * deny interactive shells unless explicitly allowed
  * audit everything (summary events)

* **[`policies/agent-sandbox.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/agent-sandbox.yaml)**: "agent runs unknown code" mode
  * default deny + explicit allowlist
  * approve any credential/path access
  * redirect network tool usage to internal proxies/mirrors
  * soft-delete destructive operations for easy recovery

---

## AI Assistant Integration Examples

Ready-to-use snippets for configuring AI coding assistants to use agentsh:

* **[Claude Code](https://github.com/canyonroad/agentsh/blob/HEAD/examples/claude/)** - CLAUDE.md snippet for Claude Code integration
* **[Cursor](https://github.com/canyonroad/agentsh/blob/HEAD/examples/cursor/)** - Cursor rules for agentsh integration
* **[AGENTS.md](https://github.com/canyonroad/agentsh/blob/HEAD/examples/agents/)** - Generic AGENTS.md snippet (works with multiple AI tools)

> **Note:** These examples are for local development scenarios where running the AI agent inside a container isn't practical. For production or CI/CD environments, prefer running agents in containers with the shell shim installed—see [Use in Docker](#use-in-docker-with-the-shell-shim).

---

## References

* **MCP Protection Demo:** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - live demo of cross-server exfiltration detection, rug pull blocking, and policy generation
* **Security & threat model:** [`SECURITY.md`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md) - what agentsh protects against, known limitations, operator checklist
* **External KMS:** [`SECURITY.md#external-kms-integration`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#external-kms-integration) - AWS KMS, Azure Key Vault, HashiCorp Vault, GCP Cloud KMS for audit integrity keys
* Config template: [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml)
* Default policy: [`configs/policies/default.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/default.yaml)
* Example Dockerfile (with shim): [`Dockerfile.example`](https://github.com/canyonroad/agentsh/blob/HEAD/Dockerfile.example)
* **Policy documentation:** [`docs/operations/policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md) - policy variables, signal rules, network redirect
* **Database access control:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - Postgres-only database enforcement scope, policy semantics, redirect behavior, and roadmap
* **Command policies cookbook:** [`docs/cookbook/command-policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/command-policies.md) - how to allow a new binary, when to use `wrap` instead of `exec`, and how to debug a denial
* **HTTP services cookbook:** [`docs/cookbook/http-services.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/http-services.md) - recipes for routing outbound HTTP API calls through declared services with rules and approval gating
* **Sandbox SDK integrations cookbook:** [`docs/cookbook/sandbox-sdk-integrations.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/sandbox-sdk-integrations.md) - `shim_install` config for Tensorlake / E2B / Modal / Daytona where commands run as siblings of the agentsh server
* **Policy authoring skills:** [`skills/`](https://github.com/canyonroad/agentsh/blob/HEAD/skills/) - AI-assistant skills for creating and editing policies in Claude Code, NanoClaw, etc.
* **Platform comparison:** [`docs/platform-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/platform-comparison.md) - feature support, security scores, performance by platform
* **Bubblewrap vs agentsh:** [`docs/bubblewrap-vs-agentsh-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/bubblewrap-vs-agentsh-comparison.md) - comparison with Bubblewrap for Linux container sandboxing
* **Database access control:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - PostgreSQL proxy taxonomy, effects model, `database_rules`, connection rules, threat model
* **Security modes & `detect`:** [`docs/security-modes.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/security-modes.md) - enforcement modes, protection score, and what `agentsh detect` reports
* **seccomp:** [`docs/seccomp.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/seccomp.md) - syscall filtering, execve interception, and socket-family blocking
* **ptrace mode:** [`docs/ptrace-support.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ptrace-support.md) - PTRACE_SEIZE enforcement for restricted containers (`attach_mode`, seccomp prefilter)
* **eBPF:** [`docs/ebpf.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ebpf.md) - eBPF network tracing & policy enforcement
* **LLM Proxy & DLP:** [`docs/llm-proxy.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/llm-proxy.md) - embedded proxy configuration, DLP patterns, usage tracking
* **macOS build guide:** [`docs/macos-build.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-build.md) - ESF+NE build instructions
* **macOS ESF+NE architecture:** [`docs/macos-esf-ne-architecture.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) - System Extension, XPC, and deployment details
* **macOS XPC sandbox:** [`docs/macos-xpc-sandbox.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-xpc-sandbox.md) - XPC/Mach IPC control for sandboxed processes
* Environment variables (all `AGENTSH_*` overrides, auto-start toggles, transport selection): [`docs/spec.md` §15.3 "Environment Variables"](https://github.com/canyonroad/agentsh/blob/HEAD/docs/spec.md#153-environment-variables)
* Architecture & data flow (FUSE + policy engine + API): inline comments in [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml) and [`internal/netmonitor`](https://github.com/canyonroad/agentsh/blob/HEAD/internal/netmonitor)
* CLI help: `agentsh --help`, `agentsh exec --help`, `agentsh shim --help`

---

Created with the help of agents for agents.

`visibility`	`silent`, `audit_only`, `warn`	Как редиректы логируются/отображаются
`on_failure`	`fail_closed`, `fail_open`, `retry_original`	Что происходит, если редирект не удаётся
`tls_mode`	`passthrough`, `rewrite_sni`	Обработка TLS для connect-редиректа

DNS Redirect	✅ eBPF	✅ pf/proxy	✅ WinDivert
Connect Redirect	✅ eBPF	✅ pf/proxy	✅ WinDivert
SNI Rewrite	✅	✅	✅

Linux	Да (seccomp user-notify)	Да	Да
macOS	Нет	Нет	Да (ES)
Windows	Частично	Нет	Да (ETW)

Популярное

agentsh

agentsh

Что такое agentsh?

Зачем нужен agentsh?

Осмысленные блокировки: deny → redirect (суперспособность «направления»)

Контейнеры + agentsh: вместе лучше

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

Установка

Запуск локально```bash

Start the server (optional if using autostart)

Create a session and run a command (shell output)

Structured output for agents

Скажите агенту, чтобы он использовал это (фрагмент AGENTS.md / CLAUDE.md)```md

Shell access

Модель политики

Решения

Области действия

Оценка

Краткая справка по политике окружения

Примеры правил (сокращено)```yaml

Аутентификация

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

60-секундное демо

1) Create a session in your repo/workspace

2) Run something simple (human-friendly output)

→ prints system info, just like normal

3) Run something that hits the network (JSON output + event summary)

→ JSON response includes: exit_code, stdout, and events[] showing dns_query + net_connect

4) Trigger a policy decision - try to delete something

→ With default policy: prompts for approval or denies based on your rules

5) See what happened (structured audit trail)

→ events[] shows every file operation, even from subprocesses

Контрольные точки рабочей области

Create a checkpoint before risky operations

List checkpoints for a session

Show what changed since a checkpoint

Preview what rollback would restore (dry-run)

Restore workspace to checkpoint state

Clean up old checkpoints

Контроль доступа к базе данных (пока только Postgres)

Генерация политик

Generate policy from latest session

Generate with custom name and threshold

Quick preview to stdout

Сетевое перенаправление

Перенаправление DNS

Options

Поддержка платформ

Варианты использования

Фильтрация сигналов

Поддержка платформ

Пример правил сигналов```yaml

Allow signals to self and children

Redirect SIGKILL to graceful SIGTERM

Block fatal signals to external processes