Managed Agents 배포 보안 강화하기

이 가이드는 Claude Managed Agents의 에이전트가 접근하고 수행할 수 있는 범위를 제한하는 설정을 중요도 순으로 나열합니다. 각 섹션은 해당 설정을 자세히 다루는 페이지로 연결됩니다.

보안 위험과 샌드박스 경계에서는 이러한 설정이 중요한 이유와 이 설정들이 보호하지 못하는 부분을 설명합니다. 세션을 검토하고 모니터링하려면 에이전트 세션 검토 및 모니터링을 참조하세요.

에이전트 실행 위치 선택하기

에이전트의 도구가 실행되는 위치에 따라 샌드박스를 보호하는 주체가 결정됩니다. 클라우드 환경에서는 Anthropic이, 자체 호스팅 샌드박스에서는 사용자가 보호합니다. 둘 중 하나를 선택하고 각각의 경우 어떤 정보가 Anthropic에 전달되는지 알아보려면 에이전트 환경 선택하기를 참조하세요.

자체 호스팅 샌드박스를 사용하는 경우 다음 네 가지 사항에 유의하세요.

• 네트워크: 네트워크 제한하기는 클라우드 환경에 적용됩니다. 자체 호스팅 샌드박스의 경우 자체 방화벽에서 해당 트래픽에 동등한 제한을 설정하세요. 방화벽은 에이전트가 선언한 MCP 서버를 제한하지 않으므로, 해당 서버와 애플리케이션이 세션에 설정하는 서버를 검토하세요.
• 웹 도구: 웹 도구는 Anthropic의 서버에서 실행되므로 방화벽으로 제한되지 않습니다. 도메인 목록으로 제한하세요. 웹 검색 및 웹 가져오기 제한하기를 참조하세요.
• 자격 증명: 환경 변수 자격 증명은 아직 자체 호스팅 샌드박스에서 지원되지 않습니다.
• 격리 및 보안 강화: 둘 다 사용자의 책임입니다. 보안 모델을 참조하세요.

어느 옵션을 선택하든 Managed Agents의 규정 준수 범위나 세션 기록 보관 기간은 달라지지 않습니다. 세션 모니터링 및 보존 검토를 참조하세요.

네트워크 제한하기

networking.type을 limited로 설정하고 allowed_hosts에 에이전트에 필요한 호스트만 나열하세요. networking을 생략한 환경 생성 요청은 unrestricted가 될 수 있으므로, 모든 생성 요청에 networking을 설정하세요. 제한 없는 네트워킹의 위험을 참조하세요.

연결한 파일, 메모리 스토어, GitHub 리포지토리는 allowed_hosts와 관계없이 에이전트가 계속 사용할 수 있습니다.

이 페이지의 예시는 지원 에이전트를 사용합니다. 이 에이전트는 고객의 티켓을 읽고, 주문을 조회하고, 헬프 센터를 읽은 다음 답변 초안을 작성합니다. 주문 조회는 애플리케이션이 실행하며 호스트가 필요하지 않으므로, 이 환경은 web_fetch를 위해 헬프 센터라는 하나의 호스트만 허용합니다.

ant apply environment.yaml

# yaml-language-server: $schema=https://platform.claude.com/schemas/ant/beta/environment.json
name: support-agent
config:
  type: cloud
  networking:
    type: limited
    allowed_hosts:
      - help.example.com

limited 환경에는 세 가지 네트워킹 설정이 있습니다.

allow_package_managers 및 allow_mcp_servers 설정은 웹 검색 및 웹 가져오기에 대한 호스트를 추가하지 않습니다.

