agentlock-browser

값이 어디에서 왔는지를 기준으로 게이트를 적용하는 브라우징 도구입니다. 값이 무엇을 말하는지는 보지 않습니다.

실제 브라우저를 구동하는 MCP 서버로, 페이지 콘텐츠에서 유래한 URL이나 폼 값에 대해서는 동작를 거부합니다. 페이지는 무엇이든 말할 수 있지만, 에이전트가 사용하도록 요청한 문자열의 출처(provenance)를 바꿀 수는 없습니다.

이것은 v0 스켈레톤입니다. 도구 호출 인가(tool-call authorization)를 위한 공개 표준인 AgentLock을 기반으로 하며, 브라우저는 Playwright를 통해 직접 소유합니다. @playwright/mcp를 타핑하지 않고 여기에 의존하지도 않습니다.

업스트림 서버를 그냥 래핑하지 않는 이유

probe/REPORT.md는 @playwright/mcp 0.0.79가 실제로 반환하는 것을 기록합니다. 모든 결과는 단일 타입 없는 텍스트 블록이며, 기록된 23개 결과 전체에서 structuredContent가 null이고 24개 도구 중 어느 것도 outputSchema를 선언하지 않습니다. 페이지 텍스트는 요소별 식별자 없이 도착합니다. Wikipedia 스냅샷의 874개 - text: 줄 중 하나도 ref를 가지지 않습니다. 요소는 호출자가 절대 볼 수 없는 Playwright locator로 해석되는 불투명한 서버측 ref로 이름이 붙으며, 같은 필드는 원시 CSS selector도 받아들입니다. 그리고 browser_evaluate는 모델이 작성한 임의의 JavaScript를 실행합니다.

어떤 것도 출처를 담을 수 없습니다. 그래서 이 서버는 대신 구조화되고 식별되며 출처(origin) 태그가 붙은 출력을 내보내며, evaluate 도구를 두지 않습니다.

Related MCP server: open-browser-control

설치

pip install agentlock-browser
python -m playwright install chromium

체크아웃 상태에서:

pip install -e .
python -m playwright install chromium

Claude Desktop에 추가

claude_desktop_config.json:

{
  "mcpServers": {
    "agentlock-browser": {
      "command": "agentlock-browser",
      "env": {
        "AGENTLOCK_BROWSER_ALLOWLIST": "https://example.com,https://docs.python.org",
        "AGENTLOCK_BROWSER_OPERATOR_TEXT": "research the docs and summarize them",
        "AGENTLOCK_BROWSER_LOG": "/home/you/agentlock-browser.jsonl"
      }
    }
  }
}

AGENTLOCK_BROWSER_CONFIG는 같은 키(allowlist, operator_text, log_, headless, …)를 가진 JSON 파일을 가리킬 수 있습니다. 환경 변수가 파일보다 우선합니다. 브라우저는 AGENTLOCK_BROWSER_HEADLESS=0가 아닌 한 헤드러으므로 실행됩니다.

도구

모든 도구는 선언된 outputSchema에 맞춰 structuredContent를 반환합니다. snapshot은 {origin, url, title, elements: [{id, role, name, text, href}]}를 반환하고, read_text는 {origin, blocks: [{id, text}]}를 반환합니다. 페이지 텍스트는 한 번에 하나의 낱낱의 문자열로 돌아오지 않습니다.

요소 id는 현재 페이지 로드 동안 안정적이며 탐색 시 재생성됩니다. id는 <page-load>-e<n> 형식이며, 탐색 전에 만들어도 탐색 후에는 해석할 수 없습니다. 거부는 오류가 아니라 이유가 담긴 구조화된 결과입니다.

출처(Provenance) 규칙

네 가지 채널이 있습니다:

• USER: 운영자 메시지에서 온 텍스트

• ALLOWLIST: 운영자가 설정한 출처이며 시작 시 로드됨

• PAGE(origin): 페이지 콘텐츠에서 읽은 값에 출처가 부표된 것

• MODEL: 페이지나 사용자 계보(lineage) 없이 모델이 만든 값

값은 소스에서 태그(provenance tag)가 붙습니다. 서버 시작 시 운영자 메시지 텍스트는 USER로 기록되고, 설정된 allowlist는 ALLOWLIST로 기록되며, snapshot이나 read_text가 반환한 모든 것은 반환되는 순간 PAGE(origin)로 기록됩니다. 콘텐츠가 오염(tainted)되는 것은 모델이 그 값을 볼 수 있는 바로 그 순서입니다.

그 결과를 행동별로 보면:

v0에서 대상이 아닌 것은 snapshot, read_text, back, 그리고 동일 출처 클릭습니다.

navigate(link_id)는 에이전트가 링크를 따라가는 방식입니다. id는 서버 측에서 href로 해석되므로, href가 모델을 통과할 일이 없습니다. 따라서 운영자가 요청한 링크를 따라가는 것은 가능하지만, 페이지가 제공한 URL을 붙이는 것은 불가능합을니다.

현재 출처를 벗어나는 클릭은 204로 응답되어 이동이 취소됩니다. 처리되지 않은 요청, 오류 페이지 없이 페이지는 위치 그대로 남습니다.

