AGENT SKILL

openevidence-security-basics

Apply OpenEvidence security best practices for HIPAA compliance and PHI protection. Use when securing API keys, implementing PHI handling, or auditing OpenEvidence security configuration. Trigger with phrases like "openevidence security", "openevidence hipaa", "openevidence phi", "secure openevidence", "openevidence compliance".

适用职业律师与法务
License 许可
MIT
最近更新
2026-11-15
Stars
★ 2.0k
Forks
233

01 前言 Front Matter

name
openevidence-security-basics
author
Jeremy Longshore <jeremy@intentsolutions.io>
license
MIT
version
1.0.0
description
Apply OpenEvidence security best practices for HIPAA compliance and PHI protection. Use when securing API keys, implementing PHI handling, or auditing OpenEvidence security configuration. Trigger with phrases like "openevidence security", "openevidence hipaa", "openevidence phi", "secure openevidence", "openevidence compliance".
allowed-tools
Read, Write, Grep

03 SKILL.md 正文

OpenEvidence Security Basics

Overview

Security best practices for OpenEvidence integrations handling Protected Health Information (PHI) in compliance with HIPAA regulations.

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
  • AES-256 encryption at rest
  • TLS 1.2+ encryption in transit
  • Google Cloud Platform hosted

Instructions

Step 1: Secure Credential Management

# .env (NEVER commit to git)
OPENEVIDENCE_API_KEY=oe_live_***
OPENEVIDENCE_ORG_ID=org_***
OPENEVIDENCE_WEBHOOK_SECRET=whsec_***

# .gitignore (REQUIRED)
.env
.env.local
.env.*.local
*.pem
*.key
credentials*.json
// src/config/secrets.ts
// Use secret manager in production (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault)
import { SecretManagerServiceClient } from '@google-cloud/secret-manager';

const client = new SecretManagerServiceClient();

export async function getOpenEvidenceCredentials(): Promise<{
  apiKey: string;
  orgId: string;
}> {
  const [apiKeyVersion] = await client.accessSecretVersion({
    name: 'projects/my-project/secrets/openevidence-api-key/versions/latest',
  });
  const [orgIdVersion] = await client.accessSecretVersion({
    name: 'projects/my-project/secrets/openevidence-org-id/versions/latest',
  });

  return {
    apiKey: apiKeyVersion.payload!.data!.toString(),
    orgId: orgIdVersion.payload!.data!.toString(),
  };
}

Step 2: PHI Handling - Input Sanitization

// src/openevidence/phi-handler.ts
// IMPORTANT: OpenEvidence should NOT receive direct PHI in queries

interface SanitizedQuery {
  question: string;
  context: {
    ageRange?: string; // "65-74" not exact age
    sex?: string;
    conditionCategories?: string[]; // "cardiovascular" not specific diagnosis
  };
}

export function sanitizeQueryForOpenEvidence(
  question: string,
  patientContext?: PatientContext
): SanitizedQuery {
  // Remove any PHI that might have leaked into the question
  let sanitized = question;

  // Remove potential names
  sanitized = sanitized.replace(/\b(Mr\.|Mrs\.|Ms\.|Dr\.)\s+[A-Z][a-z]+\b/g, '[PATIENT]');

  // Remove dates of birth
  sanitized = sanitized.replace(/\b\d{1,2}[\/\-]\d{1,2}[\/\-]\d{2,4}\b/g, '[DATE]');

  // Remove MRNs
  sanitized = sanitized.replace(/\bMRN[:\s]*\d+\b/gi, '[MRN]');

  // Remove SSNs
  sanitized = sanitized.replace(/\b\d{3}-\d{2}-\d{4}\b/g, '[SSN]');

  return {
    question: sanitized,
    context: patientContext ? {
      ageRange: getAgeRange(patientContext.age),
      sex: patientContext.sex,
      conditionCategories: categorizeConditions(patientContext.conditions),
    } : undefined,
  };
}

