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(전역 재정의)에서 구성합니다.
• 예시: config.yml 및 configs/ 아래의 정책 샘플을 참조하십시오.

---

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

version: 1 name: default