Obelisk 安全机制全解析：出站 HTTP 白名单、Secrets 管理与 OIDC 认证-育师

【免费下载链接】obelisk

Durable & Deterministic Workflow Engine

项目地址：https://gitcode.com/gh_mirrors/obelisk4/obelisk

Obelisk 是一个构建在 WASM Component Model 之上的持久化、确定性 Workflow 引擎。对运行第三方代码（甚至 AI 生成的代码）的工作流引擎而言，安全是核心命题。Obelisk 通过三道防线回答这个问题：出站 HTTP 白名单限制组件能访问的网络目标、Secrets 管理让组件全程接触不到真实密钥、OIDC 认证保护 API 访问。本文带你逐层拆解这套安全机制的设计与配置方法，帮助你在生产环境中放心使用 Obelisk。

下图是一个 Obelisk 部署的组件依赖图，安全策略正是围绕这类组件（webhook、workflow、activity）的边界来设计的：

一、出站 HTTP 白名单：双重授权与最小化网络出口

Obelisk 的组件默认不允许发起任何出站 HTTP 请求——如果deployment.toml中没有定义allowed_host条目，所有出站连接都会被拦截。这是"默认拒绝"原则的典型实践。

1. 双层策略的对称交集

出站请求必须同时通过两层策略检查（实现见 http_request_policy.rs）：

策略层	所属文件	管理方
组件策略（`hosts`）	`deployment.toml`的`[[*.allowed_host]]`	应用开发者
全局白名单（`global_allowlist`）	`app.toml`的`[[outbound_http.allowed_host]]`	应用管理员

两层都匹配，请求才放行；任一层拒绝，请求立即失败并返回HttpRequestDenied错误。更妙的是：策略被拒绝时，诊断信息会明确指出是哪一层拒绝了请求（http_request_policy.rs 中区分了Component与GlobalAllowlist两个拒绝来源），让你知道该去哪个文件补条目。

2. 白名单条目支持哪些匹配维度？

一条allowed_host可以精细控制：

协议、主机、端口：pattern字段，如api.github.com（默认 HTTPS 443 端口）、http://localhost:*（任意端口）、*.example.com（子域通配）、http://192.168.1.*（/24 网段）
HTTP 方法：methods = ["GET", "POST"]，只放行读操作
URL 正则：request_url_regex在主机和方法匹配之后做二次校验，例如^GET https://api\.github\.com/repos/只允许 GET 仓库列表
简化形式：url_prefix直接指定基础 URL，配合url_regex_suffix锚定端点

完整的语法说明在 deployment-help.toml 和 app-help.toml 中有详尽注释。这种"主机 + 方法 + 路径正则"的组合，把网络出口精确到某一个 API 端点、某一种 HTTP 方法的粒度。

3. 策略本身可审计

每份生效的出站策略都会被序列化为obelisk-http-policy-v1格式并计算 SHA-256 摘要（http_request_policy.rs 中的audit_http_policy），随组件一起持久化——事后审计时你能精确知道"当时这份部署被授权访问了哪些目标"。

二、Secrets 管理：组件永远看不到真实密钥

这是 Obelisk 安全设计中最精巧的部分。核心思路：用占位符（placeholder）代替真实密钥注入组件，只在请求真正发出、且目标在白名单内时，才由宿主侧完成替换。

1. 声明 Secret 与授权暴露

在app.toml的[secrets]表中注册密钥（secret_registry.rs 负责构建该注册表）：

[secrets] OPENAI_API_KEY = {} GITHUB_TOKEN = { optional = true }

默认从应用环境变量读取（type = "env"），启动即校验，缺失的必需输入会让服务直接启动失败，而不是让执行在运行时才暴露问题
type = "internal"的内部密钥使用启动时生成的临时令牌，重启即轮换，适合组件回调 Obelisk 自身 API
启动后这些环境变量会从进程环境中删除，宿主机侧不留明文副本

