🔱 Aquaman

🔱 AI 에이전트를 위한 유일한 독립형 자격 증명 프록시: 자신의 볼트를 가져와 격리(isolation) 및 최소 권한 요청 정책을 적용합니다. 키는 이미 보관 중인 곳에 그대로 남아 있으며, 에이전트의 메모리에는 절대 저장되지 않습니다. 1Password, keychain, keepassxc 등과 호환됩니다.

Claude Code, OpenClaw 또는 Hermes를 설정하고 나면, 이제 귀중한 API 키가 평문(plaintext)으로 들어 있는 .env 파일을 마주하게 됩니다. 관련 기사들을 읽어보셨을 테고, 에이전트가 프롬프트 인젝션(prompt injection)을 당했을 때 어떤 일이 벌어지는지 아실 겁니다. 저희도 잘 알고 있습니다.

Aquaman은 세 가지 방어 계층으로 이 문제를 해결합니다:

1. 프로세스 격리: API 키는 별도의 프록시 프로세스에 존재합니다. 에이전트는 절대 키를 볼 수 없습니다. 에이전트에서 RCE(원격 코드 실행)가 발생하더라도 자격 증명에 접근할 수 없습니다. 서로 다른 주소 공간에 있습니다.
2. 요청 정책: 서비스별 규칙으로 에이전트가 호출할 수 있는 엔드포인트를 제어합니다. 관리 API를 차단하고, 삭제를 방지하며, 초안은 허용하지만 전송은 금지합니다. 거부된 요청은 실제 자격 증명을 절대 전달받지 못합니다.
3. 변조 감지 가능한 감사: 모든 자격 증명 사용이 SHA-256 해시 체인으로 기록됩니다. 무엇이 접근되었는지 증명할 수 있고, 사후 변조를 감지할 수 있습니다.

경로 선택

Aquaman은 하나의 볼트(vault) + 하나의 데몬(daemon)을 공유하는 네 가지 패키지로 제공됩니다. 필요한 것만 설치하세요:

단일 aquaman CLI로 네 가지를 모두 사용할 수 있습니다: 최상위 명령어로 볼트 및 감사, aquaman openclaw ...로 OpenClaw 통합, aquaman coder ...로 코딩 에이전트 통합(내부적으로 aquaman-coder에 위임), 그리고 aquaman hermes ...로 Hermes Python 패키지를 다룹니다.

빠른 시작

aquaman help, aquaman doctor는 여러분의 친구입니다.

1. 볼트만 (프록시 + 비밀만)

npm install -g aquaman-proxy
aquaman setup                                # 백엔드 마법사 + 키 저장
aquaman daemon &                             # 프록시 시작
aquaman credentials list                     # 확인

프록시는 ~/.aquaman/proxy.sock(UDS, chmod 0o600)에서 수신 대기합니다. 어떤 도구든 http://aquaman.local/<service>/<path>로 요청을 보내면 프록시가 선택한 볼트 백엔드에서 해당 서비스의 인증 헤더를 주입합니다.

2. OpenClaw 게이트웨이

openclaw plugins install aquaman-plugin           # 1. 플러그인 + 프록시 설치
openclaw aquaman setup                            # 2. 백엔드 + 키 + 플러그인 연결
openclaw                                          # 3. 완료 - 프록시가 자동으로 시작됨

문제 해결: openclaw aquaman doctor.

npm을 직접 사용하시나요? npm install -g aquaman-proxy && aquaman openclaw setup도 동일한 작업을 수행합니다 - 프록시 CLI를 설치하고, 키를 저장하며, 플러그인을 ~/.openclaw/extensions/aquaman-plugin/에 설치하고, 자격 증명을 연결합니다(OpenClaw ≥ 2026.6.5에서는 SecretRef 참조, 이전 버전에서는 auth-profiles.json 플레이스홀더 사용).

플러그인의 HTTP 인터셉터는 services 설정에 있는 서비스 트래픽만 리디렉션합니다(기본값: Anthropic + OpenAI). openclaw.json의 플러그인 설정에서 더 추가할 수 있습니다 - 지원되는 채널: Slack, Discord, Telegram, MS Teams, Matrix, LINE, Twitch, Twilio, BlueBubbles, Mattermost, Nostr, Tlon, Feishu, Google Chat, ElevenLabs, xAI, Cloudflare AI Gateway, Mistral, Hugging Face 등 (총 25개).

