Astrid 加密审计链(The Cryptographic Audit Chain):不可变、链式链接、密码学签名的防篡改审计账本
Astrid 加密审计链(The Cryptographic Audit Chain):不可变、链式链接、密码学签名的防篡改审计账本
导读:本文深入讲解 Unicity Astrid OS 的审计子系统——core/crates/astrid-audit 所实现的加密审计链。审计日志不是被动的日志文件,而是一个不可变、链式链接、密码学签名的防篡改账本:对历史条目的任何修改都会破坏链条,并在验证时被检测。读完本文你将掌握:AuditEntry 的数据模型与确定性签名构造、BLAKE3 链式哈希与 Ed25519 签名如何协同、按 principal 拆分链的设计、三种篡改场景的验证算法,以及密钥轮换(key rotation)如何做到透明安全。
概览:审计子系统的三层架构
Astrid 代表用户执行的每一个动作,都会被记录为一条不可变、链式链接、密码学签名的审计条目。审计日志不是一个被动的日志文件,它是一个防篡改账本:对历史条目的任何修改都会破坏链条,并在验证时被检测。整个审计子系统由三层组成:
- Entry(
entry.rs):单个事件的已签名、链式链接记录。 - Log(
log.rs):高层 API,负责创建、存储和验证条目。 - Storage(
storage.rs):可插拔的AuditStoragetrait,生产环境由SurrealKV作为后端。
该 crate 从 astrid-capabilities 重新导出 AuditEntryId,因此所有调用方引用的是同一个规范化 ID 类型。
[AuditLog]
|-- append() / append_with_principal()
| \-- AuditEntry::create / ::create_with_principal
| \-- runtime_key.sign(signing_data)
|-- verify_chain() / verify_principal_chain()
|-- storage: Box<dyn AuditStorage>
\-- SurrealKvAuditStorage (production)
\-- SurrealKvAuditStorage::in_memory() (tests, backed by MemoryKvStore)
这套审计子系统与 Astrid 的安全模型深度耦合。在 The Five-Layer Security Gate 中,审计是第五层(fail-closed 层):每个动作,无论通过还是被拒,都必须先写入审计日志,intercept() 才会返回;审计写入失败本身就是硬错误。在 Policy, Budget, Approval, and Audit 中,审计条目还承担着"同意链"(consent chain)的角色:UserApproval::approval_entry_id 会回溯到批准该动作的那条审计记录。
AuditEntry 结构:签名覆盖所有字段
entry.rs:16 定义的 AuditEntry 是审计链的基本单元:
pub struct AuditEntry {
pub id: AuditEntryId,
pub timestamp: Timestamp,
pub session_id: SessionId,
pub principal: Option<PrincipalId>, // None = system action
pub action: AuditAction,
pub authorization: AuthorizationProof,
pub outcome: AuditOutcome,
pub previous_hash: ContentHash, // BLAKE3 hash of previous entry
pub runtime_key: PublicKey, // embedded at write time
pub signature: Signature, // ed25519 over all fields above
}
关键设计点:从 id 到 runtime_key 的每一个字段都参与签名。嵌入的 runtime_key 是条目创建时处于活动状态的 runtime 密钥对的公钥半部分。这就是密钥轮换之所以安全的核心机制:验证时永远使用条目内记录的公钥,而不是 AuditLog 当前持有的密钥。
principal: Option<PrincipalId> 表示该动作是否归属于某个用户:None 表示系统动作(如会话启动),Some(principal) 表示由具体用户(principal)发起。这与 Astrid 的多用户模型对应——同一会话内 Alice 和 Bob 的工具调用会形成各自独立的审计链。
密码学原语:BLAKE3 + Ed25519
哈希:BLAKE3
astrid-crypto/src/hash.rs:16 定义了 ContentHash:
pub struct ContentHash([u8; 32]);
impl ContentHash {
pub fn hash(data: &[u8]) -> Self {
Self(*blake3::hash(data).as_bytes())
}
pub const fn zero() -> Self { Self([0u8; 32]) }
pub fn is_zero(&self) -> bool { self.0 == [0u8; 32] }
}
ContentHash::zero() 是创世条目(genesis entry)的哨兵值:一条链的第一个条目具有 previous_hash == ContentHash::zero()。验证算法会显式检查这一不变量。
签名:Ed25519
astrid-crypto/src/keypair.rs:19 定义了 KeyPair:
#[derive(ZeroizeOnDrop)]
pub struct KeyPair {
#[zeroize(skip)]
verifying_key: VerifyingKey, // ed25519-dalek
signing_key: SigningKey,
}
ZeroizeOnDrop 派生在 KeyPair 结构体本身。verifying_key 字段带有 #[zeroize(skip)],因为 VerifyingKey 不实现 Zeroize。KeyPair::generate() 从 OsRng 汲取熵——没有静态或硬编码的密钥;内核在启动时生成全新的密钥对。
签名验证
astrid-crypto/src/signature.rs:89 中的 verify:
pub fn verify(&self, message: &[u8], public_key: &[u8; 32]) -> CryptoResult<()> {
let verifying_key = VerifyingKey::from_bytes(public_key)?;
let sig = DalekSignature::from_bytes(&self.0);
verifying_key.verify(message, &sig)
.map_err(|_| CryptoError::SignatureVerificationFailed)
}
注意 verify 接收的公钥是普通的字节切片,而不是 KeyPair。AuditEntry::verify_signature 直接提供 entry.runtime_key.as_bytes(),因此每个条目在不接触活动签名密钥的情况下即可自验证。
签名数据的确定性构造
签名载荷由 AuditEntry::signing_data()(entry.rs:123)确定性地构造。字段顺序与编码是固定的:
| 字段 | 编码 |
|---|---|
id |
16 字节 UUID 原始字节 |
timestamp |
i64 Unix 秒,小端序 |
session_id |
16 字节 UUID 原始字节 |
principal |
0xFF + u32 长度 LE + UTF-8 字节,或 0x00 |
action |
serde_json::to_vec |
authorization |
serde_json::to_vec |
outcome |
1 字节布尔值(成功 = 1,失败 = 0) |
previous_hash |
32 原始字节 |
runtime_key |
32 原始字节 |
principal 字段使用带长度的编码,并显式给出存在标记(0xFF / 0x00),以避免"principal 不存在"与"零长度 principal 紧邻下一字段"之间的歧义。
条目的内容哈希是 ContentHash::hash(&entry.signing_data())——这个值正是存储在下一条目的 previous_hash 中的内容:
pub fn content_hash(&self) -> ContentHash {
ContentHash::hash(&self.signing_data())
}
条目创建:create 与 create_with_principal
AuditEntry::create(entry.rs:67)是主构造函数,它接收前一条的哈希和当前活动的 KeyPair 作为参数:
pub fn create(
session_id: SessionId,
action: AuditAction,
authorization: AuthorizationProof,
outcome: AuditOutcome,
previous_hash: ContentHash,
runtime_key: &KeyPair,
) -> Self {
let mut entry = Self::new_unsigned(
session_id, action, authorization, outcome,
previous_hash,
runtime_key.export_public_key(), // snapshot the public key
);
let signing_data = entry.signing_data();
entry.signature = runtime_key.sign(&signing_data);
entry
}
new_unsigned 将 signature 字段置为 [0u8; 64] 占位符。真正的签名在条目返回前替换它。占位符永远不会被持久化:create 返回的是完全签名的条目。
AuditEntry::create_with_principal 与上述逻辑相同,但在计算签名数据之前额外设置 entry.principal = Some(principal)。因为 principal 参与载荷签名,一个没有 principal 创建的条目,无法在事后被追溯归属到某个用户而不使签名失效。 这是审计归因(attribution)不可篡改的核心保证。
链不变量(Chain Invariant)
一条链是一系列满足以下条件的条目序列:
- 第一个条目的
previous_hash是ContentHash::zero()(创世)。 - 每个后续条目的
previous_hash等于前一条目的content_hash()。 - 每个条目的
signature能用自己的内嵌runtime_key验证通过。
follows 方法编码了条件 2:
pub fn follows(&self, previous: &AuditEntry) -> bool {
self.previous_hash == previous.content_hash()
}
任何乱序插入、删除或字段修改都会破坏至少一个上述不变量。
按 Principal 拆分链:会话内的独立链
单个会话可能涉及多个 principal(用户)以及系统动作。与其把所有条目交错进一条链,审计日志维护以 (SessionId, Option<PrincipalId>) 为键的独立链。
log.rs:20:
type ChainKey = (SessionId, Option<PrincipalId>);
AuditLog 中的 chain_heads 映射缓存每条链当前的头,作为 ContentHash。每次 append 时,先查找相关链的头,用作 previous_hash,然后更新为新条目的哈希:
// log.rs:106
let chain_key: ChainKey = (session_id.clone(), principal.clone());
let previous_hash = self.get_previous_hash(&chain_key)?;
get_previous_hash 先检查内存缓存,然后回退到存储后端的 get_chain_head,后者在 audit:chain_heads 命名空间下存储每条链最新的 AuditEntryId。存储键格式为:
- 系统链:
"{session_uuid}" - Principal 链:
"{session_uuid}:{principal}"
(storage.rs:150)
这意味着即使在同一个会话中,Alice 的工具调用与 Bob 的工具调用也形成完全独立的链。Alice 链中的被篡改条目不会影响 Bob 的链或系统链的验证结果。这一设计与 PrincipalId and Per-Invocation Isolation 的多用户隔离模型一致,也与五层安全门中的"principal 隔离"属性相呼应。
AuditLog API:从构造到查询
构造
// Production: SurrealKV on disk
let log = AuditLog::open("/var/lib/astrid/audit", runtime_key)?;
// Tests: in-memory MemoryKvStore
let log = AuditLog::in_memory(runtime_key);
生产路径将审计数据持久化到 SurrealKV(与 KV Storage 中描述的 SurrealKvStore 同源);测试路径使用 MemoryKvStore(HashMap<String, Vec<u8>> 加 RwLock)。
追加条目
// System action (no principal)
let id = log.append(
session_id,
AuditAction::SessionStarted { user_id, platform: "cli".to_string() },
AuthorizationProof::System { reason: "session start".to_string() },
AuditOutcome::success(),
)?;
// Principal-attributed action
let id = log.append_with_principal(
session_id,
alice_principal,
AuditAction::FileWrite { path: "/tmp/out.txt".into(), content_hash },
AuthorizationProof::Capability { token_id, token_hash },
AuditOutcome::success(),
)?;
从调用方角度看,两个方法都是同步的。存储后端在 block_on 内执行 I/O,它在多线程运行时上使用 tokio::task::block_in_place(生产环境),在单线程运行时上使用作用域线程(测试)。参见 storage.rs:106 的三路分发逻辑。
检索条目
// Single entry by ID
let entry: Option<AuditEntry> = log.get(&entry_id)?;
// All entries in a session (insertion order)
let entries: Vec<AuditEntry> = log.get_session_entries(&session_id)?;
// Entries for one chain only
let alice_entries = log.get_principal_entries(&session_id, Some(&alice))?;
let system_entries = log.get_principal_entries(&session_id, None)?;
验证算法:verify_chain、verify_principal_chain、verify_all
verify_chain:三种检查、完整收集
AuditLog::verify_chain 验证会话中的每一条链。它按 principal 分组条目,按时间戳排序,并依次检查三个性质:
- 创世:
chain_entries[0].previous_hash.is_zero() - 签名:对每个条目调用
entry.verify_signature() - 链接:对每对相邻条目检查
curr.follows(prev)
pub fn verify_chain(&self, session_id: &SessionId) -> AuditResult<ChainVerificationResult>
结果类型携带 valid、entries_verified 和一个 Vec<ChainIssue>:
pub enum ChainIssue {
InvalidGenesis { entry_id: AuditEntryId },
InvalidSignature { entry_id: AuditEntryId },
BrokenLink {
entry_id: AuditEntryId,
expected_previous: ContentHash,
actual_previous: ContentHash,
},
}
verify_chain 不会在第一次失败时短路——它收集所有问题,让审计者能看到篡改的全貌。
verify_principal_chain:定向验证单条链
// Verify Alice's chain only
let result = log.verify_principal_chain(&session_id, Some(&alice))?;
// Verify the system chain
let result = log.verify_principal_chain(&session_id, None)?;
这等价于对一个只包含指定 principal 条目的会话调用 verify_chain。同样的三项检查序列适用。
verify_all:全库扫描
let results: Vec<(SessionId, ChainVerificationResult)> = log.verify_all()?;
遍历 storage.list_sessions() 返回的每个会话并分别调用 verify_chain。适合后台完整性扫描或启动自检。
篡改检测实战:三种互不重叠的失败模式
log_tests.rs 中的测试套件演示了三种篡改场景:
签名被破坏(test_verify_detects_tampered_signature):对条目标签的第一个字节做 XOR。verify_chain 为该条目报告 ChainIssue::InvalidSignature。
链接断裂(test_verify_detects_broken_link):覆盖 previous_hash 并用原始密钥重新签名(因此签名有效)。verify_chain 仅报告 ChainIssue::BrokenLink,不报告 InvalidSignature。这证明两项检查相互独立,且有效的签名并不蕴含链完整性。
创世无效(test_verify_detects_invalid_genesis):在首条目上设置非零 previous_hash 并重新签名。verify_chain 仅报告 ChainIssue::InvalidGenesis。
三种失败模式截然不同、互不重叠。
密钥轮换:嵌入公钥的透明机制
条目在创建时嵌入公钥(runtime_key: PublicKey)。验证调用 entry.runtime_key.verify(signing_data, &entry.signature),使用的是条目自身的嵌入密钥,而不是 AuditLog 当前的 runtime_key 字段。
这意味着在密钥 A 下写入的条目,在运行时轮换到密钥 B 后仍然可验证。测试 test_key_rotation_entries_verify_via_embedded_pubkey(log_tests.rs:233)明确演示了这一点:
// Write 3 entries signed by key A.
let log_a = AuditLog::in_memory(keypair_a);
append_test_entries(&log_a, &session_id, 3);
// Move entries into a log that holds key B.
let log_b = AuditLog::in_memory(keypair_b);
for entry in log_a.get_session_entries(&session_id)? {
log_b.storage.store(&entry)?;
}
// Verification succeeds because each entry carries its own public key.
let result = log_b.verify_chain(&session_id)?;
assert!(result.valid);
审计者读取链时能看到哪条目由哪个 runtime 密钥签名。如果某个密钥在特定日期被泄露,审计者能识别出哪些条目是在该密钥下产生的,哪些是在其继任密钥下产生的。注意:验证逻辑依赖的 KeyPair 生成本身同样来自 OsRng,每次内核启动都是全新密钥对,因此"启动即轮换"是天然支持的场景。
AuditAction 目录:记录哪些安全相关事件
AuditAction 枚举(entry.rs:190)覆盖每一类安全相关事件。选录变体:
| 变体 | 隐私说明 |
|---|---|
McpToolCall { server, tool, args_hash } |
参数被哈希,不存储明文 |
CapsuleToolCall { capsule_id, tool, args_hash } |
相同的哈希策略 |
FileWrite { path, content_hash } |
内容被哈希,不存储 |
CapabilityCreated { token_id, resource, permissions, scope } |
完整的授权细节 |
ApprovalGranted { action, resource, scope } |
同意链 |
SubAgentSpawned { parent_session_id, child_session_id, description } |
父子链接 |
AdminRequest { method, required_capability, target_principal, params } |
取证参数字段 |
SecurityViolation { violation_type, details } |
策略执行 |
args_hash 模式让链能够证明"某个特定工具以特定参数被调用"(通过出示原像),而无需在审计存储中保存可能敏感的参数值。这与 Capabilities, Tokens, and Delegation 中 CapabilityToken::content_hash() 的做法一脉相承:敏感内容只存哈希,原像由调用方按需出示。
AuthorizationProof:记录"为什么被允许"
每个条目携带一个 AuthorizationProof,记录动作被许可的原因:
pub enum AuthorizationProof {
User { user_id: [u8; 8], message_id: String },
Capability { token_id: TokenId, token_hash: ContentHash },
UserApproval { user_id: [u8; 8], approval_entry_id: Option<AuditEntryId> },
NotRequired { reason: String },
System { reason: String },
Denied { reason: String },
}
Capability::token_hash将审计记录链接到授权该动作的确切能力令牌。这与 Capabilities, Tokens, and Delegation 中描述的approval_audit_id机制相呼应——令牌与审批条目互链,审计链成为"谁批准了什么、何时批准"的 ground truth。UserApproval::approval_entry_id链接回同一条链中的ApprovalGranted条目,在同意事件与其授权的动作之间创建交叉引用。在 Policy, Budget, Approval, and Audit 中,ApproveAlways铸造的CapabilityToken携带approval_audit_id,未来由该令牌授权的每次调用都会携带UserApproval证明,从而在审批事件与它覆盖的所有后续调用之间建立链式链接。
被拒绝的动作使用 AuthorizationProof::Denied 配合 AuditOutcome::failure。这意味着拒绝行为与成功行为享有相同的链式链接保证——审计日志对"发生了什么"和"什么被拒绝了"一视同仁。
存储布局:三个命名空间,只追加不更新
SurrealKvAuditStorage 后端在 astrid-storage 的 KvStore 中使用三个命名空间:
| 命名空间 | 键 | 值 |
|---|---|---|
audit:entries |
{entry_uuid} |
JSON 序列化的 AuditEntry |
audit:session_index |
{session_uuid} |
AuditEntryId 的 JSON 数组(插入顺序) |
audit:chain_heads |
{session_uuid} 或 {session_uuid}:{principal} |
该链最新条目的 UTF-8 UUID |
会话索引是一个会话内所有条目 ID 的有序列表,无论它们属于哪条链。链特有的顺序通过在 entry.principal 上过滤并按时间戳排序来恢复。存储层从不删除或更新条目;它只追加。这是防篡改账本能长期成立的物理基础——写入路径只有 append,历史数据天然不可覆盖。
错误处理:AuditResult 与 AuditError
所有公开方法返回 AuditResult<T>,即 Result<T, AuditError>:
pub enum AuditError {
StorageError(String),
SerializationError(String),
EntryNotFound { entry_id: String },
IntegrityViolation { entry_id: String, reason: String },
InvalidSignature { entry_id: String },
SessionNotFound { session_id: String },
CryptoError(#[from] astrid_crypto::CryptoError),
}
IntegrityViolation 在检索过程中发现结构性问题时由存储层返回。作为 AuditError 的 InvalidSignature 与 ChainIssue::InvalidSignature 不同:AuditError 变体由 AuditEntry::verify_signature 返回,仅在独立调用验证时冒泡;而在 verify_chain 过程中,问题被收集到 Vec<ChainIssue> 而不是作为错误返回,因此调用者能看到完整图景。
在五层安全门的语境中,这些错误有更重的分量:AuditLog::append 的任何错误都会由拦截器转换为 ApprovalError::AuditFailed(fail-closed),动作被视为被拒绝,绝不带着缺失的审计记录继续执行(参见 The Five-Layer Security Gate)。
总结:三层式保证
审计链提供了三层式保证:
- 条目级完整性:覆盖所有字段的 ed25519 签名意味着对已存储条目的任何单字节修改都会被
verify_signature检测到。 - 顺序完整性:BLAKE3
previous_hash链接意味着插入、删除和重排序都会被verify_chain检测到。 - 归因清晰性:按 principal 拆分链意味着 Alice 的链与 Bob 的链可独立验证,一条链中被破坏的条目不会污染另一条链的验证结果。
密钥轮换是透明处理的,因为公钥在写入时嵌入到每个条目中,而 verify_signature 只使用那个嵌入的密钥。这使得 Astrid 的审计日志同时满足防篡改、可追溯、多租户隔离和长期可维护四项要求——它是整个安全模型(策略、能力令牌、预算、审批)的最终仲裁者。