AgentBeam
AgentBeam은 AI 에이전트를 위한 로컬 보안 계층입니다. beam은 AgentBeam CLI입니다. 이 도구는 사용자의 장치에서 감지된 에이전트에 대한 훅(hooks)을 설치하고, 에이전트 및 MCP 활동을 포착하며, AgentBeam 정책을 로컬에 적용하고, 승인된 원격 측정 데이터(telemetry)를 AgentBeam 대시보드로 전송합니다.
전체 문서, 가이드 및 쿡북: docs.agentbeam.com. 이 README는 빠른 참고 자료이며, 공식 문서는 각 기능을 심층적으로 설명하고 있으며, 그곳의 모든 페이지는 코딩 에이전트에게 전달될 수 있습니다.
WipeBench: 코딩 에이전트 안전 벤치마크
WipeBench는 코딩 에이전트에게 객관적인 기준을 제공하고, 선택된 명령어를 포착하며, Docker 환경에서 작업 완료 및 유해한 영향을 평가합니다. 이는 AgentBeam과 ExplainX.ai가 협력하여 만든 벤치마크입니다.
로컬 스냅샷에는 12개 카테고리에 걸쳐 112개의 점수화된 시나리오와 키가 필요 없는 스모크 테스트가 포함되어 있습니다:
python3 safety-bench/bench.py selftest --scenarios smoke-hello
Python 3.11 이상 및 실행 중인 Docker 데몬이 필요합니다. 스크립트형 자체 테스트는 하네스(harness)를 검증하는 것이며, 모델 순위가 아닙니다. 이 벤치마크 스냅샷은 자체 Apache-2.0 라이선스를 사용합니다. 범위 및 사용법에 대해서는 벤치마크 페이지를 참조하십시오.
설치 및 설정
npm i @agent-beam/beam -g
beam setup
beam setup은 주요 명령어입니다. 이 명령어는 지원되는 에이전트를 감지하고, 해당 에이전트의 네이티브 AgentBeam 훅을 설치하며, 구성된 MCP 서버를 인벤토리화하고, 장치를 대시보드에 연결하며, 조직 및 사용자 정책을 다운로드하고, 영구 백그라운드 서비스를 시작합니다.
설정 후에는 선택된 에이전트가 자동으로 보호됩니다. beam run을 실행하거나 수동으로 컬렉터를 시작할 필요가 없습니다.
또는 코딩 에이전트가 설정하도록 하세요
npx @agent-beam/beam add skill agentbeam-setup -g --all-agents
이는 Claude Code, Codex, Cursor, Gemini CLI, OpenCode 및 GitHub Copilot CLI용 AgentBeam 설정 스킬을 설치합니다. 그런 다음 에이전트에게 "AgentBeam 설정(set up AgentBeam)"을 요청하세요. 그러면 CLI를 설치하고 브라우저 로그인(browser sign-in)이 필요한 부분에 대해 beam setup 명령어를 제공하며, 모든 것이 정상적으로 실행되는지 확인합니다.
유용한 명령어 (Useful commands)
beam setup
beam service status
beam agent list
...
에이전트를 추가하거나 설치를 복구할 때는 beam setup을 다시 실행하세요. 이 명령어는 기존 에이전트 구성을 유지합니다.
업데이트 (Updates). Claude Code와 마찬가지로 Beam은 자체적으로 최신 상태를 유지합니다. 최대 하루에 한 번, 대화형(interactive) beam 명령어가 새 릴리스가 있는지 확인하고 백그라운드에서 설치하므로, 실행한 명령어는 기다리는 시간이 없습니다. 다음 명령어는 작업이 완료되었고 무엇을 다시 시작해야 하는지 알려줍니다.
- 에이전트 훅 내부,
beam run, beam monitor, CI 또는 비대화형(non-interactive) 셸 내에서 절대 실행되지 않으며, sudo를 요청하지 않습니다. 설치에 높은 권한이 필요한 경우, beam update을 실행하도록 안내합니다.
- 사용자별로
beam update --auto off를 사용하거나, 플릿 전체적으로 BEAM_DISABLE_AUTOUPDATE=1 (예: MDM을 통해)을 사용하여 비활성화할 수 있습니다.
- 독립형 바이너리(Standalone binaries)의 경우 다운로드 링크가 표시됩니다.
AgentBeam이 보호하는 것 (What AgentBeam protects)
조직 정책에 따라 AgentBeam은 승인 요청, 차단, 마스킹(redact), 또는 로깅을 수행할 수 있습니다:
- 환경 변수 및
.env 파일
- API 키, 토큰, 비밀번호, 개인 키 및 클라우드 자격 증명
- 현재 작업 공간 외부의 파일
- 파괴적인 명령어 및 프로덕션 변경 사항
- MCP 쓰기 또는 부작용 도구
- AgentBeam 정책/데이터 수정 시도, AgentBeam 서비스 중지, 또는 AgentBeam 제거 시도
MCP 응답은 민감한 콘텐츠가 에이전트에 도달하기 전에 로컬에서 필터링될 수 있습니다. MCP 인벤토리와 활동 내역은 대시보드에 보고되어 관리자가 한 사용자 또는 전체 조직의 서버를 검토하거나 차단할 수 있도록 합니다.
다중 에이전트 지원 (Multi-agent support)
AgentBeam은 Claude 전용이 아닙니다. 설정 과정에서 장치에 실제로 설치된 에이전트를 검색하고 선택된 각 에이전트에 적절한 네이티브 훅(hook)을 설치합니다.
Beam은 이제 호스트가 노출하는 경우 프롬프트, 사전 도구 호출(pre-tool calls), 결과, 실패, 권한 및 세션/서브 에이전트 이벤트 등을 포괄하는 27개의 네이티브 에이전트 훅/플러그인 통합을 제공합니다. 지원되는 에이전트는 Claude Code, Codex, Cursor, Copilot CLI, VS Code Copilot Chat, Gemini, Windsurf/Devin Desktop, OpenCode, OpenClaw, Pi, Kimi, Qwen, Cline, Amp, Auggie, Kiro, Goose, Kilo, OpenHands, Crush, Junie, Antigravity, Factory Droid, Grok Build, Devin CLI, Hermes, Muse Code를 포함합니다. Jev는 여전히 검색 전용입니다.
정확한 이벤트 이름은 beam agent list --events를 실행하거나 전체 커버리지 및 캡처 가이드를 참조하십시오. 감지된 에이전트를 업그레이드하려면 beam agent install-all을 다시 실행한 다음, 영향을 받은 호스트를 재시작하고 필요한 경우 변경된 훅을 승인해야 합니다. OpenHands는 명시적인 리포지토리 설정 경로가 필요하며, VS Code는 Copilot의 훅 파일을 공유합니다.
활동 기록에는 마스킹된 사용자 프롬프트, 도구 인수/결과, 파일 및 디렉토리 경로, 검색어, URL, 제공된 편집 세부 정보가 포함됩니다. Studio에서 액션을 열어 이러한 필드를 검사하십시오. 수집기(collector)를 사용할 수 없을 때 이벤트는 로컬에 큐에 저장됩니다. 캡처는 제한적이며 호스트 콜백에 의존합니다. 쉘 측 효과 및 비계측 도구는 훅으로부터 완전히 재구성될 수 없습니다.
에이전트 구성은 원본 파일 백업과 함께 기존 설정과 병합됩니다. 새로운 통합 기능은 고정값(fixture) 및 생성된 콜백 커버리지를 갖추고 있지만, 실제 호스트/버전 유효성 검사는 여전히 필요합니다.
선택적 Jev 액션 판단 (Optional Jev action judging)
Noul(두 개의 독립적인 위험 질문), Score(손상 평가 기준) 또는 둘 다를 사용하여 제안된 액션을 검토하려면 TypeSafe Jev를 사용하십시오. 이는 위 에이전트 테이블에 있는 타사 Jev CLI 검색과는 별개입니다. 이 통합 기능은 기본적으로 비활성화되어 있습니다. 활성화하면 선택되고 마스킹된 액션 데이터가 TypeSafe의 원격 API로 전송되며 비용이 발생할 수 있습니다.
쉘 또는 시크릿 매니저를 통해 TYPESAFE_API_KEY를 공급한 다음, 다음을 실행합니다:
beam jev configure --mode observe --primitive both
beam jev status
쉘 환경을 상속받지 않는 영구적인 후크(hooks)의 경우, 시크릿 매니저에서 키를 beam jev configure --key-stdin으로 파이프합니다. 키는 모드 0600으로 ~/.beam/jev.json (또는 BEAM_HOME/jev.json)에 저장됩니다. 절대로 키를 명령어 인수로 전달하지 마십시오. 환경 변수 키가 저장된 키보다 우선합니다. 설정을 직접 오퍼레이터(operator)로서 실행하십시오. Beam의 자체 보호 기능이 에이전트가 이러한 설정을 변경하는 것을 차단합니다.
명시적인 확인을 위해 action.json을 생성합니다:
{
"action": { "tool": "Bash", "command": "git diff --stat" },
"context": "Inspect workspace changes without modifying files."
...
}
beam jev judge action.json --dry-run
beam jev judge action.json
beam jev configure --mode enforce --primitive both
...
configure는 기존의 사전 도구 후크(pre-tool hooks)에서 확인을 활성화하며, 이를 설치하는 것은 아닙니다. 관측(Observation)은 판단을 표준 오류 스트림(stderr)에 출력하고 로컬 정책을 유지합니다. 강제 적용(Enforcement)은 검토(review), 거부(deny) 또는 평가 오류가 발생하면 적격한 작업을 차단합니다. 로컬 거부, 승인 및 마스킹 결정이 우선하며 Jev를 건너뜁니다. 프롬프트/도구 후 이벤트와 오프라인 beam scan은 Jev를 건너뜁니다. 명시적인 judge 명령어는 후크 모드에 관계없이 자체 판결을 보고하며, 절대 작업을 실행하지 않습니다.
| 점검 항목 | 통과 (Pass) | 거부 (Deny) | 검토 (Review) |
|---|
| Noul: 데이터 노출 및 비가역적 파괴 | 둘 다 ≤ 0.2 | 어느 하나 ≥ 0.8 | 그 외 |
| ... | | | |
| 이 초기 임계값들은 측정된 안전 보장이 아닌 보수적인 기본값입니다. Noul은 별도의 신뢰도를 갖지 않습니다. 점수는 분포와 신뢰도를 포함합니다. 잘못 구성된 설정(malformed config)의 경우 오류를 보고 선택적 점검을 건너뛰어 로컬 정책을 유지하며, Jev 커버리지를 복원하려면 이를 수정해야 합니다. 요청은 고정된 HTTPS 엔드포인트, 2초 타임아웃, 자동 재시도 없음, 32 KB 입력 제한 및 64 KB 응답 제한을 사용합니다. | | | |
후크(Hook) 요청에는 에이전트, 도구, 도구 입력 및 명령만 포함되며, 알려진 자격 증명 패턴, 민감한 필드 이름 및 정책 사용자 정의 감지기가 먼저 마스킹됩니다. 도구 인자에는 여전히 사적 소스 또는 데이터가 포함될 수 있으며, 마스킹이 모든 비밀 정보를 제거한다고 보장할 수는 없습니다. 후크는 녹취록(transcripts), 참조된 파일 내용, 사용자의 작업 또는 환경을 Jev 상태에 로드하지 않습니다. 명시적 파일은 짧은 context 문자열을 포함할 수 있습니다. 후크 적용 여부는 설치된 클라이언트의 지원 여부에 달려 있으며 계측되지 않은 동작이나 모든 MCP 전송(transport)을 포괄하지는 않습니다. disable은 제공자 키를 취소하거나 외부 환경 변수를 해제하지 않습니다.
번들된 Jev 액션 판단 스킬을 사용하거나, Beam 워크스루를 읽거나, Awesome Jev 사용 사례 모음을 탐색하십시오. API 의미론: Noul, Score, HTTP 참조.
모든 LLM 또는 결정 서비스로 선택적 판단 (Optional judging with any LLM or decision service)
beam judge는 Jev와 유사하게 작동하지만 사용자가 선택한 모델을 사용합니다. 기본적으로 비활성화되어 있습니다. 제공자 하나를 선택하십시오:
llm: OpenAI와 호환되는 chat completions 엔드포인트 뒤에 있는 모든 모델을 의미합니다. 예시로는 OpenAI, OpenRouter, LiteLLM 게이트웨이 또는 로컬 Ollama나 vLLM 서버가 있습니다. Beam은 이 llm에게 특정 액션에 대한 허용(allow), 검토(review) 또는 거부(deny) 판결을 요청합니다.http: 사용자가 직접 결정하는 서비스입니다. 내부 정책 엔진, 분류기(classifier) 또는 API 뒤에 있는 미세 조정된 모델일 수 있습니다.
op read op://vault/openai/key | beam judge configure --provider llm --key-stdin
...
결정 서비스는 POST {"version":1,"action":{"agent","tool","input","command"},"context"?}를 수신하며, 반드시 {"verdict":"allow"|"review"|"deny","reason":"..."}로 응답해야 합니다. verdict 대신 decision 필드를 사용할 수도 있습니다. 키가 있다면, 이는 BEAM_JUDGE_API_KEY에서 가져오거나 ~/.beam/judge.json (모드 0600)에 저장되며, Authorization: Bearer 헤더로 전송됩니다.
안전 규칙은 Jev의 규칙을 따릅니다:
- 이는 오직 사전 도구 후크(pre-tool hooks)에서만 실행되며, 로컬 정책이 해당 액션 실행을 허용할 때에만 작동합니다.
- 입력값 또한 동일하게 마스킹됩니다.
- 관찰 모드(Observation mode)가 기본입니다. 오직
--mode enforce만이 액션을 차단하며, review, deny 또는 오류 발생 시에도 마찬가지입니다.
- 일반 모델의 거부는
review로 간주됩니다. 읽을 수 없는 모든 것은 에러로 간주되며, 절대 allow로 간주되지 않습니다.
- 요청은 기본적으로 3초 후에 시간 초과(timeout)됩니다 (
--timeout-ms, 500에서 15000 사이).
- Agent는
beam judge configure 또는 beam judge disable를 실행할 수 없습니다.
Jev와 beam judge는 함께 작동할 수 있습니다. 각각은 모든 적격 도구 호출에 자체적인 대기(wait) 기능을 추가합니다.
앱 모니터링 (선택 사항)
beam monitor는 AI 에이전트가 아닌 실행 중인 애플리케이션을 관찰합니다. 이는 애플리케이션의 로그 파일과 HTTP 접근 로그를 24시간 감시하며, 공격이나 손상처럼 보이는 활동에 대해 경고를 발생시킵니다. beam cve check는 앱의 종속성(dependencies)에서 알려진 취약점을 확인합니다.
두 가지 모두 연결된 작업 공간이 필요하며, 앱 모니터링(App monitoring)을 대시보드에서 워크스페이스 소유자나 관리자가 켜기 전까지는 작동하지 않습니다. 그전까지 beam monitor는 기다리며 아무것도 포착하지 못합니다.
export BEAM_APP_TOKEN=beam_app_...
beam monitor --file /var/log/nginx/access.log --file /var/log/app/app.log
beam monitor --llm openai --file /var/log/app/app.log
...
앱 및 토큰(Apps and tokens). 대시보드에서 앱 모니터링 > 설정, 앱 및 알림(App monitoring > Settings, apps and alerts)에 각 앱(bgremover, explainx 등)을 추가하여 자체 토큰을 얻고, 이 토큰은 한 번만 표시됩니다. BEAM_APP_TOKEN이 설정되면, beam monitor와 beam cve check는 해당 앱으로 보고되며, 그 발견 사항, 필터 및 웹훅 라우팅이 다른 앱과 분리되어 유지됩니다. beam connect로 연결된 노트북은 토큰 없이 작동합니다. 토큰은 최소 권한 원칙(least-privilege)을 따릅니다:
- 앱 모니터링에서만 작동하며, 다른 모든 AgentBeam API는 이를 거부합니다.
- 해시 값만 저장되며, CLI는 일반 HTTP를 통해 전송하는 것을 거부합니다.
- Beam은 자체 토큰을 로그 및 증거 자료(evidence)에서 마스킹합니다.
- 각 앱에는 분당 요청 제한이 있습니다.
- 토큰을 순환하거나 제거하면 즉시 효력이 발생합니다.
앱을 계속 실행하는 환경(systemd 유닛, 로그 볼륨을 공유하는 사이드카 컨테이너, 또는 pm2)에서 실행하십시오.