go-tooling-security

Go Tooling & Security

Agent Workflow (MANDATORY)

Before ANY tooling/security change, spawn 3 agents in parallel, one Agent call each with a name:

fuse-ai-pilot:explore-codebase - Find existing go.mod/go.work, .golangci.yml, CI files
fuse-ai-pilot:research-expert - Verify latest golangci-lint v2 + govulncheck docs via Context7/Exa
mcp__context7__query-docs - Check current Go 1.27 go fix modernizer set

After changes, run fuse-ai-pilot:sniper for validation.

Overview

Area	Description
Modules & Workspaces	`go.mod` directives, `go.work` for multi-module dev without `replace`
golangci-lint v2	Config version `"2"`, `formatters` section, `golangci-lint migrate`
govulncheck	Reachability-based scan of the call graph against `vuln.go.dev`
go fix modernizers	Suite of fixers (rebuilt in 1.26, extended in 1.27), `//go:fix inline` for API migrations
CI quality gate	fmt → vet → golangci-lint → govulncheck → test -race

Critical Rules

Never invent flags or directives - Confirm every go/tool flag against official docs first
golangci-lint v2 config MUST start with version: "2" - v1 configs are rejected; migrate, don't hand-edit
govulncheck runs in source mode by default - Reachability filters noise; only reported findings matter
go.work is usually not committed - Commit only when modules are developed exclusively together
CI gate order is fail-fast - Formatting/vet before linters before vulnerability scan before tests

Architecture

repo/
├── go.work                 # optional: multi-module workspace
├── go.work.sum
├── module-a/
│   ├── go.mod              # module, go, require, toolchain
│   └── go.sum
├── module-b/
│   └── go.mod
├── .golangci.yml           # version: "2"
└── .github/workflows/ci.yml

→ See ci-workflow.md for the complete gate

Reference Guide

Concepts

Topic	Reference	When to Consult
Modules & Workspaces	modules-workspaces.md	Editing go.mod/go.work, multi-module repos
golangci-lint v2	golangci-lint-v2.md	Config, v1→v2 migration, formatters
govulncheck	govulncheck.md	Dependency vulnerability scanning
go fix modernizers	go-fix-modernizers.md	Modernizing code, `//go:fix inline`, PGO

Templates

Template	When to Use
golangci-v2-config.md	Dropping in a recommended `.golangci.yml`
ci-workflow.md	Wiring the full CI quality gate

Quick Reference

Workspace bootstrap

go work init ./module-a ./module-b   # create go.work
go work use ./module-c               # add a module
go work sync                         # sync build list to modules

→ See modules-workspaces.md

Migrate + run golangci-lint v2

golangci-lint migrate                # v1 config → v2 (backs up original)
golangci-lint run ./...

→ See golangci-v2-config.md

Scan for reachable vulnerabilities

go install golang.org/x/vuln/cmd/govulncheck@latest
govulncheck ./...                    # source mode, call-graph reachability

→ See govulncheck.md

Modernize the codebase

go fix ./...                         # apply the modernizer suite (1.27 set)

→ See go-fix-modernizers.md

Best Practices

DO

Pin toolchain with the toolchain directive for reproducible builds
Gate CI on govulncheck ./... and treat reachable findings as failures
Use go.work for local cross-module work instead of scattering replace directives
Keep formatters (gofmt/goimports) separate from linters in the v2 config

DON'T

Hand-write a v2 config from a v1 file — run golangci-lint migrate
Commit go.work in repos whose modules are also developed with external modules
Suppress govulncheck findings without confirming the vulnerable symbol is unreachable
Assume go vet/gofmt changed in 1.26 — the 1.26 change is go fix, not those
Forget that since 1.27 go test runs the stdversion vet check by default (reports stdlib symbols newer than the file's go version)