NetBox Certificates Plugin

NetBox Certificates Plugin 1.0.0 is a certificate-management layer for NetBox. It inventories X.509 certificates, encrypted private keys, CSRs and Bundles; models the Services that consume them; links plugin objects to native NetBox objects; evaluates certificate health and policy; and provides configurable alerting and secure material export.

1.0.0 is an intentional breaking release. It replaces the pre-1.0 navigation, REST object names, relationship API and expiration-only alert API. Existing cryptographic inventory is preserved by database migrations, but API/UI consumers must move to the 1.0 endpoints documented in this repository.

Compatibility

NetBox 4.6+ is deliberately rejected by this release until the plugin is validated against that NetBox API surface.

Navigation

OVERVIEW
├── Expiration Dashboard
├── Certificate Authorities
├── Cryptographic Vault
└── Health and Validity

INVENTORY
├── Groups
├── Services
├── Bundles
├── Certificates
├── Private Keys
└── CSRs

OPERATIONS
├── Import Objects
├── Generate CSR
└── Alerts Configuration

There is no Request Certificate page and no automated Let's Encrypt workflow in 1.0.0. ACME does not provide email-based domain-control validation, so the proposed email-verification design was intentionally omitted.

Core Objects

Groups

Groups organize Certificates, Private Keys, CSRs, Bundles and Services. Groups remain hierarchical and are displayed as an expandable tree while retaining the native NetBox table beneath the tree for filtering, export and bulk actions.

Services

A Service represents the thing certificate material is used for: a website, API, repository, load balancer, Kubernetes endpoint, mail service, VPN, database, internal application or another TLS consumer.

Service metadata includes:

• name, status, type and optional custom type;
• environment and criticality;
• deployment technology/pattern plus optional JSON deployment metadata (for example namespace, secret name, virtual host, ingress or configuration reference);
• protocol, primary URL and additional URLs;
• hostname, port and SNI name;
• external/reference identifier and contact;
• owner, tags, custom fields, description and comments;
• zero or more Groups;
• zero or more Certificates, Private Keys, CSRs and Bundles;
• an optional Certificate Policy.

deployment supplies common UI suggestions such as Nginx, Apache, IIS, HAProxy, Traefik, Kubernetes Ingress, Kubernetes TLS Secret, OpenShift Route, load balancers, API gateways, repositories and registries, but it is deliberately free text so administrators can add deployment values without creating another top-level object type.

Service-to-cryptographic relationships are many-to-many. One Certificate can be linked to many Services and one Service can use many Certificates/Bundles/Keys/CSRs.

Certificates

Certificates retain the pre-1.0 X.509 parsing, material storage, fingerprints, Subject/SAN/Issuer metadata, validity information, key metadata, Groups, ownership and secure download behavior.

1.0.0 adds Service relationships, Policy assignments, global search, Health Findings and generic links to NetBox objects.

There is no previous/current/next renewal history model in 1.0.0.

Certificate Authorities

The Certificate Authorities page represents real imported Certificate objects whose X.509 Basic Constraints mark them as CAs. Root, intermediate and subordinate CA certificates can all appear.

The pre-1.0 root-identity model is retained internally for chain/root resolution only. It is no longer a public CRUD/API model.

Private Keys

Private-key material remains encrypted at rest using the configured Fernet key. Raw or decrypted key material is never added to ordinary serializers, GraphQL metadata, search indexes, filters or metadata exports.

1.0.0 analyzes key strength, duplicate public-key identities, orphaned keys, key/certificate mismatches and reuse across Services.

CSRs

CSRs retain the existing PKCS#10 parsing and generation behavior and can now be linked to multiple Services, Policies, Groups and NetBox objects.

Bundles

Bundles retain their cryptographic matching rules and existing material export formats. Services and Policies can reference multiple Bundles and Bundles can be assigned to multiple Services.

Generic NetBox Object Links

ObjectLink is the 1.0 generic relationship mechanism. It uses Django ContentType because the relationship is implemented with GenericForeignKey.

Plugin objects can be related to native NetBox objects such as Devices, Virtual Machines, Interfaces, IP Addresses, Prefixes, Sites, Racks, Circuits, Clusters, VLANs, VRFs, Tenants, VPN Tunnels and other NetBox model objects.

Links are many-to-many in effect: there is no one-link-per-object limitation.

