go-dependency-audit

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/[email protected]
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/[email protected] — 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