企业审计日志

版本: v0.34.0+ | 8种事件类型 | 4级风险评估 | 敏感字段自动脱敏

核心特性

📋 8 种事件类型: browser / permission / file / db / api / cowork / auth / system 全域覆盖
⚠️ 4 级风险评估: low / medium / high / critical 自动判定与实时告警
🔒 敏感字段脱敏: 22 类字段自动识别与递归脱敏处理
🪝 Hook 系统集成: 自动捕获 21 种 Hook 事件映射为审计记录
📊 统计分析: 按事件类型/风险等级/操作者/时间趋势多维分析
📤 灵活导出: 支持 JSON / CSV 格式导出与数据保留策略

系统架构

┌─────────────────────────────────────────────────┐
│            EnterpriseAuditLogger                  │
├─────────────────────────────────────────────────┤
│                                                   │
│  ┌──────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Risk     │  │ Sanitizer│  │ Hook System  │  │
│  │ Assessor │  │ (脱敏)   │  │ Integration  │  │
│  └────┬─────┘  └────┬─────┘  └──────┬────────┘  │
│       │              │               │            │
│  ┌────▼──────────────▼───────────────▼────────┐  │
│  │         Unified Event Bus                  │  │
│  │    (highRiskEvent / cleared / logged)       │  │
│  └────────┬──────────────────┬───────────────┘  │
│           │                  │                    │
│  ┌────────▼──────┐  ┌───────▼──────────────┐   │
│  │ Memory Buffer │  │ SQLite Persistence   │   │
│  │ (max 2000)    │  │ (enterprise_audit_log)│   │
│  └───────────────┘  └──────────────────────┘   │
│                                                   │
│  ┌──────────────────────────────────────────┐    │
│  │  18 IPC Handlers (audit-ipc.js)          │    │
│  │  审计(4) + 合规(6) + DSR(6) + 保留(2)    │    │
│  └──────────────────────────────────────────┘    │
└─────────────────────────────────────────────────┘

系统概述

EnterpriseAuditLogger 是 ChainlessChain 桌面端的企业级统一审计日志模块，继承自 EventEmitter，负责聚合所有子系统（浏览器自动化、权限管理、文件操作、数据库、API 调用、多智能体协作、认证、系统运维）的审计事件，提供统一的日志记录、风险评估、敏感字段脱敏、查询导出与统计分析能力。

源码路径：desktop-app-vue/src/main/audit/enterprise-audit-logger.js

核心特性：

8 种事件类型覆盖全业务域
4 级风险自动评估（low / medium / high / critical）
敏感字段自动脱敏（密码、令牌、密钥等 22 类字段）
高风险操作实时告警（通过 EventEmitter 事件）
Hook 系统集成，自动捕获 21 种 Hook 事件
内存缓冲 + SQLite 持久化双写
支持 JSON / CSV 导出
数据保留策略（自动清理过期日志）

核心功能

统一事件记录

所有子系统的审计事件通过 log(eventType, operation, details) 方法统一写入。每条日志包含：

字段	类型	说明
`id`	string	UUID v4 唯一标识
`timestamp`	string	ISO 8601 时间戳
`eventType`	string	事件类型（8 种之一）
`operation`	string	操作名称
`actor`	string	操作者标识，默认 `system`
`riskLevel`	string	自动评估的风险等级
`success`	boolean	操作是否成功
`details`	object	脱敏后的操作详情
`context`	object	附加上下文信息
`errorMessage`	string	错误消息（失败时）
`duration`	number	操作耗时（毫秒）
`ipAddress`	string	来源 IP 地址
`sessionId`	string	会话标识
`createdAt`	number	创建时间戳（Unix 毫秒）

日志同时写入 SQLite 数据库和内存缓冲区。当内存缓冲超过 maxMemoryEntries（默认 2000）时，自动淘汰最旧记录。

风险评估

assessRisk(eventType, operation, details) 方法按以下优先级自动判定风险等级：

Critical：操作名命中关键操作列表（如 delete_database、bypass_security）
High：操作名命中对应事件类型的高风险操作列表
Medium：操作名或详情匹配敏感关键词模式（password、admin、delete、export 等 12 种），或事件类型为 auth / permission
Low：以上均未命中时的默认等级