The legacy public ArtifactLink model/API is retired. Existing link rows are migrated on a best-effort basis into ObjectLink. Automatic cryptographic links produced by the established reconciliation engine are mirrored into ObjectLink, marked automatic, and remain read-only; manual ObjectLinks remain editable/deletable.

Cryptographic Vault

The old Inventory page is replaced by Cryptographic Vault.

Vault summarizes:

• Certificates and CA Certificates;
• Private Keys;
• CSRs;
• Bundles;
• Services;
• active and critical Health Findings;
• unassigned cryptographic objects;
• finding categories.

The old /inventory/ URL is intentionally not retained.

Health and Validity

Health and Validity stores structured HealthFinding records. Findings have a category, severity, status, affected object, optional related object, stable fingerprint, evidence, timestamps and NetBox metadata.

Checks include:

• expired and not-yet-valid certificates;
• configurable expiration horizon;
• weak RSA, weak elliptic-curve and deprecated DSA keys;
• weak SHA-1/MD5 signatures;
• missing or ambiguous issuers;
• linked issuer certificates that are not CAs;
• invalid issuer signatures;
• expired/not-yet-valid issuers;
• unresolved root CAs;
• chain loops;
• invalid self-signed roots;
• duplicate Certificates, Private Keys, CSRs and Bundle identities;
• incomplete Bundles;
• public-key mismatches inside Bundles;
• orphan Private Keys;
• certificate/private-key/CSR mismatches on Services;
• private-key reuse across Services;
• Service hostname, URL or SNI values not covered by the linked certificate;
• reuse of a non-wildcard/single-host certificate across multiple Services;
• Certificate Policy violations.

Wildcard matching follows TLS DNS wildcard semantics: *.example.com can cover one label such as www.example.com, but not a.b.example.com.

Health scans run in the NetBox background worker and can also be invoked manually.

Certificate Policies

Certificate Policies define reusable requirements such as:

• minimum RSA size;
• allowed key types;
• allowed signature algorithms;
• allowed EC curves;
• maximum validity;
• SAN requirement;
• wildcard allowance;
• whether CA certificates are permitted;
• permitted issuers;
• whether private-key reuse is forbidden.

Policies can be assigned to Services and directly to Certificates, CSRs or Bundles.

Alerts

1.0.0 replaces the expiration-only alert model with configurable:

• AlertRule
• AlertChannel
• AlertEvent

Rules can scope on finding codes, categories, severities, statuses, object types, tags, owners, Services, Groups and Policies. Expiration rules can specify their own number of days. Cooldown/repeat timing and optional recovery notifications are configurable.

Channels support:

• SMTP email
• HTTP webhook

SMTP passwords and webhook URLs/headers are encrypted at rest using the same required Fernet key used by the plugin's sensitive data handling. Secrets are never returned in normal REST responses or metadata archives.

No alert rule exists by default: all alert delivery is opt-in.

Import Objects

The pre-1.0 unified import behavior remains:

• PEM and DER X.509;
• private keys;
• PKCS#10 CSRs;
• PKCS#7/CMS;
• PKCS#12/PFX;
• supported archives;
• optional RAR support through the rar package extra;
• unrelated multi-object imports;
• multiple Bundle archives in one request;
• loose multi-Bundle grouping by public-key fingerprint.

Cryptographic identity matching remains mandatory. Ambiguous Bundle candidates are rejected instead of guessed.

Generate CSR

CSR generation remains available under Operations → Generate CSR. It retains the existing sensitive-operation protection because it generates private-key material.

Filtering, Export and Bulk Operations

Every actual object-list page uses NetBox-native list/filter/table behavior and supports the applicable native:

• metadata export;
• bulk edit;
• bulk delete;
• bulk rename where the object has a meaningful name.

Derived immutable cryptographic facts and encrypted/raw secrets are intentionally not bulk editable.

The custom Export Material action exists for Certificates, Private Keys, CSRs and Bundles. The custom Export Archive action exists for metadata-oriented 1.0 objects.

0.5.0 export-filter bug

1.0.0 fixes the Invalid export filters defect from 0.5.0. The material exporter no longer sends the complete list-view query string to the FilterSet. It forwards only parameters that are actual fields in the corresponding FilterSet, so NetBox UI state such as pagination, ordering and table-column parameters cannot invalidate a material export.

