docs(part19): correct security playbook to real Hermes Agent schema#20
Conversation
Replace the fictional security: config block (provenance, approval regex/denylist, secrets.scope, network.egress_allowlist) with the real Hermes schema: top-level approvals: (mode manual|smart|off), native dangerous-command detector + hardline blocklist, command_allowlist, .env user allowlists, security.redact_secrets, terminal.backend isolation, and mcp_servers tools include/exclude. Frame OS-level isolation as the only real boundary per SECURITY.md. Resolves #19 Co-Authored-By: Rob <onerobby@gmail.com>
🤖 Devin AI EngineerI'll be helping with this pull request! Here's what you should know: ✅ I will automatically:
Note: I can only respond to comments from users who have write access to this repository. ⚙️ Control Options:
|
![devin-ai-integration[bot]](https://avatars.githubusercontent.com/in/811515?s=60&v=4){kind=small}
| --- | ||
|
|
||
| ## Layer 6: MCP Server Trust Model | ||
| ## Layer 5: MCP and Plugin Trust |
There was a problem hiding this comment.
🟡 Section heading renames break 5 existing anchor cross-links across the repo
Renaming Part 19's section headings (e.g. "Layer 1: Input Origin Labeling" → "Layer 1: User Authorization", "Layer 6: MCP Server Trust Model" → "Layer 5: MCP and Plugin Trust", "Layer 2: Approval and Denylist Layers" → "Layer 2: Dangerous-Command Approval") breaks 5 existing anchor-based cross-links that target the old headings. The CI markdown-link-check is configured with check-modified-files-only: 'yes' (.github/workflows/ci.yml:21) so it won't detect these breakages in unmodified files.
Broken links (5 total)
skills/ops/telegram-triage/SKILL.md:83→#layer-1-input-origin-labeling(gone)skills/dev/pr-review/SKILL.md:90→#layer-6-mcp-server-trust-model(gone)part17-mcp-servers.md:201→#mcp-server-trust-model(gone)part18-coding-agents.md:246→#approval-and-denylist-layers(gone)part21-remote-sandboxes.md:260→#mcp-server-trust-model(gone)
Prompt for agents
The PR renames several section headings in part19-security-playbook.md which breaks 5 anchor-based cross-links in other files. The following files need their links updated to match the new heading anchors:
1. skills/ops/telegram-triage/SKILL.md line 83: change #layer-1-input-origin-labeling to #layer-1-user-authorization--who-can-talk-to-the-agent (and update link text from 'provenance labels' to match the new concept)
2. skills/dev/pr-review/SKILL.md line 90: change #layer-6-mcp-server-trust-model to #layer-5-mcp-and-plugin-trust
3. part17-mcp-servers.md line 201: change #mcp-server-trust-model to #layer-5-mcp-and-plugin-trust
4. part18-coding-agents.md line 246: change #approval-and-denylist-layers to #layer-2-dangerous-command-approval
5. part21-remote-sandboxes.md line 260: change #mcp-server-trust-model to #layer-5-mcp-and-plugin-trust
Additionally, the link text and surrounding descriptions in these files may reference old concepts (provenance labels, MCP trust levels, approval bypass subagents, denylist) that Part 19 now explicitly says don't exist in Hermes. Consider updating the text to match the corrected guidance.
Was this helpful? React with 👍 or 👎 to provide feedback.
There was a problem hiding this comment.
Good catch — confirmed and fixed in ddfaebd. Repointed all 5 anchor cross-links to the renamed Part 19 headings:
skills/ops/telegram-triage/SKILL.md→#layer-1-user-authorization--who-can-talk-to-the-agent(also updated link text from "provenance labels" → "user authorization")skills/dev/pr-review/SKILL.md→#layer-5-mcp-and-plugin-trustpart17-mcp-servers.md→#layer-5-mcp-and-plugin-trustpart18-coding-agents.md→#layer-2-dangerous-command-approvalpart21-remote-sandboxes.md→#layer-5-mcp-and-plugin-trust
Verified each with markdown-link-check. Note: the deeper concept drift you flagged (telegram-triage still showing a trust_label: example, part17's allow_sampling:, part16's bypass_subagents anchor, part18's auto_approve_read/require_approval example) is the same fictional schema living in other files — out of scope for issue #19 (Part 19 only), but I'm flagging it to the maintainer as follow-up work.
Part 19's section headings were renamed to match the real Hermes schema; repoint the 5 anchor cross-links in part17/18/21 and the telegram-triage and pr-review skills so they don't 404. CI link-check only scans modified files, so these unmodified-file breakages needed manual repair. Co-Authored-By: Rob <onerobby@gmail.com>
1 participant
Summary
Part 19 documented a fictional Hermes config schema — a top-level
security:block withprovenance,approval.require_approvalregex +denylist,approval_channels,bypass_subagents,secrets.scope/secrets.env_access, andsecurity.network.egress_allowlist. None of those keys exist in Hermes Agent, so operators following the old guide were writing config that is silently ignored — a false sense of security. This PR rewrites the playbook against the real schema verified from the official Hermes Agent docs and SECURITY.md. Resolves #19.What changed (fiction → reality)
security.approval.require_approval/denylist/approval_channelsregex → real top-levelapprovals:(mode: manual|smart|off,timeout,cron_mode,mcp_reload_confirm,destructive_slash_confirm). Dangerous patterns are native (tools/approval.py), not user regex; documented the always-onUNRECOVERABLE_BLOCKLIST,command_allowlist:(human-readable descriptions), YOLO mode, the container-backend approval bypass, and optionalsecurity.tirith_*scanning.security.provenancetrust-labeling block → replaced with real user authorization (.envallowlists:TELEGRAM_ALLOWED_USERS,GATEWAY_ALLOWED_USERS, default-deny, DM pairing,discord.require_mention).secrets.scope: per_tool/env_access/ customredaction.patterns→ realsecurity.redact_secrets,.env0600perms, and automatic credential scoping for shell/MCP/code-exec subprocesses. Added the SECURITY.md caveat that this is leak-reduction, not containment.security.network.egress_allowlist/block_private_ranges/block_metadata_ip→ egress control actually lives in the terminal backend / whole-process sandbox (Docker/Compose or NVIDIA OpenShell L7 policy).trust:/allow_sampling/tools_allowlist/max_concurrent_callskeys → realmcp_servers.<name>withenv:credential filtering andtools.include/exclude; trust = operator review before install (skills run Python at import, plugins run with full privileges) + Skills Guard.gateways:block and--profile quarantineprofiles with accurate guidance.CHANGELOG.mdentry added (follows the existing "Part 20 routing schema fixes" precedent).Type
Checklist
./partN-foo.md) and resolve (markdown-link-checkpasses — 10/10 links)${VAR}placeholders onlytemplates/config/security-hardened.yamlcarries the same fictional schema and should be fixed in a follow-up)Link to Devin session: https://app.devin.ai/sessions/1db51c934b3e40a3a54b58fdb5c788ae
Requested by: @OnlyTerp