보안

agent-browser는 자격 증명 노출, 신뢰할 수 없는 페이지 콘텐츠를 통한 프롬프트 주입, 그리고 승인되지 않은 브라우저 작업을 방지하기 위한 보안 기능을 포함하고 있습니다.

모든 보안 기능은 선택적입니다. 기본적으로 agent-browser는 탐색, 작업 또는 출력에 대해 어떠한 제한도 두지 않습니다. 필요에 따라 이러한 기능을 활성화하세요 — 기존 워크플로우는 명시적으로 기능을 활성화하지 않는 한 영향을 받지 않습니다.

위협 모델

이 기능들은 대화형 언어 모델 기반의 에이전트가 브라우저를 조종할 때 다음 위협을 완화하도록 설계되었습니다:

• 자격 증명 노출 — 인증 저장소에 저장된 비밀번호는 언어 모델의 컨텍스트에 포함되지 않습니다. CLI는 저장소 작업을 로컬에서 처리하며, 자격 증명은 디몬의 IPC 채널을 통과하지 않습니다.
• 페이지 콘텐츠를 통한 프롬프트 주입 — 악성 페이지는 도구 출력이나 시스템 지침처럼 보이는 텍스트를 내장할 수 있습니다. 내용 경계 마커(--content-boundaries)는 오케스트레이터가 신뢰할 수 있는 도구 출력과 신뢰할 수 없는 페이지 콘텐츠를 구분할 수 있도록 합니다.
• 승인되지 않은 탐색/데이터 유출 — 해킹되거나 조작된 에이전트가 공격자 제어 도메인으로 탐색하여 데이터를 유출할 수 있습니다. 도메인 허용 목록(--allowed-domains)은 허용되지 않은 도메인으로의 탐색, 하위 리소스 요청, WebSocket 연결, EventSource 스트림 및 sendBeacon 호출을 차단합니다.
• 승인되지 않은 파괴적 작업 — 작업 정책(--action-policy) 및 확인 게이팅(--confirm-actions)은 명시적인 승인 없이 위험한 운영(예: eval, 다운로드, 업로드)을 수행하는 것을 방지합니다.
• 컨텍스트 과부하 — 큰 페이지 출력은 언어 모델의 컨텍스트 창을 가득 채울 수 있습니다. 출력 자르기(--max-output)로 페이지 소스 콘텐츠 크기를 제한합니다.

알려진 제한 사항

• WebSocket/EventSource 차단은 최선의 노력에 기초합니다. 이 기능은 초기화 스크립트를 통해 브라우저 생성자를 덮어쓰는 방식으로 작동합니다. 만약 eval 작업 카테고리가 허용된다면, 페이지 스크립트가 이론적으로 원래 생성자를 복원할 수 있습니다. 최대 보호를 위해 --action-policy를 통해 eval을 거부하세요.
• 원격 연결에서 도메인 필터 적용 시점 문제. CDP 또는 클라우드 제공업체를 통해 기존 브라우저에 연결할 때, 도메인 필터 설치 전에 이미 페이지가 콘텐츠를 로드할 수 있습니다. agent-browser는 필터가 활성화된 후 허용되지 않은 페이지를 about:blank로 이동시키지만, 그 시점 전에 로드된 리소스는 후속으로 차단되지 않습니다.
• 내용 경계는 다층 방어 전략입니다. 이는 언어 모델과 오케스트레이터가 구조적 마커를 존중한다는 가정에 의존합니다. 충분히 능력 있는 악성 페이지는 경계 형식을 모방하려 시도할 수 있지만, 각 프로세스별 CSPRNG 난수 값 때문에 이를 예측하는 것은 실현 불가능합니다.
• 확인 시간 초과. 보류 중인 확인은 60초 후 자동으로 거부됩니다. 오케스트레이터는 해당 시간 내에 응답해야 합니다.
• 비-터미널 자동 거부. --confirm-interactive가 설정되었지만 입력 스트림이 터미널이 아닌 경우(예: 파이프 입력), 동작은 자동으로 거부되어 비대화형 환경에서 부주의한 승인이 발생하는 것을 방지합니다.