3. AI 코딩 에이전트 (현재 Claude Code)

npm install -g aquaman-proxy aquaman-coder        # 1. 데몬 + 어댑터 설치
aquaman setup                                      # 2. 볼트 마법사
aquaman daemon &                                   # 3. 프록시 시작

aquaman coder project add my-app --path ~/code/my-app \
  --env ANTHROPIC_API_KEY=aquaman://anthropic/api_key \
  --env GITHUB_TOKEN=aquaman://github/token         # 4. 프로젝트 선언
aquaman coder setup claude-code                    # 5. Claude Code 후크 연결
aquaman doctor                                     # 6. 확인 - 볼트와 코더 모두 초록색으로 표시되어야 함

직접 확인해 보세요(30초면 깨닫습니다): Claude Code를 다시 시작하고, ~/code/my-app 안에서 새 세션을 연 다음 에이전트에게 다음을 실행하도록 요청하세요:

printenv | grep ANTHROPIC_API_KEY

트랜스크립트에서 다음과 같은 내용을 보게 됩니다:

ANTHROPIC_API_KEY=[REDACTED:injected-value]

⏺ ANTHROPIC_API_KEY is set and available (injected via aquaman vault). 

자식 프로세스는 실제 키를 보았습니다(테스트, 빌드, MCP 서버, 임포트 스크립트 등 실제로 필요한 모든 것이 작동합니다). 에이전트 - 사용자 머신에서 어떤 코드를 실행할지 결정하는 주체 - 는 값을 절대 보지 못하므로, 대화 기록, 모델 제공자의 로그, 나중에 터미널을 캡처하는 사람도 볼 수 없습니다.

자신의 터미널에서도 사용할 수 있습니다. 동일한 래퍼가 에이전트 없이도 작동합니다. 해당 프로젝트 디렉토리로 cd한 후 명령어 앞에 접두사를 붙이기만 하면 됩니다:

cd ~/code/
aquaman-coder exec -- python app/scripts/import.py

동일한 환경 변수 주입, stdout/stderr에 대한 동일한 편집(redaction)이 적용됩니다. Makefile 타겟, 셸 별칭, CI 실행기 등 .env 파일을 사용하던 모든 곳에 활용하세요.

Claude Code가 ~/code/my-app에서 Bash 도구를 실행할 때, aquaman의 후크는 updatedInput.command를 통해 명령어를 aquaman-coder exec 아래에서 래핑하도록 다시 작성합니다. 이 래퍼는:

• 각 aquaman://service/key 참조를 브로커(POST /broker/resolve over UDS)를 통해 해결합니다. 자격 증명은 한 명령어에 대해서만 구체화되며, 에이전트 수명 동안 유지되지 않습니다.
• stdout/stderr를 편집기(redactor)를 통해 파이프하며, 각 해결된 값에 대해 값 기반 패턴을 앞에 추가합니다: 주입된 문자열이 무엇이든 관계없이 모양에 관계없이 편집됩니다(Atlassian 토큰, Notion 비밀, 내부 API 키 - 알려진 제공자 형식과 일치할 필요가 없습니다). 일반적인 모양 기반 패턴(sk-ant-, ghp_, sk_live_, AKIA…, JWT, PEM 블록, ATATT3xF…)은 여전히 방어 심층으로 실행되어, 우리가 주입하지 않은 비밀이 자식 프로세스에 노출되는 경우를 대비합니다.
• 명령어가 종료되면 정리합니다.

4. Hermes (에이전트 호스트)

Hermes는 전송 훅(transport hook)이 없는 외부(Python) 호스트이므로 격리는 프록시 측에서 수행됩니다: 프록시는 선택적이고 토큰 게이트(token-gated)된 루프백 리스너를 노출하고, Hermes는 자체 환경 변수를 통해 해당 리스너를 가리킵니다.

npm install -g aquaman-proxy                       # 1. 데몬 설치
aquaman setup                                      # 2. 볼트 마법사
aquaman credentials add anthropic api_key sk-ant-... # 3. 제공자 키 저장

aquaman hermes setup                               # 4. 루프백 활성화 + ~/.hermes/.env 작성
aquaman daemon &                                   # 5. 프록시 시작 (UDS + 루프백)
aquaman hermes doctor                              # 6. 확인 - 리스너 + 환경 변수 + 볼트 + Hermes

