dcert
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.
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.
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).
Table of Contents
- Quick Start
- Installation
- Commands
- dcert [check] -- Certificate Analysis
- dcert csr -- CSR Creation & Validation
- dcert convert -- Format Conversion
- dcert verify-key -- Key Matching
- dcert vault -- HashiCorp Vault PKI
- dcert diagnose -- TLS, mTLS, Gateway, CDN and Proxy Diagnostics
- dcert kb -- Diagnostics and Reference Knowledge Bases
- dcert ciphers -- Cipher Suite Lookup
- dcert tls-scan -- Version, Cipher and Group Enumeration
- dcert policy -- TLS Security Policy Catalogue
- MCP Server (AI IDE Integration)
- Features by Topic
- Use Cases
- Python Package
- Development
- License
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_FILEto a CA bundle (e.g. one exported from your organization or acacert.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 anis_public_root: true attribute in JSON/YAML (usually absent, since servers
don't send the root).
Optional network probe (--resolve-issuers). For incomplete orprivate_pki results you can follow the certificate's AIA "CA Issuers" URLs to
fetch missing issuer certificates — completing the chain (which can flip anincomplete 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-bodyis 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 theCloudFront-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 andTLS_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:
- Discovery: the default handshake and two more offering only RSA or only
ECDSA suites, to learn which certificate key types the listener holds. - Each protocol version alone: accepted exactly when the policy lists it.
- Each TLS 1.2 cipher of the policy alone: accepted, with that cipher
negotiated. Every other catalogued TLS 1.2 cipher: refused. - Each TLS 1.3 suite of the policy alone: accepted. Every other suite the
linked OpenSSL implements: refused. - Each group of the policy alone,
X25519alone 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 isconformant, 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 thedcert 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:
- Verify proxy settings are passed to
dcert-mcpvia the MCP configenvblock - Check the startup diagnostics show the expected proxy URL
- Increase
DCERT_MCP_TIMEOUTif the proxy is slow - If the target is internal, add it to
NO_PROXY - If TLS interception is used, set
SSL_CERT_FILEto the corporate CA bundle
dcert binary not found
If the startup log shows a warning about the dcert binary not being found:
- Ensure
dcertis on yourPATH, or - Set
DCERT_PATHto the full path in the MCP configenvblock
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_ISSUERnorDCERT_MCP_AUTH_TOKEN),dcert-mcprefuses to start when binding to a non-loopback address (e.g.0.0.0.0:3000; the default is127.0.0.1:3000). Either configure authentication, bind to127.0.0.1, or setDCERT_MCP_ALLOW_INSECURE=1to 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 withoutDCERT_MCP_OIDC_ISSUERmakesdcert-mcprefuse 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:
- OIDC/OAuth2 — if
DCERT_MCP_OIDC_ISSUERis set (recommended for production) - Static bearer token — if only
DCERT_MCP_AUTH_TOKENis set - 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:
DCERT_MCP_BINARYenvironment variable- Bundled binary in the package
bin/directory - 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
dcert-mcponPATH
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
- X.509 parsing by x509-parser
- CLI framework by clap
- Terminal colors by colored
- TLS connections and OCSP by openssl
- YAML serialization by serde_norway
- Signal handling by ctrlc
- MCP server by rmcp
Yorumlar (0)
Yorum birakmak icin giris yap.
Yorum birakSonuc bulunamadi