审计追踪Hook：合规审计日志

// audit-trail-hook.ts — 审计追踪Hook核心架构 import { createHash } from 'node:crypto'; import { appendFile, mkdir } from 'node:fs/promises'; import { join } from 'node:path'; // ========== 审计日志条目类型定义 ========== interface AuditEntry { id: string; // 唯一标识 (UUID) timestamp: string; // ISO 8601 时间戳 user: string; // 操作用户 sessionId: string; // 会话ID requestId: string; // 请求ID (用于追踪链路) operationType: string; // 操作类型: create/update/delete/read targetType: string; // 目标类型: file/config/permission targetPath: string; // 目标路径 status: 'success' | 'failure'; errorMessage?: string; beforeHash?: string; // 操作前内容哈希 afterHash?: string; // 操作后内容哈希 previousEntryHash: string; // 上一条审计日志的哈希 (链式结构) entryHash: string; // 本条日志的哈希 } // ========== 审计追踪Hook类 ========== class AuditTrailHook { private logFilePath: string; private lastEntryHash: string = ''; private buffer: AuditEntry[] = []; private readonly FLUSH_INTERVAL = 5000; // 5秒批量写入 constructor(logDir: string) { this.logFilePath = join(logDir, 'audit-trail.chain.log'); this.initFlushTimer(); } // === before Hook: 在操作执行前记录上下文 === async before(hookParams: { user: string; operationType: string; targetType: string; targetPath: string; content?: string; }): Promise<{ auditId: string; beforeHash?: string }> { const beforeHash = hookParams.content ? this.computeHash(hookParams.content) : undefined; return { auditId: crypto.randomUUID(), beforeHash, }; } // === after Hook: 在操作执行后记录完整审计条目 === async after( context: { auditId: string; beforeHash?: string }, result: { user: string; sessionId: string; requestId: string; operationType: string; targetType: string; targetPath: string; status: 'success' | 'failure'; afterContent?: string; errorMessage?: string; }, ): Promise<void> { const afterHash = result.afterContent ? this.computeHash(result.afterContent) : undefined; const entry: AuditEntry = { id: context.auditId, timestamp: new Date().toISOString(), user: result.user, sessionId: result.sessionId, requestId: result.requestId, operationType: result.operationType, targetType: result.targetType, targetPath: result.targetPath, status: result.status, errorMessage: result.errorMessage, beforeHash: context.beforeHash, afterHash, previousEntryHash: this.lastEntryHash, entryHash: '', }; // 计算本条日志的哈希 (包含前一条的哈希，形成链) entry.entryHash = this.computeEntryHash(entry); this.lastEntryHash = entry.entryHash; // 加入缓冲区等待异步写入 this.buffer.push(entry); } private computeHash(content: string): string { return createHash('sha256').update(content).digest('hex'); } private computeEntryHash(entry: Omit<AuditEntry, 'entryHash'>): string { const serialized = JSON.stringify(entry, Object.keys(entry).sort()); return createHash('sha256').update(serialized).digest('hex'); } private initFlushTimer(): void { setInterval(() => this.flush(), this.FLUSH_INTERVAL); } }