aquaman hermes setup은 루프백 리스너를 활성화하고, 설치별 토큰을 생성하며, ~/.hermes/.env에 aquaman 관리 블록을 작성합니다(HERMES_HOME을 존중): 네이티브 ANTHROPIC_BASE_URL/OPENAI_BASE_URL과 토큰과 동일한 플레이스홀더 api_key를 포함합니다. Hermes는 토큰을 자체 제공자 키로 보내고, 프록시가 이를 제거하고 실제 볼트 자격 증명을 주입한 후 업스트림으로 전달합니다. 현재는 LLM 제공자(Anthropic, OpenAI)만 지원합니다.

선택적 세션 내 편의 기능 - Python 플러그인은 Hermes 내부에 /aquaman-status 명령어, aquaman_status 도구, 세션 시작 상태 확인(health probe)을 추가합니다(자격 증명을 보유하지 않음):

pip install aquaman-hermes            # 또는: uv tool install aquaman-hermes
aquaman-hermes install                # 플러그인을 ~/.hermes/plugins/aquaman/에 넣음
hermes plugins enable aquaman

작동 방식

Agent / OpenClaw / Coding Agent             Aquaman Proxy
┌──────────────────────┐                    ┌──────────────────────┐
│                      │                    │                      │
│  ANTHROPIC_BASE_URL  │═══ UDS / HTTP ════>│  Keychain / 1Pass /  │
│  = aquaman.local     │                    │  Vault / Encrypted   │
│                      │<══════════════════ │                      │
│  fetch() interceptor │═══ broker:resolve  │  + Policy enforced   │
│   (channel APIs)     │                    │  + Auth injected:    │
│                      │                    │    header / url-path │
│  No credentials.     │  ~/.aquaman/       │    basic / oauth     │
│  No open ports.      │  proxy.sock        │                      │
│  Nothing to steal.   │  (chmod 0o600)     │                      │
└──────────────────────┘                    └──┬─────────┬─────────┘
                                               │         │
                                               │         ▼
                                               │  ~/.aquaman/audit/
                                               │  (hash-chained)
                                               ▼
                                     api.anthropic.com
                                     api.telegram.org
                                     slack.com/api …

1. 저장: 자격 증명은 사용자가 이미 실행 중인 볼트 백엔드에 저장됩니다 - 집 볼트(house vault)가 없음(Keychain, 1Password, HashiCorp Vault, Bitwarden, KeePassXC, systemd-creds, encrypted-file).
2. 정책: 프록시는 자격 증명을 건드리기 전에 메서드 + 경로 규칙을 확인합니다. 거부된 요청은 403을 반환하며, 실제 인증 헤더를 절대 전달하지 않습니다.
3. 주입: 프록시는 자격 증명을 조회한 후 인증 헤더를 추가하여 전달합니다. 25개의 내장 서비스, 4가지 주입 인증 모드(header, URL-path, HTTP Basic, OAuth); 5번째인 none은 저장 전용(at-rest-only)입니다(프록시가 트래픽을 거부함).
4. 브로커 (coder 경로): POST /broker/resolve는 도구 호출당 하나의 자격 증명을 구체화하며, 단일 명령어의 환경으로 범위가 지정된 후 만료됩니다.
5. 감사: 모든 자격 증명 사용이 SHA-256 해시 체인으로 기록됩니다.

에이전트는 센티넬 호스트 이름(aquaman.local) 또는 플레이스홀더 마커(aquaman-proxy-managed)만 볼 수 있습니다. 실제 키를 절대 볼 수 없으며, 다른 프로세스가 탐색할 수 있는 TCP 포트도 열려 있지 않습니다.

보안 모델

자세한 모델 - 통합별 세부사항(HTTP 인터셉터 범위, 인증 프로파일, 스캐너 결과, ClawScan 게시자 노트)은 packages/plugin/README.md 및 packages/coder/README.md에 있습니다.

규정 준수 태세

Aquaman은 test/compliance/ 아래에 실행 가능한 적합성 테스트를 제공하며, 다음에 매핑됩니다:

• MITRE ATLAS v5.4.0: 기술 AML.T0055, T0012, T0062, T0090, T0098 (test/compliance/atlas/)
• NIST SP 800-53 Rev 5: IA-5, AC-3, AC-6, AU-2/9/10, SC-12/28, SI-10 (test/compliance/nist/)

