certforge-discovery

certforge-discovery is an open-source agent that scans your infrastructure for TLS certificates and surfaces them in CertForge. It finds certificates you didn’t know you had — shadow certs from acquisitions, forgotten wildcards, certs issued by shadow IT — before they expire undetected. GitHub: CertForge-LLC/certforge-discovery

What it scans

Source	What it finds
CT log	All certificates ever issued for your domains (via crt.sh)
TLS scan	Certificates live on network endpoints — hostnames, IPs, CIDR ranges
Local filesystem	Cert files on the host (`/etc/ssl`, nginx, apache, letsencrypt paths)
Kubernetes	All `kubernetes.io/tls` secrets across every namespace

Installation

Download the binary for your platform from the latest release:

# Linux (AMD64)
curl -Lo certforge-discovery https://github.com/CertForge-LLC/certforge-discovery/releases/latest/download/certforge-discovery-linux-amd64
chmod +x certforge-discovery
sudo mv certforge-discovery /usr/local/bin/

Verify the download:

curl -Lo checksums.txt https://github.com/CertForge-LLC/certforge-discovery/releases/latest/download/checksums.txt
sha256sum -c checksums.txt --ignore-missing

Or build from source (requires Go 1.22+):

go install github.com/certforge-llc/certforge-discovery/cmd/certforge-discovery@latest

Quick start — no account required

Run a scan locally without a CertForge account. Results print to stdout or write to a file:

# CT log scan for a domain
certforge-discovery scan -domain example.com

# CT log + live TLS scan of a network range → CSV
certforge-discovery scan -domain example.com -target 10.0.1.0/24 -out certs.csv

# Local filesystem scan → JSON
certforge-discovery scan -local -out certs.json

# All sources → JSON
certforge-discovery scan -domain example.com -target 10.0.1.0/24 -local -k8s -out certs.json

Use -dry-run with any scan to print the exact JSON payload that would be sent to CertForge — without posting anything:

certforge-discovery scan -domain example.com -dry-run | jq .

Connect to CertForge

The discovery agent supports two connection methods. mTLS enrollment is recommended — it connects directly to the CertForge agent endpoint on port 8443, bypassing Cloudflare, and uses a pinned mutual-TLS certificate rather than a long-lived API key.

Option A — mTLS enrollment (recommended)

Generate an enrollment token in CertForge:

Go to Integrations → Connector Agents
Click + Enroll Agent and choose type Discovery
Give it a label (e.g. prod-scanner)
Copy the one-time token

Run the enroll command on the agent host:

certforge-discovery enroll \
  -token  <one-time-token>          \
  -url    https://app.certgov.app   \
  -label  prod-scanner

The enroll command writes your mTLS credentials and updates ~/.certforge-discovery/config.yaml automatically. The config will contain:

certforge_url: https://app.certgov.app

# mTLS credentials (written by certforge-discovery enroll)
mtls_host: usagent.certgov.app     # direct agent endpoint
mtls_port: 8443                     # 8443 prod · 8444 preview/dev
mtls_cert: ~/.certforge-discovery/client.crt
mtls_key:  ~/.certforge-discovery/client.key
mtls_ca:   ~/.certforge-discovery/server.crt

poll_interval: 6h

When mtls_host / mtls_cert are set, api_key is ignored. Traffic goes directly to port 8443 on the CertForge agent endpoint.

Then run a scan:

certforge-discovery scan

Option B — API key setup (legacy)

Run setup to pick your data region and connect with an API key:

certforge-discovery setup

This writes a config file to ~/.certforge-discovery/config.yaml:

certforge_url: https://app.certgov.app
api_key: cf_...                       # from CertForge Settings → API Keys
poll_interval: 6h

Then run a scan:

certforge-discovery scan

Discovered certificates appear in CertForge under Discovery with source: ct_log, tls_scan, local, or k8s. They are automatically evaluated against your Domain Trust Profiles and flagged for policy mismatches.

Continuous agent mode

Run the agent continuously so CertForge always has a current picture of your cert inventory:

certforge-discovery agent -domain example.com

The agent re-scans on the poll_interval set in its config (default 6 hours).

Configuration

~/.certforge-discovery/config.yaml — written by enroll (mTLS) or setup (API key):

certforge_url: https://app.certgov.app  # your region's URL

# --- mTLS auth (preferred, written by certforge-discovery enroll) ---
mtls_host: usagent.certgov.app
mtls_port: 8443                          # 8443 prod · 8444 preview/dev
mtls_cert: ~/.certforge-discovery/client.crt
mtls_key:  ~/.certforge-discovery/client.key
mtls_ca:   ~/.certforge-discovery/server.crt

# --- API key auth (legacy; used when mtls_host / mtls_cert are not set) ---
# api_key: cf_...                        # from CertForge Settings → API Keys

poll_interval: 6h

# Optional
scan_local: false        # scan local filesystem for cert files
scan_k8s: false          # scan Kubernetes TLS secrets
kubeconfig: ""           # path to kubeconfig; empty = in-cluster config
storage_paths:           # additional filesystem paths to scan
  - /opt/app/certs

# Optional: identify certs signed by your private CA(s)
# When configured, discovered certs are tagged issuer_type=internal_ca in CertForge
# so your governance team can distinguish internal issuance from shadow IT or public CAs.
known_internal_cas:
  - cert: /etc/ssl/private/corp-ca.crt   # PEM CA certificate (same file as certforge-connector private_ca.cert)
    label: "Corp Internal CA"

EU West (GDPR) — API key auth:

certforge_url: https://eu.certgov.app
api_key: cf_...
poll_interval: 6h

EU West (GDPR) — mTLS auth:

