Astrid 加密审计链(The Cryptographic Audit Chain):不可变、链式链接、密码学签名的防篡改审计账本

原创2026-09-27 10:31:291,664 阅读
文章标签:文档教程

Astrid 加密审计链(The Cryptographic Audit Chain):不可变、链式链接、密码学签名的防篡改审计账本

导读:本文深入讲解 Unicity Astrid OS 的审计子系统——core/crates/astrid-audit 所实现的加密审计链。审计日志不是被动的日志文件,而是一个不可变、链式链接、密码学签名的防篡改账本:对历史条目的任何修改都会破坏链条,并在验证时被检测。读完本文你将掌握:AuditEntry 的数据模型与确定性签名构造、BLAKE3 链式哈希与 Ed25519 签名如何协同、按 principal 拆分链的设计、三种篡改场景的验证算法,以及密钥轮换(key rotation)如何做到透明安全。


概览:审计子系统的三层架构

Astrid 代表用户执行的每一个动作,都会被记录为一条不可变、链式链接、密码学签名的审计条目。审计日志不是一个被动的日志文件,它是一个防篡改账本:对历史条目的任何修改都会破坏链条,并在验证时被检测。整个审计子系统由三层组成:

  1. Entry(entry.rs):单个事件的已签名、链式链接记录。
  2. Log(log.rs):高层 API,负责创建、存储和验证条目。
  3. Storage(storage.rs):可插拔的 AuditStorage trait,生产环境由 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)

一条链是一系列满足以下条件的条目序列:

  1. 第一个条目的 previous_hash 是 ContentHash::zero()(创世)。
  2. 每个后续条目的 previous_hash 等于前一条目的 content_hash()。
  3. 每个条目的 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 分组条目,按时间戳排序,并依次检查三个性质:

  1. 创世:chain_entries[0].previous_hash.is_zero()
  2. 签名:对每个条目调用 entry.verify_signature()
  3. 链接:对每对相邻条目检查 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)。


总结:三层式保证

审计链提供了三层式保证:

  1. 条目级完整性:覆盖所有字段的 ed25519 签名意味着对已存储条目的任何单字节修改都会被 verify_signature 检测到。
  2. 顺序完整性:BLAKE3 previous_hash 链接意味着插入、删除和重排序都会被 verify_chain 检测到。
  3. 归因清晰性:按 principal 拆分链意味着 Alice 的链与 Bob 的链可独立验证,一条链中被破坏的条目不会污染另一条链的验证结果。

密钥轮换是透明处理的,因为公钥在写入时嵌入到每个条目中,而 verify_signature 只使用那个嵌入的密钥。这使得 Astrid 的审计日志同时满足防篡改、可追溯、多租户隔离和长期可维护四项要求——它是整个安全模型(策略、能力令牌、预算、审批)的最终仲裁者。

相关文档

登录后查看全文
book