Crate vigil_sdk

Expand description

§vigil-sdk

Minimal stable SDK facade for embedding Vigil’s local AI safety runtime into 3rd-party tools. Published on crates.io as vigil-sdk (Apache-2.0).

§Status

已发布 0.1.0(crates.io)。SDK pub surface 经 Codex review 守门。当前暴露的是最小核心:typed decisions/audit records + high-level firewall execution + high-level redaction scanning。

显式不在 SDK 中:server runtime(Hub / oracle)/ 运行时 backend(NoopEngine / MockEngine / OrtEngine)/ ops 基建(bootstrap / model 分发)/ MCP 路由 / 凭据 (lease) / policy 引擎 internals。增加新项必经 codex review;移除现项视为 breaking change,需 ADR 决策。

§Quickstart

use vigil_sdk::prelude::*;

// 高层 redaction:默认路径(NoopEngine + Hard 规则)即可命中 secret 类。
// soft 标签(email / phone / person 等)需 vigil-redaction 的 `ort` feature
// + 模型环境;不在 SDK Phase 1 暴露,sdk 给 consumer 用 default safe path。
let token = "ghp_0123456789abcdefghijklmnopqrstuvwxyz12";
let result: RedactionResult = scan_text(token).unwrap();
assert!(result.findings.iter().any(|f| f.kind == "github_token"));

§Invariant 约定(SDK consumer 必须遵守)

Fail-closed:任何 SDK 函数返 ScanError / FirewallError 时, consumer 不可降级为“放行“。所有错误路径默认走 deny。
绝不存原文:SDK 接收的 input 文本不会被 SDK 持久化;consumer 也不应把原文写入 audit / log / 网络。审计走 DecisionRecord / AuditEvent (已守 no-plaintext 不变量)。
DecisionRecord 强制:任何 effect 触发(tool invocation / approval / etc) 必须 first 产出 DecisionRecord。不存在 SDK API 让 consumer 跳过这步。
接口稳定:SDK pub items 在 0.x 阶段允许小改进,但移除视为 breaking change; v1.0 freeze 后仅可加,不可删(SDK SemVer 政策守门,见下)。

§SemVer 政策

当前在 0.1.x:可能小改 SDK item 签名(必经 codex review + ADR)
v1.0 之后:freeze SDK pub items;新加项允许,删除/改签名禁止
non-SDK crate(vigil-policy 等)仍可独立演进,与 SDK 解耦

§哪些 v0.7 sprint 会扩 SDK?

Phase 2 Performance:可能加 PiiScanner::scan_perf benchmark hooks(roadmap-only)
Phase 3 Multi-Model:加 ModelDescriptor + selection API

§引用

项目仓库:https://github.com/duncatzat/vigils

Re-exports§

pub use firewall_builder::FirewallBuildError;
pub use firewall_builder::FirewallBuilder;
pub use firewall_builder::SdkFirewall;

Modules§

firewall_builder: 高层 firewall facade(SDK-owned)—— 让消费者只用 vigil-sdk 就能起一个可用 firewall 并跑一次决策,无需自行装配 Ledger / PolicyEngine / DescriptorOracle(均内化为实现细节, 不进 SDK public API,守住 SDK 边界)。
prelude: Prelude — 默认安全路径的常用导入。

Structs§

ApprovalRequest: 一条待审批请求。
ApprovalResolution: 审批最终解析结果。wait_for_resolution 的返回值。
AuditEvent: append-only 事件条目。
BudgetedScanOutcome: v0.7-α2 Phase 2D — scan_text_with_engine_budgeted 输出。
DecisionRecord: 每次 tool call 的裁决记录；进入账本不可删改（只能新增反向记录）。
EffectVector: 单次调用被推断出的副作用向量。
Finding: 统一 finding 结构;Hard 和 Model 使用同一类型,merge 后 caller 按 source 区分需要时的差异化处理(如审计展现 / risk 加权)。
Firewall: Firewall 主组件。持有 extractors / scorer / policy 引擎 / 审计账本 / PII scanner。
FirewallConfig: Firewall 配置:项目根 / 允许主机 / OAuth scope allowlist / TTL 等。
LanguageHint: v0.10 Sprint 2 — typed lang hint wrapper(Decision A-prime)。
RedactionResult: scan_text 的综合输出。
RiskSignals: 聚合风险信号。纯派生数据,可从 findings 重算;先算好避免 caller 每次重跑。
ToolInvocation: 一次工具调用请求。

