Skip to content

CLI Reference

Jump to bottom
Chris Zinda edited this page Mar 7, 2026 · 3 revisions

CLI Reference

The lab provides two CLI tools for interacting with the PKI infrastructure:

  • lab — Python CLI (Typer/Rich) for end-to-end lab operations
  • pki-cli.py — Direct Dogtag PKI operations via pki CLI inside containers

Installation

# Install dependencies
pip install typer rich httpx

# Or install the package in development mode
pip install -e .

lab CLI Commands

lab status

Check health of all lab services.

lab status

Queries each service endpoint and displays a Rich table with service name, URL, and health status (healthy/unhealthy/unreachable).

lab scenarios

List all available security scenarios.

lab scenarios

Displays all 26 event types organized by category (Original, PKI/Cert, IoT, Identity, Network, SIEM).

lab test

Run an end-to-end certificate revocation test. Issues a certificate, triggers a security event, and polls every 2 seconds until the certificate status changes to REVOKED or a timeout is reached.

lab test --pki-type rsa --scenario "Certificate Private Key Compromise"

Options:

Flag Description Default
--pki-type PKI hierarchy: rsa, ecc, pqc rsa
--scenario Security scenario name (from lab scenarios) Required (unless --all or --category)
--category Run all scenarios in a category (e.g., iot, identity, network) None
--all Run all 26 scenarios sequentially false

Examples:

# Single scenario
lab test --pki-type rsa --scenario "Certificate Private Key Compromise"

# All scenarios in a category
lab test --pki-type ecc --category iot

# All 26 scenarios
lab test --all

lab test-advanced

Run advanced test suites for deeper validation.

lab test-advanced <suite>

Available suites:

Suite Description
lifecycle Full certificate lifecycle: issue, renew, revoke, verify
protocols ACME and EST protocol enrollment and revocation
multi-pki Cross-hierarchy tests (RSA + ECC + PQC)
verification CRL and OCSP verification checks
resilience Service failure and recovery tests
siem SIEM event correlation and response
freeipa FreeIPA identity certificate revocation

lab issue

Issue a certificate from Dogtag PKI via REST API.

lab issue --cn web.cert-lab.local --pki-type rsa --ca-level intermediate --profile caServerCert

Options:

Flag Description Default
--cn Common Name for the certificate Required
--pki-type PKI hierarchy: rsa, ecc, pqc rsa
--ca-level Target CA: root, intermediate, iot intermediate
--profile Certificate profile Auto-selected by PKI type

Profile auto-selection:

PKI Type Profile
rsa caServerCert
ecc caECServerCert
pqc caMLDSAServerCert

lab trigger

Trigger a security event via Mock EDR or SIEM.

lab trigger --event-type key_compromise --serial 0x1A2B3C --pki-type rsa

Options:

Flag Description Default
--event-type One of the 26 supported event types Required
--serial Certificate serial number (hex with 0x prefix) Required
--pki-type PKI hierarchy: rsa, ecc, pqc rsa
--reason Additional context for the event None

lab verify

Check the revocation status of a certificate via OCSP and CRL.

lab verify --serial 0x1A2B3C --pki-type rsa --ca-level intermediate

Options:

Flag Description Default
--serial Certificate serial number (hex) Required
--pki-type PKI hierarchy: rsa, ecc, pqc rsa
--ca-level Target CA: root, intermediate, iot intermediate

lab validate

Run comprehensive lab validation checks across 10 tiers. Optionally auto-remediate issues.

lab validate
lab validate --fix

Validation Tiers:

Tier Name Checks
0 Prerequisites Podman, podman-compose, system resources
1 Containers All containers running and healthy
2 Networks Container networks exist and configured
3 DNS Name resolution for *.cert-lab.local
4 PKI Health Dogtag CA subsystem status
5 Certificates CA chain validity and trust
6 OCSP/CRL Revocation infrastructure functional
7 Kafka Topic existence and message flow
8 EDA Rulebook engine running and connected
9 End-to-End Full issue-revoke-verify cycle

Options:

Flag Description Default
--fix Attempt auto-remediation of failures false
--tier Run only a specific tier (0-9) All tiers

lab acme-issue

Issue a certificate via ACME protocol (RFC 8555).

lab acme-issue --cn web.cert-lab.local --pki-type rsa

