dcert

mcp
Guvenlik Denetimi
Uyari
Health Uyari
  • License — License: NOASSERTION
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Low visibility — Only 5 GitHub stars
Code Gecti
  • Code scan — Scanned 12 files during light audit, no dangerous patterns found
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

A Rust CLI and MCP server for X.509 certificate analysis, format conversion, and key verification. Reads certificates from PEM files or HTTPS endpoints. Validates TLS connections, checks revocation status, converts between PFX and PEM formats and integrates with AI-powered IDEs via the Model Context Protocol (MCP) and Vault.

README.md
dcert logo

dcert

TLS Certificate Decoder & Validator

A Rust CLI and MCP server for X.509 certificate analysis, format conversion, and key verification.
Reads certificates from PEM files or HTTPS endpoints. Validates TLS connections, checks revocation status,
converts between PFX and PEM formats, and integrates with AI-powered IDEs via the Model Context Protocol (MCP).

CI/CD Pipeline PyPI version PyPI Downloads Python Rust License: MIT


Table of Contents

Quick Start

# Install via Homebrew
brew tap SCGIS-Wales/homebrew-tap https://github.com/SCGIS-Wales/homebrew-tap.git
brew install dcert

# Analyze a live HTTPS endpoint (bare hostname or full URL)
dcert api.example.com
dcert https://www.google.com

# Read PEM from a pipe
cat certificate.pem | dcert

# Check certificate expiry (CI/CD gate)
dcert https://your-api.com --expiry-warn 30

# Convert PFX to PEM
dcert convert pfx-to-pem client.pfx --password secret --output-dir ./certs

# Verify a private key matches a certificate
dcert verify-key cert.pem --key private.key

# Auto-discover and verify all cert/key pairs in a directory
dcert verify-key

# Create a new CSR with RSA 4096 key
dcert csr create --cn api.example.com --org "My Corp" --country GB

# Validate a CSR for compliance
dcert csr validate my-cert.csr

# Issue a TLS certificate from HashiCorp Vault PKI
dcert vault issue --cn www.example.com --role my-role

# Renew a certificate stored in Vault KV
dcert vault renew secret/certs/www-example-com --role my-role

# Diagnose why an endpoint, mTLS handshake, gateway or proxy is failing
dcert diagnose https://api.example.com

Installation

Homebrew (recommended — macOS and Linux)

Homebrew is the recommended installation method. On Linux it builds from source, which avoids glibc compatibility issues and works on Ubuntu 22.04 and later.

brew tap SCGIS-Wales/homebrew-tap https://github.com/SCGIS-Wales/homebrew-tap.git
brew install dcert

Note: If you don't have Homebrew on Linux, install it first:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Prebuilt binaries

Download from the Releases page. Each release includes dcert (CLI) and dcert-mcp (MCP server). Prebuilt Linux binaries require Ubuntu 22.04 (glibc 2.35) or later.

curl -L https://github.com/SCGIS-Wales/dcert/releases/latest/download/dcert-x86_64-unknown-linux-gnu.tar.gz | tar xz
chmod +x dcert dcert-mcp
sudo mv dcert dcert-mcp /usr/local/bin/

Windows

Install with Chocolatey:

choco install dcert

Or pip install dcert (the win_amd64 wheel bundles dcert.exe and dcert-mcp.exe), or download the dcert-x86_64-pc-windows-msvc.zip archive from the Releases page and add the extracted .exe files to your PATH.

Note: the Windows build links a vendored OpenSSL that has no system trust store. If certificate verification fails because no CA roots are found, set SSL_CERT_FILE to a CA bundle (e.g. one exported from your organization or a cacert.pem).

Build from source

git clone https://github.com/SCGIS-Wales/dcert.git
cd dcert
cargo build --release                                  # dcert CLI
cargo build --release --bin dcert-mcp --features mcp   # MCP server
# Binaries: target/release/dcert and target/release/dcert-mcp

Docker

docker pull ghcr.io/scgis-wales/dcert:main

# CLI
docker run --rm ghcr.io/scgis-wales/dcert:main https://www.google.com

# Local PEM file
docker run --rm -v "$PWD:/data" ghcr.io/scgis-wales/dcert:main /data/cert.pem

# MCP server
docker run --rm -i --entrypoint dcert-mcp ghcr.io/scgis-wales/dcert:main

Commands

dcert uses subcommands to organize its features. The check subcommand is the default and can be omitted:

dcert <targets> [OPTIONS]              # Certificate analysis (default, same as 'dcert check')
dcert csr create [OPTIONS]             # Create a CSR and private key
dcert csr validate <CSR_FILE>          # Validate a CSR for compliance
dcert convert <MODE> [OPTIONS]         # Format conversion (PFX/PEM/keystore/truststore)
dcert verify-key <target> --key <KEY>  # Key-certificate matching (single pair)
dcert diagnose <target> [OPTIONS]      # TLS, mTLS, gateway, CDN and forward proxy diagnostics
dcert kb <list|show|validate|schema>   # Inspect the diagnostics knowledge base
dcert ciphers <list|explain>           # Look up cipher suites in any notation (offline)
dcert tls-scan <target> [OPTIONS]      # Enumerate accepted TLS versions, cipher suites and groups
dcert policy <list|show|schema|test>   # Named TLS security policies (AWS, Mozilla); conformance tests
dcert verify-key [--dir <DIR>]         # Auto-discover and verify all cert/key pairs
dcert vault issue [OPTIONS]            # Issue a TLS certificate from Vault PKI
dcert vault sign [OPTIONS]             # Sign a CSR using Vault PKI
dcert vault revoke [OPTIONS]           # Revoke a certificate in Vault PKI
dcert vault list [OPTIONS]             # List certificates issued by Vault PKI
dcert vault store [OPTIONS] <PATH>     # Store cert+key in Vault KV
dcert vault validate <PATH>            # Validate a certificate in Vault KV
dcert vault renew <PATH> [OPTIONS]     # Renew a certificate in Vault KV

dcert [check] -- Certificate Analysis (default)

Analyze TLS certificates from PEM files or HTTPS endpoints. The check keyword is optional -- dcert https://example.com and dcert check https://example.com are equivalent.

# Fetch and analyze certificates from HTTPS
dcert https://www.google.com

# Bare hostname (auto-prepends https://)
dcert api.example.com

# Analyze a local PEM file
dcert certificate.pem

# Read PEM data from stdin (pipe)
cat certificate.pem | dcert
echo "<base64-pem>" | base64 --decode | dcert
cat certificate.pem | dcert -

# Multiple targets
dcert https://www.google.com https://github.com cert.pem

# Pipe target names from stdin (one per line)
echo -e "https://google.com\nhttps://github.com" | dcert -

# JSON or YAML output
dcert https://example.com --format json
dcert https://example.com --format yaml

# SHA-256 fingerprints and certificate extensions
dcert https://example.com --fingerprint --extensions

# Expiry warning (exit code 1 if expiring within 30 days)
dcert https://example.com --expiry-warn 30

# OCSP revocation check
dcert https://example.com --check-revocation

# Compare certificates between two targets
dcert --diff https://staging.example.com https://prod.example.com

# Monitor certificates every 60 seconds (Ctrl+C stops after the current check)
dcert --watch 60 https://example.com

# Export certificate chain to PEM file
dcert https://www.google.com --export-pem chain.pem

# Export excluding expired certificates
dcert https://www.google.com --export-pem chain.pem --exclude-expired

# Include the chain in the output instead of a file (`pem_data` in JSON and YAML)
dcert https://www.google.com --export-pem - --format json

# STARTTLS takes a bare host, optionally with a port
dcert mail.example.com:587 --starttls smtp

# Sort by expiry date
dcert certificates.pem --sort-expiry asc

# Only show expired certificates
dcert certificates.pem --expired-only

# Compliance report (CA/B Forum Baseline Requirements)
dcert https://example.com --compliance
dcert certificate.pem --compliance

# Compliance report in JSON (for CI/CD)
dcert https://example.com --compliance --format json

Root CA Trust Classification

Every check reports whether the certificate chain anchors to a publicly
trusted
root CA, a private PKI, or is self-signed — answering "is this
issued by a real public CA, or a private/self-signed one?" This runs by default.

# Classification appears in the "Root CA trust" block (pretty) and the
# "root_trust" object (JSON/YAML)
dcert https://www.google.com
dcert https://example.com --format json   # see .root_trust

# Skip it (byte-stable legacy output)
dcert https://example.com --no-trust-check

The classification is one of:

Classification Meaning
publicly_trusted Chain verifies up to a root in the embedded Mozilla/CCADB root set
private_pki Chain terminates in a private (non-public) root CA
self_signed A single self-signed certificate, not issued by any CA
incomplete Chain neither reaches a public root nor presents a self-signed root (an issuer is missing) — try --resolve-issuers

How "publicly trusted" is defined. The authoritative source is the
Mozilla/CCADB root set, embedded at build time via the webpki-root-certs
crate. CCADB is the shared database behind the Mozilla, Microsoft, Apple and
Google root programs, so DigiCert, Amazon/AWS, Google Trust Services, Microsoft
and Apple public TLS roots, GlobalSign, Sectigo, Let's Encrypt, etc. are all
included. Classification is a local cryptographic verification — no network
is used — so it stays fast across 50+ certificates with no per-host timeouts. A
private root that merely shares a Distinguished Name with a public one cannot
produce a false positive, because the signature must validate against an
embedded public key. Certificate expiry is ignored for this verdict (dcert
reports expiry separately).

