gosocialcheck: social reputation checker for Go modules

gosocialcheck checks whether a Go module is already adopted by a trustworthy project.

List of trusted projects:

• CNCF Graduated (Kubernetes, containerd, etc.)

Install

go install github.com/AkihiroSuda/gosocialcheck/cmd/gosocialcheck@latest

Usage

# Set the token if facing the GitHub API rate limit (see below)
export GITHUB_TOKEN=...

gosocialcheck update

gosocialcheck run ./...

This command checks whether the dependencies of the current module (./...) are used by trusted projects. This command does not check whether the the current module itself is used by trusted projects.

Example output:

/Users/suda/gopath/src/github.com/AkihiroSuda/gosocialcheck/pkg/analyzer/analyzer.go:18:2:
import 'golang.org/x/tools/go/analysis': module 'golang.org/x/tools@v0.33.0' does not seem adopted by a trusted project (negligible if you trust the module)
/Users/suda/gopath/src/github.com/AkihiroSuda/gosocialcheck/cmd/gosocialcheck/commands/run/run.go:5:2:
import 'golang.org/x/tools/go/analysis/singlechecker': module 'golang.org/x/tools@v0.33.0' does not seem adopted by a trusted project (negligible if you trust the module)
/Users/suda/gopath/src/github.com/AkihiroSuda/gosocialcheck/cmd/gosocialcheck/main.go:8:2:
import 'github.com/lmittmann/tint': module 'github.com/lmittmann/tint@v1.0.7' does not seem adopted by a trusted project (negligible if you trust the module)

Hints

GitHub Actions

Pass --gha to emit findings as workflow commands so they show up as annotations (up to 10) on the workflow run and any associated PR. In this mode the command always exits 0.

To stay within GitHub's annotation limits, --gha caps the number of emitted annotations and reports findings whose go.sum line changed in the PR first. On a pull_request event it fetches the base branch (GITHUB_BASE_REF) on demand to detect those lines, so the default shallow checkout works as-is:

- uses: actions/checkout@v4
- run: go install github.com/AkihiroSuda/gosocialcheck/cmd/gosocialcheck@latest
- run: gosocialcheck run --gha ./...

OpenSSF Scorecard

Pass --scorecard to also check the OpenSSF Scorecard scores of the dependencies (direct and indirect). A module is reported when its repository scores below --scorecard-min-score (default: 5.0) or has no Scorecard data at all.

gosocialcheck run --scorecard ./...

This check is opt-in, as not every repository is covered by Scorecard. Only modules hosted on github.com, gitlab.com, and golang.org/x are checked; modules with vanity import paths are skipped. //gosocialcheck:trusted directives (see below) silence this check too.

Alternative go.mod file

Pass --modfile to read the module from a file other than go.mod, like go -modfile. The corresponding go.sum is the file with the .mod suffix replaced by .sum. Findings (including --gha annotations) point to these files, and --gha detects the changed lines of the .sum file in the PR.

gosocialcheck run --modfile=vendor.mod ./...

Unlike go -modfile, go.mod does not need to exist next to the file, so this also works for repositories that only have e.g. vendor.mod and vendor.sum.

Allowlist

Use //gosocialcheck:trusted directives in go.mod to silence alerts for trustworthy modules.

e.g.,

//gosocialcheck:trusted
require (
	golang.org/x/sync v0.19.0
)

or

require (
	golang.org/x/sync v0.19.0 //gosocialcheck:trusted
)

Note: The directive ignores the module version.

Cache

gosocialcheck keeps two cache flavors under $XDG_CACHE_HOME/gosocialcheck (~/Library/Caches/gosocialcheck on macOS):

• _remote: a shallow clone of AkihiroSuda/gosocialcheck-cache, preprocessed and ready to use.
• _local: rebuilt locally from the CNCF project list and the GitHub API (gosocialcheck update --cache-mode=local).

The --cache-mode flag (or $GOSOCIALCHECK_CACHE_MODE) selects which one is used:

• auto (default): for reads, picks whichever has the more recent ModTime. For update, fetches the remote.
• remote: use the preprocessed remote cache.
• local: rebuild and use the local cache.

gosocialcheck run populates the cache automatically on the first run.

With --scorecard, the fetched OpenSSF Scorecard results (including negative "no data" results) are cached under _scorecard for 24 hours.

Run gosocialcheck info (or gosocialcheck info --json) to inspect the current cache state.

GitHub API rate limit

gosocialcheck uses the GitHub API for the following operations:

• Fetch git tags, via api.github.com.
• Fetch go.mod and go.sum, via https://raw.githubusercontent.com.

These API calls often fails unless the API token is set.

To mitigate the API rate limit, set the token as follows:

1. Open https://github.com/settings/tokens/.
2. Click Generate new token.
3. Generate a token with the following configuration:

• Token name: (arbitrary name, e.g., gosocialcheck)
• Expiration: (arbitrary lifetime, but 365 days at most)
• Repository access: Public repositories
• Account permissions: No access for all.

4. Set the token as $GITHUB_TOKEN.

export GITHUB_TOKEN=...