A comprehensive GPG key management system with both CLI and server components for tracking, monitoring, and managing GPG keys across your infrastructure.
- Track and monitor GPG keys
- Automated key backup
- Key expiration alerts
- Usage reporting
- Interactive key management
- RESTful API for key management
- Centralized key tracking
- Multi-user support
- API key authentication
- Docker deployment support
./
├── config/ # Configuration files
│ ├── .env.server.example
│ └── config.env.example
├── docker/ # Docker configuration
│ ├── Dockerfile.server
│ └── docker-compose.server.yml
├── docs/ # Documentation
│ ├── CHANGELOG.md
│ ├── INSTALL.md
│ └── server/
├── examples/ # Usage examples
├── lib/ # Core library code
├── scripts/ # Installation scripts
├── server/ # Server components
│ ├── gpg_server.py
│ └── server_cli.py
└── tests/ # Test suite
# Install client components
pip install -r requirements.txt
# Configure settings
cp config/config.env.example config/config.env# Using Docker
docker-compose -f docker/docker-compose.server.yml up -d
# Manual installation
pip install -r docker/requirements_server.txt
cp config/.env.server.example config/.env.server
./server/start_server.py- End-to-end GPG key encryption
- API key authentication
- Secure key backup system
- Role-based access control
MIT License - see LICENSE file for details.
A comprehensive GPG key management system with both standalone tracking capabilities and a secure HTTP API server for enterprise key management.
📖 Server Documentation | 🚀 Quick Start | 📋 Setup Guide | 🔍 Search API Guide
- GPG Key Management: Import, list, search, and manage GPG keys with metadata tracking
- Usage Monitoring: Track encrypt, decrypt, sign, and verify operations with full audit trails
- Expiration Tracking: Monitor key expiration dates with automated alerts
- Backup & Restore: Automated backup system with configurable retention policies
- Interactive Mode: User-friendly interactive CLI interface with rich terminal output
- Report Generation: Detailed usage reports in CSV, JSON, and HTML formats
- Prometheus Integration: Export metrics for operational monitoring systems
- 🔐 HTTP API Server: FastAPI-based secure API with SSL/TLS support on ports 80/443
- 🔑 API Key Authentication: Mandatory authentication for all operations with rate limiting
- 👑 Master Key Validation: Organizational signing & encryption keys for key validation
- 🔍 Enhanced Search: Advanced search by fingerprint, email, key ID, name, or raw key upload
- ⚡ GPG Operations: Complete support for read, list, sign, encrypt, info, and search operations
- 👨💼 Admin Interface: Full API key and master key management with comprehensive CLI tools
- 🐳 Docker Support: Production-ready containerization with Docker Compose
- 📊 Monitoring: Health checks, usage statistics, and Prometheus metrics integration
- 🏢 Organizational Keys: Default organizational signing and encryption keys for validation
- Input Validation: Comprehensive sanitization and validation for all inputs
- Rate Limiting: Configurable per-API-key rate limiting to prevent abuse
- Audit Logging: Complete operation history and usage tracking for compliance
- Permission System: Granular permissions for operations and key access
- SSL/TLS Support: Full HTTPS support with certificate validation
- Master Signatures: All keys must be signed by organizational master keys
- Secure Storage: SHA-256 hashed API keys and encrypted sensitive data
- Docker Support: Production-ready containerization
- Kubernetes Manifests: Cloud-native deployment
- CI/CD Pipeline: Automated testing and deployment
- Monitoring: Prometheus metrics and Grafana dashboards
- Service Management: Systemd integration for production
# 1. Clone and install
git clone https://github.com/straticus1/gpg-key-tracker.git
cd gpg-key-tracker
./install.sh
# 2. Initialize database
python3 gpg_tracker.py init
# 3. Add your first key
python3 gpg_tracker.py add-key --key-file /path/to/key.asc --owner "John Doe" --requester "IT Security"
# 4. List all keys
python3 gpg_tracker.py list-keys
# 5. Generate usage report
python3 gpg_tracker.py generate-report --format htmlFor detailed installation instructions, see INSTALL.md.
- 🎆 Features
- 🚀 Quick Start
- 📋 Installation
- 💻 Usage
- ⚙️ Configuration
- 📈 Reporting
- 🔒 Security
- 📝 Documentation
- 🤝 Contributing
- 📜 License
# Clone and install
git clone https://github.com/your-org/gpg-key-tracker.git
cd gpg-key-tracker
pip install -r requirements.txt
# Initialize database
python gpg_tracker.py --init-db
# Run interactive mode
python gpg_tracker.py --interactive
# Or manage keys directly
python gpg_tracker.py --add-key /path/to/key.asc --owner "[email protected]" --requester "[email protected]"
python gpg_tracker.py --list-keys# Install server dependencies
pip install -r requirements.txt -r docker/requirements_server.txt
# Configure server
cp config/.env.server.example .env
# Edit .env and set GPG_SERVER_ADMIN_API_KEY to a secure value
# Initialize and start server
python start_gpg_server.py --init-only
python server_cli_wrapper.py master-key create-organizational \
--organization "Your Organization" \
--name "Production Keys" \
--email "[email protected]"
python start_gpg_server.py
# Create API keys and test
python server_cli_wrapper.py api-key create --name "My App" --owner "[email protected]" --operations read list search
curl -H "X-API-Key: YOUR_API_KEY" https://localhost:8443/keys# Quick Docker setup
cp config/.env.server.example .env
# Edit .env with your settings
docker-compose -f docker/docker-compose.server.yml up -d
# Initialize organizational keys
docker-compose exec gpg-server python server_cli.py master-key create-organizational \
--organization "Your Organization" \
--name "Production Keys" \
--email "[email protected]"- Python 3.8 or higher
- GPG installed on your system
- Root or sudo access for GPG operations
# Core dependencies
pip install -r requirements.txt
# Server dependencies (if using GPG Key Server)
pip install -r docker/requirements_server.txtsudo yum install gnupg2
# or
sudo dnf install gnupg2sudo apt-get install gnupg2python gpg_tracker.py init# Start user-friendly interactive mode
python gpg_tracker.py interactivepython gpg_tracker.py add-key --key-file /path/to/key.asc --owner "John Doe" --requester "Jane Smith" --jira-ticket "PROJ-123"
# Alias: python gpg_tracker.py add -k /path/to/key.asc -o "John Doe" -r "Jane Smith"python gpg_tracker.py list-keys
python gpg_tracker.py list-keys --all # Include inactive keys
# Aliases: python gpg_tracker.py ls (active only) or python gpg_tracker.py ll (all keys)python gpg_tracker.py edit-key --fingerprint ABC123 --owner "New Owner"python gpg_tracker.py activate-key --fingerprint ABC123
python gpg_tracker.py deactivate-key --fingerprint ABC123python gpg_tracker.py replace-key --old-fingerprint ABC123 --new-key-file new_key.ascpython gpg_tracker.py delete-key --fingerprint ABC123
# Alias: python gpg_tracker.py rm --fingerprint ABC123python gpg_tracker.py expiring-keys --days 30
# Alias: python gpg_tracker.py expiring -d 30python gpg_tracker.py expired-keys
# Alias: python gpg_tracker.py expiredpython gpg_tracker.py update-expirypython gpg_tracker.py logs
python gpg_tracker.py logs --fingerprint ABC123 --limit 100
# Alias: python gpg_tracker.py log -f ABC123 -l 100python gpg_tracker.py health-check
# Alias: python gpg_tracker.py statuspython gpg_tracker.py metrics
python gpg_tracker.py export-metrics --format json
# Alias: python gpg_tracker.py statspython gpg_tracker.py create-backup
python gpg_tracker.py create-backup --name "pre-migration-backup"python gpg_tracker.py list-backupspython gpg_tracker.py restore-backup --backup-name backup_20240915_120000
python gpg_tracker.py restore-backup --backup-name my-backup --components database,gpg_keyringpython gpg_tracker.py delete-backup --backup-name old-backup# Generate CSV report for last 30 days
python gpg_tracker.py generate-report --format csv
# Generate HTML report for last 7 days
python gpg_tracker.py generate-report --days 7 --format html
# Generate report for specific key
python gpg_tracker.py generate-report --fingerprint ABC123 --format json# Email report
python gpg_tracker.py email-report --report-file report.csv --recipients "[email protected],[email protected]"
# Upload to S3
python gpg_tracker.py upload-to-s3 --report-file report.csv --bucket my-reports-bucket
# Upload via SCP
python gpg_tracker.py scp-report --report-file report.csv --host server.company.com --path /reports
# Auto-generate and export
python gpg_tracker.py auto-report --format html --recipients "[email protected]" --s3-bucket my-reportspython gpg_wrapper.py encrypt --file document.txt --recipient [email protected]
python gpg_wrapper.py decrypt --file document.txt.gpgCreate a .env file in the project root:
GPG_HOME=/home/user/.gnupg
DATABASE_PATH=./gpg_tracker.db
LOG_LEVEL=INFO
- The application logs all GPG key usage for audit purposes
- Keys are stored securely in the GPG keyring
- Database contains only metadata, not the actual keys
- All operations are logged with timestamps and user information
GPG Key Tracker includes comprehensive reporting capabilities:
# CSV report for last 30 days
python3 gpg_tracker.py generate-report --format csv
# HTML report for specific timeframe
python3 gpg_tracker.py generate-report --days 7 --format html
# JSON report for specific key
python3 gpg_tracker.py generate-report --fingerprint ABC123 --format json- Email: Automated email delivery with SMTP
- AWS S3: Upload reports to cloud storage
- SCP: Secure copy to remote servers
- Local: Save to filesystem
- Usage statistics and success rates
- Operation breakdown by type and user
- Key-specific filtering
- Customizable date ranges
- Beautiful HTML formatting
- Installation Guide: Comprehensive installation instructions
- Changelog: Version history and feature updates
- GitHub Pages: Full documentation website
- In-app Help: Use
--helpwith any command for detailed usage
We welcome contributions! Here's how to get started:
- Fork the repository
- Clone your fork:
git clone https://github.com/yourusername/gpg-key-tracker.git - Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes and add tests
- Commit your changes:
git commit -m 'Add amazing feature' - Push to your fork:
git push origin feature/amazing-feature - Submit a Pull Request
# Clone the repository
git clone https://github.com/straticus1/gpg-key-tracker.git
cd gpg-key-tracker
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Run tests
python3 -m pytest test_gpg_tracker.py- Follow PEP 8 style guidelines
- Add tests for new features
- Update documentation as needed
- Include clear commit messages
Found a bug or need help?
- GitHub Issues: Submit an issue
- Documentation: Check the full documentation
- Email: [email protected]
This project is licensed under the MIT License - see the LICENSE file for details.
Ryan J Coleman
- Email: [email protected]
- GitHub: @straticus1
- Role: Design and Development
🚀 Made with ❤️ for secure GPG key management