Adds the database layer for attaching workspace templates to chat projects: the schema, the queries, their authorization, and the audit type. Nothing calls the new queries yet, and the existing create and update handlers pass the new parameters unset. The API, the limit's enforcement, and the agent tools follow in the PRs above. - Attachments live in a `chat_project_templates` table (`project_id`, `template_id`, `created_by`, `created_at`), deleted with the project or the template. `chat_projects` gains `limit_templates` (default `false`), `default_template_id`, `default_template_version_preset_id`, and `default_parameters jsonb`. A project stores a default preset or default parameter values, not both. - `InsertChatProjectTemplates` needs project `update` and `use` on every template. It skips templates that are already attached, and templates outside the project's organization, so an attachment never crosses organizations. `DeleteChatProjectTemplate` needs project `update` and template `read`, and clears the project's default when it detaches the default template. Both checks are in dbauthz. - `GetChatProjectTemplatesByProjectIDs` is authorized through the project, and leaves out deleted, deprecated, and agent-disabled templates. It does not check the caller's access to each template, so callers do that before they expose one. - `UpdateChatProjectByID` changes the template settings only when the request sets them, so an update that omits them cannot write back a stale snapshot. - `AuditableChatProjectTemplates` is the audit form of a project's attached templates, logged as a write to the project. The new `chat_projects` columns are tracked in the project's own audit diff, with the default parameter values masked because they may hold credentials. **NOTE**: the migration adds one table and four columns and changes no existing rows. Existing projects keep unlimited template access. Stack (merge top to bottom): - #32309 👈 - #30754 - #32310 - #30755 - #30756 - #30898
43 KiB
title
| title |
|---|
| 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
Coder records audit log entries for the resources below. Each section lists the actions that produce an entry, followed by the resource's fields. When a tracked field changes, the change appears in the entry's diff, and untracked fields are left out.
AIGatewayKey
Actions: create, delete
| Field | Tracked |
|---|---|
created_at | No |
hashed_secret | Yes |
id | Yes |
last_heartbeat_at | No |
name | Yes |
secret_prefix | Yes |
AIProvider
Actions: create, write, delete
| Field | Tracked |
|---|---|
base_url | Yes |
created_at | No |
deleted | Yes |
display_name | Yes |
enabled | Yes |
icon | Yes |
id | Yes |
name | Yes |
settings | Yes |
settings_key_id | No |
type | Yes |
updated_at | No |
AIProviderKey
Actions: create, delete
| Field | Tracked |
|---|---|
api_key | Yes |
api_key_key_id | No |
created_at | No |
id | Yes |
provider_id | Yes |
updated_at | No |
AISeatState
Actions: create
| Field | Tracked |
|---|---|
first_used_at | Yes |
last_event_description | Yes |
last_event_type | Yes |
last_used_at | No |
updated_at | No |
user_id | Yes |
APIKey
Actions: login, logout, register, create, write, delete
| Field | Tracked |
|---|---|
allow_list | No |
created_at | Yes |
expires_at | Yes |
hashed_secret | No |
id | No |
ip_address | No |
last_used | Yes |
lifetime_seconds | No |
login_type | No |
scopes | No |
token_name | No |
updated_at | No |
user_id | Yes |
AuditOAuthConvertState
| Field | Tracked |
|---|---|
created_at | Yes |
expires_at | Yes |
from_login_type | Yes |
to_login_type | Yes |
user_id | Yes |
AuditableChatProjectInstructions
Actions: write, delete
| Field | Tracked |
|---|---|
created_at | No |
instructions | Yes |
organization_id | No |
project_id | No |
project_name | No |
updated_at | No |
updated_by | No |
AuditableChatProjectSkill
Actions: create, write, delete
| Field | Tracked |
|---|---|
action | Yes |
content | Yes |
created_at | No |
description | Yes |
display_name | Yes |
enabled | Yes |
group_acl | Yes |
id | Yes |
model_invocable | Yes |
name | Yes |
organization_id | Yes |
project_id | Yes |
updated_at | No |
user_acl | Yes |
user_id | Yes |
AuditableChatProjectTemplates
Actions: write
| Field | Tracked |
|---|---|
project_id | No |
project_name | No |
template_ids | Yes |
Group
Actions: create, write, delete
| Field | Tracked |
|---|---|
avatar_url | Yes |
chat_spend_limit_micros | Yes |
display_name | Yes |
id | Yes |
members | Yes |
name | Yes |
organization_id | No |
quota_allowance | Yes |
source | No |
AuditableGroupAIBudget
Actions: write, delete
| Field | Tracked |
|---|---|
created_at | No |
group_id | No |
group_name | No |
spend_limit | Yes |
spend_limit_micros | No |
updated_at | No |
AuditableOrganizationMember
| Field | Tracked |
|---|---|
created_at | Yes |
organization_id | No |
roles | Yes |
updated_at | Yes |
user_id | Yes |
username | Yes |
AuditableOrganizationSkill
Actions: create, write, delete
| Field | Tracked |
|---|---|
action | Yes |
content | Yes |
created_at | No |
description | Yes |
display_name | Yes |
enabled | Yes |
group_acl | Yes |
id | Yes |
model_invocable | Yes |
name | Yes |
organization_id | Yes |
project_id | Yes |
updated_at | No |
user_acl | Yes |
user_id | Yes |
AuditableUserAIBudgetOverride
Actions: write, delete
| Field | Tracked |
|---|---|
created_at | No |
group_id | Yes |
group_name | Yes |
spend_limit | Yes |
spend_limit_micros | No |
updated_at | No |
user_id | No |
username | No |
Chat
Actions: create, write
| Field | Tracked |
|---|---|
agent_id | No |
archived | Yes |
build_id | No |
client_type | No |
compaction_requested_at | No |
context_aggregate_hash | No |
context_dirty_resources | No |
context_dirty_since | No |
context_error | No |
created_at | No |
dynamic_tools | No |
generation_attempt | No |
group_acl | Yes |
heartbeat_at | No |
history_version | No |
id | Yes |
labels | Yes |
last_error | No |
last_model_config_id | No |
last_read_message_id | No |
last_reasoning_effort | No |
last_turn_summary | No |
mcp_server_ids | Yes |
mode | Yes |
organization_id | No |
owner_id | Yes |
owner_name | No |
owner_username | No |
parent_chat_id | No |
pin_order | Yes |
plan_mode | No |
project_id | Yes |
queue_version | No |
requires_action_deadline_at | No |
retry_state | No |
retry_state_version | No |
root_chat_id | No |
runner_id | No |
snapshot_version | No |
started_at | No |
status | No |
summary | No |
summary_generated_at | No |
title | Yes |
title_source | Yes |
title_updated_at | No |
updated_at | No |
user_acl | Yes |
worker_id | No |
workspace_id | Yes |
ChatInstructionSettings
Actions: write
| Field | Tracked |
|---|---|
id | No |
include_default_system_prompt | Yes |
include_default_system_prompt_set | Yes |
name | No |
plan_mode_instructions | Yes |
system_prompt | Yes |
ChatModelConfig
Actions: create, write, delete
| Field | Tracked |
|---|---|
ai_provider_id | Yes |
compression_threshold | Yes |
context_limit | Yes |
created_at | No |
created_by | Yes |
deleted | Yes |
deleted_at | No |
display_name | Yes |
enabled | Yes |
group_acl | Yes |
id | No |
is_default | Yes |
model | Yes |
options | Yes |
organization_id | No |
updated_at | No |
updated_by | Yes |
user_acl | Yes |
ChatOperationalSettings
Actions: write
| Field | Tracked |
|---|---|
chat_auto_archive_days | Yes |
chat_debug_retention_days | Yes |
chat_retention_days | Yes |
debug_logging_allow_users | Yes |
id | No |
personal_model_overrides_enabled | Yes |
workspace_ttl | Yes |
ChatOrganizationSystemPrompt
Actions: write
| Field | Tracked |
|---|---|
created_at | No |
organization_id | No |
system_prompt | Yes |
updated_at | No |
ChatProject
Actions: create, write, delete
| Field | Tracked |
|---|---|
created_at | No |
default_parameters | Yes |
default_template_id | Yes |
default_template_version_preset_id | Yes |
description | Yes |
group_acl | Yes |
icon | Yes |
id | Yes |
limit_templates | Yes |
name | Yes |
organization_id | Yes |
owner_id | Yes |
updated_at | No |
user_acl | Yes |
ChatProjectMemory
Actions: create, delete
| Field | Tracked |
|---|---|
body | Yes |
created_at | No |
created_by | Yes |
description | Yes |
id | Yes |
name | Yes |
organization_id | Yes |
project_id | Yes |
CustomRole
| Field | Tracked |
|---|---|
created_at | No |
display_name | Yes |
id | No |
is_system | No |
member_permissions | Yes |
name | Yes |
org_permissions | Yes |
organization_id | No |
site_permissions | Yes |
updated_at | No |
user_permissions | Yes |
ExperimentRule
Actions: write
| Field | Tracked |
|---|---|
condition | Yes |
experiment | Yes |
id | No |
mode | Yes |
revision | Yes |
GitSSHKey
Actions: create
| Field | Tracked |
|---|---|
created_at | No |
private_key | Yes |
private_key_key_id | No |
public_key | Yes |
updated_at | No |
user_id | Yes |
GroupSyncSettings
| Field | Tracked |
|---|---|
auto_create_missing_groups | Yes |
field | Yes |
legacy_group_name_mapping | No |
mapping | Yes |
regex_filter | Yes |
HealthSettings
| Field | Tracked |
|---|---|
dismissed_healthchecks | Yes |
id | No |
License
Actions: create, delete
| Field | Tracked |
|---|---|
exp | Yes |
id | No |
jwt | No |
uploaded_at | Yes |
uuid | Yes |
MCPServerConfig
Actions: create, write, delete
| Field | Tracked |
|---|---|
allow_in_plan_mode | Yes |
api_key_header | Yes |
api_key_value | Yes |
api_key_value_key_id | No |
auth_type | Yes |
availability | Yes |
created_at | No |
created_by | Yes |
custom_headers | Yes |
custom_headers_key_id | No |
description | Yes |
display_name | Yes |
enabled | Yes |
forward_coder_headers | Yes |
group_acl | Yes |
icon_url | Yes |
id | No |
model_intent | Yes |
oauth2_auth_url | Yes |
oauth2_client_id | Yes |
oauth2_client_registration | Yes |
oauth2_client_secret | Yes |
oauth2_client_secret_key_id | No |
oauth2_resource | Yes |
oauth2_revocation_url | Yes |
oauth2_scopes | Yes |
oauth2_token_url | Yes |
organization_id | No |
signing_secret | Yes |
signing_secret_key_id | No |
slug | Yes |
tool_allow_list | Yes |
tool_deny_list | Yes |
transport | Yes |
updated_at | No |
updated_by | Yes |
url | Yes |
user_acl | Yes |
NotificationTemplate
| Field | Tracked |
|---|---|
actions | Yes |
body_template | Yes |
enabled_by_default | Yes |
group | Yes |
id | No |
kind | Yes |
method | Yes |
name | Yes |
title_template | Yes |
NotificationsSettings
| Field | Tracked |
|---|---|
id | No |
notifier_paused | Yes |
OAuth2ProviderApp
| Field | Tracked |
|---|---|
callback_url | Yes |
client_id_issued_at | No |
client_secret_expires_at | Yes |
client_type | Yes |
client_uri | Yes |
contacts | Yes |
created_at | No |
dynamically_registered | Yes |
grant_types | Yes |
icon | Yes |
id | No |
jwks | Yes |
jwks_uri | Yes |
logo_uri | Yes |
name | Yes |
policy_uri | Yes |
redirect_uris | Yes |
registration_access_token | Yes |
registration_client_uri | Yes |
response_types | Yes |
scope | Yes |
software_id | Yes |
software_version | Yes |
token_endpoint_auth_method | Yes |
tos_uri | Yes |
updated_at | No |
OAuth2ProviderAppSecret
| Field | Tracked |
|---|---|
app_id | No |
created_at | No |
display_secret | No |
hashed_secret | No |
id | No |
last_used_at | No |
secret_prefix | No |
OAuth2ProviderSettings
| Field | Tracked |
|---|---|
dynamic_client_registration_enabled | Yes |
id | No |
Organization
| Field | Tracked |
|---|---|
created_at | No |
default_org_member_roles | Yes |
deleted | Yes |
description | Yes |
display_name | Yes |
icon | Yes |
id | No |
is_default | Yes |
members_can_disable_skills | Yes |
name | Yes |
shareable_workspace_owners | Yes |
updated_at | Yes |
OrganizationSyncSettings
| Field | Tracked |
|---|---|
assign_default | Yes |
field | Yes |
mapping | Yes |
PrebuildsSettings
| Field | Tracked |
|---|---|
id | No |
reconciliation_paused | Yes |
RoleSyncSettings
| Field | Tracked |
|---|---|
field | Yes |
mapping | Yes |
Skill
Actions: create, write, delete
| Field | Tracked |
|---|---|
action | Yes |
content | Yes |
created_at | No |
description | Yes |
display_name | Yes |
enabled | Yes |
group_acl | Yes |
id | Yes |
model_invocable | Yes |
name | Yes |
organization_id | Yes |
project_id | Yes |
updated_at | No |
user_acl | Yes |
user_id | Yes |
Template
Actions: write, delete
| Field | Tracked |
|---|---|
active_version_id | Yes |
activity_bump | Yes |
agents_allowed | Yes |
allow_user_autostart | Yes |
allow_user_autostop | Yes |
allow_user_cancel_workspace_jobs | Yes |
allow_workspace_renames | Yes |
autostart_block_days_of_week | Yes |
autostop_requirement_days_of_week | Yes |
autostop_requirement_weeks | Yes |
cors_behavior | Yes |
created_at | No |
created_by | Yes |
created_by_avatar_url | No |
created_by_name | No |
created_by_username | No |
default_ttl | Yes |
deleted | No |
deprecated | Yes |
description | Yes |
disable_module_cache | Yes |
display_name | Yes |
failure_ttl | Yes |
group_acl | Yes |
icon | Yes |
id | Yes |
max_port_sharing_level | Yes |
name | Yes |
organization_display_name | No |
organization_icon | No |
organization_id | No |
organization_name | No |
provisioner | Yes |
require_active_version | Yes |
time_til_autostop_notify | Yes |
time_til_dormant | Yes |
time_til_dormant_autodelete | Yes |
updated_at | No |
use_classic_parameter_flow | Yes |
user_acl | Yes |
TemplateVersion
Actions: create, write
| Field | Tracked |
|---|---|
archived | Yes |
created_at | No |
created_by | Yes |
created_by_avatar_url | No |
created_by_name | No |
created_by_username | No |
external_auth_providers | No |
has_external_agent | No |
id | Yes |
job_id | No |
message | No |
name | Yes |
organization_id | No |
readme | Yes |
script_order_data_source_count | No |
script_order_rule_count | No |
source_example_id | No |
template_id | Yes |
updated_at | No |
User
Actions: create, write, delete
| Field | Tracked |
|---|---|
avatar_url | No |
chat_spend_limit_micros | Yes |
created_at | No |
deleted | Yes |
email | Yes |
github_com_user_id | No |
hashed_one_time_passcode | No |
hashed_password | Yes |
id | Yes |
is_service_account | Yes |
is_system | Yes |
last_seen_at | No |
login_type | Yes |
name | Yes |
one_time_passcode_expires_at | Yes |
quiet_hours_schedule | Yes |
rbac_roles | Yes |
status | Yes |
updated_at | No |
username | Yes |
UserSecret
Actions: create, write, delete
| Field | Tracked |
|---|---|
created_at | No |
description | Yes |
enabled | Yes |
env_name | Yes |
file_path | Yes |
id | Yes |
name | Yes |
updated_at | No |
user_id | Yes |
value | Yes |
value_key_id | No |
WorkspaceBuild
Actions: start, stop
| Field | Tracked |
|---|---|
build_number | No |
created_at | No |
daily_cost | No |
deadline | No |
has_external_agent | No |
id | No |
initiator_by_avatar_url | No |
initiator_by_name | No |
initiator_by_username | No |
initiator_id | No |
job_id | No |
max_deadline | No |
notified_autostop_deadline | No |
reason | No |
template_version_id | Yes |
template_version_preset_id | No |
transition | No |
updated_at | No |
workspace_id | No |
WorkspaceProxy
| Field | Tracked |
|---|---|
created_at | Yes |
deleted | No |
derp_enabled | Yes |
derp_only | Yes |
display_name | Yes |
icon | Yes |
id | Yes |
name | Yes |
region_id | Yes |
token_hashed_secret | Yes |
updated_at | No |
url | Yes |
version | Yes |
wildcard_hostname | Yes |
WorkspaceTable
| Field | Tracked |
|---|---|
automatic_updates | Yes |
autostart_schedule | Yes |
created_at | No |
deleted | No |
deleting_at | Yes |
dormant_at | Yes |
favorite | Yes |
group_acl | Yes |
id | Yes |
last_used_at | No |
name | Yes |
next_start_at | Yes |
organization_id | No |
owner_id | Yes |
template_id | Yes |
ttl | Yes |
updated_at | No |
user_acl | Yes |
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 ofresource_id.action- The action applied to a resource, such ascreateordelete. For more actions, refer to the CoderSDK package documentation.username- The username of the user who triggered the action. You can also usemeas 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 formatYYYY-MM-DD.date_to- The inclusive end date with formatYYYY-MM-DD.build_reason- The reason for the workspace build, ifresource_typeisworkspace_build. Refer to the CoderSDK package documentation for a list of valid build reasons.
Capture and export 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=""
Purge old audit logs
Warning
Audit Logs provide critical security and compliance information. Purging Audit Logs might 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 FULLacquires an exclusive lock on the table, blocking all reads and writes. For more information, see the PostgreSQL VACUUM documentation.
You can 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 allow ample time for the operation to complete and minimize impact to users
-
Stop all running instances of
coderdto prevent connection errors while the table is locked. The actual steps for this will depend on your particular deployment setup. For example, if yourcoderddeployment is running on Kubernetes:kubectl scale deployment coder --replicas=0 -n coder -
Terminate lingering connections before running the
VACUUMoperation to make sure it starts immediatelySELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = 'coder' AND pid <> pg_backend_pid(); -
Only
coderdneeds 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_logstables, consider running theDELETEoperation during maintenance windows as it might 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.