AI代理Vault代理

Setup (one-time)

Three steps. Once you've done this, every new API key is just "add to Bitwarden + a few lines of YAML + restart": see Add a secret below.

1. Bitwarden Secrets Manager, enable it on your org, create a project for this host, create a machine account with read access to the project, generate a token. ~10 minutes the first time. Walkthrough.

1. Install + start the daemon. Pick the install path that matches your host:

<details open> <summary><b>Linux (recommended — hardened systemd install)</b></summary>

Full walkthrough: docs/install-systemd.md. ~10 minutes the first time. The doc:

• creates a dedicated avp UNIX user with no shell, no home directory,
• pip-installs the published wheel from PyPI (pip install --only-binary :all: agent-vault-proxy==0.4.3) into a system-wide venv at /opt/agent-vault-proxy/.venv — --only-binary :all: refuses source distributions, so a compromised transitive dep can't run code at install time,
• drops your BWS token at /etc/agent-vault-proxy/bws-token (root-owned, avp-readable) and your bindings at /etc/agent-vault-proxy/bindings.yaml,
• installs a locked-down systemd unit (ProtectSystem=strict, RestrictAddressFamilies, syscall filter, chattr +a append-only audit log) — sandbox controls Docker can't offer.

Token, bindings, audit log, and CA cert all live under /etc/agent-vault-proxy/ and /var/{lib,log}/agent-vault-proxy/. </details>

<details> <summary><b>Cross-platform / quick start (macOS, Windows-WSL2, or a Linux dev box)</b></summary>

   # Pick a tagged release, not `main` — tags are how you opt into a vetted
   # version. Tracking `main` exposes you to a window where a compromised
   # maintainer account could push a malicious commit before anyone notices.
   git clone -b v0.4.3 --depth 1 https://github.com/inflightsec/agent-vault-proxy && cd agent-vault-proxy
   mkdir -p secrets && bash -c '( umask 077 && read -rsp "BWS access token: " T && printf "%s" "$T" > secrets/bws-token && echo )'
   cp bindings.example.yaml bindings.yaml && $EDITOR bindings.yaml
   docker compose up -d
   

Faster setup; weaker isolation than systemd. Threat model + caveats in docs/docker.md.

⚠️ Two hard prerequisites for the Docker path: (1) your AI agent's UID must NOT have docker daemon access — docker-group membership ≈ host root, which lets the agent docker exec the CA private key + BWS token out of the proxy. (2) Do NOT add other containers to the proxy's avp-net network. If either is hard to guarantee on your host, use the systemd install path instead.

A pre-built, cosign-signed container image at ghcr.io/inflightsec/agent-vault-proxy:<tag> is planned for v0.5.0 — cosign verify + docker pull will replace the clone-and-build step. Until then, build locally from the cloned tag. </details>

1. Point your agent at the proxy:

First, copy the mitmproxy-generated CA cert into the calling shell's working dir. The location depends on install path:

   # systemd install (see install-systemd.md step 5):
   sudo cp /etc/agent-vault-proxy/ca.pem ./ca.pem && sudo chown "$USER" ./ca.pem

   # Docker install:
   docker cp agent-vault-proxy:/var/lib/agent-vault-proxy/.mitmproxy/mitmproxy-ca-cert.pem ./ca.pem
   

Then point the agent at the proxy + give it the placeholder:

   export HTTPS_PROXY="http://127.0.0.1:14322"  NODE_EXTRA_CA_CERTS="$PWD/ca.pem"  SSL_CERT_FILE="$PWD/ca.pem"
   export GITHUB_PAT="github_pat_PLACEHOLDER_01HXY1234ABCDEFGHIJ"
   curl -H "Authorization: Bearer $GITHUB_PAT" https://api.github.com/user
   

Agent's env holds only the placeholder. The real key never enters the process.

export GITHUB_PAT="github_pat_PLACEHOLDER_01HXY1234" export HTTPS_PROXY="http://127.0.0.1:14322"

bindings.yaml — what the agent sees vs. what the upstream sees

secrets: GITHUB_PAT: placeholder: "github_pat_PLACEHOLDER_01HXY1234" # the agent's env holds THIS inject: header: "Authorization" format: "Bearer {GITHUB_PAT}" # {GITHUB_PAT} = real value AVP fetches # from your backend for the entry above. # {secret} also works as a generic alias. bindings: - host: "api.github.com" # only swapped for this destination methods: [POST] # agent can open things... paths: ["/repos///pulls"] # ...but only "open a PR" - not delete, not merge