敏感字段脱敏

sanitizeData(data) 方法在写入前对所有日志详情递归脱敏：

字段名匹配：22 类敏感字段名（不区分大小写）自动替换为 ***REDACTED***
大二进制数据：字段名含 image、screenshot、base64 且值超过 5000 字符时，替换为 [BINARY_DATA: N bytes]
超长字符串：超过 1000 字符的字符串截断并追加 ...[TRUNCATED]
递归深度：最大递归 10 层，超出后替换为 [MAX_DEPTH_EXCEEDED]

高风险告警

当 alertOnHighRisk 开启（默认 true）且日志风险权重 >= 3（即 high 或 critical）时：

发出 highRiskEvent 事件，携带完整日志条目
输出警告日志（包含事件类型、操作名、风险等级）

外部模块可监听此事件以触发通知、邮件或其他告警机制：

javascript

auditLogger.on("highRiskEvent", (entry) => {
  // 发送告警通知
  notifyAdmin(entry);
});

Hook 系统集成

当传入 hookSystem 实例时，审计日志自动监听 Hook 系统的 hookExecuted 事件，将 21 种 Hook 事件映射为对应的审计事件类型：

Hook 事件	审计事件类型
`PreIPCCall` / `PostIPCCall` / `IPCError`	`api`
`PreToolUse` / `PostToolUse` / `ToolError`	`system`
`SessionStart` / `SessionEnd`	`auth`
`PreCompact` / `PostCompact`	`system`
`PreFileAccess` / `PostFileAccess` / `FileModified`	`file`
`AgentStart` / `AgentStop` / `TaskAssigned` / `TaskCompleted`	`cowork`
`MemorySave` / `MemoryLoad`	`db`

事件类型

系统定义了 8 种事件类型，覆盖全业务域：

事件类型	常量值	说明
`browser`	`EventType.BROWSER`	浏览器自动化操作（点击、输入、脚本执行）
`permission`	`EventType.PERMISSION`	权限变更（授权、撤销、角色管理）
`file`	`EventType.FILE`	文件操作（读写、删除、移动）
`db`	`EventType.DB`	数据库操作（建表、删除、Schema 变更）
`api`	`EventType.API`	API 调用（IPC 请求、批量操作）
`cowork`	`EventType.COWORK`	多智能体协作（Agent 生命周期、任务分配）
`auth`	`EventType.AUTH`	认证事件（登录、登出、密码重置）
`system`	`EventType.SYSTEM`	系统运维（关机、配置变更、插件安装）

风险等级

等级	权重	说明
`low`	1	常规操作，无安全风险
`medium`	2	涉及敏感数据或权限的操作，需关注
`high`	3	高风险操作，触发实时告警
`critical`	4	关键操作，可能造成不可逆影响，立即告警

高风险操作

以下操作被自动标记为 high 风险：

permission（权限类）

操作	说明
`grant_admin`	授予管理员权限
`revoke_all`	撤销所有权限
`delete_role`	删除角色
`elevate_privilege`	提升权限

auth（认证类）

操作	说明
`login_failed`	登录失败
`password_reset`	密码重置
`mfa_disabled`	多因素认证禁用
`account_locked`	账户锁定

db（数据库类）

操作	说明
`drop_table`	删除表
`truncate`	清空表数据
`delete_all`	删除所有记录
`schema_change`	Schema 变更

file（文件类）

操作	说明
`delete_recursive`	递归删除
`chmod_777`	设置完全开放权限
`move_system_file`	移动系统文件

system（系统类）

操作	说明
`shutdown`	系统关闭
`config_change`	配置变更
`plugin_install`	插件安装
`update_apply`	更新应用

browser（浏览器类）

操作	说明
`desktop_click`	桌面级点击操作
`desktop_type`	桌面级输入操作
`execute_script`	执行脚本

api（接口类）

操作	说明
`bulk_delete`	批量删除
`export_all`	全量导出
`key_rotation`	密钥轮转

cowork（协作类）

操作	说明
`agent_spawn`	生成 Agent
`sandbox_escape`	沙箱逃逸
`tool_override`	工具覆盖

关键操作（Critical）

以下操作被自动标记为 critical 风险（最高级别），不论事件类型：