allow_mcp_servers는 기본값인 꺼진 상태로 두고, 운영하거나 신뢰하는 각 MCP 서버의 호스트를 allowed_hosts에 나열하세요. 나열한 각 호스트는 샌드박스의 코드에도 개방됩니다. allow_mcp_servers가 꺼져 있으면, 세션 생성 시 검사에서 MCP 서버의 호스트가 나열되지 않은 경우 요청을 거부합니다. 세션 생성 시 인증 제공하기를 참조하세요. 세션 업데이트로 mcp_servers가 변경될 때도 동일한 검사가 실행됩니다.

allowed_hosts에 사용할 호스트를 선택할 때는 다음 두 가지 규칙을 따르세요.

• 운영하거나 신뢰하는 호스트만 나열하세요.
• *. 와일드카드와 누구나 콘텐츠를 게시할 수 있는 공유 호스팅 도메인은 피하세요.

에이전트가 bash를 유지하는 경우, 위험한 작업 승인하기에서 설명하는 대로 bash 도구의 권한 정책을 설정하세요.

모든 네트워킹 설정은 클라우드 환경 설정을 참조하세요.

자격 증명을 볼트에 보관하기

모든 시크릿을 볼트에 저장하세요. 각 환경 변수 자격 증명에 대해 주입 위치를 요청 헤더로만 설정하고, 해당 시크릿이 사용될 호스트만 나열하세요. 샌드박스의 코드는 시크릿 대신 플레이스홀더를 보게 됩니다. Managed Agents는 자격 증명이 허용하는 호스트로 나가는 HTTPS 요청에서만 실제 시크릿으로 교체합니다. 따라서 요청 헤더를 그대로 반환하는 엔드포인트처럼 서비스가 시크릿을 되돌려 보내지 않는 한, 시크릿은 모델이 직접 접근할 수 없는 곳에 유지됩니다. 자격 증명의 networking이 unrestricted인 경우, Managed Agents는 환경이 샌드박스에 접근을 허용하는 모든 호스트로의 요청에서 실제 시크릿으로 교체합니다. 볼트를 사용하려면 세션이나 배포를 생성할 때 vault_ids에 해당 ID를 전달하세요.

지원 에이전트는 애플리케이션이 주문 API의 API 키를 보유하므로 볼트 자격 증명이 필요하지 않습니다. 에이전트가 볼트 자격 증명을 보유하는 경우, 모든 언어로 된 요청은 자격 증명 추가하기를 참조하세요.

키를 시스템 프롬프트, 에이전트 정의, 메시지에 넣지 마세요. 에이전트에 Claude API 키를 제공하지 마세요. Claude API 키가 볼트에 있더라도 샌드박스의 코드는 이를 사용하여 Claude API를 직접 호출할 수 있습니다. 세션 시작이나 삭제, 웹 검색 및 웹 가져오기 사용 등 해당 키가 허용하는 모든 작업을 수행할 수 있습니다. 에이전트의 도구 설정, 승인, 예산은 이러한 호출에 적용되지 않습니다. limited 환경에서는 allowed_hosts가 샌드박스의 api.anthropic.com 접근을 허용하는 경우에만 코드가 이러한 호출을 할 수 있습니다.

토큰은 직접 가져와서 볼트에 저장하세요. 샌드박스의 코드가 저장된 시크릿으로 가져온 토큰은 가려지지 않은 상태로 반환되기 때문입니다.

워크스페이스에 접근할 수 있는 모든 API 키는 해당 워크스페이스의 볼트를 참조할 수 있으므로, 신뢰 수준이 다른 워크로드의 볼트는 별도의 워크스페이스에 보관하세요. 하나의 워크스페이스로 범위가 지정된 API 키를 사용하세요.

MCP 자격 증명 및 교체에 대해서는 볼트로 인증하기를 참조하세요.

웹 검색 및 웹 가져오기 제한하기

