Data Models¶

This page documents the database models used by NetBox SSL Plugin.

Overview¶

┌─────────────────────────────────────────┐
│        CertificateAuthority             │
│  • name, type (public/internal/acme)    │
│  • issuer_pattern (for auto-detect)     │
│  • website_url, portal_url, contact     │
│  • is_approved                          │
└─────────────────┬───────────────────────┘
                  │ 1:N (issuing_ca)
                  │
┌─────────────────┴───────────────────────┐
│              Certificate                │
│  • common_name                          │
│  • serial_number, fingerprint           │
│  • issuer, issuing_ca, validity dates   │
│  • algorithm, key_size                  │
│  • status, tenant                       │
└─────────────────┬───────────────────────┘
                  │ 1:N
                  │
┌─────────────────┴───────────────────────┐
│         CertificateAssignment           │
│  • certificate (FK)                     │
│  • assigned_object (GFK)                │
│  • is_primary, notes                    │
└─────────────────┬───────────────────────┘
                  │ GenericForeignKey
                  │
        ┌─────────┼─────────┐
        ▼         ▼         ▼
    ┌───────┐ ┌───────┐ ┌───────┐
    │Device │ │  VM   │ │Service│
    └───────┘ └───────┘ └───────┘


┌─────────────────────────────────────────┐
│    CertificateSigningRequest (CSR)      │
│  • common_name, subject fields          │
│  • SANs, algorithm, key_size            │
│  • status, fingerprint                  │
│  • requested_by, target_ca              │
└─────────────────┬───────────────────────┘
                  │ Optional FK
                  ▼
            ┌────────────┐
            │Certificate │
            └────────────┘

CertificateAuthority¶

Model for tracking Certificate Authorities (CAs) that issue certificates.

Fields¶

Type Choices¶

Auto-Detection¶

The issuer_pattern field is used for automatic CA matching when importing certificates. When a certificate is imported, the plugin checks if any CA's issuer_pattern is contained (case-insensitive) in the certificate's issuer field.

Example patterns: - DigiCert: digicert - Let's Encrypt: let's encrypt - Sectigo: sectigo

Default Certificate Authorities¶

The plugin provides a list of common CAs that can be pre-populated:

• Let's Encrypt (ACME)
• DigiCert (Public)
• Sectigo (Public)
• GlobalSign (Public)
• And more...

Certificate¶

The main model for storing certificate metadata.

Fields¶

Status Choices¶

Algorithm Choices¶

Chain Status Choices¶

ACME Certificate Tracking¶

The Certificate model includes fields for tracking certificates issued via the ACME protocol (Automatic Certificate Management Environment), commonly used by providers like Let's Encrypt, ZeroSSL, and others.

ACME Fields¶

ACME Provider Choices¶

ACME Challenge Type Choices¶

ACME Computed Properties¶

Auto-Detection¶

The auto_detect_acme() method automatically identifies ACME certificates by analyzing the issuer field against known ACME provider patterns:

• Let's Encrypt: R3, R10, R11, E1, E5, E6 intermediates
• Let's Encrypt Staging: (STAGING) or Fake LE patterns
• ZeroSSL: ZeroSSL in issuer
• Buypass: Buypass in issuer
• Google Trust Services: GTS CA patterns
• Sectigo: Sectigo in issuer

Computed Properties¶

These properties are calculated dynamically:

Unique Constraint¶

Certificates must be unique on (serial_number, issuer) combination. This prevents duplicate imports while allowing certificates from different CAs to have the same serial.

CertificateAssignment¶

Links certificates to infrastructure objects.

Fields¶

Supported Object Types¶

The assigned_object GenericForeignKey supports:

Tip: Service assignments are recommended because they provide port-level granularity.

Unique Constraint¶

Assignments must be unique on (certificate, assigned_object_type, assigned_object_id). This prevents assigning the same certificate to the same object twice.

Validation Rules¶

1. Tenant Boundary: If certificate has a tenant, target object must have same tenant or no tenant
2. Object Existence: Target object must exist and be of a supported type

CertificateSigningRequest (CSR)¶

Tracks pending Certificate Signing Requests before they become issued certificates.

Fields¶

Status Choices¶

Computed Properties¶

Unique Constraint¶

CSRs must be unique on fingerprint_sha256. This prevents duplicate imports.

Smart Paste Import¶

CSRs can be imported via "Smart Paste":

1. User pastes PEM-formatted CSR content
2. Parser extracts all subject fields, SANs, and key info
3. Fingerprint is calculated for duplicate detection
4. CSR record is created with pending status

CompliancePolicy¶

Defines compliance rules for certificate validation.

Fields¶

Policy Type Choices¶

Severity Choices¶

Policy Parameters Examples¶

// min_key_size
{"min_bits": 2048}

// max_validity_days
{"max_days": 397}

// algorithm_allowed
{"algorithms": ["rsa", "ecdsa", "ed25519"]}

// algorithm_forbidden
{"algorithms": ["dsa"]}

// expiry_warning
{"warning_days": 30}

// san_required
{"min_count": 1}

// issuer_allowed
{"issuers": ["DigiCert", "Let's Encrypt"]}

// issuer_forbidden
{"issuers": ["Unknown CA", "Self-Signed"]}

ComplianceCheck¶

Stores results of compliance checks against certificates.

Fields¶

Result Choices¶

Computed Properties¶

Unique Constraint¶

Only one check result per (certificate, policy) combination. Running compliance checks updates the existing record.

Database Tables¶

Indexes¶

The following indexes are created for performance:

• certificate.common_name — For CN searches
• certificate.serial_number — For serial lookups
• certificate.valid_to — For expiry queries
• certificate.status — For status filtering
• assignment.certificate_id — For certificate lookups

Migrations¶

Migrations are stored in netbox_ssl/migrations/.

Running Migrations¶

# Apply all pending migrations
python manage.py migrate netbox_ssl

# Check migration status
python manage.py showmigrations netbox_ssl

# Roll back to specific migration
python manage.py migrate netbox_ssl 0001

# Roll back all (remove tables)
python manage.py migrate netbox_ssl zero

Creating New Migrations¶

After modifying models:

python manage.py makemigrations netbox_ssl
python manage.py migrate netbox_ssl

Example Queries¶

Django ORM¶

from netbox_ssl.models import Certificate, CertificateAssignment

# Get active certificates expiring within 30 days
from django.utils import timezone
from datetime import timedelta

expiring = Certificate.objects.filter(
    status='active',
    valid_to__lte=timezone.now() + timedelta(days=30)
)

# Get certificates with their assignments
certs = Certificate.objects.prefetch_related('assignments')
for cert in certs:
    print(f"{cert.common_name}: {cert.assignments.count()} assignments")

# Find orphan certificates (no assignments)
orphans = Certificate.objects.filter(
    status='active',
    assignments__isnull=True
)

# Get all certificates for a device
from dcim.models import Device
device = Device.objects.get(name='web-server-01')
assignments = CertificateAssignment.objects.filter(
    assigned_object_type__model='device',
    assigned_object_id=device.id
)

Raw SQL¶

-- Expiring certificates
SELECT common_name, valid_to,
       (valid_to - NOW()) AS time_remaining
FROM netbox_ssl_certificate
WHERE status = 'active'
  AND valid_to < NOW() + INTERVAL '30 days'
ORDER BY valid_to;

-- Certificate assignment counts
SELECT c.common_name, COUNT(a.id) AS assignment_count
FROM netbox_ssl_certificate c
LEFT JOIN netbox_ssl_certificateassignment a ON a.certificate_id = c.id
GROUP BY c.id
ORDER BY assignment_count DESC;