操作	说明
`delete_database`	删除数据库
`factory_reset`	恢复出厂设置
`bypass_security`	绕过安全机制
`export_private_keys`	导出私钥
`disable_audit`	禁用审计日志
`root_access`	获取 root 权限
`sandbox_escape`	沙箱逃逸
`inject_code`	代码注入

判定方式：操作名（转小写后）包含上述任一关键词即命中。

配置参考

构造函数选项

javascript

const { EnterpriseAuditLogger } = require("./audit/enterprise-audit-logger");

const auditLogger = new EnterpriseAuditLogger({
  database, // SQLite 数据库实例（可选，无则仅内存缓冲）
  hookSystem, // Hook 系统实例（可选，传入后自动监听 Hook 事件）
  enabled: true, // 是否启用审计（默认 true）
  maxMemoryEntries: 2000, // 内存缓冲区最大条目数（默认 2000）
  alertOnHighRisk: true, // 是否对 high/critical 操作发出告警事件（默认 true）
});

单例管理

javascript

const {
  getEnterpriseAuditLogger,
  resetEnterpriseAuditLogger,
} = require("./audit/enterprise-audit-logger");

// 获取或创建单例
const logger = getEnterpriseAuditLogger({ database, hookSystem });

// 销毁单例（释放资源）
resetEnterpriseAuditLogger();

API 参考

log(eventType, operation, details)

记录一条审计日志。

参数：

参数	类型	必填	说明
`eventType`	string	是	事件类型（8 种之一）
`operation`	string	是	操作名称
`details`	object	否	操作详情（自动脱敏），可包含 `actor`、`success`、`context`、`error`、`duration`、`ipAddress`、`sessionId`

返回值：{ success: boolean, data?: { id, riskLevel }, error?: string }

query(filters)

分页查询审计日志。

过滤器：

字段	类型	说明
`eventType`	string	按事件类型筛选
`operation`	string	按操作名模糊匹配
`actor`	string	按操作者精确匹配
`riskLevel`	string	按风险等级筛选
`startTime`	string	起始时间（ISO 8601）
`endTime`	string	结束时间（ISO 8601）
`successOnly`	boolean	仅返回成功记录
`sessionId`	string	按会话 ID 筛选
`page`	number	页码（默认 1）
`pageSize`	number	每页大小（默认 50，最大 500）

返回值：{ success, data: { logs, pagination: { page, pageSize, total, totalPages } } }

getLogDetail(id)

获取单条日志详情。

参数：id - 日志条目 UUID

返回值：{ success, data: logEntry } 或 { success: false, error }

getStatistics(timeRange)

获取指定时间范围内的统计分析数据。

参数：

字段	类型	说明
`startTime`	string	起始时间，默认 7 天前
`endTime`	string	结束时间，默认当前时间
`period`	string	趋势粒度：`hour` / `day` / `week` / `month`

返回值：

javascript

{
  success: true,
  data: {
    timeRange: { startTime, endTime },
    summary: { total, successCount, failureCount, highRiskCount },
    byEventType: { browser: 10, auth: 5, ... },
    byRiskLevel: { low: 50, medium: 10, high: 3, critical: 1 },
    topActors: [{ actor: 'admin', count: 20 }, ...],
    trend: [{ period: '2026-02-25', count: 15 }, ...]
  }
}

exportLogs(format, filters)

导出审计日志。

参数：

参数	类型	说明
`format`	string	导出格式：`json`（默认）或 `csv`
`filters`	object	同 `query()` 的过滤器（不含分页参数）

返回值：{ success, data: string, meta: { format, count, exportedAt } }

CSV 格式包含以下列：id, timestamp, event_type, operation, actor, risk_level, success, error_message, duration, session_id

applyRetentionPolicy(policy)

应用数据保留策略，清理过期日志。

参数：

字段	类型	默认值	说明
`retentionDays`	number	90	普通日志保留天数
`maxRecords`	number	100000	最大记录数（超出则删除最旧记录）
`keepHighRisk`	boolean	true	是否保留高风险日志更长时间
`highRiskRetentionDays`	number	365	高风险日志保留天数

返回值：{ success, data: { deletedCount, remainingCount?, source } }

便捷方法

