PANDA Python SDK

Private And Secure Data Access — Field-level encryption SDK for Python applications.

Overview

PANDA (Private And Secure Data Access) is a cross-language SDK for field-level encryption and masking of sensitive personal data. The Python implementation provides the same features as the PHP, Node.js, and Go versions:

• AES-256-GCM encryption with envelope wire format
• Masking-by-default decrypted values
• Blind indexing for searchable encrypted fields
• Multiple key providers: Local (.env), HashiCorp Vault, Infisical
• CLI tool for initialization and key management
• Framework integrations: Django, Flask, FastAPI

Installation

pip install panda-crypto-py

Quick Start

1. Initialize PANDA

panda init --token panda_demo_76d08573d453cdbdb4bf5704d13f8f54d57cd3c47c9b4be2

The wizard will guide you through:

• Selecting a key provider (Local, Vault, or Infisical)
• Configuring your provider
• Generating your first encryption key

2. Use in Your Code

from panda.crypto import FieldCipher, LocalKeyProvider

# Create cipher with local keys
key_provider = LocalKeyProvider()
cipher = FieldCipher(key_provider)

# Encrypt data
envelope = cipher.encrypt("3201012501990001", kid="nik-key")

# Decrypt (returns masked value by default)
masked = cipher.decrypt(envelope)
print(masked)  # "32************01"

# Decrypt raw (audited operation)
raw = cipher.decrypt_raw(envelope)
print(raw)  # "3201012501990001"

Key Providers

Local (Environment Variables)

from panda.crypto import LocalKeyProvider

# Keys are read from PANDA_KEY_<KID> environment variables
# PANDA_KEY_NIK_KEY=<base64-encoded-32-byte-key>
key_provider = LocalKeyProvider()

HashiCorp Vault

from panda.crypto import VaultKeyProvider

key_provider = VaultKeyProvider(
    vault_url="http://localhost:8200",
    vault_token="your-token",
    mount_path="secret"
)

Infisical

from panda.crypto import InfisicalKeyProvider

key_provider = InfisicalKeyProvider(
    site_url="https://app.infisical.com",
    client_id="your-client-id",
    client_secret="your-client-secret",
    project_id="your-project-id",
    environment="dev"
)

Masking

from panda.masking import Masker

# Default: keep 2 leading, 2 trailing characters
masked = Masker.mask("3201012501990001")
# "32************01"

# Custom masking
masked = Masker.mask(
    "3201012501990001",
    keep_leading=3,
    keep_trailing=1,
    mask_char="*"
)
# "320*************1"

Blind Indexing

from panda.blind_index import BlindIndexer

# Generate blind index for searchable encryption
index = BlindIndexer.generate(
    plaintext="3201012501990001",
    key="blind-index-key",
    normalization="digits"  # or "lowercase", "trim", "raw"
)

Framework Integration

Django

# settings.py
INSTALLED_APPS = [
    ...
    'panda.integrations.django',
]

PANDA = {
    'KEY_PROVIDER_DRIVER': 'local',
    'DEFAULT_KID': 'default-key',
}

# models.py
from panda.integrations.django.fields import EncryptedField
from django.db import models

class Citizen(models.Model):
    nik = EncryptedField(kid='nik-key')
    name = models.CharField(max_length=200)

Flask

from flask import Flask
from panda.integrations.flask import PandaFlask

app = Flask(__name__)
panda = PandaFlask(app)

@app.route('/encrypt')
def encrypt():
    envelope = panda.cipher.encrypt("sensitive data", kid="my-key")
    return envelope.to_json()

FastAPI

from fastapi import FastAPI
from panda.integrations.fastapi import PandaFastAPI

app = FastAPI()
panda = PandaFastAPI(app)

@app.post("/encrypt")
def encrypt_endpoint(data: str):
    envelope = panda.cipher.encrypt(data, kid="my-key")
    return envelope.to_dict()

CLI Commands

Mode Non-Interaktif (Flags untuk CI/CD)

Semua perintah CLI dapat digunakan dalam mode non-interaktif dengan menggunakan flag. Ini sangat berguna untuk:

• CI/CD pipelines - Otomatisasi tanpa interaksi pengguna
• Docker containers - Inisialisasi otomatis saat container start
• Infrastructure as Code - Integrasi dengan Terraform, Ansible, dll
• Automated testing - Setup dan teardown otomatis

Perintah Init - Mode Non-Interaktif

# Quick init dengan Local provider (mode tercepat)
panda init --token <token> --kid default-key

# Init tanpa generate kunci pertama (untuk automation lanjutan)
panda init --token <token> --reinit

# Init dengan environment variable
export PANDA_ACCESS_TOKEN=<token>
panda init

Flag init yang tersedia:

Perintah Generate - Mode Non-Interaktif

# Generate kunci dengan KID langsung (non-interactive)
panda generate my-new-key

# Generate dengan description
panda generate nik-key --description "Key for NIK encryption"

Flag generate yang tersedia:

Perintah Deinit - Mode Non-Interaktif

# Hapus konfigurasi tanpa prompt
panda deinit --force

Flag deinit yang tersedia:

Tabel Lengkap Perintah CLI

# Initialize PANDA
panda init --token <your-token>

# Generate a new key
panda generate my-key

# Check status
panda status

# View configuration
panda config

# Remove PANDA from project
panda deinit --force

Envelope Format

Encrypted fields use a standardized JSON envelope:

{
  "v": 1,
  "alg": "aes-256-gcm",
  "kid": "key-identifier",
  "nonce": "<base64 12-byte IV>",
  "ciphertext": "<base64 ciphertext + 16-byte auth tag>"
}

Documentation

• Full Documentation
• Envelope Format Spec
• CLI Reference
• Framework Integrations

License

MIT License - See LICENSE file for details.

Support

For issues and questions:

• GitHub Issues: https://github.com/jatimprovcsirt/panda-crypto-py/issues
• Documentation: https://panda.jatimprovcsirt.go.id