agentsh

Nota para macOS: La aplicación nativa de enforcement en macOS mediante ESF (Endpoint Security Framework) + NE (Network Extension) está en Alpha. Funciona de extremo a extremo: los eventos de archivos, procesos y red fluyen a través de la extensión del sistema hasta el motor de políticas Go, pero espera bordes sin pulir y cambios que rompan compatibilidad entre versiones. Para uso en producción hoy, recomendamos Linux.

Nota para Windows: Estamos trabajando para que los controladores minifilter estén firmados. Hasta entonces, solo el modo WSL2 de Windows es totalmente compatible para uso en producción.

Puerta de enlace de ejecución segura y con políticas para agentes de IA.

agentsh se sitúa debajo de tu agente/herramienta: intercepta la actividad de archivos, red, procesos y señales (incluidos los árboles de subprocesos), aplica la política que definas y emite eventos de auditoría estructurados.

Nota de plataforma: Linux ofrece enforcement completo (100 % de puntuación de seguridad). macOS ESF+NE (90 %) está en Alpha: funcional pero no listo para producción. WSL2 de Windows ofrece enforcement completo equivalente a Linux (100 %); Windows nativo mediante controlador minifilter + AppContainer (85 %) está pendiente de la firma del controlador. Consulta la Matriz de comparación de plataformas para más detalles.

¿Qué es agentsh?

Endpoint shell/exec de sustitución directa que convierte cada comando (y sus subprocesos) en eventos auditables.
Motor de políticas por operación: allow, deny, approve (aprobación humana), soft_delete o redirect.
Visibilidad total de E/S:
- apertura/lectura/escritura/eliminación de archivos
- conexión de red + DNS
- inicio/fin de procesos
- actividad PTY
- solicitudes de API de LLM con DLP y seguimiento de uso
- tráfico de bases de datos tipo Postgres mediante db_services declarados
- envío/bloqueo de señales (aplicado en Linux, auditoría en macOS/Windows)
- consultas de bases de datos a través del proxy PostgreSQL integrado: clasificación y política por sentencia
- Enrutamiento de llamadas HTTP salientes a la API mediante servicios declarados (http_services) con reglas por método y por ruta, control de aprobación y enforcement de host con fallo cerrado
Dos modos de salida:
- salida de shell legible para humanos
- respuestas JSON compactas para agentes/herramientas

¿Por qué agentsh?

Los flujos de trabajo de agentes tarde o temprano ejecutan código arbitrario (pip install, make test, python script.py). Los controles tradicionales de "pedir aprobación antes de ejecutar un comando" se detienen en el límite de la herramienta y no pueden ver lo que sucede dentro de ese comando.

agentsh aplica la política en tiempo de ejecución, de modo que el trabajo oculto realizado por los subprocesos también se gobierna, se registra y (cuando es necesario) se aprueba.

Bloqueos significativos: deny → redirect (el superpoder del "direccionamiento")

La mayoría de los sistemas pueden denegar una acción. agentsh también puede redirigirla.

Eso significa que cuando un agente intenta el enfoque incorrecto (o soluciones por fuerza bruta), la política puede guiarlo hacia el camino correcto intercambiando el comando y devolviendo orientación, manteniendo al agente en el camino pavimentado y reduciendo reintentos desperdiciados.

Ejemplo: redirigir curl a un wrapper auditado```yaml command_rules:

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

**Ejemplo: redirigir las escrituras fuera del workspace de vuelta al interior**```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"

El agente ve una operación exitosa (no un error), pero tú controlas dónde aterrizan realmente las cosas.

Contenedores + agentsh: mejor juntos

Los contenedores aíslan la superficie del host; agentsh añade visibilidad y política de ejecución dentro del contenedor.

La auditoría por operación (archivos, red, comandos) muestra lo que ocurrió durante instalaciones/compilaciones/pruebas.
Las aprobaciones y reglas persisten a lo largo de shells de larga duración y árboles de subprocesos—no solo en el primer comando.
Controles a nivel de ruta en workspaces/cachés/credenciales montados; los contenedores no ofrecen de forma nativa ese nivel de granularidad.
El mismo comportamiento en el host y en los contenedores, por lo que la CI y el desarrollo local ven los mismos resultados de las políticas.

Inicio rápido

Instalación

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