想暴露给某个组件，必须在[secrets.<name>.exposed_to]中登记该组件的 SHA-256 摘要——也就是说，"允许哪个代码版本接触这个密钥"是一道需要管理员评审的显式决策，代码一变摘要就变，旧授权自动失效。

2. 占位符替换：三层保险

在deployment.toml的allowed_host中声明secrets与replace_in后，组件拿到的环境变量是随机占位符而非真值（机制见 http_request_policy.rs）。真实替换只发生在以下全部条件满足时：

请求目标同时匹配组件策略与全局白名单（即第一节的"双重授权"）
(secret, 替换位置)这一对在两层策略中都被授权——只有一侧授权会被丢弃
每次执行运行（run）的占位符都重新生成，历史占位符不会跨运行复用

替换位置replace_in支持三种：headers（含Bearer <占位符>这类嵌在长值中的场景）、params（URL 查询参数）、body（仅限文本类型且 UTF-8 合法时）。替换发生在宿主侧出站链路上，组件内存中自始至终只有占位符——即使组件被恶意利用，它也无法读出真实密钥。

被拒绝的请求不会静默失败：日志中会记录被哪一层策略拦截，方便排查配置。

三、API 认证：Bearer Token 与 OIDC 双通道

Obelisk 的 API 端口（默认127.0.0.1:5005）由统一的鉴权中间件守护（auth.rs），无有效Authorization: Bearer <token>的请求一律拒绝。认证通过两条通道：

1. 静态令牌（哈希存储，不明文落盘）

# server.toml api.token_hashes = [ "sha256:...", # agent "sha256:...", # laptop ]

配置文件里只存SHA-256 摘要，令牌本身不落盘
用obelisk generate token --server-config <文件>生成高熵令牌（要求至少 32 字符，过短会触发兼容性警告并将在未来版本被拒绝）
比对使用常数时间比较，防止时序侧信道
每次启动还会生成一个打印到控制台的临时恢复令牌，确保你永远不会被锁在门外

2. OIDC 认证（oidc.rs）

对云原生部署场景（如 Fly.io 机器、CI 平台），可配置 OIDC ID Token 作为等价凭据：

api.oidc = [ { issuer = "https://oidc.fly.io/my-org", audience = "https://obelisk.example.com", claims = { app_name = "deployer" } }, ]

验证链路非常严格：

iss必须精确等于配置的 issuer，未知签发者直接拒绝，不会为其发起任何网络请求
通过 OIDC Discovery 端点拉取 JWKS 公钥，JWKS 缓存 1 小时并带限流（防止被恶意 token 打爆刷新逻辑）
只接受非对称签名算法，none与 HMAC 一律拒绝
aud必须命中规则中的 audience，claims中列出的每个声明必须逐字段精确相等
通过后，审计身份记录为oidc:<iss>#<sub>，与静态令牌的identity一样进入执行审计记录

四、附加防线：Exec Activity 的双签审批

除了网络与密钥，Obelisk 对执行本地可执行程序（activity_exec）的能力同样设防：这类活动默认关闭，且需要app.toml与server.toml双方都登记并批准组件的 SHA-256 摘要才能运行（见 server-help.toml）。应用管理员决定"哪些代码可以执行"，平台管理员决定"平台允许哪些代码执行"，双重签名缺一不可。

小结

Obelisk 的安全机制体现了清晰的纵深防御思路：

防线	保护对象	关键机制
出站 HTTP 白名单	网络出口	双层策略交集、方法/正则细化、策略哈希审计
Secrets 管理	敏感凭据	占位符注入、双重授权替换、摘要级暴露审批
API 认证	控制面	令牌哈希存储、常数时间比对、严格 OIDC 校验
Exec 审批	本地执行	应用与平台双签摘要

再加上 Web UI 中可随时追溯的执行日志、系统事件与审计身份，Obelisk 让"运行不受完全信任的代码"从一句口号变成了可配置、可审计的工程实践。如果你想在自己的部署中落地，建议从 app-help.toml 与 server-help.toml 两份带完整注释的配置模板入手，它们是最好的安全配置参考文档。