Habitat protects the integrity of its local record of configured jobs, trusted actions, authenticated events, claims, and signals.

It does not claim to sandbox arbitrary code or make an already-compromised operating system trustworthy.

The action ledger is tamper-evident: each recorded action is chained to the previous action with a SHA-256 digest, and claim verification refuses to treat the ledger as trusted when the chain is inconsistent. This detects modification, deletion, insertion, or incomplete ledger state after the integrity chain was established. It is not a remote or independently anchored attestation: an attacker with unrestricted database control could rewrite both the records and integrity metadata.

• API binds to 127.0.0.1 by default.
• Signed events are required by default.
• HMAC comparison uses constant-time comparison.
• Events are bounded to 256 KiB.
• Event IDs are persistent and idempotent.
• Agent permissions are explicit and least-privilege by default.
• Network claims tied to jobs require a run/correlation ID.
• SQLite is opened with foreign keys and WAL mode.
• Trusted action verification includes an integrity-chain check.
• Portable proof verification rejects non-finite JSON numbers, timezone-less timestamps, proofs larger than 16 MiB, or ledgers containing more than 10,000 actions.
• HTTP evidence adapters accept only HTTP(S), reject redirects and URL credentials, resolve every target address before connecting, reject non-global/private/link-local/loopback/reserved addresses, and bound response bodies to 1 MiB.
• Remote server and agent authentication failures are throttled to reduce brute-force and CPU-exhaustion attacks; localhost remains unthrottled.

Do not commit webhook or agent secrets. Prefer environment variables or a secret manager supplied by the deployment environment.

Agent secrets are stored as salted PBKDF2-HMAC-SHA256 hashes with a deliberately high work factor. Databases created by older Habitat versions may contain legacy SHA-256 agent-secret hashes; a successful authentication transparently upgrades that credential to the hardened format.

CLI commands do not accept agent/webhook secrets as direct arguments because command-line arguments can be exposed through shell history, process listings, CI logs, or monitoring. Use HABITAT_WEBHOOK_SECRET, HABITAT_AGENT_SECRET, or another explicitly configured environment variable instead.

The generated agent secret is displayed once by agent-add; store it securely and rotate/disable the agent if it is exposed.

Event IDs make retries idempotent after Habitat has received the event. They do not provide freshness against an attacker who captures a valid signed event and submits it before the legitimate sender's first delivery. Deployments that require replay resistance at that boundary should add a trusted freshness/nonce mechanism at the transport or agent-enforcement layer rather than treating HMAC alone as proof of freshness.

The HTTP evidence adapter rejects direct private/local addresses before opening a configured endpoint and refuses redirects, which closes the common SSRF paths. DNS can still change between validation and connection on an untrusted network. High-assurance deployments should therefore place evidence endpoints behind controlled DNS/network policy or use a fixed allowlist/reverse proxy. Habitat does not treat external HTTP evidence as proof of real-world truth merely because the HTTP request succeeded.

A proof bundle has separate assurance dimensions. Structural validity means the bundle matches the proof schema; content integrity means its digest matches; internal consistency means its claim, action, run, and ledger relationships agree; a signature, when present and valid, establishes cryptographic authenticity for the signed content; publisher trust depends on an independently configured trust relationship; and external truth is outside Habitat's own evidence boundary. A valid signed proof is therefore not automatically a trusted publisher statement or proof that the underlying real-world event happened.

For a single-user workstation, the default localhost server is appropriate.

For a shared or remote deployment:

1. Keep Habitat behind a TLS-terminating reverse proxy.
2. Restrict network access with firewall rules.
3. Use strong, rotated secrets.
4. Do not enable unsigned events.
5. Run under a dedicated OS account.
6. Give the process the minimum filesystem permissions required.
7. Back up the SQLite database.
8. Treat job commands as privileged configuration.
9. Monitor disk space and log output.
10. Treat exported proof bundles as potentially sensitive because action details and event payloads may contain operational data.

Remote authentication throttling is deliberately in-process and keyed by client address. It is a defense-in-depth control, not a substitute for a reverse proxy, firewall, rate-limiting gateway, or account lockout policy in hostile public deployments.

If an agent secret is suspected to be compromised, disable or replace that agent credential and review the event/action ledger for the affected period. If the action-integrity check fails, treat trusted claims from the affected ledger as inconclusive until the record is restored or independently corroborated. Because Habitat is an audit system, do not erase evidence merely to hide the incident.

Habitat is not a general sandbox, EDR, SIEM, secrets manager, or multi-tenant SaaS control plane. Those concerns require additional infrastructure when the deployment demands them.