Potpie 守护进程信号回退限制SPEC-CHANGE-0012基于 PID 复用漏洞的 fail-closed 受控终止设计【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie导读本文以 Potpie 仓库中的规范变更记录 SPEC-CHANGE-0012 为主体讲解 Potpie 守护进程daemon从允许对重连进程发送SIGTERM/SIGKILL回退信号到仅允许对当前控制器直接创建的子进程做有界终止的安全收紧过程。文中将结合 ADR-0012、守护进程模块契约 以及 lifecycle.py、controller.py 等源码实现说明 PID 复用漏洞的成因、DAEMON-052~056 五项新增行为、typed 失败语义与所有权锁串行化的底层原理。读完本文你将掌握 Potpie 守护进程附着attach停止与直接子进程停止两种路径的完整安全模型以及如何通过规范、ADR、conformance 记录与测试来验证这类安全变更。一、背景daemon.pid里的数字为什么会变成安全隐患1.1 Potpie 守护进程的跨调用重连模型Potpie 的本地守护进程由 CLI 作为前台子进程直接创建运行期间通过 discovery.py 写入三类 owner-only 运行时记录记录文件作用daemon.pid记录守护进程的数值 PIDPID_FILENAME见 discovery.pydiscovery.json记录 schema 版本、instance_id、PID、传输端点UDS/TCP、协议范围与认证方案daemon.credential记录 bearer token至少 256 bit见 write_daemon_credentialCLI 命令是短生命周期的而前台守护进程是长生命周期的。因此后续的 CLI 调用会通过读取daemon.pid重新构造一个进程句柄来附着attach到早前启动的守护进程上——这正是 controller.py 中DaemonController.attach()的设计初衷_RecordedDaemonProcess只保存一个数值 PID而不是操作系统进程句柄。1.2 PID 复用如何变成误杀无辜进程问题出在数值 PID 可以被操作系统复用上第一次 CLI 启动守护进程写入daemon.pid记录 PIDN守护进程崩溃退出操作系统之后把 PIDN 分配给了另一个同用户的不相关进程后续 CLI 调用读取daemon.pid看到 PIDN 仍然存活旧实现中当无法通过发现记录完成认证missing / invalid / unauthenticated discovery时控制器会基于这个数值 PID 发送SIGTERM超时后可能继续SIGKILL。由于 Potpie 的运行时文件只证明谁创建了这些文件无法证明当前占用该 PID 的进程是谁见 ADR-0012 的 Context 部分这就构成了一个本地同用户进程误终止/恶意终止漏洞。ADR-0012 将其定性为PID 是诊断元数据而不是守护进程实例身份对应契约中的DAEMON-012与DAEMON-046。1.3 旧授权的来源ADR-0009 的有界终止回退此前的 ADR-0009 在选定认证 typed shutdown作为守护进程规范停止方式的同时也允许在无法对任何存活端点完成认证时进行有界的操作系统终止。正是这个no live endpoint 可认证时的回退打开了漏洞窗口。SPEC-CHANGE-0012 与 ADR-0012 只废除这一处回退授权其余部分保持不变详见 ADR-0012 的 Decision 部分。二、变更核心Revision 1 → 2 的语义差异SPEC-CHANGE-0012 将守护进程规范从 revision 1 推进到 revision 2change_type: securityaccepted byuser:dsantra变更记录头部其语义差异可以概括为三句话从运行时记录重连的守护进程保留 authenticated typed shutdown但当认证失败、shutdown 失败或 shutdown 超时时只返回 typed 非成功结果绝不发送SIGTERM/SIGKILL当前控制器直接创建的子进程保留就绪失败清理与shutdown 不完整时的有界终止先SIGTERM超时后SIGKILL附着停止后的清理只允许删除能证明属于精确期望 PID 且匹配 per-boot 实例身份的记录。这正是fail-closed失败即关闭的设计在无法证明进程身份时宁可停止失败并要求人工恢复也不冒险向未知进程发送信号。三、新增行为规范DAEMON-052 ~ DAEMON-056变更记录以行为操作Behavior Operations表格新增了 5 项行为SPEC-CHANGE-0012 原文表格并已在 守护进程模块契约 revision 2 中固化为规范性要求行为 ID规范要求DAEMON 契约原文对应源码位置DAEMON-052OS 信号仅限发送给当前控制器直接拥有的子进程句柄controller.py_bounded_terminate仅由 owned 分支调用DAEMON-053附着 shutdown 无法完成时返回 typed 错误不发送信号、不声称已停止controller.py_attached_stop_failureDAEMON-054规范 PID、发现与凭据的发布必须与运行时所有权锁串行化lifecycle.pystart()中启动前先经_cleanup_runtime_records取锁DAEMON-055规范 PID、发现、凭据与 owned-UDS 的移除必须与运行时所有权锁串行化lifecycle.py_cleanup_runtime_records_under_lockDAEMON-056身份绑定清理必须同时匹配精确期望 PID与per-boot 实例discovery.pyremove_daemon_runtime_records其中 DAEMON-054/055 的所有权锁即 ownership.py 中的RuntimeOwnershipLock基于fcntl.flockPOSIX或msvcrt.lockingWindows的跨平台 owner-only 排他锁。锁的意义在于防止并发 stop 抹掉正在进行的替换启动replacement boot的记录——即避免 check-then-unlink 竞态。四、源码级剖析所有权如何落到代码上4.1 所有权标志_owns_processDaemonController内部用一个布尔标志区分两种进程来源controller.pystart()通过asyncio.create_subprocess_exec创建子进程后立即设置self._owns_process Truecontroller.pyattach()附着早前调用启动的进程时设置self._owns_process Falsecontroller.py并在注释中明确这是同一 CLI 生态内的重连不是外部 supervisor 集成。这个标志是整个信号权限判断的唯一依据stop()中凡是走_bounded_terminate的分支都必须满足self._owns_process否则一律转向_attached_stop_failurecontroller.py。4.2 附着停止的失败矩阵stop()的附着分支覆盖了三种失败场景全部返回 typedResourceLifecycleError场景错误码行为认证无法建立发现缺失/不匹配daemon_attached_identity_unavailable拒绝基于记录 PID 发信号lifecycle.py认证成功但 shutdown 请求失败daemon_attached_shutdown_unavailable不降级为 OS 信号controller.pyshutdown 请求成功但超时未退出daemon_attached_shutdown_timeout不降级为 OS 信号controller.py错误携带pid、cause_category/cause_code细节、recommended_next_actioninspect daemon status and runtime records before manual recovery与retry_posturesafecontroller.py。这些字段来自 resource_manager.py 中ResourceLifecycleError的契约定义。4.3_pid_alive僵尸进程与 EPERM 的细节处理判断 PID 是否存活并不是简单的kill(pid, 0)。_pid_alivelifecycle.py依次处理了三个边界先收割僵尸POSIX 下kill(pid, 0)对已退出但未收割的子进程仍会成功因此先os.waitpid(pid, os.WNOHANG)收割自己名下的僵尸ProcessLookupError→ 不存活PermissionErrorEPERM→ 视为存活说明进程存在但不是本用户可发信号的对象按存活处理避免把跨用户进程误判为 stale PID 后执行运行时记录清理。_RecordedDaemonProcesslifecycle.py虽然仍暴露terminate()/kill()方法但已不再有任何调用路径会让附着控制器走到它们——这正是移除回退后遗留的、仅供 owned 句柄使用的进程接口。4.4 身份绑定清理精确 PID per-boot 实例清理运行时记录不是无条件的删除。discovery.py 的remove_daemon_runtime_records要求调用方传入expected_instance_id与expected_pid只有当discovery.instance_id expected_instance_id且discovery.pid expected_pid时才删除discovery.json、daemon.credential、daemon.pid以及对应的 UDS socket若instance_id或 PID 不匹配例如记录已被替换启动覆盖函数直接返回不动任何文件。在 lifecycle.py 的附着停止成功路径中清理以_cleanup_runtime_records_under_lock执行——先取所有权锁再删除锁获取失败则抛出daemon_cleanup_ownership_conflictlifecycle.py从而杜绝无验证的陈旧控制器或check-then-unlink 竞态抹掉替换启动的记录。五、失败语义与 CLI 交互5.1 typed 非成功结果而非成功字符串ADR-0012 的 Consequences 明确指出停止被拒绝从成功的 detail 字符串变为 typed 非成功结果。在 lifecycle.py 中附着身份不可用时抛DaemonStopError(ResourceLifecycleError(...))CLI 层将该异常映射为非零退出码对应 CLI 契约CLI-031的nonzero failure exits要求见变更记录的 Computed Impact Review不会报告守护进程已停止而是建议人工恢复inspect daemon status and runtime records before manual recovery。5.2 什么保持不变变更只收紧信号回退以下行为完全不受影响ADR-0012 Consequences健康守护进程仍通过 authenticated typed daemon-control 操作优雅停止直接子进程就绪失败时的有界终止SIGTERM→ 超时SIGKILLstop_timeout_s默认 10 秒见 lifecycle.py保留守护进程传输、bearer 认证、发现 schema、正常重启行为重启生成新 boot 身份对应DAEMON-034全部不变。六、兼容性、安全影响与 conformance 失效6.1 漏洞修复的收益ADR-0012 的安全收益可归纳为三点陈旧或被复用的记录 PID无法再授权SIGTERM/SIGKILL附着停止失败时fail closed无响应守护进程可能需要人工恢复这是有意为之的取舍直到 Potpie 具备稳定的进程化身process-incarnation身份契约之前强制终止被移除运行时记录清理不会通过未验证的陈旧控制器或竞态删除替换启动的记录。6.2 Conformance 记录的失效与后继变更记录明确列出三类 conformance 记录将因此失效Conformance InvalidationDaemon 记录旧记录钉住 SPEC-DAEMON revision 1 与允许 PID-only 信号回退的实现派生为 staleCLI 记录因其把 Daemon revision 1 钉为相关依赖而派生为 staleCross-system 记录在 PR head 与实现身份推进后派生为 stale。同时要求现有记录保持在其钉住的 Git ref 上不变revision 1 不可变实现并验证后发布后继记录。实际后继记录 spec/conformance/daemon.md 已在仓库中它钉住spec_revision: 2result: passed逐项验证了DAEMON-001~DAEMON-056其中DAEMON-052~056 全部标记为 complete/passed并给出可复现证据 D2-E1~D2-E5含uv run pytest tests -m not premerge_journey -q的1447 passed, 4 skipped完整根测试通道。七、验证与测试证据7.1 规范层验证SPEC-CHANGE-0012 的 Validation 区块声明结构校验 0 警告语义上将信号授权、拒绝结果、发布串行化、移除串行化、身份匹配视为相互独立的原子义务Validation。7.2 源码层测试仓库测试覆盖了本变更的核心路径test_daemon_lifecycle_runtime.py 中的test_pid_alive_reaps_an_exited_child_before_signal_probe、test_pid_alive_uses_signal_probe_for_a_non_child、test_pid_alive_treats_permission_denied_signal_probe_as_alive直接验证_pid_alive的僵尸/EPERM 边界test_stop_preserves_credential_while_replacement_boot_owns_runtime验证替换启动期间不误删凭据test_runtime_ownership.py 验证RuntimeOwnershipLock的排他语义test_daemon_controller.py 与 test_cli_daemon_service.py 覆盖附着控制器拒绝、CLI 失败退出与健康 typed-stop 对照。这些测试对应变更记录 Computed Impact Review 中Daemon tests添加 stale-PID、附着控制器拒绝、CLI 失败、健康 typed-stop 对照的要求。八、延伸阅读路径若想进一步理解这套安全模型建议按以下顺序阅读仓库内相关文档ADR-0012本变更的决策全文含备选方案保留 PID-only 终止、认证后发信号、持久化进程化身 token、匹配可执行名为何被否决的分析守护进程模块契约revision 2 的完整规范文本含生命周期状态机starting → ready → draining → failed → stopped与失败汇总表Attached shutdown cannot authenticate, fails, or times out → ResourceLifecycleError; no signal and no stopped claim守护进程 conformance 记录DAEMON-001~DAEMON-056的逐项验证证据SPEC-CHANGE-0011 与 ADR-0005、ADR-0009理解 typed daemon/CLI 边界与认证 typed shutdown 的由来实现源码daemon/lifecycle.py、runtime/controller.py、daemon/discovery.py、runtime/ownership.py。总结SPEC-CHANGE-0012 是一次教科书式的安全收紧变更——它没有推翻认证 typed shutdown 的设计而是精确切除了一条危险的信号回退路径并用所有权标志 身份绑定清理 所有权锁串行化 typed 失败语义四层机制把守护进程终止限定在可证明归属的范围内。对任何构建CLI 长驻进程或本地守护进程的开发者这套从规范到实现的 fail-closed 方法论都极具参考价值。【免费下载链接】potpieContext Graph for AI Native SDLC项目地址: https://gitcode.com/GitHub_Trending/po/potpie创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考