Esto instala el paquete de la aplicación AgentSH con la extensión del sistema ESF+NE. Después de la instalación, se te pedirá que apruebes la extensión del sistema en **System Settings > General > Login Items & Extensions**.

**Linux (desde un lanzamiento de GitHub)**

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

Desde el código fuente (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

**Desde el código fuente (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

Consulta la Guía de compilación de macOS para obtener instrucciones detalladas de compilación en macOS.

Ejecutar localmente```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

---

### Comprueba qué se aplica realmente

`agentsh detect` sondea el host e informa qué primitivas de cumplimiento están realmente disponibles — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — agrupadas en puntuaciones de protección por dominio más el modo de seguridad seleccionado. En hosts restringidos (clase Daytona, E2B, Firecracker) donde el listener user-notify de seccomp no puede instalarse, informa del modo que se aplicará *efectivamente* en lugar de lo que el kernel meramente soporta.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

Consulta Modos de seguridad para la matriz de modos y los parámetros de ajuste.

Indica a tu agente que lo use (AGENTS.md / CLAUDE.md snippet)```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)

---

### Autostart (sin paso manual de daemon)

**No** necesitas iniciar `agentsh server` tú mismo.

* El primer `agentsh exec` (o cualquier `/bin/sh`/`/bin/bash` con shim) lanzará automáticamente un servidor local usando `configs/server-config.yaml` (o `AGENTSH_CONFIG` si está definido).
* Ese servidor mantiene la capa FUSE y el motor de políticas activos durante la vida de la sesión; los comandos posteriores lo reutilizan.
* Establece `AGENTSH_NO_AUTO=1` si quieres gestionar manualmente el ciclo de vida del servidor.

---

## Uso en Docker (con el shim de shell)

Consulta `Dockerfile.example` para ver una imagen mínima basada en Debian.

Dentro de la imagen, instala un paquete de release (o copia tu compilación) y luego activa el shim:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

Apunta el shim a tu servidor (sidecar o host):```dockerfile ENV AGENTSH_SERVER=http://127.0.0.1:18080

Ahora cualquier `/bin/sh -c ...` o `/bin/bash -lc ...` en el contenedor se enruta a través de agentsh.

### Aplicación no interactiva

Por defecto, el shim omite la política cuando stdin no es una TTY (preservando datos binarios para comandos canalizados). En plataformas donde los comandos siempre son no interactivos pero aún necesitan aplicación (p. ej., exe.dev, APIs de sandbox), agregue `--force`:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --force \
  --i-understand-this-modifies-the-host

Esto escribe /etc/agentsh/shim.conf con force=true, que el shim lee al inicio. El archivo de configuración funciona independientemente de cómo se invoque el shell (a diferencia de las variables de entorno o los scripts de perfil). AGENTSH_SHIM_FORCE=1 en el entorno del proceso logra el mismo efecto por proceso.

Patrón recomendado: ejecutar agentsh como sidecar (o PID 1) en el mismo pod/servicio y compartir un volumen de trabajo; el shim garantiza que cada salto de shell permanezca bajo la política.

Modelo de política

Decisiones

allow
deny
approve (aprobación humana)
redirect (intercambiar un comando)
audit (permitir + registrar)
soft_delete (poner en cuarentena las eliminaciones con restauración)

Alcances

operaciones de archivo
comandos
variables de entorno
red (DNS/conexión)
base de datos (sentencias SQL a través del proxy PostgreSQL)
ajustes de PTY/sesión
servicios HTTP declarados

Evaluación

la primera regla que coincida gana

Las reglas viven en una política con nombre; las sesiones eligen una política.

Valores predeterminados:

configuración de ejemplo: configs/server-config.yaml
política predeterminada: configs/policies/default.yaml
anulación por entorno: establezca AGENTSH_POLICY_NAME a un nombre de política permitida (sin sufijo). Si no está definida, es inválida o no está permitida, se usa la predeterminada.
política de entorno: configure policies.env_policy (allow/deny, max_bytes, max_keys, block_iteration) y anulaciones env_* por comando en los archivos de política. Una lista de permitidos vacía predetermina a PATH/LANG/TERM/HOME mínimos con una lista de denegación de secretos integrada; establezca block_iteration para ocultar la iteración del entorno (requiere el shim de entorno).
lista de permitidos: configure policies.allowed en config.yml; vacía significa que solo se permite la predeterminada.
integridad opcional: establezca policies.manifest_path a un manifiesto SHA256 para verificar los archivos de política al momento de la carga.

Referencia rápida de la política de entorno

Valores predeterminados: Sin env_allow, agentsh construye un entorno mínimo (PATH/LANG/TERM/HOME) y elimina las claves secretas integradas.
Anulaciones: env_allow/env_deny por comando, además de env_max_keys/env_max_bytes, limitan y filtran el entorno hijo al momento de ejecutar.
Bloqueo de iteración: env_block_iteration: true (global o por regla) oculta la enumeración del entorno; establezca policies.env_shim_path a libenvshim.so para que agentsh inyecte LD_PRELOAD + AGENTSH_ENV_BLOCK_ITERATION=1.
Límites: Da error si se superan los límites; el constructor de entorno se aplica antes de la ejecución para cada comando.
env_inject: Variables de entorno de confianza del operador inyectadas en todos los comandos, omitiendo el filtrado de la política. Uso principal: BASH_ENV para deshabilitar builtins del shell que omiten seccomp. Configure en (global) o a nivel de política (anula la global).

Reglas de ejemplo (recortadas)```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

---

### Usando una 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

Autenticación

agentsh admite múltiples métodos de autenticación:

Tipo	Caso de uso
`api_key`	Implementaciones simples con claves estáticas
`oidc`	SSO empresarial (Okta, Azure AD, etc.)
`hybrid`	Ambos métodos aceptados

Modos de aprobación para verificación con intervención humana:

local_tty - Solicitud en terminal (predeterminado)
totp - Códigos de aplicación de autenticación
webauthn - Claves de seguridad de hardware (YubiKey)
api - Aprobación remota mediante REST

Consulta SECURITY.md para ver los detalles de configuración.

Seguridad de MCP

Lista blanca de herramientas: Controla qué herramientas de MCP pueden invocarse mediante políticas de permitidos/denegados
Fijación de versiones: Detecta cambios en la definición de herramientas (protección contra rug pull) con respuestas configurables
Detección entre servidores: Bloquea patrones de exfiltración de datos (leer del Servidor A → enviar mediante el Servidor B)
Limitación de tasa: Limitación de tasa con token bucket para servidores MCP y dominios de red

Consulta SECURITY.md para ver todas las opciones de configuración, o ejecuta la Demo de Protección MCP para ver estas detecciones en acción.

Demo de 60 segundos

La forma más rápida de "entenderlo" es ejecutar algo que genere subprocesos y toque el sistema de archivos/red.```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

**Lo que verás en la salida JSON:**
- `exit_code`: el estado de salida del comando
- `stdout` / `stderr`: salida capturada
- `events[]`: cada operación de archivo/red/proceso con decisiones de política
- `policy.decision`: `allow`, `deny`, `approve` o `redirect`

Consejo: mantén una terminal con `--output json` abierta al probar políticas—hace que sea obvio qué se está tocando.

---

### Informes de sesión

Genera informes markdown que resumen la actividad de la sesión:```bash
# Quick summary
agentsh report latest --level=summary

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

Los informes incluyen:

Resumen de decisiones (permitido, bloqueado, redirigido)
Detección automática de hallazgos (violaciones, anomalías)
Desglose de actividad por categoría
Línea temporal completa de eventos (modo detallado)

Consulte la Guía de integración CI/CD para ver ejemplos de pipelines.

Puntos de control del espacio de trabajo

Cree instantáneas del estado del espacio de trabajo para recuperarse de operaciones destructivas:```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:** Cuando está habilitado, agentsh crea automáticamente puntos de control antes de comandos riesgosos (`rm`, `mv`, `git reset`, `git checkout`, etc.). Configúralo en `sessions.checkpoints.auto_checkpoint`.

Consulta [SECURITY.md](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#checkpoint-and-rollback) para ver todas las opciones de configuración.

---

### Proxy LLM y DLP

agentsh incluye un proxy integrado que intercepta todas las solicitudes a la API de LLM de los agentes:```bash
# Check proxy status for a session
agentsh proxy status <session-id>

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

Características:

Enrutamiento automático: Establece ANTHROPIC_BASE_URL y OPENAI_BASE_URL para que los SDK de agentes enruten a través del proxy
Proveedores personalizados: Enruta a LiteLLM, Azure OpenAI, vLLM o pasarelas corporativas
Redacción DLP: La PII (correos electrónicos, números de teléfono, claves API, etc.) se redacta antes de llegar a los proveedores de LLM
Patrones personalizados: Define patrones específicos de la organización para datos sensibles
Seguimiento de uso: Los conteos de tokens se extraen y registran para la atribución de costos
Registro de auditoría: Todas las solicitudes/respuestas se registran en el almacenamiento de sesión

Configuración del proveedor:```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

**Configuración de DLP:**```yaml
dlp:
  mode: redact
  patterns:
    email: true
    api_keys: true
  custom_patterns:
    - name: customer_id
      display: identifier
      regex: "CUST-[0-9]{8}"

Consulte la Documentación del proxy LLM para conocer todas las opciones de configuración.

El mismo proxy también despacha las entradas http_services declaradas: upstreams de API con nombre y reglas por método y por ruta. Consulte Servicios HTTP declarados y el Cookbook de servicios HTTP para más detalles.

Control de acceso a bases de datos (solo Postgres por ahora)

agentsh puede aplicar políticas sobre los servicios de base de datos declarados mediante db_services, database_connection_rules y database_rules. La implementación actual es solo para la familia Postgres: PostgreSQL es el destino compatible, con Aurora Postgres usando la misma ruta y Redshift/CockroachDB tratados como dialectos compatibles con Postgres con cobertura beta. MySQL, MongoDB, Snowflake, BigQuery, Databricks, ClickHouse, MSSQL, Cassandra, Redis y Oracle son elementos de la hoja de ruta, no compatibilidad de ejecución actual.

El soporte actual de Postgres incluye:

Decisiones de conexión de permitir/denegar/aprobar/auditar.
Clasificación de sentencias para el protocolo wire v3 de PostgreSQL, incluyendo Simple Query, Extended Query, sentencias preparadas SQL, COPY, denegación de FunctionCall, estado de transacción y mapeo de CancelRequest.
Cobertura estricta de políticas por objeto con precedencia de denegación.
Selectores de relaciones/funciones respaldados por catálogo para políticas de objetos resueltos.
redirect seguro en tiempo de ejecución para el reemplazo de relaciones de Postgres de solo lectura.
Detección de bypass y cobertura E2E con Docker de Postgres real en CI.

El runtime del proxy Postgres es código solo Linux dentro del proceso actualmente. Use Linux nativo, WSL2 o un entorno de VM Linux para la aplicación de políticas de base de datos.

Consulte Control de acceso a bases de datos y Documentación de políticas.

Generación de políticas

Genere políticas restrictivas a partir del comportamiento observado de la sesión (flujo de trabajo «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

La política generada:
- Solo permite las operaciones observadas durante la sesión
- Agrupa rutas en globs cuando hay muchos archivos en el mismo directorio
- Colapsa subdominios en comodines (p. ej., `*.github.com`)
- Marca comandos riesgosos (curl, wget, rm) con patrones de argumentos
- Incluye operaciones bloqueadas como reglas comentadas para su revisión

**Casos de uso:**
- **Bloqueo en CI/CD**: Perfila una ejecución de build/test, bloquea futuras ejecuciones a ese comportamiento
- **Aislamiento de agentes**: Deja que un agente de IA ejecute una tarea, genera una política para futuras ejecuciones
- **Perfilado de contenedores**: Perfila una carga de trabajo, genera una política mínima para producción

---

## Acceso a bases de datos (PostgreSQL)

agentsh incluye un **proxy PostgreSQL** integrado que hace que el acceso a bases de datos sea consciente del agente y esté gobernado por políticas. Habla el protocolo de cable de Postgres, clasifica cada sentencia en una lista de *efectos* (lecturas, escrituras, DDL, DCL, control de transacciones/sesiones, `COPY`/exportación masiva, …) y evalúa cada efecto contra `database_rules` antes de reenviarlo al upstream — de modo que un `UPDATE`, `DROP` o `DELETE` sin ámbito se gobierna igual que una escritura de archivo o una conexión de red.

- **Evaluación por efecto y multiobjeto** — las reglas son acumulativas / **gana cualquier denegación** (el verbo más restrictivo decide), no la primera coincidencia.
- **Decisiones:** `allow`, `deny`, `approve` (aprobación humana), `audit` y `redirect` a nivel de sentencia.
- **Guardia `require_where`** — rechaza `UPDATE`/`DELETE` de nivel superior que carezcan de una cláusula `WHERE`.
- **Reglas a nivel de conexión** (`database_connection_rules`) controlan qué sesiones pueden alcanzar qué `db_service` declarado.
- **Eventos de auditoría de autenticación y sentencias** para cada conexión y consulta; el registro del texto de las sentencias es configurable (`policies.db.log_statements: none | parameters_redacted | full`).

La Fase 1 cubre el protocolo de cable v3 de PostgreSQL (dialectos: `postgres`, `aurora_postgres`; `redshift` / `cockroachdb` en beta). Las conexiones de replicación y cifradas con GSSAPI se deniegan por defecto.```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}}"

Consulta la especificación de Control de Acceso a la Base de Datos para ver la taxonomía completa de operaciones, el modelo de efectos, las reglas de conexión y el modelo de amenazas de inevitabilidad.

Redirección de Red

agentsh puede redirigir de forma transparente conexiones DNS y TCP, lo que permite casos de uso como enrutar llamadas a APIs a través de proxies corporativos o cambiar de proveedor de IA sin modificar el código.

Redirección DNS

Intercepta la resolución DNS y devuelve direcciones IP configuradas:```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

### Redirección de conexión

Redirige conexiones TCP a diferentes destinos con manejo opcional de 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

Opciones

Soporte de Plataformas

Casos de Uso

Enrutamiento de API Gateway: Enrutar llamadas de Anthropic/OpenAI a través de la puerta de enlace LLM corporativa
Cambio de Proveedor: Redirigir la API de Claude a GCP Vertex AI o Azure OpenAI
Pruebas: Redirigir APIs de producción a servidores mock
Cumplimiento: Forzar todo el tráfico LLM a través de proxies de auditoría

Filtrado de Señales

agentsh intercepta señales (kill, SIGTERM, etc.) enviadas entre procesos, proporcionando control basado en políticas sobre qué señales pueden llegar a qué destinos.

Soporte de Plataformas

Ejemplo de Reglas de Señales```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

### Grupos de señales

- `@all` - Todas las señales (1-31)
- `@fatal` - SIGKILL, SIGTERM, SIGQUIT, SIGABRT
- `@job` - SIGSTOP, SIGCONT, SIGTSTP, SIGTTIN, SIGTTOU
- `@reload` - SIGHUP, SIGUSR1, SIGUSR2

### Tipos de destino

- `self` - Proceso que se envía señales a sí mismo
- `children` - Procesos hijo directos
- `descendants` - Todos los procesos descendientes
- `session` - Cualquier proceso en la sesión de agentsh
- `external` - PIDs fuera de la sesión
- `system` - PID 1 y subprocesos del kernel

Consulta la [Documentación de políticas](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#signal-rules) para ver todas las opciones de configuración.

---

## Supervisión de E/S de archivos en macOS

En macOS, agentsh supervisa la E/S de archivos mediante el Endpoint Security Framework (ESF), suscribiéndose tanto a eventos AUTH como NOTIFY. Las operaciones rastreadas incluyen apertura, creación, eliminación, renombrado y escritura de archivos (detectada a través de close-modified) y, en macOS 26+, chmod y chown mediante eventos de cambio de atributos. Cada evento de archivo se atribuye a la sesión y al comando de origen mediante la resolución basada en PID, lo que proporciona pistas de auditoría completas en todos los árboles de subprocesos.

ESF proporciona aplicación de permisos/denegaciones a nivel de kernel, pero no admite la interceptación transparente de archivos como Linux FUSE. Las acciones de política que requieren interceptación -- como `redirect` (reescritura de rutas) y `soft_delete` (cuarentena) -- se implementan como denegación + orientación: la operación se bloquea a nivel de ESF y el agente recibe instrucciones para reintentar con la ruta correcta o para reconocer que el archivo está protegido. Consulta el [documento de arquitectura macOS ESF+NE](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) para obtener detalles sobre el flujo de eventos y la [documentación de políticas](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#file-rule-actions-on-macos-esf) para conocer el comportamiento de cada acción.

---

## Paquetes de políticas iniciales

Ya tienes una política predeterminada (`configs/policies/default.yaml`). Estos paquetes con criterios definidos están disponibles como archivos separados para que los equipos puedan elegir uno:

* **[`policies/dev-safe.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/dev-safe.yaml)**: seguro para el desarrollo local
  * permitir lectura/escritura en el espacio de trabajo
  * aprobar eliminaciones en el espacio de trabajo
  * denegar `~/.ssh/**`, `/root/.ssh/**`
  * restringir la red a dominios/puertos permitidos

* **[`policies/ci-strict.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/ci-strict.yaml)**: seguro para runners de CI
  * denegar cualquier cosa fuera del espacio de trabajo
  * denegar tráfico de red saliente excepto a los registros de artefactos
  * denegar shells interactivos a menos que se permitan explícitamente
  * auditar todo (eventos resumidos)

* **[`policies/agent-sandbox.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/agent-sandbox.yaml)**: modo "el agente ejecuta código desconocido"
  * denegación predeterminada + lista de permitidos explícita
  * aprobar cualquier acceso a credenciales/rutas
  * redirigir el uso de herramientas de red a proxies/duplicados internos
  * aplicar soft-delete a operaciones destructivas para facilitar la recuperación

---

## Ejemplos de integración con asistentes de IA

Fragmentos listos para usar para configurar asistentes de codificación de IA para que utilicen agentsh:

* **[Claude Code](https://github.com/canyonroad/agentsh/blob/HEAD/examples/claude/)** - fragmento de CLAUDE.md para la integración con Claude Code
* **[Cursor](https://github.com/canyonroad/agentsh/blob/HEAD/examples/cursor/)** - reglas de Cursor para la integración con agentsh
* **[AGENTS.md](https://github.com/canyonroad/agentsh/blob/HEAD/examples/agents/)** - fragmento genérico de AGENTS.md (funciona con múltiples herramientas de IA)

> **Nota:** Estos ejemplos son para escenarios de desarrollo local donde ejecutar el agente de IA dentro de un contenedor no es práctico. Para entornos de producción o CI/CD, prefiere ejecutar agentes en contenedores con el shim de shell instalado; consulta [Uso en Docker](#use-in-docker-with-the-shell-shim).

---

## Referencias

* **Demostración de protección MCP:** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - demo en vivo de detección de exfiltración entre servidores, bloqueo de rug pulls y generación de políticas
* **Modelo de seguridad y amenazas:** [`SECURITY.md`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md) - contra qué protege agentsh, limitaciones conocidas, lista de verificación para operadores
* **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 claves de integridad de auditoría
* Plantilla de configuración: [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml)
* Política predeterminada: [`configs/policies/default.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/default.yaml)
* Dockerfile de ejemplo (con shim): [`Dockerfile.example`](https://github.com/canyonroad/agentsh/blob/HEAD/Dockerfile.example)
* **Documentación de políticas:** [`docs/operations/policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md) - variables de política, reglas de señales, redirección de red
* **Control de acceso a bases de datos:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - alcance de aplicación de bases de datos solo Postgres, semántica de políticas, comportamiento de redirección y hoja de ruta
* **Recetario de políticas de comandos:** [`docs/cookbook/command-policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/command-policies.md) - cómo permitir un nuevo binario, cuándo usar `wrap` en lugar de `exec` y cómo depurar una denegación
* **Recetario de servicios HTTP:** [`docs/cookbook/http-services.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/http-services.md) - recetas para enrutar llamadas HTTP API salientes a través de servicios declarados con reglas y aprobaciones
* **Recetario de integraciones con SDK de sandbox:** [`docs/cookbook/sandbox-sdk-integrations.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/sandbox-sdk-integrations.md) - configuración `shim_install` para Tensorlake / E2B / Modal / Daytona donde los comandos se ejecutan como procesos hermanos del servidor agentsh
* **Habilidades para redactar políticas:** [`skills/`](https://github.com/canyonroad/agentsh/blob/HEAD/skills/) - habilidades para asistentes de IA para crear y editar políticas en Claude Code, NanoClaw, etc.
* **Comparación de plataformas:** [`docs/platform-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/platform-comparison.md) - soporte de funciones, puntuaciones de seguridad, rendimiento por plataforma
* **Bubblewrap vs agentsh:** [`docs/bubblewrap-vs-agentsh-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/bubblewrap-vs-agentsh-comparison.md) - comparación con Bubblewrap para el sandboxing de contenedores Linux
* **Control de acceso a bases de datos:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - taxonomía de proxy PostgreSQL, modelo de efectos, `database_rules`, reglas de conexión, modelo de amenazas
* **Modos de seguridad y `detect`:** [`docs/security-modes.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/security-modes.md) - modos de aplicación, puntuación de protección y qué informa `agentsh detect`
* **seccomp:** [`docs/seccomp.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/seccomp.md) - filtrado de llamadas al sistema, interceptación de execve y bloqueo de familias de sockets
* **Modo ptrace:** [`docs/ptrace-support.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ptrace-support.md) - aplicación de PTRACE_SEIZE para contenedores restringidos (`attach_mode`, prefiltro seccomp)
* **eBPF:** [`docs/ebpf.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ebpf.md) - rastreo de red y aplicación de políticas con eBPF
* **Proxy LLM y DLP:** [`docs/llm-proxy.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/llm-proxy.md) - configuración de proxy integrado, patrones DLP, seguimiento de uso
* **Guía de compilación para macOS:** [`docs/macos-build.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-build.md) - instrucciones de compilación de ESF+NE
* **Arquitectura macOS ESF+NE:** [`docs/macos-esf-ne-architecture.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) - detalles de System Extension, XPC e implementación
* **Sandbox XPC de macOS:** [`docs/macos-xpc-sandbox.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-xpc-sandbox.md) - control de XPC/IPC Mach para procesos en sandbox
* Variables de entorno (todos los override `AGENTSH_*`, conmutadores de inicio automático, selección de transporte): [`docs/spec.md` §15.3 "Variables de entorno"](https://github.com/canyonroad/agentsh/blob/HEAD/docs/spec.md#153-environment-variables)
* Arquitectura y flujo de datos (FUSE + motor de políticas + API): comentarios en línea en [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml) y [`internal/netmonitor`](https://github.com/canyonroad/agentsh/blob/HEAD/internal/netmonitor)
* Ayuda de CLI: `agentsh --help`, `agentsh exec --help`, `agentsh shim --help`

---

Creado con la ayuda de agentes para agentes.

`visibility`	`silent`, `audit_only`, `warn`	Cómo se registran/muestran las redirecciones
`on_failure`	`fail_closed`, `fail_open`, `retry_original`	Qué sucede si falla la redirección
`tls_mode`	`passthrough`, `rewrite_sni`	Manejo de TLS para la redirección de connect

Redirección DNS	✅ eBPF	✅ pf/proxy	✅ WinDivert
Redirección de Connect	✅ eBPF	✅ pf/proxy	✅ WinDivert
Reescritura SNI	✅	✅	✅

Linux	Sí (seccomp user-notify)	Sí	Sí
macOS	No	No	Sí (ES)
Windows	Parcial	No	Sí (ETW)

Más Populares

agentsh

agentsh

¿Qué es agentsh?

¿Por qué agentsh?

Bloqueos significativos: deny → redirect (el superpoder del "direccionamiento")

Contenedores + agentsh: mejor juntos

Inicio rápido

Instalación

Ejecutar localmente```bash

Start the server (optional if using autostart)

Create a session and run a command (shell output)

Structured output for agents

Indica a tu agente que lo use (AGENTS.md / CLAUDE.md snippet)```md

Shell access

Modelo de política

Decisiones

Alcances

Evaluación

Referencia rápida de la política de entorno

Reglas de ejemplo (recortadas)```yaml

Autenticación

Seguridad de MCP

Demo de 60 segundos

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

Puntos de control del espacio de trabajo

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

Control de acceso a bases de datos (solo Postgres por ahora)

Generación de políticas

Generate policy from latest session

Generate with custom name and threshold

Quick preview to stdout

Redirección de Red

Redirección DNS

Opciones

Soporte de Plataformas

Casos de Uso

Filtrado de Señales

Soporte de Plataformas

Ejemplo de Reglas de Señales```yaml

Allow signals to self and children

Redirect SIGKILL to graceful SIGTERM

Block fatal signals to external processes