Audit Log

對應主管要求 ① 完整稽核。 Argus 的設計原則：任何寫入操作必有對應 audit log；audit log 與業務資料分離儲存；append-only。

一條 audit 紀錄長什麼樣

每筆 audit log 包含：

欄位	範例	說明
timestamp	2026-05-23T08:42:11Z	UTC 時間，server-side 蓋章，client 不可改
actor	user/login_id=alice	誰做的；系統動作為 system/<runner>
actor_ip	10.42.11.7	來源 IP（有 reverse proxy 時取 X-Real-IP）
action	bb.issue.approve	動作名（小寫.點分）
resource	projects/play/issues/42	對象資源
resource_type	issue	對象型別
severity	info / notice / warning / critical	嚴重度
request_payload	{...}	請求內容（敏感欄位會被 redact）
response_status	ok / denied / error	結果
correlation_id	req-2026-...	同一個 HTTP 請求 / RPC 的所有 audit 紀錄共用
extra	{...}	動作特定欄位（例：approve 會帶 approval_step）

寫進 audit log 的動作

只列會被寫的，沒列的不會寫：

認證 / 身份

• bb.auth.login — 登入成功
• bb.auth.login.fail — 登入失敗（含原因；連續失敗會抬升 severity）
• bb.auth.logout
• bb.auth.mfa.enable / disable
• bb.auth.password.change / reset
• bb.user.create / update / deactivate
• bb.role.assign / revoke

變更生命週期

• bb.plan.create / update / cancel
• bb.plancheck.run / complete
• bb.issue.create / update / comment / approve / reject / cancel
• bb.rollout.create / start / pause / resume / cancel
• bb.task.update / skip
• bb.taskrun.start / done / fail
• bb.release.publish / archive

資產 / 設定

• bb.instance.create / update / delete
• bb.database.transfer / sync
• bb.environment.create / update / delete
• bb.setting.update（特別敏感 → severity = notice）
• bb.idp.create / update / delete（severity = notice）

稽核自身

• bb.auditlog.query（誰查了 audit）
• bb.auditlog.export

「誰查了 audit log」這件事本身會被記錄。

儲存與留存

• 寫入：以 transaction commit 寫進 metastore；commit 成功才視為「動作完成」
• 表：audit_log，append-only（無 update，無 delete API）
• 留存：預設 365 天；可在 Settings → Audit → Retention 調整
• 歸檔：超過保留期的記錄可自動歸檔到外部存儲（S3-compatible / 本地 fs / NFS）
• 完整性：每筆 entry 帶 prev_hash，形成 hash chain；定期由 audit-verifier 驗證

完整性驗證細節請見 docs/modules/audit-internal.md。

查詢

在 UI

Audit Log（左側 sidebar，需 bb.auditLog.read）。

可以篩：

• 時間範圍
• actor
• action（多選）
• resource_type / resource
• severity
• response_status
• correlation_id（用於追同一個請求的所有相關紀錄）

用 API

curl -s -H "Authorization: Bearer $TOKEN" \
  "$ARGUS/v1/auditLogs?filter=resource:projects/play/issues/42" | jq

filter 語法支援 AND / OR：

actor:alice AND action:bb.issue.approve
severity:critical AND timestamp>=2026-05-01T00:00:00Z
resource:projects/play/* AND response_status:denied

完整語法：REST / gRPC API — auditLogs。

用 SQL（緊急 / 大量分析）

直接連 metastore：

SELECT timestamp, actor, action, resource, response_status
FROM audit_log
WHERE actor LIKE 'user/login_id=alice%'
  AND timestamp >= now() - interval '7 days'
ORDER BY timestamp DESC
LIMIT 200;

⚠️ 從 metastore 直接讀繞過 UI 權限。只有極少數人（DBA Lead）應該有此權限，且讀 audit_log 這件事本身會在 PG audit 上記錄。

匯出

Audit Log → Export：

格式	用途
CSV	Excel / Google Sheets 分析
JSON Lines	灌進 ELK / Splunk / BigQuery
Signed manifest	給外部稽核：含 hash chain root，可驗證 tamper-proof

bb.auditlog.export 會被記錄；payload 含篩選條件與輸出檔 hash。

常見問題

哪些欄位會被 redact？

• 密碼 / token / secret 永遠 redact
• IdP claim 中標為 sensitive 的欄位 redact
• SQL 變更內容不被 redact（這是稽核核心）

Argus 自己當機，audit log 會少嗎？

audit log 與業務動作在同一個 transaction 寫入。動作完成 ↔ audit log 寫入。所以「動作完成但 audit 沒寫」不會發生。

但是：runner 啟動的非同步動作（task scheduler、advisor）的 audit log 是 best-effort，會有極少量 race，請以 bb.taskrun.* 為準。

我要證明這份 audit log 沒被改

每筆紀錄帶 prev_hash，定期由 audit-verifier runner 計算 root hash 並產生 manifest。對外提供：

• 月度 hash root 公告（內部 wiki）
• 匯出時的 signed manifest

對外稽核要更強保證，可考慮把月度 root 寫到 trusted timestamping service（roadmap）。

相關

• Release Monitoring
• 認證模式
• 二線運維 SOP
• API：REST / gRPC API — auditLogs