Skip to content

Commit e417d63

Browse files
angelampcostaRebeccaTamachiro
angelampcosta
and
RebeccaTamachiro
authored
[Fundamentals ] Audit Logs (#23784)
* Audit Logs * Updates after review. * Updates after review * Apply suggestions from code review Co-authored-by: Rebecca Tamachiro <[email protected]> --------- Co-authored-by: Rebecca Tamachiro <[email protected]>
1 parent 9503cd4 commit e417d63

File tree

6 files changed

+240
-5
lines changed

6 files changed

+240
-5
lines changed

‎src/content/docs/fundamentals/account/account-security/abuse-contact.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
---
22
pcx_content_type: how-to
33
title: Add abuse contact
4-
4+
sidebar:
5+
order: 1
56
---
67

78
Enter an abuse contact email address to ensure you are receiving communications regarding potential abuse on your websites.

‎src/content/docs/fundamentals/account/account-security/audit-logs.mdx‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
---
2+
pcx_content_type: reference
3+
title: Audit Logs - version 2 (beta)
4+
sidebar:
5+
order: 6
6+
label: Audit Logs - v2
7+
badge:
8+
text: Beta
9+
10+
---
11+
12+
import { APIRequest } from "~/components"
13+
14+
Cloudflare Audit Logs are account-based. All user-initiated actions are recorded automatically across both the Cloudflare API and dashboard. System-initiated logs are also captured to reflect actions taken automatically by Cloudflare systems, such as configuration updates, background processes, or internal policy enforcement.
15+
16+
When a user-initiated action triggers additional automated behavior, corresponding system-initiated logs may be generated. In some cases, these system-initiated logs include additional enrichments that provide more context about what was changed, offering deeper visibility into the full lifecycle of the action.
17+
18+
When an action occurs, it is streamed through Cloudflare's audit logging pipeline and stored. This ensures consistent visibility into activity across all products.
19+
20+
For more detailed information about how the user-initiated actions are logged automatically, refer to the [Cloudflare Blog](https://blog.cloudflare.com/introducing-automatic-audit-logs/).
21+
22+
:::note
23+
A transition plan from Audit Logs v1 to Audit Logs v2 will be communicated in due course.
24+
:::
25+
26+
## Key features
27+
28+
Audit Logs (version 2) provide a unified and standardized system for tracking and recording actions across Cloudflare products. This system enhances transparency and accountability by offering comprehensive insights into user-initiated and system-initiated activities within your Cloudflare environment.
29+
30+
- **Standardized logging**: Audit logs are automatically generated in a consistent format across all Cloudflare services, ensuring uniformity and eliminating inconsistencies.
31+
- **Expanded product coverage**: Audit Logs covers 111 products, capturing actions from key endpoints, such as `/accounts`, `/zones`, `/user`, and `/memberships` APIs.
32+
- **Granular filtering**: Uniformly formatted logs allow for precise filtering by actions, actors, methods, and resources, facilitating efficient investigations.
33+
- **Enhanced context and transparency**: Each log entry includes detailed context, such as the authentication method used, the interface (API or dashboard) through which the action was performed, and mappings to Cloudflare Ray IDs for improved traceability.
34+
- **Comprehensive activity capture**: Beyond create, edit, and delete actions, Audit Logs records GET requests and failed attempts, ensuring no critical activity is overlooked.
35+
36+
## Retention
37+
38+
Audit logs are retained for 18 months before being deleted. Enterprise customers can use [Logpush](/logs/logpush/) to store audit logs for longer periods of time. Logpush for Audit Logs v2 will be available for GA.
39+
40+
## Access Audit Logs
41+
42+
You can retrieve audit logs using either the API or the dashboard. Audit Logs v2 will soon be available with Logpush.
43+
44+
### API
45+
46+
Audit Logs are available through the Cloudflare API. To retrieve audit logs, use the following endpoint:
47+
48+
```bash
49+
https://api.cloudflare.com/client/v4/accounts/{account_id}/logs/audit
50+
```
51+
52+
Below is an example request to retrieve audit logs for a certain period of time along with its corresponding response. Replace the example values in the URL with your actual values:
53+
54+
- `account_id`: Your Cloudflare account identifier.
55+
- `Since` (required): Start date for the audit log retrieval in the format yyyy-mm-dd.​
56+
- `Before` (required) : End date for the audit log retrieval in the format yyyy-mm-dd.
57+
58+
```bash
59+
GET https://api.cloudflare.com/client/v4/accounts/1234567890abcdef/logs/audit?since=2025-03-01T00:00:00Z&before=2025-03-26T23:59:59Z
60+
```
61+
62+
```json title="Example response"
63+
{
64+
"result": [
65+
{
66+
"action": "zone.settings.change",
67+
"actor": {
68+
"email": "[email protected]",
69+
"id": "0987654321abcdef"
70+
},
71+
"ip": "192.0.2.1",
72+
"method": "PUT",
73+
"interface": "dashboard",
74+
"resources": [
75+
{
76+
"resource_id": "zone123",
77+
"resource_type": "zone"
78+
}
79+
],
80+
"timestamp": "2025-03-15T14:25:37Z"
81+
}
82+
// Additional log entries
83+
],
84+
"success": true,
85+
"errors": [],
86+
"messages": []
87+
}
88+
```
89+
90+
For more information refer to the [API documentation](https://developers.cloudflare.com/api/resources/accounts/subresources/logs/subresources/audit/methods/list/#(params)%20default%20%3E%20(param)%20since%20%3E%20(schema)).
91+
92+
### Dashboard
93+
94+
To access audit logs in the Cloudflare dashboard:
95+
96+
1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
97+
2. Go to **Manage Account** > **Audit Logs**.
98+
99+
:::note
100+
The Audit Logs v1 is shown by default. You can switch between Audit Logs v1 and v2 as needed.
101+
:::
102+
103+
## Audit Log structure
104+
105+
Cloudflare's audit logs offer a detailed view of activity across your environment by capturing both the source of actions and the context in which they occur. These logs are categorized by who initiated the action (user or system) and whether the activity occurred within a specific account or spanned multiple accounts under the same user profile. This structure enables flexible filtering, investigation, and compliance monitoring.
106+
107+
### Initiation type
108+
109+
Audit logs can be initiated either by users or the system. Understanding the type of actor involved helps in identifying the source and intent of actions.
110+
111+
#### User initiated Audit Logs
112+
113+
Track actions performed directly by users through Cloudflare interfaces (dashboard or API). These logs capture who performed the action, when it occurred, and what resource was affected. User initiated actions can be performed by three actors:
114+
115+
- `actor_type="user"`: Action was performed by an individual user.
116+
- `actor_type="Cloudflare_admin"`: Action was performed by Cloudflare.
117+
- `actor_type="account"`: Action was performed using an account owned token. Refer to the [Account owned tokens](/fundamentals/api/get-started/account-owned-tokens/) documentation for more information.
118+
119+
#### System initiated Audit Logs
120+
121+
Record changes made automatically by Cloudflare systems, without direct user input. These logs provide visibility into internal processes, automated tasks, and security events. Some entries may include associated user context for traceability (`actor_type="system"`).
122+
123+
### Activity Scope
124+
125+
#### Account Activity Logs
126+
127+
Contain events scoped to a single Cloudflare account. These logs are filterable by `account ID` and reflect actions within that account only. You can optionally filter events further using the `resource_scope` field, which specifies whether the resource is associated with a user, an account, or a zone (`resource_scope ="user"`, `resource_scope ="accounts"`, or `resource_scope ="zones"`).
128+
129+
#### User Profile Activity Logs
130+
131+
Reflect actions associated with a user's login (email) across multiple accounts. These logs enable cross-account tracking and can be filtered by `user ID` or `email`. They are visible on any account the user had access to at the time of the activity. User Profile Activity Logs can be filtered using `resource_scope ="user"`.
132+
133+
The `GET /memberships` endpoint supports cross-account access. To query memberships, use the parameter `resource_scope=memberships`.
134+
135+
## Example how to query Audit Logs
136+
137+
Use the following example to get a list of audit logs for a user account.
138+
139+
<APIRequest
140+
method="GET"
141+
path="/accounts/{account_id}/logs/audit"
142+
/>
143+
144+
```json title="Example response"
145+
{
146+
"errors": [
147+
{
148+
"message": "message"
149+
}
150+
],
151+
"result": [
152+
{
153+
"account": {
154+
"id": "4bb334f7c94c4a29a045f03944f072e5",
155+
"name": "Example Account"
156+
},
157+
"action": {
158+
"description": "Add Member",
159+
"result": "success",
160+
"time": "2024-04-26T17:31:07Z",
161+
"type": "create"
162+
},
163+
"actor": {
164+
"id": "f6b5de0326bb5182b8a4840ee01ec774",
165+
"context": "dash",
166+
"email": "[email protected]",
167+
"ip_address": "198.41.129.166",
168+
"token_id": "token_id",
169+
"token_name": "token_name",
170+
"type": "user"
171+
},
172+
"raw": {
173+
"cf_ray_id": "8e9b1c60ef9e1c9a",
174+
"method": "POST",
175+
"status_code": 200,
176+
"uri": "/accounts/4bb334f7c94c4a29a045f03944f072e5/members",
177+
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Safari/605.1.15"
178+
},
179+
"resource": {
180+
"id": "id",
181+
"product": "members",
182+
"request": {},
183+
"response": {},
184+
"scope": {},
185+
"type": "type"
186+
},
187+
"zone": {
188+
"id": "id",
189+
"name": "example.com"
190+
}
191+
}
192+
],
193+
"result_info": {
194+
"count": "1",
195+
"cursor": "ASqdKd7dKgxh-aZ8bm0mZos1BtW4BdEqifCzNkEeGRzi_5SN_-362Y8sF-C1TRn60_6rd3z2dIajf9EAPyQ_NmIeAMkacmaJPXipqvP7PLU4t72wyqBeJfjmjdE="
196+
},
197+
"success": true
198+
}
199+
```
200+
201+
## Common terms and definitions
202+
203+
### Actor
204+
205+
The actor represents who performed the action. It includes identity attributes like user ID, email address, IP address, and the type of actor (`user`, `account`, `Cloudflare_admin`, or `system`). It also includes the context used to initiate the action, such as API or dashboard (`dash`).
206+
207+
### Action
208+
209+
The action field captures the nature of the event and whether it was successful. It includes a high-level type (e.g., `view`, `create`, `update`, `delete`), a specific description (such as `SSO_LOGIN`), the timestamp of when the action occurred, and the result (`success` or `failure`).
210+
211+
All `GET` requests are captured as `view` actions in Audit Logs.
212+
213+
### Account
214+
215+
This field refers to the Cloudflare account under which the action was executed. It includes a unique account ID and a human-readable account name to help associate activity with a customer environment.
216+
217+
### Resource
218+
219+
The resource identifoes the object impacted by the action. It includes the resource type, the unique resource ID, the scope (`user`, `account`, or `zone`), and optionally the product associated with the change.
220+
221+
### Audit Log ID
222+
223+
This is a unique identifier for the log record itself. It can be used for deduplication, correlation, or referencing specific actions during investigations.
224+
225+

‎src/content/docs/fundamentals/account/account-security/cloudflare-access.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,8 @@ title: Allow Cloudflare access
44
head:
55
- tag: title
66
content: Provide edit access to Cloudflare Support
7-
7+
sidebar:
8+
order: 2
89
---
910

1011
Occasionally, you may want to allow edit access to your account for Cloudflare Support. A typical use case might be migrating a complex or sensitive domain over to Cloudflare.

‎src/content/docs/fundamentals/account/account-security/leaked-password-notifications.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
---
22
pcx_content_type: reference
33
title: Leaked Password Notifications
4+
sidebar:
5+
order: 3
46

57
---
68

‎src/content/docs/fundamentals/account/account-security/manage-active-sessions.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
---
22
title: Manage active sessions
33
pcx_content_type: how-to
4-
4+
sidebar:
5+
order: 4
56
---
67

78
import { Render } from "~/components"

‎src/content/docs/fundamentals/account/account-security/review-audit-logs.mdx‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,16 @@
11
---
2-
title: Review audit logs
2+
title: Review audit logs - v1
33
pcx_content_type: how-to
4-
4+
sidebar:
5+
order: 5
56
---
67

78
import { Render } from "~/components"
89

10+
:::note
11+
Audit Logs version 2 is available in beta. Refer to the [Audit Logs v2 documentation](/fundamentals/account/account-security/audit-logs/) for more details.
12+
:::
13+
914
<Render file="account-audit-logs-definition" />
1015

1116
## Access audit logs

0 commit comments

Comments
 (0)