Skip to content

M3_SECURITY_GUIDE.md

Latest commit

 

History

History
439 lines (318 loc) · 10.7 KB

M3_SECURITY_GUIDE.md

File metadata and controls

439 lines (318 loc) · 10.7 KB

PhishGuard M3 - Security Module Guide

📋 Overview

The M3 Security Module provides production-grade encryption, digital signatures, and secrets management for PhishGuard. This guide covers setup, usage, and best practices.

🔐 Components

1. crypto_simple.py - Encryption Module

  • Algorithm: AES-256-GCM (Authenticated Encryption)
  • Key Derivation: scrypt (N=16384, r=8, p=1)
  • Format: salt(16 bytes) + nonce(12 bytes) + ciphertext+tag
  • Functions:
    • encrypt_data(data, passphrase) → bytes
    • decrypt_data(blob, passphrase) → dict
    • save_encrypted(data, filepath, passphrase)
    • load_encrypted(filepath, passphrase) → dict
    • encrypt_to_base64(data, passphrase) → str
    • decrypt_from_base64(b64_string, passphrase) → dict

2. signing.py - Digital Signature Module

  • Algorithm: HMAC-SHA256
  • Output: Base64-encoded signatures
  • Functions:
    • sign(record, secret) → str
    • verify(record, signature, secret) → bool
    • sign_analysis(analysis_json, secret) → dict (with signature)
    • verify_analysis(signed_analysis, secret) → bool

3. encrypt_secrets.py - CLI Tool

  • Interactive CLI for encrypting API keys and secrets
  • Generates cryptographically secure signing secret (256-bit)
  • Creates secrets.enc file (binary encrypted format)

4. Streamlit Security Tab

  • Load encrypted secrets at runtime (hybrid mode)
  • Verify digital signatures of analysis records
  • No app restart required for secret loading

🚀 Quick Start

Step 1: Install Dependencies

Ensure you have the cryptography library installed:

pip install cryptography

Step 2: Create Encrypted Secrets

Run the interactive CLI tool:

python encrypt_secrets.py

You will be prompted for:

  1. Master passphrase (create a strong one!)
  2. Gemini API Key
  3. MongoDB URI (optional)
  4. Twilio Account SID (optional)
  5. Twilio Auth Token (optional)

Output:

  • Creates secrets.enc (encrypted binary file)
  • Auto-generates a 256-bit signing secret
  • Displays usage instructions

⚠️ IMPORTANT: Store your passphrase securely (password manager recommended)

Step 3: Load Secrets in Streamlit

  1. Run the Streamlit app:

    streamlit run app.py

  2. Navigate to the 🔐 Security tab

  3. Click 🔓 Load Secrets

  4. Enter your master passphrase

  5. Secrets are now loaded in st.session_state.secrets

Step 4: Use Secrets in Your Code

from crypto_simple import load_encrypted

# Load secrets
secrets = load_encrypted('secrets.enc', passphrase)

# Access secrets
gemini_key = secrets['gemini_api_key']
mongo_uri = secrets.get('mongo_uri', '')
signing_secret = secrets['signing_secret']

📖 Usage Examples

Encrypting Data

from crypto_simple import encrypt_data, decrypt_data

# Encrypt
data = {
    'email_id': '12345',
    'risk_score': 85,
    'category': 'HIGH_RISK'
}
passphrase = 'my-strong-passphrase'
encrypted_blob = encrypt_data(data, passphrase)

# Decrypt
decrypted_data = decrypt_data(encrypted_blob, passphrase)
print(decrypted_data)

Signing Analysis Records

from signing import sign_analysis, verify_analysis

# Sign an analysis record
analysis = {
    'email_id': '12345',
    'risk_score': 85,
    'category': 'HIGH_RISK',
    'timestamp': '2024-11-02T10:00:00Z'
}

signing_secret = bytes.fromhex('your-hex-secret')
signed_analysis = sign_analysis(analysis, signing_secret)

# signed_analysis now contains 'signature' field
print(signed_analysis['signature'])

# Verify signature
is_valid = verify_analysis(signed_analysis, signing_secret)
print(f"Valid: {is_valid}")  # True

Verifying Signatures in Streamlit

  1. Go to 🔐 Security tab
  2. Load secrets (if not already loaded)
  3. Choose verification method:
    • Paste JSON: Copy/paste signed analysis JSON
    • Upload File: Upload a .json file
  4. Click 🔍 Verify Signature
  5. See result: ✅ Valid or ❌ Invalid

🔒 Security Best Practices

Passphrases

  • ✅ Use 12+ characters
  • ✅ Mix uppercase, lowercase, numbers, symbols
  • ✅ Store in password manager
  • ❌ Never hardcode in source code
  • ❌ Never commit to version control

Secrets Management

  • ✅ secrets.enc is in .gitignore (already configured)
  • ✅ Backup secrets.enc securely (encrypted cloud storage)
  • ✅ Use different secrets for dev/staging/production
  • ❌ Never share secrets.enc via email or chat
  • ❌ Never commit secrets.enc to git

Signing Secrets

  • ✅ Auto-generated 256-bit secrets (cryptographically secure)
  • ✅ Rotate periodically (every 90 days recommended)
  • ✅ Store in encrypted secrets.enc
  • ❌ Never use predictable secrets
  • ❌ Never reuse across environments

Key Rotation

When rotating secrets:

  1. Create new secrets.enc with new passphrase
  2. Update signing secret
  3. Re-sign all existing analysis records (if needed)
  4. Archive old secrets.enc securely
  5. Update passphrase in password manager

🛠️ Advanced Usage

Base64 Encoding (for APIs/transmission)

from crypto_simple import encrypt_to_base64, decrypt_from_base64

