healthsecure 0.2.0a1

Runtime sensitive data exposure detection SDK

HealthSecure

HealthSecure is a runtime sensitive data exposure detection library for APIs and LLM outputs.

It helps engineering teams detect when sensitive data (medical, financial, credentials, personal identifiers) is unintentionally exposed in production responses, without sending raw data outside their systems.

HealthSecure analyzes responses locally, generates privacy-preserving risk signals, and sends only metadata to a centralized risk engine. Raw content is never stored or transmitted.

---

Why HealthSecure

Modern applications increasingly rely on:

• APIs returning user data

• LLMs generating dynamic responses

• Logs and services emitting free-text output

Sensitive data leaks often happen at runtime, after:

• schema design

• code review

• static analysis

• compliance documentation

HealthSecure provides visibility where traditional tools fail:

in live outputs, not in databases or schemas.

---

How It Works

1. Local Analysis (SDK)

• Inspects API or LLM responses in memory

• Detects sensitive data patterns using schema-agnostic heuristics

• Discards raw data immediately

2. Signal Generation

• Produces a minimal, irreversible signal describing:

  • detected data classes

  • identifiability

  • confidence

  • environment and region

3. Risk Evaluation

• Applies deterministic risk policy

• Returns a clear risk level: LOW, MEDIUM, or HIGH

• Backend never processes raw content

---

Key Principles

• No raw data ingestion

• Schema-agnostic detection

• Deterministic and explainable behavior

• SDK-first design

• Privacy-by-design

• Production-focused

---

Supported Data Classes

• Medical data

• Financial data

• Credentials (API keys, tokens, secrets)

• Personal identifiers (email, phone)

v2 Features

• Confidence Bands: Automatic mapping of confidence scores to LOW/MEDIUM/HIGH bands
• Reason Codes: Explainable detection reasons (MEDICAL_TERM, CREDENTIAL_PATTERN, EMAIL_PATTERN, etc.)
• Signal Fingerprinting: Privacy-safe hashing for deduplication
• Policy Context: Optional policy configuration (min_confidence, blocked_classes)
• Execution Context: Enhanced metadata (channel, mode, sdk_version)

---

Typical Use Cases

• Detect accidental leakage in LLM responses

• Monitor API responses for sensitive exposure

• Catch credential leaks in logs or service outputs

• Add a runtime safety layer without refactoring systems

---

What HealthSecure Does NOT Do

• Does not store or transmit raw data

• Does not guarantee regulatory compliance

• Does not interpret business schemas

• Does not perform audits or certifications

• Does not replace encryption or access control

HealthSecure is a risk detection layer, not a compliance authority.

---

Installation

pip install healthsecure==0.2.0a1

---

Quick Example

from healthsecure import extract_v2_json, build_v2_signal, HealthSecureClient

raw_response = {
    "message": "API token leaked: sk_live_ABC123",
    "status": "error"
}

# v2 extraction with reason codes and confidence bands
extract = extract_v2_json(raw_response)
# Returns: detected_data_classes, identifiers_present, confidence,
#          confidence_band, reasons

# Build v2 signal with enhanced metadata
signal = build_v2_signal(
    extract,
    source="api_response",
    region="EU",
    environment="production"
)
# Signal includes: fingerprint, confidence_band, reasons

client = HealthSecureClient(api_key="YOUR_API_KEY")
result = client.analyze_signal(signal)

print(f"Risk: {result.risk_level}")
print(f"Reasons: {signal.reasons}")
print(f"Confidence Band: {signal.confidence_band}")

---

Killer Demo: Safe LLM Wrapper

Instant relevance for AI teams - Wrap your LLM calls to detect sensitive data leakage:

from healthsecure import safe_llm_call

# Wrap any LLM response
response, risk = safe_llm_call(
    "Patient John Doe ([e-mail]) was diagnosed with HIV"
)

if risk == "HIGH":
    print("⚠️  Sensitive data detected! Blocking response.")
    # Block or sanitize response
else:
    print("✅ Response safe to return")

See full example: example-app/safe_llm_call.py

---

API Reference

extract_v2_json(raw: Any) -> Dict[str, Any]

v2 extraction for JSON payloads with reason codes. Returns:

• detected_data_classes: List of data classes
• identifiers_present: Boolean
• confidence: Float (0.0-1.0)
• confidence_band: "LOW", "MEDIUM", or "HIGH"
• reasons: Sorted list of reason codes

extract_v2_text(text: str) -> Dict[str, Any]

v2 extraction for text payloads. Same return format as extract_v2_json.

build_v2_signal(extract_result: Dict, *, source: str, region: str, environment: str, ...) -> SignalPayload

Build a v2 SignalPayload from extraction results. Automatically includes:

• Confidence band mapping
• Reason codes
• Privacy-safe fingerprint
• Optional policy and execution context

Helper Functions

safe_llm_call(llm_response: str, ...) -> Tuple[str, str]

Wrapper for LLM responses that detects sensitive data leakage. Returns (response, risk_level) where risk_level is "LOW", "MEDIUM", or "HIGH".

HealthSecureClient.analyze_signal(payload: SignalPayload) -> SignalResponse

Send signal to backend for risk assessment. Returns risk level (LOW/MEDIUM/HIGH) and explanation. Accepts both v1 and v2 signals.

---

Risk Assessment Logic

• HIGH Risk:
  • Credentials detected in production (inherently high-risk)
  • Medical/biometric/children data + identifiers in production
• MEDIUM Risk:
  • Identifiers present with other sensitive data
  • Sensitive data in staging/development
• LOW Risk:
  • No identifiers, no high-risk classes

---

Detection Limits

Heuristic-Based Detection

HealthSecure uses keyword matching and pattern detection, not machine learning or schema understanding:

• ✅ High-confidence signals: Detects obvious sensitive data (credit cards, API keys, medical terms)
• ⚠️ Best-effort coverage: May miss context-dependent or obfuscated data
• ⚠️ False positives possible: Generic terms may trigger false alarms
• ⚠️ No semantic understanding: Cannot distinguish between "patient" (medical) and "patient" (waiting)

Supported Detection Patterns

• Medical: 9 keywords (hiv, cancer, diabetes, diagnosis, treatment, medical, patient, disease, diagnosed)
• Financial: 9 keywords (credit, debit, card, iban, account, payment, paid, transaction, billing)
• Credentials: 8 keywords (token, apikey, apikey, secret, password, auth, bearer, sk)
• Personal Identifiers: Email addresses (regex), phone numbers (regex)

What Gets Detected

✅ Credit card numbers (pattern matching)
✅ API keys (pattern matching: sk*, pk*, api_)
✅ Email addresses (regex)
✅ Medical keywords in text
✅ Financial keywords in text
✅ Credential keywords in text

What May Be Missed

⚠️ Encrypted or encoded data
⚠️ Context-dependent sensitive information
⚠️ Industry-specific terminology not in keyword set
⚠️ Structured data in non-standard formats

---

Stability & Contracts

v2 contracts - See V2_IMPLEMENTATION.md for technical details:

• Extended signal schema with optional v2 fields
• Risk policy unchanged (uses v1 fields for evaluation)
• Documented extractor limitations
• Backward compatible with v1 signals

v2 features:

• Confidence bands (LOW/MEDIUM/HIGH)
• Reason codes for explainability
• Privacy-safe signal fingerprinting
• Policy and execution context support
• Backend accepts v2 signals (v2 fields ignored in risk calculation)

Migration Guide

Upgrading from v1? See MIGRATION.md for a step-by-step guide.

• ✅ v1 continues to work unchanged
• ✅ No breaking changes
• ✅ Incremental adoption supported

---

Target Users

• Backend engineers

• AI / LLM engineers

• Platform and security teams

• Startups and SaaS teams running production APIs

---

Requirements

• Python >= 3.9
• requests >= 2.31.0
• pydantic >= 2.0.0

---

Project Status

• Version: 0.2.0a1 (alpha)
• SDKs: Python (Node.js planned)
• Backend API: Stable v1 (accepts v2 signals)
• License: (add license here)

What's New in v2.0

• ✨ Enhanced extraction with reason codes
• ✨ Confidence band mapping
• ✨ Privacy-safe signal fingerprinting
• ✨ Policy and execution context support
• ✅ Backward compatible with v1

---

One-Line Summary

HealthSecure detects sensitive data leaks in API and LLM outputs at runtime—without ever seeing your data.

---

Support

For issues, questions, or contributions, please open an issue.