agentsh

Hinweis für macOS: Die native macOS-Durchsetzung über ESF (Endpoint Security Framework) + NE (Network Extension) befindet sich im Alpha-Stadium. Sie funktioniert Ende-zu-Ende — Datei-, Prozess- und Netzwerkereignisse fließen über die Systemerweiterung in die Go-Policy-Engine — aber erwarten Sie raue Kanten und bahnbrechende Änderungen zwischen Releases. Für den Produktionseinsatz empfehlen wir derzeit Linux.

Hinweis für Windows: Wir arbeiten daran, die Minifilter-Treiber signieren zu lassen. Bis dahin ist nur der Windows-WSL2-Modus für den Produktionseinsatz vollständig unterstützt.

Sicherer, richtliniengesteuerter Ausführungs-Gateway für KI-Agenten.

agentsh sitzt unter Ihrem Agenten/Tooling — es erfasst Datei-, Netzwerk-, Prozess- und Signal-Aktivitäten (einschließlich Subprozess-Bäume), setzt die von Ihnen definierte Richtlinie durch und emittiert strukturierte Audit-Ereignisse.

Plattform-Hinweis: Linux bietet vollständige Durchsetzung (100 % Sicherheitsbewertung). macOS ESF+NE (90 % Bewertung) befindet sich im Alpha-Stadium — funktional, aber nicht produktionsreif. Windows WSL2 bietet vollständige, Linux-äquivalente Durchsetzung (100 % Bewertung); natives Windows über Minifilter-Treiber + AppContainer (85 % Bewertung) wartet auf die Treibersignierung. Siehe Plattform-Vergleichsmatrix für Details.

Was ist agentsh?

Drop-in-Shell/Exec-Endpunkt, der jeden Befehl (und seine Subprozesse) in auditierbare Ereignisse verwandelt.
Richtlinien-Engine pro Operation: allow, deny, approve (menschliche Freigabe), soft_delete oder redirect.
Volle I/O-Sichtbarkeit:
- Datei öffnen/lesen/schreiben/löschen
- Netzwerkverbindung + DNS
- Prozessstart/-ende
- PTY-Aktivität
- LLM-API-Anfragen mit DLP und Nutzungsverfolgung
- Postgres-Familie-Datenbankverkehr über deklarierte db_services
- Signal senden/blockieren (Linux durchgesetzt, macOS/Windows Audit)
- Datenbankabfragen über den eingebetteten PostgreSQL-Proxy — Klassifizierung und Richtlinie pro Anweisung
- Ausgehende HTTP-API-Aufrufe über deklarierte Dienste (http_services) mit Regeln pro Methode, pro Pfad, Freigabe-Gating und Fail-Closed-Host-Durchsetzung
Zwei Ausgabemodi:
- menschenfreundliche Shell-Ausgabe
- kompakte JSON-Antworten für Agenten/Werkzeuge

Warum agentsh?

Agent-Workflows führen irgendwann beliebigen Code aus (pip install, make test, python script.py). Traditionelle „Vor der Befehlsausführung um Genehmigung fragen"-Kontrollen enden an der Tool-Grenze und können nicht sehen, was innerhalb dieses Befehls passiert.

agentsh setzt Richtlinien zur Laufzeit durch, sodass versteckte Arbeit von Subprozessen weiterhin gesteuert, protokolliert und (falls erforderlich) genehmigt wird.