certforge_url: https://eu.certgov.app
mtls_host: eu-agent.certgov.app
mtls_port: 8443
mtls_cert: ~/.certforge-discovery/client.crt
mtls_key:  ~/.certforge-discovery/client.key
mtls_ca:   ~/.certforge-discovery/server.crt
poll_interval: 6h

Private CA awareness

If your environment uses certforge-connector with a private_ca: configured, point known_internal_cas at the same CA cert file. Discovery will then:

Cryptographically verify (TLS scan, local filesystem, Kubernetes) or name-match (CT log) each discovered cert against the CA
Tag matching certs as issuer_type: internal_ca in CertForge
Show them distinctly in the Discovery view so your team can govern internal issuance separately from public CA certs

This is a read-only classification — discovery never contacts the CA or generates certificates.

Scan flags

Flag	Default	Description
`-domain <domain>`	—	Domain to query in CT logs (crt.sh)
`-target <host/cidr>`	—	Hostname, IP, or CIDR range for live TLS scan
`-ports <ports>`	`443,8443`	Ports for TLS scan
`-local`	false	Scan local filesystem for cert files
`-k8s`	false	Scan Kubernetes TLS secrets
`-out <file>`	stdout	Write to file (`.csv` or `.json`)
`-dry-run`	false	Print JSON payload without posting to CertForge

Running as a service

systemd:

[Unit]
Description=CertForge Discovery Agent
After=network.target

[Service]
ExecStart=/usr/local/bin/certforge-discovery agent -domain example.com
Restart=on-failure
RestartSec=30

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now certforge-discovery

Kubernetes (mTLS — recommended): Store the mTLS credentials from certforge-discovery enroll in a Secret:

kubectl create secret generic certforge-discovery-mtls \
  --namespace certforge-system \
  --from-file=client.crt=~/.certforge-discovery/client.crt \
  --from-file=client.key=~/.certforge-discovery/client.key \
  --from-file=server.crt=~/.certforge-discovery/server.crt

apiVersion: apps/v1
kind: Deployment
metadata:
  name: certforge-discovery
  namespace: certforge-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: certforge-discovery
  template:
    metadata:
      labels:
        app: certforge-discovery
    spec:
      serviceAccountName: certforge-discovery
      volumes:
        - name: mtls
          secret:
            secretName: certforge-discovery-mtls
      containers:
        - name: agent
          image: ghcr.io/certforge-llc/certforge-discovery:latest
          volumeMounts:
            - name: mtls
              mountPath: /etc/certforge-discovery/creds
              readOnly: true
          env:
            - name: CERTFORGE_URL
              value: https://app.certgov.app
            - name: MTLS_HOST
              value: usagent.certgov.app
            - name: MTLS_PORT
              value: "8443"
            - name: MTLS_CERT
              value: /etc/certforge-discovery/creds/client.crt
            - name: MTLS_KEY
              value: /etc/certforge-discovery/creds/client.key
            - name: MTLS_CA
              value: /etc/certforge-discovery/creds/server.crt

Kubernetes (API key — legacy):

apiVersion: apps/v1
kind: Deployment
metadata:
  name: certforge-discovery
  namespace: certforge-system
spec:
  replicas: 1
  selector:
    matchLabels:
      app: certforge-discovery
  template:
    metadata:
      labels:
        app: certforge-discovery
    spec:
      serviceAccountName: certforge-discovery
      containers:
        - name: agent
          image: ghcr.io/certforge-llc/certforge-discovery:latest
          env:
            - name: CERTFORGE_URL
              value: https://app.certgov.app
            - name: API_KEY
              valueFrom:
                secretKeyRef:
                  name: certforge-discovery-credentials
                  key: api_key

Grant the service account secrets: [get, list] cluster-wide so the agent can read kubernetes.io/tls secrets across all namespaces.

What is sent to CertForge

The agent posts certificate metadata only — no private keys, no plaintext traffic, no filesystem contents beyond recognized cert formats.

Field	Example
`fingerprint`	`sha256:3f2a...`
`serial`	`0x1A2B3C...`
`issuer`	`C=US, O=Let's Encrypt, CN=R11`
`subject`	`example.com`
`sans`	`example.com, www.example.com`
`not_before` / `not_after`	RFC 3339 timestamps
`source`	`ct_log`, `tls_scan`, `local`, `k8s`
`source_detail`	`192.168.1.50:443`
`seen_deployed`	`true` — live TLS confirmed
`eku`	`["TLS Web Server Authentication"]`

For Kubernetes secrets: only the tls.crt field is read — tls.key is never accessed or transmitted.

Corporate proxy

export HTTPS_PROXY=http://proxy.corp.com:8080
export NO_PROXY=localhost,127.0.0.1,10.0.0.0/8
certforge-discovery scan -domain example.com

Live TLS scanning (-target) makes direct TCP connections and is not proxied — run the agent on a host with direct access to the targets.

What happens after discovery

Discovered certs land in CertForge with governance_status = untracked. Your team can:

Track — acknowledge the cert; CertForge monitors it for expiry and includes it in compliance reports
Dismiss — mark as a known false positive; excluded from open issues
Leave as untracked; it contributes to the Ungoverned KPI on the Dashboard

See Certificate Discovery for the full governance workflow.

​What it scans

​Installation

​Quick start — no account required

​Connect to CertForge

​Option A — mTLS enrollment (recommended)

​Option B — API key setup (legacy)

​Continuous agent mode

​Configuration

​Private CA awareness

​Scan flags

​Running as a service

​What is sent to CertForge

​Corporate proxy

​What happens after discovery

What it scans

Installation

Quick start — no account required

Connect to CertForge

Option A — mTLS enrollment (recommended)

Option B — API key setup (legacy)

Continuous agent mode

Configuration

Private CA awareness

Scan flags

Running as a service

What is sent to CertForge

Corporate proxy

What happens after discovery