// register-operation-audit.ts — 注册操作审计after Hook import { AuditTrailHook } from './audit-trail-hook'; // 初始化全局审计追踪实例 const auditTrail = new AuditTrailHook('./audit-logs'); // ========== after Hook: 文件写操作审计 ========== // 该Hook在所有写操作完成后触发，记录完整操作上下文 tools.hook('after:tool/Write', async (params, result) => { await auditTrail.after( // 从context中恢复before阶段的信息 { auditId: result.context.auditId, beforeHash: result.context.beforeHash }, { user: params._meta?.user || 'unknown', sessionId: params._meta?.sessionId || '', requestId: params._meta?.requestId || '', operationType: 'create_file', targetType: 'file', targetPath: params.file_path, status: result.success ? 'success' : 'failure', afterContent: result.success ? params.content : undefined, errorMessage: result.error || undefined, }, ); }); // ========== after Hook: 文件编辑操作审计 ========== // 记录编辑操作的before/after内容对照 tools.hook('after:tool/Edit', async (params, result) => { await auditTrail.after( { auditId: result.context.auditId, beforeHash: result.context.beforeHash }, { user: params._meta?.user || 'unknown', sessionId: params._meta?.sessionId || '', requestId: params._meta?.requestId || '', operationType: 'edit_file', targetType: 'file', targetPath: params.file_path, status: result.success ? 'success' : 'failure', afterContent: result.success ? result.newContent : undefined, errorMessage: result.error || undefined, }, ); }); // ========== after Hook: 配置变更审计 ========== // 配置变更属于高风险操作，需要额外记录变更详情 tools.hook('after:tool/ConfigUpdate', async (params, result) => { await auditTrail.after( { auditId: result.context.auditId, beforeHash: result.context.beforeHash }, { user: params._meta?.user || 'unknown', sessionId: params._meta?.sessionId || '', requestId: params._meta?.requestId || '', operationType: 'update_config', targetType: 'configuration', targetPath: params.configKey || 'global', status: result.success ? 'success' : 'failure', afterContent: result.success ? JSON.stringify(params.newValue) : undefined, errorMessage: result.error || undefined, }, ); });

// file-change-before-hook.ts — 文件变更before Hook import { readFile } from 'node:fs/promises'; import { createHash } from 'node:crypto'; // before Hook: 在Edit工具执行前捕获文件当前状态 tools.hook('before:tool/Edit', async (params) => { // 仅在需要审计的文件类型上执行 const auditableExtensions = ['.ts', '.js', '.json', '.yaml', '.html', '.py']; if (!auditableExtensions.some(ext => params.file_path.endsWith(ext))) { return { skipAudit: true }; } try { // 读取当前文件内容 (修改前) const beforeContent = await readFile(params.file_path, 'utf-8'); // 计算文件内容的SHA256哈希 const beforeHash = createHash('sha256') .update(beforeContent) .digest('hex'); // 计算文件大小 const fileSize = Buffer.byteLength(beforeContent, 'utf-8'); console.log(`[审计:before] 文件: ${params.file_path}`); console.log(`[审计:before] 修改前哈希: ${beforeHash}`); console.log(`[审计:before] 文件大小: ${fileSize} bytes`); // 返回审计上下文，after Hook将使用这些信息 return { auditId: crypto.randomUUID(), beforeHash, beforeContent, // 内容快照 (高安全级别配置下使用) fileSize, timestamp: Date.now(), }; } catch (err) { // 文件不存在（新建文件场景）或无法读取 console.warn(`[审计:before] 无法读取文件: ${params.file_path}`); return { auditId: crypto.randomUUID(), beforeHash: '', beforeContent: null, fileSize: 0, timestamp: Date.now(), }; } });

