agentsh

Nota per macOS: l'applicazione nativa delle policy su macOS tramite ESF (Endpoint Security Framework) + NE (Network Extension) è in Alpha. Funziona end-to-end — gli eventi di file, processi e rete fluiscono dall'estensione di sistema al motore policy Go — ma aspettatevi spigoli da rifinire e modifiche sostanziali tra le release. Per l'uso in produzione oggi raccomandiamo Linux.

Nota per Windows: stiamo lavorando per far firmare i driver minifilter. Fino ad allora, per l'uso in produzione è pienamente supportata solo la modalità WSL2 di Windows.

Gateway di esecuzione sicuro e controllato da policy per agenti AI.

agentsh si posiziona sotto il tuo agente/strumentazione — intercettando le attività su file, rete, processi e segnali (inclusi gli alberi dei sottoprocessi), applicando la policy che definisci ed emettendo eventi di audit strutturati.

Nota sulle piattaforme: Linux offre l'applicazione completa delle policy (punteggio di sicurezza 100%). macOS ESF+NE (punteggio 90%) è in Alpha — funzionale ma non pronto per la produzione. Windows WSL2 offre la stessa applicazione completa equivalente a Linux (punteggio 100%); il supporto nativo di Windows tramite driver minifilter + AppContainer (punteggio 85%) è in attesa della firma del driver. Consulta la Matrice di confronto piattaforme per i dettagli.

Cos'è agentsh?

Endpoint shell/exec sostitutivo che trasforma ogni comando (e i suoi sottoprocessi) in eventi auditabili.
Motore di policy per operazione: allow, deny, approve (approvazione umana), soft_delete o redirect.
Visibilità I/O completa:
- apertura/lettura/scrittura/eliminazione file
- connessioni di rete + DNS
- avvio/uscita processi
- attività PTY
- richieste API LLM con DLP e monitoraggio utilizzo
- traffico database di famiglia Postgres tramite db_services dichiarati
- invio/blocco segnali (applicato su Linux, solo audit su macOS/Windows)
- query di database tramite il proxy PostgreSQL integrato — classificazione e policy per singola istruzione
- instradamento delle chiamate API HTTP in uscita tramite servizi dichiarati (http_services) con regole per metodo e per percorso, gating di approvazione e applicazione host fail-closed
Due modalità di output:
- output shell leggibile per l'uomo
- risposte JSON compatte per agenti/strumenti

Perché agentsh?

I flussi di lavoro degli agenti prima o poi eseguono codice arbitrario (pip install, make test, python script.py). I controlli tradizionali del tipo "chiedi approvazione prima di eseguire un comando" si fermano al confine dello strumento e non possono vedere cosa succede dentro quel comando.

agentsh applica la policy a runtime, quindi il lavoro nascosto svolto dai sottoprocessi rimane governato, registrato e (quando richiesto) approvato.

Blocchi significativi: deny → redirect (il superpotere dello "steering")

La maggior parte dei sistemi può negare un'azione. agentsh può anche reindirizzarla (redirect).

Questo significa che quando un agente prova l'approccio sbagliato (o aggiramenti brute-force), la policy può guidarlo verso la strada giusta sostituendo il comando e restituendo indicazioni — mantenendo l'agente sulla strada asfaltata e riducendo i tentativi sprecati.

Esempio: reindirizzare curl verso un wrapper auditato```yaml command_rules:

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

**Esempio: reindirizza le scritture fuori dall'area di lavoro di nuovo al suo interno**```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"

L'agente vede un'operazione riuscita (non un errore), ma sei tu a controllare dove finiscono effettivamente le cose.

Containers + agentsh: meglio insieme

I container isolano la superficie host; agentsh aggiunge visibilità e policy di runtime all'interno del container.

Audit per operazione (file, rete, comandi) mostra cosa è successo durante installazioni/build/test.
Approvazioni e regole persistono tra shell di lunga durata e alberi di sottoprocessi, non solo il primo comando.
Controlli a livello di percorso su workspace/cache/credenziali montati; i container non offrono nativamente questa granularità.
Stesso comportamento su host e nei container, così CI e sviluppo locale vedono gli stessi esiti delle policy.

