netbox-ssl 0.4.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:

• Preview assignments that will be transferred in a detailed table
• Transfer all assignments from the old certificate atomically
• Archive the old certificate with "Replaced" status
• Link them together for audit trail

Start a renewal directly from the certificate detail page with the Renew button.

Certificate Authority Tracking

Track your CAs (Let's Encrypt, DigiCert, Sectigo, internal CAs) with automatic detection based on issuer patterns.

Certificate Signing Requests (CSR)

Track pending certificate requests through their lifecycle: Pending, Approved, Rejected, Issued.

Chain Validation

Validate certificate chains for completeness, signature correctness, and expiry.

Compliance Reporting

Define compliance policies (minimum key size, forbidden algorithms, max validity, etc.) and run checks across your certificate inventory. 10 built-in policy types with severity levels and scoring.

Data Export

Export certificates in CSV, JSON, YAML, or PEM bundle format with configurable field selection.

ACME Certificate Tracking

Track Let's Encrypt and other ACME-issued certificates with auto-detection, renewal status, and provider metadata.

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.4.x	✅ Primary
4.4.x	0.4.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