agentsh

Note macOS : La mise en œuvre native macOS via ESF (Endpoint Security Framework) + NE (Network Extension) est en version Alpha. Elle fonctionne de bout en bout — les événements de fichiers, de processus et de réseau transitent par l'extension système vers le moteur de politique Go — mais attendez-vous à des aspérités et des changements cassants entre les versions. Pour une utilisation en production aujourd'hui, nous recommandons Linux.

Note Windows : Nous travaillons à faire signer les pilotes minifilter. D'ici là, seul le mode Windows WSL2 est entièrement pris en charge pour une utilisation en production.

Passerelle d'exécution sécurisée et supervisée par des politiques pour les agents IA.

agentsh se place sous votre agent/outillage — interceptant les activités fichier, réseau, processus et signal (y compris les arborescences de sous-processus), appliquant la politique que vous définissez et émettant des événements d'audit structurés.

Note plateforme : Linux offre une application complète (score de sécurité 100 %). macOS ESF+NE (score 90 %) est en Alpha — fonctionnel mais pas prêt pour la production. Windows WSL2 offre une application équivalente à Linux (score 100 %) ; le Windows natif via pilote minifilter + AppContainer (score 85 %) est en attente de signature de pilote. Voir la Matrice de comparaison des plateformes pour plus de détails.

Qu'est-ce que agentsh ?

Point de terminaison shell/exec enfichable qui transforme chaque commande (et ses sous-processus) en événements audités.
Moteur de politique par opération : allow, deny, approve (approbation humaine), soft_delete ou redirect.
Visibilité complète des E/S :
- ouverture/lecture/écriture/suppression de fichiers
- connexion réseau + DNS
- démarrage/arrêt de processus
- activité PTY
- requêtes API LLM avec DLP et suivi d'utilisation
- trafic de base de données de type Postgres via les db_services déclarées
- envoi/blocage de signaux (appliqué sur Linux, audit sur macOS/Windows)
- requêtes de base de données via le proxy PostgreSQL intégré — classification par instruction et politique
- Acheminer les appels API HTTP sortants via les services déclarés (http_services) avec des règles par méthode, par chemin, contrôle d'approbation et application hôte en échec-fermé
Deux modes de sortie :
- sortie shell lisible par l'humain
- réponses JSON compactes pour agents/outils

Pourquoi agentsh ?

Les workflows d'agents exécutent finalement du code arbitraire (pip install, make test, python script.py). Les contrôles traditionnels « demander une approbation avant d'exécuter une commande » s'arrêtent à la limite de l'outil et ne peuvent pas voir ce qui se passe à l'intérieur de cette commande.

agentsh applique la politique à l'exécution, de sorte que le travail caché effectué par les sous-processus est toujours régi, journalisé et (le cas échéant) approuvé.

Blocs significatifs : deny → redirect (le superpouvoir d'« orientation »)

La plupart des systèmes peuvent refuser une action. agentsh peut aussi la rediriger.

Cela signifie que lorsqu'un agent tente la mauvaise approche (ou des solutions de contournement par force brute), la politique peut l'orienter vers le bon chemin en échangeant la commande et en renvoyant des instructions — maintenant l'agent sur la voie pavée et réduisant les tentatives inutiles.

Exemple : rediriger curl vers un wrapper audité```yaml command_rules:

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

**Exemple : rediriger les écritures en dehors de l'espace de travail vers l'intérieur**```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'agent voit une opération réussie (pas une erreur), mais vous contrôlez où les choses aboutissent réellement.

Conteneurs + agentsh : mieux ensemble

Les conteneurs isolent la surface de l'hôte ; agentsh ajoute une visibilité et une politique d'exécution dans le conteneur.

Audit par opération (fichiers, réseau, commandes) montre ce qui s'est passé pendant les installations/constructions/tests.
Les approbations et les règles persistent à travers les shells de longue durée et les arbres de sous-processus — pas seulement la première commande.
Contrôles au niveau du chemin sur les espaces de travail montés/caches/credentials ; les conteneurs ne fournissent pas nativement cette granularité.
Même comportement sur l'hôte et dans les conteneurs, donc CI et dev local voient les mêmes résultats de politique.

Démarrage rapide

Installation

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

Cela installe le bundle d'applications AgentSH avec l'extension système ESF+NE. Après l'installation, il vous sera demandé d'approuver l'extension système dans **Réglages système > Général > Éléments de connexion et extensions**.

**Linux (à partir d'une version GitHub)**

Téléchargez le `.deb`, `.rpm` ou `.apk` pour votre plateforme depuis la [page des versions](https://github.com/erans/agentsh/releases).```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

Depuis les sources (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

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

Voir Guide de construction macOS pour des instructions détaillées de construction sur macOS.

Exécution locale```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

---

### Vérifier ce qui est appliqué

`agentsh detect` sonde l'hôte et rapporte quelles primitives d'application sont réellement disponibles — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — regroupées en scores de protection par domaine ainsi que le mode de sécurité sélectionné. Sur les hôtes restreints (Daytona, E2B, classe Firecracker) où l'écouteur seccomp user-notify ne peut pas s'installer, il rapporte le mode qui sera *réellement* appliqué plutôt que ce que le noyau supporte simplement.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

Voir Modes de sécurité pour la matrice des modes et les réglages fins.

Dites à votre agent de l'utiliser (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)

---

### Démarrage automatique (aucune étape manuelle du démon)

Vous n'avez **pas** besoin de démarrer `agentsh server` vous-même.

* Le premier `agentsh exec` (ou tout `/bin/sh`/`/bin/bash` pourvu d'un shim) lancera automatiquement un serveur local en utilisant `configs/server-config.yaml` (ou `AGENTSH_CONFIG` si défini).
* Ce serveur maintient la couche FUSE et le moteur de politique actifs pendant la durée de la session ; les commandes suivantes le réutilisent.
* Définissez `AGENTSH_NO_AUTO=1` si vous souhaitez gérer manuellement le cycle de vie du serveur.

---

## Utilisation dans Docker (avec le shim du shell)

Voir `Dockerfile.example` pour une image minimale basée sur Debian.

Dans l'image, installez un package de version (ou copiez votre build), puis activez le shim :```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

Pointez le shim vers votre serveur (sidecar ou hôte) :```dockerfile ENV AGENTSH_SERVER=http://127.0.0.1:18080

Désormais, toute commande `/bin/sh -c ...` ou `/bin/bash -lc ...` dans le conteneur transite par agentsh.

### Application non interactive

Par défaut, le shim contourne la politique lorsque stdin n'est pas un TTY (préservant les données binaires pour les commandes via pipe). Sur les plateformes où les commandes sont toujours non interactives mais nécessitent une application des règles (par ex., exe.dev, API sandbox), ajoutez `--force` :```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --force \
  --i-understand-this-modifies-the-host

Cela écrit /etc/agentsh/shim.conf avec force=true, que le shim lit au démarrage. Le fichier de configuration fonctionne indépendamment de la façon dont le shell est lancé (contrairement aux variables d'environnement ou aux scripts de profil). AGENTSH_SHIM_FORCE=1 dans l'environnement du processus produit le même effet par processus.

Modèle recommandé : exécuter agentsh en tant que sidecar (ou PID 1) dans le même pod/service et partager un volume de workspace ; le shim garantit que chaque saut de shell reste sous la politique.

Modèle de politique

Décisions

allow (autoriser)
deny (refuser)
approve (approbation humaine)
redirect (substituer une commande)
audit (autoriser + journaliser)
soft_delete (mettre en quarantaine les suppressions avec restauration)

Portées

opérations sur les fichiers
commandes
variables d'environnement
réseau (DNS/connect)
base de données (instructions SQL via le proxy PostgreSQL)
paramètres PTY/session
services HTTP déclarés

Évaluation

la première règle correspondante l'emporte

Les règles vivent dans une politique nommée ; les sessions choisissent une politique.

Valeurs par défaut :

exemple de configuration : configs/server-config.yaml
politique par défaut : configs/policies/default.yaml
surcharge par env : définir AGENTSH_POLICY_NAME sur un nom de politique autorisé (sans suffixe). Si non défini/invalide/interdit, la valeur par défaut est utilisée.
politique d'environnement : configurer policies.env_policy (allow/deny, max_bytes, max_keys, block_iteration) et les surcharges env_* par commande dans les fichiers de politique. Une liste d'autorisation vide par défaut donne un PATH/LANG/TERM/HOME minimal avec une liste de refus de secrets intégrée ; définir block_iteration pour masquer l'itération d'environnement (nécessite le shim d'environnement).
liste d'autorisation : configurer policies.allowed dans config.yml ; vide signifie que seule la valeur par défaut est autorisée.
intégrité optionnelle : définir policies.manifest_path sur un manifeste SHA256 pour vérifier les fichiers de politique au chargement.

Référence rapide de la politique d'environnement

Valeurs par défaut : Sans env_allow, agentsh construit un environnement minimal (PATH/LANG/TERM/HOME) et supprime les clés secrètes intégrées.
Surcharges : env_allow/env_deny par commande plus env_max_keys/env_max_bytes limitent et filtrent l'environnement enfant au moment de l'exécution.
Blocage d'itération : env_block_iteration: true (global ou par règle) masque l'énumération de l'environnement ; définir policies.env_shim_path sur libenvshim.so pour que agentsh injecte LD_PRELOAD + AGENTSH_ENV_BLOCK_ITERATION=1.
Limites : Erreur si les limites sont dépassées ; le constructeur d'environnement est appliqué avant l'exécution pour chaque commande.
env_inject : Variables d'environnement de confiance de l'opérateur injectées dans toutes les commandes, contournant le filtrage de la politique. Utilisation principale : BASH_ENV pour désactiver les builtins du shell qui contournent seccomp. Configurer dans (global) ou au niveau de la politique (remplace le global).

Exemples de règles (tronqués)```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

### Utilisation d'une politique```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

Authentification

agentsh prend en charge plusieurs méthodes d'authentification :

Type	Cas d'utilisation
`api_key`	Déploiements simples avec clés statiques
`oidc`	SSO d'entreprise (Okta, Azure AD, etc.)
`hybrid`	Les deux méthodes acceptées

Modes d'approbation pour la vérification humaine dans la boucle :

local_tty - Invite de terminal (par défaut)
totp - Codes d'application d'authentification
webauthn - Clés de sécurité matérielles (YubiKey)
api - Approbation à distance via REST

Voir SECURITY.md pour les détails de configuration.

Sécurité MCP

Liste blanche d'outils : Contrôler quels outils MCP peuvent être invoqués via des politiques allowlist/denylist
Épinglage de version : Détecter les changements de définition d'outil (protection contre les rug pulls) avec des réponses configurables
Détection inter-serveurs : Bloquer les schémas d'exfiltration de données (lire depuis le serveur A → envoyer via le serveur B)
Limitation de débit : Limitation de débit par seau à jetons pour les serveurs MCP et les domaines réseau

Voir SECURITY.md pour les options de configuration complètes, ou exécutez la Démonstration de protection MCP pour voir ces détections en action.

Démo en 60 secondes

La façon la plus rapide de « comprendre » est d'exécuter quelque chose qui lance des sous-processus et touche au système de fichiers/réseau.```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

**Ce que vous verrez dans la sortie JSON :**
- `exit_code`: le code de sortie de la commande
- `stdout` / `stderr`: sortie capturée
- `events[]`: chaque opération fichier/réseau/processus avec les décisions de politique
- `policy.decision`: `allow`, `deny`, `approve` ou `redirect`

Astuce : gardez un terminal ouvert avec `--output json` lors du test des politiques — cela rend évident ce qui est touché.

---

### Rapports de session

Générer des rapports Markdown résumant l'activité de la session :```bash
# Quick summary
agentsh report latest --level=summary

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

Rapports incluent :

Résumé de la décision (autorisé, bloqué, redirigé)
Détection automatique des constats (violations, anomalies)
Répartition des activités par catégorie
Chronologie complète des événements (mode détaillé)

Voir Guide d'intégration CI/CD pour des exemples de pipelines.

Points de contrôle de l'espace de travail

Créer des instantanés de l'état de l'espace de travail pour la récupération après des opérations destructrices :```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 :** Lorsque activé, agentsh crée automatiquement des points de contrôle avant les commandes risquées (`rm`, `mv`, `git reset`, `git checkout`, etc.). Configurez dans `sessions.checkpoints.auto_checkpoint`.

Voir [SECURITY.md](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#checkpoint-and-rollback) pour toutes les options de configuration.

---

### Proxy LLM et DLP

agentsh inclut un proxy intégré qui intercepte toutes les requêtes API LLM des agents :```bash
# Check proxy status for a session
agentsh proxy status <session-id>

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

Fonctionnalités :

Routage automatique : définit ANTHROPIC_BASE_URL et OPENAI_BASE_URL pour que les SDK des agents acheminent via le proxy
Fournisseurs personnalisés : achemine vers LiteLLM, Azure OpenAI, vLLM ou des passerelles d'entreprise
Rédaction DLP : les PII (emails, numéros de téléphone, clés API, etc.) sont masqués avant d'atteindre les fournisseurs LLM
Modèles personnalisés : définissez des modèles spécifiques à l'organisation pour les données sensibles
Suivi d'utilisation : les comptages de jetons sont extraits et journalisés pour l'attribution des coûts
Piste d'audit : toutes les demandes/réponses sont journalisées dans le stockage de session

Configuration des fournisseurs :```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

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

Voir la Documentation du proxy LLM pour les options de configuration complètes.

Le même proxy dispatche également les entrées http_services déclarées — des amonts API nommés avec des règles par méthode et par chemin. Voir Services HTTP déclarés et le Livre de recettes des services HTTP pour plus de détails.

Contrôle d'accès à la base de données (Postgres uniquement aujourd'hui)

agentsh peut appliquer des politiques sur les services de base de données déclarés via db_services, database_connection_rules et database_rules. L'implémentation actuelle est limitée à la famille Postgres : PostgreSQL est la cible prise en charge, avec Aurora Postgres utilisant le même chemin et Redshift/CockroachDB traités comme des dialectes compatibles Postgres avec une couverture bêta. MySQL, MongoDB, Snowflake, BigQuery, Databricks, ClickHouse, MSSQL, Cassandra, Redis et Oracle font partie de la feuille de route, pas du support d'exécution actuel.

La prise en charge actuelle de Postgres inclut :

Décisions de connexion (allow/deny/approve/audit).
Classification des instructions pour le protocole filaire PostgreSQL v3, incluant Simple Query, Extended Query, les instructions préparées SQL, COPY, le refus de FunctionCall, l'état des transactions et le mappage CancelRequest.
Couverture stricte des politiques par objet avec priorité au refus.
Sélecteurs de relation/fonction basés sur le catalogue pour les politiques d'objets résolus.
redirect sécurisé à l'exécution pour le remplacement de relation Postgres en lecture seule.
Détection de contournement et couverture E2E Docker Postgres réel dans le CI.

Le runtime du proxy Postgres est aujourd'hui un code intra-processus Linux uniquement. Utilisez un environnement Linux natif, WSL2 ou une VM Linux pour l'application des politiques de base de données.

Voir Contrôle d'accès à la base de données et Documentation des politiques.

Génération de politiques

Générer des politiques restrictives à partir du comportement observé des sessions (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 politique générée :
- Autorise uniquement les opérations observées durant la session
- Regroupe les chemins en globs lorsque plusieurs fichiers se trouvent dans le même répertoire
- Réduit les sous-domaines en caractères génériques (par ex., `*.github.com`)
- Marque les commandes risquées (curl, wget, rm) avec des motifs d'arguments
- Inclut les opérations bloquées sous forme de règles commentées pour révision

**Cas d'utilisation :**
- **Verrouillage CI/CD** : Profiler un cycle de build/test, verrouiller les exécutions futures à ce comportement
- **Sandboxing d'agent** : Laisser un agent IA exécuter une tâche, générer une politique pour les exécutions futures
- **Profilage de conteneur** : Profiler une charge de travail, générer une politique minimale pour la production

---

## Accès à la base de données (PostgreSQL)

agentsh inclut un **proxy PostgreSQL** intégré qui rend l'accès à la base de données conscient de l'agent et gouverné par des politiques. Il parle le protocole filaire Postgres, classe chaque instruction en une liste d'*effets* (lectures, écritures, DDL, DCL, contrôle de transaction/session, `COPY`/export en masse, …), et évalue chaque effet par rapport à `database_rules` avant de transmettre en amont — ainsi un `UPDATE`, `DROP`, ou `DELETE` sans portée est gouverné de la même manière qu'une écriture de fichier ou une connexion réseau.

- **Évaluation par effet et multi-objet** — les règles sont collect-all / **any-deny-wins** (le verbe le plus restrictif décide), pas first-match.
- **Décisions :** `allow`, `deny`, `approve` (OK humain), `audit`, et `redirect` au niveau de l'instruction.
- **Protection `require_where`** — refuse les `UPDATE`/`DELETE` de niveau supérieur sans clause `WHERE`.
- **Règles au niveau de la connexion** (`database_connection_rules`) contrôlent quelles sessions peuvent atteindre quel `db_service` déclaré.
- **Événements d'audit d'authentification + d'instruction** pour chaque connexion et requête ; la journalisation du texte des instructions est configurable (`policies.db.log_statements: none | parameters_redacted | full`).

La phase 1 couvre le protocole filaire PostgreSQL v3 (dialectes : `postgres`, `aurora_postgres` ; `redshift` / `cockroachdb` en version bêta). Les connexions de réplication et chiffrées par GSSAPI sont refusées par défaut.```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}}"

Consultez la spécification de contrôle d'accès à la base de données pour la taxonomie complète des opérations, le modèle des effets, les règles de connexion et le modèle de menace d'inévitabilité.

Redirection Réseau

agentsh peut rediriger de manière transparente les connexions DNS et TCP, permettant des cas d'utilisation tels que l'acheminement des appels API via des proxys d'entreprise ou le changement de fournisseur d'IA sans modification de code.

Redirection DNS

Intercepte la résolution DNS et renvoie les adresses IP configurées :```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

Rediriger les connexions TCP vers différentes destinations avec gestion TLS optionnelle :```yaml
connect_redirect:
  - match: "api.anthropic.com:443"
    redirect_to: "vertex-proxy.internal:8443"
    tls_mode: passthrough          # Forward encrypted traffic unchanged
    visibility: silent

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

Options

Prise en charge des plates-formes

Cas d'utilisation

Routage de passerelle API : Acheminer les appels Anthropic/OpenAI via la passerelle LLM d'entreprise
Changement de fournisseur : Rediriger l'API Claude vers GCP Vertex AI ou Azure OpenAI
Tests : Rediriger les API de production vers des serveurs mock
Conformité : Forcer tout le trafic LLM via des proxys d'audit

Filtrage des signaux

agentsh intercepte les signaux (kill, SIGTERM, etc.) envoyés entre les processus, offrant un contrôle basé sur des politiques pour déterminer quels signaux peuvent atteindre quelles cibles.

Prise en charge des plates-formes

Exemple de règles de signaux```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

### Groupes de signaux

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

### Types de cibles

- `self` - Processus qui se signale lui-même
- `children` - Processus enfants directs
- `descendants` - Tous les processus descendants
- `session` - Tout processus dans la session agentsh
- `external` - PID en dehors de la session
- `system` - PID 1 et threads du noyau

Voir la [documentation des politiques](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#règles-de-signal) pour les options de configuration complètes.

---

## Surveillance des E/S de fichiers sous macOS

Sur macOS, agentsh surveille les opérations d'entrée/sortie sur les fichiers en utilisant le framework de sécurité des endpoints (ESF), en s'abonnant aux événements AUTH et NOTIFY. Les opérations suivies incluent l'ouverture, la création, la suppression, le renommage, l'écriture (détectée via close-modified), et sur macOS 26+, chmod et chown via les événements de modification d'attributs. Chaque événement fichier est attribué à la session et à la commande d'origine via une résolution basée sur le PID, fournissant des pistes d'audit complètes dans les arborescences de sous-processus.

ESF offre un contrôle d'autorisation/refus au niveau du noyau mais ne prend pas en charge l'interception transparente des fichiers comme FUSE sous Linux. Les actions de politique nécessitant une interception -- telles que `redirect` (réécriture de chemin) et `soft_delete` (quarantaine) -- sont implémentées sous forme de refus + guidage : l'opération est bloquée au niveau ESF et l'agent reçoit des instructions pour réessayer avec le bon chemin ou pour accuser réception que le fichier est protégé. Voir le [document sur l'architecture ESF+NE de macOS](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) pour les détails des flux d'événements et la [documentation des politiques](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#actions-des-règles-de-fichier-sous-macos-esf) pour le comportement par action.

---

## Packs de politiques de démarrage

Vous disposez déjà d'une politique par défaut (`configs/policies/default.yaml`). Ces packs subjectifs sont disponibles sous forme de fichiers séparés afin que les équipes puissent en choisir un :

* **[`policies/dev-safe.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/dev-safe.yaml)** : sûr pour le développement local
  * autoriser la lecture/écriture dans l'espace de travail
  * approuver les suppressions dans l'espace de travail
  * refuser `~/.ssh/**`, `/root/.ssh/**`
  * restreindre le réseau aux domaines/ports autorisés

* **[`policies/ci-strict.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/ci-strict.yaml)** : sûr pour les exécuteurs CI
  * refuser tout ce qui se trouve en dehors de l'espace de travail
  * refuser le réseau sortant sauf les registres d'artefacts
  * refuser les shells interactifs sauf autorisation explicite
  * auditer tout (événements récapitulatifs)

* **[`policies/agent-sandbox.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/agent-sandbox.yaml)** : mode « l'agent exécute du code inconnu »
  * refus par défaut + liste d'autorisation explicite
  * approuver tout accès aux identifiants/chemins
  * rediriger l'utilisation d'outils réseau vers des proxys/miroirs internes
  * suppression douce des opérations destructrices pour une récupération facile

---

## Exemples d'intégration d'assistants IA

Extraits prêts à l'emploi pour configurer les assistants de codage IA afin d'utiliser agentsh :

* **[Claude Code](https://github.com/canyonroad/agentsh/blob/HEAD/examples/claude/)** - Extrait CLAUDE.md pour l'intégration Claude Code
* **[Cursor](https://github.com/canyonroad/agentsh/blob/HEAD/examples/cursor/)** - Règles Cursor pour l'intégration agentsh
* **[AGENTS.md](https://github.com/canyonroad/agentsh/blob/HEAD/examples/agents/)** - Extrait générique AGENTS.md (fonctionne avec plusieurs outils IA)

> **Remarque :** Ces exemples sont destinés aux scénarios de développement local où il n'est pas pratique d'exécuter l'agent IA dans un conteneur. Pour les environnements de production ou CI/CD, préférez l'exécution d'agents dans des conteneurs avec le shim shell installé—voir [Utilisation dans Docker](#utilisation-dans-docker-avec-le-shim-shell).

---

## Références

* **Démo de protection MCP :** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - démo en direct de la détection d'exfiltration entre serveurs, du blocage de rug pull et de la génération de politiques
* **Sécurité et modèle de menace :** [`SECURITY.md`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md) - ce contre quoi agentsh protège, limitations connues, liste de contrôle de l'opérateur
* **KMS externe :** [`SECURITY.md#intégration-kms-externe`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#external-kms-integration) - AWS KMS, Azure Key Vault, HashiCorp Vault, GCP Cloud KMS pour les clés d'intégrité d'audit
* Modèle de configuration : [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml)
* Politique par défaut : [`configs/policies/default.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/default.yaml)
* Exemple de Dockerfile (avec shim) : [`Dockerfile.example`](https://github.com/canyonroad/agentsh/blob/HEAD/Dockerfile.example)
* **Documentation des politiques :** [`docs/operations/policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md) - variables de politique, règles de signal, redirection réseau
* **Contrôle d'accès à la base de données :** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - périmètre d'application de la base de données exclusivement PostgreSQL, sémantique des politiques, comportement de redirection et feuille de route
* **Livre de recettes des politiques de commandes :** [`docs/cookbook/command-policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/command-policies.md) - comment autoriser un nouveau binaire, quand utiliser `wrap` au lieu de `exec`, et comment déboguer un refus
* **Livre de recettes des services HTTP :** [`docs/cookbook/http-services.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/http-services.md) - recettes pour acheminer les appels API HTTP sortants via des services déclarés avec règles et contrôle d'approbation
* **Livre de recettes des intégrations SDK Sandbox :** [`docs/cookbook/sandbox-sdk-integrations.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/sandbox-sdk-integrations.md) - configuration `shim_install` pour Tensorlake / E2B / Modal / Daytona où les commandes s'exécutent en tant que frères du serveur agentsh
* **Compétences en rédaction de politiques :** [`skills/`](https://github.com/canyonroad/agentsh/blob/HEAD/skills/) - compétences d'assistant IA pour créer et modifier des politiques dans Claude Code, NanoClaw, etc.
* **Comparaison des plateformes :** [`docs/platform-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/platform-comparison.md) - prise en charge des fonctionnalités, scores de sécurité, performances par plateforme
* **Bubblewrap vs agentsh :** [`docs/bubblewrap-vs-agentsh-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/bubblewrap-vs-agentsh-comparison.md) - comparaison avec Bubblewrap pour le sandboxing de conteneurs Linux
* **Contrôle d'accès à la base de données :** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - taxonomie du proxy PostgreSQL, modèle d'effets, `database_rules`, règles de connexion, modèle de menace
* **Modes de sécurité et `detect` :** [`docs/security-modes.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/security-modes.md) - modes d'application, score de protection, et ce que `agentsh detect` rapporte
* **seccomp :** [`docs/seccomp.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/seccomp.md) - filtrage des appels système, interception d'exécve, blocage de famille de sockets
* **Mode ptrace :** [`docs/ptrace-support.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ptrace-support.md) - application PTRACE_SEIZE pour les conteneurs restreints (`attach_mode`, prefiltre seccomp)
* **eBPF :** [`docs/ebpf.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ebpf.md) - traçage réseau eBPF et application des politiques
* **Proxy LLM et DLP :** [`docs/llm-proxy.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/llm-proxy.md) - configuration du proxy intégré, motifs DLP, suivi d'utilisation
* **Guide de construction macOS :** [`docs/macos-build.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-build.md) - instructions de construction ESF+NE
* **Architecture ESF+NE macOS :** [`docs/macos-esf-ne-architecture.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) - Extension système, XPC et détails de déploiement
* **Sandbox XPC macOS :** [`docs/macos-xpc-sandbox.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-xpc-sandbox.md) - contrôle XPC/Mach IPC pour les processus en sandbox
* Variables d'environnement (tous les remplacements `AGENTSH_*`, bascules de démarrage automatique, sélection de transport) : [`docs/spec.md` §15.3 « Variables d'environnement »](https://github.com/canyonroad/agentsh/blob/HEAD/docs/spec.md#153-environment-variables)
* Architecture et flux de données (FUSE + moteur de politiques + API) : commentaires en ligne dans [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml) et [`internal/netmonitor`](https://github.com/canyonroad/agentsh/blob/HEAD/internal/netmonitor)
* Aide en ligne de commande : `agentsh --help`, `agentsh exec --help`, `agentsh shim --help`

---

Créé avec l'aide d'agents pour des agents.

`visibility`	`silent`, `audit_only`, `warn`	Comment les redirections sont journalisées/affichées
`on_failure`	`fail_closed`, `fail_open`, `retry_original`	Ce qui se produit si la redirection échoue
`tls_mode`	`passthrough`, `rewrite_sni`	Gestion TLS pour la redirection de connexion

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

Linux	Oui (seccomp user-notify)	Oui	Oui
macOS	Non	Non	Oui (ES)
Windows	Partiel	Non	Oui (ETW)

Populaires

agentsh

agentsh

Qu'est-ce que agentsh ?

Pourquoi agentsh ?

Blocs significatifs : deny → redirect (le superpouvoir d'« orientation »)

Conteneurs + agentsh : mieux ensemble

Démarrage rapide

Installation

Exécution locale```bash

Start the server (optional if using autostart)

Create a session and run a command (shell output)

Structured output for agents

Dites à votre agent de l'utiliser (AGENTS.md / CLAUDE.md snippet)```md

Shell access

Modèle de politique

Décisions

Portées

Évaluation

Référence rapide de la politique d'environnement

Exemples de règles (tronqués)```yaml

Authentification

Sécurité MCP

Démo en 60 secondes

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

Points de contrôle de l'espace de travail

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

Contrôle d'accès à la base de données (Postgres uniquement aujourd'hui)

Génération de politiques

Generate policy from latest session

Generate with custom name and threshold

Quick preview to stdout

Redirection Réseau

Redirection DNS

Options

Prise en charge des plates-formes

Cas d'utilisation

Filtrage des signaux

Prise en charge des plates-formes

Exemple de règles de signaux```yaml

Allow signals to self and children

Redirect SIGKILL to graceful SIGTERM

Block fatal signals to external processes