agentsh

macOS 참고: ESF(Endpoint Security Framework) + NE(Network Extension)를 통한 네이티브 macOS 적용은 알파 단계입니다. 파일, 프로세스, 네트워크 이벤트가 시스템 확장을 통해 Go 정책 엔진으로 흐르는 종단 간(end-to-end) 동작은 되지만, 릴리스 사이에 거친 부분과 파격적 변경 사항이 있을 수 있습니다. 현재 프로덕션 용도로는 Linux를 권장합니다.

Windows 참고: minifilter 드라이버 서명을 받기 위해 작업 중입니다. 그때까지는 프로덕션 용도로 Windows WSL2 모드만 완전히 지원됩니다.

AI 에이전트를 위한 보안, 정책 적용 실행 게이트웨이.

agentsh는 에이전트/도구 하위 계층에 위치하여 파일, 네트워크, 프로세스, 시그널 활동(하위 프로세스 트리 포함)을 가로채고, 사용자가 정의한 정책을 적용하며, 구조화된 감사 이벤트를 방출합니다.

플랫폼 참고: Linux는 전체 적용(보안 점수 100%)을 제공합니다. macOS ESF+NE(점수 90%)는 알파 단계 — 동작은 하지만 프로덕션 준비는 아닙니다. Windows WSL2는 Linux와 동등한 전체 적용(점수 100%)을 제공하며, minifilter 드라이버 + AppContainer(점수 85%)를 통한 네이티브 Windows는 드라이버 서명을 기다리고 있습니다. 자세한 내용은 플랫폼 비교 매트릭스를 참조하세요.

agentsh란 무엇인가?

드롭인 셸/실행 엔드포인트 — 모든 명령(및 그 하위 프로세스)을 감사 가능한 이벤트로 전환합니다.
작업별 정책 엔진: allow, deny, approve(사람 확인), soft_delete, redirect.
전체 I/O 가시성:
- 파일 열기/읽기/쓰기/삭제
- 네트워크 연결 + DNS
- 프로세스 시작/종료
- PTY 활동
- DLP 및 사용량 추적이 포함된 LLM API 요청
- 선언된 db_services를 통한 Postgres 계열 데이터베이스 트래픽
- 시그널 전송/차단(Linux 적용, macOS/Windows 감사)
- 내장 PostgreSQL 프록시를 통한 데이터베이스 쿼리 — 명령문별 분류 및 정책
- 선언된 서비스(http_services)를 통한 아웃바운드 HTTP API 호출 라우팅 — 메서드별, 경로별 규칙, 승인 게이팅, fail-closed 호스트 적용
두 가지 출력 모드:
- 사람에게 친숙한 셸 출력
- 에이전트/도구용 간결한 JSON 응답

왜 agentsh인가?

에이전트 워크플로는 결국 임의의 코드(pip install, make test, python script.py)를 실행하게 됩니다. 전통적인 "명령 실행 전 승인 요청" 방식의 통제는 도구 경계에서 멈추며 해당 명령 내부에서 일어나는 일을 볼 수 없습니다.

agentsh는 런타임에 정책을 적용하므로, 하위 프로세스가 수행하는 숨은 작업도 계속 통제되고 기록되며, 필요한 경우 승인을 받습니다.

의미 있는 차단: deny → redirect("스티어링" 특급 능력)

대부분의 시스템은 작업을 *거부(deny)*할 수 있습니다. agentsh는 또한 **리디렉션(redirect)**할 수 있습니다.

즉, 에이전트가 잘못된 접근 방식(또는 무차별 대입 우회)을 시도할 때, 정책이 명령을 교체하고 안내를 반환하여 에이전트를 올바른 경로로 유도할 수 있습니다 — 에이전트를 포장된 길 위에 유지하고 낭비되는 재시도를 줄여줍니다.

예: curl을 감사 래퍼로 리디렉션```yaml command_rules:

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

**예제: 작업 공간 외부로의 쓰기를 다시 내부로 리디렉션**```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"

에이전트는 성공적인 작업(오류가 아님)을 확인하지만, 실제로 어디에 반영될지는 사용자가 제어합니다.

컨테이너 + agentsh: 함께하면 더 좋습니다

