openevidence-security-basics

OpenEvidence Security Basics

Table of Contents

• Overview
• Prerequisites
• Instructions
• Output
• Error Handling
• Examples
• Resources

Overview

Security best practices for OpenEvidence integrations handling Protected Health Information (PHI). Covers credential management, PHI sanitization, HIPAA audit logging, webhook verification, and data retention compliance.

Prerequisites

• OpenEvidence SDK installed
• Understanding of HIPAA requirements
• Signed Business Associate Agreement (BAA)
• Access to organization security policies

OpenEvidence Security Certifications

• SOC 2 Type II certified
• HIPAA compliant with BAA
• AES-256 encryption at rest
• TLS 1.2+ encryption in transit

Security Checklist

• [ ] API keys in secret manager (not env vars in production)
• [ ] BAA signed with OpenEvidence
• [ ] PHI sanitization before all queries
• [ ] HIPAA audit logging on all access
• [ ] Webhook signatures verified
• [ ] TLS 1.2+ enforced
• [ ] Different keys for dev/staging/prod
• [ ] Key rotation schedule established
• [ ] Data retention policy implemented

Instructions

Step 1: Secure Credential Management

Use .env locally (gitignored), GCP Secret Manager or AWS Secrets Manager in production. Never hardcode credentials.

Step 2: Implement PHI Sanitization

Remove names, dates, MRNs, SSNs from queries before sending to OpenEvidence. Map patient demographics to age ranges and condition categories instead of specific identifiers.

Step 3: Enable HIPAA Audit Logging

Log all clinical queries and DeepConsult requests with userId, userRole, resourceId, ipAddress, success status. Never log actual query content or responses (may contain PHI).

Step 4: Verify Webhook Signatures

Parse t=timestamp,v1=signature header format. Compute HMAC-SHA256 with timing-safe comparison. Reject timestamps older than 5 minutes for replay protection.

Step 5: Configure Data Retention

• Audit logs: 6 years (2190 days) -- HIPAA minimum
• Query results: Do not store (re-query as needed)
• DeepConsult reports: 1 year
• Run daily cleanup job to enforce policies

Output

• Secure credential management (GCP/AWS Secret Manager)
• PHI sanitization layer with pattern detection
• HIPAA-compliant audit logging
• Webhook signature verification with replay protection
• Data retention compliance with automated cleanup

Error Handling

Security Issue	Detection	Mitigation
Exposed API key	Git scanning alert	Rotate immediately, audit access
PHI in query	Log pattern matching	Block request, alert compliance
Failed signature	Webhook verification	Reject webhook, alert security
Unauthorized access	Audit log review	Revoke access, investigate

Examples

Secure Query Flow

const sanitized = sanitizeQueryForOpenEvidence(question, patientContext);
const response = await client.query({ question: sanitized.question, context: sanitized.context });
await auditLogger.logClinicalQuery(user.id, user.role, response.id, true, request);

See detailed implementation for advanced patterns.

Resources

• OpenEvidence Security
• HIPAA Security Rule
• NIST Cybersecurity Framework