每种事件类型均有对应的便捷方法，省略 eventType 参数：

javascript

await auditLogger.logBrowser("navigate", { url: "https://example.com" });
await auditLogger.logPermission("grant_admin", {
  actor: "admin",
  target: "user1",
});
await auditLogger.logFile("read", { path: "/data/config.json" });
await auditLogger.logDb("insert", { table: "notes", count: 1 });
await auditLogger.logApi("request", { method: "GET", url: "/api/users" });
await auditLogger.logCowork("agent_spawn", { agentId: "coder-01" });
await auditLogger.logAuth("login", {
  actor: "user@example.com",
  success: true,
});
await auditLogger.logSystem("config_change", { key: "theme", value: "dark" });

wrap(eventType, operation, fn)

包装函数，自动记录其执行结果和耗时：

javascript

const safeFn = auditLogger.wrap("api", "fetch_users", async (params) => {
  return await fetchUsers(params);
});

// 调用时自动记录审计日志
await safeFn({ page: 1 });

getQuickStats()

获取内存中的快速统计（无数据库查询）：

javascript

const { data } = auditLogger.getQuickStats();
// { totalLogs, byEventType, byRiskLevel, memoryBufferSize, tableInitialized }

clearMemoryBuffer()

清空内存缓冲区和统计缓存，发出 cleared 事件。

destroy()

销毁审计日志实例，释放所有资源和事件监听器。

IPC 接口

审计系统通过 audit-ipc.js 注册了 18 个 IPC 处理器，分为 4 组：

审计日志（4 个）

IPC 频道	说明	参数
`audit:query-logs`	分页查询审计日志	`filters` 对象
`audit:get-log-detail`	获取单条日志详情	`id` 字符串
`audit:export-logs`	导出日志	`format`, `filters`
`audit:get-statistics`	获取统计分析	`timeRange` 对象

合规管理（6 个）

IPC 频道	说明
`compliance:get-policies`	获取合规策略列表
`compliance:create-policy`	创建合规策略
`compliance:update-policy`	更新合规策略
`compliance:delete-policy`	删除合规策略
`compliance:check-compliance`	执行合规检查
`compliance:generate-report`	生成合规报告

数据主体请求 DSR（6 个）

IPC 频道	说明
`dsr:create-request`	创建数据主体请求
`dsr:list-requests`	列出 DSR 请求
`dsr:get-request-detail`	获取 DSR 详情
`dsr:process-request`	处理待处理的 DSR
`dsr:approve-request`	审批通过 DSR
`dsr:export-subject-data`	导出数据主体的全部数据

数据保留（2 个）

IPC 频道	说明
`retention:apply-policy`	应用数据保留策略
`retention:preview-deletion`	预览将被删除的数据

数据库 Schema

enterprise_audit_log 表

sql

CREATE TABLE IF NOT EXISTS enterprise_audit_log (
  id            TEXT PRIMARY KEY,
  timestamp     TEXT NOT NULL,
  event_type    TEXT NOT NULL,
  operation     TEXT NOT NULL,
  actor         TEXT DEFAULT 'system',
  risk_level    TEXT NOT NULL DEFAULT 'low',
  success       INTEGER NOT NULL DEFAULT 1,
  details       TEXT,          -- JSON 字符串
  context       TEXT,          -- JSON 字符串
  error_message TEXT,
  duration      INTEGER,       -- 毫秒
  ip_address    TEXT,
  session_id    TEXT,
  created_at    INTEGER NOT NULL  -- Unix 毫秒时间戳
);

索引

sql

CREATE INDEX IF NOT EXISTS idx_audit_timestamp  ON enterprise_audit_log(timestamp);
CREATE INDEX IF NOT EXISTS idx_audit_event_type ON enterprise_audit_log(event_type);
CREATE INDEX IF NOT EXISTS idx_audit_risk_level ON enterprise_audit_log(risk_level);
CREATE INDEX IF NOT EXISTS idx_audit_actor      ON enterprise_audit_log(actor);
CREATE INDEX IF NOT EXISTS idx_audit_created_at ON enterprise_audit_log(created_at);

使用示例

基本初始化

javascript

const { EnterpriseAuditLogger } = require("./audit/enterprise-audit-logger");
const { getDatabase } = require("./database");
const { getHookSystem } = require("./hooks");

