Module Monitoring

Atom Feed

The feed is available at https://feeds.api.sourcespotter.com/modules/versions.atom. It returns up to 10,000 versions (excluding pre-release versions) ordered by the time we observed them.

The feed accepts the following query parameters:

• module (required) – the module path to inspect. Append a trailing slash (/) to match all modules with the given prefix.
• mldsa (optional) – the hex-encoded SHA-256 hash of an ML-DSA public key. When supplied, the feed only returns versions that have not been authorized by that key (see below).

For example, requesting ?module=example.com/module returns the versions of exactly that module, while ?module=example.com/ returns every module whose path starts with example.com/.

Try It Out

Enter the module path and optional ML-DSA public key hash to open the feed.

Prometheus Metrics

The same information is available as Prometheus metrics at https://metrics.api.sourcespotter.com/modules, so you can alert when an unexpected version of your module appears in the checksum database.

The metrics endpoint accepts the following query parameters:

• module (required) – the module path to inspect. Append a trailing slash (/) to match all modules with the given prefix. May be specified up to 25 times to scrape several modules in one request.
• mldsa (optional) – the hex-encoded SHA-256 hash of an ML-DSA public key. When supplied, the response also includes metrics about versions that have not been authorized by that key (see below).

The following gauges are exported for each module parameter. Pre-release versions are not counted.

• sourcespotter_module_versions{module="..."} – the number of distinct versions observed in the checksum database.
• sourcespotter_module_latest_timestamp_seconds{module="..."} – the Unix time at which the most recent version was observed. Absent if no versions have been observed.
• sourcespotter_module_unauthorized_versions{module="..."} – the number of distinct versions not authorized by the given key. Only exported when mldsa is supplied.
• sourcespotter_module_unauthorized_version_info{module="...",version="..."} – one series per unauthorized version, labeled with the module path and version. Only exported when mldsa is supplied.

For example, to scrape example.com/module every 5 minutes, add the following to your Prometheus configuration:

scrape_configs:
  - job_name: sourcespotter_modules
    scheme: https
    scrape_interval: 5m
    metrics_path: /modules
    params:
      module: ["example.com/module"]
      mldsa: ["e3b0c44298fc1c14..."]
    static_configs:
      - targets: ["metrics.api.sourcespotter.com"]

You can then alert on sourcespotter_module_unauthorized_versions > 0 to be notified when the checksum database contains a version that you did not release.

Authorizing Versions

Source Spotter can accept go.sum files signed by an ML-DSA key to mark module versions as authorized. When you supply the SHA-256 hash of the public key via the mldsa parameter, the feed filters out the versions that have already been authorized, allowing you to focus on unexpected releases.

To upload an authorization, POST the JSON serialization of the following Go struct to https://v1.api.sourcespotter.com/modules/authorized:

struct {
	MLDSA     []byte // Raw ML-DSA public key used to verify Signature
	GoSum     string // A go.sum file listing authorized module versions
	Signature []byte // ML-DSA signature over GoSum with an empty context string
}

You can use the sourcespotter-authorize command to authorize module versions in a local Git repository. Typically, you would run sourcespotter-authorize right after you run git tag to release a new version.

Install the command:

$ go install software.sslmate.com/src/sourcespotter/cmd/sourcespotter-authorize@latest

Generate a new key (stored in $XDG_CONFIG_HOME/sourcespotter-authorize/private_key by default):

$ sourcespotter-authorize -keygen

Print the public key hash (hex):

$ sourcespotter-authorize -pubkey

Print the URL for the current module's Atom feed:

$ sourcespotter-authorize -feed

Print the URL for the current module's Prometheus metrics:

$ sourcespotter-authorize -metrics

Authorize a specific tag (or submodule tag like subdir/v1.2.3):

$ sourcespotter-authorize v1.2.3

Authorize every tag in the repository:

$ sourcespotter-authorize $(git tag)