Documentation

Everything you need to install, configure, and run breach detection on your AI agents.

Installation

Breach Intel can be installed in three ways depending on your setup.

Option A: Full Install (Recommended)

$ git clone https://github.com/ParthaMehtaOrg/breach-intel
$ cd breach-intel
$ ./install.sh

The installer checks prerequisites (Python 3.9+, Docker, pip), generates credentials, starts the Docker stack, installs the SDK, and sets up auto-instrumentation.

Option B: SDK Only (No Docker)

$ pip install breach-intel-client
$ breach-intel install-hook

Option C: Manual Setup

$ docker compose up --build
$ pip install -e sdk/
$ breach-intel install-hook
$ export BREACH_INTEL_URL=http://localhost:8080
$ export BREACH_INTEL_TOKEN=<your-api-key>

Configuration

Breach Intel is configured via environment variables or config.yaml.

Auto-Instrumentation

Breach Intel uses Python's sitecustomize.py mechanism to auto-patch AI frameworks at import time. No code changes required.

How it works

1. breach-intel install-hook writes a persistent sitecustomize.py to your Python site-packages
2. When any Python process starts, the hook runs first
3. It checks for the BREACH_INTEL_URL environment variable
4. If set, it patches all detected AI framework methods
5. The agent auto-registers with the policy agent
6. Every LLM response is sent to POST /events (5s timeout, silent on failure)

Supported frameworks

Diagnostics

Run breach-intel doctor to verify your installation.

$ breach-intel doctor
✓ BREACH_INTEL_URL = http://localhost:8080
✓ Persistent hook installed
✓ Detected frameworks: OpenAI, Anthropic
✓ Server health: OK (v0.3.1)
✓ Credentials: valid
─────────────────────────────
All checks passed.

Policy Agent

The policy agent is a FastAPI server that receives events from instrumented agents, classifies them, and logs breaches.

Request flow

1. Auth + rate limit check (scoped API keys, 300/min default)
2. Auto-registration (if first event from an unknown agent)
3. Payload sanitization (normalize, strip noise)
4. Deterministic classification (rule-based, <1ms)
5. If breach: insert into DB, append to JSONL, fire webhook
6. Trigger agentic analysis (async, non-blocking, Pro only)
7. Return immediately to caller

Classifier

The rule-based classifier detects breaches in under 1ms using pattern matching. No LLM is in the critical path.

It checks for PII patterns (SSN, Aadhaar, PAN, email, DOB), card data (Visa/MC/Amex, CVV), PHI markers, financial hallucination patterns, and 40+ other violation types across all verticals.

Hash Chain

Every breach record is SHA-256 checksummed. Each record includes the hash of the previous record, forming an immutable chain.

{
  "id": "br_00042",
  "breach_type": "PII_EXPOSURE",
  "severity": "CRITICAL",
  "prev_hash": "a3f8c1d9...",
  "record_hash": "7b2e4f8a...",
  "timestamp": "2026-03-28T14:22:01Z"
}

Integrity scanning runs every 6 hours. If a single record is tampered with, the chain breaks and a tamper_alert is created.

Agentic Analysis

Pro feature. An async LangGraph pipeline powered by Claude adds context to detected breaches.

The six-node graph provides: severity justification, regulatory mapping, remediation guidance, rationale extraction, context enrichment, and final assessment. This runs in the background and never blocks the agent or the classifier.

Fintech

12 breach types. Production ready.

Covers: PII_EXPOSURE, CARD_DATA_EXPOSURE, CROSS_TENANT_LEAK, DATA_EXFILTRATION, SUSPICIOUS_TRANSACTION, UNAUTHORIZED_ACCESS, PRIVILEGE_ESCALATION, REGULATORY_VIOLATION, HALLUCINATION_FINANCIAL, AUDIT_TRAIL_MISSING, SCOPE_CREEP, UNAPPROVED_EXTERNAL_CALL.

Regulations: SOC 2, GDPR, CCPA, PCI-DSS, SOX, SEBI, RBI, FINCEN.

Healthcare

14 breach types. Beta.

Covers: PHI_EXPOSURE, CLINICAL_NOTE_LEAK, UNAUTHORIZED_PRESCRIPTION_ACTION, DIAGNOSTIC_HALLUCINATION, MINORS_DATA_EXPOSURE, MENTAL_HEALTH_DISCLOSURE, HIV_STATUS_DISCLOSURE, GENOMIC_DATA_EXPOSURE, INSURANCE_DATA_LEAK, CROSS_PATIENT_LEAK, and more.

Regulations: HIPAA, 42 CFR Part 2, GDPR, DPDP, HL7/FHIR.

Pharma

14 breach types. Beta.

Covers: TRIAL_DATA_FABRICATION, UNBLINDING_BREACH, AUDIT_TRAIL_VIOLATION_21CFR11, ESIGNATURE_BYPASS, REGULATORY_SUBMISSION_VIOLATION, PHARMACOVIGILANCE_BREACH, GMP_VIOLATION, and more.

Regulations: FDA 21-CFR Part 11, 21-CFR Part 312, ICH-E6 (GCP), ICH-Q10 (GMP), EMA, GDPR.

Dashboard

A single-file React SPA served at /dashboard/. Access it with your agent token:

$ open "http://localhost:8080/dashboard/?token=$(cat ~/.breach-intel/agent_token)"

Features: breach counts by severity, agent heatmaps, live breach feed (last 50), click-to-inspect detail view with full payload, vertical distribution chart, and instance info.

Webhooks

CRITICAL breaches fire webhooks instantly. Configure via environment variables:

$ export BREACH_INTEL_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../xxx
$ export BREACH_INTEL_WEBHOOK_TYPE=slack

Supported types: slack, discord, generic (POST JSON to any URL).

Auto-Scaling

When event load exceeds the spawn threshold (default: 500 events/min), the policy agent spawns additional instances via Docker, K8s, or subprocess. Configure with BREACH_INTEL_SPAWN_THRESHOLD.

Auth & RBAC

Multi-tenant API key system with scoped permissions. Each agent gets its own key. Admin keys are rate-limit exempt. Keys are generated during installation or via the API.

REST API

POST /events

Submit an agent event for classification. Returns breach result if detected.

GET /breaches

List breach records. Supports filtering by agent, severity, type, and date range.

GET /agents

List registered agents with their framework info and breach counts.

GET /health

Server health check. Returns version, uptime, and registered agent count.

GET /metrics

Prometheus-compatible metrics endpoint for Grafana integration.

GET /dashboard/

Serves the single-file React dashboard SPA.

CLI Reference

Environment Variables

All environment variables are prefixed with BREACH_INTEL_ except for external service keys. See the Configuration section for the full reference table.