Avvio rapido

Installazione

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

Questa installa il bundle dell'app AgentSH con l'estensione di sistema ESF+NE. Dopo l'installazione ti verrà chiesto di approvare l'estensione di sistema in **Impostazioni di Sistema > Generali > Elementi di Accesso ed Estensioni**.

**Linux (da una Release di GitHub)**

Scarica il file `.deb`, `.rpm` o `.apk` per la tua piattaforma dalla [pagina delle release](https://github.com/erans/agentsh/releases).```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

Dalla sorgente (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

**Dai sorgenti (macOS)**```bash
# ESF+NE mode (full enforcement — Alpha, requires Xcode 15+)
make build-macos-enterprise

Vedi Guida alla build di macOS per istruzioni dettagliate di build su macOS.

Esegui 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

---

### Controlla cosa viene applicato

`agentsh detect` esamina l'host e riporta quali primitive di enforcement sono effettivamente disponibili — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — raggruppate in punteggi di protezione per dominio oltre alla modalità di sicurezza selezionata. Su host ristretti (Daytona, E2B, classe Firecracker) in cui il listener user-notify di seccomp non può essere installato, riporta la modalità che verrà *effettivamente* applicata anziché quella che il kernel supporta soltanto.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

Consulta Modalità di sicurezza per la matrice delle modalità e i parametri di regolazione.

Di' al tuo agente di usarlo (snippet 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)

---

### Avvio automatico (nessun passaggio manuale del daemon)

Non è **necessario** avviare `agentsh server` manualmente.

* La prima esecuzione di `agentsh exec` (o qualsiasi `/bin/sh`/`/bin/bash` con shim) avvierà automaticamente un server locale usando `configs/server-config.yaml` (o `AGENTSH_CONFIG` se impostato).
* Questo server mantiene attivi il layer FUSE e il motore delle policy per l'intera durata della sessione; i comandi successivi lo riutilizzano.
* Imposta `AGENTSH_NO_AUTO=1` se vuoi gestire manualmente il ciclo di vita del server.

---

## Utilizzo in Docker (con lo shim della shell)

Vedi `Dockerfile.example` per un'immagine minima basata su Debian.

All'interno dell'immagine, installa un pacchetto di release (oppure copia la tua build), quindi attiva lo shim:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

Punta lo shim verso il tuo server (sidecar o host):```dockerfile ENV AGENTSH_SERVER=http://127.0.0.1:18080

Ora ogni `/bin/sh -c ...` o `/bin/bash -lc ...` nel container viene instradato tramite agentsh.

### Applicazione in modalità non interattiva

Per impostazione predefinita, lo shim bypassa la policy quando stdin non è un TTY (preservando i dati binari per i comandi tramite pipe). Su piattaforme in cui i comandi sono sempre non interattivi ma necessitano comunque di applicazione (ad es. exe.dev, sandbox APIs), aggiungere `--force`:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --force \
  --i-understand-this-modifies-the-host

Questo scrive /etc/agentsh/shim.conf con force=true, che lo shim legge all'avvio. Il file di configurazione funziona indipendentemente da come viene avviata la shell (a differenza delle variabili d'ambiente o degli script di profilo). AGENTSH_SHIM_FORCE=1 nell'ambiente del processo ottiene lo stesso effetto per processo.

Schema consigliato: esegui agentsh come sidecar (o PID 1) nello stesso pod/servizio e condividi un volume di lavoro; lo shim garantisce che ogni passaggio di shell rimanga sotto le policy.

Modello di policy

Decisioni

allow
deny
approve (approvazione umana)
redirect (sostituisci un comando)
audit (consenti + registra)
soft_delete (metti in quarantena le eliminazioni con ripristino)

Ambiti

operazioni sui file
comandi
variabili d'ambiente
rete (DNS/connect)
database (istruzioni SQL tramite il proxy PostgreSQL)
impostazioni PTY/sessione
servizi HTTP dichiarati

Valutazione

vince la prima regola corrispondente

Le regole risiedono in una policy denominata; le sessioni scelgono una policy.

Predefiniti:

config di esempio: configs/server-config.yaml
policy predefinita: configs/policies/default.yaml
override via env: imposta AGENTSH_POLICY_NAME su un nome di policy consentito (senza suffisso). Se non impostato/non valido/non consentito, viene usata quella predefinita.
env policy: configura policies.env_policy (allow/deny, max_bytes, max_keys, block_iteration) e override env_* per comando nei file di policy. Un'allowlist vuota prevede per impostazione predefinita un ambiente minimale (PATH/LANG/TERM/HOME) con una deny list integrata per i segreti; imposta block_iteration per nascondere l'iterazione dell'env (richiede l'env shim).
allowlist: configura policies.allowed in config.yml; vuoto significa che è consentita solo la policy predefinita.
integrità opzionale: imposta policies.manifest_path su un manifest SHA256 per verificare i file di policy al momento del caricamento.