Each certificate that is itself a recognized public root carries an
is_public_root: true attribute in JSON/YAML (usually absent, since servers
don't send the root).

Optional network probe (--resolve-issuers). For incomplete or
private_pki results you can follow the certificate's AIA "CA Issuers" URLs to
fetch missing issuer certificates — completing the chain (which can flip an
incomplete result to publicly_trusted) and confirming whether a private CA
backend is reachable (private_backend_reachable). It is off by default.

# Complete a chain whose server omitted the intermediate
dcert https://example.com --resolve-issuers

# Keep the timeout short when probing many private CAs
dcert - --resolve-issuers --issuer-timeout 2 < hosts.txt

--resolve-issuers honours the standard forward-proxy environment variables
(http_proxy/https_proxy/no_proxy, see Proxy and Timeout
Configuration
) and uses the short
--issuer-timeout (default 2s) so large batches fail fast. Unlike the OCSP
path, it intentionally does not block private/internal IPs — private-PKI AIA
endpoints legitimately live on internal hosts, which is exactly what this flag
exists to reach. It is gated behind this explicit opt-in.

Refreshing the public root set. --refresh-public-roots fetches the latest
Mozilla/CCADB bundle from https://curl.se/ca/cacert.pem (over the proxy layer)
and unions it into the embedded set for that run, so coverage can stay current
between releases.

TLS Options

# Require TLS 1.3
dcert --min-tls 1.3 https://example.com

# Force TLS 1.2 only
dcert --min-tls 1.2 --max-tls 1.2 https://example.com

# Probe a legacy server: TLS 1.0 and 1.1 are deprecated (RFC 8996) and only
# offered with --allow-legacy-tls, which drops OpenSSL to security level 0
# for this handshake and prints a warning
dcert https://legacy.example.com --allow-legacy-tls
dcert https://legacy.example.com --allow-legacy-tls --min-tls 1.1 --max-tls 1.1

# Offer exactly these suites, in any notation (IANA name, OpenSSL name or
# code point); TLS 1.2 and TLS 1.3 suites may be mixed
dcert https://example.com --cipher 0xC02F --cipher TLS_AES_128_GCM_SHA256
dcert https://example.com --cipher ECDHE-RSA-AES256-GCM-SHA384   # TLS 1.2 only

# Raw OpenSSL cipher strings, passed as is
dcert --cipher-list "ECDHE+AESGCM:CHACHA20" --max-tls 1.2 https://example.com
dcert --cipher-suites "TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" https://example.com

# Post quantum key exchange (RFC 10024 hybrids, OpenSSL 3.5+ on the dcert host).
# Every check reports the negotiated group and classifies it; --pq-probe adds a
# second handshake that offers only the hybrids to answer "does the server
# support post quantum key agreement?" whatever the default handshake chose.
dcert https://example.com --pq-probe
dcert https://example.com --groups "X25519MLKEM768:X25519"
dcert https://example.com --tls-profile modern        # TLS 1.3 only, X25519MLKEM768 first
dcert --version                                       # names the linked OpenSSL and its PQ capability

# HTTP/2 ALPN negotiation
dcert --http-protocol http2 https://example.com

# SNI override
dcert https://10.0.0.1 --sni api.example.com

# Connection overrides — change where dcert dials without changing what it
# validates. Keep the hostname in the URL: it is still used for SNI, the Host
# header and certificate validation. Useful for probing one backend behind a
# load balancer, or a host that does not resolve from here.

# Pin a host/port to an IP address, like curl --resolve.
dcert https://api.example.com --resolve api.example.com:443:10.0.0.5

# Several addresses, tried in order; '*' matches any host on that port.
dcert https://api.example.com --resolve 'api.example.com:443:10.0.0.5,10.0.0.6'
dcert https://api.example.com --resolve '*:443:10.0.0.5'

# Redirect to a different hostname and/or port, like curl --connect-to.
dcert https://api.example.com --connect-to api.example.com:443:origin.internal:8443

# The short form dials one IP for every target.
dcert https://api.example.com --connect-to 10.0.0.5

# Both flags are repeatable and the first matching entry wins.

# Forward proxy for this run only, overriding HTTPS_PROXY/HTTP_PROXY.
dcert https://api.example.com --proxy http://proxy.corp:3128

# Bypass the proxy for specific hosts, or entirely.
dcert https://api.example.com --proxy http://proxy.corp:3128 --noproxy internal.corp
dcert https://api.example.com --noproxy '*'

# Note: --resolve/--connect-to always bypass the proxy — they exist to reach one
# specific endpoint, and going via a proxy would hand that choice back to it.
# The proxy is spoken to in plaintext HTTP CONNECT, so only http:// proxy URLs
# are accepted; an https:// proxy is refused with an explanation.

# Skip TLS verification (self-signed certs)
dcert https://localhost:8443 --no-verify

# Inspect the certificate of a STARTTLS service (SMTP/IMAP/POP3/FTP)
dcert mail.example.com:587 --starttls smtp
dcert imap.example.com:143 --starttls imap

# The negotiated cipher suite is reported in every notation by default
# (pretty: "ECDHE-RSA-AES128-GCM-SHA256 (TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, 0xC02F)";
# JSON/YAML: tls_cipher {openssl, iana, code_point, protocol, forward_secrecy, aead}).
# --cipher-notation iana or openssl reports that name alone, in every format.
dcert https://example.com --cipher-notation iana

mTLS (Mutual TLS)

# Client certificate with PEM files
dcert https://api.internal.com --client-cert client.pem --client-key client-key.pem

# Client certificate with PKCS12/PFX
dcert https://api.internal.com --pkcs12 client.pfx --cert-password secret

# Custom CA bundle (overrides system CAs)
dcert https://internal.server --ca-cert corporate-ca.pem

# Combine mTLS with custom CA
dcert https://api.internal.com --client-cert client.pem --client-key client-key.pem --ca-cert corporate-ca.pem

When the server demands a client certificate and you didn't supply one:

[mTLS REQUIRED] This server requires client certificate authentication.
  Re-run with --client-cert <pem> --client-key <pem>  or  --pkcs12 <p12> --cert-password ...
  The server's certificate chain is shown below for reference.

dcert detects the tlsv13 alert certificate required (and the equivalent legacy alerts), captures the server's certificate chain from inside the TLS handshake — so you can still inspect the server identity even though the handshake aborted — and exits with code 6.

HTTP Options

# Custom headers and method
dcert https://api.example.com --method POST --header "Authorization:Bearer token"

# POST with inline data
dcert https://api.example.com -d '{"key":"value"}' --header "Content-Type:application/json"

# POST with data from file
dcert https://api.example.com --data-file body.json

# Custom timeout
dcert https://slow-server.example.com --timeout 30 --read-timeout 15

Full Options Reference

dcert [check] [OPTIONS] [TARGETS]...

Arguments:
  [TARGETS]...                         PEM file(s), HTTPS URL(s), bare hostnames, or '-' for stdin
                                       Omit targets to read PEM data from a pipe

Options:
  -f, --format <FORMAT>                Output format [pretty, json, yaml] (default: pretty)
      --expired-only                   Show only expired certificates
      --export-pem <PATH|->            Export fetched PEM chain to a file, or - for the output
      --exclude-expired                Exclude expired certs from export
      --sort-expiry <ORDER>            Sort by expiry [asc, desc]
      --method <METHOD>                HTTP method [get, post, head, options] (default: get)
      --header <KEY:VALUE>             Custom HTTP headers (repeatable)
      --headers-file <FILE>            Headers from a file, one Key: Value per line (keeps tokens off the process list)
  -d, --data <DATA>                    Request body (implies POST)
      --data-file <FILE>               Request body from file (implies POST)
      --http-protocol <PROTO>          HTTP protocol [http1-1, http2] (default: http1-1)
      --min-tls <VERSION>              Minimum TLS version [1.0, 1.1, 1.2, 1.3] (1.0 and 1.1 need
                                       --allow-legacy-tls)
      --max-tls <VERSION>              Maximum TLS version [1.0, 1.1, 1.2, 1.3]
      --allow-legacy-tls               Offer TLS 1.0 and 1.1 (RFC 8996 deprecated) at OpenSSL
                                       security level 0; the floor becomes 1.0 unless --min-tls is set
      --cipher <SUITE>                 Offer only this suite, in any notation (IANA, OpenSSL,
                                       0xC02F, C02F, 0xC0,0x2F); repeatable, TLS 1.2 and 1.3 mixed
      --cipher-list <STRING>           Allowed TLS 1.2 ciphers (OpenSSL format, passed as is)
      --cipher-suites <SUITES>         Allowed TLS 1.3 cipher suites (colon-separated, passed as is)
      --cipher-notation <NOTATION>     Report the negotiated suite as [all, iana, openssl]
                                       (default: all; --ciphers is accepted as an alias)
      --groups <GROUPS>                Key exchange groups to offer (OpenSSL group list, e.g.
                                       X25519MLKEM768:X25519; ML-KEM needs OpenSSL 3.5+)
      --tls-profile <PROFILE>          Mozilla client profile [modern, intermediate]
      --pq-probe                       Second handshake offering only the RFC 10024 hybrid
                                       post quantum groups; reports supported / not supported
      --starttls <PROTOCOL>            Upgrade a plaintext connection before TLS
                                       [smtp, imap, pop3, ftp]
      --no-verify                      Disable TLS verification (insecure)
      --timeout <SECONDS>              Connection timeout (default: 10)
      --read-timeout <SECONDS>         Read timeout per read (default: 5); --timeout + --read-timeout also bounds the whole probe
      --sni <HOSTNAME>                 Override SNI hostname
      --resolve <HOST:PORT:ADDRESS>    Pin HOST:PORT to an IP instead of using DNS
                                       (like curl --resolve; repeatable)
      --connect-to <IP|H1:P1:H2:P2>    Redirect the connection to another host/IP
                                       (like curl --connect-to; repeatable)
      --proxy <URL>                    Forward proxy, overrides HTTPS_PROXY/HTTP_PROXY
                                       [env: DCERT_PROXY]
      --noproxy <LIST>                 Hosts bypassing the proxy, overrides NO_PROXY;
                                       '*' bypasses all [env: DCERT_NOPROXY]
      --fingerprint                    Show SHA-256 fingerprints
      --extensions                     Show certificate extensions
      --expiry-warn <DAYS>             Warn if expiring within N days (exit code 1)
      --diff                           Compare certificates between two targets
      --watch <SECONDS>                Re-check at interval
      --compliance                      Run compliance checks (CA/B Forum, DigiCert, X9)
      --check-revocation               Check OCSP revocation status
      --no-trust-check                 Skip root-CA trust classification (on by default)
      --resolve-issuers                Follow AIA "CA Issuers" URLs over the network to
                                       complete a chain / probe a private CA backend (off by default)
      --issuer-timeout <SECONDS>       Short timeout for issuer/refresh fetches (default: 2)
      --refresh-public-roots           Refresh the embedded Mozilla/CCADB root set from
                                       https://curl.se/ca/cacert.pem for this run
      --debug                          Verbose OSI-layer diagnostics on stderr
      --client-cert <PATH>             Client certificate PEM for mTLS
      --client-key <PATH>              Client private key PEM for mTLS
      --pkcs12 <PATH>                  PKCS12/PFX file for mTLS (alternative to --client-cert/--client-key)
      --cert-password <PASS>           PKCS12 password (env: DCERT_CERT_PASSWORD)
      --ca-cert <PATH>                 Custom CA bundle PEM (overrides system CAs)
  -h, --help                           Print help
  -V, --version                        Print version

Exit Codes

Code Meaning
0 Success -- all certificates valid
1 Expiry warning -- certificate(s) expiring within --expiry-warn threshold
2 Error -- connection failure, file not found, or processing error
3 TLS verification failed
4 Certificate expired
5 Certificate revoked (OCSP)
6 Client certificate error (invalid, unreadable, wrong password) — also returned when the server requires mTLS but no --client-cert / --pkcs12 was supplied
7 Key mismatch (private key doesn't match certificate)
8 Revocation check failed -- --check-revocation could not determine the status (responder unreachable, malformed or unverifiable response)

dcert csr -- CSR Creation & Validation

Create PKCS#10 Certificate Signing Requests (CSRs) and validate existing CSRs for compliance with CA/B Forum Baseline Requirements, DigiCert, and X9 standards.

Create a CSR

# RSA 4096 (default) — guided interactive mode (omit --cn)
dcert csr create

# RSA 4096 with subject fields
dcert csr create --cn api.example.com --org "My Corp" --country GB

# ECDSA P-256 (recommended modern) with multiple SANs
dcert csr create --cn www.example.com --key-algo ecdsa-p256 \
  --san DNS:www.example.com --san DNS:example.com --san IP:10.0.0.1

# Encrypted private key
dcert csr create --cn secure.example.com --encrypt-key --key-password "$(read -sp 'Password: ' p && echo $p)"

# Custom output paths and JSON output
dcert csr create --cn api.example.com --csr-out api.csr --key-out api.key --format json

# OU metadata identifiers (for internal/private PKI)
dcert csr create --cn app.internal.corp --ou "AppId:my-service-123" --ou "Team:Platform"

Validate a CSR

# Pretty compliance report
dcert csr validate my-cert.csr

# JSON output (for CI/CD pipelines)
dcert csr validate my-cert.csr --format json

# Treat warnings as errors (--strict is a deprecated alias)
dcert csr validate my-cert.csr --warnings-as-errors

Key Algorithm Options

Algorithm Flag Description
RSA 4096 --key-algo rsa-4096 Default. Strong, widely compatible.
RSA 2048 --key-algo rsa-2048 Minimum accepted by CAs.
ECDSA P-256 --key-algo ecdsa-p256 Recommended modern choice. Faster, equivalent to RSA 3072.
ECDSA P-384 --key-algo ecdsa-p384 High-security requirements.
Ed25519 --key-algo ed25519 Modern EdDSA. Compact signatures, high performance. Requires OpenSSL 3.x.

Compliance Checks

The validator checks against CA/B Forum Baseline Requirements, DigiCert, and X9 standards:

  • Key size: Minimum RSA 2048-bit / ECDSA P-256
  • Signature algorithm: SHA-256+ required, SHA-1 rejected
  • Subject Alternative Names: Required for all modern certificates
  • OU deprecation: Warning for publicly-trusted CAs (CA/B Forum Ballot SC47v2, Sep 2022)
  • Country code: ISO 3166-1 alpha-2 validation
  • CN in SAN: CN should be included in SANs per RFC 6125

Full Options Reference

dcert csr create [OPTIONS]

Options:
      --cn <NAME>          Common Name (FQDN). Omit for interactive mode.
      --org <NAME>         Organization (O)
      --ou <NAME>          Organizational Unit (repeatable, supports metadata e.g., "AppId:xxx")
      --country <CODE>     Two-letter country code (e.g., GB, US)
      --state <NAME>       State or province (ST)
      --locality <NAME>    City or locality (L)
      --email <EMAIL>      Email address
      --san <TYPE:VALUE>   Subject Alternative Name (repeatable, e.g., DNS:www.example.com, IP:10.0.0.1)
      --key-algo <ALGO>    Key algorithm [rsa-4096, rsa-2048, ecdsa-p256, ecdsa-p384, ed25519] (default: rsa-4096)
      --encrypt-key        Encrypt the private key (AES-256-CBC, PKCS#8)
      --key-password <PW>  Password for key encryption (env: DCERT_KEY_PASSWORD)
      --csr-out <FILE>     Output CSR file path (default: <cn>.csr)
      --key-out <FILE>     Output key file path (default: <cn>.key)
  -f, --format <FORMAT>    Output format [pretty, json, yaml] (default: pretty)

dcert csr validate [OPTIONS] <CSR_FILE>

Arguments:
  <CSR_FILE>              PEM-encoded CSR file to validate

Options:
      --warnings-as-errors  Treat warnings as errors (alias: --strict)
  -f, --format <FORMAT>   Output format [pretty, json, yaml] (default: pretty)

dcert convert -- Format Conversion

Convert between certificate formats. Four modes are available:

pfx-to-pem

Extract certificate, key, and CA chain from a PKCS12/PFX file into separate PEM files.

dcert convert pfx-to-pem server.pfx --password secret --output-dir ./certs
# Produces: ./certs/cert.pem, ./certs/key.pem, ./certs/ca.pem (if CA certs present)

pem-to-pfx

Bundle PEM certificate and private key into a PKCS12/PFX file.

dcert convert pem-to-pfx --cert server.pem --key server-key.pem --output server.pfx --password secret

# Include CA chain
dcert convert pem-to-pfx --cert server.pem --key server-key.pem --ca ca-chain.pem --output server.pfx --password secret

create-keystore

Create a PKCS12 keystore from PEM certificate and key (Java-compatible since JDK 9, where PKCS12 is the default keystore type).

dcert convert create-keystore --cert server.pem --key server-key.pem --output keystore.p12 --password changeit --alias myserver

# Print a beginner primer about keystores before creating one (useful when
# handing instructions to external partners)
dcert convert create-keystore --explain --cert server.pem --key server-key.pem --output keystore.p12 --password changeit

dcert warns if the cert PEM contains only a leaf with no intermediates (Java clients usually need the full chain), or if the first cert is a CA rather than the leaf (wrong order).

To convert to JKS format if needed:

keytool -importkeystore -srckeystore keystore.p12 -srcstoretype PKCS12 -destkeystore keystore.jks -deststoretype JKS

create-truststore

Create a PKCS12 truststore from CA certificate PEM files. By default dcert rejects leaf (server) certificates — a truststore should hold trust anchors (CAs), not the server's own cert. The error message points to --allow-non-ca if you really need to override.

# Standard truststore from CA chain
dcert convert create-truststore ca1.pem ca2.pem --output truststore.p12 --password changeit

# Beginner primer (six-line explanation of truststores + CA rotation)
dcert convert create-truststore --explain ca1.pem --output truststore.p12

# Override the leaf-rejection guard (advanced, rarely correct)
dcert convert create-truststore --allow-non-ca cert-with-leaf.pem --output truststore.p12

# Machine-readable JSON output (for scripts and the MCP layer)
dcert convert --format json create-truststore ca1.pem --output truststore.p12

The pretty default output prints a pre-flight table with each cert's role ([ROOT] / [INTERMEDIATE] / [LEAF]), expiry, and SHA-256 fingerprint, plus warnings for duplicates, expired CAs, and CA-rotation cases (two CAs with the same subject CN but different fingerprints).


dcert verify-key -- Key Matching

Verify that a private key matches a certificate. Works with PEM files and HTTPS endpoints. When run without arguments, auto-discovers matching cert/key pairs in the current directory.

# Verify a specific pair
dcert verify-key cert.pem --key private.key

# Verify against an HTTPS endpoint
dcert verify-key https://example.com --key private.key

# Network targets take the same TLS and connection options as check
dcert verify-key https://api.internal --key private.key --ca-cert ca.pem --proxy http://proxy:3128
dcert verify-key mail.example.com:587 --starttls smtp --key private.key

# Auto-discover all cert/key pairs in the current directory
dcert verify-key

# Auto-discover in a specific directory
dcert verify-key --dir /etc/ssl/certs

# JSON output
dcert verify-key cert.pem --key private.key --format json
dcert verify-key --format json

Auto-discovery scans for .crt and .pem files that have a matching .key file with the same base name (e.g. server.crt + server.key, app.pem + app.key). Files without a matching key are skipped.

Returns key type, key size, certificate subject, and whether the key matches. Exit code 7 on mismatch.


dcert vault -- HashiCorp Vault PKI

Issue, sign, revoke, list, store, validate, and renew TLS certificates using HashiCorp Vault's PKI Secrets Engine. Supports interactive wizard mode (omit required args) or fully non-interactive CLI usage.

Prerequisites

Set these environment variables before using vault commands:

Variable Required Description
VAULT_ADDR Yes Vault server URL (e.g., https://vault.example.com:8200)
VAULT_TOKEN No* Vault authentication token (for --auth-method token)
VAULT_CACERT No Custom CA certificate PEM file for Vault TLS
VAULT_CAPATH No Directory of CA PEM files for Vault TLS
VAULT_SKIP_VERIFY No Set to 1 to skip TLS verification (insecure)
SSL_CERT_FILE No Fallback CA cert file (used if VAULT_CACERT is not set)
SSL_CERT_DIR No Fallback CA cert directory (used if VAULT_CAPATH is not set)
DCERT_LDAP_USERNAME / DCERT_LDAP_PASSWORD No Credentials for --auth-method ldap
DCERT_APPROLE_ROLE_ID / DCERT_APPROLE_SECRET_ID No Credentials for --auth-method approle

* Token is discovered in order: VAULT_TOKEN env var, then ~/.vault-token file.

Authentication Methods

By default dcert authenticates with a Vault token. LDAP and AppRole logins are also supported via --auth-method:

# LDAP login (credentials via flags or DCERT_LDAP_USERNAME / DCERT_LDAP_PASSWORD)
dcert vault --auth-method ldap --ldap-username alice issue --cn www.example.com --role my-role

# AppRole login (credentials via flags or DCERT_APPROLE_ROLE_ID / DCERT_APPROLE_SECRET_ID)
dcert vault --auth-method approle \
  --approle-role-id "$ROLE_ID" --approle-secret-id "$SECRET_ID" \
  issue --cn www.example.com --role my-role

TLS configuration: By default, dcert uses your system's native CA store. For corporate Vault servers using internal CAs, set VAULT_CACERT or SSL_CERT_FILE to point to your CA bundle. Use --debug to diagnose TLS issues:

# Use a custom CA certificate
export VAULT_CACERT=/path/to/corporate-ca.pem
dcert vault issue --cn www.example.com --role my-role

# Or via CLI flag
dcert vault --vault-cacert /path/to/ca.pem issue --cn www.example.com --role my-role

# Debug TLS connectivity issues
dcert vault --debug issue --cn www.example.com --role my-role

# Skip TLS verification (insecure, for testing only)
dcert vault --skip-verify issue --cn www.example.com --role my-role

Role Discovery

If --role is not provided, dcert looks up your token's policies (vault token lookup-self) and extracts role names from policies that follow a dotted naming convention (prefix.rolename.permission). The second segment is used as the role name. If multiple roles are found, you are prompted to select one.

Issue a Certificate

Vault generates a new private key and certificate via the PKI engine.

# Interactive wizard (guided step-by-step)
dcert vault issue

# Non-interactive with all options
dcert vault issue --cn www.example.com --role my-role \
  --san "DNS:*.example.com" --ip-san 10.0.0.1 --ttl 8760h

# Output as PFX instead of PEM
dcert vault issue --cn www.example.com --role my-role --pfx-password secret

# Issue and store in Vault KV
dcert vault issue --cn www.example.com --role my-role \
  --store-path secret/company/project/certs/www-example-com

# Custom PKI mount point
dcert vault issue --cn www.example.com --role my-role --mount pki_intermediate

Sign a CSR

Submit an existing CSR to Vault PKI for signing (no private key is generated).

# Interactive wizard
dcert vault sign

# Non-interactive
dcert vault sign --csr-file server.csr --role my-role --ttl 8760h

# Override CN from CSR
dcert vault sign --csr-file server.csr --role my-role --cn override.example.com

# Sign with IP SANs
dcert vault sign --csr-file server.csr --role my-role --ip-san 10.0.0.1 --ip-san 192.168.1.1

Revoke a Certificate

# Revoke by serial number
dcert vault revoke --serial "1a:2b:3c:4d:5e"

# Revoke by PEM certificate file
dcert vault revoke --cert-file server.crt

List Certificates

# List all issued certificates (serial numbers only)
dcert vault list

# Fetch and display details for each certificate
dcert vault list --show-details

# Filter by status
dcert vault list --show-details --expired-only
dcert vault list --show-details --valid-only

# Export to JSON, CSV, or Excel
dcert vault list --show-details --export certs.json
dcert vault list --show-details --export certs.csv
dcert vault list --show-details --export certs.xlsx

# JSON output
dcert vault list --show-details --format json

Store in Vault KV

Store a local certificate and private key in Vault KV (v1 by default, v2 with --kv-version 2).

dcert vault store --cert-file server.crt --key-file server.key \
  secret/company/project/certs/www-example-com

# Use KV v2
dcert vault store --cert-file server.crt --key-file server.key \
  --kv-version 2 secret/company/project/certs/www-example-com

# Custom key names in KV
dcert vault store --cert-file server.crt --key-file server.key \
  --cert-key tls_cert --key-key tls_key \
  secret/company/project/certs/www-example-com

Validate from Vault KV

Read a certificate and key from Vault KV, validate them, and display certificate details (same output as dcert check). Also verifies the private key matches the certificate.

dcert vault validate secret/company/project/certs/www-example-com

# Custom key names
dcert vault validate secret/company/project/certs/www-example-com \
  --cert-key tls_cert --key-key tls_key

# JSON output
dcert vault validate secret/company/project/certs/www-example-com --format json

Renew a Certificate

Read an existing certificate from Vault KV, extract its CN and SANs, issue a new certificate with the same parameters, and overwrite the KV entry. Optionally override SANs or IP SANs.

dcert vault renew secret/company/project/certs/www-example-com --role my-role

# Custom TTL and mount
dcert vault renew secret/company/project/certs/www-example-com \
  --role my-role --ttl 2160h --mount pki_intermediate

# Override SANs on renew
dcert vault renew secret/company/project/certs/www-example-com --role my-role \
  --san app.example.com --ip-san 10.0.0.1

Permission Errors

All Vault API calls produce clear, actionable error messages on permission denial:

Error: Permission denied by Vault.

  Endpoint: POST vault_intermediate/issue/my-role
  Required: create capability on "vault_intermediate/issue/my-role"

  Ask your Vault administrator to add this policy to your token:
    path "vault_intermediate/issue/my-role" {
      capabilities = ["create"]
    }

Full Options Reference

dcert vault [GLOBAL OPTIONS] <SUBCOMMAND> [OPTIONS]

Global Vault Options:
      --skip-verify              Skip TLS verification (insecure). Also: VAULT_SKIP_VERIFY=1
      --vault-cacert <PATH>      Custom CA certificate PEM file. Also: VAULT_CACERT env var
      --auth-method <METHOD>     Vault auth method [token, ldap, approle] (default: token)
      --ldap-username <USER>     LDAP username (env: DCERT_LDAP_USERNAME)
      --ldap-password <PASS>     LDAP password (env: DCERT_LDAP_PASSWORD)
      --ldap-mount <MOUNT>       LDAP auth mount (default: ldap)
      --approle-role-id <ID>     AppRole role ID (env: DCERT_APPROLE_ROLE_ID)
      --approle-secret-id <ID>   AppRole secret ID (env: DCERT_APPROLE_SECRET_ID)
      --approle-mount <MOUNT>    AppRole auth mount (default: approle)
      --debug                    Show verbose TLS and API diagnostics

dcert vault issue [OPTIONS]
      --cn <NAME>           Common Name. Omit for interactive wizard.
      --san <SAN>           Subject Alternative Names (repeatable)
      --ip-san <IP>         IP SANs (repeatable)
      --ttl <TTL>           Certificate TTL (default: 8760h)
      --role <ROLE>         Vault PKI role name
      --mount <MOUNT>       Vault PKI mount point (default: vault_intermediate)
      --output <NAME>       Output file base name (default: sanitised CN)
  -f, --format <FORMAT>     Output format [pretty, json, yaml]
      --pfx-password <PW>   Output as PFX instead of PEM (env: DCERT_CERT_PASSWORD)
      --store-path <PATH>   Store cert+key in Vault KV after issuance
      --kv-version <1|2>    Vault KV version for --store-path (default: 1)

dcert vault sign [OPTIONS]
      --csr-file <FILE>     CSR PEM file. Omit for interactive wizard.
      --cn <NAME>           Override CN from CSR
      --san <SAN>           Additional SANs (repeatable)
      --ip-san <IP>         IP SANs (repeatable)
      --ttl <TTL>           Certificate TTL (default: 8760h)
      --role <ROLE>         Vault PKI role name
      --mount <MOUNT>       PKI mount point (default: vault_intermediate)
      --output <NAME>       Output file base name
  -f, --format <FORMAT>     Output format [pretty, json, yaml]
      --pfx-password <PW>   Output as PFX instead of PEM (env: DCERT_CERT_PASSWORD)
      --store-path <PATH>   Store certificate in Vault KV after signing
      --kv-version <1|2>    Vault KV version for --store-path (default: 1)

dcert vault revoke [OPTIONS]
      --serial <SERIAL>     Certificate serial number (hex, colon or hyphen-separated)
      --cert-file <FILE>    PEM certificate file to revoke
      --mount <MOUNT>       PKI mount point (default: vault_intermediate)

dcert vault list [OPTIONS]
      --mount <MOUNT>       PKI mount point (default: vault_intermediate)
  -f, --format <FORMAT>     Output format [pretty, json, yaml]
      --show-details        Fetch details for each certificate
      --expired-only        Show only expired certificates
      --valid-only          Show only valid certificates
      --export <FILE>       Export to JSON, CSV, or XLSX file

dcert vault store [OPTIONS] <PATH>
      --cert-file <FILE>    Local PEM certificate file (required)
      --key-file <FILE>     Local PEM private key file (required)
      --cert-key <NAME>     KV key name for certificate (default: cert)
      --key-key <NAME>      KV key name for private key (default: key)
      --kv-version <1|2>    Vault KV version (default: 1)

dcert vault validate [OPTIONS] <PATH>
      --cert-key <NAME>     KV key name for certificate (default: cert)
      --key-key <NAME>      KV key name for private key (default: key)
      --kv-version <1|2>    Vault KV version (default: 1)
  -f, --format <FORMAT>     Output format [pretty, json, yaml]

dcert vault renew [OPTIONS] <PATH>
      --role <ROLE>         PKI role name for issuing new certificate
      --mount <MOUNT>       PKI mount point (default: vault_intermediate)
      --ttl <TTL>           TTL for new certificate (default: 8760h)
      --cert-key <NAME>     KV key name for certificate (default: cert)
      --key-key <NAME>      KV key name for private key (default: key)
      --kv-version <1|2>    Vault KV version (default: 1)
      --san <SAN>           Override SANs from existing cert (repeatable)
      --ip-san <IP>         Override IP SANs from existing cert (repeatable)
  -f, --format <FORMAT>     Output format [pretty, json, yaml]

dcert diagnose -- TLS, mTLS, Gateway, CDN and Proxy Diagnostics

dcert diagnose probes a target the way dcert check does, then explains why it failed and what the response means. It captures the TLS handshake, the certificate chain and its trust anchor, the HTTP status, response headers and a bounded body excerpt, plus the forward-proxy CONNECT reply and the local proxy environment, and scores that evidence against a knowledge base of failure signatures.

# Explain a failing endpoint
dcert diagnose https://api.example.com

# Machine-readable, for a CI gate or a ticket
dcert diagnose https://api.example.com --format json

# Probe an mTLS endpoint with a client identity
dcert diagnose https://api.example.com --client-cert client.pem --key client.key

# Probe a specific origin behind the distribution
dcert diagnose https://api.example.com --connect-to origin.internal:8443

Findings are reported earliest layer first, so the primary attribution names the hop that actually failed:

Layer What it covers
Local proxy environment HTTP_PROXY set without HTTPS_PROXY, unreachable proxy, TLS spoken to a plain proxy port
Proxy CONNECT 407 authentication, 403 policy denial, 5xx upstream failure (including X-Squid-Error), CONNECT not supported, captive portal
TLS handshake No common protocol version or cipher, SNI not served, incomplete chain, retired intermediates and distrusted roots; on AWS: CloudFront's default *.cloudfront.net certificate, incomplete chain, a CloudFront or API Gateway security policy refusing the offered TLS version, an expired certificate still served by an edge after an ACM renewal
Client certificate (mTLS) Any server: client certificate required but absent (TLS 1.2 and 1.3), requested optionally and then refused at HTTP, configured but never requested, unknown CA, expired, or rejected after validation; nginx 400 No required SSL certificate was sent and The SSL certificate error; CloudFront viewer mTLS specifics (OCSP, Connection Function, chain depth) when the endpoint is on AWS
TLS interception Chain re-signed by a known inspection product (Zscaler, Netskope, Umbrella, FortiGate, Palo Alto, Blue Coat, Forcepoint and others), or a public hostname anchored to a private root
CloudFront edge Alternate domain not configured, AWS WAF block, geo restriction, HTTP method not allowed, URL or header size limits (414, 494), missing or invalid signed URL, origin DNS failure, origin TLS failure, origin timeout, Lambda@Edge and CloudFront Functions errors, capacity, edge 503 from an edge function or the origin mTLS pause
API gateway Apigee runtime faults (target TLS handshake failure, unreachable target, target timeout, unexpected EOF, policy faults), Envoy and Istio upstream errors (upstream TLS failure, connect error, no healthy upstream), and Amazon API Gateway responses told apart by x-amzn-ErrorType and the message: Missing Authentication Token (no matching resource, stage or mapping), Forbidden (API key, WAF, private DNS, base path mapping, disabled default endpoint), Forbidden on a mutual TLS custom domain when a client certificate was sent, AccessDenied (IAM, resource policy, Lambda authorizer), SigV4 signature errors, Unauthorized, throttling and quota (429), request too large (413), unsupported media type (415), request validation (400), internal server error and configuration errors (500), bad gateway (502), integration timeout (504), backend unavailable (503)
Origin S3 access denied or missing key, any origin status forwarded by the edge, origin mTLS not enabled on the distribution

mTLS detection and platform scoping

dcert registers an OpenSSL certificate callback, so it knows whenever the server sends a CertificateRequest, independently of alert wording and TLS version. That matters for TLS 1.3, where a server that requires a client certificate completes the handshake and only then sends certificate_required: dcert reports it as mTLS required (exit code 6, [mTLS REQUIRED] banner, captured server chain) instead of an empty HTTP response. The connection object in JSON (and the MCP tools) carries:

Field Meaning
client_auth not_requested, optional (asked, connection accepted without one), required (refused without one) or presented (asked, and the configured certificate was sent)
acceptable_client_cas CA names the server listed in its CertificateRequest; empty when it sent none
client_auth_required true for required, kept for existing callers

Vendor specific advice is scoped by platform. Before scoring, dcert fingerprints the products on the path from headers, body, host and chain (aws_cloudfront, aws_api_gateway, aws, apigee, envoy, nginx, google_cloud) and prints them as a Platform: line (platforms in JSON). CloudFront and API Gateway entries require their platform, so an mTLS refusal from Apigee hybrid, Envoy or nginx gets vendor neutral advice and no AWS links. When Apigee relays an AWS backend's x-amzn-* headers, the API Gateway finding is attributed to the origin. Knowledge base entries can use the same gate with a platform signal:

signals:
  - type: platform
    any_of: [apigee]
    required: true

Each finding carries a confidence figure, the evidence that matched, remediation steps and a link to the authoritative documentation:

=== Diagnosis ===
PRIMARY   CloudFront could not complete TLS with the origin [cloudfront.edge.origin-tls-failure] (CloudFront edge, 95% confidence)
    CloudFront reached the origin but the TLS negotiation failed or the origin closed the
    connection. ...
    Evidence:
      - HTTP status 502
      - body contains "attempted to establish a connection with the origin, ..."
      - header x-cache: Error from cloudfront
    Next steps:
      - Probe the origin directly with dcert, using --connect-to if its DNS name differs, ...

Under the diagnosis, a Context section explains the response itself from the reference knowledge base: what the status code means for the service that produced it (and whether the edge or the origin usually generates it), what each recognised header says (X-Cache, Via, X-Amz-Cf-Pop, X-Amz-Cf-Id, x-amzn-ErrorType, x-amz-apigw-id and others), and what the canonical error sentences in the body mean. Notes are only produced when a CloudFront or API Gateway fingerprint is present, so probes of unrelated hosts stay quiet:

=== Context ===
  status 502 [cloudfront]
      Bad Gateway: CloudFront could not obtain a usable response from the origin. ...
      (usually generated at the edge)
  body   wasn't able to resolve the origin domain name [cloudfront]
      NonS3OriginDnsError. The origin domain does not resolve in public DNS. ...
  header X-Cache: Error from cloudfront [cloudfront]
      ... CloudFront generated the error itself; the origin did not produce this status.

The same diagnosis and context arrays are added to dcert check output in every format, so existing checks gain the explanation without changing command. Pass --no-diagnose to skip both.

Related options

Option Description
--body-limit <BYTES> Response body bytes captured for diagnostics (default 16384, 0 disables)
--show-body Include the captured body excerpt in output even when no finding cites it
--no-diagnose Skip the diagnostics pass entirely
--kb-file <PATH> Merge an extra knowledge base file over the built-in one (also DCERT_KB_FILE)

The body excerpt is treated as evidence, not output: it is emitted only when a finding cites it or --show-body is set.

dcert kb -- Diagnostics and Reference Knowledge Bases

dcert ships two knowledge bases, both data rather than code, compiled from the AWS documentation and the AWS Knowledge Center (every page consulted is listed in kb/SOURCES.md):

  • Diagnostics (kb/diagnostics.yaml): failure signatures scored against the evidence of a probe. A versioned YAML catalogue embedded at build time and extendable at runtime, so a team can add its own signatures without waiting for a release.
  • Reference (kb/reference.yaml): what CloudFront and API Gateway responses mean. Every status code each service returns with its causes and checks, every response header they add or rewrite (including the CloudFront-Viewer-* and mTLS headers), the canonical error sentences of their error pages, all 167 CloudFront and 33 API Gateway control plane exceptions and gateway response types, and longer topics on viewer mTLS (required, optional and passthrough modes, trust stores, OCSP and Connection Functions), origin mTLS, security policies and ciphers, error caching, limits, signed URLs, S3 origins, API Gateway mutual TLS, endpoint types and private APIs.
dcert kb list                                   # every diagnostics entry: id, layer, title
dcert kb show cloudfront.edge.waf-blocked       # one entry in full
dcert kb validate my-entries.yaml               # schema, unique ids, regex check
dcert kb schema > schema.json                   # JSON schema for diagnostics files
dcert kb schema --reference > reference.json    # JSON schema for the reference base

dcert kb explain 502                            # what a 502 means on CloudFront and on API Gateway
dcert kb explain x-cache                        # a header and the meaning of each value
dcert kb explain x-amzn-errortype               # the API Gateway error type table
dcert kb explain InvalidViewerCertificate       # a control plane exception
dcert kb explain passthrough                    # topics: viewer mTLS modes, origin mTLS, truststore, limits...
dcert kb explain 403 --service api_gateway      # restrict to one service; --format json for tooling
dcert kb topics                                 # what can be looked up, per service

# Use extra diagnostics entries for a single run, or export DCERT_KB_FILE
dcert diagnose https://api.example.com --kb-file my-entries.yaml

An entry declares weighted signals over the captured evidence, the root cause, remediation steps and references. An entry whose id matches a built-in one replaces it:

version: 1
entries:
  - id: org.edge.custom-block-page
    title: Blocked by the corporate edge
    layer: edge_http
    category: cloudfront
    weight: 0.95
    signals:
      - type: status
        codes: [403]
        required: true
      - type: body
        pattern: '(?i)blocked by acme security'
        required: true
        weight: 3
    root_cause: >
      The corporate edge returned its block page rather than forwarding the request.
    remediation:
      - Raise a request to allow list the destination.
    references:
      - https://intranet.example.com/edge-policy

dcert ciphers -- Cipher Suite Lookup

One table of the IANA TLS Cipher Suites registry, offline: code point, IANA
and OpenSSL names, protocol family, key exchange, authentication, encryption,
MAC, the AEAD, forward secrecy, export, NULL, anonymous and FIPS flags, the
IANA recommended or discouraged status, and whether the linked OpenSSL can
offer the suite. Every notation names the same record:

dcert ciphers explain C02F
dcert ciphers explain TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
dcert ciphers explain ECDHE-RSA-AES128-GCM-SHA256 -f json

dcert ciphers list --protocol 1.3            # TLS 1.3 suites
dcert ciphers list --offerable -f json       # what this build can offer

A misspelt name is an error that suggests the nearest known names.

dcert tls-scan -- Version, Cipher and Group Enumeration

Asks the server, one handshake at a time, what it accepts: each protocol
version on its own, then every cipher suite the linked OpenSSL can offer for
each accepted version, then each key exchange group (post quantum hybrids,
pure ML-KEM, classical curves and finite field groups) at the newest
accepted version. Each handshake records the suite in every notation, the
group, the leaf key type (RSA 2048, EC prime256v1) and the alert on
rejection, so a server with RSA and ECDSA certificates shows which suites
each key serves.

dcert tls-scan example.com
dcert tls-scan example.com -f json --max-handshakes 300
dcert tls-scan legacy.example.com --allow-legacy-tls        # adds TLS 1.0 and 1.1
dcert tls-scan mail.example.com:587 --starttls smtp
dcert tls-scan api.example.com --resolve api.example.com:443:10.0.0.5

Handshakes run four at a time and stop at --max-handshakes (default 120);
the report says when the budget ran out. Certificate verification is
skipped, since the question is what the server negotiates. The exit code is
0 when at least one version was accepted and 2 when none was.

dcert policy -- TLS Security Policy Catalogue

A catalogue of named TLS security policies, generated from the published
pages: every Application and Network Load Balancer ELBSecurityPolicy-*
(including the thirteen post quantum policies), the CloudFront viewer
policies, the API Gateway policies for Regional, private and edge-optimized
endpoints, and Mozilla's modern and intermediate configurations. Each entry
lists protocols, TLS 1.3 suites and TLS 1.2 ciphers (by IANA name), the key
exchange groups where the provider names them, FIPS and post quantum flags,
where the provider applies it by default, and the source page with its
retrieval date.

dcert policy list --provider aws_alb
dcert policy show ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09 --provider aws_alb
dcert policy show TLSv1.2_2021 -f json
dcert policy schema > tls_policies.schema.json

ALB and NLB publish policies of the same names; show lists every match
unless --provider picks one. API Gateway's edge-optimized TLS_1_0 and
TLS_1_2 differ from the Regional ones and are catalogued as TLS_1_0/edge
and TLS_1_2/edge. Sources are listed in kb/SOURCES.md.

Testing an endpoint against a policy

dcert policy test answers "does this endpoint behave exactly like policy
X?" with bounded handshakes, four at a time:

  1. Discovery: the default handshake and two more offering only RSA or only
    ECDSA suites, to learn which certificate key types the listener holds.
  2. Each protocol version alone: accepted exactly when the policy lists it.
  3. Each TLS 1.2 cipher of the policy alone: accepted, with that cipher
    negotiated. Every other catalogued TLS 1.2 cipher: refused.
  4. Each TLS 1.3 suite of the policy alone: accepted. Every other suite the
    linked OpenSSL implements: refused.
  5. Each group of the policy alone, X25519 alone for post quantum policies
    (the classical fallback), and the RFC 10024 hybrids alone for the others
    (refused).

Each check is pass, fail, not_testable (ML-KEM groups on OpenSSL older
than 3.5, TLS 1.0 and 1.1 without --allow-legacy-tls) or not_applicable
(an ECDSA cipher on a listener with only an RSA certificate). The verdict is
conformant, non_conformant (deviations listed first, suites in every
notation) or inconclusive.

dcert policy test alb.example.com --policy ELBSecurityPolicy-TLS13-1-2-Res-PQ-2025-09
dcert policy test alb.example.com --policy ELBSecurityPolicy-TLS13-1-3-PQ-2025-09 --versions 1.3 -f json
dcert policy test alb.example.com --identify            # rank every catalogued policy
dcert policy test old.example.com --policy ELBSecurityPolicy-2016-08 --allow-legacy-tls --strict

Exit codes: 0 conformant (or inconclusive without --strict), 9 non
conformant, 10 inconclusive with --strict, 2 when no version is accepted.
STARTTLS, --resolve, --connect-to, proxies, timeouts and the mTLS client
certificate flags apply to every handshake.


MCP Server (AI IDE Integration)

dcert-mcp is a Model Context Protocol server that exposes dcert's capabilities as tools for AI-powered IDEs. It supports two transport modes: stdio (default, for IDE integration) and HTTP (for remote deployment with optional OIDC/OAuth2 authentication).

It implements the current MCP specification revision (2025-11-25) via the rmcp SDK. Both transports are served by the SDK, so the HTTP transport exposes the same tools, schemas, session handling and protocol negotiation as stdio.

Tools

Tool Description
analyze_certificate Decode and analyze TLS certificates. Returns subject, issuer, SANs, validity, fingerprints, extensions, TLS connection info, and OSI-layer diagnostics. Supports mTLS.
check_expiry Check if certificates expire within N days. Returns ALL_VALID, EXPIRING_SOON, or ALREADY_EXPIRED. Supports mTLS.
check_revocation Check OCSP revocation status via the certificate's OCSP responder. Supports mTLS.
compare_certificates Compare certificates between two targets side-by-side.
tls_connection_info Get TLS connection details: protocol, cipher, ALPN, latency, verification, diagnostics. Supports mTLS.
export_pem Export TLS certificate chain from an HTTPS endpoint as PEM. Saves to output_path, or returns the chain as pem_data in the JSON when no path is given. Can exclude expired certs. Supports mTLS.
create_csr Create a PKCS#10 CSR and private key. Supports RSA/ECDSA, OU metadata, and encrypted keys. Compliant with CA/B Forum, DigiCert, and X9 standards.
validate_csr Validate a CSR for compliance with CA/B Forum Baseline Requirements, DigiCert, and X9 standards. Returns findings with severity levels.
diagnose_endpoint Diagnose why an endpoint fails: TLS and mTLS on any server, Apigee, Envoy/Istio and nginx errors, CloudFront edge and origin errors, API Gateway gateway responses, forward proxy failures and TLS interception. Returns findings ordered earliest layer first with confidence, evidence and remediation, the platforms the probe fingerprinted, and context notes explaining CloudFront and API Gateway responses.
tls_scan Enumerate the TLS versions, cipher suites (with leaf key type) and key exchange groups a server accepts, one handshake at a time within a handshake budget.
tls_policy_test Test an endpoint against a catalogued TLS security policy, check by check, or rank every policy by match (identify). Verdict conformant, non_conformant or inconclusive. Supports mTLS.
list_tls_policies List the catalogued TLS security policies (AWS load balancers, CloudFront, API Gateway, Mozilla), filtered by provider. No network access.
show_tls_policy Show one catalogued policy: protocols, suites, groups, flags, defaults and source. No network access.
list_cipher_suites List TLS cipher suites from the IANA registry with every notation and property; filter by protocol family or by what the linked OpenSSL can offer. No network access.
explain_cipher_suite Explain one cipher suite given as an IANA name, OpenSSL name or code point. No network access.
explain_edge_term Look up what a CloudFront or API Gateway status code, header, error name, gateway response type or topic (viewer mTLS modes, origin mTLS, truststores, security policies, limits) means, from the built-in reference knowledge base. No network access.
validate_certificate Run compliance checks on a certificate (PEM file or HTTPS endpoint). Checks key size, signature algorithm, validity period (SC-081v3 schedule), revocation pointers (SC-063v4), SANs, CT, EKU, and Basic Constraints against CA/B Forum standards.
verify_key_match Verify that a private key matches a certificate (PEM file or HTTPS endpoint).
verify_key_auto_discover Auto-discover and verify all matching cert/key pairs in a directory.
convert_pfx_to_pem Convert PKCS12/PFX to separate PEM files (cert, key, CA chain).
convert_pem_to_pfx Convert PEM certificate + key to PKCS12/PFX file.
create_keystore Create a PKCS12 keystore from PEM cert + key (Java-compatible).
create_truststore Create a PKCS12 truststore from CA certificate PEM files. Leaf certificates are refused unless allow_non_ca is true (same default as the CLI).
vault_issue Issue a TLS certificate from HashiCorp Vault PKI.
vault_sign Sign a CSR using Vault PKI.
vault_revoke Revoke a certificate in Vault PKI (by serial or PEM file).
vault_list List certificates issued by Vault PKI, optionally with details.
vault_store Store a certificate + key in Vault KV (v1 or v2).
vault_validate Read and validate a certificate + key from Vault KV.
vault_renew Renew a certificate stored in Vault KV.

Configuration

Claude Code / Kiro / Kiro CLI

These tools use the same mcpServers configuration format. Create the config file at the appropriate location:

Tool Project config Global config
Claude Code .mcp.json ~/.claude/settings/mcp.json
Kiro (IDE) .kiro/settings/mcp.json ~/.kiro/settings/mcp.json
Kiro CLI .kiro/settings/mcp.json ~/.kiro/settings/mcp.json
{
  "mcpServers": {
    "dcert": {
      "type": "stdio",
      "command": "dcert-mcp"
    }
  }
}

Or add via Claude Code CLI:

claude mcp add dcert -- dcert-mcp

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "dcert": {
      "type": "stdio",
      "command": "dcert-mcp"
    }
  }
}

JetBrains IDEs

For JetBrains IDEs 2025.2+: Go to Settings > Tools > AI Assistant > Model Context Protocol (MCP), click +, choose "As JSON", and paste:

{
  "mcpServers": {
    "dcert": {
      "type": "stdio",
      "command": "dcert-mcp"
    }
  }
}

For earlier versions, install the MCP Server plugin first.

Docker-based MCP

Use the Docker image if dcert-mcp is not installed locally:

{
  "mcpServers": {
    "dcert": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "--rm", "-i", "--entrypoint", "dcert-mcp", "ghcr.io/scgis-wales/dcert:main"]
    }
  }
}