web_fetch의 allowed_domains를 에이전트에 필요한 사이트로 설정하세요. 에이전트가 가져오는 모든 URL은 해당 URL이 가리키는 사이트로 데이터를 전달할 수 있으므로, 이 목록은 보안 통제 수단입니다. web_search에서는 allowed_domains를 결과를 받고자 하는 사이트로 설정하여, 정확하다고 신뢰하는 사이트에서만 결과가 나오도록 하세요. 이 목록은 검색 쿼리가 검색 제공자에게 전달되는 것을 막지 않습니다. 검색 결과에는 페이지의 텍스트가 포함되므로, 이 목록은 어떤 사이트의 텍스트가 에이전트에 도달하는지도 제한합니다. 모든 유형의 환경에서 두 도구 모두에 allowed_domains를 설정하세요.

blocked_domains 목록은 나열한 호스트와 그 하위 도메인만 차단하며, 다른 호스트는 차단하지 않습니다. 동일한 콘텐츠가 웹 아카이브, 캐시, 미러 또는 나열하지 않은 관련 도메인을 통해 여전히 에이전트에 도달할 수 있습니다. 보안을 위해 blocked_domains에 의존하지 마세요. allowed_domains를 사용하고 신뢰하는 호스트를 명시하세요.

limited 환경에서는 네트워크 제한하기의 allowed_hosts 목록도 웹 도구를 제한합니다. unrestricted 환경이나 자체 호스팅 샌드박스는 웹 도구를 제한하지 않습니다.

두 목록은 호스트를 서로 다르게 매칭합니다.

에이전트에 사이트와 그 모든 하위 도메인이 필요한 경우 allowed_hosts에 example.com과 *.example.com을 모두 나열하고, 그렇지 않으면 정확한 호스트를 나열하세요. 도구가 example.com을 나열하고 allowed_hosts가 *.example.com만 나열하는 경우 세션은 생성됩니다. 세션 생성 시 검사는 example.com을 *.example.com에 포함된 것으로 간주하지만, 도구는 example.com 자체에서는 아무것도 반환하지 않습니다. 두 목록의 매칭 방식은 에이전트에 도메인 목록 설정을 참조하세요.

web_fetch 도구는 또한 세션에 이미 나타난 URL만 엽니다.

멀티에이전트 세션에서 web_fetch는 다른 에이전트로부터 받은 URL이 "예"로 표시된 출처를 통해 해당 에이전트에 도달한 경우에만 엽니다. 직접 호출한 커스텀 도구의 결과는 "예"로 표시된 출처로 간주됩니다. 이는 도구가 입력을 그대로 반복하는 경우처럼 Claude가 그 텍스트를 작성한 경우에도 마찬가지입니다. URL은 example.com/docs처럼 https:// 없이 작성된 경우에도 인정될 수 있습니다. web_fetch 도구는 "Contact support."처럼 URL 대신 단어를 표시하는 링크를 항상 열 수 있는 것은 아닙니다. 에이전트가 세션에 나타나지 않은 URL을 가져와야 하는 경우, 사용자 메시지로 보내세요.

이 규칙은 주입된 텍스트가 비공개 데이터를 전달하는 URL을 구성할 가능성을 줄여 줍니다. 최종 사용자 텍스트, 검색 결과, 가져온 페이지, 커스텀 도구 결과는 여전히 URL을 추가할 수 있으므로 allowed_domains를 계속 설정해 두세요. Messages API는 다른 출처 목록으로 유사한 규칙을 적용합니다. URL 검증을 참조하세요.

web_fetch의 도메인 목록은 bash 도구를 제한하지 않습니다. 네트워크도 제한하세요. 도메인 목록 규칙을 참조하세요.

위험한 작업 승인하기

bash, write, edit, web_fetch 및 데이터를 읽기만 하는 MCP 도구에는 auto를 설정하세요. 샌드박스 외부에 가한 변경 사항을 되돌릴 수 없는 도구에는 대신 always_ask를 사용하세요. 전달하는 최종 사용자 텍스트가 요청한다는 이유만으로 실행되어서는 안 되는 도구에도 이를 사용하세요. 권한 정책은 도구 호출이 실행될지, 승인을 기다릴지, 서버가 평가할지를 결정합니다.

