ribbybibby/ssl-exporter

SSL Certificate Exporter

镜像概述和主要用途

SSL Certificate Exporter是一款用于导出SSL证书Prometheus指标的工具，支持从多种来源收集证书信息，包括TCP探针、HTTPS探针、PEM文件、Kubernetes密钥和Kubeconfig文件。指标带有证书字段标签，可用于构建信息仪表盘和实现灵活的告警路由。

核心功能和特性

• 多源证书收集：支持从TCP连接、HTTPS端点、本地PEM文件、Kubernetes TLS密钥和Kubeconfig文件中提取证书信息
• 丰富的指标输出：提供证书过期时间、生效时间、OCSP响应状态、TLS版本等关键指标
• 灵活的标签体系：指标包含序列号、颁发者CN、通用名称、DNS名称等证书字段标签
• Prometheus集成：原生支持Prometheus抓取，可直接集成到监控系统中
• 多探针支持：提供TCP、HTTPS、文件、Kubernetes和Kubeconfig五种探针类型

使用场景和适用范围

• SSL/TLS证书过期监控与告警
• 证书链完整性验证
• Kubernetes集群内证书状态监控
• 多环境证书统一管理
• 安全合规审计与证书生命周期管理

部署和使用方法

Docker镜像获取与运行

拉取镜像

bash
docker pull ribbybibby/ssl-exporter

基本运行

bash
docker run -p 9219:9219 ribbybibby/ssl-exporter:latest <flags>

访问http://localhost:9219/probe?target=example.com:443可获取example.com的证书指标，ssl_probe_success指标指示探针是否成功。

命令行参数

usage: ssl_exporter [<flags>]

Flags:
  -h, --help                     显示上下文相关帮助（也可尝试 --help-long 和 --help-man）
      --web.listen-address=":9219"
                                 Web界面和遥测的监听地址
      --web.metrics-path="/metrics"
                                 暴露指标的路径
      --web.probe-path="/probe"  暴露探针端点的路径
      --config.file=""           SSL exporter配置文件路径
      --log.level="info"         日志级别，仅记录指定级别及以上的日志，有效值：[debug, info, warn, error, fatal]
      --log.format="logger:stderr"
                                 设置日志目标和格式，例如："logger:syslog?appname=bob&local=7" 或 "logger:stdout?json=true"
      --version                  显示应用版本

指标说明

配置说明

TCP探针配置

通过Prometheus的relabel配置实现目标发现和监控：

yaml
scrape_configs:
  - job_name: "ssl"
    metrics_path: /probe
    static_configs:
      - targets:
          - example.com:443
          - prometheus.io:443
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9219  # SSL exporter地址

HTTPS探针配置

若需使用HTTP代理，可通过module参数指定HTTPS探针：

yaml
scrape_configs:
  - job_name: "ssl"
    metrics_path: /probe
    params:
      module: ["https"]  # 指定使用HTTPS探针
    static_configs:
      - targets:
          - example.com:443
          - prometheus.io:443
    relabel_configs:
      - source_labels: [__address__]
        target_label: __param_target
      - source_labels: [__param_target]
        target_label: instance
      - target_label: __address__
        replacement: 127.0.0.1:9219

HTTPS探针支持通过环境变量（HTTP_PROXY、HTTPS_PROXY、ALL_PROXY）或模块配置中的proxy_url选项设置代理。

文件探针配置

用于监控本地PEM文件中的证书，支持通配符匹配：

bash
# 单个文件
curl "localhost:9219/probe?module=file&target=/etc/ssl/cert.pem"

# 通配符匹配多个文件
curl "localhost:9219/probe?module=file&target=/etc/ssl/**/*.pem"

在Kubernetes中作为DaemonSet运行以监控节点证书：

yaml
scrape_configs:
  - job_name: "ssl-kubernetes-file"
    metrics_path: /probe
    params:
      module: ["file"]
      target: ["/etc/kubernetes/**/*.crt"]
    kubernetes_sd_configs:
      - role: node
    relabel_configs:
      - source_labels: [__address__]
        regex: ^(.*):(.*)$
        target_label: __address__
        replacement: ${1}:9219