Custom binary path

If dcert-mcp is not on your PATH, specify the full path. You can also set DCERT_PATH to tell the MCP server where to find the dcert CLI:

{
  "mcpServers": {
    "dcert": {
      "type": "stdio",
      "command": "/usr/local/bin/dcert-mcp",
      "env": {
        "DCERT_PATH": "/usr/local/bin/dcert"
      }
    }
  }
}

Proxy and Timeout Configuration

In corporate environments behind forward proxies, dcert-mcp inherits proxy settings from the environment. The subprocess (dcert) automatically receives all parent environment variables including proxy and SSL settings.

Proxy environment variables

Variable Description
DCERT_PROXY Forward proxy URL; takes precedence over the variables below (equivalent to --proxy)
DCERT_NOPROXY Proxy bypass list; takes precedence over NO_PROXY (equivalent to --noproxy)
HTTPS_PROXY / https_proxy Forward proxy URL for HTTPS connections
HTTP_PROXY / http_proxy Forward proxy URL for plain HTTP connections. Never used for HTTPS on its own; set HTTPS_PROXY or ALL_PROXY for that
ALL_PROXY / all_proxy Forward proxy URL for every scheme when no scheme specific variable is set
NO_PROXY / no_proxy Comma-separated list of hosts to bypass the proxy
SSL_CERT_FILE Custom CA certificate file for proxy TLS interception
SSL_CERT_DIR Custom CA certificate directory