또한 CISA/5개국 "에이전트형 AI 서비스의 신중한 도입"(2026년 4월), CSA MAESTRO, OWASP Top 10 for Agentic Applications에 대한 정렬 서술이 포함됩니다. 테스트는 npm test의 일부로 실행됩니다. 매핑은 docs/compliance/에서 확인하세요.

요청 정책

OAuth 범위는 "이메일 초안 작성"과 "이메일 전송"을 구분할 수 없습니다. 둘 다 gmail.send입니다. 요청 정책이 그 차이를 채웁니다.

# ~/.aquaman/config.yaml
policy:
  anthropic:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organizations/**"
        action: deny          # 관리/결제 API 차단
  openai:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organization/**"
        action: deny
      - method: DELETE
        path: "/v1/**"
        action: deny          # 삭제 금지
  slack:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/admin.*"
        action: deny
  gmail:
    defaultAction: allow
    rules:
      - method: POST
        path: "/v1/users/*/messages/send"
        action: deny          # 초안은 허용, 전송은 차단

• 정책 없음 = 모두 허용(하위 호환)
• 첫 번째 일치 우선: 규칙은 위에서 아래로 평가되며, 일치하지 않는 요청은 defaultAction으로 넘어감
• 거부는 인증 전: 차단된 요청은 실제 자격 증명을 절대 얻지 못함
• 경로 글로브(glob): *는 세그먼트 내에서 일치, **는 0개 이상의 세그먼트와 일치
• aquaman setup은 저장된 서비스(anthropic, openai, slack, gmail)에 대해 안전한 기본값을 적용함
• aquaman policy list / aquaman policy test <svc> <method> <path>로 검사 및 드라이런 가능

자격 증명 백엔드

자신의 볼트를 가져오세요 - aquaman에는 집 저장소(house store)가 없습니다. 이미 실행 중인 백엔드를 선택하면, 비밀은 그곳에 남아 있고 프록시가 그 자리에서 읽습니다.

aquaman setup은 적절한 기본값을 자동 감지합니다(macOS → keychain; Linux → keychain(libsecret이 있는 경우), systemd-creds(systemd ≥ 256인 경우), 그 외 encrypted-file).

encrypted-file은 네이티브 키링이 없는 헤드리스 Linux/CI 환경을 위한 최후의 수단입니다. Linux에서 보안을 강화하려면 libsecret-1-dev(GNOME Keyring)를 설치하거나 systemd-creds(TPM2 바인딩) 또는 1Password/Vault를 사용하세요.

자격 증명 캐싱 (v0.13.1+)

접근당 비용이 발생하는 백엔드 — 1password(데스크톱 앱 모드에서 읽을 때마다 생체 인증 프롬프트), bitwarden(~1-2초 CLI 생성), vault(HTTP 왕복) — 는 기본적으로 데몬 메모리에 15분 동안 캐시되므로, 바쁜 에이전트 세션은 요청당 한 번이 아니라 시간 창당 한 번만 볼트를 잠금 해제합니다. 다른 백엔드는 이미 빠르거나 내부적으로 캐시하므로, 기본적으로 캐싱이 꺼져 있습니다. ~/.aquaman/config.yaml에서 credentials.cacheTtlSeconds로 조정하거나(AQUAMAN_CACHE_TTL), 0으로 설정하면 비활성화됩니다.

솔직한 트레이드오프: 접근당 생체 인증 프롬프트는 사용자 존재 확인이며, 캐시는 TTL 창 동안 접근당 존재 확인을 제거합니다. 무인 에이전트의 경우 해당 프롬프트는 절대 응답되지 않습니다 — 볼트를 평문 .env 파일로 포기하게 되어 훨씬 더 나쁩니다. 캐시는 격리 경계를 이동시키지 않습니다: 값은 프록시 프로세스(이미 모든 요청에서 전송되는 곳)에만 존재하고, 디스크에 기록되지 않으며, aquaman credentials add로 회전할 때 즉시 무효화됩니다. 쓰기는 항상 볼트로 이동합니다. 적합성 테스트는 test/compliance/cache-residency.test.ts에서 확인할 수 있습니다. 1Password에서 프롬프트 제로를 원하면 aquaman 볼트로 범위가 지정된 서비스 계정을 사용하세요 — aquaman doctor가 안내할 것입니다.

라이선스

MIT - LICENSE 참조.