**Exemplo: redirecionar escritas fora do workspace de volta para dentro**```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"

Isto instala o pacote de aplicativos AgentSH com a extensão de sistema ESF+NE. Após a instalação, será solicitado que você aprove a extensão do sistema em **System Settings > General > Login Items & Extensions**.

**Linux (a partir de um GitHub Release)**

Baixe o `.deb`, `.rpm` ou `.apk` para sua plataforma na [página de releases](https://github.com/erans/agentsh/releases).```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

**A partir do código-fonte (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

---

### Verificar o que é aplicado

`agentsh detect` sonda o host e relata quais primitivas de aplicação estão realmente disponíveis — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — agrupadas em pontuações de proteção por domínio, além do modo de segurança selecionado. Em hosts restritos (Daytona, E2B, Firecracker-class) onde o listener user-notify do seccomp não pode ser instalado, ele relata o modo que *realmente* aplicará em vez do que o kernel meramente suporta.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

---

### Início automático (sem etapa manual do daemon)

Você **não** precisa iniciar `agentsh server` manualmente.

* O primeiro `agentsh exec` (ou qualquer `/bin/sh`/`/bin/bash` com shim) iniciará automaticamente um servidor local usando `configs/server-config.yaml` (ou `AGENTSH_CONFIG`, se definido).
* Esse servidor mantém a camada FUSE e o mecanismo de políticas ativos durante a sessão; comandos subsequentes o reutilizam.
* Defina `AGENTSH_NO_AUTO=1` se quiser gerenciar o ciclo de vida do servidor manualmente.

---

## Uso no Docker (com o shim do shell)

Veja `Dockerfile.example` para uma imagem mínima baseada em Debian.

Dentro da imagem, instale um pacote de lançamento (ou copie sua compilação) e ative o shim:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

Agora, qualquer `/bin/sh -c ...` ou `/bin/bash -lc ...` no contêiner é roteado através do agentsh.

### Aplicação não interativa

Por padrão, o shim ignora a política quando stdin não é um TTY (preservando dados binários para comandos com pipe). Em plataformas onde os comandos são sempre não interativos mas ainda precisam de aplicação (por exemplo, exe.dev, sandbox APIs), adicione `--force`:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --force \
  --i-understand-this-modifies-the-host

---
### Usando uma política```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

**O que você verá na saída JSON:**
- `exit_code`: o status de saída do comando
- `stdout` / `stderr`: saída capturada
- `events[]`: todas as operações de arquivo/rede/processo com decisões de política
- `policy.decision`: `allow`, `deny`, `approve` ou `redirect`

Dica: mantenha um terminal com `--output json` aberto ao testar políticas — isso torna óbvio o que está sendo tocado.

---

### Relatórios de Sessão

Gerar relatórios markdown resumindo a atividade da sessão:```bash
# Quick summary
agentsh report latest --level=summary

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

**Auto-checkpoint:** Quando ativado, agentsh cria automaticamente pontos de verificação antes de comandos arriscados (`rm`, `mv`, `git reset`, `git checkout`, etc.). Configure em `sessions.checkpoints.auto_checkpoint`.

Consulte [SECURITY.md](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#checkpoint-and-rollback) para opções completas de configuração.

---

### Proxy LLM e DLP

agentsh inclui um proxy embutido que intercepta todas as requisições de API LLM dos agentes:```bash
# Check proxy status for a session
agentsh proxy status <session-id>

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

# 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

**Configuração DLP:**```yaml
dlp:
  mode: redact
  patterns:
    email: true
    api_keys: true
  custom_patterns:
    - name: customer_id
      display: identifier
      regex: "CUST-[0-9]{8}"

The generated policy:
- Permite apenas operações observadas durante a sessão
- Agrupa caminhos em globs quando muitos arquivos no mesmo diretório
- Colapsa subdomínios em curingas (ex.: `*.github.com`)
- Sinaliza comandos arriscados (curl, wget, rm) com padrões de argumentos
- Inclui operações bloqueadas como regras comentadas para revisão

**Casos de uso:**
- **Bloqueio de CI/CD**: Perfilar uma execução de build/teste, bloquear execuções futuras para esse comportamento
- **Sandbox de agente**: Deixar um agente de IA executar uma tarefa, gerar política para execuções futuras
- **Perfil de contêiner**: Perfilar uma carga de trabalho, gerar política mínima para produção

---

## Acesso a Banco de Dados (PostgreSQL)

o agentsh inclui um **proxy PostgreSQL** embutido que torna o acesso ao banco de dados consciente do agente e governado por políticas. Ele fala o protocolo wire do Postgres, classifica cada declaração em uma lista de *efeitos* (leituras, escritas, DDL, DCL, controle de transação/sessão, `COPY`/exportação em massa, …) e avalia cada efeito em relação às `database_rules` antes de encaminhar upstream — então um `UPDATE`, `DROP`, ou `DELETE` sem escopo é governado da mesma forma que uma escrita de arquivo ou conexão de rede.

- **Avaliação por efeito e multi-objeto** — as regras são coletar-tudo / **qualquer-nega-vence** (o verbo mais restritivo decide), não primeira correspondência.
- **Decisões:** `allow`, `deny`, `approve` (OK humano), `audit` e `redirect` no nível da declaração.
- **Guarda `require_where`** — recusa `UPDATE`/`DELETE` de nível superior que não tenham cláusula `WHERE`.
- **Regras de nível de conexão** (`database_connection_rules`) controlam quais sessões podem alcançar qual `db_service` declarado.
- **Eventos de auditoria de autenticação + declaração** para cada conexão e consulta; o registro do texto da declaração é configurável (`policies.db.log_statements: none | parameters_redacted | full`).

A Fase 1 cobre o protocolo wire PostgreSQL v3 (dialetos: `postgres`, `aurora_postgres`; `redshift` / `cockroachdb` em beta). Conexões de replicação e criptografadas por GSSAPI têm negação padrão.```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}}"