Sinnvolle Blockierungen: deny → redirect (die „Steuerungs"-Superkraft)

Die meisten Systeme können eine Aktion verweigern. agentsh kann sie auch umleiten (redirect).

Das bedeutet: Wenn ein Agent den falschen Ansatz versucht (oder Brute-Force-Workarounds), kann die Richtlinie ihn auf den richtigen Pfad lenken, indem sie den Befehl austauscht und Anleitung zurückgibt — so bleibt der Agent auf der befestigten Straße und verschwendete Wiederholungsversuche werden reduziert.

Beispiel: curl zu einem auditierten Wrapper umleiten```yaml command_rules:

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

**Beispiel: Schreibvorgänge außerhalb des Arbeitsbereichs zurück nach innen umleiten**```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"

Der Agent sieht eine erfolgreiche Operation (keinen Fehler), aber du kontrollierst, wohin die Dinge tatsächlich landen.

Container + agentsh: besser zusammen

Container isolieren die Host-Oberfläche; agentsh fügt Laufzeitsichtbarkeit und Richtlinien innerhalb des Containers hinzu.

Pro-Operation-Audit (Dateien, Netzwerk, Befehle) zeigt, was während Installationen/Builds/Tests passiert ist.
Genehmigungen und Regeln bleiben über langlebige Shells und Subprozess-Bäume hinweg bestehen – nicht nur für den ersten Befehl.
Kontrollen auf Pfadebene für gemountete Workspaces/Caches/Credentials; Container bieten diese Granularität nicht nativ.
Gleiches Verhalten auf dem Host und in Containern, sodass CI und lokale Entwicklung dieselben Richtlinienergebnisse sehen.

Schnellstart

Installation

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

Dies installiert das AgentSH-App-Bundle mit der ESF+NE-Systemerweiterung. Nach der Installation werden Sie aufgefordert, die Systemerweiterung in **Systemeinstellungen > Allgemein > Anmeldeobjekte & Erweiterungen** zu genehmigen.

**Linux (aus einem GitHub-Release)**

Laden Sie die `.deb`, `.rpm` oder `.apk` für Ihre Plattform von der [Releases-Seite](https://github.com/erans/agentsh/releases) herunter.```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

Aus dem Quellcode (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

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

Siehe macOS-Build-Anleitung für detaillierte macOS-Build-Anweisungen.

Lokal ausführen```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

### Prüfen, was durchgesetzt wird

`agentsh detect` untersucht den Host und meldet, welche Durchsetzungs-Primitiven tatsächlich verfügbar sind — seccomp, Landlock, FUSE, eBPF, ptrace, cgroups — gruppiert in bereichsspezifische Schutzwerte sowie den ausgewählten Sicherheitsmodus. Auf eingeschränkten Hosts (Daytona, E2B, Firecracker-Klasse), auf denen der seccomp-user-notify-Listener nicht installiert werden kann, meldet es den Modus, der *tatsächlich* durchsetzt, statt nur das, was der Kernel lediglich unterstützt.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

Siehe Sicherheitsmodi für die Modusmatrix und die Stellschrauben.

Sagen Sie Ihrem Agenten, er soll es verwenden (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 (ohne manuellen Daemon-Schritt)

Du musst `agentsh server` **nicht** selbst starten.

* Der erste `agentsh exec`-Aufruf (oder jede geshimte `/bin/sh`/`/bin/bash`) startet automatisch einen lokalen Server mit `configs/server-config.yaml` (bzw. `AGENTSH_CONFIG`, falls gesetzt).
* Dieser Server hält die FUSE-Ebene und die Policy-Engine für die gesamte Sitzungsdauer am Leben; nachfolgende Befehle verwenden ihn erneut.
* Setze `AGENTSH_NO_AUTO=1`, wenn du den Server-Lebenszyklus manuell verwalten möchtest.

---

## Verwendung in Docker (mit dem Shell-Shim)

Siehe `Dockerfile.example` für ein minimales Debian-basiertes Image.

Installiere innerhalb des Images ein Release-Paket (oder kopiere deinen Build) und aktiviere dann den Shim:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

Richten Sie den Shim auf Ihren Server (Sidecar oder Host):```dockerfile ENV AGENTSH_SERVER=http://127.0.0.1:18080

Jetzt läuft jeder `/bin/sh -c ...`- oder `/bin/bash -lc ...`-Befehl im Container über agentsh.

### Nicht-interaktive Durchsetzung

Standardmäßig umgeht der Shim die Richtlinie, wenn stdin kein TTY ist (wodurch Binärdaten für gepipete Befehle erhalten bleiben). Auf Plattformen, auf denen Befehle immer nicht-interaktiv sind, aber dennoch eine Durchsetzung benötigen (z. B. exe.dev, Sandbox-APIs), fügen Sie `--force` hinzu:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --force \
  --i-understand-this-modifies-the-host

Dies schreibt /etc/agentsh/shim.conf mit force=true, das der Shim beim Start liest. Die Konfigurationsdatei funktioniert unabhängig davon, wie die Shell gestartet wird (anders als Umgebungsvariablen oder Profil-Skripte). AGENTSH_SHIM_FORCE=1 in der Prozessumgebung erzielt denselben Effekt pro Prozess.

Empfohlenes Muster: agentsh als Sidecar (oder PID 1) im selben Pod/Dienst ausführen und ein gemeinsames Workspace-Volume verwenden; der Shim stellt sicher, dass jeder Shell-Hop innerhalb der Policy bleibt.

Policy-Modell

Entscheidungen

allow
deny
approve (menschliche Freigabe)
redirect (ersetzt einen Befehl)
audit (erlauben + protokollieren)
soft_delete (quarantäniert Löschvorgänge mit Wiederherstellung)

Bereiche

Dateioperationen
Befehle
Umgebungsvariablen
Netzwerk (DNS/Verbindung)
Datenbank (SQL-Anweisungen über den PostgreSQL-Proxy)
PTY-/Sitzungseinstellungen
deklarierte HTTP-Dienste

Auswertung

Die erste passende Regel gewinnt

Regeln sind in einer benannten Policy definiert; Sitzungen wählen eine Policy.

Standardwerte:

Beispielkonfiguration: configs/server-config.yaml
Standard-Policy: configs/policies/default.yaml
Umgebungs-Override: Setze AGENTSH_POLICY_NAME auf einen erlaubten Policy-Namen (ohne Suffix). Wenn nicht gesetzt/ungültig/nicht erlaubt, wird die Standard-Policy verwendet.
Umgebungs-Policy: Konfiguriere policies.env_policy (allow/deny, max_bytes, max_keys, block_iteration) und Pro-Befehl-env_*-Overrides in Policy-Dateien. Eine leere Allowlist führt standardmäßig zu minimalem PATH/LANG/TERM/HOME mit integrierter Secret-Denylist; setze block_iteration, um die Umgebungsiteration zu verbergen (erfordert den Env-Shim).
Allowlist: Konfiguriere policies.allowed in config.yml; wenn leer, ist nur die Standard-Policy erlaubt.
Optionale Integrität: Setze policies.manifest_path auf ein SHA256-Manifest, um Policy-Dateien beim Laden zu verifizieren.

Kurzreferenz zur Umgebungs-Policy

Standardwerte: Ohne env_allow erstellt agentsh eine minimale Umgebung (PATH/LANG/TERM/HOME) und entfernt die eingebauten geheimen Schlüssel.
Overrides: Pro Befehl env_allow/env_deny plus env_max_keys/env_max_bytes begrenzen und filtern die Kind-Umgebung zur Ausführungszeit.
Blockierung der Iteration: env_block_iteration: true (global oder pro Regel) verbirgt die Umgebungsaufzählung; setze policies.env_shim_path auf libenvshim.so, damit agentsh LD_PRELOAD + AGENTSH_ENV_BLOCK_ITERATION=1 injiziert.
Limits: Fehler, wenn Limits überschritten werden; der Umgebungs-Builder wird vor der Ausführung für jeden Befehl angewendet.
env_inject: Vom Betreiber vertrauenswürdige Umgebungsvariablen werden in alle Befehle injiziert und umgehen die Policy-Filterung. Hauptverwendung: BASH_ENV, um Shell-Builtins zu deaktivieren, die seccomp umgehen. Konfiguriere in (global) oder auf Policy-Ebene (überschreibt global).

Beispielregeln (gekürzt)```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

---

### Verwenden einer Richtlinie```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

Authentifizierung

agentsh unterstützt mehrere Authentifizierungsmethoden:

Typ	Anwendungsfall
`api_key`	Einfache Bereitstellungen mit statischen Schlüsseln
`oidc`	Enterprise-SSO (Okta, Azure AD usw.)
`hybrid`	Beide Methoden werden akzeptiert

Genehmigungsmodi für die Prüfung mit menschlicher Beteiligung:

local_tty - Terminal-Eingabeaufforderung (Standard)
totp - Authenticator-App-Codes
webauthn - Hardware-Sicherheitsschlüssel (YubiKey)
api - Remote-Genehmigung per REST

Weitere Konfigurationsdetails finden Sie unter SECURITY.md.

MCP-Sicherheit

Tool-Whitelisting: Steuern Sie, welche MCP-Tools über Allowlist-/Denylist-Richtlinien aufgerufen werden können
Versions-Pinning: Erkennung von Änderungen an Tool-Definitionen (Rug-Pull-Schutz) mit konfigurierbaren Reaktionen
Serverübergreifende Erkennung: Blockieren von Datenexfiltrationsmustern (Lesen von Server A → Senden über Server B)
Ratenbegrenzung: Token-Bucket-Ratenbegrenzung für MCP-Server und Netzwerkdomänen

Weitere Konfigurationsoptionen finden Sie unter SECURITY.md oder führen Sie die MCP Protection Demo aus, um diese Erkennungen in Aktion zu sehen.

60-Sekunden-Demo

Der schnellste Weg, das Konzept zu verstehen, besteht darin, etwas auszuführen, das Unterprozesse erzeugt und auf Dateisystem/Netzwerk zugreift.```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

**Was du in der JSON-Ausgabe sehen wirst:**
- `exit_code`: der Exit-Status des Befehls
- `stdout` / `stderr`: erfasste Ausgabe
- `events[]`: jede Datei-/Netzwerk-/Prozessoperation mit Policy-Entscheidungen
- `policy.decision`: `allow`, `deny`, `approve` oder `redirect`

Tipp: Halte ein Terminal mit `--output json` offen, wenn du Policies testest – so wird klar, was berührt wird.

---

### Sitzungsberichte

Erzeuge Markdown-Berichte, die die Sitzungsaktivität zusammenfassen:```bash
# Quick summary
agentsh report latest --level=summary

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

Berichte umfassen:

Entscheidungszusammenfassung (erlaubt, blockiert, umgeleitet)
Automatische Erkennung von Befunden (Verstöße, Anomalien)
Aktivitätsaufschlüsselung nach Kategorie
Vollständige Ereigniszeitachse (detaillierter Modus)

Siehe CI/CD-Integrationsleitfaden für Pipeline-Beispiele.

Arbeitsbereichs-Checkpoints

Erstellen Sie Schnappschüsse des Arbeitsbereichszustands zur Wiederherstellung nach destruktiven Vorgängen:```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:** Wenn aktiviert, erstellt agentsh automatisch Checkpoints vor riskanten Befehlen (`rm`, `mv`, `git reset`, `git checkout` usw.). Konfiguration in `sessions.checkpoints.auto_checkpoint`.

Siehe [SECURITY.md](https://github.com/canyonroad/agentsh/blob/main/SECURITY.md#checkpoint-and-rollback) für alle Konfigurationsoptionen.

---

### LLM-Proxy und DLP

agentsh enthält einen eingebetteten Proxy, der alle LLM-API-Anfragen von Agenten abfängt:```bash
# Check proxy status for a session
agentsh proxy status <session-id>

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

Features:

Automatisches Routing: Setzt ANTHROPIC_BASE_URL und OPENAI_BASE_URL, sodass Agent-SDKs über den Proxy geleitet werden
Benutzerdefinierte Anbieter: Weiterleitung an LiteLLM, Azure OpenAI, vLLM oder Unternehmens-Gateways
DLP-Redaktion: Persönlich identifizierbare Informationen (E-Mails, Telefonnummern, API-Schlüssel usw.) werden vor der Übertragung an LLM-Anbieter geschwärzt
Benutzerdefinierte Muster: Definieren Sie organisationsspezifische Muster für sensible Daten
Nutzungsverfolgung: Token-Anzahlen werden extrahiert und für die Kostenverteilung protokolliert
Audit-Trail: Alle Anfragen/Antworten werden im Sitzungsspeicher protokolliert

Anbieterkonfiguration:```yaml proxy: mode: embedded providers: anthropic: https://api.anthropic.com # Default Anthropic API openai: https://api.openai.com # Default OpenAI API

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

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

Siehe LLM-Proxy-Dokumentation für alle Konfigurationsoptionen.

Derselbe Proxy leitet auch deklarierte http_services-Einträge weiter – benannte API-Upstreams mit Regeln pro Methode und pro Pfad. Siehe Deklarierte HTTP-Dienste und HTTP-Services-Kochbuch für Details.

Datenbankzugriffskontrolle (derzeit nur Postgres)

agentsh kann Richtlinien für deklarierte Datenbankdienste über db_services, database_connection_rules und database_rules durchsetzen. Die derzeitige Implementierung unterstützt nur die Postgres-Familie: PostgreSQL ist das unterstützte Ziel, wobei Aurora Postgres denselben Pfad verwendet und Redshift/CockroachDB als Postgres-kompatible Dialekte mit Beta-Abdeckung behandelt werden. MySQL, MongoDB, Snowflake, BigQuery, Databricks, ClickHouse, MSSQL, Cassandra, Redis und Oracle stehen auf der Roadmap, werden aber derzeit zur Laufzeit nicht unterstützt.

Die derzeitige Postgres-Unterstützung umfasst:

Verbindungsentscheidungen: Erlauben/Verweigern/Genehmigen/Auditieren.
Anweisungsklassifizierung für das PostgreSQL-Drahtprotokoll v3, einschließlich Simple Query, Extended Query, vorbereiteter SQL-Anweisungen, COPY, FunctionCall-Verweigerung, Transaktionsstatus und CancelRequest-Zuordnung.
Strikte Richtlinienabdeckung pro Objekt mit Deny-Vorrang.
Kataloggestützte Relations-/Funktionsselektoren für Richtlinien aufgelöster Objekte.
Sicheres Laufzeit-redirect zum Ersetzen schreibgeschützter Postgres-Relationen.
Bypass-Erkennung und E2E-Abdeckung mit echtem Postgres unter Docker in der CI.

Die Postgres-Proxy-Laufzeit ist derzeit reiner Linux-In-Process-Code. Verwenden Sie natives Linux, WSL2 oder eine Linux-VM-Umgebung für die Durchsetzung der Datenbankrichtlinien.

Siehe Datenbankzugriffskontrolle und Richtliniendokumentation.

Richtliniengenerierung

Generieren Sie restriktive Richtlinien aus beobachtetem Sitzungsverhalten ("profile-then-lock"-Workflow):```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

Die generierte Richtlinie:
- Erlaubt nur während der Sitzung beobachtete Operationen
- Fasst Pfade zu Globs zusammen, wenn viele Dateien im selben Verzeichnis liegen
- Reduziert Subdomains zu Wildcards (z. B. `*.github.com`)
- Markiert riskante Befehle (`curl`, `wget`, `rm`) mit Argumentmustern
- Enthält blockierte Operationen als auskommentierte Regeln zur Überprüfung

**Anwendungsfälle:**
- **CI/CD-Abschottung**: Einen Build-/Testlauf profilieren, zukünftige Läufe auf dieses Verhalten festlegen
- **Agent-Sandboxing**: Einen KI-Agenten eine Aufgabe ausführen lassen, eine Richtlinie für zukünftige Läufe generieren
- **Container-Profiling**: Eine Workload profilieren, eine minimale Richtlinie für die Produktion generieren

---

## Datenbankzugriff (PostgreSQL)

agentsh enthält einen eingebetteten **PostgreSQL-Proxy**, der den Datenbankzugriff agentenbewusst und richtliniengesteuert macht. Er spricht das Postgres-Drahtprotokoll, ordnet jeder Anweisung eine Liste von *Effekten* zu (Lesezugriffe, Schreibzugriffe, DDL, DCL, Transaktions-/Sitzungssteuerung, Bulk-`COPY`/Export, …) und bewertet jeden Effekt anhand von `database_rules`, bevor er ihn stromaufwärts weiterleitet — sodass ein `UPDATE`, `DROP` oder ein nicht eingegrenztes `DELETE` genauso gesteuert wird wie ein Dateischreib- oder Netzwerkverbindungszugriff.

- **Pro-Effekt-Bewertung über mehrere Objekte** — Regeln sind Collect-all / **Any-deny-wins** (das restriktivste Verb entscheidet), nicht First-Match.
- **Entscheidungen:** `allow`, `deny`, `approve` (menschliches OK), `audit` und `redirect` auf Anweisungsebene.
- **`require_where`-Schutz** — lehnt Top-Level-`UPDATE`/`DELETE` ab, denen eine `WHERE`-Klausel fehlt.
- **Verbindungsbezogene Regeln** (`database_connection_rules`) legen fest, welche Sitzungen welchen deklarierten `db_service` erreichen dürfen.
- **Auth- und Anweisungs-Audit-Ereignisse** für jede Verbindung und Abfrage; die Protokollierung des Anweisungstexts ist konfigurierbar (`policies.db.log_statements: none | parameters_redacted | full`).

Phase 1 deckt das PostgreSQL-v3-Drahtprotokoll ab (Dialekte: `postgres`, `aurora_postgres`; `redshift` / `cockroachdb` in der Betaphase). Replikation und GSSAPI-verschlüsselte Verbindungen sind standardmäßig verweigert (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}}"

Siehe die Database Access Control-Spezifikation für die vollständige Operations-Taxonomie, das Effektmodell, die Verbindungsregeln und das Unvermeidbarkeits-Bedrohungsmodell.

Netzwerk-Umleitung

agentsh kann DNS- und TCP-Verbindungen transparent umleiten und ermöglicht so Anwendungsfälle wie das Routen von API-Aufrufen über Unternehmens-Proxys oder den Wechsel von KI-Anbietern ohne Codeänderungen.

DNS-Umleitung

DNS-Auflösung abfangen und konfigurierte IP-Adressen zurückgeben:```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

### Verbindungsweiterleitung

Leitet TCP-Verbindungen mit optionaler TLS-Behandlung an verschiedene Ziele weiter:```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

Optionen

Plattformunterstützung

Anwendungsfälle

API-Gateway-Routing: Anthropic/OpenAI-Aufrufe über das firmeneigene LLM-Gateway leiten
Anbieterwechsel: Claude-API auf GCP Vertex AI oder Azure OpenAI umleiten
Testen: Produktions-APIs auf Mock-Server umleiten
Compliance: Den gesamten LLM-Verkehr durch Audit-Proxys erzwingen

Signal-Filterung

agentsh fängt Signale (kill, SIGTERM usw.) ab, die zwischen Prozessen gesendet werden, und ermöglicht eine richtlinienbasierte Kontrolle darüber, welche Signale welche Ziele erreichen dürfen.

Plattformunterstützung

Beispiel-Signalregeln```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-Gruppen

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

### Zieltypen

- `self` - Prozess, der sich selbst signalisiert
- `children` - Direkte Kindprozesse
- `descendants` - Alle Nachfolgeprozesse
- `session` - Jeder Prozess in der agentsh-Sitzung
- `external` - PIDs außerhalb der Sitzung
- `system` - PID 1 und Kernel-Threads

Siehe [Policy-Dokumentation](https://github.com/canyonroad/agentsh/blob/main/docs/operations/policies.md#signal-rules) für vollständige Konfigurationsoptionen.

---

## macOS-Datei-I/O-Überwachung

Unter macOS überwacht agentsh Datei-I/O mithilfe des Endpoint Security Framework (ESF) und abonniert sowohl AUTH- als auch NOTIFY-Ereignisse. Verfolgte Operationen umfassen Öffnen, Erstellen, Löschen, Umbenennen, Schreiben (erkannt über close-modified) sowie unter macOS 26+ chmod und chown über Attributänderungsereignisse. Jedes Dateiereignis wird über PID-basierte Auflösung der ursprünglichen Sitzung und dem Befehl zugeordnet, wodurch vollständige Audit-Pfade über Subprozessbäume hinweg entstehen.

ESF bietet Durchsetzung auf Kernel-Ebene (Erlauben/Verweigern), unterstützt jedoch keine transparente Dateiinterception wie Linux FUSE. Richtlinienaktionen, die Interception erfordern -- wie `redirect` (Pfadumschreibung) und `soft_delete` (Quarantäne) -- sind als Verweigern + Anleitung implementiert: Die Operation wird auf ESF-Ebene blockiert und der Agent erhält Anweisungen, es mit dem korrekten Pfad erneut zu versuchen oder zu bestätigen, dass die Datei geschützt ist. Siehe das [macOS-ESF+NE-Architekturdokument](https://github.com/canyonroad/agentsh/blob/main/docs/macos-esf-ne-architecture.md) für Details zum Ereignisstrom und die [Policy-Dokumentation](https://github.com/canyonroad/agentsh/blob/main/docs/operations/policies.md#file-rule-actions-on-macos-esf) für das Verhalten pro Aktion.

---

## Starter-Policy-Pakete

Sie haben bereits eine Standard-Policy (`configs/policies/default.yaml`). Diese meinungsstarken Pakete sind als separate Dateien verfügbar, sodass Teams eines auswählen können:

* **[`policies/dev-safe.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/dev-safe.yaml)**: sicher für die lokale Entwicklung
  * Lese-/Schreibzugriff im Workspace erlauben
  * Löschungen im Workspace genehmigen
  * Zugriff auf `~/.ssh/**`, `/root/.ssh/**` verweigern
  * Netzwerk auf zugelassene Domains/Ports beschränken

* **[`policies/ci-strict.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/ci-strict.yaml)**: sicher für CI-Runner
  * Alles außerhalb des Workspace verweigern
  * Ausgehenden Netzwerkverkehr außer zu Artefakt-Registries verweigern
  * Interaktive Shells verweigern, sofern nicht ausdrücklich erlaubt
  * Alles protokollieren (Summary-Ereignisse)

* **[`policies/agent-sandbox.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/agent-sandbox.yaml)**: Modus „Agent führt unbekannten Code aus"
  * Standardmäßig verweigern + explizite Allowlist
  * Jeglichen Zugriff auf Zugangsdaten/Pfade genehmigen
  * Nutzung von Netzwerktools auf interne Proxys/Mirrors umleiten
  * Destruktive Operationen per Soft-Delete für eine einfache Wiederherstellung

---

## Beispiele für KI-Assistenten-Integration

Sofort verwendbare Snippets zur Konfiguration von KI-Coding-Assistenten für die Nutzung von agentsh:

* **[Claude Code](https://github.com/canyonroad/agentsh/blob/main/examples/claude)** - CLAUDE.md-Snippet für die Claude-Code-Integration
* **[Cursor](https://github.com/canyonroad/agentsh/blob/main/examples/cursor)** - Cursor-Regeln für die agentsh-Integration
* **[AGENTS.md](https://github.com/canyonroad/agentsh/blob/main/examples/agents)** - Generisches AGENTS.md-Snippet (funktioniert mit mehreren KI-Tools)

> **Hinweis:** Diese Beispiele sind für lokale Entwicklungs-Szenarien gedacht, in denen der Betrieb des KI-Agenten in einem Container unpraktisch ist. Für Produktions- oder CI/CD-Umgebungen sollten Agenten bevorzugt in Containern mit installiertem Shell-Shim ausgeführt werden—siehe [Verwendung in Docker](#use-in-docker-with-the-shell-shim).

---

## Referenzen

* **MCP-Schutzdemo:** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - Live-Demo zur Erkennung von Cross-Server-Exfiltration, Blockierung von Rug Pulls und Policy-Generierung
* **Sicherheits- & Bedrohungsmodell:** [`SECURITY.md`](https://github.com/canyonroad/agentsh/blob/main/SECURITY.md) - wogegen agentsh schützt, bekannte Einschränkungen, Checkliste für Betreiber
* **Externer KMS:** [`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 für Audit-Integritätsschlüssel
* Konfigurationsvorlage: [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/server-config.yaml)
* Standard-Policy: [`configs/policies/default.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/policies/default.yaml)
* Beispiel-Dockerfile (mit Shim): [`Dockerfile.example`](https://github.com/canyonroad/agentsh/blob/main/Dockerfile.example)
* **Policy-Dokumentation:** [`docs/operations/policies.md`](https://github.com/canyonroad/agentsh/blob/main/docs/operations/policies.md) - Policy-Variablen, Signal-Regeln, Netzwerk-Umleitung
* **Datenbank-Zugriffskontrolle:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/main/docs/agentsh-db-access-spec.md) - Nur-Postgres-Datenbank-Durchsetzungsumfang, Policy-Semantik, Redirect-Verhalten und Roadmap
* **Kochbuch für Befehls-Policies:** [`docs/cookbook/command-policies.md`](https://github.com/canyonroad/agentsh/blob/main/docs/cookbook/command-policies.md) - wie man ein neues Binärprogramm erlaubt, wann `wrap` statt `exec` verwendet wird und wie man eine Ablehnung debuggt
* **Kochbuch für HTTP-Dienste:** [`docs/cookbook/http-services.md`](https://github.com/canyonroad/agentsh/blob/main/docs/cookbook/http-services.md) - Rezepte zum Routing ausgehender HTTP-API-Aufrufe über deklarierte Dienste mit Regeln und Genehmigungs-Gating
* **Kochbuch für Sandbox-SDK-Integrationen:** [`docs/cookbook/sandbox-sdk-integrations.md`](https://github.com/canyonroad/agentsh/blob/main/docs/cookbook/sandbox-sdk-integrations.md) - `shim_install`-Konfiguration für Tensorlake / E2B / Modal / Daytona, bei denen Befehle als Geschwisterprozesse des agentsh-Servers laufen
* **Fähigkeiten zur Policy-Erstellung:** [`skills/`](https://github.com/canyonroad/agentsh/blob/main/skills) - KI-Assistenten-Fähigkeiten zum Erstellen und Bearbeiten von Policies in Claude Code, NanoClaw usw.
* **Plattformvergleich:** [`docs/platform-comparison.md`](https://github.com/canyonroad/agentsh/blob/main/docs/platform-comparison.md) - Funktionsunterstützung, Sicherheitsbewertungen, Leistung nach Plattform
* **Bubblewrap vs agentsh:** [`docs/bubblewrap-vs-agentsh-comparison.md`](https://github.com/canyonroad/agentsh/blob/main/docs/bubblewrap-vs-agentsh-comparison.md) - Vergleich mit Bubblewrap für Linux-Container-Sandboxing
* **Datenbank-Zugriffskontrolle:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/main/docs/agentsh-db-access-spec.md) - PostgreSQL-Proxy-Taxonomie, Effektmodell, `database_rules`, Verbindungsregeln, Bedrohungsmodell
* **Sicherheitsmodi & `detect`:** [`docs/security-modes.md`](https://github.com/canyonroad/agentsh/blob/main/docs/security-modes.md) - Durchsetzungsmodi, Schutzbewertung und was `agentsh detect` meldet
* **seccomp:** [`docs/seccomp.md`](https://github.com/canyonroad/agentsh/blob/main/docs/seccomp.md) - Syscall-Filterung, execve-Interception und Blockierung von Socket-Familien
* **ptrace-Modus:** [`docs/ptrace-support.md`](https://github.com/canyonroad/agentsh/blob/main/docs/ptrace-support.md) - PTRACE_SEIZE-Durchsetzung für eingeschränkte Container (`attach_mode`, seccomp-Vorfilter)
* **eBPF:** [`docs/ebpf.md`](https://github.com/canyonroad/agentsh/blob/main/docs/ebpf.md) - eBPF-Netzwerk-Tracing & Policy-Durchsetzung
* **LLM-Proxy & DLP:** [`docs/llm-proxy.md`](https://github.com/canyonroad/agentsh/blob/main/docs/llm-proxy.md) - eingebettete Proxy-Konfiguration, DLP-Muster, Nutzungsverfolgung
* **macOS-Build-Anleitung:** [`docs/macos-build.md`](https://github.com/canyonroad/agentsh/blob/main/docs/macos-build.md) - ESF+NE-Build-Anweisungen
* **macOS-ESF+NE-Architektur:** [`docs/macos-esf-ne-architecture.md`](https://github.com/canyonroad/agentsh/blob/main/docs/macos-esf-ne-architecture.md) - System Extension, XPC und Bereitstellungsdetails
* **macOS-XPC-Sandbox:** [`docs/macos-xpc-sandbox.md`](https://github.com/canyonroad/agentsh/blob/main/docs/macos-xpc-sandbox.md) - XPC/Mach-IPC-Steuerung für Sandbox-Prozesse
* Umgebungsvariablen (alle `AGENTSH_*`-Overrides, Auto-Start-Umschalter, Transportauswahl): [`docs/spec.md` §15.3 "Environment Variables"](https://github.com/canyonroad/agentsh/blob/main/docs/spec.md#153-environment-variables)
* Architektur & Datenfluss (FUSE + Policy-Engine + API): Inline-Kommentare in [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/main/configs/server-config.yaml) und [`internal/netmonitor`](https://github.com/canyonroad/agentsh/blob/main/internal/netmonitor)
* CLI-Hilfe: `agentsh --help`, `agentsh exec --help`, `agentsh shim --help`

---

Erstellt mit der Hilfe von Agenten für Agenten.

`visibility`	`silent`, `audit_only`, `warn`	Wie Weiterleitungen protokolliert/angezeigt werden
`on_failure`	`fail_closed`, `fail_open`, `retry_original`	Was passiert, wenn die Weiterleitung fehlschlägt
`tls_mode`	`passthrough`, `rewrite_sni`	TLS-Behandlung für Connect-Weiterleitung

DNS-Weiterleitung	✅ eBPF	✅ pf/Proxy	✅ WinDivert
Connect-Weiterleitung	✅ eBPF	✅ pf/Proxy	✅ WinDivert
SNI-Neuschreiben	✅	✅	✅

Linux	Ja (seccomp user-notify)	Ja	Ja
macOS	Nein	Nein	Ja (ES)
Windows	Teilweise	Nein	Ja (ETW)

Beliebteste

agentsh

agentsh

Was ist agentsh?

Warum agentsh?

Sinnvolle Blockierungen: deny → redirect (die „Steuerungs"-Superkraft)

Container + agentsh: besser zusammen

Schnellstart

Installation

Lokal ausführen```bash

Start the server (optional if using autostart)

Create a session and run a command (shell output)

Structured output for agents

Sagen Sie Ihrem Agenten, er soll es verwenden (AGENTS.md / CLAUDE.md-Snippet)```md

Shell access

Policy-Modell

Entscheidungen

Bereiche

Auswertung

Kurzreferenz zur Umgebungs-Policy

Beispielregeln (gekürzt)```yaml

Authentifizierung

MCP-Sicherheit

60-Sekunden-Demo

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

Arbeitsbereichs-Checkpoints

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

Datenbankzugriffskontrolle (derzeit nur Postgres)

Richtliniengenerierung

Generate policy from latest session

Generate with custom name and threshold

Quick preview to stdout

Netzwerk-Umleitung

DNS-Umleitung

Optionen

Plattformunterstützung

Anwendungsfälle

Signal-Filterung

Plattformunterstützung

Beispiel-Signalregeln```yaml

Allow signals to self and children

Redirect SIGKILL to graceful SIGTERM

Block fatal signals to external processes