Auth Proxy가 LangSmith 에이전트 샌드박스(agent sandboxes)의 네트워크 액세스를 보호하는 방법

핵심 요약 (Key Takeaways)

에이전트(Agent)는 코드를 실행하고, 패키지를 설치하며, API를 호출하고, 신뢰할 수 없는 콘텐츠의 지시를 따를 수 있기 때문에 에이전트 샌드박스(Agent sandboxes)에는 더 강력한 네트워크 제어가 필요합니다.
LangSmith Auth Proxy는 네트워크 계층(network layer)에서 인증 헤더(auth headers)를 주입함으로써 자격 증명(credentials)을 샌드박스 외부에 유지하며, 이를 통해 프롬프트 주입(prompt injection), 로그, 파일 및 악성 종속성(malicious dependencies)으로부터의 노출을 줄입니다.
팀은 송신 정책(egress policies)과 동적 자격 증명 흐름(dynamic credential flows)을 정의하여, 에이전트가 장기 생존 비밀값(long-lived secrets)에 직접 접근하지 않고도 승인된 서비스, 패키지 레지스트리(package registries) 및 사용자 범위 API(user-scoped APIs)에 도달할 수 있도록 할 수 있습니다.

대기업에서 근무해 본 적이 있다면, 표준적인 기업용 노트북 설정을 본 적이 있을 것입니다.

엔드포인트 보호(endpoint protection), 브라우저 필터링(browser filtering), 장치 관리(device management), 네트워크 제어(network controls), 인증서 저장소(certificate stores), 비밀값 스캐너(secret scanners) 등... 신뢰할 수 있는 직원이 실수로 자격 증명을 유출하거나, 악성 패키지를 설치하거나, 잘못된 페이지를 방문하는 것을 방지하는 역할을 하는 도구들의 긴 목록이 존재합니다.

이러한 툴링(tooling)이 존재하는 이유는 개발자들에게 광범위한 권한이 부여되기 때문입니다. 그들은 코드를 실행하고, 종속성(dependencies)을 설치하며, 시스템 간에 데이터를 복사합니다. 또한 내부 및 외부 서비스에 인증합니다. 많은 기업 보안은 이러한 강력하고 개방적인 환경을 더 안전하게 만드는 것을 중심으로 구축되어 있습니다.

에이전트는 이 문제의 규모와 형태를 변화시킵니다. 단순히 한 명의 개발자에게 노트북을 주는 것이 아닙니다. 여러분은 코드를 작성하고, 명령을 실행하며, 패키지를 설치하고, 여러분을 대신하여 네트워크 요청을 보낼 수 있는 수천 명, 혹은 궁극적으로 수백만 명의 "신뢰할 수 없는 개발자(untrusted developers)"를 생성하게 될 수도 있습니다.

인간 개발자의 경우, 환경은 기본적으로 개방되어 있어야 하는 경우가 많습니다. 개발자는 업무가 변경됨에 따라 탐색하고, 디버깅하고, 도구를 설치하며, 새로운 서비스에 접근해야 합니다. 하지만 에이전트의 경우, 기본 설정이 다를 수 있습니다. 작업 내용이 알려져 있다면 네트워크 범위는 더 좁아질 수 있습니다. 만약 에이전트가 GitHub와 LLM 제공업체만 필요로 한다면, 인터넷상의 모든 무작위 호스트와 통신할 수 있어서는 안 됩니다. 만약 에이전트에게 자격 증명이 필요하다면, 그 자격 증명은 런타임(runtime) 내부에 아예 존재할 필요가 없어야 합니다.

이 지점에서 샌드박스 네트워킹 (sandbox networking)은 에이전트 하네스 (agent harness)의 핵심적인 부분 (first-class part)이 됩니다.

샌드박스 Auth Proxy 소개

LangSmith Sandboxes는 메인 인프라에 영향을 주지 않으면서 코드를 실행하고 파일 시스템 (filesystems)과 상호작용할 수 있도록 에이전트에게 격리된 환경을 제공합니다. 하지만 격리는 이야기의 일부분일 뿐입니다. 에이전트는 여전히 모델 제공자 (model providers), GitHub, 패키지 레지스트리 (package registries), 내부 서비스 (internal services), 데이터 API (data APIs) 등과 같은 외부 API를 호출해야 합니다.

샌드박스 인증 프록시 (sandbox auth proxy)은 에이전트가 생성한 동작과 나머지 세상 사이의 경계를 제어하는 방법입니다.

