clay-good/invariant-robotics

# 不变性 [](https://github.com/clay-good/invariant/actions/workflows/ci.yml) [](https://crates.io/crates/invariant-robotics) [](https://docs.rs/invariant-robotics-core) [](LICENSE) [](https://github.com/rust-secure-code/safety-dance/) **用于 AI 控制机器人的加密命令验证防火墙。** ``` COGNITIVE DOMAIN INVARIANT FIREWALL KINETIC DOMAIN +-----------------+ +------------------------+ +----------------+ | LLM reasoning | --> | Verify authority chain | --> | Joint motors | | RL policies | | Check 25 physics rules | | Actuators | | Prompt injection| | Sign approved commands | | End effectors | | Hallucinations | | Reject + log denied | | The real world | | | | Watchdog heartbeat | | | | Error: ~10%+ | | Error: 0% | | Consequence: | | Stochastic | | Deterministic | | Irreversible | +-----------------+ +------------------------+ +----------------+ UNTRUSTED TRUST BOUNDARY PROTECTED ``` 如果没有 Invariant 的 Ed25519 签名，任何来自认知域的内容都无法到达动能域。AI 无法绕过它。AI 无法修改它。电机控制器在移动前会验证签名。 ## 目录 - [为什么这很重要](#why-this-matters) - [快速开始](#quick-start) - [安全不变量](#safety-invariants) - [架构](#architecture) - [CLI 参考](#cli-reference) - [集成](#integration) - [威胁模型](#threat-model) - [部署示例](#example-deployment) - [构建](#building) - [贡献](#contributing) ## 为什么这很重要 随着 AI 控制越来越多的物理系统——协作机器人、人形机器人、手术机械臂——“模型产生幻觉”与“执行器移动”之间的差距必须由某种**确定性的、通过加密强制执行的、且故障即关闭**的机制来填补。 Invariant 就是这种机制。 ## 快速开始 ``` cargo build --release # 运行自动化五分钟演示 ./examples/demo.sh # 或手动： ./target/release/invariant keygen --kid my-robot --output keys.json ./target/release/invariant inspect --profile profiles/ur10.json ./target/release/invariant adversarial --profile profiles/ur10.json --key keys.json --suite all # 输出："540 attacks, 0 escapes. PASS" ``` 从 [crates.io](https://crates.io/crates/invariant-robotics) 安装： ``` cargo install invariant-robotics invariant --help ```

Demo 输出

``` [Step 3] Validating a SAFE command... APPROVED + signed [Step 4] Validating a DANGEROUS command... REJECTED (P1, P2, P3, P5 violations) [Step 5] Verifying audit log... 2 entries, hash chain intact [Step 6] Testing tamper detection... Tampered log DETECTED [Step 7] Running 1000-command campaign with fault injection... 500 approved, 500 rejected, 0 violations escaped. ```

