Skip to content

Commit e194eee

Browse files
craigcomstockcraigcomstock
authored
Merge pull request #3360 from aleksandrychev/ENT-11977
ENT-11977: Added the Audit logs API documentation
2 parents 49d82af + 77ceadf commit e194eee

File tree

2 files changed

+170
-0
lines changed

2 files changed

+170
-0
lines changed

‎api/enterprise-api-ref/audit-logs-api.markdown

Lines changed: 148 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,148 @@
1+
---
2+
layout: default
3+
title: Audit logs API
4+
published: true
5+
---
6+
7+
Audit logs API provides access to system audit logs that track user actions across the platform made to critical parts
8+
such as settings, host data, users, roles, Build projects, etc.
9+
10+
## Get audit logs
11+
12+
**URI:** https://hub.cfengine.com/api/audit-logs
13+
14+
**Method:** GET
15+
16+
**Parameters:**
17+
18+
* **actor** *(string)*
19+
Filter by user who performed the action.
20+
* **object_type** *(string)*
21+
Filter by object type (see [Allowed object types][Audit logs API#Allowed object types]).
22+
* **action** *(string)*
23+
Filter by action type (see [Allowed actions][Audit logs API#Allowed actions]).
24+
* **created_after** *(integer)*
25+
Unix timestamp to filter logs after this time.
26+
* **created_before** *(integer)*
27+
Unix timestamp to filter logs before this time.
28+
* **page** *(integer)*
29+
Page number for pagination (default: 1).
30+
* **offset** *(integer)*
31+
Number of results to skip for the processed query.
32+
* **sort_column** *(string)*
33+
Column to sort by. Allowed values:
34+
* time
35+
* actor
36+
* action
37+
* object_id
38+
* object_type
39+
* **sort_direction** *(string, default: "DESC")*
40+
Sort direction. Allowed values:
41+
* ASC (ascending)
42+
* DESC (descending)
43+
44+
**Example request (curl):**
45+
46+
```console
47+
curl --user <username>:<password> -X GET https://hub.cfengine.com/api/audit-logs
48+
```
49+
50+
**Successful response example:**
51+
52+
```
53+
HTTP 200 OK
54+
{
55+
"data": [
56+
{
57+
"id": 4,
58+
"time": "2024-10-24 09:47:08.329041",
59+
"actor": "admin",
60+
"action": "created",
61+
"object_type": "user",
62+
"object_id": "test",
63+
"details": [
64+
"Created user `test`."
65+
]
66+
},
67+
{
68+
"id": 3,
69+
"time": "2024-10-24 09:46:56.204391",
70+
"actor": "admin",
71+
"action": "created",
72+
"object_type": "role",
73+
"object_id": "test",
74+
"details": [
75+
"Created role `test`.",
76+
{
77+
"description": "test",
78+
"excludeContext": "",
79+
"includedContext": "test"
80+
}
81+
]
82+
},
83+
{
84+
"id": 2,
85+
"time": "2024-10-24 09:46:42.595813",
86+
"actor": "admin",
87+
"action": "updated",
88+
"object_type": "settings",
89+
"object_id": null,
90+
"details": [
91+
"Settings updated.",
92+
{
93+
"changes": [
94+
"minPasswordLength"
95+
]
96+
}
97+
]
98+
}
99+
],
100+
"meta": {
101+
"count": 4,
102+
"page": 1,
103+
"timestamp": 1729763237,
104+
"total": 4
105+
}
106+
}
107+
```
108+
109+
**Responses:**
110+
111+
| HTTP response code | Description |
112+
|------------------------------|--------------------------------------|
113+
| 200 OK | Audit logs returned |
114+
| 422 Unprocessable entity | Validation error occurred |
115+
| 401 Unauthorized | Authorization is missing |
116+
| 403 Insufficient permissions | Audit logs are not available to user |
117+
| 500 Internal server error | Internal server error |
118+
119+
120+
### Allowed actions
121+
122+
| Action | Description |
123+
|----------------------|---------------------------|
124+
| created | Resource creation |
125+
| updated | Resource update |
126+
| deleted | Resource deletion |
127+
| deployed | Deployment action |
128+
| pushed | Push action |
129+
| module added | Module addition |
130+
| module deleted | Module removal |
131+
| module updated | Module modification |
132+
| module input updated | Module input modification |
133+
| CMDB updated | CMDB update |
134+
| CMDB deleted | CMDB deletion |
135+
| CMDB created | CMDB creation |
136+
| RBAC updated | RBAC modification |
137+
138+
### Allowed object types
139+
140+
| Object Type | Description |
141+
|---------------------|----------------------------------------------|
142+
| user | User account |
143+
| role | Role definition |
144+
| settings | System, Mail, VCS or Authentication settings |
145+
| federated reporting | Federated reporting configuration |
146+
| group | Host groups |
147+
| host | Host configuration |
148+
| Build project | Build project configuration |

‎api/enterprise-api-ref/sql-schema/cfsettings.markdown

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,28 @@ published: true
66

77
Settings used by Mission Portal APIs, no reported data.
88

9+
## Table: audit_logs
10+
11+
Stores system logs about actions performed by users.
12+
13+
**Columns:**
14+
15+
* **id** *(bigint)*
16+
The unique identifier of audit log event, generated from a sequence.
17+
* **time** *(timestamp without a time zone)*
18+
Time when an event happened.
19+
* **action** *(text)*
20+
What was done (e.g., updated, created, deleted, deployed).
21+
* **object_type** *(text)*
22+
Type of affected object (e.g., user, role, build project).
23+
* **object_id** *(text)*
24+
Identifier of an affected object (e.g. user, role id, build project id), if applicable.
25+
* **details** *(json)*
26+
More details in the free-json format.
27+
* **ip_address** *(boolean)*
28+
IP address of the user who performed the action.
29+
30+
931
## Table: build_modules
1032

1133
Information about build modules available from the index (build.cfengine.com).

0 commit comments

Comments
 (0)