인증 저장소

자격 증명을 로컬에 저장하고 이름으로 참조하세요. 언어 모델은 비밀번호를 절대 볼 수 없습니다.

# 자격 증명 저장 (AGENT_BROWSER_ENCRYPTION_KEY가 설정되면 암호화됨)
# 권장: 쉘 히스토리 또는 프로세스 목록 노출을 피하기 위해 비밀번호를 표준 입력으로 전달
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin

# 또는 직접 전달 (경고 메시지가 표시됨)
agent-browser auth save github --url https://github.com/login --username user --password pass

# 저장된 자격 증명으로 로그인
agent-browser auth login github

# 저장된 프로파일 목록 보기 (이름과 URL만, 비밀 정보는 없음)
agent-browser auth list

# 프로파일 메타데이터 보기
agent-browser auth show github

# 프로파일 삭제
agent-browser auth delete github

자동 감지가 실패할 경우 사용자 정의 선택자를 지정할 수 있습니다:

agent-browser auth save myapp \
  --url https://app.example.com/login \
  --username user --password pass \
  --username-selector "#email" \
  --password-selector "#password" \
  --submit-selector "button.login"

프로파일은 ~/.agent-browser/auth/에 저장되며 항상 AES-256-GCM으로 암호화됩니다. AGENT_BROWSER_ENCRYPTION_KEY가 설정되지 않은 경우, 처음 사용 시 ~/.agent-browser/.encryption-key에 자동 생성된 키가 생성됩니다. 이 파일을 백업하거나 환경 변수를 명시적으로 설정하여 이식성을 확보하세요.

유닉스(chmod 600/700)와 Windows(icacls 현재 사용자에게만 제한)에서 파일 권한이 강제 적용되어 다른 사용자가 암호화 키나 인증 프로파일을 읽는 것을 방지합니다.

내용 경계 마커

--content-boundaries가 활성화되면 모든 페이지 기반 출력은 구조적 마커로 감싸져, 언어 모델이 도구 출력과 신뢰할 수 없는 페이지 콘텐츠를 구분할 수 있도록 합니다:

--- AGENT_BROWSER_PAGE_CONTENT nonce=a1b2c3d4 origin=https://example.com ---
[snapshot / text / html / eval 출력 여기에]
--- END_AGENT_BROWSER_PAGE_CONTENT nonce=a1b2c3d4 ---

nonce는 CLI 프로세스 실행마다 생성되는 임의 값이며, 경계를 위조하려는 페이지 콘텐츠가 예측할 수 없도록 합니다.

플래그 또는 환경 변수를 통해 활성화할 수 있습니다:

agent-browser --content-boundaries snapshot
# 또는
export AGENT_BROWSER_CONTENT_BOUNDARIES=1

영향을 받는 출력 유형: snapshot, get text, get html, eval, console.

--json 모드에서는 경계 메타데이터가 _boundary 객체로 포함된 JSON 응답에 주입되어 오케스트레이터가 프로바넌스를 프로그래밍 방식으로 검증할 수 있도록 합니다:

{
  "success": true,
  "data": { "snapshot": "...", "origin": "https://example.com" },
  "_boundary": { "nonce": "a1b2c3d4e5f6...", "origin": "https://example.com" }
}

도메인 허용 목록

브라우저가 상호작용할 수 있는 도메인을 제한하여 리디렉션 기반 공격과 데이터 유출을 방지합니다:

agent-browser --allowed-domains "example.com,*.example.com,github.com" open https://example.com
# 또는
export AGENT_BROWSER_ALLOWED_DOMAINS="example.com,*.example.com"

정확한 일치(github.com)와 와일드카드 접두사(*.example.com, 바이너리 도메인 example.com도 포함)를 지원합니다. 허용되지 않은 도메인으로의 페이지 탐색 및 하위 리소스 요청(스크립트, 이미지, fetch, XHR 등)은 모두 차단되어 데이터 유출을 방지합니다. 또한 생성자 수준 패칭을 통해 WebSocket과 EventSource 연결도 차단됩니다. 비-http(s) 하위 리소스(Data URI, Blob 등)는 여전히 허용됩니다. 요청이 차단되면 명령어는 오류를 반환합니다.