### Connect Redirect

Redirecione conexões TCP para destinos diferentes com manipulação TLS opcional:```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

### Grupos de Sinais

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

### Tipos de Alvo

- `self` - Processo sinalizando a si mesmo
- `children` - Processos filhos diretos
- `descendants` - Todos os processos descendentes
- `session` - Qualquer processo na sessão agentsh
- `external` - PIDs fora da sessão
- `system` - PID 1 e threads do kernel

Consulte a [Documentação de Políticas](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#signal-rules) para opções completas de configuração.

---

## Monitoramento de E/S de Arquivos no macOS

No macOS, o agentsh monitora E/S de arquivos usando o Endpoint Security Framework (ESF), inscrevendo-se em eventos AUTH e NOTIFY. As operações rastreadas incluem abrir, criar, excluir, renomear, escrever (detectado via close-modified) e, no macOS 26+, chmod e chown através de eventos de alteração de atributos. Cada evento de arquivo é atribuído à sessão e comando de origem através da resolução baseada em PID, fornecendo trilhas de auditoria completas entre árvores de subprocessos.

O ESF fornece imposição de permitir/negar no nível do kernel, mas não suporta interceptação transparente de arquivos como o FUSE do Linux. As ações de política que exigem interceptação -- como `redirect` (reescrita de caminho) e `soft_delete` (quarentena) -- são implementadas como negar + orientação: a operação é bloqueada no nível do ESF e o agente recebe instruções para tentar novamente com o caminho correto ou para reconhecer que o arquivo está protegido. Consulte o [documento de arquitetura ESF+NE do macOS](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) para detalhes do fluxo de eventos e a [documentação de políticas](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#file-rule-actions-on-macos-esf) para o comportamento por ação.

---

## Pacotes de políticas iniciais

Você já tem uma política padrão (`configs/policies/default.yaml`). Esses pacotes opinativos estão disponíveis como arquivos separados para que as equipes possam escolher um:

* **[`policies/dev-safe.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/dev-safe.yaml)**: seguro para desenvolvimento local
  * permitir leitura/gravação do workspace
  * aprovar exclusões no workspace
  * negar `~/.ssh/**`, `/root/.ssh/**`
  * restringir rede a domínios/portas na lista de permissões

* **[`policies/ci-strict.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/ci-strict.yaml)**: seguro para runners de CI
  * negar qualquer coisa fora do workspace
  * negar rede de saída, exceto registros de artefatos
  * negar shells interativos, a menos que explicitamente permitidos
  * auditar tudo (eventos resumidos)

* **[`policies/agent-sandbox.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/agent-sandbox.yaml)**: modo 'agente executa código desconhecido'
  * negar padrão + lista de permissões explícita
  * aprovar qualquer acesso a credenciais/caminhos
  * redirecionar uso de ferramentas de rede para proxies/mirrors internos
  * soft-delete de operações destrutivas para fácil recuperação

---

## Exemplos de Integração com Assistente de IA

Trechos prontos para uso para configurar assistentes de codificação de IA para usar agentsh:

* **[Claude Code](https://github.com/canyonroad/agentsh/blob/HEAD/examples/claude/)** - Trecho CLAUDE.md para integração com Claude Code
* **[Cursor](https://github.com/canyonroad/agentsh/blob/HEAD/examples/cursor/)** - Regras do Cursor para integração com agentsh
* **[AGENTS.md](https://github.com/canyonroad/agentsh/blob/HEAD/examples/agents/)** - Trecho AGENTS.md genérico (funciona com múltiplas ferramentas de IA)

> **Nota:** Estes exemplos são para cenários de desenvolvimento local onde executar o agente de IA dentro de um contêiner não é prático. Para ambientes de produção ou CI/CD, prefira executar agentes em contêineres com o shell shim instalado—consulte [Uso no Docker](#use-in-docker-with-the-shell-shim).

---

## Referências

* **Demonstração de Proteção MCP:** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - demonstração ao vivo de detecção de exfiltração entre servidores, bloqueio de rug pull e geração de políticas
* **Segurança e modelo de ameaça:** [`SECURITY.md`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md) - contra o que agentsh protege, limitações conhecidas, lista de verificação do operador
* **KMS Externo:** [`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 para chaves de integridade de auditoria
* Modelo de configuração: [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml)
* Política padrão: [`configs/policies/default.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/default.yaml)
* Exemplo de Dockerfile (com shim): [`Dockerfile.example`](https://github.com/canyonroad/agentsh/blob/HEAD/Dockerfile.example)
* **Documentação de políticas:** [`docs/operations/policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md) - variáveis de política, regras de sinal, redirecionamento de rede
* **Controle de acesso a banco de dados:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - escopo de imposição de banco de dados apenas Postgres, semântica de política, comportamento de redirecionamento e roteiro
* **Livro de receitas de políticas de comando:** [`docs/cookbook/command-policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/command-policies.md) - como permitir um novo binário, quando usar `wrap` em vez de `exec` e como depurar uma negação
* **Livro de receitas de serviços HTTP:** [`docs/cookbook/http-services.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/http-services.md) - receitas para rotear chamadas de API HTTP de saída através de serviços declarados com regras e portão de aprovação
* **Livro de receitas de integrações de SDK de sandbox:** [`docs/cookbook/sandbox-sdk-integrations.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/sandbox-sdk-integrations.md) - configuração `shim_install` para Tensorlake / E2B / Modal / Daytona onde os comandos são executados como irmãos do servidor agentsh
* **Habilidades de criação de políticas:** [`skills/`](https://github.com/canyonroad/agentsh/blob/HEAD/skills/) - habilidades de assistente de IA para criar e editar políticas no Claude Code, NanoClaw, etc.
* **Comparação de plataformas:** [`docs/platform-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/platform-comparison.md) - suporte a recursos, pontuações de segurança, desempenho por plataforma
* **Bubblewrap vs agentsh:** [`docs/bubblewrap-vs-agentsh-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/bubblewrap-vs-agentsh-comparison.md) - comparação com Bubblewrap para sandboxing de contêineres Linux
* **Controle de acesso a banco de dados:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - taxonomia de proxy PostgreSQL, modelo de efeitos, `database_rules`, regras de conexão, modelo de ameaça
* **Modos de segurança e `detect`:** [`docs/security-modes.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/security-modes.md) - modos de imposição, pontuação de proteção e o que `agentsh detect` relata
* **seccomp:** [`docs/seccomp.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/seccomp.md) - filtragem de chamadas de sistema, interceptação de execve e bloqueio de famílias de sockets
* **Modo ptrace:** [`docs/ptrace-support.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ptrace-support.md) - imposição PTRACE_SEIZE para contêineres restritos (`attach_mode`, pré-filtro seccomp)
* **eBPF:** [`docs/ebpf.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ebpf.md) - rastreamento de rede e imposição de políticas via eBPF
* **Proxy LLM e DLP:** [`docs/llm-proxy.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/llm-proxy.md) - configuração de proxy embutido, padrões DLP, rastreamento de uso
* **Guia de compilação macOS:** [`docs/macos-build.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-build.md) - instruções de compilação ESF+NE
* **Arquitetura ESF+NE macOS:** [`docs/macos-esf-ne-architecture.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) - Extensão de Sistema, XPC e detalhes de implantação
* **Sandbox XPC macOS:** [`docs/macos-xpc-sandbox.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-xpc-sandbox.md) - controle XPC/Mach IPC para processos em sandbox
* Variáveis de ambiente (todas as substituições `AGENTSH_*`, alternâncias de inicialização automática, seleção de transporte): [`docs/spec.md` §15.3 "Variáveis de Ambiente"](https://github.com/canyonroad/agentsh/blob/HEAD/docs/spec.md#153-environment-variables)
* Arquitetura e fluxo de dados (FUSE + motor de política + API): comentários inline em [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml) e [`internal/netmonitor`](https://github.com/canyonroad/agentsh/blob/HEAD/internal/netmonitor)
* Ajuda da CLI: `agentsh --help`, `agentsh exec --help`, `agentsh shim --help`

---

Criado com a ajuda de agentes para agentes.