const auditLogger = new EnterpriseAuditLogger({
  database: getDatabase(),
  hookSystem: getHookSystem(),
  enabled: true,
  maxMemoryEntries: 2000,
  alertOnHighRisk: true,
});

记录认证事件

javascript

// 登录成功
await auditLogger.logAuth("login", {
  actor: "did:key:z6Mk...",
  success: true,
  ipAddress: "192.168.1.100",
  sessionId: "sess-abc-123",
  duration: 320,
});

// 登录失败（自动标记为 high 风险）
await auditLogger.logAuth("login_failed", {
  actor: "unknown",
  success: false,
  error: "Invalid credentials",
  ipAddress: "10.0.0.55",
});

记录权限变更

javascript

await auditLogger.logPermission("grant_admin", {
  actor: "admin@company.com",
  targetUser: "user@company.com",
  role: "admin",
  context: { reason: "Promoted to team lead" },
});

监听高风险事件

javascript

auditLogger.on("highRiskEvent", (entry) => {
  console.warn(
    `[ALERT] ${entry.riskLevel}: ${entry.eventType}/${entry.operation}`,
  );
  // 触发告警通知逻辑
});

查询与分页

javascript

const result = await auditLogger.query({
  eventType: "auth",
  riskLevel: "high",
  startTime: "2026-02-01T00:00:00Z",
  endTime: "2026-02-28T23:59:59Z",
  page: 1,
  pageSize: 20,
});

if (result.success) {
  console.log(`共 ${result.data.pagination.total} 条记录`);
  result.data.logs.forEach((log) => {
    console.log(`${log.timestamp} [${log.riskLevel}] ${log.operation}`);
  });
}

使用 wrap 自动审计

javascript

const { EventType } = require("./audit/enterprise-audit-logger");

const auditedDelete = auditLogger.wrap(
  EventType.DB,
  "delete_user_data",
  async (userId) => {
    return await database.run("DELETE FROM user_data WHERE user_id = ?", [
      userId,
    ]);
  },
);

// 执行时自动记录审计日志（含耗时和结果）
await auditedDelete("user-123");

查询与导出

渲染进程调用示例

javascript

// 查询日志
const logs = await window.electronAPI.invoke("audit:query-logs", {
  eventType: "auth",
  riskLevel: "high",
  page: 1,
  pageSize: 50,
});

// 获取统计信息
const stats = await window.electronAPI.invoke("audit:get-statistics", {
  startTime: "2026-02-01T00:00:00Z",
  endTime: "2026-02-28T23:59:59Z",
  period: "day",
});

// 导出为 CSV
const csvData = await window.electronAPI.invoke("audit:export-logs", "csv", {
  eventType: "permission",
  startTime: "2026-01-01T00:00:00Z",
});

// 应用保留策略
const retention = await window.electronAPI.invoke("retention:apply-policy", {
  retentionDays: 90,
  maxRecords: 100000,
  keepHighRisk: true,
  highRiskRetentionDays: 365,
});

导出格式说明

JSON 格式：标准 JSON 数组，每个元素为完整日志对象，包含所有字段。

CSV 格式：首行为表头，包含 10 个字段：

id,timestamp,event_type,operation,actor,risk_level,success,error_message,duration,session_id

CSV 自动处理逗号、双引号和换行符的转义。

故障排除

审计日志未写入数据库

现象：日志仅存在内存缓冲，查询结果为空。

排查：

确认构造函数传入了有效的 database 实例
检查 _tableInitialized 是否为 true（通过 getQuickStats() 查看）
查看日志中是否有 [EnterpriseAuditLogger] Failed to initialize table 错误

审计日志已禁用

现象：log() 返回 { success: false, error: 'Audit logger is disabled' }。

解决：检查构造函数 enabled 参数是否被设为 false。

高风险告警未触发

排查：

确认 alertOnHighRisk 为 true
确认操作名正确包含在高风险操作列表中
确认已注册 highRiskEvent 事件监听器

Hook 事件未被捕获

排查：

确认构造函数传入了 hookSystem 实例
确认 Hook 系统正常运行并发出 hookExecuted 事件
查看日志中是否有 HookSystem listeners registered 确认信息

