Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

docs(agent-vault): audit 2 (#8290)

Adrian Kahali775429a608f8
diff --git a/docs/cli/commands/agent-vault.mdx b/docs/cli/commands/agent-vault.mdx
index c90dab8558..4cb9bfbffb 100644
--- a/docs/cli/commands/agent-vault.mdx
+++ b/docs/cli/commands/agent-vault.mdx
@@ -16,7 +16,7 @@ infisical agent-vault run --access-bundle <bundle-name> --proxy <proxy-host>:173
These subcommands are the CLI half of [Agent Vault](/documentation/platform/agent-vault/overview). `proxy` runs the process that attaches credentials to agent traffic. `run` launches an agent with its HTTP traffic routed through a proxy and a session token to identify it.
-The two usually run on different machines. A proxy's settings are set on the Proxies page, not with flags, and reach a running proxy on its next poll.
+The two usually run on different machines. You change a proxy's settings on the **Proxies** page, not with flags. If the proxy is running, it applies the change within one [poll interval](/documentation/platform/agent-vault/proxies#poll-interval).
`av` is an alias for `agent-vault`, so `infisical av run` works wherever `infisical agent-vault run` does.
diff --git a/docs/documentation/platform/agent-vault/access-bundles.mdx b/docs/documentation/platform/agent-vault/access-bundles.mdx
index db2ede3c9f..f1eeb921b7 100644
--- a/docs/documentation/platform/agent-vault/access-bundles.mdx
+++ b/docs/documentation/platform/agent-vault/access-bundles.mdx
@@ -55,4 +55,4 @@ To allow a user, group, or machine identity to create sessions for a given acces
### Revoke access
-To revoke access from a user, group, or machine identity, open the bundle and select **Options** > **Manage Access**. Find them with the search box, open their actions menu, and select **Revoke Access**. Any of their running agents lose the bundle's credentials within one poll interval of the proxy.
\ No newline at end of file
+To revoke access from a user, group, or machine identity, open the bundle and select **Options** > **Manage Access**. Find them with the search box, open their actions menu, and select **Revoke Access**. If any of their agents are running, those agents lose the bundle's credentials within one [poll interval](/documentation/platform/agent-vault/proxies#poll-interval).
\ No newline at end of file
diff --git a/docs/documentation/platform/agent-vault/access-control.mdx b/docs/documentation/platform/agent-vault/access-control.mdx
index 432d788036..23afd18e25 100644
--- a/docs/documentation/platform/agent-vault/access-control.mdx
+++ b/docs/documentation/platform/agent-vault/access-control.mdx
@@ -5,49 +5,86 @@ description: "Understand how permissions work in Agent Vault."
Access control in Agent Vault happens at two levels:
-1. **Product membership** — being added to Agent Vault itself
-2. **Access bundle grants** — being granted an access bundle, which is what lets you create sessions with it
+1. **Product membership:** being added to Agent Vault itself
+2. **Access bundle grants:** being granted an [access bundle](/documentation/platform/agent-vault/access-bundles), which lets you create sessions with it
-Users, groups, and [machine identities](/documentation/platform/identities/machine-identities) all go through both levels and hold the same roles, so everything below applies to all three unless it says otherwise. An agent holds no access of its own: it runs on a session created by a person or a machine identity, and reaches only what that session's access bundle covers.
+Users, groups, and [machine identities](/documentation/platform/identities/machine-identities) go through both levels and use the same roles, so this page applies to all three unless it says otherwise.
+
+<Note>
+Access control doesn't directly apply to the actual agents you run through Agent Vault:
+
+- A user or machine identity uses their access to create a [session](/documentation/platform/agent-vault/sessions) with an associated access bundle
+- Agents can only make requests that are allowed by their session's access bundle
+
+This keeps the user or machine identity directly accountable for what an agent can access.
+</Note>
## Product membership
-Agent Vault is organization-wide, so there is one membership list for the whole organization rather than one per project. There are two roles:
+Agent Vault has one member list for your whole organization, instead of one per project. Each member has one of two roles:
| Role | What they can do |
|------|------------------|
-| **Admin** | Create and manage access bundles, services, and proxies. Grant access bundles. Manage membership. Read audit logs |
-| **Member** | Create sessions with the access bundles granted to them, and revoke their own |
+| **Admin** | <ul><li>Create and manage access bundles, services, and proxies</li><li>Grant access bundles</li><li>Manage membership</li><li>Read audit logs</li></ul> |
+| **Member** | <ul><li>Create sessions with the access bundles granted to them</li><li>Revoke their own sessions</li></ul> |
-An admin reaches every access bundle without being granted one. A member reaches nothing until an admin grants them one, and sees only the ones they hold. Members see their own sessions; admins can switch the Sessions page between **All Sessions** and **My Sessions**.
+An admin can use every access bundle without a grant. A member can't use an access bundle until an admin grants it, and only sees the bundles granted to them. On the **Sessions** page, members see their own sessions, and admins can switch between **All Sessions** and **My Sessions**.
<Note>
- Organization admins can enter Agent Vault as an admin themselves, without being added by someone else. Opening the product from the organization overview is enough.
+ If you're an organization admin, Infisical adds you to Agent Vault as an admin the first time you open it. You don't need another admin to add you.
</Note>
### Adding members
-1. Go to **Agent Vault → Access Control**
-2. Select the **Users**, **Machine Identities**, or **Groups** tab
-3. Select **Add Users**, **Add Machine Identity**, or **Add Group**
-4. Choose who to add, and give them **Admin** or **Member**
+<Info>
+ You need the **Admin** role in Agent Vault to add members.
+</Info>
+
+<Steps>
+ <Step>
+ In Agent Vault, go to **Access Control**.
+ </Step>
+ <Step>
+ Select the **Users**, **Machine Identities**, or **Groups** tab.
+ </Step>
+ <Step>
+ Select **Add Users**, **Add Machine Identity**, or **Add Group**.
+ </Step>
+ <Step>
+ Select who to add, and choose **Admin** or **Member** in **Product Role**.
+ </Step>
+</Steps>
+
+You can only add users who are already in the [organization](/documentation/platform/organization), including users whose invite is still pending. If a user's invite is pending, they can't create sessions until they accept it.
-Each tab searches the whole membership rather than the rows on screen. A search matches a user's name, username, or email address, and a group or machine identity's name.
+<Note>
+You can't change your own role or remove your own access. Ask an admin if you need to do either.
+</Note>
-Whoever you add has to be an active member of the organization first. Invite them to the organization before adding them here.
+## Access bundle grants
-You can't change your own role or remove your own access. Ask another admin to do either.
+Adding someone to Agent Vault doesn't automatically give their agents access to any external APIs. They also need a grant on an [access bundle](/documentation/platform/agent-vault/access-bundles), which defines the external APIs their agents can access during a [session](/documentation/platform/agent-vault/sessions).
-## Access bundle grants
+<Info>
+ You need the **Admin** role in Agent Vault to grant access bundles.
+</Info>
+
+Open an access bundle and select **Manage Access** to [grant it](/documentation/platform/agent-vault/access-bundles#grant-access) to a user, machine identity, or group.
-Product membership is the entry ticket. Reaching a host still takes a grant on the [access bundle](/documentation/platform/agent-vault/access-bundles) that holds the service covering it.
+### Groups
-Open an access bundle and select **Manage Access** to grant it to a user, machine identity, or group. The grantee has to be an Agent Vault member already. That list is paged and searchable, so finding one member of a bundle granted to hundreds doesn't mean scrolling through all of them.
+If you grant an access bundle to a group, every member of that group gets access to it, and each member can independently create sessions.
-Granting a group grants everyone in it, and each member creates sessions as themselves. Someone who joins the group later picks the grant up, and someone who leaves loses it.
+<Note>
+If someone joins the group, they inherit access to the bundle. If they leave the group, they lose access to the bundle.
+</Note>
## When access changes
-A change to membership or a grant reaches a running agent within one proxy poll, 60 seconds by default. Nothing on the agent's machine needs restarting.
+If someone's Agent Vault membership or access bundle grants change while their agent is running, the proxy applies the change to the agent's requests within one [poll interval](/documentation/platform/agent-vault/proxies#poll-interval) (60 seconds by default). They don't need to restart the agent.
+
+If someone is removed from Agent Vault, Infisical also removes their access bundle grants. If they get added back, they'll need to be re-granted the same access bundles again before their sessions get credentials.
-Removing someone from Agent Vault also takes away their access bundle grants, so adding them back leaves their sessions without credentials until you grant those again. See [what a running agent can reach](/documentation/platform/agent-vault/sessions#access-changes) for what happens to each kind of change mid-run.
+<Tip>
+For more information about what happens when access changes mid-run, check out [access changes](/documentation/platform/agent-vault/sessions#access-changes).
+</Tip>
\ No newline at end of file
diff --git a/docs/documentation/platform/agent-vault/how-it-works.mdx b/docs/documentation/platform/agent-vault/how-it-works.mdx
index 8b52c9903c..1bd9c361a7 100644
--- a/docs/documentation/platform/agent-vault/how-it-works.mdx
+++ b/docs/documentation/platform/agent-vault/how-it-works.mdx
@@ -115,10 +115,12 @@ Here's a breakdown of each primitive that Agent Vault relies on.
A service represents one external API, such as GitHub's REST API, Slack's Web API, or Anthropic's messages endpoint. Each service holds:
-- **Hosts.** The host or hosts the service applies to, like `api.github.com`
-- **Authentication scheme.** How the API authenticates: bearer, basic, or pass-through
-- **Credential.** The real API token or username and password the proxy attaches to matching requests
-- **Rules.** The HTTP methods and paths the service allows, if you want to narrow it further
+- **Hosts**: The host or hosts the service applies to, like `api.github.com`
+- **Authentication scheme**: How the API authenticates: bearer, basic, or pass-through
+- **Credential**: The real API token or username and password the proxy attaches to matching requests
+- **Rules**: The HTTP methods and paths the service allows (every method and path by default)
+- **Custom headers**: Extra headers the proxy adds to each request
+- **Substitutions**: Placeholders that the proxy replaces with real values
You don't hand services to an agent directly—they're defined within access bundles.
@@ -150,7 +152,7 @@ Even if an attacker stole the session token, they could only reach the hosts, me
### Proxies
-A proxy runs where your agent's traffic leaves your network. It intercepts every outbound request, authorizes the request against the session's access bundle, attaches the matching service's credential as a header, and forwards the request to the upstream host. A request that breaks the service's rules is refused instead.
+A proxy runs where your agent's traffic leaves your network. It intercepts every outbound request, authorizes the request against the session's access bundle, attaches the matching service's credential as a header, and forwards the request to the upstream host. If the request breaks the matching service's [method or path rules](/documentation/platform/agent-vault/services#methods-and-paths), the proxy refuses it instead.
<Card title="Proxies" icon="route" href="/documentation/platform/agent-vault/proxies">
Forward proxies that intercept an AI agent's requests and attach real credentials on the way out.
@@ -162,7 +164,7 @@ Here's what happens when an agent calls `api.github.com` through an Agent Vault
1. The agent's HTTPS client routes the request through the [proxy](#proxies) (because the `HTTPS_PROXY` environment variable points at it), including the [session](#sessions) token as the proxy credential.
2. The proxy looks up the session with Infisical, checking if it's still live and which [access bundle](#access-bundles) it carries.
-3. The proxy looks inside the session's access bundle and finds a [service](#services) whose host pattern covers `api.github.com`. If that service allows only certain methods or paths, the request is checked against them first. The proxy reads the real GitHub token from that service.
+3. The proxy looks inside the session's access bundle and finds a [service](#services) whose host pattern covers `api.github.com`. If the service limits methods or paths, the proxy refuses a request that doesn't match them. The proxy reads the real GitHub token from that service.
4. The proxy opens a new HTTPS connection to `api.github.com`, attaches the real token in the authorization header, and forwards the request.
5. GitHub responds. The proxy pipes the response back to the agent.
diff --git a/docs/documentation/platform/agent-vault/proxies.mdx b/docs/documentation/platform/agent-vault/proxies.mdx
index dcbe219081..b102fd3e1c 100644
--- a/docs/documentation/platform/agent-vault/proxies.mdx
+++ b/docs/documentation/platform/agent-vault/proxies.mdx
@@ -3,15 +3,36 @@ title: "Proxies"
description: "Run the proxy that attaches credentials, set its traffic policy, and understand how agents trust it."
---
-A proxy is the forward proxy that brokers credentials: it applies the real credential to matching requests on the way out and leaves everything else untouched. It runs where agent traffic leaves your network: on a host of its own that agents across your network share, or next to a single agent. You create it in the dashboard, enroll it once from the CLI, and change its settings from the dashboard afterwards.
+A proxy intercepts your agents' requests to the APIs they call, then attaches the necessary API credential to each request that matches a [service](/documentation/platform/agent-vault/services). Run the proxy where agent traffic leaves your network, either on its own host that several agents share, or on the same machine as one agent.
-## Enrolling
+You create a proxy in Infisical, enroll it once from the CLI, and change its settings in Infisical afterwards.
-Go to **Proxies**, select **Create Proxy**, name it, and select **Create**. The dialog shows a one-time enrollment token, valid for an hour, and the same three snippets below with your token and instance filled in. Run one of them where the proxy will live:
+## Create and enroll a proxy
-<Frame>
- <img src="/images/platform/agent-vault/proxy-enrollment-token.png" alt="The Enrollment Token dialog with CLI, Docker, and systemd tabs and the one-hour countdown" />
-</Frame>
+<Steps>
+ <Step>
+ In Agent Vault, go to **Proxies** and select **Create Proxy**.
+ </Step>
+ <Step>
+ Enter a **Name**. To set the [traffic policy](#traffic-policy), [exceptions](#exceptions), or [poll interval](#poll-interval) now, expand **Advanced Options**. You can change them later.
+
+ <Frame>
+ <img src="/images/platform/agent-vault/proxy-create.png" alt="The Create Proxy dialog with the two traffic policy options and the poll interval" />
+ </Frame>
+ </Step>
+ <Step>
+ Select **Create**. The **Enrollment Token** dialog shows a one-time token that expires in an hour, and commands for the CLI, Docker, and systemd with your token and instance filled in.
+
+ <Frame>
+ <img src="/images/platform/agent-vault/proxy-enrollment-token.png" alt="The Enrollment Token dialog with CLI, Docker, and systemd tabs and the one-hour countdown" />
+ </Frame>
+ </Step>
+ <Step>
+ Run one of the commands on the machine where the proxy will run.
+ </Step>
+</Steps>
+
+The commands look like this:
<Tabs>
<Tab title="CLI">
@@ -51,30 +72,51 @@ Go to **Proxies**, select **Create Proxy**, name it, and select **Create**. The
</Tab>
</Tabs>
-`--domain` points the proxy at your Infisical instance. It defaults to `https://app.infisical.com`, so EU Cloud and self-hosted instances have to pass it.
+### Command flags
+
+Here's a list of available flags for the [`infisical agent-vault proxy`](/cli/commands/agent-vault#infisical-agent-vault-proxy) command:
-The proxy enrolls, generates its own certificate authority, and serves on port `17323`. It keeps its state in `~/.infisical/agent-vault`, or `/etc/infisical/agent-vault` when run as root, so run it somewhere that directory persists. Running the same command again on a restart is fine. A proxy that starts with an empty state directory needs a new token: select **New Enrollment Token** on the proxy's menu.
+| Option | What it sets |
+|--------|--------------|
+| `--enrollment-token` | The one-time token from the **Enrollment Token** dialog. You can set `INFISICAL_AGENT_VAULT_ENROLLMENT_TOKEN` instead |
+| `--domain` | Your Infisical instance URL. It defaults to Infisical Cloud (US), and the commands in the dialog already include your instance's URL |
+| `--port` | The port the proxy listens on. It defaults to `17323` |
+| `--data-dir` | Where the proxy keeps its state. See [state directory](#state-directory) |
<Note>
- Anything on a command line is readable by other users on the machine. To keep the token out of it, put `INFISICAL_AGENT_VAULT_ENROLLMENT_TOKEN=<enrollment-token>` in a file with mode `0600` and pass it with `--env-file` (Docker) or `EnvironmentFile=` (systemd), dropping `--enrollment-token` from the command. You can delete the file once the proxy has enrolled.
+ Other users on the machine can read anything on a command line. To keep the enrollment token off it, put `INFISICAL_AGENT_VAULT_ENROLLMENT_TOKEN=<enrollment-token>` in a file with mode `0600`, and pass the file with `--env-file` for Docker or `EnvironmentFile=` for systemd. You can delete the file once the proxy has enrolled.
</Note>
-Run `infisical agent-vault proxy --port 18000` to listen on a different port.
+### State directory
+
+When the proxy enrolls, it generates its own certificate authority and saves it with its enrollment in a state directory at `~/.infisical/agent-vault` (or `/etc/infisical/agent-vault` if you run the proxy as the root user on the machine).
+
+The enrollment token only works once. After the first run, the proxy reads its enrollment from the state directory, so you can restart the proxy without `--enrollment-token`:
+
+```bash
+infisical agent-vault proxy --domain <your-instance-url>
+```
+
+If the state directory is empty, the proxy can't start without a new token. Select **New Enrollment Token** on the proxy's menu and [enroll again](#re-enroll-a-proxy).
## Settings
-Every setting lives in Infisical and reaches a running proxy on its next poll. Select **Edit Settings** on the proxy's menu.
+To change a setting, select **Edit Settings** on the proxy's menu. If the proxy is running, it applies the change within one [poll interval](#poll-interval) (60 seconds by default).
### Traffic policy
-Which hosts an agent may reach through this proxy.
+The **Traffic Policy** setting controls which hosts agents can reach through the proxy:
-- **Allow requests to reach any host**, the default: every request goes out. Hosts an access bundle covers get its credential, and the rest go out with none.
-- **Only allow requests to reach hosts specified in access bundles**: a request to any host outside them is refused, unless the host is an exception.
+- **Any host** (default): the proxy forwards every request, and attaches a credential only for hosts covered by a service
+- **Access bundle hosts only**: the proxy refuses requests to hosts that no service in the session's access bundle covers, unless the host is an [exception](#exceptions)
-Use the second when the proxy sits somewhere it could reach more than you intend, such as a network with internal systems on it. Under it, a pass-through service is how one access bundle makes a host reachable without giving it a credential.
+<Tip>
+Use **Access bundle hosts only** if the proxy can reach systems that agents shouldn't have access to, such as internal services on the same network.
+</Tip>
-A refusal isn't a refused connection. The proxy answers `CONNECT` with `200 Connection Established` and completes the TLS handshake first, then refuses the request itself:
+#### Blocked requests
+
+If the policy blocks a request, the proxy still accepts the connection and completes the TLS handshake, so the agent gets a 403 response instead of a connection error:
```text
HTTP/1.1 403 Forbidden
@@ -82,58 +124,89 @@ HTTP/1.1 403 Forbidden
no service covers host "internal.example.com": host blocked by policy
```
-Ports are part of the match. A [service's host pattern](/documentation/platform/agent-vault/services#host-patterns) that names no port covers port 443 only, so a service on `example.com` doesn't cover `example.com:8443`, and under this policy a request to the second is refused. Name the port in the pattern to cover it.
-
-The proxy returns a 403 the same way for a request that breaks a service's own [method or path rules](/documentation/platform/agent-vault/services#methods-and-paths), whichever traffic policy it runs.
+The proxy also returns a 403 for:
-<Frame>
- <img src="/images/platform/agent-vault/proxy-create.png" alt="The Create Proxy dialog with the two traffic policy options and the poll interval" />
-</Frame>
+- A request to a port the service's [host pattern](/documentation/platform/agent-vault/services#host-patterns) doesn't name, such as `example.com:8443` for a service on `example.com`, which only covers port `443`
+- A request that breaks the service's [method or path rules](/documentation/platform/agent-vault/services#methods-and-paths), under either traffic policy
### Exceptions
-A comma-separated list of hosts that stay reachable under **Only allow requests to reach hosts specified in access bundles**, with no credential attached. Use it for hosts every agent needs, such as a package registry or a documentation site. Under **Allow requests to reach any host** the list changes nothing.
+Exceptions allow your agents to access hosts that aren't covered by any service in an access bundle, even when your proxy uses **Access bundle hosts only**. Use exceptions for hosts every agent needs, such as a package registry or a documentation site.
-An exception written without a port matches that host on every port, unlike a [service pattern](/documentation/platform/agent-vault/services#default-port), which means port 443 when it names none. An exception never carries a credential, so the wider match attaches nothing extra.
+To add exceptions, select the policy and enter the hosts in **Exceptions** as a comma-separated list. The field doesn't appear under **Any host**, because that policy already lets every host through.
-An exception isn't exempt from interception. Every HTTPS host is TLS-terminated by the proxy before any policy applies, so an exception is a host the proxy doesn't block, not a host it leaves alone. To open a host for one access bundle rather than for every agent on the proxy, add a pass-through service to that bundle instead.
+Exception hosts behave differently from hosts that are covered by services:
-### Poll interval
+- **Credentials:** The proxy never attaches a credential to requests to an exception host
+- **Ports:** An exception with no port matches the host on every port, while a [service's host pattern](/documentation/platform/agent-vault/services#default-port) with no port only matches port `443`
+- **Interception:** The proxy still decrypts requests to an exception host, but doesn't block them
+- **Scope:** An exception applies to every agent that uses the proxy
-How often, in seconds, the proxy re-checks each active session with Infisical and picks up settings changes. The default is 60 and the range is 10 to 300. Every "within one poll interval" on these pages means this number.
+<Tip>
+To let only one access bundle reach a host, add a [pass-through service](/documentation/platform/agent-vault/services#pass-through) to that bundle instead of adding an exception to the proxy.
+</Tip>
-If the proxy can't reach Infisical, it keeps serving what it last knew for five poll intervals, then refuses the affected requests with a 502 until it can check again. It never forwards a request without the credential it was supposed to attach. The Proxies page marks a proxy **Unreachable** after three missed check-ins.
+### Poll interval
-## Certificate trust
+The poll interval is how often, in seconds, the proxy re-checks each active session with Infisical and applies settings changes. It defaults to 60 and can be set from 10 to 300.
-The proxy terminates TLS to attach the credential, so each agent has to trust the proxy's certificate authority. Every proxy has its own.
+If the proxy can't reach Infisical:
-`infisical agent-vault run` handles this. It fetches the certificate from the proxy on every run and sets `SSL_CERT_FILE`, `NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `GIT_SSL_CAINFO`, and `DENO_CERT` for the agent. On macOS it also offers to add the certificate to your login keychain, for tools such as `gh` and `docker` that read the system trust store. Pass `--no-ca-trust` to skip the step on a machine that already trusts the proxy.
+- The proxy keeps using the session data it last fetched for five poll intervals
+- After that, the proxy refuses the affected requests with a 502 until it reaches Infisical again, instead of forwarding them without their credentials
+- The **Proxies** page marks the proxy **Unreachable** after three missed check-ins
-An agent you start without the CLI, such as a container that sets `HTTPS_PROXY` itself, needs the certificate mounted and those variables set. `http://<proxy-address>/_agent-vault/ca` returns the certificate inside a JSON object, so write the `certificate` field out on its own:
+## Certificate trust
-```bash
-curl -s http://<proxy-address>/_agent-vault/ca | jq -r .certificate > ca.pem
-```
+The proxy decrypts HTTPS traffic to attach the credential, so each agent has to trust the proxy's certificate authority (CA). Each proxy generates its own self-signed CA when it enrolls.
-That agent also needs `HTTPS_PROXY` and `HTTP_PROXY` set, with the session token as the password:
+<Tabs>
+ <Tab title="With the CLI">
+ If you start the agent with `infisical agent-vault run`, the CLI sets up trust for you. On every run, it fetches the certificate from the proxy and sets these variables for the agent: `SSL_CERT_FILE`, `NODE_EXTRA_CA_CERTS`, `REQUESTS_CA_BUNDLE`, `CURL_CA_BUNDLE`, `GIT_SSL_CAINFO`, and `DENO_CERT`.
-```bash
-export HTTPS_PROXY="http://x-agent-vault:<session-token>@<proxy-address>"
-export HTTP_PROXY="$HTTPS_PROXY"
-```
+ On macOS, if you run the CLI in a terminal, it also adds the certificate to your login keychain for tools such as `gh` and `docker` that read the system trust store. macOS asks you to approve the change. To skip this step on a machine that already trusts the proxy, pass `--no-ca-trust`.
+ </Tab>
+ <Tab title="Without the CLI">
+ If you start the agent another way, such as in a container that sets `HTTPS_PROXY` itself, set up trust yourself:
+
+ <Steps>
+ <Step>
+ Download the certificate from the proxy:
+
+ ```bash
+ curl -s http://<proxy-address>/_agent-vault/ca | jq -r .certificate > ca.pem
+ ```
+ </Step>
+ <Step>
+ Mount `ca.pem` where the agent can read it, and point the agent's CA variables at it, such as `SSL_CERT_FILE` and `NODE_EXTRA_CA_CERTS`.
+ </Step>
+ <Step>
+ Route the agent through the proxy, with the session token as the password:
+
+ ```bash
+ export HTTPS_PROXY="http://x-agent-vault:<session-token>@<proxy-address>"
+ export HTTP_PROXY="$HTTPS_PROXY"
+ ```
+ </Step>
+ </Steps>
+ </Tab>
+</Tabs>
-The session token travels to the proxy with every request, so run the proxy where only your agents can reach it: the same host, a private network, or a container network.
+<Warning>
+Agents send their session token to the proxy unencrypted with every request. If someone can read that traffic and reach the proxy, they can use the token to call every API in the session's access bundle with its real credentials. The token keeps working until the session expires or you [revoke it](/documentation/platform/agent-vault/sessions#revoke-a-session).
-### Pinning
+For this reason, we recommend running the proxy where only your agents can reach it, such as on the same host, a private network, or a container network.
+</Warning>
-To make sure the agent is talking to your proxy and nothing else, pass the fingerprint from the Proxies page:
+### Pin the proxy's certificate
+
+If the agent runs on a network you don't fully control, pin the proxy's certificate so the agent only talks to your proxy. Copy the fingerprint from the **Certificate Authority** column on the **Proxies** page, and pass it with `--ca-fingerprint`:
```bash
infisical agent-vault run --session-token <session-token> --proxy <proxy-address> --ca-fingerprint SHA256:9F:2C:... -- claude
```
-The CLI aborts before starting the agent if the served certificate doesn't match. Pin when the agent runs on a network you don't fully control.
+If the proxy's certificate doesn't match, the CLI stops before starting the agent.
<Frame>
<img src="/images/platform/agent-vault/proxies-list.png" alt="The Proxies page showing two healthy proxies with their traffic policy and certificate authority fingerprints" />
@@ -141,14 +214,26 @@ The CLI aborts before starting the agent if the served certificate doesn't match
### APIs with a private certificate authority
-The proxy verifies the certificate of each API it connects to, the way any HTTPS client would. If an API you're connecting to uses a private certificate authority, the machine running the proxy has to trust that authority. The agent's machine doesn't.
+The proxy checks the certificate of each API it connects to, the way any HTTPS client does. If an API uses a private certificate authority, the machine running the proxy has to trust that authority. The agent's machine doesn't need to trust it.
+
+### Re-enroll a proxy
+
+To re-enroll a proxy, select **New Enrollment Token** on the proxy's menu and run the new command. The proxy keeps its name, settings, and history, but gets a new certificate authority.
+
+After you re-enroll a proxy:
-### Re-enrolling
+- Restart every agent that uses the proxy, because those agents still trust the old certificate
+- Update any `--ca-fingerprint` pin
+- Replace any mounted copy of the certificate
+- On macOS, replace the certificate in your login keychain
-Selecting **New Enrollment Token** and enrolling again replaces the proxy's certificate authority. The proxy keeps its name, settings, and history. Restart any agent that was running through it, since it trusts the old certificate. Update any `--ca-fingerprint` pin, mounted copy of the certificate, or macOS keychain entry as well.
+## Revoke or delete a proxy
-## Revoking and deleting
+Both actions are on the proxy's menu:
-**Revoke Access** on a proxy's menu invalidates the proxy's token on its next poll. Every agent routed through it loses credentials, and the proxy process exits with a message saying its access was revoked. Use it when you believe the proxy host is compromised. To bring the proxy back, select **New Enrollment Token** and enroll again.
+| Action | What happens |
+|--------|--------------|
+| **Revoke Access** | The proxy's token stops working right away. Every agent using the proxy loses its credentials, and the proxy answers requests with a 503. The proxy process exits after two failed check-ins in a row (one to two [poll intervals](#poll-interval)) |
+| **Delete** | Infisical removes the proxy. If the proxy is running, it stops working and exits the same way as a revoked proxy |
-**Delete** removes the proxy record. A running process for it exits the same way.
+Revoke access if you think the proxy's host is compromised. To bring a revoked proxy back, [re-enroll it](#re-enroll-a-proxy).
diff --git a/docs/documentation/platform/agent-vault/services.mdx b/docs/documentation/platform/agent-vault/services.mdx
index d0cf060dd2..7d2c6c96a1 100644
--- a/docs/documentation/platform/agent-vault/services.mdx
+++ b/docs/documentation/platform/agent-vault/services.mdx
@@ -3,7 +3,11 @@ title: "Services"
description: "External APIs that an AI agent can securely call during a session."
---
-A service represents one external API that an agent can access during a [session](/documentation/platform/agent-vault/sessions). Each service defines the external API’s host URL, its authentication method, and a real credential to attach when forwarding requests from the agent.
+A service represents one external API that an agent can access during a [session](/documentation/platform/agent-vault/sessions). Each service defines the external API’s [host URL](#host-patterns), its [authentication method](#credential-types), and a real credential to attach when forwarding requests from the agent.
+
+<Tip>
+A service can also limit which [HTTP methods and paths](#methods-and-paths) the agent can use, [add custom headers](#custom-headers) to each request, and [replace placeholder values](#substitutions) the agent sends with real ones.
+</Tip>
You can configure services within an [access bundle](/documentation/platform/agent-vault/access-bundles). For example, you might create a **code-review** access bundle and add services for Slack, GitHub, and Anthropic:
@@ -56,7 +60,7 @@ Basic is the right choice for APIs behind HTTP basic authentication, including o
### Pass-through
-The proxy attaches no credential. Unless the service adds [custom headers](#custom-headers) or [substitutions](#substitutions), it forwards the agent's request to the API unchanged.
+The proxy attaches no credential. Unless the service adds [custom headers](#custom-headers) or [substitutions](#substitutions), the proxy forwards the agent's request to the API unchanged.
Pass-through is the right choice when the proxy's strict [traffic policy](/documentation/platform/agent-vault/proxies#traffic-policy) would otherwise block the host. It lets the request reach the API without attaching a credential.
@@ -100,15 +104,19 @@ internal-api.example.com:8443
### Plaintext hosts
-A service behaves the same way over plain `http://` as it does over HTTPS. The proxy attaches the credential, the custom headers, and the substitutions either way. Use a plaintext host for an API on your own network that terminates TLS at the edge, or one that serves no HTTPS at all.
+A service works the same way over plain HTTP as it does over HTTPS. The proxy attaches the credential, the custom headers, and the substitutions either way. Use a plaintext host for an API on your own network that doesn't serve HTTPS.
-Since a host without a port means `443`, a plaintext service has to name its port:
+Leave the `http://` scheme off the host, and name the port instead:
```text
internal-api.example.com:8080
```
-The credential crosses that hop unencrypted, so anyone who can read traffic between the proxy and the API can read it. Keep plaintext hosts to a network you trust.
+If you don't name the port, the host will only match [port `443`](#default-port):
+
+<Warning>
+The proxy sends the credential to a plaintext host unencrypted, so anyone who can read traffic between the proxy and the API can read the credential. Only use plaintext hosts on a network you trust.
+</Warning>
### Wildcards
@@ -118,9 +126,28 @@ Wildcards match exactly one label. The pattern below matches `api.atlassian.net`
*.atlassian.net
```
+## Host conflicts
+
+Two services within an access bundle can't cover the same host with the same pattern. For example, if you have a service that defines its host as `api.github.com` and you try to create a second service with that same host, Infisical will stop you from saving the second service.
+
+However, two services can match the same host if they define the host pattern differently. When the agent makes a request to that host, the request will match the service that defines the host more explicitly. For example:
+
+- One service defines its host as `api.github.com`
+- Another service defines it as `*.github.com`
+
+In the above example, requests to `api.github.com` are handled by the first service.
+
+<Warning>
+The proxy applies only the more specific service's [methods and paths](#methods-and-paths). This means that if the `api.github.com` service allows only `GET`, the proxy refuses a `POST` to `api.github.com`, even if that same `POST` request would succeed through `*.github.com`.
+</Warning>
+
+<Note>
+Different access bundles can cover the same host with different credentials, since an agent only gets the credential from the access bundle its session is scoped to.
+</Note>
+
## Methods and paths
-By default, a service allows every HTTP method and every path on its hosts. When configuring a service, you have the option to narrow it to only the methods and routes your agent needs.
+By default, a service allows every HTTP method and every path on its hosts. When configuring a service, you have the option to narrow it to only the methods and paths your agent needs.
<Frame>
<img src="/images/platform/agent-vault/service-details.png" alt="The Details step of a GitHub service, allowing GET and POST on the path prefixes /repos and /search" />
@@ -128,61 +155,51 @@ By default, a service allows every HTTP method and every path on its hosts. When
### Methods
-Select the HTTP methods the service allows. A read-only service might allow only `GET` and `HEAD`, so a request that tries to write is stopped before it leaves your network.
+On the **Details** step, clear **All Methods** and select the HTTP methods the service allows. For example, if a service allows only `GET` and `HEAD`, the proxy refuses a `POST` or `DELETE` request before the request leaves your network.
-### Path prefixes
-
-List the routes the service allows. A path prefix matches whole segments, so `/repos` covers `/repos/octo/hello` but not `/repositories`. Write the path exactly as it appears in the URL.
-
-The proxy blocks a request that breaks either rule with a 403:
-
-```text
-HTTP/1.1 403 Forbidden
+### Paths
-service "github" does not allow POST: blocked by service policy
-```
+On the **Details** step's **Paths** field, enter each path prefix the service allows. A path prefix matches whole segments, so `/repos` covers `/repos/octo/hello` but not `/repositories`. Write the path exactly as it appears in the URL.
<Note>
-A service with path prefixes set also refuses any path that different servers would resolve differently, such as one containing `..` or an encoded slash. Ordinary paths still work, including ones carrying a space or a non-ASCII character such as `/repos/owner/repo/contents/café.md`.
+If a service has path prefixes, the proxy also refuses any path that different servers would resolve differently, such as one containing `..` or an encoded slash. Ordinary paths still work, including ones with a space or a non-ASCII character such as `/repos/owner/repo/contents/café.md`.
</Note>
-## Host conflicts
-
-Two services within an access bundle can't cover the same host with the same pattern. For example, if you have a service that defines its host as `api.github.com` and you try to create a second service with that same host, Infisical will stop you from saving the second service.
+### Refused requests
-However, two services can match the same host if they define the host pattern differently. When the agent makes a request to that host, the request will match the service that defines the host more explicitly. For example:
+If a request breaks either rule, the proxy refuses the request with a 403. The message names the service and the method or path it doesn't allow:
-- One service defines its host as `api.github.com`
-- Another service defines it as `*.github.com`
-
-In the above example, requests to `api.github.com` are handled by the first service.
+```text
+HTTP/1.1 403 Forbidden
-The more specific service handles the request outright, so its [methods and paths](#methods-and-paths) are the ones that apply. If it allows only GET, a POST to `api.github.com` is refused even though the wildcard service allows every method. A wildcard covers the hosts its sibling doesn't name, not the requests its sibling refuses.
+service "github" does not allow POST: blocked by service policy
+```
-<Note>
-Different access bundles can cover the same host with different credentials, since an agent only gets the credential from the access bundle its session is scoped to.
-</Note>
+```text
+HTTP/1.1 403 Forbidden
+service "github" does not allow path "/admin": blocked by service policy
+```
## Custom headers
-Some APIs need a header alongside the credential, such as an organization ID or an API version. On the **Credential** step, under **Advanced Options**, add one with a name, an optional prefix, and a value. The proxy attaches it to every request to that service, whatever credential type the service uses.
+Some APIs need a header alongside the credential, such as an organization ID or an API version. On the **Credential** step, under **Advanced Options**, select **Add Custom Header** and enter a name, an optional prefix, and a value. The proxy attaches it to every request to that service, whatever credential type the service uses.
<Frame>
<img src="/images/platform/agent-vault/service-advanced-options.png" alt="The Credential step with an API version custom header and a substitution that swaps the agent's placeholder for the real token, matched in the header" />
</Frame>
-A custom header can't reuse the credential's own header name, because the credential would win and the custom header would do nothing. Infisical rejects the save. Headers the proxy sets itself, such as `Host`, `Content-Length`, and `Connection`, are rejected for the same reason.
+Infisical won't save a custom header with the same name as the credential's header, because the proxy would overwrite it with the credential. Infisical also won't save a custom header that the proxy sets itself, such as `Host`, `Content-Length`, or `Connection`.
-A header value can carry a substitution placeholder, which the proxy resolves before it goes out, so one substitution can stand in for a value reused across several headers.
+<Tip>
+A custom header's value can include a [substitution](#substitutions) placeholder. If that substitution has **Headers** selected under **Replace In**, the proxy replaces the placeholder with the real value, so several headers can reuse one secret.
+</Tip>
## Substitutions
-When an agent already sends a fake value, a substitution swaps it for the real one on the way out. It works with any credential type, including pass-through, which is what makes a host reachable without attaching a credential of its own.
-
-On the **Credential** step, under **Advanced Options**, give the placeholder your agent sends and the real value, then use **Replace In** to select the parts of the request where you want it replaced: the URL path, the query string, the headers, or the body.
+Instead of attaching headers to an agent's request, you can configure your service to use substitution instead.
-For example, an agent configured with `__GITHUB_PAT__` as its GitHub token sends:
+With a substitution, you give the agent a placeholder instead of the real credential, such as a fake API token. The agent sends the placeholder in its requests, and the proxy replaces it with the real value before forwarding each request. For example, if you set the agent's GitHub token to `__GITHUB_PAT__`, the agent sends:
```text
Authorization: Bearer __GITHUB_PAT__
@@ -190,8 +207,38 @@ Authorization: Bearer __GITHUB_PAT__
GitHub receives the real token, and the agent never holds it.
-The swap is a plain find-and-replace, so pick a placeholder distinctive enough that it can't appear anywhere else in the request.
+We recommend using substitutions when your agent's tool won't run without a token of its own, or when the API expects the credential outside a header, such as in the URL path or the query string.
+
+<Info>
+Substitutions work with every credential type, including pass-through.
+</Info>
+
+### Add a substitution
+
+<Steps>
+ <Step>
+ On the **Credential** step, expand **Advanced Options** and select **Add Substitution**.
+ </Step>
+ <Step>
+ Enter the placeholder your agent sends in **Replace**, and the real value in **With**.
+
+ <Tip>
+ The proxy replaces every occurrence of the placeholder, so pick one that won't appear anywhere else in the request.
+ </Tip>
+ </Step>
+ <Step>
+ Under **Replace In**, select where the proxy looks for the placeholder: **URL Path**, **Query String**, **Headers**, or **Body**.
+ </Step>
+ <Step>
+ In the agent's environment or configuration, set the credential to the placeholder, such as `GITHUB_TOKEN=__GITHUB_PAT__`. Infisical doesn't set the placeholder for you.
+
+ <Tip>
+ Some tools check a token's format before they send it. If the agent's tool does, make the placeholder match the format of the real key, such as `ghp_` followed by 36 characters for a GitHub token.
+ </Tip>
+ </Step>
+</Steps>
-A value containing a `/` stays inside one path segment rather than adding another, so a GitLab project reaches the API as `group%2Fproject` and a path prefix still accepts it.
+### Encoding and body limits
-The proxy doesn't rewrite a body over 10 MB, or one sent compressed with `Content-Encoding`. The placeholder goes out unchanged, and the proxy logs a warning naming the service.
+- **Slashes in the URL path:** The proxy sends a `/` in the real value as `%2F`, so a GitLab project like `group/project` stays one path segment and still passes the service's [path prefixes](#paths)
+- **Large or compressed bodies:** The proxy doesn't replace placeholders in a body larger than 10 MB or compressed with `Content-Encoding` (it forwards the body unchanged and logs a warning that names the service)
diff --git a/docs/documentation/platform/agent-vault/sessions.mdx b/docs/documentation/platform/agent-vault/sessions.mdx
index de4c812bda..0343944bf8 100644
--- a/docs/documentation/platform/agent-vault/sessions.mdx
+++ b/docs/documentation/platform/agent-vault/sessions.mdx
@@ -5,7 +5,7 @@ description: "Time-bound grants that let AI agents access services without holdi
A session is a time-bound grant scoped to one [access bundle](/documentation/platform/agent-vault/access-bundles). Infisical returns a session token that identifies the session, and the agent uses that token to authenticate to the [proxy](/documentation/platform/agent-vault/proxies) on every outbound request. The proxy then attaches the real credential from the matching [service](/documentation/platform/agent-vault/services) at the network boundary.
-Every session is scoped to one access bundle and expires on a schedule you set. When the session expires (or [you revoke it](#revoke-a-session)), the proxy stops attaching credentials to the agent's requests within one poll interval.
+Every session is scoped to one access bundle and expires on a schedule you set. When the session expires (or [you revoke it](#revoke-a-session)), the proxy stops attaching credentials to the agent's requests within one [poll interval](/documentation/platform/agent-vault/proxies#poll-interval).
## Create a session
@@ -56,7 +56,7 @@ Anyone granted at least one access bundle can create a session. Admins can creat
## Revoke a session
-To revoke a session before it expires, go to the **Sessions** page, open the session's menu, and select **Revoke Session**. The proxy stops applying credentials for it on its next poll.
+To revoke a session before it expires, go to the **Sessions** page, open the session's menu, and select **Revoke Session**. The proxy stops attaching credentials for the session within one [poll interval](/documentation/platform/agent-vault/proxies#poll-interval).
The **Sessions** page shows each session as **Active**, **Revoked**, or **Expired**, and keeps expired and revoked sessions for 30 days so you can audit what an agent had access to during the session:
@@ -66,14 +66,15 @@ The **Sessions** page shows each session as **Active**, **Revoked**, or **Expire
## Access changes
-The access bundle is chosen when you create the session and can't be changed afterwards. However, the proxy re-checks whether the agent still gets credentials on every poll (60 seconds by default). Here are a few situations where a session's access might be revoked:
+The access bundle is chosen when you create the session and can't be changed afterwards. However, the proxy re-checks whether the agent still gets credentials once every [poll interval](/documentation/platform/agent-vault/proxies#poll-interval) (60 seconds by default). Here's how common access changes affect a session:
-- If an access bundle is revoked from a user, group, or machine identity, every session they created with that bundle stops getting credentials
-- If an access bundle is deleted, every session scoped to it stops getting credentials. The session still lists the bundle's name so you can see what it was
-- If a user is removed from Agent Vault, the proxy refuses every request on their sessions
+- If someone no longer has any grant on an access bundle, directly or through a group, their sessions for that bundle stop getting credentials
+- If someone still has another grant on the bundle, such as through a group, revoking one grant doesn't affect their sessions
+- If you delete an access bundle, every session scoped to it stops getting credentials (the session still lists the bundle's name, so you can see what it was)
+- If you remove someone from Agent Vault, the proxy refuses every request on their sessions
<Note>
-In the first two cases, the agent's requests still go out. However, whether they reach the upstream host depends on the proxy's [traffic policy](/documentation/platform/agent-vault/proxies#traffic-policy).
+If a session stops getting credentials because of a lost grant or a deleted bundle, the proxy still forwards the agent's requests, without credentials. Whether those requests reach the upstream host depends on the proxy's [traffic policy](/documentation/platform/agent-vault/proxies#traffic-policy).
</Note>
## Audit trail
diff --git a/docs/snippets/agent-vault/QuickstartBody.mdx b/docs/snippets/agent-vault/QuickstartBody.mdx
index 0a7a0d652c..17c901e1eb 100644
--- a/docs/snippets/agent-vault/QuickstartBody.mdx
+++ b/docs/snippets/agent-vault/QuickstartBody.mdx
@@ -161,9 +161,9 @@ The CLI adds the proxy's certificate authority to the agent process' trusted CAs
<Accordion title="403 from the proxy">
This could be for a few reasons:
- - The session was revoked or has expired. Check the Sessions page in Infisical, and create a new one if needed.
- - Under the proxy's [strict traffic policy](/documentation/platform/agent-vault/proxies#traffic-policy), no service in the bundle covers the host you called. Add a service that does, or use a pass-through service.
- - The service covers the host, but the request uses a method or a path it doesn't allow. The message names the service and the method. Check the service's [methods and paths](/documentation/platform/agent-vault/services#methods-and-paths).
+ - The session was revoked or has expired (check the **Sessions** page in Infisical, and create a new one if needed)
+ - Under the proxy's [strict traffic policy](/documentation/platform/agent-vault/proxies#traffic-policy), no service in the bundle covers the host you called (add a service that does, or use a pass-through service)
+ - The service covers the host, but doesn't allow the request's method or path (check the service's [methods and paths](/documentation/platform/agent-vault/services#methods-and-paths))
</Accordion>
</AccordionGroup>