Move to a modules/probers model, like the blackbox_exporter. (#34)

There are a number of reasons for this change:
- Modules allow a single instance of the exporter to be configured with numerous
different tls configs. Previously you had to run a different exporter for each
combination.
- Adding new and more complicated options to the exporter should be easier with
modules than if I was to go down the route of accepting configuration directly through url params
- I prefer defining a specific prober (https,tcp) over using the URL to guess
what the user wants

README.md

@@ -21,20 +21,19 @@ meaningful visualisations and consoles.
 ## Table of Contents
 
 - [SSL Certificate Exporter](#ssl-certificate-exporter)
+  - [Table of Contents](#table-of-contents)
   - [Building](#building)
-  - [Docker](#docker)
-  - [Flags](#flags)
+    - [Docker](#docker)
+    - [Release process](#release-process)
+  - [Usage](#usage)
   - [Metrics](#metrics)
-  - [Prometheus](#prometheus)
-    - [Configuration](#configuration)
-    - [Targets](#targets)
-      - [Valid targets](#valid-targets)
-      - [Invalid targets](#invalid-targets)
-    - [Example Queries](#example-queries)
-  - [Client authentication](#client-authentication)
+  - [Configuration](#configuration)
+    - [Configuration file](#configuration-file)
+      - [<module>](#module)
+      - [<tls_config>](#tls_config)
+  - [Example Queries](#example-queries)
   - [Proxying](#proxying)
-  - [Limitations](#limitations)
-  - [Acknowledgements](#acknowledgements)
+  - [Grafana](#grafana)
 
 Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
 
@@ -61,43 +60,40 @@ metric indicates if the probe has been successful.
 - Dockerhub will build and tag a new container image in response to tags of the
   format `/^v[0-9.]+$/`
 
-## Flags
-
-    ./ssl_exporter --help
-
-- **`--tls.insecure`:** Skip certificate verification (default false). This is
-  insecure but does allow you to collect metrics in the case where a certificate
-  has expired. That being said, I feel that it's more important to catch
-  verification failures than it is to identify an expired certificate,
-  especially as the former includes the latter.
-- **`--tls.cacert`:** Provide the path to an alternative bundle of root CA
-  certificates. By default the exporter will use the host's root CA set.
-- **`--tls.client-auth`:** Enable client authentication (default false). When
-  enabled the exporter will present the certificate and key configured by
-  `--tls.cert` and `tls.key` to the other side of the connection.
-- **`--tls.cert`:** The path to a local certificate for client authentication
-  (default "cert.pem"). Only used when `--tls.client-auth` is toggled on.
-- **`--tls.key`:** The path to a local key for client authentication (default
-  "key.pem"). Only used when `--tls.client-auth` is toggled on.
-- **`--web.listen-address`:** The port (default ":9219").
-- **`--web.metrics-path`:** The path metrics are exposed under (default
-  "/metrics")
-- **`--web.probe-path`:** The path the probe endpoint is exposed under (default
-  "/probe")
+## Usage
+
+```
+usage: ssl_exporter [<flags>]
+
+Flags:
+  -h, --help                     Show context-sensitive help (also try --help-long and
+                                 --help-man).
+      --web.listen-address=":9219"
+                                 Address to listen on for web interface and telemetry.
+      --web.metrics-path="/metrics"
+                                 Path under which to expose metrics
+      --web.probe-path="/probe"  Path under which to expose the probe endpoint
+      --config.file=""           SSL exporter configuration file
+      --log.level="info"         Only log messages with the given severity or above. Valid
+                                 levels: [debug, info, warn, error, fatal]
+      --log.format="logger:stderr"
+                                 Set the log target and format. Example:
+                                 "logger:syslog?appname=bob&local=7" or
+                                 "logger:stdout?json=true"
+      --version                  Show application version.
+```
 
 ## Metrics
 
 | Metric                  | Meaning                                                                             | Labels                                              |
 | ----------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------- |
 | ssl_cert_not_after      | The date after which the certificate expires. Expressed as a Unix Epoch Time.       | serial_no, issuer_cn, cn, dnsnames, ips, emails, ou |
 | ssl_cert_not_before     | The date before which the certificate is not valid. Expressed as a Unix Epoch Time. | serial_no, issuer_cn, cn, dnsnames, ips, emails, ou |
-| ssl_client_protocol     | The protocol used by the exporter to connect to the target. Boolean.                | protocol                                            |
+| ssl_prober              | The prober used by the exporter to connect to the target. Boolean.                  | prober                                              |
 | ssl_tls_connect_success | Was the TLS connection successful? Boolean.                                         |                                                     |
 | ssl_tls_version_info    | The TLS version used. Always 1.                                                     | version                                             |
 
-## Prometheus
-
-### Configuration
+## Configuration
 
 Just like with the blackbox_exporter, you should pass the targets to a single
 instance of the exporter in a scrape config with a clever bit of relabelling.
@@ -121,38 +117,68 @@ scrape_configs:
         replacement: 127.0.0.1:9219 # SSL exporter.
 ```
 
-### Targets
+By default the exporter will make a TCP connection to the target. You can change
+this to https by setting the module parameter:
 
-The exporter uses the provided uri to decide which client (http or tcp) to use
-when connecting to the target. The uri must contain either a protocol scheme
-(`https://`), a port (`:443`), or both (`https://example.com:443`).
+```yml
+scrape_configs:
+  - job_name: "ssl"
+    metrics_path: /probe
+    params:
+      module: ["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
+```
 
-If the `https://` scheme is provided then the exporter will use a http client to
-connect to the target. This allows you to take advantage of some features not
-available when using tcp, like host-based proxying. The exporter doesn't
-understand any other L7 protocols, so it will produce an error for others, like
-`ldaps://` or `ftps://`.
+### Configuration file
 
-If there's only a port, then a tcp client is used to make the TLS connection.
-This should allow you to connect to any TLS target, regardless of L7 protocol.
+You can provide further module configuration by providing the path to a
+configuration file with `--config.file`. The file is written in yaml format,
+defined by the schema below.
 
-If neither are given, the exporter assumes a https connection on port `443` (the
-most common case).
+```
+modules: [<module>]
+```
+
+#### \<module\>
+
+```
+# The protocol over which the probe will take place (http, tcp)
+prober: <prober_string>
+
+# Configuration for TLS
+tls_config: <tls_config>
+```
+
+#### <tls_config>
+
+```
+# Disable target certificate validation.
+[ insecure_skip_verify: <boolean> | default = false ]
 
-#### Valid targets
+# The CA cert to use for the targets.
+[ ca_file: <filename> ]
 
-- `https://example.com`
-- `https://example.com:443`
-- `example.com:443`
-- `example.com:636`
-- `example.com`
+# The client cert file for the targets.
+[ cert_file: <filename> ]
 
-#### Invalid targets
+# The client key file for the targets.
+[ key_file: <filename> ]
 
-- `ldaps://example.com`
-- `ldaps://example.com:636`
+# Used to verify the hostname for the targets.
+[ server_name: <string> ]
+```
 
-### Example Queries
+## Example Queries
 
 Certificates that expire within 7 days:
 
@@ -178,45 +204,17 @@ Identify instances that have failed to create a valid SSL connection:
 ssl_tls_connect_success == 0
 ```
 
-## Client authentication
-
-The exporter optionally supports client authentication, which can be toggled on
-by providing the `--tls.client-auth` flag. By default, it will use the host
-system's root CA bundle and attempt to use `./cert.pem` and `./key.pem` as the
-client certificate and key, respectively. You can override these defaults with
-`--tls.cacert`, `--tls.cert` and `--tls.key`.
-
-If you do enable client authentication, keep in mind that the certificate will
-be passed to all targets, even those that don't necessarily require client
-authentication. I'm not sure what the implications of that are but I think you'd
-probably want to avoid passing a certificate to an unrelated server.
-
-Also, if you want to scrape targets with different client certificate
-requirements, you'll need to run different instances of the exporter for each.
-This seemed like a better approach than overloading the exporter with the
-ability to pass different certificates per-target.
-
 ## Proxying
 
-The https client used by the exporter supports the use of proxy servers
-discovered by the environment variables `HTTP_PROXY`, `HTTPS_PROXY` and
-`ALL_PROXY`.
+The `https` prober supports the use of proxy servers discovered by the
+environment variables `HTTP_PROXY`, `HTTPS_PROXY` and `ALL_PROXY`.
 
 For instance:
 
     $ export HTTPS_PROXY=localhost:8888
     $ ./ssl_exporter
 
-In order to use the https client, targets must be provided to the exporter with
-the protocol in the uri (`https://<host>:<optional port>`).
-
 ## Grafana
 
 You can find a simple dashboard [here](grafana/dashboard.json) that tracks
 certificate expiration dates and target connection errors.
-
-## Acknowledgements
-
-The overall structure and implementation of this exporter is based on the
-[consul_exporter](https://github.com/prometheus/consul_exporter). The probing
-functionality borrows from the blackbox_exporter.

config/config.go

@@ -0,0 +1,53 @@
+package config
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/prometheus/common/config"
+	yaml "gopkg.in/yaml.v3"
+)
+
+var (
+	DefaultConfig = &Config{
+		map[string]Module{
+			"tcp": Module{
+				Prober: "tcp",
+			},
+			"http": Module{
+				Prober: "https",
+			},
+			"https": Module{
+				Prober: "https",
+			},
+		},
+	}
+)
+
+func LoadConfig(confFile string) (*Config, error) {
+	var c *Config
+
+	yamlReader, err := os.Open(confFile)
+	if err != nil {
+		return c, fmt.Errorf("error reading config file: %s", err)
+	}
+	defer yamlReader.Close()
+	decoder := yaml.NewDecoder(yamlReader)
+	decoder.KnownFields(true)
+
+	if err = decoder.Decode(&c); err != nil {
+		return c, fmt.Errorf("error parsing config file: %s", err)
+	}
+
+	return c, nil
+
+}
+
+type Config struct {
+	Modules map[string]Module `yaml:"modules"`
+}
+
+type Module struct {
+	Prober    string           `yaml:"prober,omitempty"`
+	TLSConfig config.TLSConfig `yaml:"tls_config,omitempty"`
+}

examples/ssl_exporter.yaml

@@ -0,0 +1,15 @@
+modules:
+  https_insecure:
+    prober: https
+    tls_config:
+      insecure_skip_verify: true
+  tcp_servername:
+    prober: tcp
+    tls_config:
+      server_name: example.com
+  tcp_client_auth:
+    prober: tcp
+    tls_config:
+      ca_file: /etc/tls/ca.crt
+      cert_file: /etc/tls/tls.crt
+      key_file: /etc/tls/tls.key

go.mod

@@ -1,9 +1,21 @@
 module github.com/ribbybibby/ssl_exporter
 
 require (
-	github.com/prometheus/client_golang v0.9.2
-	github.com/prometheus/common v0.2.0
+	github.com/alecthomas/units v0.0.0-20190924025748-f65c72e2690d // indirect
+	github.com/golang/protobuf v1.4.2 // indirect
+	github.com/jpillora/backoff v1.0.0 // indirect
+	github.com/mwitkow/go-conntrack v0.0.0-20190716064945-2f068394615f // indirect
+	github.com/prometheus/client_golang v1.6.0
+	github.com/prometheus/common v0.10.0
+	github.com/prometheus/procfs v0.1.3 // indirect
+	github.com/sirupsen/logrus v1.6.0 // indirect
+	golang.org/x/net v0.0.0-20200602114024-627f9648deb9 // indirect
+	golang.org/x/sys v0.0.0-20200615200032-f1bc736245b1 // indirect
+	golang.org/x/text v0.3.2 // indirect
+	google.golang.org/protobuf v1.24.0 // indirect
 	gopkg.in/alecthomas/kingpin.v2 v2.2.6
+	gopkg.in/yaml.v2 v2.3.0 // indirect
+	gopkg.in/yaml.v3 v3.0.0-20200615113413-eeeca48fe776
 )
 
 go 1.14