HealthClaw Guardrails is a reference implementation of security and compliance patterns for AI-agent access to health data. Security is the product, so we hold the codebase to the bar we advocate.
Email security@healthclaw.io. Please include a description, reproduction steps, and impact. We aim to acknowledge within 3 business days and will coordinate disclosure. Please do not open public issues for security reports.
The guardrail stack runs on every request:
| Control | What it does |
|---|---|
| PHI redaction | Reads pass through Safe-Harbor-style field redaction (demographics stripped; identifier values removed, keeping only the identifier's system and type) or patient-controlled redaction before leaving the store. It is a compensating control, not a legal de-identification determination — see README and #112. |
| Tenant isolation | Every database query is scoped to the requested tenant at the query layer; cross-tenant access is blocked. |
| Tenant-authenticated reads | Hosted deployments handling real records require a tenant-bound token on reads (config: READ_AUTH_ENABLED); synthetic/demo tenants remain open. |
| Step-up authorization | Writes require an HMAC-signed, tenant-bound, expiring token. |
| Human-in-the-loop | Real-world actions require out-of-band approval at a separate endpoint with a single-use step-up credential — an agent cannot approve its own action. Direct clinical FHIR writes currently return HTTP 428 until the X-Human-Confirmed header is present; that header is client-supplied and is being migrated to the action-rail mechanism (#214). |
| Append-only audit | Every read/write/action is logged immutably (no UPDATE/DELETE on audit rows, enforced at the ORM layer). |
| Transport & headers | HTTPS; HSTS, CSP, X-Content-Type-Options, X-Frame-Options: DENY, Referrer-Policy, Permissions-Policy on every response. |
| Abuse controls | Per-tenant/per-IP rate limiting, request payload caps, and replay-resistant tokens. |
Production deployments should set:
READ_AUTH_ENABLED=trueandPUBLIC_TENANTS=<demo tenants only>— authenticate reads for real tenants.STEP_UP_SECRET— strong random secret for HMAC tokens.INTERNAL_TOKEN_MINT_SECRET— locks the internal token-mint endpoint; distribute to trusted minters only.ACTIONS_WEBHOOK_SECRET— verifies real-world-action provider callbacks.- Terminate TLS at the edge; run behind a WAF; back the rate-limit/nonce stores with Redis for multi-worker.
This is a reference implementation, not a turnkey production PHI service. Local mode stores JSON blobs in SQLite. Validation is structural (US Core v9 required fields), not full StructureDefinition conformance or terminology binding. The hosted demo runs synthetic or patient-directed data. Operators deploying this to process ePHI are responsible for their own BAA-covered infrastructure, access governance, and compliance program — see the Terms of Service.
When records are delivered through consumer chat platforms (Telegram, Slack, Discord), HealthClaw acts as the patient's own agent retrieving the patient's own records to a channel the patient chooses — patient-directed access under HIPAA's individual right of access, after a clear risk acknowledgment. These channels are not BAA-covered transport. Notifications are PHI-free by rule, reads are redacted, and a summary-only mode is available.