에이전트에 최소한의 도구 세트 제공하기의 도구 세트가 이러한 정책을 적용합니다.

auto 정책은 서버가 호출을 실행하거나, 거부하거나, 승인을 위해 일시 중지하도록 합니다. 긴 실행에서 사람이 모든 호출을 승인할 수는 없으므로, 대신 서버가 각 호출을 검사합니다. auto는 제한된 네트워킹, 좁은 권한을 가진 키, 예산, 유휴 세션에 대한 알림과 함께 사용하세요. auto는 사람의 검토 지점이 아니므로, 도구의 호출이 실행되기 전에 사람이 검토해야 한다면 해당 도구에 always_ask를 구성하세요.

auto는 user.message 이벤트의 텍스트와 user.define_outcome 이벤트의 설명을, 전달하는 최종 사용자 텍스트를 포함하여 사용자의 지시로 취급합니다.

일시 중지된 세션은 무기한 대기하므로, 무인 세션에는 일시 중지된 호출에 응답하거나 세션을 중단하는 클라이언트가 필요합니다.

일시 중지된 각 호출을 허용하기 전에 검토하세요. 사람에게 보여 주지 않고 모든 호출을 허용하는 클라이언트는 always_allow와 같습니다. 확인 요청에 응답하기 및 각 호출이 어떻게 평가되었는지 확인하기를 참조하세요.

에이전트에 최소한의 도구 세트 제공하기

default_config.enabled를 false로 설정하고 에이전트에 필요한 도구만 활성화하세요. 에이전트 도구 세트는 기본적으로 8개의 내장 도구를 모두 활성화합니다.

지원 에이전트에는 세 가지 내장 도구가 필요합니다. 초안 작성을 위한 read와 write, 그리고 헬프 센터를 위한 web_fetch입니다. 주문 조회는 애플리케이션이 실행하는 커스텀 도구인 lookup_order를 통해 수행합니다. 애플리케이션이 주문 API의 API 키를 보유하므로, 에이전트에는 bash도 자격 증명도 필요하지 않습니다.

다음 샘플은 allowed_domains로 web_fetch를 help.example.com으로 제한합니다. 위험한 작업 승인하기에서 권장하는 대로 write와 web_fetch에 auto를 설정합니다. 고객의 티켓으로 인해 에이전트가 이러한 도구를 사용하더라도, 에이전트는 샌드박스의 파일을 변경하거나 헬프 센터 페이지를 여는 것만 할 수 있습니다. 그래서 두 도구 모두 always_ask가 필요하지 않습니다. 샘플은 또한 default_config에 always_ask를 설정하므로, 나중에 자체 정책 없이 활성화하는 도구는 always_ask를 사용합니다.

ant apply agent.md

---
name: Support Agent
model: claude-opus-5-5
tools:
  - type: agent_toolset_20260401
    default_config:
      enabled: false
      permission_policy:
        type: always_ask
    configs:
      - name: read
        enabled: true
        permission_policy:
          type: always_allow
      - name: write
        enabled: true
        permission_policy:
          type: auto
      - name: web_fetch
        enabled: true
        allowed_domains: [help.example.com]
        permission_policy:
          type: auto
  - type: custom
    name: lookup_order
    description: Look up one order by its ID. Returns the status, the items, and the delivery date.
    input_schema:
      type: object
      properties:
        order_id:
          type: string
          description: The order ID from the ticket
      required:
        - order_id
---

에이전트 업데이트는 tools 배열 전체를 교체하므로, 유지하려는 모든 항목을 보내세요.

에이전트 업데이트는 새 세션에만 적용되므로, 배포, 이 에이전트를 나열하는 에이전트, 기존 세션도 확인하세요.