// file-change-after-hook.ts — 文件变更after Hook import { createHash } from 'node:crypto'; import { diffLines } from 'diff'; // 文本差异比较库 // after Hook: 在Edit工具执行后捕获文件新状态并生成差异报告 tools.hook('after:tool/Edit', async (params, result) => { // 如果before Hook标记了跳过审计，则同样跳过 if (result.context?.skipAudit) return; const beforeContent = result.context?.beforeContent || ''; const afterContent = result.success ? result.newContent : ''; // 计算修改后文件的SHA256哈希 const afterHash = afterContent ? createHash('sha256').update(afterContent).digest('hex') : ''; // 检测是否发生了实际变更 const hasChanged = beforeContent !== afterContent; if (!hasChanged) { console.log(`[审计:after] 文件 ${params.file_path} 无实际变更，跳过记录`); return; } // 生成文件变更差异报告 const diffReport = generateDiffReport( params.file_path, beforeContent, afterContent, ); // 检测未授权的文件修改 (比对预期哈希) const expectedHash = getExpectedHash(params.file_path); if (expectedHash && afterHash !== expectedHash) { console.warn(`[审计:警告] 检测到未授权的文件修改!`); console.warn(`[审计:警告] 文件: ${params.file_path}`); console.warn(`[审计:警告] 预期哈希: ${expectedHash}`); console.warn(`[审计:警告] 实际哈希: ${afterHash}`); // 触发安全告警 await notifySecurityTeam({ type: 'unauthorized_file_change', filePath: params.file_path, expectedHash, actualHash: afterHash, user: params._meta?.user, timestamp: new Date().toISOString(), }); } // 记录完整的变更审计条目 console.log(`[审计:after] 文件: ${params.file_path}`); console.log(`[审计:after] 修改前哈希: ${result.context?.beforeHash}`); console.log(`[审计:after] 修改后哈希: ${afterHash}`); console.log(`[审计:after] 变更大小: ${diffReport.changes} 处变更`); // 持久化差异报告到审计存储 await appendToAuditLog('file-changes.log', JSON.stringify({ timestamp: new Date().toISOString(), filePath: params.file_path, beforeHash: result.context?.beforeHash, afterHash, diffSummary: diffReport.summary, user: params._meta?.user, }) + '\n'); }); // 生成文件变更差异报告 function generateDiffReport( filePath: string, oldContent: string, newContent: string, ): { changes: number; summary: string; diff: string } { const changes = diffLines(oldContent, newContent); let added = 0; let removed = 0; const diffParts: string[] = []; for (const change of changes) { if (change.added) { added += change.count || 0; diffParts.push(`+ ${change.value}`); } else if (change.removed) { removed += change.count || 0; diffParts.push(`- ${change.value}`); } else { diffParts.push(` ${change.value}`); } } return { changes: changes.filter(c => c.added || c.removed).length, summary: `+${added} -${removed}`, diff: diffParts.join(''), }; }

// tamper-proof-audit.ts — 审计日志防篡改实现 import { createHash, sign, verify } from 'node:crypto'; import { readFile, writeFile, appendFile } from 'node:fs/promises'; // ========== 哈希链日志条目 ========== interface ChainEntry { index: number; // 区块序号 timestamp: string; // 创建时间 data: string; // 审计数据 (JSON序列化) previousHash: string; // 前一条目的哈希 hash: string; // 本条目的哈希 signature: string; // 数字签名 (使用私钥签名) publicKeyId: string; // 签名公钥标识 } // ========== 哈希链管理器 ========== class HashChainManager { private entries: ChainEntry[] = []; private readonly chainFile: string; constructor(chainFile: string) { this.chainFile = chainFile; } // 添加新的审计条目到哈希链 async addEntry(auditData: object): Promise<ChainEntry> { const previousEntry = this.entries[this.entries.length - 1]; const previousHash = previousEntry ? previousEntry.hash : '0'.repeat(64); const index = this.entries.length; const entry: ChainEntry = { index, timestamp: new Date().toISOString(), data: JSON.stringify(auditData), previousHash, hash: '', signature: '', publicKeyId: 'key-001', }; // 计算本条日志的哈希 const hashInput = entry.index + entry.timestamp + entry.data + entry.previousHash; entry.hash = createHash('sha256').update(hashInput).digest('hex'); // 使用私钥对哈希进行数字签名 entry.signature = this.sign(entry.hash); this.entries.push(entry); // 追加到文件 await appendFile(this.chainFile, JSON.stringify(entry) + '\n'); return entry; } // 验证整个链的完整性 async verifyChain(): Promise<{ valid: boolean; brokenEntries: number[]; message: string; }> { const brokenEntries: number[] = []; for (let i = 0; i < this.entries.length; i++) { const entry = this.entries[i]; // 1. 验证哈希是否正确 const hashInput = entry.index + entry.timestamp + entry.data + entry.previousHash; const expectedHash = createHash('sha256').update(hashInput).digest('hex'); if (entry.hash !== expectedHash) { brokenEntries.push(i); continue; } // 2. 验证链式连接是否完整 if (i > 0) { const previousEntry = this.entries[i - 1]; if (entry.previousHash !== previousEntry.hash) { brokenEntries.push(i); } } // 3. 验证数字签名 if (!this.verify(entry.hash, entry.signature, entry.publicKeyId)) { brokenEntries.push(i); } } return { valid: brokenEntries.length === 0, brokenEntries, message: brokenEntries.length === 0 ? '审计日志完整性验证通过' : `发现 ${brokenEntries.length} 条日志被篡改: [${brokenEntries.join(', ')}]`, }; } // 定期生成校验和报告 async generateChecksumReport(): Promise<string> { const lastEntry = this.entries[this.entries.length - 1]; const totalEntries = this.entries.length; // 对整个文件计算哈希 const fileContent = this.entries.map(e => JSON.stringify(e)).join('\n'); const fileHash = createHash('sha256').update(fileContent).digest('hex'); const report = { generatedAt: new Date().toISOString(), totalEntries, lastEntryHash: lastEntry?.hash || '', fileHash, chainValid: await this.verifyChain().then(r => r.valid), }; // 将校验和报告也作为审计条目写入 await this.addEntry({ type: 'checksum_report', report, }); return JSON.stringify(report, null, 2); } private sign(hash: string): string { // 使用HS256 HMAC进行签名 const hmac = createHash('sha256'); hmac.update(hash + process.env.AUDIT_SIGNING_KEY || 'default-key'); return hmac.digest('hex'); } private verify(hash: string, signature: string, keyId: string): boolean { const expected = this.sign(hash); return signature === expected; } }

