coder/docs/admin/security/audit-logs.md

Audit Logs

Audit Logs allows Auditors to monitor user operations in their deployment.

Tracked Events

We track the following resources:

Resource
APIKey login, logout, register, create, delete	Field Tracked created_at true expires_at true hashed_secret false id false ip_address false last_used true lifetime_seconds false login_type false scope false token_name false updated_at false user_id true
AuditOAuthConvertState	Field Tracked created_at true expires_at true from_login_type true to_login_type true user_id true
Group create, write, delete	Field Tracked avatar_url true display_name true id true members true name true organization_id false quota_allowance true source false
AuditableOrganizationMember	Field Tracked created_at true organization_id false roles true updated_at true user_id true username true
CustomRole	Field Tracked created_at false display_name true id false name true org_permissions true organization_id false site_permissions true updated_at false user_permissions true
GitSSHKey create	Field Tracked created_at false private_key true public_key true updated_at false user_id true
GroupSyncSettings	Field Tracked auto_create_missing_groups true field true legacy_group_name_mapping false mapping true regex_filter true
HealthSettings	Field Tracked dismissed_healthchecks true id false
License create, delete	Field Tracked exp true id false jwt false uploaded_at true uuid true
NotificationTemplate	Field Tracked actions true body_template true enabled_by_default true group true id false kind true method true name true title_template true
NotificationsSettings	Field Tracked id false notifier_paused true
OAuth2ProviderApp	Field Tracked callback_url true client_type true created_at false dynamically_registered true icon true id false name true redirect_uris true updated_at false
OAuth2ProviderAppSecret	Field Tracked app_id false created_at false display_secret false hashed_secret false id false last_used_at false secret_prefix false
Organization	Field Tracked created_at false deleted true description true display_name true icon true id false is_default true name true updated_at true
OrganizationSyncSettings	Field Tracked assign_default true field true mapping true
RoleSyncSettings	Field Tracked field true mapping true
Template write, delete	Field Tracked active_version_id true activity_bump true allow_user_autostart true allow_user_autostop true allow_user_cancel_workspace_jobs true autostart_block_days_of_week true autostop_requirement_days_of_week true autostop_requirement_weeks true created_at false created_by true created_by_avatar_url false created_by_name false created_by_username false default_ttl true deleted false deprecated true description true display_name true failure_ttl true group_acl true icon true id true max_port_sharing_level true name true organization_display_name false organization_icon false organization_id false organization_name false provisioner true require_active_version true time_til_dormant true time_til_dormant_autodelete true updated_at false use_classic_parameter_flow true user_acl true
TemplateVersion create, write	Field Tracked archived true created_at false created_by true created_by_avatar_url false created_by_name false created_by_username false external_auth_providers false has_ai_task false id true job_id false message false name true organization_id false readme true source_example_id false template_id true updated_at false
User create, write, delete	Field Tracked avatar_url false created_at false deleted true email true github_com_user_id false hashed_one_time_passcode false hashed_password true id true is_system true last_seen_at false login_type true name true one_time_passcode_expires_at true quiet_hours_schedule true rbac_roles true status true updated_at false username true
WorkspaceAgent connect, disconnect	Field Tracked api_key_scope false api_version false architecture false auth_instance_id false auth_token false connection_timeout_seconds false created_at false deleted false directory false disconnected_at false display_apps false display_order false environment_variables false expanded_directory false first_connected_at false id false instance_metadata false last_connected_at false last_connected_replica_id false lifecycle_state false logs_length false logs_overflowed false motd_file false name false operating_system false parent_id false ready_at false resource_id false resource_metadata false started_at false subsystems false troubleshooting_url false updated_at false version false
WorkspaceApp open, close	Field Tracked agent_id false command false created_at false display_group false display_name false display_order false external false health false healthcheck_interval false healthcheck_threshold false healthcheck_url false hidden false icon false id false open_in false sharing_level false slug false subdomain false url false
WorkspaceBuild start, stop	Field Tracked ai_task_sidebar_app_id false build_number false created_at false daily_cost false deadline false has_ai_task false id false initiator_by_avatar_url false initiator_by_name false initiator_by_username false initiator_id false job_id false max_deadline false provisioner_state false reason false template_version_id true template_version_preset_id false transition false updated_at false workspace_id false
WorkspaceProxy	Field Tracked created_at true deleted false derp_enabled true derp_only true display_name true icon true id true name true region_id true token_hashed_secret true updated_at false url true version true wildcard_hostname true
WorkspaceTable	Field Tracked automatic_updates true autostart_schedule true created_at false deleted false deleting_at true dormant_at true favorite true id true last_used_at false name true next_start_at true organization_id false owner_id true template_id true ttl true updated_at false

Filtering logs

In the Coder UI you can filter your audit logs using the pre-defined filter or by using the Coder's filter query like the examples below:

• resource_type:workspace action:delete to find deleted workspaces
• resource_type:template action:create to find created templates

The supported filters are:

• resource_type - The type of the resource. It can be a workspace, template, user, etc. You can find here all the resource types that are supported.
• resource_id - The ID of the resource.
• resource_target - The name of the resource. Can be used instead of resource_id.
• action- The action applied to a resource. You can find here all the actions that are supported.
• username - The username of the user who triggered the action. You can also use me as a convenient alias for the logged-in user.
• email - The email of the user who triggered the action.
• date_from - The inclusive start date with format YYYY-MM-DD.
• date_to - The inclusive end date with format YYYY-MM-DD.
• build_reason - To be used with resource_type:workspace_build, the initiator 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.

Service Logs

Audit trails are also dispatched as service logs and can be captured and categorized using any log management tool such as Splunk.

Example of a JSON formatted audit log entry:

{
    "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 audit log entry:

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=<nil>  UserAgent=<nil>  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 a premium license. Learn more