【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载OpenShell 为自治 AI Agent 沙箱提供结构化审计日志OCSF JSON 导出为保证产物在无外网环境下仍可做 Schema 校验仓库将 OCSF Schema Server 的官方 JSON 架构 vendored 到crates/openshell-ocsf/schemas/ocsf/目录下。本文以该目录下的README.md为核心完整梳理 vendored 架构的版本、类Class与对象Object清单、离线用途并给出可复制的升级脚本与源码级佐证帮助你理解 OpenShell 是如何把 OCSF 事件模型落地为可审计、可降级、可对接 SIEM 的结构化日志的。为什么 OpenShell 要内置 OCSF 架构文件OCSFOpen Cybersecurity Schema Framework是安全领域通用的事件模型OpenShell 的沙箱审计日志正是以 OCSF v1.8.0 事件模型为骨架产出的。在 CI、离线测试、离线构建等无外网场景下运行时无法访问https://schema.ocsf.io/因此 OpenShell 选择将所需类与对象的 JSON Schema 直接打入仓库供离线测试校验使用——这正是 vendored 目录存在的意义。这一设计从源码中可以确认crates/openshell-ocsf/src/validation/schema.rs中的load_class_schema与load_object_schema会直接以env!(CARGO_MANIFEST_DIR)为基准拼出schemas/ocsf/v1.8.0/classes/{class}.json与schemas/ocsf/v1.8.0/objects/{object}.json的本地路径并读取缺失文件或非法 JSON 会直接 panic从而让任何缺少 vendored 架构的构建立刻暴露问题。换句话说仓库里的 JSON 不是摆设而是校验测试的硬依赖。当前版本与目录结构关联文档明确记录当前 vendored 的 OCSF 版本为v1.8.0来源为https://schema.ocsf.io/api/1.8.0/。在仓库中版本号同时存在于两个位置并保持一致目录crates/openshell-ocsf/schemas/ocsf/v1.8.0/其下VERSION文件内容为1.8.0源码常量OCSF_VERSION定义于crates/openshell-ocsf/src/lib.rs/// OCSF schema version this crate implements. pub const OCSF_VERSION: str 1.8.0;从目录结构还可以看到仓库同时保留了v1.7.0的历史快照crates/openshell-ocsf/schemas/ocsf/v1.7.0/说明该目录支持按版本归档升级时旧版本架构并不会被立即删除而是保留为可追溯的历史。实际运行时校验固定指向v1.8.0子目录见schema.rs中的路径拼接这也与OCSF_VERSION常量保持一致。v1.8.0 目录下包含classes/、objects/、profiles/三个子目录分别存放 8 个事件类、17 个对象、1 个 Profile 的 JSON 定义。Vendored 架构内容总览8 个事件类Classes关联文档列出的 8 个类及对应class_uid如下它们也是 OpenShell 审计日志实际会产出的事件类型类名class_uid用途network_activity4001沙箱网络连接的开/拒绝等行为http_activity4002HTTP 请求/响应级审计含 L7 MCP 决策ssh_activity4007SSH 会话与认证行为process_activity1007进程启动/退出等生命周期detection_finding2004检测发现如威胁判定application_lifecycle6002应用启停等生命周期device_config_state_change5019设备/策略配置变更审计base_event0基础事件基类注意仓库实际的v1.8.0/classes/目录中还额外包含api_activity.jsonAI 推理调用类即运行时实现的事件类比 README 列出的清单多一个README 清单对应的是 offline 校验测试的最小覆盖集。全部 9 个事件类在lib.rs中均有对应的 Rust 类型导出ApiActivityEvent、NetworkActivityEvent、HttpActivityEvent、SshActivityEvent、ProcessActivityEvent、DetectionFindingEvent、ApplicationLifecycleEvent、DeviceConfigStateChangeEvent、BaseEvent。17 个对象Objects关联文档列出的对象清单均为类内复用的结构化字段类型metadata、network_endpoint、network_proxy、process、actor、device、container、product、firewall_rule、finding_info、evidences、http_request、http_response、url、attack、remediation、connection_info。同样的v1.8.0/objects/目录在 README 清单之外还多出ai_model.json与api.json对应 AI 推理类所需的模型标识与 API 调用信息。Rust 侧的对象类型在lib.rs中以Actor、Endpoint、Metadata、Container、Device、FirewallRule、FindingInfo、HttpRequest、HttpResponse、Url、ConnectionInfo、AiModel、Api等结构体导出。1 个 ProfileProfileai_operation用于标记事件是否携带 AI 模型操作信息。Profile 在 OCSF 中是按需附加到类上的属性集合。OpenShell 用ai_operation承载模型身份模型名、AI 提供商这在crates/openshell-ocsf/src/builders/api_activity.rs的 builder 中可以看到当事件附加 AI 模型信息时builder 会同时把ai_operation写入metadata.profiles。正因为这些字段是 Profile 门控的降级到旧 Schema 时才允许直接剥离详见后文降级小节。Vendored 架构在项目中的实际用途这部分结合源码确认 vendored 架构的三个实际用途帮助你理解离线校验具体校验什么。1. 必须字段校验required / at_least_onevalidate_required_fields会解析 Schema 的attributes与constraints对每个标记为requirement: required且非 Profile 门控的字段断言事件 JSON 中必须存在且非空对constraints.at_least_one声明的分组例如network_activity要求src_endpoint与dst_endpoint至少一个、http_activity要求http_request与http_response至少一个断言分组内至少一个字段非空。校验不通过会直接触发断言失败从而在测试阶段就拦截掉不完整的 OCSF 事件。对应的测试见schema.rs。2. 枚举值校验enumvalidate_enum_value会读取 Schema 属性定义中的enum映射断言事件中枚举字段如severity_id的取值必须命中合法枚举键防止序列化出 Schema 不认识的取值。3. Schema 完整性自检test_load_class_schemas遍历全部 8 个基础类断言每个 JSON 都包含caption与attributes键。如果升级时拉取失败、文件缺字段或路径对不上该测试会立刻失败——这也是必须同步更新OCSF_VERSION这一约束背后的原因。如何升级到新的 OCSF 版本关联文档给出了完整的升级流程核心是两条重新拉取 Schema JSON以及同步源码中的版本常量。原文中的拉取脚本为此处整理为可直接执行的完整形式VERSION1.8.0 # 1) 拉取事件类 Schema for class in network_activity http_activity ssh_activity process_activity \ detection_finding application_lifecycle device_config_state_change base_event; do curl -s https://schema.ocsf.io/api/${VERSION}/classes/${class} \ | python3 -m json.tool classes/${class}.json done # 2) 拉取对象 Schema for object in metadata network_endpoint network_proxy process actor device \ container product firewall_rule finding_info evidences \ http_request http_response url attack remediation connection_info; do curl -s https://schema.ocsf.io/api/${VERSION}/objects/${object} \ | python3 -m json.tool objects/${object}.json done # 3) 记录版本号 echo ${VERSION} VERSION脚本中的classes/、objects/、VERSION均相对于crates/openshell-ocsf/schemas/ocsf/版本号/目录执行。执行时需要注意几点每个新版本创建独立的版本子目录如v1.8.0、v1.9.0旧版本目录保留用于回溯若新版新增了类、对象或 Profile如 v1.8.0 新增的api_activity、ai_model、api、ai_operation需要在脚本清单中同步补充否则运行时校验会因找不到文件而 panic拉取完成后必须更新源码常量否则目录版本与OCSF_VERSION不一致Schema 自检与降级逻辑都会基于错误的版本号运行。最后一步关联文档明确要求// crates/openshell-ocsf/src/lib.rs pub const OCSF_VERSION: str 1.8.0; // 升级时改为目标版本升级的联动影响升级 Schema 不只是换文件还可能联动影响以下代码以 v1.8.0 为例事件类型与 builder新类通常伴随新增 Rust 事件结构与 builder如ApiActivityEvent、ApiActivityBuilder见crates/openshell-ocsf/src/builders/api_activity.rs枚举与对象类型新对象如AiModel、Api对应crates/openshell-ocsf/src/objects/ai_model.rs与crates/openshell-ocsf/src/objects/api.rs降级规则downgrade.rs中定义的要剥离字段/Profile 清单需要与新版本的新增字段保持同步详见下节文档中的类清单docs/observability/ocsf-json-export.mdx中class_uid映射表与 README 清单需同步维护。版本降级Schema 快照的另一层保障升级到新版本后如果下游 SIEM 只支持旧版 OCSFOpenShell 通过ocsf_schema_version设置对序列化的 JSONL 做降级转换。该能力由crates/openshell-ocsf/src/format/downgrade.rs的downgrade_event实现其转换规则为目标版本早于或等于 v1.3.0 时剥离ai_model、container、observation_point_id字段从metadata.profiles移除ai_operation、container两个 Profile 名将metadata.version改写为目标版本在unmapped对象中写入downgraded_from: 1.8.0作为审计痕迹便于区分本来就没模型信息与模型信息被剥离两种情形。支持的降级目标是1.1与1.3对应 AWS Security Lake 的 v1.1.0 与 Splunk CIM Add-On 的 v1.1-v1.3 兼容范围。降级只在序列化输出层生效内部事件模型始终保持在 v1.8.0shorthand 人类可读日志不受影响。这条链路再次体现了 vendored Schema 的价值v1.1/v1.3 的字段集合定义就来自本地 Schema 快照离线环境下的降级校验同样可信。从 Schema 到日志一条完整的产出链路为了让你对 vendored Schema 在整个审计链路中的位置有整体认识这里把openshell-ocsfcrate 的产出链路串起来相关源码见crates/openshell-ocsf/src/lib.rs事件构造调用方通过 per-class builder如NetworkActivityBuilder、HttpActivityBuilder配合EventContext携带sandbox_id、sandbox_name、container_image、hostname、product_version、proxy_ip/port等共享元数据见crates/openshell-ocsf/tests/roundtrip.rs构造OcsfEvent事件桥接emit_ocsf_event把事件写入线程局部存储再发出一条target: ocsf的 tracing 事件emit_ocsf_event_routed额外附加sandbox_id字段供网关按沙箱路由见crates/openshell-ocsf/src/tracing_layers/event_bridge.rs双格式输出OcsfShorthandLayer产出人类可读的单行 shorthand写入openshell.YYYY-MM-DD.logOcsfJsonlLayer产出完整 OCSF JSONL写入openshell-ocsf.YYYY-MM-DD.log二者同源于一份事件数据JSON 序列化由to_json()/to_json_line()完成见crates/openshell-ocsf/src/format/jsonl.rsSchema 校验测试与test-supportfeature 下validation/schema.rs用 vendored JSON 对事件做 required / at_least_one / enum 断言版本降级当配置了ocsf_schema_version时JSONL 层先降级再写出format/downgrade.rs可观测配置ocsf_json_enabled控制是否启用 JSON 导出全局openshell settings set --global --key ocsf_json_enabled --value true或按沙箱设置配置生效于下一个轮询周期默认 10 秒无需重启沙箱日志默认保留最近 3 个按日轮转文件。JSONL 输出示例节选自docs/observability/ocsf-json-export.mdx中network_activity允许连接事件该文档还包含完整的拒绝事件示例与各class_uid对照表{ class_uid: 4001, class_name: Network Activity, category_uid: 4, activity_id: 1, activity_name: Open, severity_id: 1, severity: Informational, action_id: 1, action: Allowed, disposition_id: 1, disposition: Allowed, dst_endpoint: { domain: api.github.com, port: 443 }, actor: { process: { name: /usr/bin/curl, pid: 57 } }, firewall_rule: { name: github_api, type: opa }, metadata: { version: 1.8.0, product: { name: OpenShell Sandbox Supervisor, vendor_name: NVIDIA, version: 0.3.0 } } }常见维护动作速查场景操作查看当前 vendored 版本cat crates/openshell-ocsf/schemas/ocsf/v1.8.0/VERSION并与lib.rs的OCSF_VERSION核对确认某个类的 Schema 存在ls crates/openshell-ocsf/schemas/ocsf/v1.8.0/classes/离线校验一个事件 JSON借助crates/openshell-ocsf/src/validation/schema.rs的load_class_schemavalidate_required_fields通过 crate 的test-supportfeature 暴露升级 OCSF 版本执行上文脚本 → 更新OCSF_VERSION→ 运行cargo test -p openshell-ocsf验证 Schema 自检与 round-trip 测试对接 SIEM参考docs/observability/ocsf-json-export.mdx中的 SIEM 兼容表与ocsf_schema_version设置Splunk 用1.3AWS Security Lake 用1.1升级后请务必运行cargo test -p openshell-ocsftests/roundtrip.rs会对全部事件类执行to_json → from_value → to_json的往返一致性断言见crates/openshell-ocsf/tests/roundtrip.rs而validation/schema.rs的测试则验证 vendored 架构文件本身完好。这两类测试共同构成了Schema 快照与代码实现保持一致的守护网。赞分享【免费下载链接】OpenShellOpenShell is the safe, private runtime for autonomous AI agents.项目地址https://gitcode.com/gh_mirrors/op/OpenShell点击查看免费下载相关推荐AReaL vLLM 升级审计清单全解14 个 API 条目、双清单架构与维护工作流AReaL vLLM 升级审计清单全解14 个 API 条目、双清单架构与维护工作流 AReaL 仓库中的 vllm.md https://link.gitc人工智能大模型强化学习分布式训练AI AgentNemoClaw 中 OpenShell SDK 受审归档Reviewed Archive的离线安装与校验机制NemoClaw 中 OpenShell SDK 受审归档Reviewed Archive的离线安装与校验机制 导读 本文围绕 NemoClaw 仓库中 sSubtitle Edit 的 Flathub 提交指南Flatpak 清单、离线 NuGet 与发布维护全流程Subtitle Edit 的 Flathub 提交指南Flatpak 清单、离线 NuGet 与发布维护全流程 导读 本指南围绕 Subtitle Edit音视频桌面应用上一篇VLC Android电视版技术解析构建跨平台媒体中心的架构实践下一篇科研知识管理革命如何用Obsidian打造你的专属研究大脑创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考