function getAgeRange(age?: number): string | undefined {
  if (!age) return undefined;
  if (age < 18) return 'pediatric';
  if (age < 40) return '18-39';
  if (age < 65) return '40-64';
  if (age < 75) return '65-74';
  return '75+';
}

function categorizeConditions(conditions?: string[]): string[] | undefined {
  // Map specific conditions to categories
  const categoryMap: Record<string, string> = {
    'hypertension': 'cardiovascular',
    'diabetes': 'endocrine',
    'asthma': 'pulmonary',
    // ... more mappings
  };

  return conditions?.map(c => categoryMap[c.toLowerCase()] || 'other');
}

Step 3: Audit Logging (HIPAA Required)

// src/openevidence/audit-log.ts
interface AuditEntry {
  timestamp: Date;
  eventType: 'query' | 'deepconsult' | 'access' | 'export';
  userId: string;
  userRole: string;
  action: string;
  resourceType: 'clinical_answer' | 'research_report';
  resourceId?: string;
  ipAddress: string;
  userAgent: string;
  success: boolean;
  errorCode?: string;
  // Never log the actual query content or response - may contain PHI
}

export class HIPAAAuditLogger {
  private logStore: AuditLogStore;

  constructor(store: AuditLogStore) {
    this.logStore = store;
  }

  async logClinicalQuery(
    userId: string,
    userRole: string,
    queryId: string,
    success: boolean,
    request: Request
  ): Promise<void> {
    await this.logStore.insert({
      timestamp: new Date(),
      eventType: 'query',
      userId,
      userRole,
      action: 'clinical_query',
      resourceType: 'clinical_answer',
      resourceId: queryId,
      ipAddress: this.getClientIP(request),
      userAgent: request.headers.get('user-agent') || 'unknown',
      success,
    });
  }

  async logDeepConsult(
    userId: string,
    userRole: string,
    consultId: string,
    success: boolean,
    request: Request
  ): Promise<void> {
    await this.logStore.insert({
      timestamp: new Date(),
      eventType: 'deepconsult',
      userId,
      userRole,
      action: 'research_synthesis',
      resourceType: 'research_report',
      resourceId: consultId,
      ipAddress: this.getClientIP(request),
      userAgent: request.headers.get('user-agent') || 'unknown',
      success,
    });
  }

  private getClientIP(request: Request): string {
    // Handle proxies
    const forwarded = request.headers.get('x-forwarded-for');
    if (forwarded) return forwarded.split(',')[0].trim();
    return 'unknown';
  }
}

Step 4: Webhook Signature Verification

// src/openevidence/webhook-security.ts
import crypto from 'crypto';

export function verifyWebhookSignature(
  payload: string | Buffer,
  signature: string,
  secret: string,
  tolerance: number = 300 // 5 minute tolerance
): boolean {
  // Parse signature header: t=timestamp,v1=signature
  const parts = signature.split(',').reduce((acc, part) => {
    const [key, value] = part.split('=');
    acc[key] = value;
    return acc;
  }, {} as Record<string, string>);

  const timestamp = parseInt(parts['t']);
  const providedSignature = parts['v1'];

  // Check timestamp to prevent replay attacks
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > tolerance) {
    console.error('Webhook timestamp too old or in future');
    return false;
  }

  // Compute expected signature
  const signedPayload = `${timestamp}.${payload}`;
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  // Timing-safe comparison
  try {
    return crypto.timingSafeEqual(
      Buffer.from(providedSignature),
      Buffer.from(expectedSignature)
    );
  } catch {
    return false;
  }
}

Step 5: Data Retention Compliance

// src/openevidence/data-retention.ts
// HIPAA requires minimum 6-year retention of access logs

interface RetentionPolicy {
  auditLogs: number;      // days
  queryResults: number;   // days
  deepConsultReports: number; // days
}

const HIPAA_RETENTION: RetentionPolicy = {
  auditLogs: 2190,        // 6 years
  queryResults: 0,        // Do not store (re-query as needed)
  deepConsultReports: 365, // 1 year (user can re-run)
};

