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

Audit Logs

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

Note

Audit logs require a Premium license. For more details, contact your account team.

Tracked Events

We track the following resources:

Resource
APIKey login, logout, register, create, write, delete	Field Tracked allow_list false created_at true expires_at true hashed_secret false id false ip_address false last_used true lifetime_seconds false login_type false scopes false token_name false updated_at false user_id true
AiSeatState create	Field Tracked first_used_at true last_event_description true last_event_type true last_used_at 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 chat_spend_limit_micros 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 is_system false member_permissions true 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_id_issued_at false client_secret_expires_at true client_type true client_uri true contacts true created_at false dynamically_registered true grant_types true icon true id false jwks true jwks_uri true logo_uri true name true policy_uri true redirect_uris true registration_access_token true registration_client_uri true response_types true scope true software_id true software_version true token_endpoint_auth_method true tos_uri 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 shareable_workspace_owners true updated_at true
OrganizationSyncSettings	Field Tracked assign_default true field true mapping true
PrebuildsSettings	Field Tracked id false reconciliation_paused true
RoleSyncSettings	Field Tracked field true mapping true
TaskTable	Field Tracked created_at false deleted_at false display_name true id true name true organization_id false owner_id true prompt true template_parameters true template_version_id true workspace_id 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 cors_behavior 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 disable_module_cache 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 has_external_agent 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 chat_spend_limit_micros true created_at false deleted true email true github_com_user_id false hashed_one_time_passcode false hashed_password true id true is_service_account 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
WorkspaceBuild start, stop	Field Tracked build_number false created_at false daily_cost false deadline false has_ai_task false has_external_agent 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 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 group_acl 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 user_acl true

How to Filter Audit Logs

You can filter audit logs by the following parameters:

• resource_type - The type of the resource, such as a workspace, template, or user. For more resource types, refer to the CoderSDK package documentation.
• 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, such as create or delete. For more actions, refer to the CoderSDK package documentation.
• 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 - The reason for the workspace build, if resource_type is workspace_build. Refer to the CoderSDK package documentation for a list of valid build reasons.

Capturing/Exporting Audit Logs

In addition to the Coder dashboard, there are multiple ways to consume or query audit trails.

REST API

You can retrieve audit logs via the Coder API.

Visit the get-audit-logs endpoint documentation for details.

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/coder/coder/enterprise/audit/backends/slog.go:38",
    "func": "github.com/coder/coder/v2/enterprise/audit/backends.(*SlogExporter).ExportStruct",
    "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": null,
        "UserAgent": null,
        "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=""

Purging Old Audit Logs

Warning

Audit Logs provide critical security and compliance information. Purging Audit Logs may impact your organization's ability to investigate security incidents or meet compliance requirements. Consult your security and compliance teams before purging any audit data.

Data Retention

Coder supports configurable retention policies that automatically purge old Audit Logs. To enable automated purging, configure the --audit-logs-retention flag or CODER_AUDIT_LOGS_RETENTION environment variable. For comprehensive configuration options, see Data Retention.

Manual Purging

Alternatively, you can purge Audit Logs manually by running SQL queries directly against the database.

Audit Logs can account for a large amount of disk usage. Use the following query to determine the amount of disk space used by the audit_logs table.

SELECT
    relname AS table_name,
    pg_size_pretty(pg_total_relation_size(relid)) AS total_size,
    pg_size_pretty(pg_relation_size(relid)) AS table_size,
    pg_size_pretty(pg_indexes_size(relid)) AS indexes_size,
    (SELECT COUNT(*) FROM audit_logs) AS total_records
FROM pg_catalog.pg_statio_user_tables
WHERE relname = 'audit_logs'
ORDER BY pg_total_relation_size(relid) DESC;

Should you wish to purge these records, it is safe to do so. This can only be done by running SQL queries directly against the audit_logs table in the database. We advise users to only purge old records (>1yr) and in accordance with your compliance requirements.

Maintenance Procedures for the Audit Logs Table

Note

VACUUM FULL acquires an exclusive lock on the table, blocking all reads and writes. For more information, see the PostgreSQL VACUUM documentation.

You may choose to run a VACUUM or VACUUM FULL operation on the audit logs table to reclaim disk space. If you choose to run the FULL operation, consider the following when doing so:

• Run during a planned maintenance window to ensure ample time for the operation to complete and minimize impact to users

• Stop all running instances of coderd to prevent connection errors while the table is locked. The actual steps for this will depend on your particular deployment setup. For example, if your coderd deployment is running on Kubernetes:

  kubectl scale deployment coder --replicas=0 -n coder
  

• Terminate lingering connections before running the VACUUM operation to ensure it starts immediately

  SELECT pg_terminate_backend(pg_stat_activity.pid)
  FROM pg_stat_activity
  WHERE pg_stat_activity.datname = 'coder' AND pid <> pg_backend_pid();
  

• Only coderd needs to scale down - external provisioner daemons, workspace proxies, and workspace agents don't connect to the database directly.

After the vacuum completes, scale coderd back up:

kubectl scale deployment coder --replicas= -n coder

Backup/Archive

Consider exporting or archiving these records before deletion:

-- Export to CSV
COPY (SELECT * FROM audit_logs WHERE time < CURRENT_TIMESTAMP - INTERVAL '1 year')
TO '/path/to/audit_logs_archive.csv' DELIMITER ',' CSV HEADER;

-- Copy to archive table
CREATE TABLE audit_logs_archive AS
SELECT * FROM audit_logs WHERE time < CURRENT_TIMESTAMP - INTERVAL '1 year';

Permanent Deletion

Note

For large audit_logs tables, consider running the DELETE operation during maintenance windows as it may impact database performance. You can also batch the deletions to reduce lock time.

DELETE FROM audit_logs WHERE time < CURRENT_TIMESTAMP - INTERVAL '1 year';
-- Consider running `VACUUM VERBOSE audit_logs` afterwards for large datasets to reclaim disk space.

How to Enable Audit Logs

This feature is only available with a Premium license, and is automatically enabled.