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.

📖 Getting Started Guide — Installation, prerequisites, quick start, and troubleshooting.

• 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)
  • Device detection and enumeration
  • FIDO2 credential management (list, register, delete, verify attestation)
  • PIN validation and complexity checking
  • Sanitized logging to prevent credential leakage
• 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.sh

The 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.

git clone https://github.com/yourusername/yubikey-tools.git
cd yubikey-tools
pip install -e ".[dev]"

pip install yubikey-tools

Note: The project is currently in pre-release (v0.1.0). Use the development installation for now. See the Getting Started Guide for detailed prerequisites and platform-specific setup.

from yubikey_tools.core.operations.yubikey_detection import list_yubikeys, check_firmware_version

# List all connected YubiKeys
devices = list_yubikeys()
for d in devices:
    print(f"{d['serial']}: {d['form_factor']} (firmware {d['version']})")

# Verify firmware version
ok = check_firmware_version(serial=12345678, min_version="5.0.0")
print(f"Firmware OK: {ok}")

For more examples (FIDO2 credential management, PIN validation, attestation verification), see the Getting Started Guide.

yubikey-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_logging decorator 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 with all dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run security checks
bandit -r src/
safety check

# Format and lint code
black src/ tests/
isort src/ tests/
flake8 src/ tests/
mypy src/

• Python 3.9+
• ykman (YubiKey Manager CLI)
• libfido2
• A dedicated test YubiKey for hardware integration tests

See docs/guides/getting-started.md for platform-specific dependency installation instructions.

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)