API 키를 환경 변수 (environment variables)나 파일 형태로 샌드박스에 직접 넣는 대신, 프록시는 아웃바운드 네트워크 경로 (outbound network path)에 위치하여 샌드박스화된 코드가 외부 서비스와 상호작용하는 방식을 제어합니다. 프록시는 어떤 목적지가 허용되는지, 어떤 인증 (authentication)이 적용되는지, 그리고 요청이 샌드박스를 떠나기 전에 어떻게 구성되어야 하는지에 대한 정책을 강제할 수 있습니다. 샌드박스 코드는 외부 API에 일반적인 요청을 보내지만, 자격 증명 (credentials)과 액세스 규칙은 샌드박스 외부의 네트워크 계층 (network layer)에서 처리됩니다.

이 모델을 통해 다음 세 가지가 훨씬 쉬워집니다:

자격 증명이 런타임 (runtime) 외부에 유지됩니다. 에이전트는 API 키를 읽을 수 없는 상태에서도 API를 사용할 수 있으며, 이는 프롬프트 인젝션 (prompt injection), 악성 의존성 (malicious dependencies), 실수로 인한 로깅 (accidental logging), 그리고 모델의 실수로 인한 피해를 줄여줍니다.
네트워크 액세스 (network access)가 명시적으로 변합니다. 만약 에이전트가 OpenAI, Anthropic, GitHub 또는 내부 API하고만 통신해야 한다면, 이는 에이전트의 판단에 맡기는 것이 아니라 인프라 정책 (infrastructure policy)으로 인코딩되어야 합니다.
팀은 더 깔끔한 관심사 분리 (separation of concerns)를 얻을 수 있습니다: 에이전트는 작업에 집중하고, 샌드박스는 격리를 제공하며, 프록시는 네트워크 권한 부여 (network authorization) 및 자격 증명 주입 (credential injection)을 처리하고, 애플리케이션 또는 인증 서비스 (auth service)는 사용자 범위의 액세스 (user-scoped access) 및 토큰 갱신 (token refresh)을 처리합니다.

이러한 분리는 에이전트(agents)가 신뢰할 수 없는 존재이며, 그들이 취할 모든 경로를 사전에 검토할 수 없기 때문에 중요합니다. 더 안전한 패턴은 인프라에 의해 가능한 동작이 제한되는 제약된 환경(constrained environments)을 제공하는 것이며, 이를 통해 인증 프록시(auth proxy)가 샌드박스(sandbox)로부터 자격 증명(credentials)을 완전히 격리하도록 유지합니다.

작동 방식

개괄적으로 살펴보면, 인증 프록시는 샌드박스의 외부 유출(egress)을 제어하는 중개자 역할을 하며, 그 과정은 다음과 같습니다:

에이전트 또는 샌드박스화된 코드(sandboxed code)가 외부 요청을 보냅니다.
요청이 인증 프록시(Auth Proxy)를 통과합니다.
인증 프록시는 해당 목적지에 대해 설정된 정책(policy)을 확인합니다.
프록시는 요청을 차단하거나, 허용하거나, 헤더(headers)를 부착할 수 있습니다.
요청은 런타임(runtime)에 자격 증명을 노출하지 않고 목적지로 계속 진행됩니다.

간단한 규칙의 예로, 샌드박스가 api.openai.com을 호출할 때 LangSmith 워크스페이스 비밀(workspace secret)에서 가져온 값을 가진 Authorization 헤더를 주입하도록 설정할 수 있습니다. 또 다른 규칙으로는 샌드박스가 /repos/* 또는 /user 경로에 대해 api.github.com을 호출할 때 GitHub 토큰을 주입하도록 설정할 수 있습니다.

우리가 샌드박스의 네트워크를 제어하기 때문에, 이 과정은 완전히 투명하게 이루어집니다. 이는 모든 언어, 패키지 관리자(package manager), SDK 또는 서브프로세스(subprocess)가 HTTP_PROXY를 준수하기를 기대하며 구현된 것이 아닙니다. 모든 런타임이 동일하게 동작하는 것은 아니며, 에이전트는 종종 사용자가 작성하지 않은 임의의 코드 경로(arbitrary code paths)를 실행하기 때문입니다.

에이전트에게 자격 증명을 넘겨주지 않고 인증하기

프록시는 다양한 정책 구성(policy configurations)을 지원합니다. 강력한 기능 중 하나는 특정 특성과 일치하는 요청에 헤더를 주입할 수 있는 능력입니다.

헤더는 다음과 같은 다양한 유형으로 구성할 수 있습니다:

workspace_secret: LangSmith 워크스페이스 설정에 저장된 비밀(secret)을 참조합니다.
plaintext: 민감하지 않은 헤더를 위해 있는 그대로 저장되고 반환됩니다.
opaque: 쓰기 전용이며, 저장 시 암호화되고, API에 의해 절대 반환되지 않습니다.

예를 들어, OpenAI 규칙의 경우 다음과 같이 주입할 수 있습니다:

{
"name": "Authorization",
"type": "workspace_secret",
...

샌드박스 코드는 API 키를 알 필요가 없습니다. .env 파일도 필요하지 않습니다. 파일 시스템에 시크릿 (secret)을 마운트할 필요도 없습니다. 그저 API를 호출하기만 하면 되며, 목적지가 설정된 규칙과 일치할 때 프록시 (proxy)가 적절한 헤더 (header)를 추가합니다.

이는 에이전트 시스템을 위한 더 나은 기본 설정입니다. 인간 개발자는 새로운 통합 (integration)을 디버깅하기 위해 자격 증명 (credential)에 직접 접근해야 할 수도 있지만, 에이전트는 대개 그렇지 않습니다. 에이전트에게 필요한 것은 자격 증명 그 자체가 아니라, 자격 증명의 효과 — 즉, 특정 API를 호출할 수 있는 능력입니다.

에이전트 실행 횟수가 늘어날수록 이러한 차이는 더욱 중요해집니다. 단일 샌드박스에서 키가 유출되는 것도 문제지만, 수많은 샌드박스 군단(fleet)을 운영할 때 런타임 (runtime)에 직접 자격 증명을 넣는 것은 상당한 위험 요소입니다. 모든 도구 호출 (tool call), 패키지 설치 (package install), 로그 라인 (log line), 파일 쓰기 (file write)가 잠재적인 자격 증명 노출 경로가 될 수 있습니다. 헤더 주입 (Header injection)은 자격 증명을 이러한 폭발 반경 (blast radius) 밖으로 이동시킵니다.

네트워크 잠금 (Locking down the network)

자격 증명은 네트워크 문제의 절반에 불과합니다. 에이전트는 의존성 (dependencies)을 설치하고, 스크립트를 가져오며, API를 호출하고, 신뢰할 수 없는 콘텐츠의 지시를 따를 수 있기 때문에 송신 정책 (egress policy) 또한 필요합니다. 만약 모든 샌드박스가 인터넷에 개방되어 있다면, 침해되었거나 혼란에 빠진 에이전트가 가서는 안 될 곳에 도달할 수 있습니다.

헤더를 주입하는 것과 동일한 프록시 경계는 팀이 다음과 같이 예상되는 목적지를 정의하는 장소가 될 수도 있습니다:

모델 제공업체 API만 허용하고 나머지는 모두 차단
에이전트가 필요한 GitHub API 경로만 허용하되, 임의의 GitHub 관련 도메인은 차단
패키지 레지스트리 (package registry)를 허용하되, 내부 미러 (internal mirror)만 허용
알려진 악성 또는 신뢰할 수 없는 패키지 레지스트리 차단
승인되지 않은 제3자 서비스로의 실수적인 호출 방지

이는 특히 패키지 관리 (package management)에서 중요합니다. 만약 코딩 에이전트가 pip install, npm install 또는 curl | bash를 실행할 수 있다면

, 코드를 가져와 실행할 수 있습니다. 여기서 보안 문제는 단순히 샌드박스(sandbox)가 실행을 격리할 수 있는지 여부뿐만 아니라, 해당 코드가 어디에서 오는지, 그리고 데이터를 어디로 보낼 수 있는지를 제어할 수 있는지에 관한 것입니다.

실제 운영 환경의 인증을 위한 동적 자격 증명 (Dynamic credentials)

샌드박스를 LangSmith Fleet과 통합하는 과정에서, 고급 사용 사례(advanced use cases)의 경우 정적 설정(static configuration)만으로는 충분하지 않을 수 있다는 점을 깨달았습니다. Fleet 에이전트는 실제 자격 증명(credential) 처리를 에이전트 런타임(runtime) 외부에서 유지하면서도, 위임된 액세스(delegated access) 및 OAuth 토큰 갱신(refresh)이 필요할 수 있습니다.

고급 사용 사례의 다른 예로는 다음과 같은 것들이 있습니다:

수명이 짧은 OAuth 액세스 토큰 (short-lived OAuth access tokens)
사용자별 범위가 지정된 토큰 (per-user-scoped tokens)
내부 인증 서비스에서 발행한 자격 증명 (credentials minted by an internal auth service)
목적지 또는 현재 사용자 컨텍스트에 따라 갱신이 필요한 토큰

이러한 경우를 위해, 인증 프록시(auth proxy)는 콜백(callback)을 통한 동적 자격 증명을 지원합니다.

모든 자격 증명 정보를 정적 규칙(static rules)에 넣는 대신, proxy_config 아래에 콜백을 구성합니다. 샌드박스가 일치하는 호스트로 요청을 보낼 때 프록시에 캐시된 자격 증명이 없다면, 프록시는 대상 호스트와 포트를 포함하여 사용자의 콜백 엔드포인트(endpoint)를 호출합니다. 사용자의 엔드포인트는 주입할 헤더(headers)를 반환하며, 프록시는 설정된 TTL(Time To Live) 동안 그 결과를 캐시합니다.

규약(contract)은 간단합니다. 콜백은 다음과 같은 JSON 객체를 반환합니다:

{
"headers": {
"Authorization": "Bearer <token>",
...

프록시는 해당 헤더를 아웃바운드 요청(outbound request)에 주입합니다. 만약 콜백이 실패하거나, 잘못된 형식의 JSON을 반환하거나, 2xx가 아닌 상태 코드로 응답하는 경우, 프록시는 자격 증명 없이 요청을 보내는 대신 'fail closed' 방식으로 동작하여 샌드박스 요청을 거부합니다. 이것이 바로 샌드박스에 리프레시 토큰(refresh tokens)이나 장기 유지 자격 증명(long-lived credentials)을 노출하지 않으면서, 샌드박스 네트워크 계층이 인증 흐름(auth flows)에 참여할 수 있게 하는 패턴입니다.

이를 통해 다음에 가능해지는 것들

샌드박스 네트워크 경로를 제어할 수 있게 되면, 프록시는 단순한 자격 증명 주입기(credential injector) 이상의 역할을 할 수 있으며, 몇 가지 자연스러운 확장 기능들이 존재합니다.

DNS 리매핑 (DNS remapping): 팀은 퍼블릭 패키지 레지스트리 (public package registries)로 향하는 요청이 대신 내부 Artifactory나 패키지 미러 (package mirror)로 해석되기를 원할 수 있습니다. 또한 LLM API 요청을 내부 게이트웨이 (internal gateway)로 향하게 하고 싶을 수도 있습니다. 에이전트 (agent)는 여전히 일반적인 설치 명령어를 실행하지만, 네트워크 계층 (network layer)이 해당 요청을 승인된 인프라로 안내합니다.
네트워크 로깅 (Network logging): 에이전트가 긴 시간 범위 (long horizons)에 걸쳐 의미 있는 작업을 수행하는 경우, 팀은 에이전트가 어떤 서비스를 호출했는지, 어떤 패키지를 가져왔는지, 그리고 어떤 도메인에 접속을 시도했는지 알고 싶어 할 것입니다. 네트워크 로그는 에이전트 행동에 대한 감사 추적 (audit trail)의 일부가 됩니다.
요청 변환 (Request transformation): 프록시 (proxy)는 아웃바운드 요청 (outbound requests)을 확인하므로, 개인정보 (PII) 삭제, 조직 메타데이터 (organization metadata) 추가, 요청 형태 (request shape) 강제, 또는 정책을 위반하는 페이로드 (payloads) 차단과 같은 결정론적 변환 (deterministic transformations)을 적용하는 장소가 될 수 있습니다.

더 넓은 관점에서의 핵심은, 에이전트 인프라 (agent infrastructure)에는 런타임 (runtime) 외부에 존재하며 에이전트의 지시나 결정에 노출되지 않는 제어 평면 (control planes)이 필요하다는 점입니다.

에이전트 이그레스 (agent egress)의 새로운 기본값

에이전트가 유용한 작업을 수행하려면 자격 증명 (credentials)과 네트워크 액세스 (network access)가 필요하지만, 이러한 기능이 런타임 내부에 장기 생존 비밀값 (long-lived secrets)을 두거나 제한 없는 인터넷 액세스를 허용하는 것을 요구해서는 안 됩니다. Auth Proxy는 자격 증명을 환경 외부에 유지하고, 아웃바운드 트래픽을 제어된 계층을 통해 라우팅하며, 언어, SDK, 패키지 매니저 (package managers), 그리고 CLI 전반에 걸쳐 정책을 일관되게 적용함으로써 샌드박스된 에이전트 (sandboxed agents)에게 더 안전한 기본값을 제공합니다.

그 결과, 플랫폼의 제어 하에 자격 증명과 네트워크 정책을 유지하면서도, 에이전트에게 필요한 시스템에 대한 액세스를 제공하는 샌드박스 모델이 완성됩니다.

LangSmith Sandboxes 체험하기: https://www.langchain.com/langsmith/sandboxes

문서 읽기: https://docs.langchain.com/langsmith/sandboxes