diff --git a/docs/admin/audit-logs.md b/docs/admin/audit-logs.md index 1e00c468877b1..85b1e8aa7dbb6 100644 --- a/docs/admin/audit-logs.md +++ b/docs/admin/audit-logs.md @@ -43,6 +43,59 @@ The supported filters are: - `date_to` - The inclusive end date with format `YYYY-MM-DD`. - `build_reason` - To be used with `resource_type:workspace_build`, the [initiator](https://pkg.go.dev/github.com/coder/coder/codersdk#BuildReason) behind the build start or stop. +## Capturing/Exporting Audit Logs + +In addition to the user interface, there are multiple ways to consume or query audit trails. + +## REST API + +Audit logs can be accessed through our REST API. You can find detailed information about this in our [endpoint documentation](../api/audit#get-audit-logs). + +## Service Logs + +Audit trails are also dispatched as service logs and can be captured and categorized using any log management tool such as [Splunk](https://splunk.com). + +Example of a [JSON formatted](../cli/server#--log-json) audit log entry: + +```json +{ + "ts": "2023-06-13T03:45:37.294730279Z", + "level": "INFO", + "msg": "audit_log", + "caller": "/home/runner/work/coder/coder/enterprise/audit/backends/slog.go:36", + "func": "github.com/coder/coder/enterprise/audit/backends.slogBackend.Export", + "logger_names": ["coderd"], + "fields": { + "ID": "033a9ffa-b54d-4c10-8ec3-2aaf9e6d741a", + "Time": "2023-06-13T03:45:37.288506Z", + "UserID": "6c405053-27e3-484a-9ad7-bcb64e7bfde6", + "OrganizationID": "00000000-0000-0000-0000-000000000000", + "Ip": "{IPNet:{IP:\u003cnil\u003e Mask:\u003cnil\u003e} Valid:false}", + "UserAgent": "{String: Valid:false}", + "ResourceType": "workspace_build", + "ResourceID": "ca5647e0-ef50-4202-a246-717e04447380", + "ResourceTarget": "", + "Action": "start", + "Diff": {}, + "StatusCode": 200, + "AdditionalFields": { + "workspace_name": "linux-container", + "build_number": "9", + "build_reason": "initiator", + "workspace_owner": "" + }, + "RequestID": "bb791ac3-f6ee-4da8-8ec2-f54e87013e93", + "ResourceIcon": "" + } +} +``` + +Example of a [human readable](../cli/server#--log-human) audit log entry: + +```sh +2023-06-13 03:43:29.233 [info] coderd: audit_log ID=95f7c392-da3e-480c-a579-8909f145fbe2 Time="2023-06-13T03:43:29.230422Z" UserID=6c405053-27e3-484a-9ad7-bcb64e7bfde6 OrganizationID=00000000-0000-0000-0000-000000000000 Ip= UserAgent= ResourceType=workspace_build ResourceID=988ae133-5b73-41e3-a55e-e1e9d3ef0b66 ResourceTarget="" Action=start Diff="{}" StatusCode=200 AdditionalFields="{\"workspace_name\":\"linux-container\",\"build_number\":\"7\",\"build_reason\":\"initiator\",\"workspace_owner\":\"\"}" RequestID=9682b1b5-7b9f-4bf2-9a39-9463f8e41cd6 ResourceIcon="" +``` + ## Enabling this feature This feature is only available with an enterprise license. [Learn more](../enterprise.md)