OneCLI: AI 에이전트를 위한 안전한 오픈소스 인증 정보 저장소(Credential Vault) 및 게이트웨이

읽을거리&정보공유
, ,
1

OneCLI: AI 에이전트를 위한 안전한 오픈소스 인증 정보 저장소(Credential Vault) 및 프록시
OneCLI: AI 에이전트를 위한 안전한 오픈소스 인증 정보 저장소(Credential Vault) 및 프록시1168×614 73.4 KB

OneCLI 소개

OneCLI는 AI 에이전트가 실제 API 키를 직접 취급하지 않고도 외부 서비스에 접근할 수 있도록 돕는 오픈소스 인증 정보 저장소(Credential Vault)이자 HTTP 게이트웨이입니다. 개발자는 실제 인증 정보(API 키, 토큰 등)를 OneCLI의 암호화된 볼트에 안전하게 저장하고, AI 에이전트에게는 가짜 키(Placeholder)만 제공하게 됩니다. 에이전트가 이 가짜 키를 사용하여 HTTP 요청을 보내면, 중간에 위치한 OneCLI 프록시가 이를 가로채어 실제 키로 교체해 줍니다.

결과적으로 AI 에이전트는 자신이 어떤 실제 비밀키를 사용하고 있는지 전혀 알지 못하는 상태로 정상적인 API 호출을 수행할 수 있습니다. 이러한 구조는 에이전트의 코드나 메모리 상에 민감한 정보가 노출되는 것을 원천적으로 차단하는 훌륭한 접근 방식입니다.

최근 자율형 AI 에이전트가 발전하면서 GitHub, Twitter, 클라우드 서비스 등 다양한 외부 API를 호출하여 작업을 수행하는 사례가 급증하고 있습니다. 하지만 에이전트에게 실제 API 키를 직접 쥐어주는 것은 프롬프트 인젝션(Prompt Injection) 공격이나 로깅 실수로 인해 치명적인 보안 사고로 이어질 수 있는 큰 위험을 내포하고 있습니다. 기존에는 환경 변수를 사용하거나 전통적인 비밀값 관리 도구를 사용했지만, 결국 에이전트의 메모리에 키가 직접 로드되어야 한다는 근본적인 한계가 있었습니다.

onecli-flow-light

OneCLI는 네트워크 계층에서 프록시를 통해 인증 정보를 투명하게 주입하는 방식으로 이 문제를 우회하여 보안을 극대화합니다. 이로써 기업과 개발자는 보안 침해에 대한 걱정 없이 AI 에이전트에게 더 많은 권한과 유연성을 안전하게 부여할 수 있게 되었습니다.

또한, OneCLI는 프록시 기반으로 동작하기 때문에 특정 프레임워크나 개발 언어에 종속되지 않는다는 강력한 장점이 있습니다. OpenClaw, NanoClaw, IronClaw를 비롯하여 HTTPS_PROXY 환경 변수를 설정할 수 있는 모든 에이전트 프레임워크 및 도구와 완벽하게 호환됩니다.

무엇보다 단일 도커(Docker) 컨테이너 내에서 모든 구성 요소가 실행되므로 복잡한 외부 데이터베이스 세팅이나 의존성 없이 로컬 환경이나 서버에 쉽게 배포할 수 있습니다. 개발팀은 함께 제공되는 웹 대시보드를 통해 에이전트별 접근 권한을 세밀하게 제어하고, 호스트 및 경로(Path) 기반의 라우팅 정책을 직관적으로 관리할 수 있습니다. 종합적으로 OneCLI는 AI 에이전트 생태계에서 가장 취약했던 자격 증명 관리 문제를 우아하게 해결하는 필수 인프라 도구로 자리매김하고 있습니다.

OneCLI 구조 및 주요 기능

아키텍처 구성 요소

## OneCLI의 아키텍처 구성 요소
## OneCLI의 아키텍처 구성 요소2082×1045 138 KB

OneCLI는 고성능과 보안을 유지하면서도 배포 편의성을 높이기 위해 크게 세 가지 핵심 구성 요소로 이루어져 있습니다. 이 모든 요소는 외부 의존성 없이 단일 Docker 컨테이너 내에서 구동됩니다:

  • Rust 게이트웨이 (Rust Gateway): 외부로 나가는 HTTP 요청을 실시간으로 가로채고 크리덴셜을 주입하는 핵심 프록시 서버입니다. 메모리 안전성과 매우 빠른 네트워크 처리 속도를 보장하기 위해 Rust 언어로 작성되었습니다. 에이전트는 Proxy-Authorization 헤더를 통해 자신의 액세스 토큰을 제공하여 게이트웨이에 인증 절차를 거칩니다.

  • 웹 대시보드 (Web Dashboard): 에이전트 등록, 비밀키 관리, 접근 권한(퍼미션) 설정을 할 수 있는 사용자 친화적인 Next.js 기반의 웹 애플리케이션입니다. 게이트웨이가 각 HTTP 요청에 대해 어떤 크리덴셜을 주입해야 하는지 즉각적으로 결정할 수 있도록 자체 API를 제공합니다.

  • 시크릿 스토어 (Secret Store): 저장된 자격 증명은 AES-256-GCM 암호화 알고리즘을 통해 디스크에 저장될 때 강력하게 보호(Encryption at rest)됩니다. 비밀값은 오직 HTTP 요청이 발생하는 런타임 시점에만 메모리 상에서 복호화되며, 모든 데이터는 임베디드 PostgreSQL(PGlite)을 사용하여 안전하게 보관됩니다.