内存缓冲溢出

现象：历史日志丢失，仅保留最近的条目。

说明：内存缓冲遵循 FIFO 策略，超过 maxMemoryEntries 后自动淘汰最旧记录。如需保留全部日志，确保数据库实例已正确传入。

敏感字段未脱敏

排查：确认字段名是否在 22 种敏感字段列表中（不区分大小写匹配）。支持的字段名包括：

password, passwd, pwd, token, accessToken, refreshToken,
access_token, refresh_token, secret, clientSecret, client_secret,
apiKey, api_key, apikey, credential, credentials,
privateKey, private_key, authorization, cookie, pin, cvv, ssn

关键文件

文件	职责
`desktop-app-vue/src/main/audit/enterprise-audit-logger.js`	企业审计日志核心模块
`desktop-app-vue/src/main/audit/audit-ipc.js`	审计 IPC 处理器 (18 handlers)
`desktop-app-vue/src/main/audit/compliance-manager.js`	合规策略管理
`desktop-app-vue/src/main/audit/dsr-handler.js`	数据主体请求处理
`desktop-app-vue/src/main/hooks/index.js`	Hook 系统 (21 种事件)

企业审计日志 ​

核心特性 ​

系统架构 ​

系统概述 ​

核心功能 ​

统一事件记录 ​

风险评估 ​

敏感字段脱敏 ​

高风险告警 ​

Hook 系统集成 ​

事件类型 ​

风险等级 ​

高风险操作 ​

permission（权限类） ​

auth（认证类） ​

db（数据库类） ​

file（文件类） ​

system（系统类） ​

browser（浏览器类） ​

api（接口类） ​

cowork（协作类） ​

关键操作（Critical） ​

配置参考 ​

构造函数选项 ​

单例管理 ​

API 参考 ​

log(eventType, operation, details) ​

query(filters) ​

getLogDetail(id) ​

getStatistics(timeRange) ​

exportLogs(format, filters) ​

applyRetentionPolicy(policy) ​

便捷方法 ​

wrap(eventType, operation, fn) ​

getQuickStats() ​

clearMemoryBuffer() ​

destroy() ​

IPC 接口 ​

审计日志（4 个） ​

合规管理（6 个） ​

数据主体请求 DSR（6 个） ​

数据保留（2 个） ​

数据库 Schema ​

enterprise_audit_log 表 ​

索引 ​

使用示例 ​

基本初始化 ​

记录认证事件 ​

记录权限变更 ​

监听高风险事件 ​

查询与分页 ​

使用 wrap 自动审计 ​

查询与导出 ​

渲染进程调用示例 ​

导出格式说明 ​

故障排除 ​

审计日志未写入数据库 ​

审计日志已禁用 ​

高风险告警未触发 ​

Hook 事件未被捕获 ​

内存缓冲溢出 ​

敏感字段未脱敏 ​

关键文件 ​

相关文档 ​

企业审计日志

核心特性

系统架构

系统概述

核心功能

统一事件记录

风险评估

敏感字段脱敏

高风险告警

Hook 系统集成

事件类型

风险等级

高风险操作

permission（权限类）

auth（认证类）

db（数据库类）

file（文件类）

system（系统类）

browser（浏览器类）

api（接口类）

cowork（协作类）

关键操作（Critical）

配置参考

构造函数选项

单例管理

API 参考

log(eventType, operation, details)

query(filters)

getLogDetail(id)

getStatistics(timeRange)

exportLogs(format, filters)

applyRetentionPolicy(policy)

便捷方法

wrap(eventType, operation, fn)

getQuickStats()

clearMemoryBuffer()

destroy()

IPC 接口

审计日志（4 个）

合规管理（6 个）

数据主体请求 DSR（6 个）

数据保留（2 个）

数据库 Schema

enterprise_audit_log 表

索引

使用示例

基本初始化

记录认证事件

记录权限变更

监听高风险事件

查询与分页

使用 wrap 自动审计

查询与导出

渲染进程调用示例

导出格式说明

故障排除

审计日志未写入数据库

审计日志已禁用

高风险告警未触发

Hook 事件未被捕获

内存缓冲溢出

敏感字段未脱敏

关键文件

相关文档