@happy-technology/ 审计
Tamper-防审计散列内核 产品。 每个审计条目为HMAC-SHA256-hashed,用一个应用设备键入 与上一个条目的散列 同一房客,形成 a 租户散列链:任何内容编辑、插入、删除或重排间隔 链被检测。 因为大麻是按键的 派对只能 写入数据库(无应用程序秘密)无法伪造一个重新验证的链条: 这是篡改 -证明不仅仅是不言自明的.
0.2.0是一个从0.1.x.的突破变化. 无钥匙的平地SHA -256
computeEntryHash编号 :verifyAuditChain顶级导出被删除。 每个 消费者必须打电话createAuditChain(secret)获取密钥内核。 那边 没有将数据迁移路径烤入此软件包: 因为 HMAC 取代 根据0.1.x计算的链条不会在0.2.0下核实. (本变更时不存在生产审计数据
安装
{
"dependencies": {
"@happy-technologies/audit": "^0.2.0"
}
}
使用量
根导出: 纯内核
createAuditChain, (中文(简体) ), stableStringify,类型有 没有 依赖性
在 Postgres 或任何数据库驱动程序上,任何类型脚本运行时间都可以使用.
import { createAuditChain, type ChainRow } from "@happy-technologies/audit";
// secret comes from the app's own env/KMS -- see "Key management" below.
const chain = createAuditChain(process.env.AUDIT_HMAC_SECRET!);
const entryHash = chain.computeEntryHash(
{
id: "entry-1",
action: "document.created",
actorId: "user-1",
tenantId: "tenant-1",
resourceType: "document",
resourceId: "doc-1",
metadata: { source: "upload" },
ipAddress: "127.0.0.1",
userAgent: "Mozilla/5.0",
},
null, // prevHash, or the previous row's entryHash
);
const rows: ChainRow[] = []; // loaded from storage, ordered (timestamp ASC, id ASC)
const result = chain.verifyAuditChain(rows);
if (!result.ok) {
console.error(`chain broken at ${result.brokenAt} (${result.reason})`);
}
createAuditChain 返回 a ChainKernel 绑在一个秘密上:
interface ChainKernel {
computeEntryHash(fields: AuditChainFields, prevHash: string | null): string;
verifyAuditChain(rows: readonly ChainRow[]): ChainVerification;
}
./pg 子路径: 可选 Postgres 写入助手
消费者使用 pg 直接, insertAuditEntry 提供强制执行的
单写路径: 它获得租户 pg_advisory_xact_lock,读取
房客的最后一个 entry_hash,通过
ChainKernel 插入 prev_hash + 键 entry_hash 在一个
交易.
import { createAuditChain } from "@happy-technologies/audit";
import { insertAuditEntry } from "@happy-technologies/audit/pg";
const chain = createAuditChain(process.env.AUDIT_HMAC_SECRET!); // create once, reuse
const client = await pool.connect();
try {
await insertAuditEntry(
client,
{
id: "entry-1",
timestamp: new Date(),
action: "document.created",
actorId: "user-1",
tenantId: "tenant-1",
resourceType: "document",
resourceId: "doc-1",
metadata: { source: "upload" },
ipAddress: "127.0.0.1",
userAgent: "Mozilla/5.0",
},
chain,
);
} finally {
client.release();
}
pg 是一个 可选端点依赖性: 只有在从
@happy-technologies/audit/pg。根出口从不进口 pg。 。 。 .
主要管理(消费者责任)
该应用程序提供 HMAC 秘密; 此软件包永远不会有 .
- 该秘密由CONSUMER应用程序创建和持有,来源于
环境变量或进程启动时 KMS 支持的秘密存储.
它传递给
createAuditChain(secret)一次(通常在启动时)和 返回时ChainKernel重复使用过呼叫. - 密钥必须不被硬化 默认 或在此任何地方实施 软件包的源代码,并且不存储在审计数据库本身 (在它所保护的数据旁边储存核查密钥将使 DB- write 攻击者伪造新条目, 击败整个点 键入链).
createAuditChain如果给定了空/ 未定义的密钥, 则丢出; 它永远不会 返回到未按键或默认模式.- 丢失密钥不会丢失数据 . 如果秘密丢失或旋转
现有链条仍然保留
完整且可读,但
verifyAuditChain无法再确认他们的 在新的/缺漏的密钥下保持完整性。 将秘密损失视为可用性 核查事件,不是数据损失事件. - 旋转新密钥下的新链 需要连续可核查的旋转必须设计 移徙本身(超出本一揽子计划的范围).
Canonical外地订单合同
ChainKernel#computeEntryHash 计算 HMAC-SHA256 文摘,按键
内核的秘密, 一个犬JSON序列化的Tuple:
[prevHash ?? "", id, action, actorId, tenantId, resourceType, resourceId,
metadata ?? {}, ipAddress ?? null, userAgent ?? null]
- 这行
timestamp是故意的,这是故意的 不包括 从散列。 订购 完整性来自prevHash链接,而不是从散列时间戳 值; 时间戳-值完整性是一个有记录的非目标. metadata序列化为stableStringify键 递归到如此密钥顺序( 如在 JSONB 往返之后) 永不更改 散货.
这个字段订单和序列化是一个版本合同. 改变它
打破根据旧合同计算的每个链条; 添加一个字段必须是
有意的、版本的改动(例如: computeEntryHashV2没有沉默
编辑到 computeEntryHash。 。 。 .
非目标
- 这个软件包是 没有 定义
audit_log表格计划,一组 已审计行动,或添加性列迁移。 每个消耗的应用程序都有 它的图谋和移民(例如:快乐知识)scripts/040_audit_hash_chain.sql) (中文(简体) ). - 这个软件包是 没有 吸收SDK拥有的或特定用途的链条
(例如快乐生活)
governance_provenance并且不主张 全球跨租户链; 连锁是租户. - 这个软件包是 没有 管理HMAC秘密的生命周期(生成, 存储,旋转)——这完全是消耗性应用程序的 责任。 见上文"关键管理".
- 这个软件包是 没有 实施外部定位(例如定期) 发布链头散列 外部,独立控制 对攻击者进行辩护 调和数据库和应用程序的机密 那个 将进一步加强防篡改的保证 除了"攻击者" "攻击者缺乏秘密,不能改变" 外部记录,但它是可选的未来硬化,没有执行 在这里.
- 只使用节点的脚本类型
crypto.createHmac。无粗口执行 存在或正在计划; 没有多块双向同步.