요청 처리 및 크리덴셜 주입(Injection) 흐름

OneCLI의 가장 큰 특징인 투명한 크리덴셜 주입은 다음과 같은 논리적 흐름으로 진행됩니다.

  1. 개발자가 OneCLI 대시보드를 통해 볼트에 실제 API 토큰(예: ghp_123...)을 저장하고, 에이전트 환경 변수에는 가짜 키(예: FAKE_GITHUB_KEY)를 부여합니다.

  2. 에이전트는 가짜 키를 사용하여 평소처럼 대상 서비스(예: api.github.com)로 HTTP 요청을 생성합니다. 단, 이때 네트워크 트래픽은 OneCLI 프록시를 거치도록 라우팅 설정이 되어 있어야 합니다.

  3. OneCLI 게이트웨이가 이 HTTP 요청을 가로채어 목적지 호스트명과 URL 경로를 분석합니다.

  4. 사전에 정의된 정책(Policy)과 일치하고 해당 에이전트의 권한이 유효한 것으로 확인되면, 페이로드나 헤더에 있는 가짜 키(FAKE_GITHUB_KEY)를 복호화된 실제 토큰(ghp_123...)으로 안전하게 교체(Swap)합니다.

  5. 크리덴셜이 주입된 최종 요청이 실제 목적지 API 서버로 전달되며, 그에 대한 응답은 다시 프록시를 거쳐 에이전트에게 투명하게 반환됩니다.

OneCLI의 주요 기능

  • 호스트 및 경로 패턴 매칭: 특정 API 엔드포인트(도메인이나 특정 URL 경로)에 맞춰 올바른 비밀키가 정확히 라우팅되도록 정교한 패턴 매칭 기능을 지원합니다.

  • 멀티 에이전트 지원: 하나의 프록시 시스템에서 여러 개의 AI 에이전트를 동시에 운영할 수 있습니다. 각 에이전트마다 고유한 액세스 토큰을 발급하고 독립적으로 제한된 스코프(권한)를 부여할 수 있어 격리성이 뛰어납니다.

  • 유연한 인증 모드: 로컬 개발 환경이나 개인 프로젝트를 위해 별도의 로그인이 필요 없는 단일 사용자(Single-user) 모드를 지원하며, 엔터프라이즈 환경 및 팀 단위의 협업을 위해 Google OAuth 연동을 통한 인증 모드도 기본 제공합니다.

OneCLI 설치 및 빠른 시작

OneCLI는 Docker 컨테이너 환경을 기본으로 제공하므로, 복잡한 언어 런타임 설치나 환경 설정 과정 없이 아래의 명령어를 통해 로컬 머신에서 즉시 실행해 볼 수 있습니다.

단일 Docker 명령어로 바로 실행하기

Docker 컨테이너 환경을 실행할 수 있다면, 아래와 같이 한 줄의 명령어 만으로 이미지를 가져와 실행할 수 있습니다. 일반적인 사용 시에는 이 방법을 권장합니다:

docker run --pull always -p 10254:10254 -p 10255:10255 -v onecli-data:/app/data ghcr.io/onecli/onecli

소스 코드를 다운로드하여 Docker Compose로 실행하기

또는, 아래와 같이 소스코드를 내려받아 Docker 이미지를 빌드하여 사용할 수도 있습니다. OneCLI 코드를 변경하거나 기여를 하고 싶은 경우 이 방법을 사용합니다:

git clone https://github.com/onecli/onecli.git
cd onecli
docker compose -f docker/docker-compose.yml up

컨테이너가 정상적으로 실행된 후, 웹 브라우저에서 http://localhost:10254 포트로 접속하면 OneCLI 대시보드가 열립니다. 이곳에서 새로운 에이전트를 생성하고 필요한 비밀값을 등록한 뒤, 사용 중인 AI 에이전트의 HTTP 프록시 주소를 localhost:10255로 지정해 주면 모든 통신이 안전하게 보호되기 시작합니다.

라이선스

OneCLI 프로젝트는 Apache License 2.0으로 공개 및 배포 되고 있습니다.

:house: OneCLI 공식 홈페이지

:github: OneCLI 프로젝트 GitHub 저장소



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck: