Skip to content

M3_QUICK_START.md

Latest commit

 

History

History
171 lines (125 loc) · 3.74 KB

M3_QUICK_START.md

File metadata and controls

171 lines (125 loc) · 3.74 KB

PhishGuard M3 - Quick Start Guide

🚀 5-Minute Setup

Step 1: Install Dependencies

pip install cryptography

Step 2: Create Encrypted Secrets

python encrypt_secrets.py

Follow the prompts:

  1. Enter master passphrase (remember this!)
  2. Enter Gemini API Key
  3. Enter optional credentials (MongoDB, Twilio)
  4. File secrets.enc will be created

Step 3: Run the App

streamlit run app.py

Step 4: Load Secrets

  1. Click 🔐 Security tab
  2. Enter your passphrase
  3. Click 🔓 Load Secrets
  4. ✅ Done!

📁 Files Created

File Purpose
crypto_simple.py AES-256-GCM encryption/decryption
signing.py HMAC-SHA256 digital signatures
encrypt_secrets.py CLI tool to create secrets.enc
secrets.enc Encrypted secrets (binary)
app.py Updated with Security tab
.gitignore Updated to ignore secrets.enc

🔐 Security Features

Encryption

  • Algorithm: AES-256-GCM
  • Key Derivation: scrypt (N=16384)
  • Format: salt(16) + nonce(12) + ciphertext+tag

Signing

  • Algorithm: HMAC-SHA256
  • Output: Base64-encoded signatures
  • Auto-generated: 256-bit signing secret

Streamlit Integration

  • Load secrets at runtime (no restart needed)
  • Verify analysis signatures
  • Hybrid mode support

💻 Code Examples

Load Secrets in Python

from crypto_simple import load_encrypted

secrets = load_encrypted('secrets.enc', 'your-passphrase')
api_key = secrets['gemini_api_key']
signing_secret = secrets['signing_secret']

Sign Analysis Record

from signing import sign_analysis

analysis = {
    'email_id': '123',
    'risk_score': 85,
    'category': 'HIGH_RISK'
}

signing_secret = bytes.fromhex(secrets['signing_secret'])
signed = sign_analysis(analysis, signing_secret)

# signed now contains 'signature' field

Verify Signature

from signing import verify_analysis

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

⚠️ Important Security Notes

  1. Never commit secrets.enc - Already in .gitignore ✅
  2. Store passphrase securely - Use password manager
  3. Backup secrets.enc - Keep encrypted backup
  4. Use strong passphrase - 12+ characters recommended
  5. Rotate secrets - Every 90 days for production

🧪 Test Your Setup

# Test encryption
python -c "from crypto_simple import encrypt_data, decrypt_data; \
data = {'test': 'data'}; \
encrypted = encrypt_data(data, 'test'); \
print('✅ Encryption works!' if decrypt_data(encrypted, 'test') == data else '❌ Failed')"

# Test signing
python -c "from signing import sign, verify; \
record = {'id': '1'}; \
sig = sign(record, b'secret'); \
print('✅ Signing works!' if verify(record, sig, b'secret') else '❌ Failed')"

📖 Full Documentation

See M3_SECURITY_GUIDE.md for:

  • Detailed API reference
  • Advanced usage examples
  • Troubleshooting guide
  • Security best practices
  • Key rotation procedures

🆘 Troubleshooting

Problem: secrets.enc not found
Solution: Run python encrypt_secrets.py first

Problem: Decryption failed
Solution: Check passphrase (case-sensitive, no extra spaces)

Problem: Module not found: cryptography
Solution: Run pip install cryptography

Problem: Signature Invalid
Solution: Ensure signing secret matches and data wasn't modified

✅ Verification Checklist

  • cryptography installed
  • secrets.enc created
  • Can load secrets in Streamlit
  • Security tab accessible
  • Signature verification works
  • Passphrase stored securely

Ready to use! 🎉

For questions, see M3_SECURITY_GUIDE.md or check code comments.
⚡