shithub Public

Watch 1 Fork 0 Star 0
Go · 7787 bytes Raw Blame History
1 // SPDX-License-Identifier: AGPL-3.0-or-later
2
3 // Package audit writes structured rows into the auth_audit_log table for
4 // security-relevant events. The schema is generic — actor, action, target,
5 // meta JSON — so future sprints reuse this for permission changes,
6 // org-membership changes, admin actions, etc.
7 //
8 // Callers MUST NOT put secret material in the meta JSON. The values land
9 // unredacted in the DB; treat the table contents as confidential but
10 // never sensitive (no plaintext passwords, no TOTP secrets, no PATs).
11 package audit
12
13 import (
14 "context"
15 "encoding/json"
16 "errors"
17 "fmt"
18
19 "github.com/jackc/pgx/v5/pgtype"
20
21 usersdb "github.com/tenseleyFlow/shithub/internal/users/sqlc"
22 )
23
24 // DBTX matches sqlc's DBTX so callers can pass *pgxpool.Pool or a tx.
25 type DBTX = usersdb.DBTX
26
27 // Action is a typed action constant. Reuse these across packages so the
28 // set stays tight and grep-able.
29 type Action string
30
31 const (
32 Action2FAEnabled Action = "2fa_enabled"
33 Action2FADisabled Action = "2fa_disabled"
34 ActionRecoveryCodesIssued Action = "recovery_codes_issued"
35 ActionRecoveryCodeUsed Action = "recovery_code_used"
36 ActionRecoveryRegenerated Action = "recovery_codes_regenerated"
37 ActionAdminCleared2FA Action = "admin_cleared_2fa"
38 ActionPasswordChanged Action = "password_changed"
39 ActionPasswordReset Action = "password_reset_consumed"
40 ActionLoginSucceeded Action = "login_succeeded"
41 ActionLoginFailedThrottled Action = "login_failed_throttled"
42 ActionAccountSuspended Action = "account_suspended"
43 ActionSSHKeyAdded Action = "ssh_key_added"
44 ActionSSHKeyDeleted Action = "ssh_key_deleted"
45 ActionPATCreated Action = "pat_created"
46 ActionPATRevoked Action = "pat_revoked"
47 ActionUsernameChanged Action = "username_changed"
48 ActionAccountDeleted Action = "account_deleted"
49 ActionAccountRestored Action = "account_restored"
50 ActionRepoCreated Action = "repo_created"
51 ActionRepoRenamed Action = "repo_renamed"
52 ActionRepoArchived Action = "repo_archived"
53 ActionRepoUnarchived Action = "repo_unarchived"
54 ActionRepoVisibilityChanged Action = "repo_visibility_changed"
55 ActionRepoSoftDeleted Action = "repo_soft_deleted"
56 ActionRepoRestored Action = "repo_restored"
57 ActionRepoHardDeleted Action = "repo_hard_deleted"
58 ActionRepoTransferRequested Action = "repo_transfer_requested"
59 ActionRepoTransferAccepted Action = "repo_transfer_accepted"
60 ActionRepoTransferDeclined Action = "repo_transfer_declined"
61 ActionRepoTransferCanceled Action = "repo_transfer_canceled"
62 ActionRepoTransferExpired Action = "repo_transfer_expired"
63 ActionIssueStateChanged Action = "issue_state_changed"
64 ActionIssueLockChanged Action = "issue_lock_changed"
65 ActionIssueCommentCreated Action = "issue_comment_created"
66 ActionPullStateChanged Action = "pull_state_changed"
67 ActionPullMerged Action = "pull_merged"
68 ActionStarCreated Action = "star_created"
69 ActionStarDeleted Action = "star_deleted"
70 ActionWatchSet Action = "watch_set"
71 ActionWatchUnset Action = "watch_unset"
72 ActionFollowCreated Action = "follow_created"
73 ActionFollowDeleted Action = "follow_deleted"
74 ActionRepoForked Action = "repo_forked"
75 ActionRepoForkSynced Action = "repo_fork_synced"
76
77 // S33 / SR2 H1 — webhook lifecycle. Pre-SR2 webhook create/update
78 // overloaded ActionRepoCreated; delete/toggle/ping/redeliver were
79 // not audited at all. Each event now has its own enum.
80 ActionWebhookCreated Action = "webhook_created"
81 ActionWebhookUpdated Action = "webhook_updated"
82 ActionWebhookDeleted Action = "webhook_deleted"
83 ActionWebhookActiveSet Action = "webhook_active_set"
84 ActionWebhookActiveUnset Action = "webhook_active_unset"
85 ActionWebhookPinged Action = "webhook_pinged"
86 ActionWebhookRedelivered Action = "webhook_redelivered"
87
88 // S41c — Actions secret/variable lifecycle. Metadata must include
89 // names only, never secret values.
90 ActionActionsSecretSet Action = "actions_secret_set"
91 ActionActionsSecretDeleted Action = "actions_secret_deleted"
92 ActionActionsVariableSet Action = "actions_variable_set"
93 ActionActionsVariableDeleted Action = "actions_variable_deleted"
94
95 // S41h — Actions run/job lifecycle. Metadata must stay structural:
96 // run/job ids, status, conclusion, workflow path/name. Never include
97 // event payloads, env, logs, permissions, tokens, or secret values.
98 ActionWorkflowRunCreated Action = "workflow_run_created"
99 ActionWorkflowRunStarted Action = "workflow_run_started"
100 ActionWorkflowRunCompleted Action = "workflow_run_completed"
101 ActionWorkflowJobCreated Action = "workflow_job_created"
102 ActionWorkflowJobStarted Action = "workflow_job_started"
103 ActionWorkflowJobCompleted Action = "workflow_job_completed"
104 ActionWorkflowJobCancelled Action = "workflow_job_cancelled"
105
106 // S34 — site admin actions. Always recorded with the real admin's
107 // id in actor_id; impersonation flows additionally carry the
108 // impersonated user's id in meta.impersonated_user_id.
109 ActionAdminSiteAdminGranted Action = "admin_site_admin_granted"
110 ActionAdminSiteAdminRevoked Action = "admin_site_admin_revoked"
111 ActionAdminUserSuspended Action = "admin_user_suspended"
112 ActionAdminUserUnsuspended Action = "admin_user_unsuspended"
113 ActionAdminUserForceDeleted Action = "admin_user_force_deleted"
114 ActionAdminUserPasswordReset Action = "admin_user_password_reset"
115 ActionAdminRepoForceArchived Action = "admin_repo_force_archived"
116 ActionAdminRepoForceUnarchived Action = "admin_repo_force_unarchived"
117 ActionAdminRepoForceDeleted Action = "admin_repo_force_deleted"
118 ActionAdminJobRetried Action = "admin_job_retried"
119 ActionAdminJobDiscarded Action = "admin_job_discarded"
120 ActionAdminImpersonateStarted Action = "admin_impersonate_started"
121 ActionAdminImpersonateStopped Action = "admin_impersonate_stopped"
122 ActionAdminImpersonateWriteOn Action = "admin_impersonate_write_on"
123 )
124
125 // Target is a typed target-type constant.
126 type Target string
127
128 const (
129 TargetUser Target = "user"
130 TargetRepo Target = "repo"
131 TargetOrg Target = "org"
132 TargetIssue Target = "issue"
133 TargetPull Target = "pull"
134 )
135
136 // Recorder writes audit rows. Bound to the sqlc queries handle.
137 type Recorder struct {
138 q *usersdb.Queries
139 }
140
141 // NewRecorder constructs a recorder.
142 func NewRecorder() *Recorder { return &Recorder{q: usersdb.New()} }
143
144 // Record inserts a single audit-log row. actorID is the user_id of the
145 // actor performing the action (use 0 for system / admin-CLI actions).
146 // targetID is the affected entity (use 0 for actions without a single
147 // concrete target).
148 //
149 // meta MUST be a JSON-serializable map; secrets and PII (tokens, raw
150 // passwords, etc.) MUST NOT appear here.
151 func (r *Recorder) Record(
152 ctx context.Context, db DBTX,
153 actorID int64, action Action, target Target, targetID int64, meta map[string]any,
154 ) error {
155 if action == "" || target == "" {
156 return errors.New("audit: action and target_type required")
157 }
158 if meta == nil {
159 meta = map[string]any{}
160 }
161 metaJSON, err := json.Marshal(meta)
162 if err != nil {
163 return fmt.Errorf("audit: marshal meta: %w", err)
164 }
165 var actorParam pgtype.Int8
166 if actorID != 0 {
167 actorParam = pgtype.Int8{Int64: actorID, Valid: true}
168 }
169 var targetParam pgtype.Int8
170 if targetID != 0 {
171 targetParam = pgtype.Int8{Int64: targetID, Valid: true}
172 }
173 return r.q.InsertAuditLog(ctx, db, usersdb.InsertAuditLogParams{
174 ActorID: actorParam,
175 Action: string(action),
176 TargetType: string(target),
177 TargetID: targetParam,
178 Meta: metaJSON,
179 })
180 }
181