Riferimento rapido alla policy dell'ambiente

Predefiniti: senza env_allow, agentsh costruisce un ambiente minimale (PATH/LANG/TERM/HOME) e rimuove le chiavi segrete integrate.
Override: env_allow/env_deny per comando più env_max_keys/env_max_bytes limitano e filtrano l'ambiente del processo figlio al momento dell'exec.
Blocco iterazione: env_block_iteration: true (globale o per regola) nasconde l'enumerazione dell'ambiente; imposta policies.env_shim_path su libenvshim.so così agentsh inietta LD_PRELOAD + AGENTSH_ENV_BLOCK_ITERATION=1.
Limiti: errori se i limiti vengono superati; il builder dell'env viene applicato prima dell'exec per ogni comando.
env_inject: variabili d'ambiente ritenute affidabili dall'operatore, iniettate in tutti i comandi, bypassando il filtraggio della policy. Uso principale: BASH_ENV per disabilitare le builtin della shell che bypassano seccomp. Configura in (globale) o a livello di policy (sovrascrive il globale).

Regole di esempio (abbreviate)```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

### Utilizzo di una policy```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

Autenticazione

agentsh supporta più metodi di autenticazione:

Tipo	Caso d'uso
`api_key`	Distribuzioni semplici con chiavi statiche
`oidc`	SSO aziendale (Okta, Azure AD, ecc.)
`hybrid`	Entrambi i metodi accettati

Modalità di approvazione per la verifica con intervento umano:

local_tty - Prompt del terminale (predefinito)
totp - Codici di app authenticator
webauthn - Chiavi di sicurezza hardware (YubiKey)
api - Approvazione remota tramite REST

Vedi SECURITY.md per i dettagli di configurazione.

Sicurezza MCP

Whitelisting degli strumenti: Controlla quali strumenti MCP possono essere invocati tramite policy di allowlist/denylist
Version Pinning: Rileva le modifiche alle definizioni degli strumenti (protezione da rug pull) con risposte configurabili
Rilevamento Cross-Server: Blocca i pattern di esfiltrazione dei dati (lettura dal Server A → invio tramite Server B)
Rate Limiting: Rate limiting a token bucket per server MCP e domini di rete

Vedi SECURITY.md per tutte le opzioni di configurazione, oppure esegui la MCP Protection Demo per vedere queste rilevazioni in azione.

Demo in 60 secondi

Il modo più rapido per "capirlo" è eseguire qualcosa che genera sottoprocessi e accede a filesystem/rete.```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

**Cosa vedrai nell'output JSON:**
- `exit_code`: lo stato di uscita del comando
- `stdout` / `stderr`: output catturato
- `events[]`: ogni operazione su file/reti/processi con decisioni delle policy
- `policy.decision`: `allow`, `deny`, `approve` o `redirect`

Suggerimento: tieni aperto un terminale con `--output json` quando testi le policy—rende evidente cosa viene toccato.

---

### Report delle sessioni

Genera report markdown che riassumono l'attività della sessione:```bash
# Quick summary
agentsh report latest --level=summary

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