export class DataRetentionManager {
  constructor(private policy: RetentionPolicy = HIPAA_RETENTION) {}

  async cleanupExpiredData(): Promise<CleanupReport> {
    const cutoffs = {
      auditLogs: new Date(Date.now() - this.policy.auditLogs * 24 * 60 * 60 * 1000),
      deepConsultReports: new Date(Date.now() - this.policy.deepConsultReports * 24 * 60 * 60 * 1000),
    };

    // Note: Audit logs should be archived, not deleted
    const archivedLogs = await db.auditLogs.archive({
      where: { timestamp: { lt: cutoffs.auditLogs } },
    });

    const deletedReports = await db.deepConsultReports.deleteMany({
      where: { createdAt: { lt: cutoffs.deepConsultReports } },
    });

    return {
      auditLogsArchived: archivedLogs.count,
      reportsDeleted: deletedReports.count,
      executedAt: new Date(),
    };
  }
}

Security Checklist

  • [ ] API keys stored in secret manager (not env vars in production)
  • [ ] BAA signed with OpenEvidence
  • [ ] PHI sanitization before sending queries
  • [ ] Audit logging enabled for all access
  • [ ] Webhook signatures verified
  • [ ] TLS 1.2+ enforced
  • [ ] IP allowlist configured (if available)
  • [ ] Different keys for dev/staging/prod
  • [ ] Key rotation schedule established
  • [ ] Data retention policy implemented

Output

  • Secure credential management
  • PHI sanitization layer
  • HIPAA-compliant audit logging
  • Webhook signature verification
  • Data retention compliance

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 Service

const auditLogger = new HIPAAAuditLogger(auditStore);

export async function secureClinicaQuery(
  question: string,
  patientContext: PatientContext | undefined,
  user: AuthenticatedUser,
  request: Request
): Promise<ClinicalResponse> {
  // 1. Sanitize input
  const sanitized = sanitizeQueryForOpenEvidence(question, patientContext);

  // 2. Make query
  const response = await client.query({
    question: sanitized.question,
    context: {
      specialty: 'internal-medicine',
      urgency: 'routine',
      ...sanitized.context,
    },
  });

  // 3. Audit log
  await auditLogger.logClinicalQuery(
    user.id,
    user.role,
    response.id,
    true,
    request
  );

  return response;
}

Resources

Next Steps

For production deployment, see openevidence-prod-checklist.

04 同仓库更多 Skills

Dicklesworthstone
Dicklesworthstone/pi_agent_rust

theme-factory

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

视觉设计
★ 2.0k
Dicklesworthstone
Dicklesworthstone/pi_agent_rust

web-artifacts-builder

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

前端开发
★ 2.0k
Dicklesworthstone
Dicklesworthstone/pi_agent_rust

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

测试与质量前端开发
★ 2.0k
Dicklesworthstone
Dicklesworthstone/pi_agent_rust

neuropixels-analysis

Neuropixels neural recording analysis. Load SpikeGLX/OpenEphys data, preprocess, motion correction, Kilosort4 spike sorting, quality metrics, Allen/IBL curation, AI-assisted visual analysis, for Neuropixels 1.0/2.0 extracellular electrophysiology. Use when working with neural recordings, spike sorting, extracellular electrophysiology, or when the user mentions Neuropixels, SpikeGLX, Open Ephys, Kilosort, quality metrics, or unit curation.

★ 2.0k
Dicklesworthstone
Dicklesworthstone/pi_agent_rust

skill-creator

Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.

Skill与智能体开发
★ 2.0k
Dicklesworthstone
Dicklesworthstone/pi_agent_rust

notebooklm

Use this skill to query your Google NotebookLM notebooks directly from Claude Code for source-grounded, citation-backed answers from Gemini. Browser automation, library management, persistent auth. Drastically reduced hallucinations through document-only responses.

Skill与智能体开发
★ 2.0k