Per-request proxy and connection overrides

The environment settles proxying for the whole server process. To override it for
a single tool call, the certificate-analysis tools (analyze_certificate,
check_expiry, check_revocation, tls_connection_info, export_pem) accept:

Parameter Description
proxy Forward proxy URL for this request, overriding the inherited environment. "" forces a direct connection.
noproxy Comma-separated bypass list, overriding NO_PROXY. "*" bypasses the proxy entirely.
connect_to Redirect the connection: a bare IP, or "HOST1:PORT1:HOST2:PORT2" to redirect to another hostname/port. A single string or a list.
resolve Pin "HOST:PORT:ADDRESS" to specific IP addresses instead of using DNS. IPs only — use connect_to for a hostname. A single string or a list.
groups Key exchange groups to offer as an OpenSSL group list, e.g. "X25519MLKEM768:X25519" (ML-KEM needs OpenSSL 3.5+ on the dcert host).
tls_profile "modern" (TLS 1.3 only) or "intermediate" (TLS 1.2 and 1.3), the Mozilla configurator v6 client profiles.
pq_probe true runs a second handshake offering only the RFC 10024 hybrid groups; the verdict is returned as post_quantum_probe.

The hostname in target still drives SNI, the Host header and certificate
validation, so connect_to/resolve probe a specific backend without weakening
what gets verified. Both always bypass the proxy. proxy and noproxy reach the
dcert subprocess as DCERT_PROXY/DCERT_NOPROXY environment variables rather
than command-line arguments, so a proxy URL carrying credentials does not appear
in the process list.