// scheduled-audit-verify.ts — 定时审计日志完整性校验 import { CronJob } from 'cron'; // 每6小时执行一次审计日志完整性校验 const verifyJob = new CronJob('0 */6 * * *', async () => { console.log('[审计校验] 开始执行定时审计日志完整性检查...'); const chainManager = new HashChainManager('./audit-logs/audit-trail.chain.log'); const result = await chainManager.verifyChain(); if (!result.valid) { // 发现篡改！立即告警 console.error(`[审计校验] 严重: 审计日志被篡改!`); console.error(`[审计校验] 被篡改条目: [${result.brokenEntries.join(', ')}]`); await sendAlert({ severity: 'critical', type: 'audit_log_tampered', brokenEntries: result.brokenEntries, timestamp: new Date().toISOString(), }); } else { console.log(`[审计校验] 审计日志完整性验证通过`); // 生成校验和报告并存储 const report = await chainManager.generateChecksumReport(); console.log(`[审计校验] 校验和报告已生成`); } }); verifyJob.start();

// audit-query-engine.ts — 审计数据查询和筛选引擎 interface AuditQueryFilter { startDate?: string; endDate?: string; users?: string[]; operationTypes?: string[]; targetTypes?: string[]; status?: 'success' | 'failure' | 'all'; minSeverity?: number; } class AuditQueryEngine { private storage: AuditStorage; constructor(storage: AuditStorage) { this.storage = storage; } // 按条件筛选审计记录 async query(filter: AuditQueryFilter): Promise<AuditEntry[]> { let results = await this.storage.loadAll(); if (filter.startDate) { results = results.filter(e => e.timestamp >= filter.startDate); } if (filter.endDate) { results = results.filter(e => e.timestamp <= filter.endDate); } if (filter.users && filter.users.length > 0) { results = results.filter(e => filter.users!.includes(e.user)); } if (filter.operationTypes && filter.operationTypes.length > 0) { results = results.filter(e => filter.operationTypes!.includes(e.operationType), ); } if (filter.targetTypes && filter.targetTypes.length > 0) { results = results.filter(e => filter.targetTypes!.includes(e.targetType)); } if (filter.status && filter.status !== 'all') { results = results.filter(e => e.status === filter.status); } return results.sort((a, b) => a.timestamp.localeCompare(b.timestamp), ); } // 生成操作汇总统计 async generateSummary( filter: AuditQueryFilter, ): Promise<AuditSummary> { const entries = await this.query(filter); const byUser = new Map<string, number>(); const byOperation = new Map<string, number>(); const byStatus = { success: 0, failure: 0 }; for (const entry of entries) { byUser.set(entry.user, (byUser.get(entry.user) || 0) + 1); byOperation.set( entry.operationType, (byOperation.get(entry.operationType) || 0) + 1, ); byStatus[entry.status]++; } return { period: { start: filter.startDate || '', end: filter.endDate || '' }, totalOperations: entries.length, successCount: byStatus.success, failureCount: byStatus.failure, failureRate: entries.length > 0 ? ((byStatus.failure / entries.length) * 100).toFixed(2) + '%' : '0%', topUsers: [...byUser.entries()] .sort((a, b) => b[1] - a[1]) .slice(0, 10) .map(([user, count]) => ({ user, count })), operationBreakdown: [...byOperation.entries()] .map(([type, count]) => ({ type, count })), }; } } // ========== 审计汇总报告类型 ========== interface AuditSummary { period: { start: string; end: string }; totalOperations: number; successCount: number; failureCount: number; failureRate: string; topUsers: { user: string; count: number }[]; operationBreakdown: { type: string; count: number }[]; }

