🔱 AI 에이전트를 위한 유일한 독립 자격 증명 프록시: 자체 볼트 격리(BYOV) 및 최소 권한 요청 정책. 키는 이미 보관 중인 곳에 그대로 남아 있으며, 에이전트 메모리에 절대 저장되지 않습니다. 1Password, keychain, keepassxc 및 기타 여러 도구와 호환됩니다.
# 🔱 Aquaman
[](https://github.com/tech4242/aquaman/actions/workflows/ci.yml)
[](https://codecov.io/gh/tech4242/aquaman)
[](https://www.npmjs.com/package/aquaman-proxy)
[](https://www.npmjs.com/package/aquaman-proxy)
[](https://github.com/tech4242/aquaman#security-model)
[](https://www.typescriptlang.org/)
[](LICENSE)
🔱 AI 에이전트를 위한 유일한 독립형 자격 증명 프록시: bring-your-own-vault 격리 및 최소 권한 요청 정책. 여러분의 키는 이미 보관하고 있는 곳에 그대로 남아 있으며, 에이전트의 메모리에는 절대 들어가지 않습니다. 1Password, keychain, keepassxc 및 기타 여러 도구와 호환됩니다.
Claude Code, Codex, OpenClaw, Hermes 또는 Docker Sandboxes를 설정했는데, 이제 소중한 API 키가 평문으로 들어 있는 `.env` 파일을 뚫어지게 바라보고 있을 겁니다. 관련 글들을 읽어보셨을 테고, 에이전트가 프롬프트 인젝션을 당하면 무슨 일이 벌어지는지도 아실 겁니다. 충분히 이해합니다.
Aquaman은 세 가지 방어 계층으로 이 문제를 해결합니다:
1. **프로세스 격리**: API 키는 송신 시점에 키를 주입하는 별도의 프록시 프로세스에 존재합니다. 에이전트는 키가 아닌 마커만 보유하므로, 에이전트에서 RCE가 발생하더라도 키를 읽을 수 없습니다. 코딩 에이전트는 여러분이 선언한 참조만, 한 번에 하나의 명령씩 받습니다.
2. **요청 정책**: 서비스별 규칙이 에이전트가 호출할 수 있는 *엔드포인트*를 제어합니다. 관리자 API를 차단하고, 삭제를 방지하며, 초안 작성은 허용하되 전송은 거부할 수 있습니다. 거부된 요청에는 실제 자격 증명이 절대 전달되지 않습니다.
3. **변조 감지 감사**: 모든 자격 증명 사용은 SHA-256 해시 체인으로 기록됩니다. 무엇에 접근했는지 증명하고, 사후에 변조를 감지할 수 있습니다.
## 경로 선택
Aquaman은 하나의 vault + 하나의 데몬을 공유하는 네 개의 조율된 패키지로 제공됩니다. 필요한 것만 설치하세요:
| 패키지 | 기능 | 설치 시점 |
|---|---|---|
| **[`aquaman-proxy`](https://github.com/tech4242/aquaman/blob/main/packages/proxy)** | 핵심: vault, 데몬, 감사, 정책, CLI. 누구나 필요한 부분. | 항상. |
| **[`aquaman-plugin`](https://github.com/tech4242/aquaman/blob/main/packages/plugin)** | OpenClaw Gateway 어댑터. Gateway 시작 시 프록시를 실행하고, 모델 및 Telegram 트래픽을 이를 통해 라우팅하며, 5가지 인증 모드에 걸쳐 25개의 내장 서비스를 제공합니다. | OpenClaw Gateway를 운영하는 경우. https://clawhub.ai/plugins/aquaman-plugin 에서도 이용 가능 |
| **[`aquaman-coder`](https://github.com/tech4242/aquaman/blob/main/packages/coder)** | AI 코딩 에이전트 어댑터. Bash 도구 호출마다 해석되는 프로젝트 범위의 `aquaman://service/key` 참조. | Claude Code 또는 Codex를 사용하는 경우. |
| **[`aquaman-hermes`](https://github.com/tech4242/aquaman/blob/main/packages/hermes)** | Hermes 에이전트 호스트 플러그인 (Python, PyPI). 네이티브 `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL`을 통해 Hermes를 옵트인 방식의 토큰 게이트 루프백 리스너로 연결하며, 세션 내 `/aquaman-status` 명령, 도구, 상태 프로브를 추가합니다. 격리는 프록시 측에서 이루어지며, 플러그인은 자격 증명을 보유하지 않습니다. | Hermes 에이전트 호스트를 운영하는 경우. `pip install aquaman-hermes` |
| **Docker Sandboxes** | 패키지가 아닙니다: `aquaman-proxy`만 필요한 별도의 경로입니다. Docker 자체 프록시가 시크릿을 주입하고, `aquaman get`이 허용 목록 및 감사 로그와 함께 vault에서 시크릿을 제공합니다. | Docker Sandboxes에서 에이전트를 실행하는 경우. [Quick Start 5](#5-docker-sandboxes) 참조. |
단일 `aquaman` CLI가 네 가지 모두를 노출합니다: vault 및 감사를 위한 최상위 명령, OpenClaw 통합을 위한 `aquaman openclaw ...`, 코딩 에이전트 통합을 위한 `aquaman coder ...`(내부적으로 `aquaman-coder`에 위임) 그리고 Hermes Python 패키지를 위한 `aquaman hermes ...`.
## Quick Start
`aquaman help`, `aquaman doctor`가 여러분의 친구입니다.
### 1. Vault만 사용 (프록시 + 여러분의 시크릿만)
```bash
npm install -g aquaman-proxy
aquaman setup # backend wizard + store keys
aquaman daemon & # start the proxy
aquaman credentials list # verify
```
프록시는 `~/.aquaman/proxy.sock` (UDS, `chmod 0o600`)에서 수신 대기합니다. 어떤 도구든 `http://aquaman.local/<service>/<path>`로 지정하면 프록시가 선택한 vault 백엔드에서 해당 서비스의 인증 헤더를 주입합니다.
### 2. OpenClaw Gateway
```bash
openclaw plugins install aquaman-plugin # 1. install plugin + proxy
openclaw aquaman setup # 2. backend + keys + plugin wire-up
openclaw # 3. done - proxy starts automatically
```
문제 해결: `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 플레이스홀더).
`aquaman openclaw setup`은 `models.providers.<svc>.baseUrl`과 `channels.telegram.apiRoot`를 프록시의 루프백 리스너로 지정합니다. OpenClaw의 모델 전송과 각 채널이 자체 HTTP 클라이언트를 구축하여 fetch 인터셉터를 우회하기 때문입니다. Telegram 이외의 채널은 엔드포인트 재정의를 노출하지 않으므로, 해당 토큰은 저장되고 마이그레이션되지만 이그레스 시점에 주입되지 않습니다 ([`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md) 참조). `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, Codex)
```bash
npm install -g aquaman-proxy aquaman-coder # 1. install daemon + adapter
aquaman setup # 2. vault wizard
aquaman daemon & # 3. start the proxy
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. declare a project
aquaman coder setup claude-code # 5. wire Claude Code hooks
# (or: aquaman coder setup codex)
aquaman doctor # 6. verify - should show both vault + coder green
```
**직접 확인해 보세요 (30초 만에 깨닫는 순간):** Claude Code(또는 Codex)를 재시작하고, `~/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 서버, import 스크립트 등 실제로 키가 필요한 모든 것은 작동합니다). *에이전트* - 즉, 여러분의 머신에서 어떤 코드를 실행할지 결정하는 그 존재 - 는 값을 결코 보지 못하며, 따라서 대화 기록도, 모델 제공자의 로그도, 나중에 여러분의 터미널을 스크린샷 찍는 누구도 보지 못합니다.
**여러분의 터미널에서도 사용하세요.** 동일한 래퍼는 에이전트 없이도 작동합니다. 커버된 프로젝트로 `cd`한 다음 명령 앞에 접두사를 붙이기만 하면 됩니다:
```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py
```
동일한 환경 변수 주입, stdout/stderr에 대한 동일한 리댁션. Makefile 타깃, 셸 별칭, CI 러너 등 평소라면 `.env` 파일을 찾았을 곳 어디든 넣으면 된다.
Claude Code나 Codex가 `~/code/my-app`에서 셸 명령을 실행하면, aquaman의 훅이 `updatedInput.command`를 통해 명령을 재작성하여 `aquaman-coder exec` 아래로 감싼다. 이 래퍼는:
- 브로커(`POST /broker/resolve`, UDS 경유)를 통해 각 `aquaman://service/key` 참조를 해석한다. 자격 증명은 에이전트의 수명이 아니라 단일 명령을 위해 구체화된다.
- stdout/stderr를 리댁터를 통해 파이프하며, 해석된 각 값에 대해 값 기반 패턴을 앞에 붙인다: **주입된 문자열은 형태와 무관하게 리댁션된다** (Atlassian 토큰, Notion 시크릿, 내부 API 키 — 어느 것도 알려진 제공자 형식과 일치할 필요가 없다). 일반적인 형태 기반 패턴(sk-ant-, ghp_, sk_live_, AKIA…, JWT, PEM 블록, ATATT3xF…)은 우리가 주입하지 않은, 자식 프로세스가 노출하는 시크릿에 대한 심층 방어로서 이후에 여전히 실행된다.
- 명령이 종료되면 정리한다.
**Claude Code 샌드박스:** 기본적으로 Unix 소켓을 차단하므로, `aquaman coder setup claude-code`가 macOS에서 프록시 소켓을 허용 목록에 추가한다(`sandbox.network.allowUnixSockets`). Linux와 WSL2는 이 목록을 무시하며, 유일한 옵션은 `sandbox.network.allowAllUnixSockets: true`인데, 이는 샌드박스된 명령에 모든 Unix 소켓을 개방한다.
**Codex:** 설정 후 Codex의 시작 훅 검토에서 aquaman 훅을 승인하라 (Codex는 신뢰하기 전까지 새 훅을 건너뛴다). 이 샌드박스 역시 기본적으로 프록시 소켓을 차단하므로, `aquaman coder setup codex`가 이를 허용하는 `config.toml` 권한 프로필을 출력한다. Codex 훅은 셸 출력을 재작성할 수 없으므로, 리댁션은 `aquaman-coder exec` 내부에서 일어난다. 자세한 내용은 [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md#codex) 참조.
### 4. Hermes (에이전트 호스트)
Hermes는 주입할 전송 훅이 없는 외부(Python) 호스트이므로, 격리는 프록시 측에서 수행된다: 프록시가 옵트인 방식의 토큰 게이트 루프백 리스너를 노출하고, Hermes는 자체 환경 변수를 통해 이 리스너를 가리킨다.
```bash
npm install -g aquaman-proxy # 1. install daemon
aquaman setup # 2. vault wizard
aquaman credentials add anthropic api_key sk-ant-... # 3. store a provider key
aquaman hermes setup # 4. enable loopback + write ~/.hermes/.env
aquaman daemon & # 5. start the proxy (UDS + loopback)
aquaman hermes doctor # 6. verify - listener + env + vault + Hermes
```
`aquaman hermes setup`은 루프백 리스너를 활성화하고, 설치별 토큰을 생성하며, `~/.hermes/.env`(`HERMES_HOME` 존중)에 aquaman이 관리하는 블록을 기록합니다: 네이티브 `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL`과 토큰과 동일한 자리 표시자 api_key입니다. Hermes는 토큰을 프로바이더 키로 전송하고, 프록시는 이를 제거한 뒤 실제 vault 자격 증명을 주입하여 업스트림으로 전달합니다. 현재는 LLM 프로바이더(Anthropic, OpenAI)만 지원합니다.
**선택적 세션 내 편의 기능** - Python 플러그인은 `/aquaman-status` 명령, `aquaman_status` 도구, 그리고 Hermes 내부의 세션 시작 상태 프로브를 추가합니다(자격 증명은 보유하지 않음):
```bash
pip install aquaman-hermes # or: uv tool install aquaman-hermes
aquaman-hermes install # drops the plugin into ~/.hermes/plugins/aquaman/
hermes plugins enable aquaman
```
플러그인은 또한 `GITHUB_TOKEN`과 같은 프로젝트 시크릿을 위한 `aquaman` **시크릿 소스**(Hermes ≥ 0.18.1)를 등록합니다. Hermes의 `config.yaml`에서 `secrets.aquaman.env` 아래에 이들을 바인딩한 다음, 각 ref를 `aquaman broker allow aquaman://github/token`으로 선언하세요(v0.15.0부터 필수이며, `aquaman hermes doctor`가 누락된 항목을 나열합니다). 위의 LLM 키와 달리, 이 값들은 Hermes의 env에 들어갑니다. [`packages/hermes/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/hermes/README.md)를 참조하세요.
### 5. Docker 샌드박스
Docker 샌드박스는 이미 자격 증명을 샌드박스 외부에 유지합니다. 사용자 머신의 프록시가 요청에 자격 증명을 주입하고, VM 내부의 에이전트는 플레이스홀더를 봅니다. 기본적으로 값은 OS 키체인에서 가져옵니다. 대신 이들을 aquaman으로 지정하면 aquaman이 지원하는 모든 vault, ref 허용 목록, 그리고 sbx가 시크릿을 읽을 때마다 변조 감지 가능한 감사 항목을 얻을 수 있습니다.
```bash
npm install -g aquaman-proxy
aquaman setup # 1. vault wizard
aquaman daemon & # 2. start the proxy
aquaman credentials add github token # 3. store the secret (if not already there)
aquaman broker allow aquaman://github/token # 4. allow it to be handed out
sbx secret set github \
--command "$(command -v node) $(command -v aquaman) get aquaman://github/token" \
--refresh on-demand # 5. sbx reads it from aquaman
```
sbx는 자체 백그라운드 서비스에서 해당 명령을 실행하며, 이 서비스에는 셸의 `PATH`가 없으므로 5단계에서 절대 경로를 저장합니다. 샌드박스가 사용하는 각 서비스에 대해 4단계와 5단계를 반복하세요.
동일한 `aquaman get` 명령은 도구가 시크릿을 출력하는 명령을 요구하는 어디에서나 작동합니다: Codex(`model_providers.<id>.auth.command`), Claude Code(`apiKeyHelper`), OpenClaw exec 시크릿 제공자 및 Hermes 명령 시크릿 소스.
## 작동 방식
```
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 │ │
│ No keys to read. │ (chmod 0o600) │ │
└──────────────────────┘ └──┬─────────┬─────────┘
│ │
│ ▼
│ ~/.aquaman/audit/
│ (hash-chained)
▼
api.anthropic.com
api.telegram.org
slack.com/api …
```
1. **Store**: 자격 증명은 이미 운영 중인 vault 백엔드에 저장됩니다 - 별도의 house vault는 없습니다 (Keychain, 1Password, HashiCorp Vault, Bitwarden, Keeper, KeePassXC, systemd-creds, encrypted-file).
2. **Policy**: 프록시는 자격 증명을 건드리기 *전에* 메서드 + 경로 규칙을 확인합니다. 거부된 요청은 `403`을 받으며, 실제 인증 헤더는 절대 받지 않습니다.
3. **Inject**: 프록시는 자격 증명을 조회하고 전달하기 전에 인증 헤더를 추가합니다. 25개의 내장 서비스, 4개의 주입 인증 모드 (header, URL-path, HTTP Basic, OAuth); 5번째인 `none`은 at-rest 전용입니다 (프록시가 트래픽을 거부).
4. **Broker (coder, Hermes secret source, `aquaman get`)**: `POST /broker/resolve`는 도구 호출마다 자격 증명을 구체화하며, 단일 명령의 env로 범위가 제한됩니다. `aquaman daemon`만 이를 제공하며, 선언한 ref(`projects.yaml` 또는 `aquaman broker allow`)에 대해서만 제공합니다. OpenClaw 플러그인의 프록시는 이를 절대 제공하지 않습니다 (v0.15.0+).
5. **Audit**: 모든 자격 증명 사용은 SHA-256 해시 체인으로 기록됩니다.
프록시 경로에서 에이전트는 로컬 엔드포인트와 마커를 봅니다: `aquaman-proxy-managed` 플레이스홀더, 또는 로컬 프록시에 대해서만 작동하는 loopback 토큰입니다. 실제 키는 절대 보지 못합니다. coder 경로에서는 *자식* 명령이 선언된 값을 받고 에이전트는 리댁션된 출력을 봅니다.
## Security Model
| Layer | What it does | What it stops |
|---|---|---|
| **Process isolation** | 자격 증명은 별도 프로세스에 있으며, Unix 소켓(`chmod 0o600`) 또는 토큰으로 게이트된 loopback 리스너를 통해 접근됩니다 | 침해된 에이전트는 프록시된 키를 읽을 수 없습니다: 주소 공간이 다릅니다 |
| **Broker scope** | `aquaman daemon`만 값을 전달하며, 선언한 ref에 대해서만 전달합니다; OpenClaw가 호스팅하는 프록시는 절대 전달하지 않습니다 (v0.15.0+) | 에이전트가 소켓을 통해 임의의 vault 항목을 가져올 수 없습니다 |
| **Service allowlisting** | `proxiedServices`가 에이전트가 접근할 수 있는 API를 제어합니다 | 에이전트가 승인하지 않은 서비스와 통신할 수 없습니다 |
| **Request policies** | 서비스별 메서드 + 경로 규칙으로, 자격 증명 주입 전에 적용됩니다 | 에이전트가 Anthropic에는 접근할 수 있지만 admin API에는 접근할 수 없습니다; 이메일을 작성할 수 있지만 보낼 수는 없습니다 |
| **Audit trail** | 모든 자격 증명 사용에 대한 SHA-256 해시 체인 로그 | 사후 포렌식, 변조 탐지, 컴플라이언스 증거 |
| **Per-tool-call broker (coder)** | `aquaman-coder exec`는 한 번에 하나의 명령에 대해 자격 증명을 구체화합니다 | 자격 증명이 에이전트의 셸 환경 전반에 퍼지지 않습니다 |
| **Output redaction (coder)** | `aquaman-coder exec`는 stdout/stderr를 리댁터를 통해 파이프하여 방금 주입한 각 값을 그대로 스크럽합니다 - 추가로 일반적인 제공자 패턴을 폴백으로 사용합니다 | 임의의, 형태 없는 자격 증명조차 에이전트 트랜스크립트에 도달하지 않습니다 |
### Transports and access control
| Path | Transport | Access control |
|---|---|---|
| Coding agents, 소켓을 다이얼할 수 있는 모든 클라이언트 | Unix 소켓 `~/.aquaman/proxy.sock` | 파일 권한 (`0600`): 당신으로 실행되는 프로세스만 |
| Hermes (v0.13.0+), OpenClaw 모델 및 Telegram 트래픽 (v0.15.0+) | Loopback TCP `127.0.0.1:<port>` | 설치별 토큰, 상수 시간 검사, loopback 바인드 |
Hermes와 OpenClaw는 각자 자체 HTTP 클라이언트를 구축하며 소켓을 다이얼할 수 없으므로 리스너를 사용합니다. 그 외 모든 것은 소켓을 사용합니다.
토큰은 로컬 프록시에 도달하기 위한 capability이며, 자격 증명이 아닙니다. 설치별로 생성되어 `~/.aquaman/config.yaml`(`0600`)에 저장되며, 호스트가 자신의 provider api key로 전송합니다. 프록시는 이를 확인하고, 제거하고, 실제 키를 주입합니다. Telegram에는 인증 헤더가 없으므로, 거기서는 토큰이 대신 `/bot<TOKEN>` 경로 세그먼트에 실립니다.
트레이드오프: 모든 로컬 프로세스가 loopback 포트에 도달할 수 있으며, 다른 사용자도 포함됩니다. 소켓의 `0600`은 그들을 차단합니다. 토큰이 거기서 게이트 역할을 하므로, `aquaman hermes setup` 또는 `aquaman openclaw setup`이 켜기 전까지 리스너는 꺼져 있습니다.
### Channel credentials on OpenClaw 2026.7.33+
| Channel | Egress through the proxy |
|---|---|
| Telegram | 예, v0.15.0부터 |
| 그 외 모든 것 | 아니오. Vault 저장 및 마이그레이션만 |
각 채널은 요청마다 자체 HTTP 클라이언트를 구축하므로, 플러그인의 `fetch` 인터셉터는 이 버전들에서 더 이상 채널 트래픽을 보지 못합니다. 채널을 라우팅하려면 호스트의 엔드포인트 오버라이드가 필요하며, Telegram만 이를 가지고 있습니다: `aquaman openclaw setup`은 `channels.telegram.apiRoot`를 프록시로 지정하고 봇 토큰을 loopback 토큰으로 교체합니다.
나머지의 경우, 토큰은 vault에 남아 있지만 OpenClaw가 이를 직접 사용하므로 프록시가 경로에 없고 해당 호출은 감사되지 않습니다. `aquaman openclaw doctor`는 구성된 채널 중 어느 것이 어느 그룹에 속하는지 나열합니다. 모델 제공자는 영향을 받지 않습니다.
**What same-user isolation can't do.** 소켓의 `0o600`은 다른 사용자를 차단하지만, 당신으로 실행되는 다른 프로세스는 차단하지 않습니다. 그러한 프로세스는 실행 중에 프록시를 통해 요청을 보낼 수 있으며 (요청 정책에 의해 제한되고 감사 로그에 기록됨), 선언한 ref를 가져올 수 있습니다. 선언한다는 것은 바로 그런 의미입니다. 프록시가 주입하는 키는 읽을 수 없습니다. 더 강한 경계를 위해서는 에이전트를 다른 OS 사용자로 실행하거나 샌드박스에서 실행하십시오.
상세 모델 - 통합별 세부 사항 (HTTP 인터셉터 범위, 인증 프로필, 스캐너 결과, ClawScan 게시자 노트) - 은 [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md) 및 [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md)에 있습니다.
### Compliance posture
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/Five-Eyes "Careful Adoption of Agentic AI Services" (2026년 4월), CSA MAESTRO, OWASP Top 10 for Agentic Applications에 대한 정렬 내러티브가 있습니다. 테스트는 `npm test`의 일부로 실행됩니다. 매핑은 [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance)를 참조하십시오.
## Request Policies
OAuth 스코프는 "이메일 초안 작성"과 "이메일 전송"을 구분할 수 없습니다. 둘 다 `gmail.send`입니다. 요청 정책이 그 간극을 메웁니다.
```yaml
# ~/.aquaman/config.yaml
policy:
anthropic:
defaultAction: allow
rules:
- method: "*"
path: "/v1/organizations/**"
action: deny # block admin/billing API
openai:
defaultAction: allow
rules:
- method: "*"
path: "/v1/organization/**"
action: deny
- method: DELETE
path: "/v1/**"
action: deny # no deletions
slack:
defaultAction: allow
rules:
- method: "*"
path: "/api/admin.*"
action: deny # Slack Web API admin methods
gmail:
defaultAction: allow
rules:
- method: POST
path: "/gmail/v1/users/*/messages/send"
action: deny # drafts ok, sending blocked
```
- **경로는 서비스 접두사 뒤의 업스트림 API 전체 경로입니다**: Slack의 Web API는 `/api/<method>`, Gmail은 `/gmail/v1/...`입니다. v0.15.0 이전의 프리셋은 `/admin.*`와 `/v1/users/*/messages/send`를 사용했는데, 이는 실제 트래픽과 결코 일치하지 않았습니다. `aquaman doctor`는 이러한 항목이 아직 설정에 남아 있으면 표시합니다.
- **정책 없음 = 모두 허용** (하위 호환)
- **첫 번째 일치가 우선**: 규칙은 위에서 아래로 평가되며, 일치하지 않는 요청은 `defaultAction`으로 넘어갑니다
- **인증 전에 거부**: 차단된 요청은 실제 자격 증명을 절대 받지 못합니다
- **경로 글롭:** `*`는 세그먼트 내에서 일치하고, `**`는 0개 이상의 세그먼트와 일치합니다
- `aquaman setup`은 저장된 서비스(`anthropic`, `openai`, `slack`, `gmail`)에 안전한 기본값을 적용합니다.
- `aquaman policy list` / `aquaman policy test <svc> <method> <path>`로 검사 / 드라이런을 수행합니다.
## 자격 증명 백엔드
자체 볼트를 사용하세요 - aquaman에는 자체 저장소가 없습니다. 이미 운영 중인 백엔드를 선택하면 비밀은 그곳에 남아 있고, 프록시가 그 자리에서 읽습니다.
| 백엔드 | 최적 용도 | 설정 |
|---|---|---|
| `keychain` | macOS 로컬 개발 (기본값) | 별도 설정 없이 작동 |
| `encrypted-file` | Linux, WSL2, CI/CD | AES-256-GCM, 비밀번호 보호 |
| `keepassxc` | 기존 KeePass 사용자 | `npm i -g kdbxweb argon2` (v0.14.1부터 선택적 피어), 그런 다음 `AQUAMAN_KEEPASS_PASSWORD` 또는 키 파일 설정 |
| `1password` | 팀 자격 증명 공유 | `brew install 1password-cli && op signin`. 무인 에이전트의 경우 [서비스 계정](https://developer.1password.com/docs/service-accounts/) 사용 (`OP_SERVICE_ACCOUNT_TOKEN`) |
| `vault` | 엔터프라이즈 비밀 관리 | `VAULT_ADDR` + `VAULT_TOKEN` 설정 |
| `systemd-creds` | systemd ≥ 256인 Linux | TPM2 기반, root 불필요 |
| `bitwarden` | Bitwarden 사용자 | `bw login && export BW_SESSION=$(bw unlock --raw)` |
| `keeper` | Keeper 비밀번호 관리자 사용자 (v0.16.0+) | `pip install keepercommander`, `keeper shell`로 한 번 로그인하고 `this-device persistent-login on`을 켠 다음, aquaman용 폴더를 만들고 `export AQUAMAN_KEEPER_FOLDER_UID=<folder UID>`를 실행합니다. 레코드 제목은 `aquaman::<service>::<key>`입니다 |
`aquaman setup`은 적절한 기본값을 자동 감지합니다 (macOS → `keychain`; Linux → libsecret이 있으면 `keychain`, 없으면 systemd ≥ 256인 경우 `systemd-creds`, 그 외에는 `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 스폰), `keeper` (로그인하고 동기화하는 Commander 스폰), `vault` (HTTP 왕복)처럼 접근마다 비용이 발생하는 백엔드는 기본적으로 **데몬의 메모리**에 15분 동안 캐시되므로, 바쁜 에이전트 세션에서 요청마다가 아니라 창당 한 번만 볼트를 잠금 해제합니다. 다른 백엔드는 이미 빠르거나 내부적으로 캐시하므로 기본적으로 캐싱이 꺼져 있습니다. `~/.aquaman/config.yaml`의 `credentials.cacheTtlSeconds` (또는 `AQUAMAN_CACHE_TTL`)로 조정하세요. `0`은 비활성화합니다.
솔직한 트레이드오프: 접근마다의 생체 인증 프롬프트는 사용자 존재 확인이며, 캐시는 TTL 창 동안 접근마다의 존재 확인을 제거합니다. 무인 에이전트의 경우 그 프롬프트는 결코 응답되지 않으므로, 볼트는 평문 `.env`로 방치되며 이는 명백히 더 나쁩니다. 캐시는 격리 경계를 **이동시키지 않습니다**: 값은 프록시 프로세스에만 존재하고 (모든 요청에서 이미 거쳐가는 곳), 디스크에 절대 기록되지 않으며, `aquaman credentials add`로 교체하면 즉시 무효화됩니다. 쓰기는 항상 볼트로 갑니다. [`test/compliance/cache-residency.test.ts`](https://github.com/tech4242/aquaman/blob/main/test/compliance/cache-residency.test.ts)에서 적합성 테스트를 거쳤습니다. 1Password에서 프롬프트 없이 사용하려면 `aquaman` 볼트로 범위가 지정된 서비스 계정을 사용하세요. `aquaman doctor`가 그곳으로 안내합니다.
## 라이선스
MIT - [LICENSE](https://github.com/tech4242/aquaman/blob/main/LICENSE) 참조.