I report includono:

Riepilogo delle decisioni (consentito, bloccato, reindirizzato)
Rilevamento automatico dei riscontri (violazioni, anomalie)
Suddivisione delle attività per categoria
Timeline completa degli eventi (modalità dettagliata)

Vedi la Guida all'integrazione CI/CD per esempi di pipeline.

Checkpoint del workspace

Crea snapshot dello stato del workspace per il ripristino da operazioni distruttive:```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:** Quando abilitato, agentsh crea automaticamente checkpoint prima dei comandi rischiosi (`rm`, `mv`, `git reset`, `git checkout`, ecc.). Configura in `sessions.checkpoints.auto_checkpoint`.

Consulta [SECURITY.md](https://github.com/canyonroad/agentsh/blob/main/SECURITY.md#checkpoint-and-rollback) per le opzioni di configurazione complete.

---

### Proxy LLM e DLP

agentsh include un proxy integrato che intercetta tutte le richieste API LLM provenienti dagli agenti:```bash
# Check proxy status for a session
agentsh proxy status <session-id>

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

Funzionalità:

Instradamento automatico: Imposta ANTHROPIC_BASE_URL e OPENAI_BASE_URL così gli SDK degli agenti instradano le richieste attraverso il proxy
Provider personalizzati: Instrada verso LiteLLM, Azure OpenAI, vLLM o gateway aziendali
Redazione DLP: La PII (email, numeri di telefono, chiavi API, ecc.) viene oscurata prima di raggiungere i provider LLM
Pattern personalizzati: Definisci pattern specifici dell'organizzazione per dati sensibili
Monitoraggio dell'utilizzo: Conteggi dei token estratti e registrati per l'attribuzione dei costi
Traccia di audit: Tutte le richieste/risposte registrate nell'archivio di sessione