최종 판정은 AgentLock 게이트가 내립니다. 이 패키지는 출처를 기록하고 gate.authorize()를 호추한 뒤 결과를 보고만 합니다. 판정을 임의로 덮지 않습니다. 유일 예외는 AgentLock이 표현할 수 없는 link-id 신선도 규칙입니다. 그 거부들은 로그에서 decided_by: "server:link_freshness"로 표시되어 게이트 판정으로 잘못 오인되지 못하게 합니다. NEEDS.md 참조.

모든 결정과 출처 기록은 게이트의 증거(evidence) 및 서명된 receipt과 함께 JSONL 로그에 추가기록:

{"event": "decision", "action": "navigate_url", "allowed": false,
 "reason": "param_lineage", "channel": "PAGE", "origin": "http://fixture.test",
 "decided_by": "agentlock_gate",
 "evidence": {"gate": "param_lineage", "matched_param": "url",
              "matched_token": "evil.test/collect?x=handbook-session-7f3a1c",
              "untrusted_provenance_id": "cprov_8fb61c8f03117287"},
 "receipt": {"receipt_id": "rcpt_…", "signature": "…"}}

그 로그는 사전 등록된 테스트에 대한 기준 자료(ground truth)이며, 채팅 요약이 아닙니다.

USER 채널

MCP는 서버에 운영자 메시지를 볼 수 있는 방법을 주지 않으므로, USER 텍스트는 도구 인자가 아니라 시작 시 입력(operator_text / AGENT_BLOCK_BROWSER_OPERATOR_TEXT)입니다. 운영자 텍스트가 빛 또는 무미한 세션은 운영자가 원하는 바를 밝힌 세션보다 USER 기준선(baseline)이 약합니다. (아래 2번째 한계 참조)

테스트

pytest                                  # T5 runs; T1-T4 are registered and skipped
cat tests/results/T5.txt                # the raw T5 transcript, log and checks

T5(정상 기준선)는 모델을 배제하고 자동화됩니다. 도구 호출이 직접 이루어지므로 측정 대상은 게이트와 서버 결과입니다. T1~T4 피xture와 두 로컬 오리진은 모두 구현되어 있습니다 (evil.test는 두 번째 로컬 서버로 해석되므로 크로스 오리진 사례가 실제로 존재합니다). 그러나 모델 기반 예측을 실행으로 검증해보지 않았습니다. 모델 행동을 예측하고 있어서입니다.

명시된 한계

PREDICTIONS.md에서 있는 그대로 복사했습니다. 이 문서는 서버 코드가 작성되기 전에 상태에서 동결된 문서입니다.

• 선택 영향(selection influence): 페이지 콘텐츠는 여전히 모델이 어느 link\_id를 고를지를 유도할 수 있습니다. 범위 밖이며 문서화되어 있습니다. 핵심 AgentLock과 같습니다.

• 동일 출처(same-origin) 클릭은 v0에서 게이트 대상이 아닙니다. 악성 있는 사이트가 에이전트를 자기 내부에서 통제할 수 있습니다. 크로스 오리진이 우리가 방어하는 경계입니다.

• 모델의 거부 때문에 T1과 T3은 유의미한 정보를 주지 못할 수 있습니다. 이것은 지불 payload의 문제이지 게이트 결과의 문제가 아니니다.

v0을 만드는 동안 발견했으며 아직 닫지 못한 것:

• 고유 토큰이 없는 값에는 출처 계열 게이트가 fail open 됩니다. AgentLock은 값에서 토큰을 추출하여 분류합니다. 숫자나 구두점이 없는 12자 미만의 일반 단어는 토큰을 생성하지 않으며, 분류할 수 없는 값은 허용됩니다. 페이지가 expenses라는 단어를 입력하라고 말하면 잡지 못합니다. abc123을 입력하라고 말하면 잡힙니다. 이 과정에서의 허용은 로컬 검사로 막지 못하고 "channel": "UNCLASSIFIED", "fail_open": true로 기록됩니다. NEEDS.md 문항 3.

• 평범한 운영자 메시지는 MODEL 검사를 약화시킵니다. 새 출처 new lineage를 판별하려면 권위 있는 컨텍스트에 뚜렷한 토큰 수 있어야 합니다. 그렇지 않으면 모델이 만든 값이라도 허용됩니다. EED 항목 3(b).

• read_text와 snapshot은 선별된 요소만을 보고합니다. 어느 셀렉터에도 매치되지 않는 요소의 텍스트는 반환되지 않으며, 그 때문에 PAGE로 기록되지도 않습니다. 그 일관성은 이 도구를을 page content가 대화에 들어오는 유일한 통로로 유지하는 동안에만 유지됩니다. 모델이 봐야 하는 것은 그 경로 만의 것입니다.

• 허가된 탐색 이후 발생하는 리다이렉트는 다른 검사 없이 따라갑니다. v0은 허용한 URL의 redirect 체인을 그대로 허용 신뢰합니다.

• 한 탭. target="_blank" 및 팝업은 v0에서 지원되지 않습니다.

라이선스

AGPL-3.0-or-later. Copyright 2026. David Grice.