HashiCorp Vault PKI Discovery

How It Works

The Vault PKI connector uses Vault's REST API with token authentication. It performs three operations per PKI mount:

Lab Setup

Two options — Docker (recommended, no install needed) or Homebrew. Both produce an identical Vault instance for testing.

docker run --rm --name vault-lab \
  -p 8200:8200 \
  -e VAULT_DEV_ROOT_TOKEN_ID=devroot \
  -e VAULT_DEV_LISTEN_ADDRESS=0.0.0.0:8200 \
  hashicorp/vault:latest

export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=devroot

# Enable PKI secrets engine
vault secrets enable pki
vault secrets tune -max-lease-ttl=87600h pki

# Generate root CA (RSA-2048)
vault write pki/root/generate/internal \
  common_name="Lab Root CA" \
  key_type=rsa key_bits=2048 \
  ttl=87600h

# Create a role so you can issue leaf certs
vault write pki/roles/lab \
  allowed_domains=lab.local \
  allow_subdomains=true \
  max_ttl=720h

# Issue a leaf cert to populate LIST /v1/pki/certs
vault write pki/issue/lab \
  common_name=server.lab.local ttl=24h

vault secrets enable -path=pki-int pki
vault secrets tune -max-lease-ttl=43800h pki-int

# Generate intermediate CSR
vault write pki-int/intermediate/generate/internal \
  common_name="Lab Intermediate CA" \
  key_type=ec key_bits=256 | grep csr | awk '{print $2}' \
  > /tmp/int_csr.pem

# Sign with root CA
vault write pki/root/sign-intermediate \
  csr=@/tmp/int_csr.pem \
  format=pem_bundle ttl=43800h | grep certificate | awk '{print $2}' \
  > /tmp/int_cert.pem

# Import signed cert into pki-int
vault write pki-int/intermediate/set-signed \
  certificate=@/tmp/int_cert.pem

# Role + issue a leaf so LIST has data
vault write pki-int/roles/lab allowed_domains=lab.local allow_subdomains=true max_ttl=720h
vault write pki-int/issue/lab common_name=app.lab.local ttl=24h

# Store Vault address and token in config.enc
./build/certscanner -config \
  -config-vault-addr http://127.0.0.1:8200 \
  -config-vault-token devroot

# Run PKI scan — auto-discovers all pki mounts
./build/certscanner -scan-pki -outputformat flatndjson \
  -output /tmp/vault_scan.ndjson

# Verify output
grep "vault://" /tmp/vault_scan.ndjson | grep -o '"source_file_path":"[^"]*"'

# Install Vault CLI + server
/opt/homebrew/bin/brew install vault

# Start dev server (same flags as Docker)
vault server -dev -dev-root-token-id=devroot -dev-listen-address=127.0.0.1:8200

# Then follow the same PKI setup steps above (Step 2 onward)

Credential Chain

The scanner resolves a Vault token using this priority order. The first tier that returns a non-empty token wins.

Configuration Flags

Quick Start Examples

# Store config once
./build/certscanner -config \
  -config-vault-addr http://127.0.0.1:8200 \
  -config-vault-token devroot

# Scan (auto-discovers all pki mounts)
./build/certscanner -scan-pki -outputformat flatndjson -output vault_certs.ndjson

./build/certscanner -config \
  -config-vault-addr https://vault.corp.com:8200 \
  -config-vault-token s.AbCdEfGhIjKlMnOp \
  -config-vault-mount pki,pki-intermediate,pki-iot

./build/certscanner -scan-pki -outputformat flatndjson -output vault_certs.ndjson

./build/certscanner -scan-pki -insecure -outputformat flatndjson -output vault_certs.ndjson

export VAULT_ADDR=https://vault.corp.com:8200
export VAULT_TOKEN=s.AbCdEfGhIjKlMnOp
./build/certscanner -scan-pki -outputformat flatndjson -output vault_certs.ndjson

Multi-Mount Auto-Discovery

When -config-vault-mount is not set, the connector calls GET /v1/sys/mounts and scans every mount whose type field is "pki". This is the recommended configuration for environments with multiple PKI hierarchies.

