ComplyChain

Multi-Regulation Compliance Toolkit with Quantum-Safe Cryptography

ComplyChain is an open-source Python library for financial compliance engineering. It covers GLBA §314.4, PCI-DSS 4.0, DORA, SOC 2, and HIPAA — with post-quantum cryptography (ML-DSA-65 / NIST FIPS 204), graph-based AML detection, SAR narrative generation, ML-based anomaly detection, Merkle-chained audit trails, a configurable rule engine, SIEM export, evidence packaging, key rotation, and a webhook event system.

• 📦 PyPI: pip install complychain
• 🌐 GitHub: github.com/RanaEhtashamAli/comply-chain
• 📄 White Paper (PDF)

What it does

Installation

pip install complychain

Python 3.9+ required. All core dependencies install automatically.

Quantum-safe cryptography (optional)

By default, the library falls back to RSA-4096. To enable ML-DSA-65 (NIST FIPS 204):

# Ubuntu / Debian
sudo apt-get install cmake build-essential ninja-build libssl-dev
pip install liboqs-python

# macOS
brew install cmake
pip install liboqs-python

Verify:

python -c "import oqs; print('liboqs available:', oqs.get_enabled_sig_mechanisms()[:3])"

Without liboqs, the library prints a warning and falls back to RSA-4096 transparently — no code changes needed.

Quickstart

Transaction scanning

from complychain import GLBAScanner

scanner = GLBAScanner()
result = scanner.scan({
    "amount": 12500,
    "currency": "USD",
    "transaction_type": "wire",
    "beneficiary": "ACME Corp",
    "originator": "Jane Doe"
})

print(result["risk_score"])       # 0.0 – 1.0
print(result["threat_flags"])     # ["HIGH_VALUE_TRANSACTION", ...]
print(result["fincen_compliance"]["ctr_required"])  # True if amount >= $10,000

Quantum-safe signing

from complychain import QuantumSafeSigner

signer = QuantumSafeSigner()
signer.generate_keys()

data = b"transaction payload"
signature = signer.sign(data)
assert signer.verify(data, signature)

print(signer.algorithm)  # "ml-dsa-65" or "rsa-4096" (fallback)

Regulation assessment

from complychain.regulations import default_registry, InstitutionProfile

profile = InstitutionProfile(
    name="First Community Bank",
    jurisdiction="US",
    entity_type="bank",
)

# Assess all applicable regulations at once
reports = default_registry.assess_all(profile)
for reg_id, report in reports.items():
    print(f"{reg_id}: {report.overall_status.value}  risk={report.risk_score:.2f}")

Output:

glba: NON_COMPLIANT  risk=0.61
pci_dss: NOT_APPLICABLE  risk=0.00
soc2: COMPLIANT  risk=0.12

Audit chain

from complychain import GLBAAuditor

auditor = GLBAAuditor()
auditor.log_transaction({"amount": 5000, "type": "ACH"}, b"signature_bytes")

# Verify chain integrity
from complychain.verification import AuditChainVerifier
result = AuditChainVerifier().verify()
print(result.ok, result.total_entries, result.tampered_entries)

ML anomaly detection

import numpy as np
from complychain.detection import EnsembleDetector, VelocityDetector

# Ensemble (IsolationForest + LOF + Z-score majority vote)
det = EnsembleDetector()
X_train = np.random.normal(size=(200, 3))
det.fit(X_train)

is_anomaly, score = det.predict(np.array([100.0, 100.0, 100.0]))

# Velocity / structuring detection
vel = VelocityDetector(window_seconds=86_400, max_count_threshold=10)
vel.observe("account-123", amount=4900.0)
vel.observe("account-123", amount=4900.0)
print(vel.is_suspicious("account-123"))  # True at high velocity

Assessment persistence and diff

from complychain.persistence import AssessmentStore
from complychain.regulations import GLBARegulation

store = AssessmentStore()
report = GLBARegulation().assess(profile)
store.save(report)

# Later — compare two runs
diff = store.diff("glba")
print(diff.risk_delta, diff.status_changed)
for ctrl in diff.control_diffs:
    if ctrl.changed:
        print(f"{ctrl.control_id}: {ctrl.old_status} → {ctrl.new_status}")

Events and webhooks

from complychain.events import default_bus, EventType, WebhookEmitter, SlackEmitter

# HTTP webhook (HMAC-SHA256 signed)
emitter = WebhookEmitter(
    urls=["https://your-siem.example.com/events"],
    secret="your-signing-secret",
)
emitter.start()

# Slack notifications
slack = SlackEmitter(webhook_url="https://hooks.slack.com/services/...")
slack.start()

# Events fire automatically when threats are detected or assessments complete
# You can also emit manually:
from complychain.events import Event
default_bus.emit(Event(EventType.THREAT_DETECTED, {"risk_score": 0.91}))

CLI

Transaction scanning

complychain scan --file transaction.json
complychain scan --file transaction.json --quantum-safe

Cryptographic operations

# Generate ML-DSA-65 keys
complychain quantum-keys generate --output-dir ./keys

# Sign
complychain sign --file data.json --quantum-safe

# Verify
complychain verify --file data.json --signature sig.bin --public-key pub.pem

Compliance reporting

complychain report --type monthly --output glba_report.pdf
complychain report --type daily --output daily_report.pdf

Regulation assessment

# List all registered regulations
complychain regulations list

# Assess all applicable regulations for a profile
complychain regulations assess --name "First Community Bank" --entity-type bank

# Assessment history
complychain regulations history --regulation glba --days 30