Kubernetes探针配置

用于监控Kubernetes中kubernetes.io/tls类型的密钥：

bash
# 监控指定命名空间下的密钥
curl "localhost:9219/probe?module=kubernetes&target=kube-system/secret-name"

# 通配符匹配
curl "localhost:9219/probe?module=kubernetes&target=kube-system/*"  # 匹配kube-system命名空间下所有密钥
curl "localhost:9219/probe?module=kubernetes&target=*/*"            # 匹配所有命名空间下所有密钥

凭据获取顺序：

1. 模块配置中的kubeconfig路径
2. $KUBECONFIG环境变量
3. 默认配置文件（$HOME/.kube/config）
4. 集群内环境（当在Pod中运行时）

Kubeconfig探针配置

用于监控kubeconfig文件中的证书：

bash
curl "localhost:9219/probe?module=kubeconfig&target=/etc/kubernetes/admin.conf"

在Kubernetes中监控节点kubeconfig：

yaml
scrape_configs:
  - job_name: "ssl-kubernetes-kubeconfig"
    metrics_path: /probe
    params:
      module: ["kubeconfig"]
      target: ["/etc/kubernetes/admin.conf"]
    kubernetes_sd_configs:
      - role: node
    relabel_configs:
      - source_labels: [__address__]
        regex: ^(.*):(.*)$
        target_label: __address__
        replacement: ${1}:9219

配置文件

通过--config.file参数指定配置文件，支持模块级别的详细配置，格式为YAML：

yaml
modules: [<module>]

模块配置结构

yaml
# 探针类型（https, tcp, file, kubernetes, kubeconfig）
prober: <prober_string>

# 探针超时时间
[ timeout: <duration> ]

# TLS配置
[ tls_config: <tls_config> ]

# 特定探针配置
[ https: <https_probe> ]
[ tcp: <tcp_probe> ]
[ kubernetes: <kubernetes_probe> ]

TLS配置

yaml
# 禁用目标证书验证
[ insecure_skip_verify: <boolean> | default = false ]

# 目标CA证书文件
[ ca_file: <filename> ]

# 客户端证书文件
[ cert_file: <filename> ]

# 客户端密钥文件
[ key_file: <filename> ]

# 用于验证目标的主机名
[ server_name: <string> ]

HTTPS探针配置

yaml
# 用于连接目标的HTTP代理服务器
[ proxy_url: <string> ]

TCP探针配置

yaml
# 对支持的协议（smtp, ftp, imap）在启动TLS前使用STARTTLS命令
[ starttls: <string> ]

Kubernetes探针配置

yaml
# 用于配置探针的kubeconfig文件路径
[ kubeconfig: <string> ]

示例查询

7天内过期的证书

promql
ssl_cert_not_after - time() < 86400 * 7

即将过期的通配符证书

promql
ssl_cert_not_after{cn=~"\*.*"} - time() < 86400 * 7

验证链中7天内过期且最后过期的证书

promql
ssl_verified_cert_not_after{chain_no="0"} - time() < 86400 * 7

服务器提供的证书数量

promql
count(ssl_cert_not_after) by (instance)

失败的探针

promql
ssl_probe_success == 0

对等证书与验证链证书的区别

• 对等证书（Peer Certificates）：仅包含目标显式提供的证书
• 验证链证书（Verified Chain Certificates）：包含客户端构建的完整信任链，可能包括客户端本地的根证书

chain_no标签按过期时间倒序编号，chain_no="0"表示过期时间最晚的信任链。监控证书过期时，建议使用ssl_verified_cert_not_after{chain_no="0"}，因为它反映了客户端实际使用的信任链。

注意：此查询仅反映exporter与目标之间的信任链，实际客户端可能因根证书不同而具有不同的验证链。

Grafana仪表盘

可在此处获取跟踪证书过期日期和目标连接错误的简单仪表盘。