{
  "target": "https://api.example.com",
  "connect_to": "api.example.com:443:origin.internal:8443",
  "noproxy": "*"
}

Example configuration with a corporate proxy:

{
  "mcpServers": {
    "dcert": {
      "type": "stdio",
      "command": "dcert-mcp",
      "env": {
        "HTTPS_PROXY": "http://proxy.corp.com:8080",
        "NO_PROXY": "localhost,127.0.0.1,.internal.corp.com",
        "SSL_CERT_FILE": "/etc/ssl/certs/corporate-ca.pem"
      }
    }
  }
}

Timeout settings

dcert-mcp supports configurable timeouts via CLI flags or environment variables:

Setting CLI flag Environment variable Default Description
Subprocess timeout --timeout DCERT_MCP_TIMEOUT 60s Max time for a single dcert invocation
Connection timeout --connection-timeout DCERT_MCP_CONNECTION_TIMEOUT 10s TCP connection timeout (passed to dcert)
Read timeout --read-timeout DCERT_MCP_READ_TIMEOUT 5s Response read timeout (passed to dcert)

Example with extended timeouts for slow networks:

{
  "mcpServers": {
    "dcert": {
      "type": "stdio",
      "command": "dcert-mcp",
      "env": {
        "DCERT_MCP_TIMEOUT": "120",
        "DCERT_MCP_CONNECTION_TIMEOUT": "30",
        "DCERT_MCP_READ_TIMEOUT": "15"
      }
    }
  }
}

