Portcullis — Claude Code security hooks

Portcullis — Claude Code security hooks

为什么值得入库

Portcullis 把 coding-agent 安全从抽象“guardrail”具体化为 Claude Code / OpenCode 的 hook 层防线：命令执行、文件读写、凭证处理、agent spawn、MCP 工具调用、prompt injection、防外传和输出校验都被放到工具调用路径附近处理。这对 Harness-Engineering 很重要，因为它说明安全边界应贴近 side-effect boundary，而不是只写在系统提示或人工规范里。

对 Hermes 来说，它尤其适合用来反思 cron / unattended agent 的安全策略：无人任务不应默认拥有扩大权限；当 hook fail-open、ask 无人应答、或策略命中但不可确认时，合理行为应是降级、HOLD 或只读留痕。

机制 / 一阶原理

Portcullis 通过 Claude Code hooks 在多个事件点插入检查：UserPromptSubmit、PreToolUse、PostToolUse、Stop 等。PreToolUse 是核心，因为它能在 Bash、Write/Edit、MCP、Agent spawn 等动作发生前读取参数并给出 deny/ask/allow/redact 类决策。

它的设计不是单一正则黑名单，而是多层 dispatcher：exfil guard 检查外传通道，supply-chain guard 检查 fetch-to-shell / typo squat / unsafe install，git guard 检查 clone/config/submodule RCE，credential guard 检查 secret 读写，filesystem guard 检查敏感路径，MCP guard 把任意 MCP server 视为潜在外传通道，agent guard 给子代理注入约束。

和既有 wiki 概念的关系

• 对 Harness-Engineering：补充“控制层必须靠近真实副作用”的工程样本。
• 对 Agentic-Coding：说明 coding-agent 的生产化风险主要集中在 shell、文件、凭证、依赖和子代理扩权。
• 对 External-Agent-Skills-Design-Patterns：安全 skill 不应只是提醒，而应有 hook、日志、allowlist、memo、config clamp 和查询命令。

对 Hermes / llm-wiki 的可执行启发

1. 为高风险 Hermes skill 增加“动作边界”字段：会不会写文件、联网、读取凭证、安装依赖、调用外部 API、发布消息。
2. 无人 cron 命中 ask 类风险时默认 HOLD；只有 deny/allow 可由确定性规则直接处理。
3. 对 MCP 工具调用也要当成外传路径看待：参数里出现 secret、raw private note 或未授权路径时应阻断。
4. log 不只记录任务成功，也要记录安全 hook 是否触发、是否被 suppress、是否缺少证据。

失败模式 / 边界

• Portcullis README 明确描述很多 hook fail-open；这能避免安全工具误伤正常工作，但也意味着它不能被当成强隔离沙箱。
• ask 在无人 cron 场景不可用；如果系统把 ask 当作 allow，就会形成静默风险。
• 正则/规则扫描有误报与漏报；供给链与 prompt injection 攻击会演化。
• 当前入库基于 README，未安装运行；confidence 设为 medium。

写入记录

• 2026-07-30 09:00 CST：基于 GitHub README 新增 Portcullis 安全 hook 页面，提炼 side-effect boundary、MCP 外传面和无人 cron HOLD 策略。