Vault Enterprise — Namespaces

Vault Enterprise supports multi-tenancy via namespaces. Set the namespace using -config-vault-namespace and the scanner will include the X-Vault-Namespace header on every API request.

# Enterprise: store namespace alongside addr/token
./build/certscanner -config \
  -config-vault-addr https://vault.enterprise.com:8200 \
  -config-vault-token s.TokenHere \
  -config-vault-namespace "infosec/pki"

# Scans /v1/infosec/pki/{mount}/... automatically
./build/certscanner -scan-pki -outputformat flatndjson -output vault_ent.ndjson

Output Fields

Vault PKI CA certificates appear as pki_ca_discovered events; issued leaf certificates appear as pki_issued_cert_discovered events. Both have event.dataset: pki_certificate, which routes them to the tychon-pqc-certificates Elasticsearch index.

PKI platform metadata (Vault address, mount name) lives in tychon.pki.*. Certificate cryptographic data follows the standard ECS namespace (x509.*, certificate.*).

Minimum Vault Policy

Create a scoped policy instead of using the root token in production. The scanner requires only read and list capabilities on PKI paths — no write, delete, create, update, patch, or sudo access is needed or should be granted.

Known Mount Names

Use explicit mount paths when your PKI mounts have fixed, known names. Add one block per mount.

# tychon-pki-read.hcl  (known mount names: pki, pki-int)

# Read CA certificate (raw PEM endpoint)
path "pki/ca/pem"     { capabilities = ["read"] }
path "pki-int/ca/pem" { capabilities = ["read"] }

# List issued certificate serials
path "pki/certs"     { capabilities = ["list"] }
path "pki-int/certs" { capabilities = ["list"] }

# Read individual certificates by serial
path "pki/cert/*"     { capabilities = ["read"] }
path "pki-int/cert/*" { capabilities = ["read"] }

# Required for auto-discovery (omit if using -config-vault-mount explicitly)
path "sys/mounts" { capabilities = ["read"] }

Dynamic / Unknown Mount Names

If your environment uses programmatically created PKI mounts with unpredictable names, use the + single-level wildcard. This covers all direct child mounts without granting access to other secret engines.

# tychon-pki-read.hcl  (wildcard variant — covers any top-level PKI mount name)

path "+/ca/pem"   { capabilities = ["read"] }
path "+/certs"    { capabilities = ["list"] }
path "+/cert/*"   { capabilities = ["read"] }
path "sys/mounts" { capabilities = ["read"] }

Apply the Policy and Create a Token

# Write the policy
vault policy write tychon-pki-read tychon-pki-read.hcl

# Create a standard token (TTL = 1 year)
vault token create \
  -policy=tychon-pki-read \
  -display-name="tychon-scanner" \
  -ttl=8760h

# Store the token in config.enc (never on the CLI or in env vars in production)
./build/certscanner -config -config-vault-addr https://vault.corp.example.com:8200 \
                            -config-vault-token s.YourTokenHere

Token Renewal (Scheduled Scans)

For recurring scans, create a periodic token (no hard expiry) with an explicit max TTL and renew it on each scan run. Periodic tokens require the sudo capability on auth/token/create to create, but the resulting token itself has no elevated rights.

# Create a periodic token — max-ttl caps total lifetime even with renewals
vault token create \
  -policy=tychon-pki-read \
  -display-name="tychon-scanner" \
  -period=720h \
  -explicit-max-ttl=8760h

# Renew before each scan (add to your scheduling wrapper script)
vault token renew -increment=720h

Troubleshooting

# Option A — store in config.enc
./build/certscanner -config -config-vault-token s.YourToken

# Option B — environment variable
export VAULT_TOKEN=s.YourToken

# Option C — interactive login (writes ~/.vault-token)
export VAULT_ADDR=http://127.0.0.1:8200
vault login devroot

vault secrets enable pki
# Then generate or import a root CA before scanning

./build/certscanner -scan-pki -insecure -outputformat flatndjson -output out.ndjson