compz 1.0.0
Privacy-Preserving Compliance Attestation SDK with Zcash blockchain anchoring
Requires Python: >=3.10
Keywords: compliance, attestation, blockchain, zcash, privacy, security, audit, devsecops, pci-dss, soc2, fedramp



# 🔐 CompZ

### **Privacy-Preserving Compliance Attestation SDK**

*Anchor compliance proofs to Zcash blockchain without revealing sensitive data*

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Zcash](https://img.shields.io/badge/Zcash-Testnet%20%7C%20Mainnet-orange)](https://z.cash)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)

[Features](#-key-features) • [Quick Start](#-quickstart) • [Architecture](#-architecture) • [API](#-api-reference) • [Documentation](#-documentation) • [Contributing](#-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**

```bash
# 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**

```bash
# 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

```bash
# 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)**

```bash
# 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:

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

Example `.env` configuration:

```bash
# .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:**

```bash
# 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**

```bash
# 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**

```bash
# 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)**

```bash
# 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.

2. 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.

⸻

3. Normalization

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

⸻

4. Hashing

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

⸻

5. Zcash Anchoring

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

⸻

6. 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.