Configurazione del provider:```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

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

Vedi Documentazione del proxy LLM per le opzioni di configurazione complete.

Lo stesso proxy instrada anche le voci http_services dichiarate — upstream API con nome e regole per-metodo e per-percorso. Vedi Servizi HTTP dichiarati e il Cookbook dei servizi HTTP per i dettagli.

Controllo degli accessi al database (solo Postgres oggi)

agentsh può applicare policy sui servizi di database dichiarati tramite db_services, database_connection_rules e database_rules. L'implementazione attuale riguarda solo la famiglia Postgres: PostgreSQL è il target supportato, con Aurora Postgres che utilizza lo stesso percorso e Redshift/CockroachDB trattati come dialetti compatibili con Postgres con copertura beta. MySQL, MongoDB, Snowflake, BigQuery, Databricks, ClickHouse, MSSQL, Cassandra, Redis e Oracle sono elementi della roadmap, non supporto runtime attuale.

Il supporto Postgres attuale include:

Decisioni di connessione allow/deny/approve/audit.
Classificazione delle istruzioni per PostgreSQL wire protocol v3, incluse Simple Query, Extended Query, istruzioni preparate SQL, COPY, negazione di FunctionCall, stato della transazione e mappatura di CancelRequest.
Copertura rigorosa delle policy per oggetto con precedenza del deny.
Selettori di relazione/funzione basati su catalogo per policy di oggetti risolti.
redirect runtime sicuro per la sostituzione di relazioni Postgres in sola lettura.
Rilevamento del bypass e copertura E2E Docker con Postgres reale in CI.

Il runtime del proxy Postgres è oggi codice in-process solo per Linux. Usa Linux nativo, WSL2 o un ambiente VM Linux per l'applicazione delle policy sul database.

Vedi Controllo degli accessi al database e Documentazione delle policy.

Generazione delle policy

Genera policy restrittive dal comportamento delle sessioni osservato (workflow "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 policy generata:
- Consente solo le operazioni osservate durante la sessione
- Raggruppa i percorsi in glob quando molti file si trovano nella stessa directory
- Riduce i sottodomini in wildcard (es., `*.github.com`)
- Contrassegna i comandi rischiosi (curl, wget, rm) con pattern di argomenti
- Include le operazioni bloccate come regole commentate per la revisione

**Casi d'uso:**
- **Blocco CI/CD**: Profila un'esecuzione di build/test, blocca le esecuzioni future a quel comportamento
- **Sandboxing degli agenti**: Lascia che un agente AI esegua un compito, genera una policy per le esecuzioni future
- **Profilazione dei container**: Profila un carico di lavoro, genera una policy minima per la produzione

---

## Accesso al Database (PostgreSQL)

agentsh include un **proxy PostgreSQL** integrato che rende l'accesso al database consapevole dell'agente e governato dalle policy. Parla il protocollo wire di Postgres, classifica ogni istruzione in un elenco di *effetti* (letture, scritture, DDL, DCL, controllo di transazioni/sessioni, `COPY`/export in blocco, …), e valuta ogni effetto rispetto a `database_rules` prima di inoltrarlo a monte — così un `UPDATE`, un `DROP`, o una `DELETE` senza ambito vengono governati allo stesso modo di una scrittura di file o di una connessione di rete.

- **Valutazione per-effetto e multi-oggetto** — le regole sono di tipo collect-all / **any-deny-wins** (decide il verbo più restrittivo), non first-match.
- **Decisioni:** `allow`, `deny`, `approve` (approvazione umana), `audit` e `redirect` a livello di istruzione.
- **Guardia `require_where`** — rifiuta `UPDATE`/`DELETE` di primo livello prive di clausola `WHERE`.
- **Regole a livello di connessione** (`database_connection_rules`) determinano quali sessioni possono raggiungere quale `db_service` dichiarato.
- **Eventi di audit di autenticazione e istruzioni** per ogni connessione e query; il logging del testo delle istruzioni è configurabile (`policies.db.log_statements: none | parameters_redacted | full`).

La Fase 1 copre il protocollo wire di PostgreSQL v3 (dialetti: `postgres`, `aurora_postgres`; `redshift` / `cockroachdb` in beta). Le connessioni di replica e quelle crittografate con GSSAPI sono in default-deny.```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}}"

Vedi la specifica di controllo accessi al database per la tassonomia completa delle operazioni, il modello degli effetti, le regole di connessione e il modello di minaccia di inevitabilità.

Reindirizzamento di rete

agentsh può reindirizzare in modo trasparente le connessioni DNS e TCP, consentendo casi d'uso come l'instradamento delle chiamate API attraverso proxy aziendali o il cambio di provider AI senza modifiche al codice.

Reindirizzamento DNS

Intercetta la risoluzione DNS e restituisce gli indirizzi IP configurati:```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

### Connect Redirect

Reindirizza le connessioni TCP verso destinazioni diverse con gestione TLS opzionale:```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

Opzioni

Supporto Piattaforme

Casi d'uso

API Gateway Routing: Instrada le chiamate Anthropic/OpenAI attraverso il gateway LLM aziendale
Provider Switching: Reindirizza l'API Claude a GCP Vertex AI o Azure OpenAI
Testing: Reindirizza le API di produzione verso server mock
Compliance: Forza tutto il traffico LLM attraverso proxy di audit

Filtraggio dei Segnali

agentsh intercetta i segnali (kill, SIGTERM, ecc.) inviati tra processi, fornendo un controllo basato su policy su quali segnali possono raggiungere quali destinazioni.

Supporto Piattaforme

Esempio di Regole sui Segnali```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` - Tutti i segnali (1-31)
- `@fatal` - SIGKILL, SIGTERM, SIGQUIT, SIGABRT
- `@job` - SIGSTOP, SIGCONT, SIGTSTP, SIGTTIN, SIGTTOU
- `@reload` - SIGHUP, SIGUSR1, SIGUSR2