## 安全不变量 **共 34 个不变量。** 全部为确定性。全部经过签名。全部经过审计。 ### 物理检查 (P1--P25) | ID | 检查项 | 捕获目标 | |----|-------|---------| | P1 | 关节位置限制 | 过度伸展，机械损伤 | | P2 | 速度限制 | 危险速度 | | P3 | 扭矩限制 | 电机烧毁 | | P4 | 加速度限制 | 抖动，不稳定 | | P5 | 工作空间边界 | 伸出到安全区域外 | | P6 | 排除区域 | CNC 主轴碰撞，人员碰撞 | | P7 | 自身碰撞 | 自身损坏 | | P8 | 时间步边界 | 过期命令 | | P9 | 稳定性 (ZMP) | 倾倒，翻覆 | | P10 | 接近速度缩放 | 符合 ISO/TS 15066 标准 | | P11--P14 | 操作安全性 | 挤压，掉落 | | P15--P20 | 移动安全性 | 滑动，绊倒，跌倒 | | P21 | 地形倾斜 | 在不安全斜坡上行走 | | P22 | 执行器温度 | 电机过热 | | P23 | 电池状态 | 任务中途中断电 | | P24 | 通信延迟 | 因网络延迟导致的过期命令 | | P25 | 紧急停止 | 始终拒绝，无法禁用 | ### 权限、审计与完整性 | ID | 检查项 | 保证 | |----|-------|-----------| | A1--A3 | Ed25519 PIC 权限链 | 加密 | | L1--L4 | 哈希链 + 签名审计日志 | 加密 | | M1 | 签名的驱动命令 | 加密 | | W1 | 看门狗心跳 / 安全停止 | 时间 + 加密 | | ISO 15066 | 身体区域受力上限 | 符合标准 | ## 架构 ### 工作区 | Crate | 描述 | |-------|-------------| | [`invariant-core`](crates/invariant-core/) | 物理检查 (P1--P25)、PIC 权限链、Ed25519 加密、验证器、URDF 解析器、看门狗、审计日志、差分验证、意图管道 | | [`invariant-cli`](crates/invariant-cli/) | 具有 19 个子命令的 CLI 二进制文件 | | [`invariant-sim`](crates/invariant-sim/) | 13 个仿真场景、21 个故障注入器、试运行活动、Isaac Lab 桥接 | | [`invariant-eval`](crates/invariant-eval/) | 追踪评估：安全性 / 完整性 / 回归预设、评估规则、安全护栏、差异比较 | | [`invariant-fuzz`](crates/invariant-fuzz/) | 对抗性测试：协议 (PA1--PA15)、权限 (AA1--AA10)、系统 (SA1--SA15)、认知 (CE1--CE10) | | [`invariant-coordinator`](crates/invariant-coordinator/) | 多机器人协调：间距监控、工作空间分区 | | [`formal/`](formal/) | 包含证明草稿的 Lean 4 形式化规范（独立构建） | ### 内置机器人配置文件 (共 34 个) **人形机器人 (11)** | 配置 | 关节 | 平台 | |---------|--------|----------| | `humanoid_28dof` | 28 | 通用全尺寸人形机器人 | | `unitree_h1` | 19 | 宇树科技 H1 | | `unitree_g1` | 23 | 宇树科技 G1 | | `fourier_gr1` | 39 | 傅利叶智能 GR-1 (NVIDIA GR00T) | | `tesla_optimus` | 28 | Tesla Optimus Gen 2 | | `figure_02` | 42 | Figure 02 (带灵巧手) | | `bd_atlas` | 28 | Boston Dynamics Atlas (电动) | | `agility_digit` | 16 | Agility Robotics Digit | | `sanctuary_phoenix` | 24 | Sanctuary AI Phoenix | | `onex_neo` | 28 | 1X Technologies NEO | | `apptronik_apollo` | 30 | Apptronik Apollo | **四足机器人 (5)** | 配置 | 关节 | 平台 | |---------|--------|----------| | `quadruped_12dof` | 12 | 通用四足机器人 | | `spot` | 12 | Boston Dynamics Spot | | `unitree_go2` | 12 | 宇树科技 Go2 | | `unitree_a1` | 12 | 宇树科技 A1 | | `anybotics_anymal` | 12 | ANYbotics ANYmal | **机械臂 (7)** | 配置 | 关节 | 平台 | |---------|--------|----------| | `franka_panda` | 7 | Franka Emika Panda | | `ur10` | 6 | Universal Robots UR10/UR10e | | `ur10e_haas_cell` | 6 | UR10e + Haas VF-2 CNC 工作站 | | `ur10e_cnc_tending` | 6 | UR10e CNC 上下料工作站 | | `kuka_iiwa14` | 7 | KUKA LBR iiwa 14 | | `kinova_gen3` | 7 | Kinova Gen3 | | `abb_gofa` | 6 | ABB GoFa CRB 15000 | **灵巧手 (4)** | 配置 | 关节 | 平台 | |---------|--------|----------| | `shadow_hand` | 24 | Shadow 灵巧手 | | `allegro_hand` | 16 | Wonik Allegro Hand | | `leap_hand` | 16 | CMU LEAP Hand | | `psyonic_ability` | 6 | PSYONIC Ability Hand | **移动操作机器人 (3)** | 配置 | 关节 | 平台 | |---------|--------|----------| | `spot_with_arm` | 19 | Spot + 7-DOF 机械臂 | | `hello_stretch` | 4 | Hello Robot Stretch | | `pal_tiago` | 14 | PAL Robotics TIAGo | ## CLI 参考 ``` # Key 管理 invariant keygen --kid "my-robot-001" --output keys.json # 验证 invariant validate --profile profiles/ur10.json --command cmd.json --key keys.json invariant differential --profile profiles/ur10.json --command cmd.json --key keys.json --forge # Intent pipeline invariant intent list-templates invariant intent template --template pick_and_place --param limb=left_arm --key keys.json invariant intent direct --op "actuate:left_arm:*" --key keys.json --duration 30 # Campaigns invariant campaign --config campaign.yaml --dry-run --key keys.json # 审计 invariant audit show --log audit.jsonl --last 10 invariant audit verify --log audit.jsonl --pubkey keys.json invariant audit-gaps --log audit.jsonl # 检查 invariant inspect --profile profiles/ur10.json invariant eval trace.json --preset safety-check invariant diff trace_a.json trace_b.json invariant bench --profile profiles/ur10.json --key keys.json invariant compliance --profile profiles/ur10.json --key keys.json # 对抗性测试 invariant adversarial --profile profiles/ur10.json --key keys.json --suite all # 服务器模式 invariant serve --profile profiles/ur10.json --key keys.json --port 8080 --trust-plane # Profile 管理 invariant profile init --name my_robot --joints 6 --output my_robot.json # 完整性 invariant verify-self invariant verify-package --path proof-package/ invariant transfer --sim-log sim.jsonl --real-log shadow.jsonl # Shell 补全 invariant completions bash >> ~/.bashrc invariant completions zsh > ~/.zfunc/_invariant invariant completions fish > ~/.config/fish/completions/invariant.fish ``` ## 集成 ``` Isaac Lab --> [ Invariant ] --> Isaac Sim actuators ROS 2 --> [ Invariant ] --> Hardware drivers Edge PC --> [ Invariant ] --> Cobot via safety relay Custom RL --> [ Invariant ] --> Any robot with a profile ``` ### 库嵌入 (Rust) ``` use invariant_robotics_core::validator::ValidatorConfig; let config = ValidatorConfig::new(profile, trusted_keys, signing_key, kid)?; let result = config.validate(&command, now, previous_joints)?; if result.signed_verdict.verdict.approved { // Send result.actuation_command to motor controller } ``` ### HTTP 服务器 ``` invariant serve --profile profiles/ur10.json --key keys.json --port 8080 ``` | 端点 | 方法 | 用途 | |----------|--------|---------| | `/validate` | POST | 提交命令，获取签名裁决 + 驱动命令 | | `/heartbeat` | POST | 看门狗保活 | | `/health` | GET | 状态、配置、看门狗状态、运行时间 | ### Unix Socket (Isaac Lab / Edge) ``` invariant serve --profile profiles/ur10e_cnc_tending.json --key keys.json --bridge ``` 监听 `/tmp/invariant.sock`。Python 客户端： ``` from invariant_isaac_bridge import InvariantBridge with InvariantBridge("/tmp/invariant.sock") as bridge: verdict = bridge.validate(command_dict) if verdict["approved"]: env.apply_action(verdict["signed_verdict"]) bridge.heartbeat() ``` ## 威胁模型 | # | 攻击 | 防御 | 保证 | |---|--------|---------|-----------| | 1 | 混淆代理人 | PCA 将权限追踪到人类源头 | 加密 | | 2 | 权限提升 | 单调性：操作仅能缩小范围 | 加密 | | 3 | 身份欺骗 | p_0 不可变，已签名 | 加密 | | 4 | 链伪造 | 每一跳均采用 Ed25519 | 加密 | | 5 | 重放 | 时间约束 + 序列号 | 结构性 | | 6 | 跨操作者访问 | Ops 范围防止越界 | 加密 | | 7 | 提示注入 | LLM 的跳转已缩小操作范围 | 加密 | | 8 | 审计篡改 | 哈希链 + Ed25519 条目 | 加密 | | 9 | 裁决伪造 | Ed25519 签名裁决 | 加密 | | 10 | 命令注入 | 电机需要签名的驱动命令 | 加密 | | 11 | 大脑崩溃 | 看门狗 + 签名的安全停止 | 时间 + 加密 | | 12 | 传感器欺骗 | 签名的传感器数据模块 | 加密 | 所有 12 种攻击均已在 `adversarial_test.rs` 中进行端到端测试。零逃脱。 ## 部署示例

