Skip to content

README.md

Latest commit

 

History

History
375 lines (278 loc) · 9.45 KB

README.md

File metadata and controls

375 lines (278 loc) · 9.45 KB

🔐 CompZ

Privacy-Preserving Compliance Attestation SDK

Anchor compliance proofs to Zcash blockchain without revealing sensitive data

License: MIT Python 3.10+ Zcash PRs Welcome

Features • Quick Start • Architecture • API • Documentation • Contributing

📖 Overview

CompZ is a lightweight, open-source SDK that transforms compliance evaluations into cryptographic proofs anchored on the Zcash blockchain. It enables:

✅ Immutable audit trails - Blockchain-backed compliance records
✅ Privacy preservation - Only hashes on-chain, sensitive data stays private
✅ Tamper detection - Cryptographic verification of compliance data
✅ Timestamp proofs - Blockchain proves "when" compliance was checked
✅ Zero-knowledge ready - Compatible with ZK proof systems

Use Cases

  • 🏢 Enterprise Compliance - Prove SOC2/ISO27001/PCI compliance without revealing architecture
  • 🔒 Security Audits - Immutable records of vulnerability assessments
  • 📋 Regulatory Reporting - Tamper-proof compliance evidence for auditors
  • ⚡ DevSecOps - CI/CD pipeline compliance attestations
  • 🌐 Web3 Projects - DeFi protocol compliance for regulators

✨ Key Features

🎯 Compliance Rule Evaluation

Built-in evaluators for major frameworks:

Framework Controls Description
🟦 PCI DSS 5 sample controls Payment card security (firewall, encryption, MFA, logging)
🟩 SOC 2 Security 5 sample controls Trust services criteria (access, risk, monitoring)
🟧 FedRAMP Moderate 8 NIST 800-53 controls Federal security requirements (AC-2, AU-2, CM-2, etc.)

🔐 Privacy-Preserving Design

┌─────────────────────┐
│  Sensitive Data     │  ← Stays in your environment
│  - Source code      │
│  - Configs          │
│  - Credentials      │
│  - Business logic   │
└──────────┬──────────┘
           │
           ▼ SHA-256 Hash
┌─────────────────────┐
│  0xabc123def456...  │  ← Only this goes on-chain
└─────────────────────┘

No sensitive data ever leaves your infrastructure.

🔗 Zcash Blockchain Anchoring

  • ✅ Shielded transactions with 512-byte memo field
  • ✅ Privacy-first - Transaction details encrypted
  • ✅ Testnet & Mainnet support
  • ✅ Low fees (~$0.001 per attestation)
  • ✅ 2.5 min block time for confirmations

✓ Cryptographic Verification

# Anchor compliance data
$ compz anchor compliance.json
→ Hash: 0xabc123...
→ TXID: 9c8f7e6d...

# Verify later (or share with auditor)
$ compz verify compliance.json 9c8f7e6d...
→ ✅ VALID - Hashes match
→ Block: 2500123
→ Timestamp: 2024-01-01 10:30:00 UTC

🔧 Integration Ready

Works standalone or integrates with:

  • CompliLedger - AI-driven compliance platform
  • COMP-LEO - Compliance orchestration engine
  • GitHub Sentinel - Repository security monitoring
  • Any CI/CD pipeline - Jenkins, GitLab, GitHub Actions
  • SBOM/SCA tools - SPDX, CycloneDX, Snyk, etc.

🚀 Quickstart

Prerequisites

  • Python 3.10 or higher
  • Access to a Zcash node (testnet or mainnet)
  • Basic understanding of JSON and command-line tools

Step 1: Installation

# Clone the repository
git clone https://github.com/Compliledger/CompZ.git
cd CompZ

# Install dependencies
pip install -e .

Note: PyPI release coming soon. For now, install from source using pip install -e .

Quick Start Options

Option 1: Local Mode (No Setup Required)

  • Hashing and verification work immediately
  • No blockchain connection needed
  • Perfect for testing the SDK
# Try it now - no configuration required!
compz status

Option 2: Self-Hosted Mode (Full Blockchain Integration)

  • Requires Zcash node setup
  • Enables real on-chain anchoring
  • See configuration steps below

Step 2: Set Up Zcash Node

⚠️ Optional: Only required for self-hosted mode with real blockchain anchoring. You can skip this and use local mode or Zashi wallet integration instead.

Option A: Docker (Recommended for Testing)

# Run Zcash testnet node
docker run -d \
  --name zcash-testnet \
  -p 18232:18232 \
  -v ~/.zcash:/root/.zcash \
  electriccoinco/zcashd \
  -testnet \
  -rpcuser=compz \
  -rpcpassword=your_secure_password \
  -rpcallowip=127.0.0.1

