A comprehensive collection of tools for configuring, managing, and automating YubiKey hardware security keys. This project focuses on providing developers and security administrators with reliable, well-tested utilities for YubiKey lifecycle management, batch configuration, security auditing, and integration with enterprise authentication systems.
- Automated YubiKey Setup: Complete GPG key generation and YubiKey configuration with
yubikey-setup.sh - Python Library: Modular library for YubiKey operations (PIV, FIDO2, OATH, OpenPGP)
- CLI Tools: Command-line utilities for common YubiKey management tasks
- Security-First: Built with security best practices, comprehensive auditing, and sanitized logging
- Hardware Testing: Integration tests with real YubiKey devices
- Custom Commands: YubiKey-specific slash commands for security audits and compliance
- Agent Framework: Specialized AI agents for security validation and crypto review
The fastest way to configure a YubiKey with GPG keys:
# Run the automated setup script
./yubikey-setup.sh
# Or from the scripts directory
./scripts/automation/yubikey-setup/yubikey-setup.shThe setup script supports three modes:
- Generate: Create new GPG keys and transfer to YubiKey
- Load: Import existing keys from backup
- Backup: Export configuration and keys
See yubikey-setup documentation for detailed usage.
# Install from source
pip install -e .
# Or install from PyPI (when released)
pip install yubikey-toolsyubikey-tools/
├── src/ # Python library source
│ ├── core/ # Core YubiKey operations
│ │ ├── config/ # Configuration schemas
│ │ └── operations/ # FIDO2, PIV, OATH, OpenPGP handlers
│ ├── tools/ # CLI tools
│ ├── validators/ # Security validation modules
│ └── utils/ # Helper functions and utilities
│
├── tests/ # Test suite
│ ├── unit/ # Unit tests
│ ├── integration/ # Hardware integration tests
│ └── fixtures/ # Test data and mock YubiKeys
│
├── docs/ # Documentation
│ ├── api/ # API documentation
│ ├── guides/ # User guides and tutorials
│ └── security/ # Security considerations
│
├── scripts/ # Automation scripts
│ └── automation/
│ └── yubikey-setup/ # Automated YubiKey setup tool
│
├── .claude/ # Claude Code configuration
│ ├── commands/ # Custom slash commands
│ └── agents/ # Specialized AI agents
│
├── AGENTS.md # AI agent configuration
├── CLAUDE.md # Claude Code guidelines
├── DEVELOPMENT_PLAN.md # Development roadmap
└── TODO.md # Task tracking
YubiKey-specific slash commands for development and security:
/security-audit- Comprehensive security scan (bandit, safety, credential check)/yubikey-enum- Enumerate connected YubiKeys (read-only)/test-hardware- Run integration tests with real hardware/validate-crypto- Review cryptographic operations/check-compliance- Verify security standards compliance/yubikey-backup-verify- Verify backup integrity/pin-security-check- Audit PIN handling in code
AI agents for YubiKey development:
- Security Validator: YubiKey-specific security review, attestation validation, PIN auditing
- Hardware Tester: Physical YubiKey integration testing and device management
- Cryptography Reviewer: Cryptographic code review and algorithm validation
- Getting Started - Installation and basic usage
- YubiKey Setup - Automated setup guide
- Development Plan - Roadmap and architecture
- Security - Threat model and best practices
- Contributing - How to contribute
This project handles hardware security keys and sensitive cryptographic operations. Security is paramount:
- No credential logging: PINs, PUKs, and keys are never logged
- Sanitized logging:
@sanitize_loggingdecorator on sensitive functions - Input validation: All inputs validated before YubiKey operations
- Test device protection: Production YubiKeys never used in tests
- Established crypto libraries: No custom cryptographic implementations
See CLAUDE.md for detailed security standards and docs/security/ for threat model.
Current Phase: Foundation (Phase 1)
- ✅ Repository structure established
- ✅ Automated setup script (yubikey-setup.sh v1.1.0)
- ✅ Documentation and planning complete
- ✅ Custom commands and agents created
- 🚧 Python library in progress
- 📋 CLI tools planned
See DEVELOPMENT_PLAN.md for detailed roadmap.
- Python 3.9+
- YubiKey Manager (ykman)
- libfido2
- GPG (for OpenPGP operations)
- python-fido2
- yubikey-manager
- PyUSB
- cryptography
See requirements.txt or pyproject.toml for complete list.
Contributions are welcome! Please read CONTRIBUTING.md for guidelines.
# Clone repository
git clone https://github.com/yourusername/yubikey-tools.git
cd yubikey-tools
# Create virtual environment
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
# Install in development mode
pip install -e .[dev]
# Run tests
pytest
# Run security checks
bandit -r src/
safety check| Model | PIV | FIDO2 | OATH | OpenPGP | Status |
|---|---|---|---|---|---|
| YubiKey 5 Series | ✅ | ✅ | ✅ | ✅ | Fully Supported |
| YubiKey 5 FIPS | ✅ | ✅ | ✅ | ✅ | Fully Supported |
| Security Key Series | ❌ | ✅ | ❌ | ❌ | FIDO2 Only |
| YubiKey 4 Series | ✅ | ❌ | ✅ | ✅ | Legacy Support |
See docs/compatibility.md for detailed compatibility matrix.
This project is licensed under the MIT License - see the LICENSE file for details.
- Yubico for YubiKey hardware and documentation
- python-fido2 library
- yubikey-manager CLI tool
- Original yubikey-setup.sh contributors
- Issues: GitHub Issues
- Documentation: Project Wiki
- Security: See SECURITY.md for vulnerability reporting
Elvis Nuno
See CHANGELOG.md for version history.
Status: Active Development | Version: 0.1.0 (Pre-release)