### Target Types

- `self` - Processo che segnala se stesso
- `children` - Processi figli diretti
- `descendants` - Tutti i processi discendenti
- `session` - Qualsiasi processo nella sessione agentsh
- `external` - PID al di fuori della sessione
- `system` - PID 1 e thread del kernel

Vedi la [Documentazione delle policy](https://github.com/canyonroad/agentsh/blob/main/docs/operations/policies.md#signal-rules) per le opzioni di configurazione complete.

---

## Monitoraggio I/O file su macOS

Su macOS, agentsh monitora l'I/O dei file utilizzando l'Endpoint Security Framework (ESF), sottoscrivendo sia gli eventi AUTH che NOTIFY. Le operazioni tracciate includono apertura, creazione, eliminazione, rinomina e scrittura dei file (rilevata tramite close-modified) e, su macOS 26+, chmod e chown tramite eventi di modifica degli attributi. Ogni evento di file viene attribuito alla sessione e al comando di origine tramite risoluzione basata su PID, fornendo audit trail completi attraverso gli alberi dei sottoprocessi.

ESF fornisce applicazione allow/deny a livello di kernel ma non supporta l'intercettazione trasparente dei file come Linux FUSE. Le azioni di policy che richiedono intercettazione -- come `redirect` (riscrittura del percorso) e `soft_delete` (quarantena) -- sono implementate come deny + guida: l'operazione viene bloccata a livello ESF e l'agente riceve istruzioni per riprovare con il percorso corretto o per riconoscere che il file è protetto. Vedi il [documento sull'architettura macOS ESF+NE](https://github.com/canyonroad/agentsh/blob/main/docs/macos-esf-ne-architecture.md) per i dettagli dello stream di eventi e la [documentazione delle policy](https://github.com/canyonroad/agentsh/blob/main/docs/operations/policies.md#file-rule-actions-on-macos-esf) per il comportamento di ciascuna azione.

---

## Pacchetti di policy iniziali

Hai già una policy predefinita (`configs/policies/default.yaml`). Questi pacchetti orientati sono disponibili come file separati, così i team possono sceglierne uno:

* **[`policies/dev-safe.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/dev-safe.yaml)**: sicuro per lo sviluppo locale
  * consenti lettura/scrittura nell'area di lavoro
  * approva le eliminazioni nell'area di lavoro
  * nega `~/.ssh/**`, `/root/.ssh/**`
  * limita la rete a domini/porte in allowlist

* **[`policies/ci-strict.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/ci-strict.yaml)**: sicuro per i runner CI
  * nega qualsiasi cosa al di fuori dell'area di lavoro
  * nega il traffico di rete in uscita tranne i registry di artefatti
  * nega le shell interattive a meno che non siano esplicitamente consentite
  * registra tutto (eventi di riepilogo)

* **[`policies/agent-sandbox.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/agent-sandbox.yaml)**: modalità "l'agente esegue codice sconosciuto"
  * deny di default + allowlist esplicita
  * approva qualsiasi accesso a credenziali/percorsi
  * reindirizza l'uso degli strumenti di rete verso proxy/mirror interni
  * soft-delete delle operazioni distruttive per un facile recupero

---

## Esempi di integrazione con assistenti AI

Frammenti pronti all'uso per configurare gli assistenti di codifica AI affinché utilizzino agentsh:

* **[Claude Code](https://github.com/canyonroad/agentsh/blob/main/examples/claude)** - frammento CLAUDE.md per l'integrazione con Claude Code
* **[Cursor](https://github.com/canyonroad/agentsh/blob/main/examples/cursor)** - regole di Cursor per l'integrazione con agentsh
* **[AGENTS.md](https://github.com/canyonroad/agentsh/blob/main/examples/agents)** - frammento AGENTS.md generico (funziona con più strumenti AI)

> **Nota:** Questi esempi sono pensati per scenari di sviluppo locale in cui eseguire l'agente AI all'interno di un container non è pratico. Per ambienti di produzione o CI/CD, è preferibile eseguire gli agenti in container con lo shell shim installato—vedi [Uso in Docker](#use-in-docker-with-the-shell-shim).

---

## Riferimenti

* **Demo di protezione MCP:** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - demo dal vivo di rilevamento dell'esfiltrazione cross-server, blocco dei rug pull e generazione di policy
* **Modello di sicurezza e minacce:** [`SECURITY.md`](https://github.com/canyonroad/agentsh/blob/main/SECURITY.md) - cosa protegge agentsh, limitazioni note, checklist per gli operatori
* **KMS esterno:** [`SECURITY.md#external-kms-integration`](https://github.com/canyonroad/agentsh/blob/main/SECURITY.md#external-kms-integration) - AWS KMS, Azure Key Vault, HashiCorp Vault, GCP Cloud KMS per le chiavi di integrità degli audit
* Modello di configurazione: [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/server-config.yaml)
* Policy predefinita: [`configs/policies/default.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/default.yaml)
* Dockerfile di esempio (con shim): [`Dockerfile.example`](https://github.com/canyonroad/agentsh/blob/main/Dockerfile.example)
* **Documentazione delle policy:** [`docs/operations/policies.md`](https://github.com/canyonroad/agentsh/blob/main/docs/operations/policies.md) - variabili di policy, regole dei segnali, reindirizzamento di rete
* **Controllo degli accessi al database:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/main/docs/agentsh-db-access-spec.md) - ambito di enforcement del database solo Postgres, semantica delle policy, comportamento di redirect e roadmap
* **Ricettario delle policy dei comandi:** [`docs/cookbook/command-policies.md`](https://github.com/canyonroad/agentsh/blob/main/docs/cookbook/command-policies.md) - come consentire un nuovo binario, quando usare `wrap` invece di `exec` e come eseguire il debug di una negazione
* **Ricettario dei servizi HTTP:** [`docs/cookbook/http-services.md`](https://github.com/canyonroad/agentsh/blob/main/docs/cookbook/http-services.md) - ricette per instradare le chiamate API HTTP in uscita attraverso servizi dichiarati con regole e gating delle approvazioni
* **Ricettario delle integrazioni Sandbox SDK:** [`docs/cookbook/sandbox-sdk-integrations.md`](https://github.com/canyonroad/agentsh/blob/main/docs/cookbook/sandbox-sdk-integrations.md) - configurazione `shim_install` per Tensorlake / E2B / Modal / Daytona, dove i comandi vengono eseguiti come processi fratelli del server agentsh
* **Skill per la creazione di policy:** [`skills/`](https://github.com/canyonroad/agentsh/blob/main/skills) - skill per assistenti AI per creare e modificare policy in Claude Code, NanoClaw, ecc.
* **Confronto tra piattaforme:** [`docs/platform-comparison.md`](https://github.com/canyonroad/agentsh/blob/main/docs/platform-comparison.md) - supporto delle funzionalità, punteggi di sicurezza, prestazioni per piattaforma
* **Bubblewrap vs agentsh:** [`docs/bubblewrap-vs-agentsh-comparison.md`](https://github.com/canyonroad/agentsh/blob/main/docs/bubblewrap-vs-agentsh-comparison.md) - confronto con Bubblewrap per il sandboxing dei container Linux
* **Controllo degli accessi al database:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/main/docs/agentsh-db-access-spec.md) - tassonomia del proxy PostgreSQL, modello degli effetti, `database_rules`, regole di connessione, modello delle minacce
* **Modalità di sicurezza e `detect`:** [`docs/security-modes.md`](https://github.com/canyonroad/agentsh/blob/main/docs/security-modes.md) - modalità di enforcement, punteggio di protezione e cosa riporta `agentsh detect`
* **seccomp:** [`docs/seccomp.md`](https://github.com/canyonroad/agentsh/blob/main/docs/seccomp.md) - filtraggio delle syscall, intercettazione di execve e blocco delle famiglie di socket
* **Modalità ptrace:** [`docs/ptrace-support.md`](https://github.com/canyonroad/agentsh/blob/main/docs/ptrace-support.md) - enforcement PTRACE_SEIZE per container ristretti (`attach_mode`, prefiltro seccomp)
* **eBPF:** [`docs/ebpf.md`](https://github.com/canyonroad/agentsh/blob/main/docs/ebpf.md) - tracciamento di rete e enforcement delle policy tramite eBPF
* **Proxy LLM e DLP:** [`docs/llm-proxy.md`](https://github.com/canyonroad/agentsh/blob/main/docs/llm-proxy.md) - configurazione del proxy integrato, pattern DLP, tracciamento dell'uso
* **Guida alla build su macOS:** [`docs/macos-build.md`](https://github.com/canyonroad/agentsh/blob/main/docs/macos-build.md) - istruzioni di build ESF+NE
* **Architettura macOS ESF+NE:** [`docs/macos-esf-ne-architecture.md`](https://github.com/canyonroad/agentsh/blob/main/docs/macos-esf-ne-architecture.md) - System Extension, XPC e dettagli di distribuzione
* **Sandbox XPC su macOS:** [`docs/macos-xpc-sandbox.md`](https://github.com/canyonroad/agentsh/blob/main/docs/macos-xpc-sandbox.md) - controllo XPC/Mach IPC per i processi in sandbox
* Variabili d'ambiente (tutti gli override `AGENTSH_*`, toggle di avvio automatico, selezione del trasporto): [`docs/spec.md` §15.3 "Environment Variables"](https://github.com/canyonroad/agentsh/blob/main/docs/spec.md#153-environment-variables)
* Architettura e flusso dei dati (FUSE + motore delle policy + API): commenti inline in [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/server-config.yaml) e [`internal/netmonitor`](https://github.com/canyonroad/agentsh/blob/main/internal/netmonitor)
* Aiuto CLI: `agentsh --help`, `agentsh exec --help`, `agentsh shim --help`

---

Creato con l'aiuto di agenti per agenti.

`visibility`	`silent`, `audit_only`, `warn`	Come vengono registrate/mostrate le regole di reindirizzamento
`on_failure`	`fail_closed`, `fail_open`, `retry_original`	Cosa succede se il reindirizzamento fallisce
`tls_mode`	`passthrough`, `rewrite_sni`	Gestione TLS per il reindirizzamento dei connect

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

Linux	Sì (seccomp user-notify)	Sì	Sì
macOS	No	No	Sì (ES)
Windows	Parziale	No	Sì (ETW)

Più Popolari

agentsh

agentsh

Cos'è agentsh?

Perché agentsh?

Blocchi significativi: deny → redirect (il superpotere dello "steering")

Containers + agentsh: meglio insieme

Avvio rapido

Installazione

Esegui localmente```bash

Start the server (optional if using autostart)

Create a session and run a command (shell output)

Structured output for agents

Di' al tuo agente di usarlo (snippet AGENTS.md / CLAUDE.md)```md

Shell access

Modello di policy

Decisioni

Ambiti

Valutazione

Riferimento rapido alla policy dell'ambiente

Regole di esempio (abbreviate)```yaml

Autenticazione

Sicurezza MCP

Demo in 60 secondi

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

Checkpoint del workspace

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

Controllo degli accessi al database (solo Postgres oggi)

Generazione delle policy

Generate policy from latest session

Generate with custom name and threshold

Quick preview to stdout

Reindirizzamento di rete

Reindirizzamento DNS

Opzioni

Supporto Piattaforme

Casi d'uso

Filtraggio dei Segnali

Supporto Piattaforme

Esempio di Regole sui Segnali```yaml

Allow signals to self and children

Redirect SIGKILL to graceful SIGTERM

Block fatal signals to external processes