• 배포는 에이전트 버전을 고정하므로, 각 배포가 새 버전을 가리키도록 하세요.
• subagents.predefined_agents 또는 workflows.predefined_agents에 이 에이전트를 나열하는 에이전트는 고정한 버전을 유지하므로, 해당 에이전트도 업데이트하세요.
• 이미 존재하는 세션을 강화하려면 해당 세션의 도구를 업데이트하세요. 세션은 idle 상태여야 하며, 업데이트는 tools 배열 전체를 교체합니다. 멀티에이전트 세션에서는 세션이 실행하는 에이전트의 웹 도구에 대한 새 allowed_domains 및 blocked_domains 목록이 다른 모든 에이전트에도 적용됩니다. 이는 각 에이전트의 다음 턴부터 적용됩니다. 해당 에이전트들의 활성화된 도구와 권한 정책은 변경되지 않습니다. 이를 변경하려면 각 에이전트를 업데이트한 다음 새 세션을 시작하세요.

MCP 서버와 커스텀 도구도 에이전트에 필요한 것으로 제한하세요.

• MCP 서버: MCP 도구 세트는 기본적으로 서버가 노출하는 모든 도구를 활성화합니다. default_config.enabled를 false로 설정하고 이름을 지정한 도구를 활성화하여, 서버가 나중에 추가하는 도구가 꺼진 상태로 유지되도록 하세요. 에이전트가 사용하지 않는 서버는 제거하세요. MCP 커넥터를 참조하세요.
• 커스텀 도구: 애플리케이션이 실행하며, 권한 정책이 적용되지 않습니다. 애플리케이션에서 각 호출의 입력을 검증하고 도구가 접근할 수 있는 범위를 제한하세요.

신뢰할 수 없는 입력을 강력한 도구로부터 분리하기

에이전트가 신뢰할 수 없는 입력, 즉 팀 외부의 누군가가 작성할 수 있는 텍스트를 읽을 때마다 에이전트가 보유한 도구와 자격 증명을 확인하세요. 이 섹션에서는 두 가지 용어를 사용합니다.

• 신뢰할 수 없는 입력: 웹 페이지, 검색 결과, 지원 티켓, 이메일, 리포지토리 파일, 업로드, MCP 서버 결과, 전달하는 최종 사용자 메시지.
• 강력한 도구: bash, write, edit, web_fetch, web_search, 데이터를 쓰거나 전송하는 MCP 도구 및 커스텀 도구, 그리고 자격 증명을 사용하는 모든 도구.

신뢰할 수 없는 입력의 텍스트는 에이전트에게 보유한 강력한 도구를 사용하도록 지시할 수 있습니다. 지원 에이전트는 티켓을 읽으므로, 커스텀 도구 lookup_order를 통해서만 주문 API에 접근합니다. 애플리케이션은 주문이 티켓 발신자의 것인지 확인합니다.

클라우드 환경에서는 read로 파일을 읽을 때 CLAUDE.md 및 AGENTS.md 파일도 지침으로 로드될 수 있습니다. 이 파일들은 해당 파일의 디렉터리와 그 상위 디렉터리에서 샌드박스의 작업 디렉터리까지 로드됩니다. @docs/setup.md처럼 @와 경로로 참조하는 파일도 최대 5단계 깊이까지 로드됩니다. 참조는 @/etc/hosts처럼 샌드박스의 어느 곳이든 가리킬 수 있습니다. read를 비활성화하는 것 외에는 이를 끄는 설정이 없으므로, 팀 외부의 누군가가 작성할 수 있는 리포지토리, 패키지 또는 아카이브는 신뢰할 수 없는 입력으로 취급하세요.

에이전트가 신뢰할 수 없는 입력을 읽으면서 동시에 작업도 수행해야 하는 경우, 이 가이드는 세 가지 설계 중 하나를 권장합니다.