Troubleshooting

Startup diagnostics

dcert-mcp logs diagnostic information to stderr at startup. In MCP mode, stderr is separate from the protocol channel (which uses stdio), so these logs are visible in your IDE's MCP server output or logs:

[dcert-mcp] v3.0.12
[dcert-mcp] dcert binary: /usr/local/bin/dcert
[dcert-mcp] subprocess timeout: 60s
[dcert-mcp] connection timeout: 10s (--timeout)
[dcert-mcp] read timeout: 5s (--read-timeout)
[dcert-mcp] HTTPS proxy: http://proxy.corp.com:8080
[dcert-mcp] HTTP proxy: (none)
[dcert-mcp] NO_PROXY: localhost,127.0.0.1

Proxy URLs are logged with passwords masked (shown as ****).

Common issues

MCP server hangs or times out silently

This often happens behind corporate proxies. Check:

  1. Verify proxy settings are passed to dcert-mcp via the MCP config env block
  2. Check the startup diagnostics show the expected proxy URL
  3. Increase DCERT_MCP_TIMEOUT if the proxy is slow
  4. If the target is internal, add it to NO_PROXY
  5. If TLS interception is used, set SSL_CERT_FILE to the corporate CA bundle

dcert binary not found

If the startup log shows a warning about the dcert binary not being found:

  1. Ensure dcert is on your PATH, or
  2. Set DCERT_PATH to the full path in the MCP config env block