UR10e + Haas VF-2 CNC 上下料工作站

``` EDGE PC (Invariant) UR10e HAAS VF-2 +- Safety firewall --> +- 6-axis cobot --> +- 12,000 RPM spindle +- 25 physics checks +- Schunk gripper +- 30HP +- Authority chain +- Load/unload +- M-code I/O +- Heartbeat relay +- Safety input +- Cycle coordination +- Audit logging +- Incident response ``` CNC 上下料配置文件 (`profiles/ur10e_cnc_tending.json`) 定义了： - 6 个具有真实 UR10e 硬件限制的关节 - 工作空间 `[-1.2, -0.8, 0.0]` 至 `[0.8, 0.8, 1.8]`，与工作站占地匹配 - 4 个排除区域：条件性主轴区、外壳后部、地面区域、边缘 PC - 门接近邻近区域（靠近人类时速度缩放为 50%） - 夹爪力限制：最大 140N，抓取 100N，负载 10kg - Guardian 余量：5% 位置，15% 速度，10% 扭矩，10% 加速度 - 环境感知：5 度倾斜，75 C 执行器温度，50ms 延迟，紧急停止 - 100ms 看门狗，带有 `controlled_crouch` 安全停止 ### 压力测试活动 ``` invariant keygen --kid ur10e-001 --output keys.json # 正常生产周期 (100K commands) invariant campaign --config campaigns/ur10e_normal_ops.yaml --key keys.json --dry-run # 主轴安全 (50K commands -- 机械臂试图进入 CNC 外壳) invariant campaign --config campaigns/ur10e_spindle_safety.yaml --key keys.json --dry-run # 完全对抗 (100K commands) invariant campaign --config campaigns/ur10e_adversarial.yaml --key keys.json --dry-run # Watchdog / brain crash (10K commands) invariant campaign --config campaigns/ur10e_watchdog.yaml --key keys.json --dry-run # 1M command 验证包 (~50s on MacBook) invariant campaign --config campaigns/ur10e_million_proof.yaml --key keys.json --dry-run # 1.06M episode CNC 上下料 campaign invariant campaign --config campaigns/cnc_tending_1m.yaml --key keys.json --dry-run ```

## 构建 ``` cargo build --release cargo test # ~2,047 tests cargo clippy -- -D warnings # zero warnings python3 -m pytest isaac/tests # Python tests ./examples/demo.sh # five-minute proof ``` ## 安全 要报告漏洞，请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 [MIT](LICENSE)

标签：AI安全, Chat Copilot, CISA项目, Ed25519, JSONLines, RL策略安全, Rust, 不可变, 减速器, 可信边界, 可视化界面, 命令验证, 安全防护, 审计, 密码学, 嵌入式系统, 工业安全, 手动系统调用, 控制安全, 提示词模板, 机器人安全, 机器人控制, 权限验证, 物理不变量, 监控与审计, 确定性控制, 确定性系统, 系统工程, 网络安全, 网络流量审计, 自动驾驶安全, 边缘计算安全, 通知系统, 防伪造, 防火墙, 防篡改, 隐私保护, 零信任