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

Run setup to pick your data region and connect the agent to your CertForge account:

certforge-discovery setup

This writes a config file to ~/.certforge-discovery/config.yaml. 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

Setup writes ~/.certforge-discovery/config.yaml:

certforge_url: https://app.certgov.app  # your region's URL
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):

certforge_url: https://eu.certgov.app
api_key: cf_...
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:

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

​Continuous agent mode

​Configuration

​Private CA awareness

​Scan flags

​Running as a service

​What is sent to CertForge

​Corporate proxy

​What happens after discovery