컨테이너는 호스트 표면을 격리하며, agentsh는 컨테이너 내 런타임 가시성과 정책을 추가합니다.

작업별 감사(파일, 네트워크, 명령)를 통해 설치/빌드/테스트 중 어떤 일이 있었는지 보여줍니다.
승인 및 규칙은 최초 명령뿐만 아니라 오래 지속되는 셸과 하위 프로세스 트리 전반에 걸쳐 유지됩니다.
마운트된 작업공간/캐시/자격 증명에 대한 경로 수준 제어; 컨테이너는 기본적으로 그런 세분성을 제공하지 않습니다.
호스트와 컨테이너에서 동일한 동작을 보장하므로 CI와 로컬 개발에서 동일한 정책 결과를 확인할 수 있습니다.

빠른 시작

설치

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

이렇게 하면 ESF+NE 시스템 확장이 포함된 AgentSH 앱 번들이 설치됩니다. 설치 후 **System Settings > General > Login Items & Extensions**에서 시스템 확장을 승인하라는 메시지가 표시됩니다.

**Linux (GitHub 릴리스에서)**

플랫폼에 맞는 `.deb`, `.rpm` 또는 `.apk` 파일을 [릴리스 페이지](https://github.com/erans/agentsh/releases)에서 다운로드하세요.```bash
# Example for Debian/Ubuntu
sudo dpkg -i agentsh_<VERSION>_linux_amd64.deb

소스에서 (Linux)```bash make build sudo install -m 0755 bin/agentsh bin/agentsh-shell-shim /usr/local/bin

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

상세한 macOS 빌드 지침은 macOS 빌드 가이드를 참조하세요.

로컬에서 실행```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

### 무엇이 강제되는지 확인

`agentsh detect`는 호스트를 검사하고 seccomp, Landlock, FUSE, eBPF, ptrace, cgroups 중 실제로 사용 가능한 강제 프리미티브를 보고하며, 이를 도메인별 보호 점수와 선택된 보안 모드로 그룹화합니다. seccomp user-notify 리스너를 설치할 수 없는 제한된 호스트(Daytona, E2B, Firecracker-class)에서는 커널이 단순히 지원하는 모드가 아니라 *실제로* 강제할 모드를 보고합니다.```bash
agentsh detect              # human-readable protection report
agentsh detect config       # emit a config tuned for this host

보안 모드 문서에서 모드 매트릭스와 튜닝 노브를 확인하세요.

에이전트가 사용하도록 지시하기 (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)

---

### 자동 시작 (수동 데몬 단계 없음)

`agentsh server`를 직접 시작할 **필요**는 없습니다.

* 첫 번째 `agentsh exec`(또는 shim 처리된 `/bin/sh`/`/bin/bash`)는 `configs/server-config.yaml`(또는 설정된 경우 `AGENTSH_CONFIG`)을 사용하여 로컬 서버를 자동으로 실행합니다.
* 해당 서버는 세션 수명 동안 FUSE 레이어와 정책 엔진을 유지합니다. 이후 명령은 이를 재사용합니다.
* 서버 수명 주기를 수동으로 관리하려면 `AGENTSH_NO_AUTO=1`을 설정하세요.

---

## Docker에서 사용 (셸 shim 사용)

최소 Debian 기반 이미지에 대해서는 `Dockerfile.example`을 참조하세요.

이미지 내부에서 릴리스 패키지를 설치한 후(또는 빌드를 복사한 후) shim을 활성화하세요:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --i-understand-this-modifies-the-host

shim을 서버(사이드카 또는 호스트)로 지정하십시오:```dockerfile ENV AGENTSH_SERVER=http://127.0.0.1:18080

이제 컨테이너 내의 모든 `/bin/sh -c ...` 또는 `/bin/bash -lc ...` 명령은 agentsh를 통해 라우팅됩니다.

### 비대화형 시행

기본적으로, stdin이 TTY가 아닌 경우 shim은 정책을 우회합니다(파이프된 명령의 바이너리 데이터 보존). 명령이 항상 비대화형이지만 여전히 시행이 필요한 플랫폼(예: exe.dev, sandbox APIs)에서는 `--force`를 추가하십시오:```bash
agentsh shim install-shell \
  --root / \
  --shim /usr/bin/agentsh-shell-shim \
  --bash \
  --force \
  --i-understand-this-modifies-the-host

이것은 시작 시 shim이 읽는 /etc/agentsh/shim.conf를 force=true로 작성합니다. 구성 파일은 (환경 변수나 프로필 스크립트와 달리) 셸이 어떻게 생성되는지와 관계없이 작동합니다. 프로세스 환경의 AGENTSH_SHIM_FORCE=1은 프로세스별로 동일한 효과를 냅니다.

권장 패턴: 동일한 pod/service에서 agentsh를 사이드카(또는 PID 1)로 실행하고 워크스페이스 볼륨을 공유합니다. shim이 모든 셸 이동이 정책 하에 유지되도록 보장합니다.

정책 모델

결정

allow
deny
approve (사람 승인)
redirect (명령 교체)
audit (허용 + 로그)
soft_delete (삭제 격리 및 복원)

범위

파일 작업
명령
환경 변수
네트워크 (DNS/연결)
데이터베이스 (PostgreSQL 프록시를 통한 SQL 문)
PTY/세션 설정
선언된 HTTP 서비스

평가

첫 번째 일치 규칙이 우선합니다

규칙은 명명된 정책에 존재하며, 세션은 정책을 선택합니다.

기본값:

샘플 구성: configs/server-config.yaml
기본 정책: configs/policies/default.yaml
환경 변수 재정의: AGENTSH_POLICY_NAME을 허용된 정책 이름(접미사 없음)으로 설정합니다. 설정되지 않았거나 유효하지 않거나 허용되지 않는 경우 기본값이 사용됩니다.
환경 정책: policies.env_policy(allow/deny, max_bytes, max_keys, block_iteration) 및 정책 파일의 명령별 env_* 재정의를 구성합니다. 빈 허용 목록은 기본적으로 최소 PATH/LANG/TERM/HOME과 내장 비밀 변수 거부 목록으로 설정됩니다. block_iteration을 설정하면 환경 변수 순회를 숨깁니다(env shim 필요).
허용 목록: config.yml에서 policies.allowed를 구성합니다. 비어 있으면 기본값만 허용됩니다.
선택적 무결성: policies.manifest_path를 SHA256 매니페스트로 설정하여 로드 시 정책 파일을 검증합니다.

환경 정책 빠른 참조

기본값: env_allow가 없으면 agentsh는 최소 환경(PATH/LANG/TERM/HOME)을 구성하고 내장 비밀 키를 제거합니다.
재정의: 명령별 env_allow/env_deny와 env_max_keys/env_max_bytes는 실행 시 하위 환경을 제한하고 필터링합니다.
순회 차단: env_block_iteration: true(전역 또는 규칙별)는 환경 변수 열거를 숨깁니다. policies.env_shim_path를 libenvshim.so로 설정하면 agentsh가 LD_PRELOAD + AGENTSH_ENV_BLOCK_ITERATION=1을 주입합니다.
제한: 한도를 초과하면 오류가 발생합니다. env 빌더는 모든 명령의 exec 전에 적용됩니다.
env_inject: 운영자가 신뢰하는 환경 변수로, 정책 필터링을 우회하여 모든 명령에 주입됩니다. 주요 용도: seccomp를 우회하는 셸 내장 기능을 비활성화하는 BASH_ENV. sandbox.env_inject(전역) 또는 정책 수준 env_inject(전역 재정의)에서 구성합니다.

예시 규칙 (일부 발췌)```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

---

### 정책 사용하기```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

인증

agentsh는 여러 인증 방법을 지원합니다:

유형	사용 사례
`api_key`	정적 키를 사용하는 간단한 배포
`oidc`	엔터프라이즈 SSO(Okta, Azure AD 등)
`hybrid`	두 방식 모두 허용

승인 모드 — 사람 개입 검증용:

local_tty - 터미널 프롬프트(기본값)
totp - 인증 앱 코드
webauthn - 하드웨어 보안 키(YubiKey)
api - REST를 통한 원격 승인

구성 세부 정보는 SECURITY.md를 참조하세요.

MCP 보안

도구 허용 목록: 허용 목록/차단 목록 정책을 통해 호출할 수 있는 MCP 도구를 제어합니다.
버전 고정: 구성 가능한 응답으로 도구 정의 변경(rug pull 방지)을 감지합니다.
교차 서버 감지: 데이터 유출 패턴을 차단합니다(서버 A에서 읽기 → 서버 B로 전송).
속도 제한: MCP 서버 및 네트워크 도메인에 대한 토큰 버킷 속도 제한.

전체 구성 옵션은 SECURITY.md를 참조하거나, 이러한 감지 기능을 직접 확인하려면 MCP Protection Demo 를 실행하세요.

60초 데모

가장 빠르게 "이해"하는 방법은 하위 프로세스를 생성하고 파일 시스템/네트워크에 접근하는 무언가를 실행하는 것입니다.```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

**JSON 출력에서 볼 수 있는 항목:**
- `exit_code`: 명령의 종료 상태
- `stdout` / `stderr`: 캡처된 출력
- `events[]`: 정책 결정이 포함된 모든 파일/네트워크/프로세스 작업
- `policy.decision`: `allow`, `deny`, `approve` 또는 `redirect`

팁: 정책을 테스트할 때 `--output json` 옵션으로 터미널을 열어 두면 어떤 항목이 건드려지는지 명확하게 보입니다.

---

### 세션 보고서

세션 활동을 요약하는 마크다운 보고서를 생성합니다:```bash
# Quick summary
agentsh report latest --level=summary

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

보고서에는 다음이 포함됩니다:

결정 요약 (허용, 차단, 리디렉션)
자동 발견 사항 감지 (위반, 이상 징후)
카테고리별 활동 분석
전체 이벤트 타임라인 (상세 모드)

파이프라인 예시는 CI/CD 통합 가이드를 참조하세요.

작업공간 체크포인트

파괴적인 작업으로부터 복구할 수 있도록 작업공간 상태의 스냅샷을 생성합니다:```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

**자동 체크포인트:** 활성화하면 agentsh는 위험한 명령(`rm`, `mv`, `git reset`, `git checkout` 등)을 실행하기 전에 자동으로 체크포인트를 생성합니다. `sessions.checkpoints.auto_checkpoint`에서 구성하세요.

전체 구성 옵션은 [SECURITY.md](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#checkpoint-and-rollback)를 참조하세요.

---

### LLM 프록시 및 DLP

agentsh에는 에이전트의 모든 LLM API 요청을 가로채는 내장 프록시가 포함되어 있습니다:```bash
# Check proxy status for a session
agentsh proxy status <session-id>

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

Features:

Automatic routing: ANTHROPIC_BASE_URL 및 OPENAI_BASE_URL을 설정하여 에이전트 SDK가 프록시를 통해 라우팅되도록 합니다.
Custom providers: LiteLLM, Azure OpenAI, vLLM 또는 기업 게이트웨이로 라우팅합니다.
DLP redaction: PII(이메일, 전화번호, API 키 등)는 LLM 공급자에 도달하기 전에 편집됩니다.
Custom patterns: 조직별 중요 데이터 패턴을 정의합니다.
Usage tracking: 비용 귀속을 위해 토큰 수를 추출하여 기록합니다.
Audit trail: 모든 요청/응답이 세션 저장소에 기록됩니다.

Provider configuration:```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 구성:**```yaml
dlp:
  mode: redact
  patterns:
    email: true
    api_keys: true
  custom_patterns:
    - name: customer_id
      display: identifier
      regex: "CUST-[0-9]{8}"

See LLM Proxy Documentation for full configuration options.

The same proxy also dispatches declared http_services entries — named API upstreams with per-method, per-path rules. See Declared HTTP Services and the HTTP Services Cookbook for details.

Database Access Control (Postgres only today)

agentsh can enforce policy on declared database services through db_services, database_connection_rules, and database_rules. The current implementation is Postgres-family only: PostgreSQL is the supported target, with Aurora Postgres using the same path and Redshift/CockroachDB treated as Postgres-compatible dialects with beta coverage. MySQL, MongoDB, Snowflake, BigQuery, Databricks, ClickHouse, MSSQL, Cassandra, Redis, and Oracle are roadmap items, not current runtime support.

Current Postgres support includes:

Connection allow/deny/approve/audit decisions.
Statement classification for PostgreSQL wire protocol v3, including Simple Query, Extended Query, SQL prepared statements, COPY, FunctionCall denial, transaction state, and CancelRequest mapping.
Strict per-object policy coverage with deny precedence.
Catalog-backed relation/function selectors for resolved-object policies.
Safe runtime redirect for read-only Postgres relation replacement.
Bypass detection and real-Postgres Docker E2E coverage in CI.

The Postgres proxy runtime is Linux-only in-process code today. Use native Linux, WSL2, or a Linux VM environment for database enforcement.

See Database Access Control and Policy documentation.

Policy Generation

Generate restrictive policies from observed session behavior ("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

생성된 정책:
- 세션 중 관찰된 작업만 허용합니다
- 동일 디렉터리에 파일이 많으면 경로를 글로브(glob)로 그룹화합니다
- 하위 도메인을 와일드카드로 축약합니다 (예: `*.github.com`)
- 위험한 명령(curl, wget, rm)을 인자 패턴과 함께 플래그로 표시합니다
- 검토를 위해 차단된 작업을 주석 처리된 규칙으로 포함합니다

**사용 사례:**
- **CI/CD 잠금**: 빌드/테스트 실행을 프로파일링하고 향후 실행을 해당 동작으로 잠급니다
- **에이전트 샌드박싱**: AI 에이전트가 작업을 실행하게 한 다음 향후 실행을 위한 정책을 생성합니다
- **컨테이너 프로파일링**: 워크로드를 프로파일링하고 프로덕션을 위한 최소 정책을 생성합니다

---

## 데이터베이스 액세스 (PostgreSQL)

agentsh는 데이터베이스 액세스를 에이전트 인지형이자 정책 기반으로 만드는 임베디드 **PostgreSQL 프록시**를 포함합니다. Postgres 와이어 프로토콜을 사용하며, 모든 문(statement)을 *효과(effects)* 목록(읽기, 쓰기, DDL, DCL, 트랜잭션/세션 제어, 대량 `COPY`/내보내기, …)으로 분류한 다음, 업스트림으로 전달하기 전에 각 효과를 `database_rules`에 대해 평가합니다. 따라서 `UPDATE`, `DROP`, 또는 범위가 지정되지 않은 `DELETE`도 파일 쓰기나 네트워크 연결과 동일한 방식으로 관리됩니다.

- **효과별 다중 객체 평가** — 규칙은 최초 일치(first-match)가 아니라 전체 수집(collect-all) / **any-deny-wins**(가장 제한적인 동사가 결정) 방식입니다.
- **결정:** `allow`, `deny`, `approve`(인간 승인), `audit`, 및 문(statement) 수준 `redirect`.
- **`require_where` 가드** — `WHERE` 절이 없는 최상위 `UPDATE`/`DELETE`를 거부합니다.
- **연결 수준 규칙**(`database_connection_rules`)은 어떤 세션이 선언된 `db_service`에 도달할 수 있는지를 제어합니다.
- 모든 연결 및 쿼리에 대한 **인증 + 문 감사 이벤트**; 문 텍스트 로깅은 구성 가능합니다(`policies.db.log_statements: none | parameters_redacted | full`).

1단계는 PostgreSQL v3 와이어 프로토콜을 다룹니다(방언: `postgres`, `aurora_postgres`; `redshift` / `cockroachdb`는 베타). 복제 및 GSSAPI 암호화 연결은 기본 거부(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}}"

See the Database Access Control spec for the full operation taxonomy, effects model, connection rules, and unavoidability threat model.

Network Redirect

agentsh can transparently redirect DNS and TCP connections, enabling use cases like routing API calls through corporate proxies or switching AI providers without code changes.

DNS Redirect

Intercept DNS resolution and return configured IP addresses:```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

TCP 연결을 선택적 TLS 처리와 함께 다른 대상으로 리디렉션합니다:```yaml
connect_redirect:
  - match: "api.anthropic.com:443"
    redirect_to: "vertex-proxy.internal:8443"
    tls_mode: passthrough          # Forward encrypted traffic unchanged
    visibility: silent

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

Options

Platform Support

Use Cases

API Gateway 라우팅: Anthropic/OpenAI 호출을 기업 LLM 게이트웨이를 통해 라우팅
프로바이더 전환: Claude API를 GCP Vertex AI 또는 Azure OpenAI로 리디렉션
테스트: 프로덕션 API를 mock 서버로 리디렉션
컴플라이언스: 모든 LLM 트래픽이 감사 프록시를 통과하도록 강제

신호 필터링

agentsh는 프로세스 간에 전송되는 신호(kill, SIGTERM 등)를 가로채서, 어떤 신호가 어떤 대상에 도달할 수 있는지 정책 기반으로 제어합니다.

Platform Support

Example Signal Rules```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` - 모든 신호(1-31)
- `@fatal` - SIGKILL, SIGTERM, SIGQUIT, SIGABRT
- `@job` - SIGSTOP, SIGCONT, SIGTSTP, SIGTTIN, SIGTTOU
- `@reload` - SIGHUP, SIGUSR1, SIGUSR2

### Target Types

- `self` - 자기 자신에게 시그널을 보내는 프로세스
- `children` - 직접 자식 프로세스
- `descendants` - 모든 하위(자손) 프로세스
- `session` - agentsh 세션의 모든 프로세스
- `external` - 세션 외부의 PID
- `system` - PID 1 및 커널 스레드

전체 구성 옵션은 [정책 문서](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#signal-rules)를 참조하세요.

---

## macOS 파일 I/O 모니터링

macOS에서 agentsh는 ESF(Endpoint Security Framework)를 사용하여 파일 I/O를 모니터링하며 AUTH 및 NOTIFY 이벤트를 모두 구독합니다. 추적되는 작업에는 파일 열기, 생성, 삭제, 이름 변경, 쓰기(close-modified를 통해 감지), 그리고 macOS 26 이상에서는 속성 변경 이벤트를 통한 chmod 및 chown이 포함됩니다. 모든 파일 이벤트는 PID 기반 식별을 통해 원래 세션과 명령에 귀속되므로 하위 프로세스 트리 전체에 걸친 완전한 감사 추적을 제공합니다.

ESF는 커널 수준의 허용/거부(allow/deny) 적용을 제공하지만 Linux FUSE와 같은 투명한 파일 인터셉션은 지원하지 않습니다. 인터셉션이 필요한 정책 작업(예: `redirect`(경로 재작성) 및 `soft_delete`(격리))은 거부 + 안내(deny + guidance) 방식으로 구현됩니다. 작업은 ESF 수준에서 차단되고 에이전트는 올바른 경로로 재시도하거나 파일이 보호되고 있음을 인지하라는 지침을 받습니다. 이벤트 스트림 세부 정보는 [macOS ESF+NE 아키텍처 문서](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md)를, 작업별 동작은 [정책 문서](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md#file-rule-actions-on-macos-esf)를 참조하세요.

---

## 시작용 정책 팩

이미 기본 정책(`configs/policies/default.yaml`)이 있습니다. 다음은 팀이 선택할 수 있도록 별도 파일로 제공되는 특정 철학이 담긴 팩들입니다:

* **[`policies/dev-safe.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/dev-safe.yaml)**: 로컬 개발에 안전
  * 작업 공간 읽기/쓰기 허용
  * 작업 공간 내 삭제 승인
  * `~/.ssh/**`, `/root/.ssh/**` 거부
  * 네트워크를 허용 목록의 도메인/포트로 제한

* **[`policies/ci-strict.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/ci-strict.yaml)**: CI 러너에 안전
  * 작업 공간 외부의 모든 것 거부
  * 아티팩트 레지스트리를 제외한 아웃바운드 네트워크 거부
  * 명시적으로 허용되지 않는 한 대화형 셸 거부
  * 모든 항목 감사(요약 이벤트)

* **[`policies/agent-sandbox.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/agent-sandbox.yaml)**: "에이전트가 알 수 없는 코드를 실행" 모드
  * 기본 거부 + 명시적 허용 목록
  * 모든 자격 증명/경로 접근 승인
  * 네트워크 도구 사용을 내부 프록시/미러로 리디렉션
  * 손쉬운 복구를 위해 파괴적 작업을 소프트 삭제(soft-delete)

---

## AI 어시스턴트 통합 예시

AI 코딩 어시스턴트가 agentsh를 사용하도록 구성하기 위한 바로 사용 가능한 스니펫:

* **[Claude Code](https://github.com/canyonroad/agentsh/blob/HEAD/examples/claude/)** - Claude Code 통합용 CLAUDE.md 스니펫
* **[Cursor](https://github.com/canyonroad/agentsh/blob/HEAD/examples/cursor/)** - agentsh 통합용 Cursor 규칙
* **[AGENTS.md](https://github.com/canyonroad/agentsh/blob/HEAD/examples/agents/)** - 범용 AGENTS.md 스니펫(여러 AI 도구와 호환)

> **참고:** 이 예시는 컨테이너 내부에서 AI 에이전트를 실행하는 것이 현실적이지 않은 로컬 개발 시나리오를 위한 것입니다. 프로덕션 또는 CI/CD 환경에서는 셸 심(shim)이 설치된 컨테이너에서 에이전트를 실행하는 것이 좋습니다—[Docker에서 사용](#use-in-docker-with-the-shell-shim)을 참조하세요.

---

## 참고 자료

* **MCP 보호 데모:** [`agentsh-mcp-protection-demo`](https://github.com/canyonroad/agentsh-mcp-protection-demo) - 교차 서버 유출 탐지, 러그 풀 차단, 정책 생성의 라이브 데모
* **보안 및 위협 모델:** [`SECURITY.md`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md) - agentsh가 방어하는 대상, 알려진 제한 사항, 운영자 체크리스트
* **외부 KMS:** [`SECURITY.md#external-kms-integration`](https://github.com/canyonroad/agentsh/blob/HEAD/SECURITY.md#external-kms-integration) - 감사 무결성 키용 AWS KMS, Azure Key Vault, HashiCorp Vault, GCP Cloud KMS
* 구성 템플릿: [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml)
* 기본 정책: [`configs/policies/default.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/policies/default.yaml)
* 예시 Dockerfile(심 포함): [`Dockerfile.example`](https://github.com/canyonroad/agentsh/blob/HEAD/Dockerfile.example)
* **정책 문서:** [`docs/operations/policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/operations/policies.md) - 정책 변수, 시그널 규칙, 네트워크 리디렉션
* **데이터베이스 접근 제어:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - Postgres 전용 데이터베이스 적용 범위, 정책 의미론, 리디렉션 동작 및 로드맵
* **명령 정책 쿡북:** [`docs/cookbook/command-policies.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/command-policies.md) - 새 바이너리를 허용하는 방법, `exec` 대신 `wrap`을 사용해야 하는 시점, 거부를 디버깅하는 방법
* **HTTP 서비스 쿡북:** [`docs/cookbook/http-services.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/http-services.md) - 규칙과 승인 게이팅(gating)을 적용해 아웃바운드 HTTP API 호출을 선언된 서비스를 통해 라우팅하는 레시피
* **샌드박스 SDK 통합 쿡북:** [`docs/cookbook/sandbox-sdk-integrations.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/cookbook/sandbox-sdk-integrations.md) - 명령이 agentsh 서버의 형제 프로세스로 실행되는 Tensorlake / E2B / Modal / Daytona용 `shim_install` 구성
* **정책 작성 스킬:** [`skills/`](https://github.com/canyonroad/agentsh/blob/HEAD/skills/) - Claude Code, NanoClaw 등에서 정책을 생성·편집하기 위한 AI 어시스턴트 스킬
* **플랫폼 비교:** [`docs/platform-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/platform-comparison.md) - 플랫폼별 기능 지원, 보안 점수, 성능
* **Bubblewrap vs agentsh:** [`docs/bubblewrap-vs-agentsh-comparison.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/bubblewrap-vs-agentsh-comparison.md) - Linux 컨테이너 샌드박싱을 위한 Bubblewrap과의 비교
* **데이터베이스 접근 제어:** [`docs/agentsh-db-access-spec.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/agentsh-db-access-spec.md) - PostgreSQL 프록시 분류, 효과 모델, `database_rules`, 연결 규칙, 위협 모델
* **보안 모드 및 `detect`:** [`docs/security-modes.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/security-modes.md) - 적용 모드, 보호 점수 및 `agentsh detect`가 보고하는 내용
* **seccomp:** [`docs/seccomp.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/seccomp.md) - 시스템 콜 필터링, execve 인터셉션, 소켓 패밀리 차단
* **ptrace 모드:** [`docs/ptrace-support.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ptrace-support.md) - 제한된 컨테이너를 위한 PTRACE_SEIZE 적용(`attach_mode`, seccomp 사전 필터)
* **eBPF:** [`docs/ebpf.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/ebpf.md) - eBPF 네트워크 추적 및 정책 적용
* **LLM 프록시 및 DLP:** [`docs/llm-proxy.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/llm-proxy.md) - 내장 프록시 구성, DLP 패턴, 사용 추적
* **macOS 빌드 가이드:** [`docs/macos-build.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-build.md) - ESF+NE 빌드 지침
* **macOS ESF+NE 아키텍처:** [`docs/macos-esf-ne-architecture.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-esf-ne-architecture.md) - 시스템 확장(System Extension), XPC 및 배포 세부 정보
* **macOS XPC 샌드박스:** [`docs/macos-xpc-sandbox.md`](https://github.com/canyonroad/agentsh/blob/HEAD/docs/macos-xpc-sandbox.md) - 샌드박스 프로세스에 대한 XPC/Mach IPC 제어
* 환경 변수(모든 `AGENTSH_*` 재정의, 자동 시작 토글, 전송 선택): [`docs/spec.md` §15.3 "환경 변수"](https://github.com/canyonroad/agentsh/blob/HEAD/docs/spec.md#153-environment-variables)
* 아키텍처 및 데이터 흐름(FUSE + 정책 엔진 + API): [`configs/server-config.yaml`](https://github.com/canyonroad/agentsh/blob/HEAD/configs/server-config.yaml) 및 [`internal/netmonitor`](https://github.com/canyonroad/agentsh/blob/HEAD/internal/netmonitor)의 인라인 주석
* CLI 도움말: `agentsh --help`, `agentsh exec --help`, `agentsh shim --help`

---

에이전트를 위해 에이전트의 도움으로 만들어졌습니다.

`visibility`	`silent`, `audit_only`, `warn`	리디렉션이 기록/표시되는 방식
`on_failure`	`fail_closed`, `fail_open`, `retry_original`	리디렉션 실패 시 수행할 동작
`tls_mode`	`passthrough`, `rewrite_sni`	connect 리디렉션에 대한 TLS 처리

DNS 리디렉션	✅ eBPF	✅ pf/proxy	✅ WinDivert
Connect 리디렉션	✅ eBPF	✅ pf/proxy	✅ WinDivert
SNI 재작성	✅	✅	✅

Linux	예 (seccomp user-notify)	예	예
macOS	아니요	아니요	예 (ES)
Windows	일부	아니요	예 (ETW)

agentsh

인기

agentsh

agentsh란 무엇인가?

왜 agentsh인가?

의미 있는 차단: deny → redirect("스티어링" 특급 능력)

컨테이너 + agentsh: 함께하면 더 좋습니다

빠른 시작

설치

로컬에서 실행```bash

Start the server (optional if using autostart)

Create a session and run a command (shell output)

Structured output for agents

에이전트가 사용하도록 지시하기 (AGENTS.md / CLAUDE.md 스니펫)```md

Shell access

정책 모델

결정

범위

평가

환경 정책 빠른 참조

예시 규칙 (일부 발췌)```yaml

인증

MCP 보안

60초 데모

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

작업공간 체크포인트

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

Database Access Control (Postgres only today)

Policy Generation

Generate policy from latest session

Generate with custom name and threshold

Quick preview to stdout

Network Redirect

DNS Redirect

Options

Platform Support

Use Cases

신호 필터링

Platform Support

Example Signal Rules```yaml

Allow signals to self and children

Redirect SIGKILL to graceful SIGTERM

Block fatal signals to external processes