Enums§

ApprovalScope: 审批范围(ADR 0003 §D6)。
ApprovalStatus: 审批状态。
DecisionKind: 裁决类型。
EffectKind: 效应种类。
EngineStatus: v0.7-α2 Phase 2D(ADR 0016 Fail-Closed Bottom Line):模型路径执行状态。
EngineStatusReport: v0.8 Sprint 1 A2 — PiiScanner 层引擎状态汇报。
FindingSource: Finding 来源分类。
FirewallError: Firewall 错误。
FirewallOutcome: Firewall.evaluate() 返回的裁决结果。
LangHintSource: v0.10 Sprint 2 — LanguageHint 信息来源 enum。
OAuthScopeContext: I10c-β2(R3 MUST-FIX 修复):调用路径的 OAuth 上下文,显式区分“非 OAuth“与“OAuth + scope“。
PrivacyLabel: Stage 2 T0 业务标签枚举(ADR 0013)。
ScanError: scan_text 错误类型。Stage 1 scaffold 主要覆盖 EmptyInput; InferenceFailed 为 ISS-008 真模型接入预留 variant,现阶段不会由本函数返出。
XlmrProfileMode: v0.10 Sprint 1 F 续 — typed xlmr profile mode(替代裸 env)。

Constants§

SDK_MODEL_ID_OPENAI_PRIVACY_FILTER_V1: SDK consumer 配置 / 审计跨表 join 用的稳定 model_id 字符串常量(v0.8)。
SDK_MODEL_ID_XLMR_PII_V1: xlmr-pii-v1 stable model_id(35 BIO labels,multilang strong on address/account)。
SDK_MODEL_ID_YONIGO_PII_V1: yonigo-pii-v1 stable model_id(38 BIO labels,strong on email/phone)。

Traits§

PiiScanner: R2 BLOCKER 2 修复 —— 把 PII 扫描抽象为 trait,让测试能注入 failing scanner 真触发 fail-closed 路径。默认实现 [DefaultScanner] 直接 forward 到 vigil_redaction::scan_text。
RedactionEngine: Privacy Filter 推理引擎抽象。scan_text_with_engine 通过本 trait 拿 Model 侧 findings, 与 Hard 侧 [crate::scan::collect_hard_findings] 输出送 merge_findings 决策合并。

Functions§

descriptor_hash: 计算一个工具描述符的 hash(hex-lower 64 字符)。
detect_lang_heuristic: v0.10 Sprint 6 — 独立函数版启发式 lang detect(advisory only)。
scan_text: Stage 2 T0 统一入口:扫描文本,产出 findings + 脱敏文本 + 风险信号。
scan_text_with_engine: 引擎可注入版本的 scan_text(ISS-008 Phase 1)。
scan_text_with_engine_budgeted: v0.7-α2 Phase 2D(ADR 0016)— 带 budget 的 scan,模型路径超时即退化 Hard-only。
scan_text_with_engine_with_hint: v0.10 Sprint 2 — scan_text_with_engine_with_hint 浅级 wrapper。

Crate vigil_sdk

Crate vigil_sdk Copy item path

§vigil-sdk

§Status

§Quickstart

§Invariant 约定(SDK consumer 必须遵守)

§SemVer 政策

§哪些 v0.7 sprint 会扩 SDK?

§引用

Re-exports§

Modules§

Structs§

Enums§

Constants§

Traits§

Functions§

Crate vigil_sdk