# Wait for sync (2-4 hours for testnet)
docker exec zcash-testnet zcash-cli -testnet getblockchaininfo

Option B: Use Existing Node

If you already have a Zcash node running, just configure the connection.

Step 3: Configure Environment

For self-hosted mode only. Copy the template and configure:

cp .env.example .env
# Edit .env with your Zcash node credentials

Example .env configuration:

# .env
ZCASH_RPC_URL=http://127.0.0.1:18232
ZCASH_RPC_USER=compz
ZCASH_RPC_PASS=your_secure_password
ZCASH_DEFAULT_ADDRESS=ztestsapling1...  # Your z-address
ZCASH_TESTNET=true

Generate a z-address:

# Create a new shielded address
docker exec zcash-testnet zcash-cli -testnet z_getnewaddress sapling

# Get testnet funds from faucet
# Visit: https://faucet.testnet.z.cash/

Step 4: Run Your First Attestation

# Anchor compliance data to Zcash
compz anchor examples/compliance_result.json

# Output:
# {
#   "hash": "0xabc123def456...",
#   "txid": "9c8f7e6d5c4b3a2...",
#   "network": "testnet",
#   "timestamp": "2024-01-01T10:30:00Z",
#   "block_height": 2500123,
#   "explorer_url": "https://explorer.testnet.z.cash/tx/9c8f..."
# }

Step 5: Verify the Attestation

# Verify compliance data matches blockchain record
compz verify examples/compliance_result.json 9c8f7e6d5c4b3a2...

# Output:
# ✅ VALID - Compliance data matches blockchain record
# {
#   "valid": true,
#   "local_hash": "0xabc123def456...",
#   "onchain_hash": "0xabc123def456...",
#   "txid": "9c8f7e6d5c4b3a2...",
#   "block_time": "2024-01-01T10:30:00Z",
#   "confirmations": 42
# }

Step 6: Try Tampering (Demo)

# Edit the JSON file (change any value)
# Then try to verify again
compz verify examples/compliance_result.json 9c8f7e6d5c4b3a2...

# Output:
# ❌ INVALID - Hash mismatch detected
# {
#   "valid": false,
#   "local_hash": "0xDIFFERENT...",
#   "onchain_hash": "0xabc123def456...",
#   "reason": "Data has been tampered with"
# }

🧠 How CompZ Works

  1. Input → Raw System Payload

You supply system metadata (e.g., config settings) in JSON.

  1. Rule Evaluation

CompZ evaluates this data against minimal demonstrative control sets:

PCI DSS (5 controls) • Firewall rules • Secure defaults • PAN encryption • MFA • Logging

SOC 2 Security (5 controls) • Access policies • Risk assessment • Change management • Monitoring • Business continuity

FedRAMP Moderate (8 NIST controls) • AC-2, AC-3, AU-2, AU-6 • CM-2, CM-6 • SC-13 • SI-2

Output is a structured ComplianceResult object.

⸻

  1. Normalization

ComplianceResult → Deterministic normalized JSON: • Sorted keys • UTF-8 safe • No whitespace variance

⸻

  1. Hashing

SHA-256 hash returned as: 0x This is the privacy-preserving compliance attestation.

⸻

  1. Zcash Anchoring

CompZ: • Connects to a Zcash node • Creates a transaction • Embeds the hash in the memo field • Returns the transaction ID for auditability

⸻

  1. Verification

Given: • The original JSON • A Zcash txid

CompZ will: • Recompute the hash locally • Retrieve memo/OP_RETURN from Zcash • Compare hashes • Output match = true or false

⸻

🧪 Example Directory Layout CompZ/ ├── compz/ │ ├── models.py │ ├── evaluator.py │ ├── normalize.py │ ├── hash.py │ ├── zcash_client.py │ ├── anchor.py │ └── verify.py ├── examples/ │ ├── compliance_result_example.json │ ├── run_anchor.sh │ └── run_verify.sh └── docs/ └── architecture.md 🛠 Roadmap • Shielded-pool anchoring • ZK-SNARK/Circuit attestation proofs • Full PCI/SOC2/FedRAMP/HIPAA libraries • GitHub Sentinel integration • CompliLedger DevSync / AuditSync integration • DID/VC support • Zero-Knowledge control evaluation pipelines

⸻

🤝 Contributing

Pull requests, issues, and feature requests are welcome. We encourage contributions focused on: • Zcash memo integration • Compliance rule expansion • Privacy-preserving computation • Open-source compliance tooling

⸻

📄 License

MIT License. See LICENSE for details.

⸻

🎉 Built by CompliLedger

CompZ is an open-source privacy attestation toolkit from CompliLedger, an AI-driven compliance intelligence platform for regulated industries, cloud environments, stablecoins, and Web3 ecosystems.