This guide covers security best practices, threat models, and recommendations for running Falconer safely in production environments.
- Security Model Overview
- Threat Model
- Key Management
- Network Security
- Operational Security
- Policy Configuration
- Monitoring & Incident Response
- Compliance & Auditing
- Security Checklist
Falconer implements a defense-in-depth security model with multiple layers of protection:
- 🔐 No Hot Wallets: Private keys never stored on internet-connected devices
- 🛡️ Air-gapped Signing: All transactions require manual PSBT signing
- 📋 Policy Enforcement: Every action validated against configurable rules
- 👤 Human Oversight: Critical decisions require human approval
- 📊 Audit Trails: Complete logging of all operations and decisions
┌─────────────────────────────────────────────────────────────┐
│ Human Approval Layer │
│ • Funding proposals • Emergency stops • Policy changes │
├─────────────────────────────────────────────────────────────┤
│ Policy Engine Layer │
│ • Spending limits • Risk controls • Time restrictions │
├─────────────────────────────────────────────────────────────┤
│ Application Layer │
│ • Authentication • Authorization • Input validation │
├─────────────────────────────────────────────────────────────┤
│ Network Layer │
│ • TLS encryption • Firewall rules • VPN access │
├─────────────────────────────────────────────────────────────┤
│ Infrastructure Layer │
│ • Secure hosting • Backup systems • Monitoring │
└─────────────────────────────────────────────────────────────┘
- Malicious Actors: Hackers attempting to steal funds or disrupt operations
- Network Attacks: Man-in-the-middle, DDoS, or network interception
- Supply Chain: Compromised dependencies or third-party services
- Social Engineering: Phishing, impersonation, or social manipulation
- Insider Access: Compromised credentials or malicious insiders
- Configuration Errors: Misconfigured policies or permissions
- Software Bugs: Vulnerabilities in Falconer or dependencies
- Operational Mistakes: Human error in configuration or operations
- Market Manipulation: Attempts to influence AI decisions
- Infrastructure Failure: Hardware, network, or service outages
- Regulatory Changes: Legal or compliance requirement changes
- Technology Obsolescence: Deprecated protocols or standards
| Threat | Likelihood | Impact | Risk Level | Mitigation |
|---|---|---|---|---|
| Private key theft | Low | Critical | High | Air-gapped signing, hardware wallets |
| Network interception | Medium | High | High | TLS encryption, VPN, firewall |
| AI manipulation | Medium | Medium | Medium | Policy limits, human oversight |
| Configuration errors | High | Medium | Medium | Automated testing, validation |
| Infrastructure failure | Medium | High | Medium | Redundancy, monitoring, backups |
# ❌ NEVER DO THIS echo "private_key_here" > ~/.falconer/keys.txt # ✅ CORRECT APPROACH # Use hardware wallets or air-gapped devices only
Falconer supports hardware wallet integration for maximum security:
# Example: Ledger integration from falconer.wallet.hardware import LedgerWallet wallet = LedgerWallet() # Private keys never leave the hardware device
For additional security, configure multi-signature wallets:
# 2-of-3 multisig configuration FALCONER_MULTISIG_THRESHOLD=2 FALCONER_MULTISIG_TOTAL=3 FALCONER_MULTISIG_KEYS="key1,key2,key3"
- Generate PSBT: Falconer creates Partially Signed Bitcoin Transaction
- Transfer to Air-gapped Device: Use QR codes or USB transfer
- Sign Offline: Sign transaction on air-gapped device
- Broadcast: Transfer signed transaction back to online device
# Generate PSBT for funding proposal falconer proposals approve <proposal-id> --generate-psbt # Transfer PSBT to air-gapped device (QR code) # Sign on air-gapped device # Transfer signed transaction back falconer proposals broadcast <signed-tx>
Always validate PSBTs before signing:
# Validate PSBT structure and amounts def validate_psbt(psbt_data): # Check input/output amounts # Verify destination addresses # Validate fee rates # Confirm policy compliance pass
# Use TLS 1.3 with strong cipher suites TLS_VERSION=1.3 TLS_CIPHERS="TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" # Certificate configuration SSL_CERT_PATH=/path/to/cert.pem SSL_KEY_PATH=/path/to/private.key SSL_CA_PATH=/path/to/ca.pem
- Use valid SSL certificates from trusted CAs
- Implement certificate pinning for critical endpoints
- Regular certificate rotation and monitoring
- Use Let's Encrypt for automated certificate management
# Allow only necessary ports # Bitcoin RPC: 8332 (or custom port) # LNbits: 443 (HTTPS) # Falconer API: 8080 (custom port) # SSH: 22 (restrict to specific IPs) # Example iptables rules iptables -A INPUT -p tcp --dport 8332 -s 127.0.0.1 -j ACCEPT iptables -A INPUT -p tcp --dport 443 -j ACCEPT iptables -A INPUT -p tcp --dport 8080 -s 10.0.0.0/8 -j ACCEPT iptables -A INPUT -p tcp --dport 22 -s YOUR_IP -j ACCEPT iptables -A INPUT -j DROP
For remote access, use VPN instead of direct SSH:
# Configure WireGuard VPN
[Interface]
PrivateKey = your_private_key
Address = 10.0.0.2/24
[Peer]
PublicKey = server_public_key
Endpoint = your-server.com:51820
AllowedIPs = 10.0.0.0/24# Create dedicated user for Falconer sudo useradd -r -s /bin/false falconer sudo usermod -aG bitcoin falconer # Restrict file permissions chmod 600 /etc/falconer/.env chown falconer:falconer /etc/falconer/.env
# Use strong, unique API keys LNBITS_API_KEY=$(openssl rand -hex 32) N8N_SHARED_SECRET=$(openssl rand -hex 32) # Rotate keys regularly # Store keys in secure key management system # Never commit keys to version control
# Disable unnecessary services systemctl disable bluetooth systemctl disable cups systemctl disable avahi-daemon # Configure automatic security updates apt install unattended-upgrades dpkg-reconfigure -plow unattended-upgrades # Enable firewall ufw enable ufw default deny incoming ufw default allow outgoing
# Run Falconer in container for isolation
docker run -d \
--name falconer \
--restart unless-stopped \
--cap-drop ALL \
--cap-add NET_BIND_SERVICE \
-v /etc/falconer:/config:ro \
falconer:latest# Create encrypted backups tar -czf - /var/lib/falconer | \ gpg --symmetric --cipher-algo AES256 --output falconer-backup-$(date +%Y%m%d).tar.gz.gpg # Store backups in multiple locations # Test backup restoration regularly # Use different encryption keys for different backup locations
# Start with very conservative limits MAX_DAILY_SPEND_SATS=10000 # 5ドル-10 per day MAX_SINGLE_TX_SATS=5000 # 2ドル.50-5 per transaction MAX_DAILY_PROPOSALS=2 # Maximum 2 funding proposals per day FUNDING_PROPOSAL_THRESHOLD_SATS=5000 # Request funding when below 2ドル.50
# Only allow operations during business hours ALLOWED_HOURS_START=9 ALLOWED_HOURS_END=17 ALLOWED_TIMEZONE=UTC # Weekend restrictions WEEKEND_OPERATIONS=false
# Maximum fee rate for transactions MAX_FEE_RATE_SATS_PER_VBYTE=50 # Minimum confirmation requirements MIN_CONFIRMATIONS=3 # Maximum mempool congestion threshold MAX_MEMPOOL_CONGESTION_PERCENT=80
# Require human approval for large amounts HUMAN_APPROVAL_THRESHOLD_SATS=10000 # Limit AI decision frequency AI_DECISION_INTERVAL_SECONDS=300 # Require confirmation for new strategies AUTO_APPROVE_NEW_STRATEGIES=false
# Monitor for suspicious activity tail -f /var/log/falconer/security.log | grep -E "(FAILED|ERROR|UNAUTHORIZED)" # Set up log alerts # Monitor for: # - Failed authentication attempts # - Policy violations # - Unusual spending patterns # - Network anomalies
# Configure alerts for critical events ALERT_ON_POLICY_VIOLATION=true ALERT_ON_LARGE_TRANSACTION=true ALERT_ON_FUNDING_PROPOSAL=true ALERT_ON_SYSTEM_ERROR=true # Notification channels ALERT_EMAIL=security@yourdomain.com ALERT_SLACK_WEBHOOK=https://hooks.slack.com/... ALERT_SMS_NUMBER=+1234567890
- Detection: Automated monitoring detects security event
- Assessment: Determine severity and impact
- Containment: Isolate affected systems
- Investigation: Analyze logs and system state
- Recovery: Restore normal operations
- Post-mortem: Document lessons learned
# Emergency stop script #!/bin/bash # emergency-stop.sh echo "EMERGENCY STOP INITIATED" | logger -t falconer systemctl stop falconer systemctl stop bitcoin # Notify administrators # Preserve logs and system state
# System recovery checklist # 1. Verify system integrity # 2. Check backup integrity # 3. Restore from clean backup if needed # 4. Update all security patches # 5. Rotate all credentials # 6. Reconfigure policies # 7. Test all functionality # 8. Resume operations with increased monitoring
# Log all critical operations logger.info("Transaction initiated", amount_sats=amount, destination=address, policy_check=passed, user_id=user_id, timestamp=datetime.utcnow().isoformat() )
# Retain logs for compliance period LOG_RETENTION_DAYS=2555 # 7 years LOG_ROTATION_SIZE=100M LOG_COMPRESSION=true LOG_ENCRYPTION=true
- KYC/AML: Implement customer identification procedures
- Transaction Reporting: Maintain detailed transaction records
- Audit Requirements: Support external audit processes
- Data Protection: Comply with GDPR, CCPA, and other privacy laws
- ISO 27001: Information security management
- SOC 2: Security, availability, and confidentiality
- PCI DSS: Payment card industry standards (if applicable)
- Server hardened with security updates
- Firewall configured with restrictive rules
- VPN access configured for remote management
- SSL/TLS certificates properly configured
- Backup systems tested and verified
- Monitoring and alerting systems active
- All default passwords changed
- API keys generated with strong entropy
- Environment variables properly secured
- Policy limits configured conservatively
- Logging configured for security events
- Error handling prevents information leakage
- Access controls implemented (least privilege)
- Incident response procedures documented
- Security monitoring active
- Regular security updates scheduled
- Backup and recovery procedures tested
- Staff trained on security procedures
- Review security logs for anomalies
- Check system resource usage
- Verify backup completion
- Monitor for policy violations
- Review funding proposal approvals
- Update security patches
- Review access logs
- Test backup restoration
- Analyze spending patterns
- Review AI decision history
- Rotate API keys and passwords
- Review and update policies
- Conduct security assessment
- Update incident response procedures
- Review compliance requirements
# Emergency contact information
SECURITY_EMAIL=security@yourdomain.com
SECURITY_PHONE=+1234567890
BITCOIN_EXPERT=bitcoin-expert@yourdomain.com
LEGAL_COUNSEL=legal@yourdomain.com- Bitcoin Security Best Practices
- Hardware Wallet Security
- Network Security Guidelines
- Incident Response Planning
- Policy Configuration Guide
- Hardware Wallet Integration
- Network Setup Guide
- Incident Response Playbook
Remember: Security is an ongoing process, not a one-time setup. Regular review, testing, and updates are essential for maintaining a secure Falconer deployment.