Exports always start with the permission-restricted queryset and then apply the same filter model used by the list page.

Archive manifests

Multi-file/material exports contain manifest.json, including:

• manifest and plugin versions;
• export timestamp;
• object kind and object count;
• applied filters;
• object IDs/displays;
• filenames;
• SHA-256 checksums;
• available cryptographic fingerprints;
• a conservative sensitivity indicator.

Single-file direct Certificate/Private-Key/CSR downloads do not receive an extra manifest.

Sensitive download responses use cache-prevention headers. ZIP member permissions are restrictive.

Global Search

Search indexes cover user-facing plugin inventory/management objects and useful cryptographic identifiers. Private-key plaintext/encrypted material and alert transport secrets are excluded.

NetBox custom fields also participate in global search when the administrator assigns them a search weight.

Permissions

Standard NetBox view, add, change and delete permissions apply to user-managed PrimaryModels. Existing sensitive material actions remain in force for cryptographic objects.

1.0 adds custom actions such as:

Sensitive-operation overlays from pre-1.0 remain: possession of a normal ObjectPermission does not automatically grant plaintext private-key operations where the plugin requires a superuser/write-capable context.

On NetBox 4.5, plugin custom actions can be entered in ObjectPermission Additional actions when the UI does not render a dedicated checkbox.

See docs/PERMISSIONS.md.

REST API

Base:

/api/plugins/ssl-certificates/

1.0 public model endpoints:

groups/
services/
bundles/
certificates/
private-keys/
csrs/
certificate-authorities/
certificate-policies/
health-findings/
object-links/
alert-rules/
alert-channels/
alert-events/

certificate-authorities/ returns CA Certificate objects, not the old internal root identity.

The pre-1.0 artifact-links, root-identity Certificate Authority and expiration-only alert endpoints are intentionally removed. There are no compatibility endpoint aliases.

See docs/API.md.

GraphQL

The plugin exposes the 1.0 public object model through NetBox's plugin GraphQL integration. Internal root identities, legacy ArtifactLinks, legacy expiration objects, private-key material and alert secrets are omitted.

Installation

Add the pinned package to NetBox:

netbox-certificates-plugin==1.0.0

in /opt/netbox/local_requirements.txt.

Enable:

PLUGINS = [
    "netbox_certificates",
]

PLUGINS_CONFIG = {
    "netbox_certificates": {
        "encryption_key": "YOUR_EXISTING_FERNET_KEY",
    },
}

Do not generate a new Fernet key when upgrading an installation that already contains encrypted private-key material. Keep the existing key.

Run the normal NetBox upgrade:

cd /opt/netbox
sudo ./upgrade.sh

Then:

sudo -u netbox /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py check
sudo systemctl restart netbox netbox-rq

Upgrading from 0.5.0

Take a PostgreSQL backup before installing 1.0.0.

The database migrations:

1. add Services, Policies, Object Links, Health Findings and generic Alerts;
2. preserve existing Certificates, Private Keys, CSRs, Bundles, Groups and internal CA/root data;
3. migrate legacy ArtifactLinks on a best-effort basis;
4. remove obsolete public permissions for the retired pre-1.0 models.

The old expiration-only configuration/event tables are retained as private legacy database state so the upgrade does not destructively erase history, but they are not part of the 1.0 public UI/API and are not automatically translated to generic alert rules. Configure the desired 1.0 Alert Channels and Rules after upgrade.

Removed public concepts are documented in UPGRADE.md.

Security

• Private keys remain encrypted at rest.
• SMTP passwords and webhook details are encrypted at rest.
• Raw private-key material is excluded from normal serializers, GraphQL, search and metadata export.
• Sensitive downloads are permission checked and use no-store/no-cache response headers.
• Multi-file exports carry SHA-256 manifests.
• Generic ObjectLinks are limited to public NetBox/plugin model objects; internal/private models are rejected.
• The plugin requires an existing Fernet key.
• Back up both PostgreSQL and the Fernet key before a major upgrade.

Documentation

• Upgrade guide
• Compatibility
• API
• Services
• Health and Validity
• Policies
• Alerts
• Exports and manifests
• Permissions
• Bulk operations
• Publishing
• Uninstall
• Validation

License

Apache-2.0. See LICENSE and NOTICE.