Timeout errors with diagnostic hints

When a subprocess times out, dcert-mcp produces actionable error messages that include:

  • The timeout duration
  • Detected proxy configuration
  • Suggestions for adjusting timeout environment variables
  • Hints about DNS, connectivity, or proxy issues

HTTP Transport Mode

For remote or multi-user deployments, dcert-mcp can run as an HTTP server:

# Start in HTTP mode (no auth)
dcert-mcp --mode http --addr 0.0.0.0:3000

# With OIDC/OAuth2 authentication
DCERT_MCP_OIDC_ISSUER="https://login.example.com/v2.0" \
DCERT_MCP_OIDC_AUDIENCE="api://dcert-mcp" \
dcert-mcp --mode http --addr 0.0.0.0:3000

# With static bearer token (simpler deployments)
DCERT_MCP_AUTH_TOKEN="my-secret-token" \
dcert-mcp --mode http

The HTTP server exposes:

  • GET /health — health check endpoint, deliberately outside authentication so probes need no token
  • /mcp — the MCP streamable HTTP endpoint (every tool, same schemas as stdio)

Security: the HTTP transport exposes cert tooling that spawns subprocesses. If no authentication is configured (neither DCERT_MCP_OIDC_ISSUER nor DCERT_MCP_AUTH_TOKEN), dcert-mcp refuses to start when binding to a non-loopback address (e.g. 0.0.0.0:3000; the default is 127.0.0.1:3000). Either configure authentication, bind to 127.0.0.1, or set DCERT_MCP_ALLOW_INSECURE=1 to explicitly opt in to an unauthenticated public bind (not recommended). Unauthenticated binds to loopback are always allowed.

The transport also validates the Host header against an allowlist (loopback names and the bind address by default) to defeat DNS rebinding, rejects cross-origin requests unless DCERT_MCP_ALLOWED_ORIGINS names the origin, and bounds every request with a timeout and a body size limit, and the /mcp endpoint with a concurrency limit (/health is exempt, so a liveness probe still answers while the tool API is saturated). Both transports shut down gracefully on SIGINT and SIGTERM.

Per-tool authorization

A token that is admitted to the server is not automatically allowed to call every tool. Scope requirements can be set per tool, or in bulk for the tools that change state:

# Reading is open to any authenticated caller; writes need a scope; revocation needs more
DCERT_MCP_SCOPE_WRITE="pki.write" \
DCERT_MCP_SCOPE_VAULT_REVOKE="pki.admin" \
dcert-mcp --mode http
Variable Applies to
DCERT_MCP_SCOPE_<TOOL> One named tool, e.g. DCERT_MCP_SCOPE_VAULT_REVOKE
DCERT_MCP_SCOPE_WRITE Every tool that changes state (issue, sign, revoke, store, renew, convert, keystore, truststore, CSR, export)
DCERT_MCP_SCOPE_READ Every read-only tool

Any listed scope or role satisfies the requirement. A tool with no applicable rule is allowed, so existing deployments keep working until a policy is set.

Requires OIDC. Scopes and roles are read from a validated token, which a static bearer token does not carry. Setting any DCERT_MCP_SCOPE_* variable without DCERT_MCP_OIDC_ISSUER makes dcert-mcp refuse to start, rather than run with a policy it cannot enforce.

Authentication (OIDC/OAuth2)

When running in HTTP mode, dcert-mcp supports OIDC/OAuth2 JWT authentication following MCP Security Best Practices. Authentication is resolved in priority order:

  1. OIDC/OAuth2 — if DCERT_MCP_OIDC_ISSUER is set (recommended for production)
  2. Static bearer token — if only DCERT_MCP_AUTH_TOKEN is set
  3. No auth — if neither is configured

OIDC tokens are validated against JWKS (JSON Web Key Sets) with automatic key rotation. Validated tokens are cached in-memory with a configurable sliding window TTL.

Authentication Environment Variables

Variable Description
DCERT_MCP_OIDC_ISSUER OIDC issuer URL (enables OIDC mode)
DCERT_MCP_OIDC_AUDIENCE Expected audience claim (required with OIDC)
DCERT_MCP_OIDC_JWKS_URL JWKS URL (auto-discovered from issuer if omitted)
DCERT_MCP_REQUIRED_SCOPES Comma-separated required OAuth2 scopes
DCERT_MCP_REQUIRED_ROLES Comma-separated required app roles
DCERT_MCP_ALLOWED_CLIENTS Comma-separated allowed client app IDs
DCERT_MCP_SESSION_TTL Session cache inactivity TTL in seconds (default: 300)
DCERT_MCP_AUTH_TOKEN Static bearer token (lower priority than OIDC)
DCERT_MCP_ALLOWED_ORIGINS Comma-separated CORS allowlist for HTTP mode. Unset = no cross-origin access (default); * allows any origin (not recommended)
DCERT_MCP_ALLOW_INSECURE Set to 1 to allow starting HTTP mode unauthenticated on a non-loopback address (not recommended)
DCERT_MCP_ALLOWED_HOSTS Comma-separated Host header allowlist (default: loopback names and the bind address)
DCERT_MCP_SCOPE_WRITE / _READ / _<TOOL> Scopes or roles required per tool (see above)
DCERT_MCP_JWKS_TTL How long JWKS keys stay cached, in seconds (default: 3600)
DCERT_MCP_JWKS_MAX_STALE Longest a cached key is served past its TTL while the identity provider is unreachable, in seconds (default: 86400)
DCERT_MCP_ALLOW_NO_VERIFY Set to 1 to let diagnose_endpoint disable certificate verification (refused by default)
DCERT_MCP_BEHIND_TLS Set to 1 to confirm TLS terminates in front of a non loopback bind (silences the plaintext bearer warning)
DCERT_MCP_MAX_CONCURRENT_REQUESTS Concurrent in-flight HTTP requests (default: 64)
DCERT_MCP_REQUEST_TIMEOUT Per-request timeout in seconds (default: 120)
DCERT_MCP_MAX_BODY_BYTES Maximum request body size (default: 1048576)
DCERT_MCP_AUTH_FAILURE_LIMIT Failed authentications per client address before a 429 is answered (default: 10; 0 disables)
DCERT_MCP_AUTH_FAILURE_WINDOW Window for that limit in seconds (default: 60)
DCERT_MCP_FILE_ROOT Comma separated directories that tool file parameters and file targets are confined to (default: the working directory only). The first root is the working directory of every dcert child process
DCERT_MCP_ALLOWED_TARGETS Comma separated destinations tool calls may reach: hostnames, suffixes (.corp.example), IPs and CIDRs. Applies to target, connect_to, resolve, proxy and AIA issuer URLs. When set, everything else is refused, and a listed entry overrides the private range denial
DCERT_MCP_DENY_PRIVATE_TARGETS 1 refuses loopback, RFC 1918, link local (169.254.0.0/16, fe80::/10), fc00::/7 and the metadata addresses 169.254.169.254 and fd00:ec2::254 (default: 1 in HTTP mode, 0 in stdio mode)
DCERT_MCP_VAULT_ADDR_ALLOWLIST Comma separated Vault addresses a tool call may target. The server's own VAULT_TOKEN or ~/.vault-token is used only for these addresses or the server's VAULT_ADDR; any other address needs an explicit vault_token
DCERT_MCP_VAULT_ALLOW_SKIP_VERIFY Set to 1 to let a tool call disable Vault TLS verification (refused by default)

The server also reads a few non-auth environment variables: DCERT_MCP_MODE (stdio/http, alternative to --mode), DCERT_MCP_ADDR (bind address, alternative to --addr), and DCERT_MCP_DEBUG (pass --debug to the dcert subprocess).

See SECURITY.md for full security architecture documentation.


Features by Topic

Certificate Analysis

Decode X.509 certificates from PEM files, HTTPS endpoints, bare hostnames, or piped stdin: subject, issuer, serial number, validity window, SANs, expiry status. Reads PEM data automatically when piped (e.g. cat cert.pem | dcert).

Certificate Extensions and Fingerprints

SHA-256 fingerprints (--fingerprint), key usage, extended key usage, basic constraints, authority info access, signature algorithm, public key info, SCT count (--extensions).

TLS Debugging

Protocol version, cipher suite, key exchange group, ALPN negotiation, certificate transparency, verification result, and per-certificate chain validation detail. Network latency measurements for DNS resolution, TCP connect (Layer 4), and TLS+HTTP (Layer 7). Enable --debug for full OSI-layer diagnostics.

Post Quantum Key Exchange

