go-dependency-audit

name	go-dependency-audit
description	Audit Go module dependencies: detect outdated packages, check for known vulnerabilities, review go.mod hygiene, identify unused or redundant deps, and evaluate dependency quality. Use when auditing dependencies, checking for CVEs, cleaning up go.mod, upgrading modules, or evaluating third-party packages. Trigger examples: "check dependencies", "audit deps", "go.mod review", "update modules", "vulnerability scan", "govulncheck". Do NOT use for code-level security issues (use go-security-audit) or architecture review (use go-architecture-review).
license	MIT
metadata	{"version":"1.0.0"}

Go Dependency Audit

Every dependency you add is code you don't control but are responsible for. Audit ruthlessly.

1. Vulnerability Scanning

govulncheck (official Go tool):

# Install
go install golang.org/x/vuln/cmd/govulncheck@latest

# Scan project
govulncheck ./...

# Scan binary
govulncheck -mode=binary ./cmd/api-server

govulncheck checks against the Go vulnerability database and reports only vulnerabilities that actually affect your code paths — not just transitive deps you never call.

Run this in CI. No exceptions.

Additional scanning:

# Nancy (Sonatype OSS Index)
go list -json -deps ./... | nancy sleuth

# Trivy (container + deps)
trivy fs --scanners vuln .

2. go.mod Hygiene

Check for unused dependencies:

go mod tidy
git diff go.mod go.sum  # any changes = deps were stale

go mod tidy MUST be run before every commit. Add to CI:

go mod tidy
git diff --exit-code go.mod go.sum

No replace directives in committed code:

// ❌ Bad — committed replace directive
replace github.com/foo/bar => ../local-bar

// ✅ Acceptable — in monorepos with workspace
// go.work handles this instead

Exception: temporary replace for bug fixes with a comment and linked issue:

// TODO(#1234): remove after upstream merges fix
replace github.com/foo/bar => github.com/myorg/bar v0.0.0-fix

Verify checksums:

go mod verify

This confirms that downloaded modules match their expected checksums. Failures indicate supply-chain tampering.

3. Dependency Evaluation Criteria

Before adding any dependency, evaluate:

Criterion	Check
Maintenance	Last commit < 6 months? Active issue responses?
Popularity	Stars/forks alone mean nothing. Usage in production projects matters.
License	Compatible with your project? MIT/Apache/BSD preferred.
Size	Does it pull in 50 transitive deps for one function?
Alternatives	Can you do this with stdlib in < 50 lines?
API stability	Is it v1+? Does it follow semver? Frequent breaking changes?
Test coverage	Does the project have meaningful tests?

The stdlib question:

Go's standard library is excellent. Before adding a dependency, ask: "Can I solve this with net/http, encoding/json, database/sql, text/template, crypto/*, os/exec, etc.?"

If the answer is yes and the code is < 100 lines, write it yourself.

4. Module Version Audit

List all dependencies with versions:

go list -m all

Check for available updates:

go list -m -u all  # shows available updates

Upgrade strategy:

# Update specific module
go get github.com/foo/bar@latest

# Update all direct deps (minor/patch only)
go get -u ./...

# Update all deps including major versions (dangerous)
go get -u -t ./...

ALWAYS run full test suite after updates:

go get github.com/foo/bar@v1.5.0
go mod tidy
go test -race ./...

5. Transitive Dependency Analysis

# Why is this module in my dependency tree?
go mod why github.com/some/transitive-dep

# Full dependency graph
go mod graph

# Visual dependency graph (with modgraphviz)
go mod graph | modgraphviz | dot -Tpng -o deps.png

Watch for:

• 🔴 Transitive deps with known CVEs
• 🔴 Abandoned transitive deps (no commits in 2+ years)
• 🟡 Diamond dependency conflicts (two versions of same module)
• 🟡 Oversized transitive trees (a logging library pulling in gRPC)

6. Go Version Management

// go.mod
module github.com/myorg/myproject

go 1.22  // minimum Go version required

Rules:

• Set go directive to the minimum version that supports features you use.
• toolchain directive (Go 1.21+) pins the exact toolchain version.
• Test against multiple Go versions in CI (at minimum: current and previous).

7. Recommended vs. Avoid

Well-maintained, production-proven packages:

Domain	Package
Logging	go.uber.org/zap, log/slog (stdlib 1.21+)
HTTP Router	github.com/go-chi/chi, net/http (1.22+ routing)
Config	github.com/caarlos0/env, github.com/spf13/viper
Testing	github.com/stretchr/testify, stdlib testing
Database	github.com/jackc/pgx, github.com/jmoiron/sqlx
Validation	github.com/go-playground/validator
UUID	github.com/google/uuid
Errors	go.uber.org/multierr, stdlib errors (1.20+)

Patterns to avoid:

• ❌ Frameworks that take over main() (Go is not Java Spring)
• ❌ ORMs that hide SQL (prefer sqlx or raw database/sql)
• ❌ Code generators you don't understand
• ❌ Packages with v0.x that have been v0 for 3+ years

Audit Output Format

## Dependency Audit Report

**Module:** github.com/myorg/myproject
**Go version:** 1.22
**Direct deps:** N | **Indirect deps:** M

### 🔴 Vulnerabilities
- CVE-XXXX-YYYY in github.com/foo/bar@v1.2.3 — upgrade to v1.2.5

### 🟡 Outdated Dependencies
- github.com/foo/bar v1.2.3 → v1.5.0 available (minor)

### 🟢 Observations
- go.mod is clean, no replace directives
- All deps actively maintained