govern

govern is a small Go library that lets an application check itself for known vulnerabilities at runtime.

The library reads the Go modules compiled into the running binary, checks them against the public Go vulnerability database, and reports what it finds. It can run once during startup or keep checking in the background.

Why use it?

Most vulnerability scanners run outside the application. govern is meant for the application itself: it can notice vulnerable dependencies when the binary starts and while it keeps running.

By default, critical vulnerabilities stop the process. Applications can opt out of that behavior, for example when they expose their own command-line flag for a temporary emergency override.

Quick start

package main

import (
	"context"
	"log"
	"time"

	govern "go.schlittermann.de/heiko/govern"
)

func main() {
	ctx := context.Background()

	runner, err := govern.Start(ctx, govern.Options{
		Interval: 12 * time.Hour,
		Logger:   log.Default(),
	})
	if err != nil {
		log.Fatal(err)
	}
	defer runner.Stop()

	// Start the rest of the application here.
}

For a one-shot check, call govern.CheckOnce.

Runtime behavior

govern checks the modules built into the current binary. Background checks started with Start run immediately and then repeat at the configured interval.

The application does not block indefinitely when the vulnerability database is unreachable:

• each source lookup has a finite timeout, defaulting to 5 seconds
• Start runs the initial check in the background
• repeated lookup failures are logged only after several consecutive failures, defaulting to 3

Critical vulnerabilities

Critical findings call os.Exit(1) by default. To keep running, pass CriticalActionWarnOnly:

runner, err := govern.Start(ctx, govern.Options{
	Interval:       12 * time.Hour,
	Logger:         log.Default(),
	CriticalAction: govern.CriticalActionWarnOnly,
})

Applications own their command-line interface. If you want an override flag, parse it in the application and map it to CriticalActionWarnOnly.

Vulnerability database and cache

The default source uses the public Go vulnerability database at https://vuln.go.dev. The implementation uses only the Go standard library and has no third-party module dependencies.

Fetched database JSON is cached in memory for the lifetime of the HTTPSource. The source also keeps a best-effort disk cache in the user's cache directory, normally $XDG_CACHE_HOME/govern or $HOME/.cache/govern on Unix. Set HTTPSource.CacheDir to choose another location.

When cached content has a Last-Modified value, later lookups send If-Modified-Since so the database can reply with 304 Not Modified. If the local cache cannot be read or written, govern logs a warning through HTTPSource.Logger or, when using the default source, Options.Logger. The vulnerability check continues without failing because of the local cache.

License

Apache License 2.0. See LICENSE.