# Encrypt to base64 string
data = {'key': 'value'}
b64_encrypted = encrypt_to_base64(data, passphrase)

# Send via API, store in database, etc.
print(b64_encrypted)  # "aGVsbG8gd29ybGQ..."

# Decrypt from base64
decrypted = decrypt_from_base64(b64_encrypted, passphrase)

Custom Signing Secrets

from signing import sign_with_hex_secret, verify_with_hex_secret

# Use hex-encoded secret
hex_secret = 'a1b2c3d4e5f6...'  # 64 hex chars = 256 bits

signature = sign_with_hex_secret(record, hex_secret)
is_valid = verify_with_hex_secret(record, signature, hex_secret)

Programmatic Secret Creation

from crypto_simple import save_encrypted
import secrets

# Generate signing secret
signing_secret = secrets.token_hex(32)  # 256 bits

# Create secrets dict
secrets_data = {
    'gemini_api_key': 'your-api-key',
    'signing_secret': signing_secret
}

# Encrypt and save
save_encrypted(secrets_data, 'secrets.enc', passphrase)

🧪 Testing

Test Encryption/Decryption

from crypto_simple import encrypt_data, decrypt_data

test_data = {'test': 'data', 'number': 42}
passphrase = 'test-passphrase'

# Encrypt
encrypted = encrypt_data(test_data, passphrase)
print(f"Encrypted size: {len(encrypted)} bytes")

# Decrypt
decrypted = decrypt_data(encrypted, passphrase)
assert decrypted == test_data
print("✅ Encryption test passed")

Test Signing

from signing import sign, verify

record = {'email_id': '123', 'score': 85}
secret = b'test-secret-key'

# Sign
signature = sign(record, secret)
print(f"Signature: {signature}")

# Verify
is_valid = verify(record, signature, secret)
assert is_valid
print("✅ Signing test passed")

# Test tampering detection
record['score'] = 90  # Modify data
is_valid = verify(record, signature, secret)
assert not is_valid
print("✅ Tampering detection test passed")

🐛 Troubleshooting

"Decryption failed: incorrect passphrase"

  • ✅ Check passphrase spelling/capitalization
  • ✅ Ensure no extra spaces
  • ✅ Verify you're using the correct secrets.enc file

"secrets.enc not found"

  • ✅ Run python encrypt_secrets.py first
  • ✅ Check current working directory
  • ✅ Ensure file wasn't accidentally deleted

"Signature Invalid"

  • ✅ Verify signing secret matches
  • ✅ Check if data was modified
  • ✅ Ensure JSON format is correct
  • ✅ Confirm signature field exists

"Module not found: cryptography"

  • ✅ Install: pip install cryptography
  • ✅ Activate virtual environment if using one

📊 File Formats

secrets.enc Structure

[16 bytes: salt]
[12 bytes: nonce]
[variable: encrypted JSON + 16-byte GCM tag]

Signed Analysis JSON

{
  "email_id": "12345",
  "risk_score": 85,
  "category": "HIGH_RISK",
  "timestamp": "2024-11-02T10:00:00Z",
  "signature": "base64-encoded-hmac-sha256-signature"
}

🔄 Hybrid Mode

Hybrid Mode allows loading secrets at runtime without restarting the app:

  1. Start app without secrets loaded
  2. Navigate to 🔐 Security tab
  3. Load secrets when needed
  4. Reload with different passphrase/file anytime
  5. No app restart required

Use Cases:

  • Switch between dev/prod secrets
  • Load secrets only when needed
  • Test different configurations
  • Multi-tenant scenarios

📚 API Reference

crypto_simple.py

encrypt_data(data: dict, passphrase: str) -> bytes

Encrypts a dictionary using AES-256-GCM.

Raises:

  • ValueError: If passphrase is empty
  • TypeError: If data cannot be serialized to JSON

decrypt_data(blob: bytes, passphrase: str) -> dict

Decrypts an encrypted blob back to dictionary.

Raises:

  • ValueError: If blob format is invalid or passphrase is wrong

save_encrypted(data: dict, filepath: str, passphrase: str) -> None

Encrypts and saves data to a file.

load_encrypted(filepath: str, passphrase: str) -> dict

Loads and decrypts data from a file.

signing.py

sign(record: dict, secret: bytes) -> str

Generates HMAC-SHA256 signature for a record.

Returns: Base64-encoded signature

verify(record: dict, signature: str, secret: bytes) -> bool

Verifies HMAC-SHA256 signature for a record.

Returns: True if valid, False otherwise

sign_analysis(analysis_json: dict, secret: bytes) -> dict

Signs an analysis JSON and returns a copy with signature field.

verify_analysis(signed_analysis: dict, secret: bytes) -> bool

Verifies a signed analysis record.

✅ Security Checklist

  • Created strong master passphrase (12+ characters)
  • Stored passphrase in password manager
  • Created secrets.enc using encrypt_secrets.py
  • Verified secrets.enc is in .gitignore
  • Backed up secrets.enc securely
  • Tested loading secrets in Streamlit
  • Tested signature verification
  • Set up key rotation schedule (90 days)
  • Documented passphrase recovery process
  • Configured different secrets for each environment

🆘 Support

For issues or questions:

  1. Check this guide's troubleshooting section
  2. Review code comments in crypto_simple.py and signing.py
  3. Test with simple examples first
  4. Verify all dependencies are installed

📝 License & Security Notice

This module uses industry-standard cryptographic algorithms:

  • AES-256-GCM: NIST-approved authenticated encryption
  • scrypt: Memory-hard key derivation function
  • HMAC-SHA256: FIPS-approved message authentication

Security Audit Recommendation: For production use, consider a third-party security audit of cryptographic implementations.

Last Updated: November 2024
Version: M3.0
Module: PhishGuard Security
⚡