Metadata-Version: 2.4
Name: netbox-certificates-plugin
Version: 1.0.0
Summary: Certificate inventory, services, cryptographic relationships, health, policy, alerts, and secure material management for NetBox
Author: NetBox Certificates Plugin contributors
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Fokkert/netbox-certificates-plugin
Project-URL: Repository, https://github.com/Fokkert/netbox-certificates-plugin
Project-URL: Issues, https://github.com/Fokkert/netbox-certificates-plugin/issues
Project-URL: Documentation, https://github.com/Fokkert/netbox-certificates-plugin#readme
Project-URL: Changelog, https://github.com/Fokkert/netbox-certificates-plugin/blob/main/CHANGELOG.md
Keywords: netbox,netbox-plugin,x509,certificate,pki,csr,pkcs12,tls
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Intended Audience :: Information Technology
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: cryptography>=42
Requires-Dist: requests>=2.32
Provides-Extra: rar
Requires-Dist: rarfile>=4.2; extra == "rar"
Dynamic: license-file

# 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

| Component | Supported |
| --- | --- |
| NetBox | 4.5.9, 4.5.10 |
| Python | 3.12+ |
| `cryptography` | 42+ |
| Upgrade baseline | 0.5.0 |

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

## Navigation

```text
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:

| Object | Custom actions |
| --- | --- |
| Service | `archive_export` |
| Certificate | existing `download` |
| Private Key | existing `download` |
| CSR | existing `download` |
| Bundle | existing `export`, `export_pfx` |
| Certificate Policy | `archive_export` |
| Object Link | `archive_export` |
| Health Finding | `run_healthscan`, `acknowledge`, `ignore`, `resolve`, `archive_export` |
| Alert Channel | `test`, `archive_export` |
| Alert Rule | `test`, `archive_export` |
| Alert Event | `archive_export` |

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](docs/PERMISSIONS.md).

## REST API

Base:

```text
/api/plugins/ssl-certificates/
```

1.0 public model endpoints:

```text
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](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:

```text
netbox-certificates-plugin==1.0.0
```

in `/opt/netbox/local_requirements.txt`.

Enable:

```python
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:

```bash
cd /opt/netbox
sudo ./upgrade.sh
```

Then:

```bash
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](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](UPGRADE.md)
- [Compatibility](COMPATIBILITY.md)
- [API](docs/API.md)
- [Services](docs/SERVICES.md)
- [Health and Validity](docs/HEALTH-AND-VALIDITY.md)
- [Policies](docs/POLICIES.md)
- [Alerts](docs/ALERTS.md)
- [Exports and manifests](docs/EXPORTS.md)
- [Permissions](docs/PERMISSIONS.md)
- [Bulk operations](docs/BULK_OPERATIONS.md)
- [Publishing](docs/PUBLISHING.md)
- [Uninstall](docs/UNINSTALL.md)
- [Validation](VALIDATION.md)

## License

Apache-2.0. See `LICENSE` and `NOTICE`.
