From 91e7d2dd33bc958ff7446e0030287d506c3efe68 Mon Sep 17 00:00:00 2001 From: Brian Refsdal Date: Tue, 25 Aug 2026 10:43:16 -0700 Subject: [PATCH] docs: add AI Governance Audit Logs API --- .../ai/sandboxes/governance/audit/_index.md | 1 + .../ai/sandboxes/governance/audit/api.md | 150 +++++++ .../api/ai-governance-audit-logs/api.yaml | 370 ++++++++++++++++++ .../api/ai-governance-audit-logs/index.md | 7 + 4 files changed, 528 insertions(+) create mode 100644 content/manuals/ai/sandboxes/governance/audit/api.md create mode 100644 content/reference/api/ai-governance-audit-logs/api.yaml create mode 100644 content/reference/api/ai-governance-audit-logs/index.md diff --git a/content/manuals/ai/sandboxes/governance/audit/_index.md b/content/manuals/ai/sandboxes/governance/audit/_index.md index 35ac8c59b7da..360913824fe0 100644 --- a/content/manuals/ai/sandboxes/governance/audit/_index.md +++ b/content/manuals/ai/sandboxes/governance/audit/_index.md @@ -80,4 +80,5 @@ Policy](https://www.docker.com/legal/privacy/). - [Configure audit delivery](configure.md) - [View and export audit events](view-export.md) - [SIEM forwarding](siem.md) +- [Retrieve audit events with the API](api.md) - [Audit record reference](record-reference.md) diff --git a/content/manuals/ai/sandboxes/governance/audit/api.md b/content/manuals/ai/sandboxes/governance/audit/api.md new file mode 100644 index 000000000000..7812d524cbd4 --- /dev/null +++ b/content/manuals/ai/sandboxes/governance/audit/api.md @@ -0,0 +1,150 @@ +--- +title: Retrieve audit events with the API +linkTitle: Audit Logs API +weight: 45 +description: Retrieve and filter Docker AI Governance audit events with the Audit Logs API. +keywords: docker sandboxes, AI Governance, audit logs API, audit events, organization access token, OAT +--- + +{{< summary-bar feature_name="AI Governance Audit Logs" >}} + +The Audit Logs API retrieves cloud-delivered Docker AI Governance events for +automation, investigation, and reporting. The API returns the same event data +shown in the hosted audit log view. + +## Prerequisites + +Before you use the API, you need: + +- A Docker [AI Governance plan](/manuals/subscription/plans/ai-governance.md) +- Docker Cloud delivery turned on in [audit delivery settings](configure.md) +- An Organization Access Token (OAT) with the **View audit logs** permission + +Personal Access Tokens and Docker account session tokens aren't supported. + +## Create an access token + +Create an OAT for the organization whose events you want to retrieve: + +1. Sign in to [Docker Home](https://app.docker.com/) and select your + organization. +1. Select **Identity & auth**, then **Access tokens**. +1. Select **Generate access token**. +1. Under the AI Governance organization permissions, select **View audit + logs**. +1. Select **Generate token**, then store the token in a credential manager. + +For token expiration, rotation, and management instructions, see +[Organization access tokens](/manuals/enterprise/security/access-tokens.md). + +Set variables for the examples: + +```bash +ORG="" +OAT="" +``` + +Pass the raw OAT in the bearer header. Don't exchange it for another token. + +## List audit events + +Request the first 25 events for your organization: + +```console +$ curl --get "https://api.docker.com/v2/auditlogs/governance/$ORG" \ + --header "Authorization: Bearer $OAT" \ + --data-urlencode "page_size=25" | jq . +``` + +Events are returned in reverse chronological order. The response contains an +array of events and an opaque cursor for the next page: + +```json +{ + "events": [ + { + "audit_event_id": "95e7257f-93c9-4f29-bde7-88830e2dae80", + "org_id": "9f8e7d6c-5b4a-3210-fedc-ba9876543210", + "event_type": "docker.marlin.audit.event.v1.AuditRecord", + "category": "AUDIT_CATEGORY_EVALUATION", + "decision": "AUDIT_DECISION_DENY", + "action_type": "network_egress", + "enforcement_mode": "enforce", + "audit_session_id": "8a3bc076-79d0-4502-baf3-cc6ad35fb578", + "username": "jordandoe", + "created_at": "2026-08-25T18:42:31.123Z", + "ingested_at": "2026-08-25T18:42:31.456Z", + "payload": { + "resource_id": "example.com:443", + "agent": "claude", + "network_egress": { "protocol": "tcp" } + } + } + ], + "next_page_token": "eyJ0cyI6IjIwMjYtMDgtMjVUMTg6NDI6MzEuMTIzWiIsImVpZCI6Ijk1ZTcyNTdmLTkzYzktNGYyOS1iZGU3LTg4ODMwZTJkYWU4MCJ9" +} +``` + +See the [audit record reference](record-reference.md) for category, decision, +action, and payload fields. + +## Filter events + +Use query parameters to narrow the result set: + +| Parameter | Match behavior | +| --- | --- | +| `from`, `to` | Events inside an inclusive RFC 3339 time range | +| `audit_session_id` | Exact session ID | +| `username` | Exact Docker username | +| `decision` | Exact audit decision | +| `enforcement_mode` | Exact `audit`, `warn`, or `enforce` mode | +| `action_type` | Exact action type | +| `query` | Case-insensitive text search across username, action type, decision, and event type | +| `resource_id` | Case-insensitive resource ID prefix | +| `agent` | Exact agent value | + +For example, retrieve denied network events from a time range: + +```console +$ curl --get "https://api.docker.com/v2/auditlogs/governance/$ORG" \ + --header "Authorization: Bearer $OAT" \ + --data-urlencode "decision=AUDIT_DECISION_DENY" \ + --data-urlencode "action_type=network_egress" \ + --data-urlencode "from=2026-08-01T00:00:00Z" \ + --data-urlencode "to=2026-08-25T23:59:59Z" | jq . +``` + +A `query` search requires both `from` and `to`. The search term must contain at +least three characters, and the time range must not exceed 30 days. + +## Retrieve the next page + +The API returns up to 25 events by default and accepts a `page_size` up to 500. +When `next_page_token` isn't empty, pass it unchanged as `page_token`: + +```console +$ curl --get "https://api.docker.com/v2/auditlogs/governance/$ORG" \ + --header "Authorization: Bearer $OAT" \ + --data-urlencode "page_size=25" \ + --data-urlencode "page_token=$NEXT_PAGE_TOKEN" | jq . +``` + +Keep the same filters while paging through one result set. + +## Request limits + +The API applies all of the following request limits: + +- 100 requests per minute for each organization +- 600 requests per minute for each source IP address +- 1000 requests per hour for each organization + +Requests that exceed a limit receive `429 Too Many Requests` with a JSON error +response. The minute limit controls bursts, while the hourly limit controls +sustained traffic. + +## API reference + +See the [Audit Logs API reference](/reference/api/ai-governance-audit-logs/) +for the complete request and response schema. diff --git a/content/reference/api/ai-governance-audit-logs/api.yaml b/content/reference/api/ai-governance-audit-logs/api.yaml new file mode 100644 index 000000000000..eb2afe5b1d48 --- /dev/null +++ b/content/reference/api/ai-governance-audit-logs/api.yaml @@ -0,0 +1,370 @@ +openapi: "3.0.3" + +info: + title: Docker AI Governance Audit Logs API + version: "1" + description: | + Retrieve Docker AI Governance audit events for an organization. + + The API returns cloud-delivered governance records in reverse chronological + order. Use filters to investigate policy decisions, principals, resources, + sessions, and agents. Results use cursor-based pagination. + + Send an Organization Access Token (OAT) with the **View audit logs** + permission as the bearer token. Personal Access Tokens (PATs) and Docker + account session tokens aren't supported. The organization in the request + path must match the organization associated with the OAT. + + An AI Governance subscription and Docker Cloud audit delivery are required. + + Requests are limited to 100 per minute for each organization, 600 per + minute for each source IP address, and 1000 per hour for each organization. + A request must remain below every limit. + contact: + name: Docker + url: https://www.docker.com/products/ai-governance/ + +servers: + - url: https://api.docker.com + +security: + - bearerAuth: [] + +tags: + - name: audit-events + description: Retrieve Docker AI Governance audit events. + +paths: + /v2/auditlogs/governance/{org_name}: + get: + operationId: listAuditEvents + tags: [audit-events] + summary: List audit events + description: | + Returns audit events for the organization in reverse chronological + order. Pass `next_page_token` from one response as `page_token` in the + next request to continue listing events. + + When `query` is present, `from` and `to` are required and must define a + range of 30 days or less. The search term must contain at least three + characters. + parameters: + - $ref: "#/components/parameters/OrgName" + - $ref: "#/components/parameters/From" + - $ref: "#/components/parameters/To" + - $ref: "#/components/parameters/AuditSessionID" + - $ref: "#/components/parameters/Username" + - $ref: "#/components/parameters/Decision" + - $ref: "#/components/parameters/EnforcementMode" + - $ref: "#/components/parameters/ActionType" + - $ref: "#/components/parameters/Query" + - $ref: "#/components/parameters/ResourceID" + - $ref: "#/components/parameters/Agent" + - $ref: "#/components/parameters/PageSize" + - $ref: "#/components/parameters/PageToken" + responses: + "200": + description: Paginated audit events. + content: + application/json: + schema: + $ref: "#/components/schemas/ListAuditEventsResponse" + examples: + default: + value: + events: + - audit_event_id: 95e7257f-93c9-4f29-bde7-88830e2dae80 + org_id: 9f8e7d6c-5b4a-3210-fedc-ba9876543210 + event_type: docker.marlin.audit.event.v1.AuditRecord + category: AUDIT_CATEGORY_EVALUATION + decision: AUDIT_DECISION_DENY + action_type: network_egress + enforcement_mode: enforce + audit_session_id: 8a3bc076-79d0-4502-baf3-cc6ad35fb578 + username: jordandoe + created_at: "2026-08-25T18:42:31.123Z" + ingested_at: "2026-08-25T18:42:31.456Z" + payload: + resource_id: example.com:443 + agent: claude + network_egress: + protocol: tcp + next_page_token: eyJ0cyI6IjIwMjYtMDgtMjVUMTg6NDI6MzEuMTIzWiIsImVpZCI6Ijk1ZTcyNTdmLTkzYzktNGYyOS1iZGU3LTg4ODMwZTJkYWU4MCJ9 + "400": + $ref: "#/components/responses/BadRequest" + "401": + $ref: "#/components/responses/Unauthenticated" + "403": + $ref: "#/components/responses/Forbidden" + "429": + $ref: "#/components/responses/RateLimited" + "500": + $ref: "#/components/responses/InternalError" + +components: + securitySchemes: + bearerAuth: + type: http + scheme: bearer + description: | + A raw Organization Access Token with the **View audit logs** permission. + Pass the OAT in the `Authorization: Bearer ` header. Don't exchange + the OAT for a Docker account session token. PATs aren't supported. + + parameters: + OrgName: + name: org_name + in: path + required: true + description: Organization name. The value must match the organization associated with the OAT. + schema: + type: string + example: my-org + + From: + name: from + in: query + required: false + description: Include events created at or after this RFC 3339 timestamp. Required with `query`. + schema: + type: string + format: date-time + example: "2026-08-01T00:00:00Z" + + To: + name: to + in: query + required: false + description: Include events created at or before this RFC 3339 timestamp. Required with `query`. + schema: + type: string + format: date-time + example: "2026-08-25T23:59:59Z" + + AuditSessionID: + name: audit_session_id + in: query + required: false + description: Return events from this audit session. + schema: + type: string + example: 8a3bc076-79d0-4502-baf3-cc6ad35fb578 + + Username: + name: username + in: query + required: false + description: Return events associated with this Docker username. + schema: + type: string + example: jordandoe + + Decision: + name: decision + in: query + required: false + description: Return events with this exact audit decision value. + schema: + type: string + example: AUDIT_DECISION_DENY + + EnforcementMode: + name: enforcement_mode + in: query + required: false + description: Return events with this exact enforcement mode. + schema: + type: string + enum: [audit, warn, enforce] + example: enforce + + ActionType: + name: action_type + in: query + required: false + description: Return events with this exact action type. + schema: + type: string + example: network_egress + + Query: + name: query + in: query + required: false + description: | + Case-insensitive text search across username, action type, decision, and + event type. `from` and `to` are required when this parameter is present, + and their range must not exceed 30 days. + schema: + type: string + minLength: 3 + maxLength: 256 + example: network + + ResourceID: + name: resource_id + in: query + required: false + description: Case-insensitive prefix match against the resource ID in the event payload. + schema: + type: string + maxLength: 256 + example: example.com + + Agent: + name: agent + in: query + required: false + description: Exact match against the agent in the event payload. + schema: + type: string + maxLength: 256 + example: claude + + PageSize: + name: page_size + in: query + required: false + description: Number of events to return. Defaults to 25 and is capped at 500. + schema: + type: integer + format: int32 + minimum: 1 + maximum: 500 + default: 25 + example: 25 + + PageToken: + name: page_token + in: query + required: false + description: Opaque cursor from `next_page_token` in the previous response. + schema: + type: string + + schemas: + ListAuditEventsResponse: + type: object + required: [events, next_page_token] + properties: + events: + type: array + items: + $ref: "#/components/schemas/AuditEvent" + next_page_token: + type: string + description: Opaque cursor for the next page. Empty when no more events remain. + + AuditEvent: + type: object + required: [audit_event_id, org_id, event_type] + properties: + audit_event_id: + type: string + format: uuid + description: Unique audit event ID. + org_id: + type: string + format: uuid + description: ID of the organization that owns the event. + event_type: + type: string + description: Fully qualified event schema name. + category: + type: string + description: Audit event category. + example: AUDIT_CATEGORY_EVALUATION + decision: + type: string + description: Governance decision for evaluation records. + example: AUDIT_DECISION_DENY + action_type: + type: string + description: Action-specific payload discriminator. + example: network_egress + enforcement_mode: + type: string + description: Enforcement mode in effect for the decision. + example: enforce + audit_session_id: + type: string + description: Session that produced the event. + username: + type: string + description: Docker username associated with the event. + created_at: + type: string + format: date-time + description: Time Docker recorded the event. + ingested_at: + type: string + format: date-time + description: Time Docker ingested the event into cloud storage. + payload: + type: object + description: Event-specific audit record fields. + additionalProperties: true + + Error: + type: object + required: [error] + properties: + error: + type: string + description: Human-readable error message. + + responses: + BadRequest: + description: Invalid timestamp, page size, page token, filter, or search window. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + default: + value: + error: "invalid argument\nfrom must be RFC3339" + + Unauthenticated: + description: Missing, malformed, invalid, or expired OAT. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + default: + value: + error: invalid or expired token + + Forbidden: + description: The OAT lacks permission, lacks organization identity, or belongs to another organization. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + default: + value: + error: insufficient permissions + + RateLimited: + description: The organization or source IP address exceeded a request limit. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + default: + value: + error: rate limit exceeded + + InternalError: + description: Unexpected server error. + content: + application/json: + schema: + $ref: "#/components/schemas/Error" + examples: + default: + value: + error: internal error diff --git a/content/reference/api/ai-governance-audit-logs/index.md b/content/reference/api/ai-governance-audit-logs/index.md new file mode 100644 index 000000000000..b3e085e64dfe --- /dev/null +++ b/content/reference/api/ai-governance-audit-logs/index.md @@ -0,0 +1,7 @@ +--- +layout: api-reference +title: Docker AI Governance Audit Logs API +linkTitle: Audit Logs API +description: HTTP API reference for retrieving Docker AI Governance audit events programmatically. +keywords: docker sandboxes, AI Governance, audit logs API, audit events, REST API, openapi +---