참고: WebSocket/EventSource 차단은 최선의 노력에 기초합니다 — 이는 초기화 스크립트를 통해 브라우저 생성자를 덮어쓰는 방식으로 작동합니다. 만약 eval 작업 카테고리가 허용된다면, 페이지 스크립트가 이론적으로 원래 생성자를 복원할 수 있습니다. 최대 보호를 위해 --allowed-domains를 사용할 때 --action-policy를 통해 eval 카테고리를 거부하세요.

구성 파일:

{
  "allowedDomains": ["example.com", "*.example.com", "github.com"]
}

CDN 및 제3자 리소스: 도메인 필터는 허용되지 않은 도메인으로의 모든 하위 리소스 요청(스크립트, 스타일시트, 이미지, 폰트, fetch/XHR 등)을 차단합니다. 대부분의 웹사이트는 CDN 도메인에서 자산을 로드합니다. 이들을 허용 목록에 포함하거나 페이지가 깨질 수 있습니다. 예를 들어:

--allowed-domains "myapp.com,*.myapp.com,cdn.jsdelivr.net,fonts.googleapis.com,fonts.gstatic.com"

작업 정책

정적 정책 파일을 사용하여 작업을 게이트링합니다. 정책은 디몬에서 강제 시행되며, 거부된 작업은 즉시 실패합니다.

agent-browser --action-policy ./policy.json open https://example.com
# 또는
export AGENT_BROWSER_ACTION_POLICY=./policy.json

예시 정책(일반적인 허용과 특정 거부):

{
  "default": "allow",
  "deny": ["eval", "download", "upload"]
}

예시 정책(엄격한 제한):

{
  "default": "deny",
  "allow": ["navigate", "snapshot", "click", "scroll", "wait", "get"]
}

인증 저장소 작업(auth save, auth login, auth list, auth show, auth delete) 및 기타 내부/메타 작업은 신뢰할 수 있는 로컬 작업이므로 작업 정책 적용을 우회합니다. 하지만 auth login 탐색에는 여전히 도메인 허용 목록 제약이 적용됩니다.

작업 확인

명시적 승인이 필요한 작업의 경우, --confirm-actions 플래그를 사용해 승인이 필요한 카테고리를 지정합니다:

# 오케스트레이터 모드: 확인 필요 응답 반환
agent-browser --confirm-actions eval,download eval "document.title"

# 이후 승인 또는 거부:
agent-browser confirm c_8f3a1234
agent-browser deny c_8f3a1234

대화형(사람이 개입하는) 확인을 위한 경우:

agent-browser --confirm-actions eval,download --confirm-interactive eval "document.title"
# 프롬프트: 허용하시겠습니까? [y/N]

보류 중인 확인은 60초 후 자동으로 거부됩니다.

비-터미널 동작: --confirm-interactive가 설정되었지만 표준 입력이 TTY가 아닐 경우(예: 파이프 입력 또는 자동화 파이프라인 내에서 실행), 동작은 자동으로 거부됩니다. 이는 비대화형 환경에서 부주의한 승인이 발생하는 것을 방지합니다.

출력 길이 제한

큰 페이지 출력으로 인한 컨텍스트 과부하를 방지하기 위해 출력을 자르는 기능을 제공합니다:

agent-browser --max-output 50000 get text body
# 또는
export AGENT_BROWSER_MAX_OUTPUT=50000

영향을 받는 출력 유형: snapshot, get text, get html, eval, console.

환경 변수

추천 구성

생산 환경용 AI 에이전트 배포를 위한 구성:

{
  "contentBoundaries": true,
  "maxOutput": 50000,
  "allowedDomains": ["your-app.com", "*.your-app.com"],
  "actionPolicy": "./policy.json"
}