# Diff two most recent runs
complychain regulations diff --regulation glba

Regulation framework

Supported regulations

Control statuses

Each control returns COMPLIANT, PARTIAL, NON_COMPLIANT, or NOT_APPLICABLE. Many controls perform active verification — they read the filesystem, check real key pairs, validate MFA secrets, and walk the audit chain hash tree rather than just reading environment flags.

Adding a custom regulation

from complychain.regulations.base import BaseRegulation, ComplianceStatus, InstitutionProfile, RegulationReport
from complychain.regulations import default_registry

class MyRegulation(BaseRegulation):
    @property
    def regulation_id(self): return "my_reg"

    @property
    def regulation_name(self): return "My Internal Policy v1"

    @property
    def version(self): return "1.0"

    def is_applicable(self, profile): return True

    def assess(self, profile) -> RegulationReport:
        controls = {}
        # ... build ControlResult dict ...
        return self._build_report(profile, controls)

default_registry.register(MyRegulation())

Architecture

Modules

complychain/
├── regulations/          # GLBA, PCI-DSS, DORA, SOC 2, HIPAA + RegulationRegistry
├── reporting/            # SARGenerator (FinCEN XML/PDF), ExplanationEngine
├── rules/                # RuleEngine (YAML rules, simpleeval safe eval)
├── detection/
│   ├── ml_engine.py      # MLEngine (Isolation Forest, training pipeline)
│   ├── ensemble.py       # EnsembleDetector (IF + LOF + Z-score majority vote)
│   ├── velocity.py       # VelocityDetector (rolling-window, per-entity)
│   ├── drift.py          # DriftDetector (Page-Hinkley change detection)
│   └── graph.py          # AMLGraph (structuring, layering, fan-out, common beneficiary)
├── export/
│   ├── siem.py           # SIEMExporter (CEF, JSON, LEEF, syslog)
│   └── evidence.py       # EvidencePackage (signed ZIP for auditors)
├── key_management/       # KeyRotationManager (archive, generate, sign manifest)
├── monitoring/           # MonitoringScheduler (APScheduler, optional)
├── api/                  # FastAPI app (optional: pip install complychain[api])
├── persistence/          # AssessmentStore (SQLite), AssessmentDiff, risk_trend()
├── events/               # EventBus, WebhookEmitter (HMAC), SlackEmitter (Block Kit)
├── verification/         # KeyVerifier, AuditChainVerifier, MFAVerifier
├── audit_system.py       # GLBAAuditor (Merkle-chain, PDF reports)
├── crypto_engine.py      # QuantumSafeSigner (ML-DSA-65 / RSA-4096 fallback)
├── threat_scanner.py     # GLBAScanner (FinCEN thresholds, OFAC, sanctions)
├── compliance/           # GLBA engine, MFA, vendor management, training
└── cli.py                # Typer CLI (18 commands)

Audit chain integrity

Every transaction logged by GLBAAuditor is linked by a SHA-256 Merkle chain:

hash_n = SHA-256(prev_hash_n-1 || merkle_root_n || sig_hex_n)

AuditChainVerifier walks the full chain and reports any broken link or tampered entry.

Deep active verification

Unlike policy-only frameworks, several controls perform live checks:

• KeyVerifier — confirms PEM key files exist, reads keystore.json age, and performs a round-trip sign/verify with the stored key pair
• AuditChainVerifier — walks every entry in audit_chain.json and recomputes the hash chain
• MFAVerifier — validates each secret is valid base32, decodes to ≥ 10 bytes, and checks expires_at timestamps

Cryptography

ComplyChain implements ML-DSA-65 as specified in NIST FIPS 204 via the pqcrypto library (a wrapper around the liboqs C reference implementation). This is not a NIST CMVP-certified module; it implements the algorithm as specified in the standard.

Key storage uses AES-GCM-256 with Scrypt key derivation (N=16384, r=8, p=1 — OWASP recommended parameters).

Environment variables

Docker

# Build
docker build -t complychain .

# Scan a transaction
docker run -v ./audit:/audit_chain \
  -e COMPLYCHAIN_FINCEN_API_KEY=your_key \
  complychain scan --file /audit_chain/tx.json

# With quantum-safe cryptography (requires cmake at build time)
docker build -f Dockerfile.oqs -t complychain-quantum .
docker run -v ./keys:/keys complychain-quantum quantum-keys generate --output-dir /keys

GLBA §314.4 coverage

Development

git clone https://github.com/RanaEhtashamAli/comply-chain.git
cd comply-chain
uv sync --extra dev   # or: pip install -e ".[dev]"

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=complychain --cov-report=term-missing

Current test suite: 781 tests, 89% coverage.

Compliance standards implemented

• NIST FIPS 204 — ML-DSA-65 digital signature algorithm
• GLBA §314.4 — Safeguards Rule (FTC, 2023 revision)
• PCI-DSS 4.0 — Payment Card Industry Data Security Standard
• DORA — EU Digital Operational Resilience Act (Regulation 2022/2554)
• SOC 2 Type II — AICPA Trust Service Criteria (2017)
• FinCEN BSA — Bank Secrecy Act thresholds (CTR $10K, SAR $5K, wire $3K)
• NIST SP 800-131A — Key management guidance
• OWASP 2024 — Password storage parameters (Scrypt)

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

Areas where help is most useful:

• Additional regulation adapters (Basel III, ISO 27001, HIPAA)
• Real FinCEN API integration testing
• Core banking system integration adapters
• Performance benchmarking suite

License

Apache License 2.0 — see LICENSE.

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: ranaehtashamali1@gmail.com