• 읽기와 작업 수행을 분리하세요. 하나의 멀티에이전트 세션에서 리드 에이전트가 웹을 읽는 페처(fetcher)와 파일이나 레코드를 변경하는 라이터(writer)에게 작업을 할당합니다.
• 에이전트에 좁은 범위의 커스텀 도구 하나를 제공하세요. 애플리케이션이 도구를 실행하고, 입력을 검사하며, 자격 증명을 보유합니다. 지원 에이전트는 분리 방식이 아닌 이 설계를 사용합니다. 세션을 일시 중지시키는 도구 호출에 응답하기를 참조하세요.
• 사람이 개입하도록 하세요. 강력한 도구에 always_ask를 사용하여 사람이 각 호출을 승인하도록 하세요.

분리 방식은 세 개의 에이전트를 사용합니다.

페처의 결과는 신뢰할 수 없는 페이지로부터 구성되며, 리드는 그 텍스트를 라이터에게 전달할 수 있습니다. 라이터의 도구는 auto 또는 always_ask로 유지하세요. 페처는 여전히 읽은 내용의 일부를 web_fetch 목록에 있는 사이트로, 그리고 쿼리를 통해 검색 제공자에게 보낼 수 있습니다.

하나의 멀티에이전트 세션에 있는 에이전트들은 샌드박스, 그 파일, 볼트 자격 증명을 공유하므로, 이 분리는 도구와 대화만 분리합니다. 더 강력한 분리를 위해서는 별도의 환경과 볼트를 가진 두 개의 세션을 사용하세요. 애플리케이션이 두 세션 간에 주문 ID와 같은 고정된 필드만 전달하도록 하세요.

한도와 중지 방법 설정하기

각 세션을 생성할 때 예산을 설정하고, 에이전트를 중지하는 방법을 미리 정해 두세요.

실행 중인 에이전트를 중지하려면 다음 단계를 따르세요.

1. user.interrupt만 단독으로 보내세요.
2. 예약된 에이전트의 경우, 새로운 예약 실행이 시작되지 않도록 배포도 일시 중지하세요. 일정을 영구적으로 종료하려면 배포를 보관하세요.
3. 키가 노출되었을 가능성이 있다면, 키를 발급한 서비스에서 교체하세요.
4. 에이전트에 열려 있는 워크플로 실행이 있다면, 중단은 실행을 종료하지 않으므로 실행을 중지하도록 요청하는 user.message도 보내세요. 먼저 취소해야 할 도구 호출은 실행이 열려 있는 세션 중단하기를 참조하세요.
5. 세션이 idle 상태가 될 때까지 기다리세요. 실행 중인 세션은 보관하거나 삭제할 수 없습니다.
6. 기록을 유지하려면 세션을 보관하세요. 기록이 더 이상 필요하지 않으면 삭제하세요.

중단은 에이전트가 이미 수행했거나 보낸 것을 되돌리지 않습니다. 에이전트를 보관해도 실행 중인 세션은 중지되지 않습니다.

예산의 max_list_cost.amount는 문자열로 작성된 미국 센트 단위의 정수이므로, "125"는 $1.25를 의미합니다. 세션 생성 시 예산 설정을 참조하세요.

예산 없이 생성된 세션에는 예산을 추가할 수 없습니다. 상한을 변경하거나 제거하려면 예산에 도달한 세션 재개를 참조하세요. 세션의 상한을 제거한 후에는 새 상한을 설정할 수 없습니다.

예산은 지출을 제한하지만, 상한에 도달하기 전에 에이전트가 수행하는 작업은 제한하지 않습니다. 신뢰 수준이 다른 워크로드를 분리하려면 별도의 워크스페이스를 사용하세요. 여러 워크스페이스에 접근할 수 있는 키는 그중 어느 곳에서든 작업할 수 있으므로, 각 워크로드에 하나의 워크스페이스로 범위가 지정된 API 키를 제공하세요.

세션 예산, 세션 작업, 예약된 배포를 참조하세요.

다음 단계