Every connection reports the negotiated key exchange group (tls_key_exchange_group, for example X25519MLKEM768 or X25519) and classifies it (key_exchange_class: hybrid_pq, pure_pq, obsolete_pq, classical or unknown). Hybrid key agreement is standardised in RFC 10024 (X25519MLKEM768, SecP256r1MLKEM768, SecP384r1MLKEM1024); the pre standard X25519Kyber768Draft00 is flagged as obsolete. --pq-probe runs a second handshake offering only the RFC 10024 hybrids and reports supported, not_supported or not_testable. --groups sets the offered group list and --tls-profile modern|intermediate applies the Mozilla configurator v6 client profiles with X25519MLKEM768 first. Negotiating ML-KEM needs OpenSSL 3.5 or later on the dcert host (Ubuntu 26.04, Debian trixie, Homebrew, the Windows build and the Docker image all qualify; build with cargo build --features vendored elsewhere). The Linux release binary keeps the Ubuntu 22.04 glibc floor and is built against OpenSSL 3.0 headers; it looks up SSL_get0_group_name in the loaded libssl at run time, so on an OpenSSL 3.5 host (including the Docker image) it still names ML-KEM groups and --pq-probe reports correctly. dcert --version names the loaded OpenSSL, whether post quantum key exchange is available, and the build headers when they differ. The compliance report recognises ML-DSA and SLH-DSA certificates and notes the NIST IR 8547 timeline for RSA and ECDSA.

Mutual TLS (mTLS)

Client certificate authentication via PEM (--client-cert + --client-key) or PKCS12/PFX (--pkcs12 + --cert-password). Custom CA bundle support (--ca-cert) for corporate/internal PKI.

CSR Creation & Validation

Create PKCS#10 Certificate Signing Requests with guided interactive mode or CLI flags (dcert csr create). Supports RSA 4096 (default), RSA 2048, ECDSA P-256 (recommended), ECDSA P-384, and Ed25519 (modern EdDSA). Optional AES-256-CBC key encryption. Validate existing CSRs for compliance with CA/B Forum, DigiCert, and X9 standards (dcert csr validate). OU metadata identifiers (e.g., AppId:my-service) supported for internal PKI.

Certificate Compliance

Run compliance checks against the CA/B Forum Baseline Requirements, DigiCert, and X9 standards (--compliance). Checks key size, signature algorithm, validity period, revocation pointers, Subject Alternative Names, Certificate Transparency (SCTs), Extended Key Usage, and Basic Constraints. Returns findings with severity levels (Error, Warning, Info) and an overall COMPLIANT/NON-COMPLIANT status. Available in pretty, JSON, and YAML formats. Each finding names the ballot or policy it comes from so it can be looked up.

  • Validity period (ballot SC-081v3). The maximum validity of a subscriber (leaf) certificate depends on its notBefore date: 398 days when issued before 2026-03-15, 200 days from 2026-03-15, 100 days from 2027-03-15 and 47 days from 2029-03-15. Exceeding the limit is an Error for leaf certificates from publicly trusted CAs. CA certificates are exempt. When the chain looks privately issued (a self signed leaf, or a chain ending in a self signed root that is not in the public root set) the finding is downgraded to a Warning, because the limit binds public CAs and dcert cannot see the root trust verdict from inside the compliance engine; when the server omits its root, the chain is treated as public.
  • Revocation (ballot SC-063v4). Short lived certificates (at most 10 days if issued before 2026-03-15, at most 7 days from that date) are exempt from revocation checking and get an Info finding. Any other leaf must carry a CRL distribution point (mandatory since 2024-03-15), so a missing one is a Warning; a missing OCSP URL is only Info when a CRL is present, because OCSP became optional on the same date. Requires --extensions.
  • Signature algorithm. SHA-1 with RSA, ECDSA or DSA, MD5 and MD2 are Errors (ballot SC-097 sunsets every remaining use of SHA-1 in certificates and CRLs in 2026). SHA-2 families, RSA-PSS, Ed25519 and Ed448 are compliant. ML-DSA-44/65/87 (FIPS 204, RFC 9881) and the SLH-DSA parameter sets (FIPS 205) are reported as post quantum signatures.
  • Public key. RSA below 2048 bits and EC below 256 bits are Errors; RSA 2048 is a Warning. ML-DSA, ML-KEM, SLH-DSA and EdDSA keys are named (an ML-DSA key is reported as ML-DSA-65, not as an OID). A leaf with an RSA or ECDSA key gets one Info note that NIST IR 8547 (draft) deprecates these after 2030 and disallows them after 2035.
  • Extended Key Usage. serverAuth is required. clientAuth alongside serverAuth on a leaf is a Warning: the Chrome Root Program policy requires serverAuth only leaf certificates from publicly trusted CAs (Google Trust Services stopped issuing clientAuth in April 2026, Let's Encrypt removed it in February 2026 and retired the tlsclient profile in July 2026); mTLS client identities should come from a private CA.

Key-Certificate Matching

Verify private key matches a certificate (dcert verify-key). Supports RSA and EC keys against PEM files or live HTTPS endpoints. Auto-discovers matching .crt/.pem + .key pairs in a directory when run without arguments.

PFX/PEM Conversion

Convert PKCS12/PFX to separate PEM files or bundle PEM cert + key into PFX (dcert convert pfx-to-pem, dcert convert pem-to-pfx).

Java KeyStore and TrustStore

Create PKCS12 keystores and truststores compatible with Java JDK 9+ (dcert convert create-keystore, dcert convert create-truststore).

OCSP Revocation Checking

Query the certificate's OCSP responder to verify revocation status (--check-revocation).

Expiry Monitoring

Configurable threshold warnings (--expiry-warn N) with machine-readable exit codes. Continuous monitoring with --watch.

Certificate Comparison

Side-by-side diff of certificates between two targets (--diff).

Certificate Export

Save fetched certificate chains as PEM files (--export-pem), with optional filtering of expired certificates (--exclude-expired).

Vault PKI Integration

Issue, sign, revoke, list, and renew TLS certificates via HashiCorp Vault's PKI Secrets Engine (dcert vault). Store and validate certificates in Vault KV v1 or v2 (--kv-version). Interactive wizard mode for guided certificate issuance. Full chain assembly from Vault root and intermediate CAs. Export certificate lists to JSON, CSV, or Excel (.xlsx). SAN and IP SAN support across all certificate operations. Role inference from Vault token policies. Clear, actionable permission error messages with Vault policy hints.


Use Cases

DevOps & CI/CD

# Gate deployments on certificate health
dcert https://your-api.com --expiry-warn 14

# Check multiple endpoints
dcert https://api.example.com https://www.example.com https://admin.example.com

# Continuous monitoring
dcert --watch 300 https://your-api.com

Security Auditing

# Enforce TLS 1.3 only
dcert --min-tls 1.3 https://target.com

# Full audit with extensions, fingerprints, and revocation
dcert https://site.com --fingerprint --extensions --check-revocation

# Compliance audit against CA/B Forum Baseline Requirements
dcert https://site.com --compliance

# Test specific cipher suites, named in any notation
dcert https://target.com --cipher ECDHE-RSA-AES128-GCM-SHA256 --cipher 0xC030

CSR Management

# Create a CSR for a new service
dcert csr create --cn api.example.com --org "My Corp" --country GB --san DNS:api.example.com

# Create with ECDSA P-256 for modern deployments
dcert csr create --cn api.example.com --key-algo ecdsa-p256

# Create with Ed25519 (modern EdDSA, compact signatures)
dcert csr create --cn api.example.com --key-algo ed25519

# Validate before submitting to CA
dcert csr validate api-example-com.csr --format json

# Internal PKI with metadata identifiers
dcert csr create --cn app.internal.corp --ou "AppId:svc-123" --ou "Env:prod"

Vault PKI Automation

# Issue a certificate from Vault PKI and store in KV
dcert vault issue --cn www.example.com --role web-server \
  --san "DNS:*.example.com" --store-path secret/certs/www-example-com

# Renew a certificate stored in Vault KV
dcert vault renew secret/certs/www-example-com --role web-server

# Validate certificates stored in Vault KV
dcert vault validate secret/certs/www-example-com

# Audit all issued certificates
dcert vault list --show-details --export audit.xlsx

# Sign a CSR through Vault PKI
dcert vault sign --csr-file server.csr --role web-server --ttl 2160h

Certificate Management

# Convert PFX for web server deployment
dcert convert pfx-to-pem server.pfx --password secret --output-dir /etc/ssl

# Prepare Java keystore
dcert convert create-keystore --cert server.pem --key server-key.pem --output keystore.p12 --password changeit

# Verify key matches certificate before deployment
dcert verify-key server.pem --key server-key.pem

# Verify all cert/key pairs in a directory
dcert verify-key --dir /etc/ssl/certs

# Compare staging vs production certificates
dcert --diff https://staging.example.com https://prod.example.com

# Export and backup certificate chains
for domain in google.com github.com; do
  dcert "https://$domain" --export-pem "${domain}-chain.pem"
done

Python Package

A Python wrapper is available on PyPI, providing a FastMCP proxy around the dcert-mcp Rust binary. Each wheel bundles dcert and dcert-mcp for its platform, so installing from PyPI or a private mirror (Artifactory, Nexus) needs no access to GitHub.

Platform Wheel tag
Linux x86_64, glibc 2.34+ (RHEL 9, Ubuntu 22.04, Debian 12 and later) manylinux_2_34_x86_64
macOS Intel 10.15+ macosx_10_15_x86_64
macOS Apple Silicon 11+ macosx_11_0_arm64
Windows x86_64 win_amd64

The same wheels are attached to every GitHub release. On a host no wheel fits, pip reports "no matching distribution" rather than installing a package without the binary.

pip install dcert

Quick Start

from dcert import create_server

server = create_server()
server.run()  # stdio mode (default)

CLI

# stdio mode (default, for MCP clients like Claude Code)
dcert-python

# HTTP and SSE mode refuse to start without authentication: a static bearer
# token (at least 32 characters) or an OIDC issuer, audience and JWKS URL
export DCERT_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
dcert-python --transport http --port 8080

# On all interfaces, name the Host header values clients will use
dcert-python --transport http --host 0.0.0.0 --port 8080 --allowed-hosts mcp.example.com

# OIDC access tokens instead of a static token
DCERT_MCP_OIDC_ISSUER=https://idp.example.com DCERT_MCP_OIDC_AUDIENCE=dcert \
DCERT_MCP_OIDC_JWKS_URL=https://idp.example.com/keys dcert-python --transport http

# Pre-download binary
dcert-python --setup

Binary Discovery

The Python package locates the dcert-mcp binary in this order:

  1. DCERT_MCP_BINARY environment variable
  2. Bundled binary in the package bin/ directory
  3. Download from GitHub Releases with SHA256 verification, only when no binary was found above (for example a source checkout); never needed with a published wheel
  4. dcert-mcp on PATH

See the Python package README for full documentation.


Development

cargo fmt --all
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --features mcp -- -D warnings
cargo test
cargo test --features mcp
cargo build --release

License

MIT. See LICENSE.

Acknowledgements

Yorumlar (0)

Sonuc bulunamadi