compalgo
Advanced tools
Static Analysis + On-Chain Proof Anchoring for Algorand Smart Contracts
SOC 2 • PCI DSS • FedRAMP • Smart Contract Security
CompALGO is a comprehensive compliance and security toolkit for Algorand smart contracts that provides two powerful capabilities:
Analyze PyTeal and TEAL contracts for vulnerabilities and compliance issues during development with 8 policy packs covering PCI-DSS, SOC2, and security best practices.
Create cryptographically verifiable compliance verdicts and anchor them immutably on the Algorand blockchain for audit trails and regulatory evidence.
Algorand is not just storage — it's the trust layer for CompliLedger.
# Install CompALGO
pip install compalgo
# With interactive menu mode
pip install compalgo[interactive]
# With file watching (auto-check on save)
pip install compalgo[watch]
# Development install
git clone https://github.com/compliledger/compalgo.git
cd compalgo
pip install -e .
# Quick security scan with default policy
compalgo check examples/escrow.py
# Scan with specific policy and threshold
compalgo check contracts/payment.py --policy pci-dss-standard --threshold 90
# Scan entire directory
compalgo check contracts/
# Scan and create verdict JSON
compalgo check examples/escrow.py --verdict-out verdict.json
# View all available policies
compalgo list-policies
# Set your Algorand account (testnet)
export ALGO_MNEMONIC="your 25 word mnemonic here"
# Anchor the verdict hash on Algorand blockchain
compalgo anchor --verdict verdict.json
# Output:
# ✅ Anchored! TXID: CTOE5M6ZZD...
# Explorer: https://testnet.algoexplorer.io/tx/CTOE5M6ZZD...
# Verify verdict against blockchain
compalgo verify --verdict verdict.json --txid CTOE5M6ZZD...
# Output:
# ✅ VALID
from compalgo import ComplianceChecker, CompliLedgerClient
from compalgo.core.verdict import build_verdict
# Scan contract
checker = ComplianceChecker(policy_pack="algorand-baseline", threshold=80)
result = checker.check_file("contract.py")
# Build compliance verdict
verdict = build_verdict(
contract=result.file_path,
violations=result.violations,
framework="SOC2",
control_id="CC6.1",
fail_on="medium"
)
# Anchor on Algorand
client = CompliLedgerClient(
algod_url="https://testnet-api.algonode.cloud",
algod_token="",
sender_mnemonic="your mnemonic",
network="testnet"
)
anchor_result = client.mint_verdict(verdict)
print(f"TXID: {anchor_result.txid}")
print(f"Explorer: {anchor_result.explorer_url}")
# Verify
is_valid = client.verify_verdict(verdict, anchor_result.txid)
assert is_valid # ✅ True
| Framework | Controls | Use Case |
|---|---|---|
| SOC 2 | Trust Services | SaaS & Web3 infrastructure |
| PCI DSS | Payment Security | Payment & crypto custody |
| FedRAMP | Federal Baseline | Government cloud services |
| Algorand Security | Smart contracts | dApp development |
CompALGO provides a comprehensive CLI for all workflows. See CLI_USER_FLOWS.md for complete examples.
# Scan contracts
compalgo check contract.py # Quick scan
compalgo check contracts/ --policy pci-dss-standard # Directory scan
compalgo check contract.py --threshold 95 # Custom threshold
compalgo check contract.py --verdict-out v.json # Generate verdict
# Export reports
compalgo report contract.py -o report.json --format json
compalgo report contract.py -o report.md --format markdown
compalgo report contract.py -o report.html --format html
# Policy management
compalgo list-policies # Show all policies
# Blockchain anchoring
export ALGO_MNEMONIC="your 25 word mnemonic"
compalgo anchor --verdict verdict.json # Anchor on testnet
compalgo anchor --verdict v.json --network mainnet # Anchor on mainnet
# Verification
compalgo verify --verdict verdict.json --txid TXID # Verify proof
👉 See CLI_USER_FLOWS.md for complete step-by-step examples
Run compalgo list-policies to see all 9 available policy packs:
| Policy Pack | Rules | Threshold | Target |
|---|---|---|---|
| algorand-baseline ⭐ | 9 | 80 | Algorand-specific (PyTeal/TEAL) |
| security-baseline ⭐ | 10 | 75 | General security patterns (all chains) |
| pci-dss-algorand | 3 | 80 | Algorand payment subset |
| pci-dss-basic | 7 | 85 | Payment/DeFi (essential) |
| pci-dss-standard | 15 | 90 | Payment/DeFi (comprehensive) |
| pci-secure-software | 7 | 90 | Software vendors |
| pci-tokenization | 4 | 90 | Token service providers |
⭐ = Recommended for most Algorand projects
from compalgo import ComplianceChecker, CompliLedgerClient
from compalgo.core.verdict import build_verdict
# Scan payment contract with PCI-DSS Standard policy
checker = ComplianceChecker(policy_pack="pci-dss-standard", threshold=90)
result = checker.check_file("contracts/payment_app.py")
print(f"Score: {result.score}/100")
print(f"Violations: {len(result.violations)}")
# Build compliance verdict
verdict = build_verdict(
contract=result.file_path,
violations=result.violations,
framework="PCI-DSS",
control_id="6.5.1",
fail_on="high"
)
# If compliant, anchor proof on Algorand
if result.passed:
client = CompliLedgerClient(
algod_url="https://testnet-api.algonode.cloud",
algod_token="",
sender_mnemonic=os.getenv("ALGO_MNEMONIC"),
network="testnet"
)
anchor_result = client.mint_verdict(verdict)
print(f"✅ Proof anchored: {anchor_result.explorer_url}")
from compalgo import ComplianceChecker
from compalgo.core.verdict import build_verdict
# Check contract for SOC 2 compliance (access controls)
checker = ComplianceChecker(policy_pack="algorand-baseline", threshold=80)
result = checker.check_file("contracts/auth_contract.py")
# Build SOC 2 verdict
verdict = build_verdict(
contract=result.file_path,
violations=result.violations,
framework="SOC2",
control_id="CC6.1", # Logical and Physical Access Controls
fail_on="medium"
)
# Verdict includes: status, severity, rules_triggered, timestamp
print(f"Status: {verdict.status}")
print(f"Severity: {verdict.severity}")
print(f"Rules triggered: {verdict.rules_triggered}")
from compalgo import ComplianceChecker
policies = ["algorand-baseline", "pci-dss-basic", "pci-dss-standard"]
contract = "contracts/payment.py"
for policy in policies:
checker = ComplianceChecker(policy_pack=policy)
result = checker.check_file(contract)
print(f"{policy}: Score={result.score}, Passed={result.passed}")
Access Control
Input Validation
State Management
Asset Security
Payment Security (PCI-DSS)
Logic & Optimization
╭────────────────────── ⚠️ 5 Violation(s) Found ──────────────────────╮
│ 🔴 CRITICAL: 2 issue(s) │
│ • Missing sender verification in admin function │
│ → contracts/payment_app.py:45 │
│ 💡 Add: Assert(Txn.sender() == Global.creator_address()) │
│ │
│ • Cardholder data stored in global state (PCI-DSS 3.4) │
│ → contracts/payment_app.py:78 │
│ 💡 Use local state or encryption │
│ │
│ ⚠️ HIGH: 3 issue(s) │
│ • Payment amount not validated (PCI-DSS 6.5.1) │
│ • Missing transaction logging │
│ • Potential integer overflow │
│ │
│ Score: 62/100 - NON COMPLIANT ❌ │
╰──────────────────────────────────────────────────────────────────────╯
✅ 42 checks passed ⚠️ 3 warnings ❌ 2 critical
| Policy Pack | Status | Controls | Focus Area |
|---|---|---|---|
algorand-baseline | ✅ Available | 15+ | PyTeal/TEAL security |
pci-dss-algorand | ✅ Available | 7 | Payment & DeFi |
soc2-algorand | 🚧 v0.2.0 | 25+ | Trust Services |
fedramp-algorand | 🚧 v0.3.0 | 50+ | Federal security |
iso-27001 | 🚧 v0.4.0 | 114 | InfoSec mgmt |
# Use specific policy
compliledger check contracts/ --policy pci-dss-algorand
# Use multiple policies
compliledger check contracts/ --policy algorand-baseline,pci-dss-algorand
name: CompliLedger Security
on: [pull_request, push]
jobs:
security-analysis:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Set up Python
uses: actions/setup-python@v4
with:
python-version: '3.11'
- name: Install CompliLedger
run: pip install compliledger-algorand
- name: Run Security Analysis
run: |
compliledger check contracts/ \
--fail-on-critical \
--threshold 80
- name: Anchor Proof (main branch only)
if: github.ref == 'refs/heads/main'
env:
ALGORAND_MNEMONIC: ${{ secrets.ALGORAND_MNEMONIC }}
run: |
compliledger anchor \
--framework SOC2 \
--control CC6.1 \
--status pass
#!/bin/bash
# .git/hooks/pre-commit
echo "🔍 Running CompliLedger security analysis..."
compliledger check contracts/ --threshold 75 --fail-on-critical
if [ $? -ne 0 ]; then
echo "❌ Security check failed. Fix issues before committing."
exit 1
fi
echo "✅ Security check passed!"
from compliledger_algorand import CompliLedgerClient
# Initialize
client = CompliLedgerClient(
algod_url="https://testnet-api.algonode.cloud",
algod_token="",
sender_mnemonic="your mnemonic",
network="testnet"
)
# Create and anchor
event = client.create_compliance_event(
framework="SOC2",
control_id="CC6.1",
status="pass",
resource="payment-service"
)
proof = client.mint_proof(event)
# Verify
is_valid = client.verify_proof(event, proof.txid)
assert is_valid
# Query history
proofs = client.query_proofs(
framework="SOC2",
from_date="2025-01-01"
)
from compliledger_algorand.analyzer import ComplianceChecker
# Initialize checker
checker = ComplianceChecker(
policy_pack="algorand-baseline",
threshold=80
)
# Check single file
result = checker.check_file("contracts/payment_app.py")
print(f"Score: {result.score}/100")
print(f"Violations: {len(result.violations)}")
for v in result.violations:
print(f"{v.severity}: {v.message} at line {v.line_number}")
# Check directory
results = checker.check_directory("contracts/")
# Generate report
checker.generate_report(
results,
format="html",
output_path="compliance_report.html"
)
1. Developer creates compliance event
↓
2. SDK hashes event locally (SHA-256)
↓
3. Hash written to Algorand transaction note
↓
4. Blockchain provides immutable timestamp
↓
5. Anyone can verify proof on-chain
↓
6. Original data stays private
1. Developer writes PyTeal/TEAL contract
↓
2. SDK parses code (AST extraction)
↓
3. Pattern matching against security rules
↓
4. Severity scoring (0-100)
↓
5. Generate actionable remediation suggestions
↓
6. Export reports or fail CI/CD
Your smart contract code never leaves your machine:
True privacy for blockchain development.
┌─────────────────────────────────────────────────────────────┐
│ CompliLedger Algorand SDK │
├─────────────────────────────────────────────────────────────┤
│ CLI Tool Python API CI Integration │
│ compliledger CompliLedgerClient GitHub Actions │
│ check/anchor ComplianceChecker GitLab CI │
│ verify/report mint_proof() Pre-commit hooks │
├─────────────────────────────────────────────────────────────┤
│ Proof Anchoring Engine │
│ Event Creator → Hasher → Algorand Txn → Verifier │
├─────────────────────────────────────────────────────────────┤
│ Smart Contract Analysis Engine │
│ PyTeal/TEAL Parser → AST → Pattern Matcher → Scorer │
├─────────────────────────────────────────────────────────────┤
│ Policy Engine │
│ Rules | Severity | Evidence | Control Mapping │
├─────────────────────────────────────────────────────────────┤
│ Algorand Integration │
│ Algod Client | Transaction Builder | Explorer Links │
└─────────────────────────────────────────────────────────────┘
compliledger-algorand/
├── cli/ # Command-line interface
├── client/ # Proof anchoring client
│ ├── algorand.py # Algorand integration
│ ├── events.py # Event creation
│ └── verification.py # Proof verification
├── analyzer/ # Smart contract analysis
│ ├── parser.py # PyTeal/TEAL parser
│ ├── checker.py # Pattern matcher
│ ├── scorer.py # Severity scoring
│ └── reporter.py # Report generation
├── policies/ # Compliance rules
│ ├── algorand_baseline.json
│ ├── pci_dss_algorand.json
│ ├── soc2_algorand.json
│ └── fedramp_algorand.json
├── integrations/ # CI/CD plugins
│ ├── github/
│ └── gitlab/
└── tests/ # Test suite
| Tier | Checks/Month | Proofs/Month | Price | Features |
|---|---|---|---|---|
| Freemium | 100 | 100 | Free | Core policies, CLI |
| Pro | 1,000 | 1,000 | $99/mo | All policies, API access |
| Enterprise | Unlimited | Unlimited | $999/mo | Custom rules, SLA, support |
Algorand transaction fees (≈0.001 ALGO per proof) paid separately
We welcome contributions! See CONTRIBUTING.md for guidelines.
Areas we need help:
MIT License for core SDK (open-source)
Proprietary for enterprise features
See LICENSE for details.
CompliLedger is building the Proof-of-Compliance layer for Web3 — combining AI agents, blockchain attestations, and smart contract security.
Algorand is our primary trust anchor.
Built for the Algorand ecosystem 🔷
If you're building on Algorand and care about compliance, we'd love your help.
FAQs
CompALGO SDK: Algorand smart contract compliance analysis + on-chain proof anchoring
We found that compalgo demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.