// audit-report-exporter.ts — 审计报告导出 (CSV/PDF) class AuditReportExporter { // 导出为CSV格式 async exportCSV( entries: AuditEntry[], outputPath: string, ): Promise<void> { const headers = [ '时间戳', '用户', '操作类型', '目标类型', '目标路径', '状态', '错误信息', '请求ID', '修改前哈希', '修改后哈希', ]; const rows = entries.map(e => [ e.timestamp, e.user, e.operationType, e.targetType, e.targetPath, e.status, e.errorMessage || '', e.requestId, e.beforeHash || '', e.afterHash || '', ]); const csvContent = [ headers.join(','), ...rows.map(row => row.map(cell => `"${(cell || '').replace(/"/g, '""')}"`).join(','), ), ].join('\n'); // 写入CSV文件 await writeFile(outputPath, '' + csvContent, 'utf-8'); //  = BOM，确保Excel正确识别UTF-8中文 console.log(`[审计报告] CSV报告已生成: ${outputPath}`); console.log(`[审计报告] 包含 ${entries.length} 条审计记录`); } // 生成PDF合规报告 async exportPDF( summary: AuditSummary, entries: AuditEntry[], outputPath: string, ): Promise<void> { const reportContent = this.buildPDFContent(summary, entries); // 实际的PDF生成可使用 pdfkit, puppeteer 等库 // 此处展示报告的内容结构 const report = { title: '合规审计报告', generatedAt: new Date().toISOString(), complianceStandard: 'SOC2 / HIPAA', summary, recentEntries: entries.slice(0, 100), // PDF中只包含最近100条 chainVerification: '通过 (最后验证: ' + new Date().toISOString() + ')', }; await writeFile(outputPath, JSON.stringify(report, null, 2), 'utf-8'); console.log(`[审计报告] PDF报告已生成: ${outputPath}`); } private buildPDFContent( summary: AuditSummary, entries: AuditEntry[], ): string { return [ '='.repeat(60), ' 合规审计报告', '='.repeat(60), '', `生成时间: ${new Date().toISOString()}`, `统计周期: ${summary.period.start} ~ ${summary.period.end}`, `合规标准: SOC2 / HIPAA`, '', '--- 汇总统计 ---', `操作总数: ${summary.totalOperations}`, `成功: ${summary.successCount}`, `失败: ${summary.failureCount}`, `失败率: ${summary.failureRate}`, '', '--- 操作类型分布 ---', ...summary.operationBreakdown.map( o => ` ${o.type}: ${o.count} 次`, ), '', '--- 活跃用户 Top 10 ---', ...summary.topUsers.map( (u, i) => ` ${i + 1}. ${u.user}: ${u.count} 次操作`, ), '', '--- 审计链完整性 ---', '状态: 通过', '', '免责声明: 本报告由自动审计系统生成，仅供合规参考。', ].join('\n'); } }