HeartBeatAgents

Security

View as Markdown

How HeartBeatAgents enforces defense-in-depth for agents that execute code and make HTTP requests on your behalf.

Agents that can execute code and call external services need security boundaries that hold even if the agent's own reasoning goes wrong. HeartBeatAgents' design principle is that every boundary is physically unavoidable: enforced at a layer the agent's code cannot bypass, not just requested nicely of it.

The seven mechanisms

  1. Credential broker: agents receive opaque handles instead of real OAuth tokens. Actual credentials are injected only at the moment of the HTTP request and are never exposed to the LLM itself.
  2. Egress policy: read and write operations are treated differently. Public hosts are reachable via GET; POST/PUT/PATCH/DELETE are restricted to approved integration endpoints, and HTTPS is mandatory.
  3. DNS rebinding defense: DNS resolution, IP validation, and the TCP connection itself are performed atomically at the network stack.
  4. Egress proxy: all outbound traffic passes through a network-level proxy running in an isolated Docker container with kernel-enforced iptables rules.
  5. Token scrubbing: a pattern-matching scrubber inspects every output boundary (LLM context, logs, tool call history) and strips OAuth tokens, API keys, and JWTs before they can leak.
  6. WebSocket auth: connections require an authentication token up front; signature, expiry, and organization ownership are all verified before the connection is accepted.
  7. Container hardening: agents run as non-root, with dropped Linux capabilities, a read-only root filesystem, per-organization container isolation, and enforced resource limits.

What this means day to day

  • You never paste a raw API key into an agent's prompt or standing orders. See Integrations Guide for how connections are authenticated instead.
  • Revoking an integration's access is immediate and total (see Configuration).
  • Running self-hosted doesn't weaken any of this: the same container boundaries apply whether HeartBeatAgents runs on your laptop or your own server (see Self-Hosting).

How this is checked, not just designed

Secret-scanning runs on every commit in CI and as a pre-commit check, plus a periodic scan across the entire commit and tag history, so a credential that slipped into a past commit doesn't stay hidden. This is the kind of control a security review can ask to see evidence of, not just a policy this page asserts.

Development and production security are kept structurally separate, not just documented as different: startup refuses to run with a default or placeholder secret unless one explicit, loudly-logged flag opts a local install into relaxed development mode. There's no in-between setting that quietly weakens production without anyone noticing.

Folder access

Agents only reach the parts of your filesystem you explicitly share. Share a folder from Settings → Folder Access and agents can read, and unless you mark it read-only, write inside it; nothing outside a shared folder is reachable at all. System directories and credential stores are blocked from being shared, full stop, regardless of what path you try to point at. See Shared Folders for how sharing one actually works.