netbox-ssl 0.1.0

NetBox plugin for TLS/SSL certificate management - Project Janus

NetBox SSL Plugin

Project Janus — Your Single Source of Truth for TLS/SSL certificate management in NetBox

Named after Janus, the Roman god of doorways and transitions — because every certificate guards a doorway, and every renewal is a transition.

---

✨ Why NetBox SSL?

Managing SSL certificates across your infrastructure shouldn't be a scavenger hunt. NetBox SSL brings visibility and control to your certificate lifecycle:

• 🔍 See everything at a glance — Know which certificates are expiring, where they're deployed, and who owns them
• 🔄 Painless renewals — The Janus workflow transfers all assignments automatically when you renew
• 🔒 Security first — Private keys are never stored, only location hints for your secret management system
• 🎯 Deep integration — Certificates link directly to NetBox Services, Devices, and VMs

🚀 Quick Start

pip install netbox-ssl

Add to your configuration.py:

PLUGINS = ["netbox_ssl"]

Run migrations and restart NetBox:

python manage.py migrate netbox_ssl
sudo systemctl restart netbox netbox-rq

That's it! Navigate to Plugins > SSL Certificates in your NetBox.

📖 Full documentation: docs/

⚙️ Configuration

Customize the plugin via PLUGINS_CONFIG in your configuration.py:

PLUGINS_CONFIG = {
    "netbox_ssl": {
        "expiry_warning_days": 30,   # Days before expiry → Warning status
        "expiry_critical_days": 14,  # Days before expiry → Critical status
    },
}

Option	Type	Default	Description
expiry_warning_days	Integer	30	Certificates expiring within this many days show warning status
expiry_critical_days	Integer	14	Certificates expiring within this many days show critical status

See Configuration for more options including custom fields, permissions, and webhooks.

📸 Screenshots

Certificate details with validity and assignments	Smart Paste import with automatic X.509 parsing
Dashboard widget showing certificate health	Track which certificates are assigned where

🎯 Key Features

Smart Paste Import

Just paste your PEM certificate — the plugin extracts everything automatically: Common Name, SANs, validity dates, issuer chain, fingerprints, and more.

Janus Renewal Workflow

When you import a renewed certificate (same CN as an existing one), the plugin offers to:

• Transfer all assignments from the old certificate
• Archive the old certificate with "Replaced" status
• Link them together for audit trail

Certificate Assignments

Link certificates to the objects that use them:

• Services (recommended) — Port-level granularity (e.g., HTTPS on port 443)
• Devices — Physical servers and appliances
• Virtual Machines — VMs in your virtualization clusters

Expiry Dashboard Widget

Add the widget to your NetBox dashboard to see:

• 🔴 Critical — Expiring within 14 days
• 🟠 Warning — Expiring within 30 days
• ⚫ Orphan — Certificates without assignments

Security by Design

• No private key storage — Private keys never touch the database
• Private key rejection — PEM input with private keys is blocked
• Key location hints — Document where keys are stored (e.g., vault:secret/certs/example.com)

📊 Compatibility

NetBox Version	Plugin Version	Status
4.5.x	0.1.x	✅ Primary
4.4.x	0.1.x	✅ Supported
4.3.x and older	—	❌ Unsupported

📚 Documentation

Full documentation is available in the docs/ folder:

• Installation — Get up and running
• Configuration — Customize expiry thresholds and more
• Usage Guide — Learn the workflows
• API Reference — REST API and GraphQL
• Data Models — Database schema details
• Contributing — Contribution guidelines

🛠️ Development

# Clone and start development environment
git clone https://github.com/ctrl-alt-automate/netbox-ssl.git
cd netbox-ssl
docker compose up -d

# Access NetBox at http://localhost:8000
# Login: admin / admin

See CONTRIBUTING.md for more details.

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch from dev
3. Make your changes with tests
4. Submit a pull request

📄 License

Apache License 2.0

🙏 Acknowledgments

• The NetBox community for the excellent plugin framework
• The cryptography library for robust X.509 parsing