Uses the ACME RA endpoint (https://acme-ca.cert-lab.local:8446/acme/directory) to perform HTTP-01 challenge validation and obtain a certificate from the Intermediate CA.

lab est-enroll

Enroll for a certificate via EST protocol (RFC 7030).

lab est-enroll --cn device.iot.cert-lab.local --pki-type rsa

Submits a PKCS#10 CSR to the EST RA (https://est-ca.cert-lab.local:8447/.well-known/est/simpleenroll). The EST RA proxies the request to the Intermediate CA for signing.

lab est-reenroll

Re-enroll (renew) an existing EST-issued certificate.

lab est-reenroll --cn device.iot.cert-lab.local --pki-type rsa --cert <path-to-cert>

Uses the EST simplereenroll endpoint with client certificate authentication from the existing certificate.

lab est-cacerts

Retrieve CA certificates from the EST endpoint.

lab est-cacerts --pki-type rsa

Fetches the CA certificate chain from /.well-known/est/cacerts. Returns the full trust chain (Root CA, Intermediate CA) in PEM format.

lab perf-test

Run a bulk PKI performance test measuring issuance and revocation throughput.

lab perf-test --count 100 --pki-type rsa --ca-level intermediate

Options:

Flag Description Default
--count Number of certificates to issue and revoke 10
--pki-type PKI hierarchy: rsa, ecc, pqc rsa
--ca-level Target CA: root, intermediate, iot intermediate

Outputs timing metrics including average issuance time, revocation time, and throughput (certs/sec).

lab policy-check

Validate a certificate request against the Policy Engine.

lab policy-check <cn> --type server --key-type rsa --key-size 4096 --validity 365

Options:

Flag Description Default
<cn> Common name (positional) Required
--type Certificate type: server, client, iot server
--key-type Key algorithm: rsa, ecc, pqc rsa
--key-size Key size in bits 4096
--validity Validity in days 365

See the Policy Engine page for details on validation rules.

lab crl-list

List CRL files available from a CA's CRL Distribution Point.

lab crl-list --pki-type rsa --ca-level intermediate

lab crl-check

Check whether a certificate serial number appears in a CRL.

lab crl-check --serial 0x1A2B3C --pki-type rsa --ca-level intermediate

Returns whether the serial is listed as revoked in the current CRL, along with the revocation reason and date if present.

pki-cli.py Tool

Direct Dogtag PKI operations via the pki CLI executed inside CA containers using sudo podman exec.

Location: scripts/pki-cli.py

Commands

list

List certificates from a CA.

./scripts/pki-cli.py list --ca iot --pki rsa

issue

Issue a new certificate.

./scripts/pki-cli.py issue --ca iot --cn "device.cert-lab.local" --pki rsa

Auto-selects the correct profile based on --pki type.

status

Check the status of a certificate by serial number.

./scripts/pki-cli.py status 0x1A2B3C --ca iot --pki rsa

revoke

Revoke a certificate.

./scripts/pki-cli.py revoke 0x1A2B3C --ca iot --reason key_compromise --pki rsa

Revocation reasons: unspecified, key_compromise, ca_compromise, affiliation_changed, superseded, cessation_of_operation, certificate_hold, privilege_withdrawn

test

Run an end-to-end test (issue, verify, revoke, verify).

./scripts/pki-cli.py test --ca iot --pki rsa

Common Options

Flag Description Values
--ca Target CA level root, intermediate, iot, est, acme
--pki PKI hierarchy rsa, ecc, pq
--cn Common Name Any valid hostname
--reason Revocation reason See list above

Notes:

  • Serial numbers require the 0x prefix for Dogtag REST API
  • The tool uses sudo podman exec to execute commands inside rootful PKI containers
  • Profile selection is automatic: caServerCert (RSA), caECServerCert (ECC), caMLDSAServerCert (PQ)

Certificate Pinning Commands

pin-register

Register a certificate pin for a hostname.

lab pin-register web-server.cert-lab.local --cert data/certs/rsa/web-server.pem
lab pin-register web-server.cert-lab.local --pin "sha256/abc123..." --pki-type rsa
Option Description
--cert Path to PEM certificate file (extracts SPKI hash)
--pin SHA-256 pin (base64-encoded)
--pki-type PKI type (default: rsa)

pin-validate

Validate a certificate against stored pins.

lab pin-validate web-server.cert-lab.local --cert data/certs/rsa/web-server.pem

pin-list

List all registered certificate pins.

lab pin-list

See Certificate Pinning Validator for full documentation.

KMIP Key Management Commands

kmip-list

List all KMIP-managed keys.

lab kmip-list

kmip-create

Create a KMIP-managed key.

lab kmip-create "rsa-signing-key" --algorithm RSA --length 4096 --pki-type rsa --ca-level root
Option Description
--algorithm Key algorithm: RSA, AES, ECDSA (default: RSA)
--length Key length in bits (default: 4096)
--pki-type Associated PKI type (default: rsa)
--ca-level Associated CA level (default: intermediate)

kmip-lifecycle

Show KMIP key lifecycle summary (count by state).

lab kmip-lifecycle

See KMIP Key Management for full documentation and the scripts/kmip-manage.py CLI.

HSM Commands

hsm-status

Show Kryoptic HSM status and token slots.

lab hsm-status

See Kryoptic HSM for full documentation and the scripts/pki/hsm-manage.sh management script.

Incident Response Commands

incident-response

Run the full 7-phase incident response workflow for a device.

lab incident-response compromised.cert-lab.local --type key_compromise --severity critical
lab incident-response device.cert-lab.local --type decommission --pki-type ecc --no-reissue
Option Description
--type Incident type: key_compromise, ca_compromise, affiliation_changed, decommission, privilege_withdrawn
--pki-type PKI hierarchy (default: rsa)
--severity Severity level (default: critical)
--ca-level CA level (default: intermediate)
--no-reissue Skip automatic certificate re-issuance

See Incident Response for full documentation.

Semaphore Setup Script

setup-semaphore.sh

Configure Ansible Semaphore with the full lab project.

./scripts/setup-semaphore.sh

Creates 20 task templates, 6 environments, keys, repository, and inventories in Semaphore. Idempotent -- safe to re-run.

See Ansible Semaphore for full documentation.

Home

Getting Started
Architecture
PKI Operations
Security & Compliance
Operations & Testing
Key & HSM Management
Monitoring
Advanced Topics

Clone this wiki locally