Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.
TypeScript acmeagentsai-agentscertificate-managementdevsecopsenvironment-variableskubernetesopen-sourcepampkipostgresprivate-caprivileged-access-managementsecret-managementsecret-managersecretssecrets-managementsecuritysecurity-toolsvault
docs(agent-vault): audit session logs (#8387)
Adrian Kahalie309d83b23b3
diff --git a/docs/documentation/platform/agent-vault/overview.mdx b/docs/documentation/platform/agent-vault/overview.mdxindex 7e82f2a96a..95cb4363a9 100644--- a/docs/documentation/platform/agent-vault/overview.mdx+++ b/docs/documentation/platform/agent-vault/overview.mdx@@ -37,12 +37,12 @@ Infisical Agent Vault is an access layer for AI agents. It securely equips agent<Card title="Sessions" icon="monitor" href="/documentation/platform/agent-vault/sessions">Time-bound grants that let AI agents access services without holding real credentials.</Card>- <Card title="Proxies" icon="server" href="/documentation/platform/agent-vault/proxies">- Forward proxies that intercept an AI agent's requests and attach real credentials on the way out.- </Card><Card title="Session logs" icon="list" href="/documentation/platform/agent-vault/session-logs">A record of every request an AI agent makes, stored encrypted in your own Amazon S3 bucket.</Card>+ <Card title="Proxies" icon="server" href="/documentation/platform/agent-vault/proxies">+ Forward proxies that intercept an AI agent's requests and attach real credentials on the way out.+ </Card><Card title="Access control" icon="shield-half" href="/documentation/platform/agent-vault/access-control">Understand how permissions work in Agent Vault.</Card>diff --git a/docs/documentation/platform/agent-vault/session-logs.mdx b/docs/documentation/platform/agent-vault/session-logs.mdxindex 6894b39214..6d31a7d2f8 100644--- a/docs/documentation/platform/agent-vault/session-logs.mdx+++ b/docs/documentation/platform/agent-vault/session-logs.mdx@@ -3,91 +3,147 @@ title: "Session logs"description: "Keep an encrypted record of every request an AI agent makes, stored in your own Amazon S3 bucket."---+import SelfHostedInstance from "/snippets/app-connections/aws/self-hosted-instance.mdx";+import CreateIamRole from "/snippets/app-connections/aws/create-iam-role.mdx";+import AgentVaultSessionLogsCorsRule from "/snippets/app-connections/aws/agent-vault-session-logs-cors-rule.mdx";+<Info>Session logs are a paid feature.If you're using Infisical Cloud, they're available under the **Enterprise Tier**. If you're self-hosting Infisical, contact [email protected] to purchase an enterprise license to use them.</Info>-A session log is the per-request record of what an agent actually did: the method, host, path, status, and whether a credential went out with it. Every request that reaches a proxy is recorded, including requests to hosts that no access bundle covers.+A session log is a record of every request an agent makes during a [session](/documentation/platform/agent-vault/sessions): the method, host, path, status code, and whether the proxy attached a credential. The [proxy](/documentation/platform/agent-vault/proxies) adds every request it receives to the session log, including requests to hosts that no [access bundle](/documentation/platform/agent-vault/access-bundles) covers.-Records are encrypted before they leave the proxy and stored in an Amazon S3 bucket you own.+The proxy encrypts the records before they leave your network and uploads them to an Amazon S3 bucket you own.## Setting up session logs-Go to **Settings** under Agent Vault and select **Set Up Session Logs** on the **Session Logs** card:+You'll switch between Infisical and AWS during setup. Infisical generates the AWS policy and CORS rule for your bucket, you add them in AWS, and then you finish in Infisical.-1. Turn on **Enable**.-2. Pick the **AWS Connection** whose credentials write the records. It can be one from your organization or one created in Agent Vault, or select **Create New Connection** to add one.-3. Enter the **Bucket** and **Region** of an S3 bucket you've already created.-4. Optionally set a **Key Prefix**, so session logs sit under one path in a bucket you use for other things.-5. Select **Save**.+### Prerequisites-<Frame>- <img src="/images/platform/agent-vault/session-logs-setup.png" alt="The Session Logs dialog with Enable turned on and an AWS connection, region, bucket, and key prefix filled in" />-</Frame>+- The [Admin role](/documentation/platform/agent-vault/access-control) in Agent Vault+- An [Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) to store the records in+- Permission in AWS to edit the bucket's CORS configuration, create IAM roles, and attach policies to them-When you save, Infisical checks that the bucket exists and that it can write to it.+### Step 1: Start in Infisical-The connection needs an IAM policy and the bucket needs a CORS rule. Select **View AWS Setup** in the **Session Logs** dialog to see both.+<Steps>+ <Step>+ In Agent Vault, go to **Administration** > **Settings** and select **Set Up Session Logs**.+ </Step>+ <Step>+ Enter the **Region** and **Bucket** of your S3 bucket.+ </Step>+ <Step>+ Optionally, enter a **Key Prefix** to store session logs under one path in a bucket you also use for other data.+ </Step>+ <Step>+ Select **View AWS Setup**. Infisical shows an **IAM policy** with your bucket and key prefix already filled in, so you can paste it into AWS as it is.+ </Step>+</Steps>-<Tabs>- <Tab title="IAM policy">- Attach this identity policy (not a bucket policy) to the user or role the connection authenticates as:+Leave the **Session Logs** dialog open, and open AWS in another browser tab.- ```json- {- "Version": "2012-10-17",- "Statement": [- {- "Effect": "Allow",- "Action": ["s3:PutObject", "s3:GetObject"],- "Resource": "arn:aws:s3:::<bucket>/<prefix>/*"- },- {- "Effect": "Allow",- "Action": ["s3:ListBucket"],- "Resource": "arn:aws:s3:::<bucket>"- }- ]- }- ```- </Tab>- <Tab title="CORS rule">- Add this CORS rule to the bucket, because your browser is what fetches the records:+### Step 2: Add a CORS rule to the bucket- ```json- [- {- "AllowedHeaders": ["*"],- "AllowedMethods": ["GET"],- "AllowedOrigins": ["https://app.infisical.com"],- "MaxAgeSeconds": 3000- }- ]- ```+Your browser downloads session logs directly from your bucket, so the bucket has to accept requests from Infisical. Add a CORS rule for Infisical to the bucket.- If you're on EU Cloud or a self-hosted instance, replace `https://app.infisical.com` with `https://eu.infisical.com` or your instance's URL.- </Tab>-</Tabs>+<Steps>+ <AgentVaultSessionLogsCorsRule />+</Steps>-## Viewing session logs+### Step 3: Create an IAM role for Infisical++Infisical assumes this role to write session logs to the bucket.++<Note>+ If you already have an AWS app connection you want to use, skip to [Step 4](#step-4-attach-the-iam-policy).+</Note>++<SelfHostedInstance />++<Steps>+ <CreateIamRole externalId="organization" />+</Steps>++### Step 4: Attach the IAM policy++Attach the **IAM policy** from [Step 1](#step-1-start-in-infisical) to the IAM role, or to the role or user your existing connection signs in as.++<Steps>+ <Step>+ In the IAM console, open the role or user. On the **Permissions** tab, select **Add permissions** > **Create inline policy**, switch to the **JSON** editor, and paste the policy.+ </Step>+ <Step>+ Select **Next**, enter a **Policy name**, then select **Create policy**.+ </Step>+ <Step>+ If you created a new role in Step 3, copy its **ARN** from the **Summary** section.-Go to **Sessions** and select **View Session Logs** on the session's row. You can filter and search the requests, and while the session is active, new logs keep appearing.+ + </Step>+</Steps>++### Step 5: Finish in Infisical++Go back to the **Session Logs** dialog.++<Steps>+ <Step>+ Under **AWS Connection**, select **Create New Connection**.++ <Note>+ If you already have an AWS app connection you want to use, select it here instead. Then, select **Save** and skip the remaining steps.+ </Note>+ </Step>+ <Step>+ Enter a **Name**, keep the **Assume Role (Recommended)** method, paste the role's ARN into **Role ARN**, and select **Connect to AWS**. Infisical creates the connection in Agent Vault and selects it.+ </Step>+ <Step>+ Select **Save**.+ </Step>+</Steps><Frame>- <img src="/images/platform/agent-vault/session-logs-view.png" alt="The Session Logs sheet for an active session, listing each request's time, method, host, path, upstream status, and outcome" />+ <img src="/images/platform/agent-vault/session-logs-setup.png" alt="The Session Logs dialog with Enable turned on and an AWS connection, region, bucket, and key prefix filled in" /></Frame>-<Accordion title="Reading session logs through the API" id="reading-session-logs-through-the-api">- The API returns a session's logs as chunks. A chunk is one encrypted batch of [records](#what-gets-recorded) that a proxy uploaded to your bucket. You can read a session's logs if you created the session or you're an Agent Vault admin.+When you save, Infisical checks that the bucket exists and that the IAM user or role can write to it. If either check fails, Infisical shows the error and doesn't save the settings. If your browser can't read from the bucket, the **Session Logs** card shows a warning after you save.++<Check>+ You've successfully set up session logs within Agent Vault.+</Check>++## Viewing session logs++You can view a session's logs if you created the session or you're an Agent Vault admin.++<Tabs>+<Tab title="In Infisical">+ Go to **Sessions** and select **View Session Logs** on the session's row. You can filter and search the requests, and while the session is active, new requests appear as the proxy uploads them.++ <Frame>+ <img src="/images/platform/agent-vault/session-logs-view.png" alt="The Session Logs sheet for an active session, listing each request's time, method, host, path, upstream status, and outcome" />+ </Frame>+</Tab>+<Tab title="Through the API" id="reading-session-logs-through-the-api">+ The API returns a session's logs as chunks. A chunk is one encrypted batch of [records](#what-gets-recorded) that a proxy uploaded to your bucket.<Steps><Step>Call [the endpoint that lists session logs](/api-reference/endpoints/agent-vault-session-logs/list). It returns the newest chunks first. To get older chunks, call it again with the response's `nextCursor` as `cursor`.</Step><Step>- Download each chunk from its `presignedGetUrl` within 5 minutes, before the URL expires. If `presignedGetUrl` is null, either the chunk is in a bucket other than the current one, or `sessionLogs.storageUnavailable` says why the chunk can't be downloaded right now.+ Download each chunk from its `presignedGetUrl` within 5 minutes, before the URL expires.++ <Note>+ If `presignedGetUrl` is null, it could be for either of the following two reasons:++ - The chunk is in a bucket that session logs no longer use+ - Storage is unavailable. Read `sessionLogs.storageUnavailable` to find the reason why+ </Note></Step><Step>Check that the SHA-256 digest of the downloaded bytes, as base64 without padding, matches `ciphertextSha256`. If the digests differ, the chunk was changed after the proxy uploaded it.@@ -102,7 +158,7 @@ Go to **Sessions** and select **View Session Logs** on the session's row. You ca{"ts": "2026-09-16T10:31:04.221Z","seq": 8412,- "proxyId": "7c1e…",+ "proxyId": "<proxy-id>","method": "POST","host": "api.github.com","port": "443",@@ -118,7 +174,7 @@ Go to **Sessions** and select **View Session Logs** on the session's row. You caThis Node.js script reads the newest page of a session's logs:- ```javascript+ ```javascript expandableimport { createDecipheriv, createHash } from "node:crypto";const token = "<your-access-token>";@@ -150,10 +206,13 @@ Go to **Sessions** and select **View Session Logs** on the session's row. You ca}```+ <Note>The script runs outside a browser, so the bucket's CORS rule doesn't apply to it.+ </Note>To receive new logs as they arrive, pass the response's `liveCursor` as `cursor` to [the endpoint that tails session logs](/api-reference/endpoints/agent-vault-session-logs/tail), then keep calling it with each response's `nextCursor`. If `hasMore` is true, call again right away. Otherwise, wait a few seconds before the next call. The same chunk can appear in more than one response, so skip any `chunkId` you've already read.-</Accordion>+</Tab>+</Tabs>## What gets recorded@@ -162,9 +221,9 @@ Each request produces one record with:| Field | What it holds || --- | --- || **Time** | When the request was made |-| **Proxy** | The proxy that handled it |+| **Proxy** | The proxy that handled the request || **Method**, **Host**, **Path** | Where the request went, for example `POST api.github.com/repos/acme/web/issues` |-| **Upstream status** | The HTTP status code the API returned, such as `201`. For **Blocked** and **Error** requests, it's the status code Agent Vault returned itself, such as `403` or `502` |+| **Upstream status** | The HTTP status code the API returned, such as `201`. For **Blocked** and **Error** requests, it's the status code the proxy returned, such as `403` or `502` || **Outcome** | What the proxy did with the request || **Service** | The service that matched the request, if any |@@ -172,10 +231,10 @@ The outcome is one of four:| Outcome | What happened || --- | --- |-| **Brokered** | A service matched and its credential went out with the request |-| **Passthrough** | No service matched, or the one that did carries no credential. The request went out untouched |-| **Blocked** | The traffic policy refused the request |-| **Error** | The proxy couldn't reach the upstream |+| **Brokered** | A service matched and the proxy attached its credential to the request |+| **Passthrough** | No service matched, or the matching service has no credential. The proxy forwarded the request without a credential |+| **Blocked** | The proxy refused the request, for one of the reasons in [Blocked requests](/documentation/platform/agent-vault/proxies#blocked-requests) |+| **Error** | The proxy couldn't reach the destination host |Request and response bodies, headers, and query strings aren't recorded.@@ -183,9 +242,9 @@ Request and response bodies, headers, and query strings aren't recorded.### Connections-Session logs use one AWS connection at a time, which you pick in the **Session Logs** dialog. It can be one created in Agent Vault or one your organization already has under **Integrations**. See [AWS connection](/integrations/app-connections/aws) for how to create one.+Session logs use one AWS connection at a time, which you select in the **Session Logs** dialog.-To update its AWS credentials, open the menu next to **Configure** on the **Session Logs** card and select **Edit AWS Credentials**. For an organization connection, update the credentials under **Integrations** instead.+To update the connection's AWS credentials, open the menu next to **Configure** on the **Session Logs** card and select **Edit AWS Credentials**. If the connection belongs to your organization, update its credentials under **Integrations** in your organization instead.To add or delete Agent Vault's AWS connections, select **Manage Connections** from the same menu:@@ -193,18 +252,58 @@ To add or delete Agent Vault's AWS connections, select **Manage Connections** fr<img src="/images/platform/agent-vault/session-logs-connections.png" alt="The Manage Connections sheet listing Agent Vault's AWS connections, with the one session logs use marked In Use" /></Frame>-You can't delete the connection session logs are using. Pick a different one in the **Session Logs** dialog first.+You can't delete a connection while session logs use it. To delete the connection, select a different one in the **Session Logs** dialog first.### Changing the bucket or prefix-Changing the bucket copies nothing, so everything recorded before the change can't be read in Infisical until you switch back to that bucket.+Infisical doesn't copy existing records when you change the bucket. You can't view the records in the old bucket in Infisical until you switch back to that bucket.++If you change only the key prefix, earlier records stay readable as long as the IAM role or user can still read the old prefix. The policy you [attached during setup](#step-4-attach-the-iam-policy) covers only the prefix you entered then, so add the new prefix to it instead of replacing it:++<Steps>+ <Step>+ In the **Session Logs** dialog, enter the new **Key Prefix** and select **View AWS Setup**.+ </Step>+ <Step>+ In the policy it shows, copy the object ARN from the first statement's `Resource`, the one that ends in `/*`.+ </Step>+ <Step>+ In the IAM console, open the inline policy you attached during setup. Turn the first statement's `Resource` into a list that holds both ARNs:++ ```json highlight={7-10}+ {+ "Version": "2012-10-17",+ "Statement": [+ {+ "Effect": "Allow",+ "Action": ["s3:PutObject", "s3:GetObject"],+ "Resource": [+ "arn:aws:s3:::<bucket>/<old-prefix>/*",+ "arn:aws:s3:::<bucket>/<new-prefix>/*"+ ]+ },+ {+ "Effect": "Allow",+ "Action": ["s3:ListBucket"],+ "Resource": "arn:aws:s3:::<bucket>"+ }+ ]+ }+ ```-Changing only the key prefix keeps earlier records readable, as long as the AWS connection can still read the old prefix. The [IAM policy](#setting-up-session-logs) on this page covers only the current prefix.+ Then, save the policy.+ </Step>+ <Step>+ In the **Session Logs** dialog, select **Save**.+ </Step>+</Steps>### Retention-Infisical never deletes sessions or their session logs. To delete older logs automatically, add a lifecycle rule to the bucket in AWS.+Infisical never deletes sessions or their session logs. To delete older logs automatically, add an [S3 Lifecycle rule](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lifecycle-mgmt.html) to the bucket.## Troubleshooting-If a session shows no session logs when you expect some, check the logs of each proxy the agent used.+If a proxy couldn't upload some records, the session's logs show a row that says how many requests are missing. Those requests still reached their destination, but they aren't in the session log. To find out why the upload failed, check the output of each proxy the agent used.++If the AWS connection returns an error or session logs reach their storage limit, a red dot appears next to **Settings** in the Agent Vault sidebar, and the **Settings** page shows the error.diff --git a/docs/documentation/platform/agent-vault/sessions.mdx b/docs/documentation/platform/agent-vault/sessions.mdxindex bfb39aef82..a6aa5c54df 100644--- a/docs/documentation/platform/agent-vault/sessions.mdx+++ b/docs/documentation/platform/agent-vault/sessions.mdx@@ -89,4 +89,4 @@ If a session stops getting credentials because of a lost grant or a deleted bundWhen you create or revoke a session, Infisical writes an audit event. To review these events, open **Audit Logs** in Agent Vault, or scope an [audit log stream](/documentation/platform/audit-log-streams/audit-log-streams) to the Agent Vault product.-Audit events cover what you changed in Infisical. To see what an agent reached while its session was running, [view its session logs](#view-session-logs).+Audit events cover what you changed in Infisical. To see which requests an agent made while its session was running, [view its session logs](#view-session-logs).diff --git a/docs/integrations/app-connections/aws.mdx b/docs/integrations/app-connections/aws.mdxindex ab6a89d646..b90413b10a 100644--- a/docs/integrations/app-connections/aws.mdx+++ b/docs/integrations/app-connections/aws.mdx@@ -11,6 +11,7 @@ import SelfHostedInstance from "/snippets/app-connections/aws/self-hosted-instanimport CreateIamRole from "/snippets/app-connections/aws/create-iam-role.mdx";import CreateIamUser from "/snippets/app-connections/aws/create-iam-user.mdx";import ConnectionFormFields from "/snippets/app-connections/aws/form-fields.mdx";+import AgentVaultSessionLogsCorsRule from "/snippets/app-connections/aws/agent-vault-session-logs-cors-rule.mdx";<UseCasePicker prefix="I want the connection to work with" groups={awsUseCaseGroups} />@@ -135,7 +136,7 @@ Next, add the required policies to the IAM role or user from [Step 1](#step-1-crIn the Amazon S3 console, open the recording bucket, go to **Permissions**, and select **Edit** under **Cross-origin resource sharing (CORS)**.</Step><Step>- Paste this rule, then select **Save changes**:+ Paste this rule, then select **Save changes**. If the bucket already has CORS rules, add this rule's object to the existing array instead of replacing it, so other applications that use the bucket keep working:<CodeGroup>```json Infisical Cloud (US)@@ -174,38 +175,7 @@ Next, add the required policies to the IAM role or user from [Step 1](#step-1-crYour browser downloads session logs directly from the bucket, so the bucket needs a CORS rule. To see the same rule with your Infisical URL filled in, select **View AWS Setup** in the **Session Logs** dialog.<Steps>- <Step>- In the Amazon S3 console, open the session logs bucket, go to **Permissions**, and select **Edit** under **Cross-origin resource sharing (CORS)**.- </Step>- <Step>- Paste this rule, then select **Save changes**:-- <CodeGroup>- ```json Infisical Cloud (US)- [- {- "AllowedHeaders": ["*"],- "AllowedMethods": ["GET"],- "AllowedOrigins": ["https://app.infisical.com"],- "MaxAgeSeconds": 3000- }- ]- ```-- ```json Infisical Cloud (EU)- [- {- "AllowedHeaders": ["*"],- "AllowedMethods": ["GET"],- "AllowedOrigins": ["https://eu.infisical.com"],- "MaxAgeSeconds": 3000- }- ]- ```- </CodeGroup>-- If you self-host Infisical or use a dedicated instance, replace `AllowedOrigins` with your instance's URL.- </Step>+ <AgentVaultSessionLogsCorsRule /></Steps></UseCase>diff --git a/docs/snippets/app-connections/aws/agent-vault-session-logs-cors-rule.mdx b/docs/snippets/app-connections/aws/agent-vault-session-logs-cors-rule.mdxnew file mode 100644index 0000000000..9dcb253771--- /dev/null+++ b/docs/snippets/app-connections/aws/agent-vault-session-logs-cors-rule.mdx@@ -0,0 +1,39 @@+{/*+Bare <Step> elements for adding Agent Vault's session logs CORS rule to the bucket, so a page can+place them inside its own <Steps>. Used by integrations/app-connections/aws.mdx and+documentation/platform/agent-vault/session-logs.mdx. The rule matches what the Session Logs+dialog's View AWS Setup generates (AwsSetupDialog.tsx).+*/}++<Step>+ In the Amazon S3 console, open the session logs bucket, go to **Permissions**, and select **Edit** under **Cross-origin resource sharing (CORS)**.+</Step>+<Step>+ Paste this rule, then select **Save changes**. If the bucket already has CORS rules, add this rule's object to the existing array instead of replacing it, so other applications that use the bucket keep working:++ <CodeGroup>+ ```json Infisical Cloud (US)+ [+ {+ "AllowedHeaders": ["*"],+ "AllowedMethods": ["GET"],+ "AllowedOrigins": ["https://app.infisical.com"],+ "MaxAgeSeconds": 3000+ }+ ]+ ```++ ```json Infisical Cloud (EU)+ [+ {+ "AllowedHeaders": ["*"],+ "AllowedMethods": ["GET"],+ "AllowedOrigins": ["https://eu.infisical.com"],+ "MaxAgeSeconds": 3000+ }+ ]+ ```+ </CodeGroup>++ If you self-host Infisical or use a dedicated instance, replace `AllowedOrigins` with your instance's URL.+</Step>diff --git a/docs/snippets/app-connections/aws/create-iam-role.mdx b/docs/snippets/app-connections/aws/create-iam-role.mdxindex 073da7b2ad..f64250a8a6 100644--- a/docs/snippets/app-connections/aws/create-iam-role.mdx+++ b/docs/snippets/app-connections/aws/create-iam-role.mdx@@ -1,8 +1,10 @@{/*Bare <Step> elements, so a page can place them inside its own <Steps> and keep the numbering.Props:-- externalId: "required" adds the External ID instructions. "skip" leaves them out, for a page- whose connection sends an External ID the reader can't look up.+- externalId: "required" adds the External ID instructions, split by the page's+ Organization-level and Project-level views. "organization" adds a single instruction to use the+ Organization ID, for a page whose connection always sends it (Agent Vault) and that has no views.+ "skip" leaves them out.*/}<Step>@@ -39,6 +41,12 @@ Props:Infisical sends this ID every time it assumes the role, so the role only works for connections in the organization or project you named. This protects your account from the [confused deputy problem](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html).</MDX>)}++ {externalId === "organization" && (+ <MDX>+ Enable **Require external ID** and enter your Organization ID. You can copy it from your Infisical URL: it's the ID after `/organizations/`.+ </MDX>+ )}</Step><Step>Select **Next** to go to the **Add permissions** page. Then, select **Next** again without choosing a policy. You'll add the permissions as an inline policy after the role exists.