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:

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

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

Overview

Critical Rules

1. Never invent flags or directives - Confirm every go/tool flag against official docs first
2. golangci-lint v2 config MUST start with version: "2" - v1 configs are rejected; migrate, don't hand-edit
3. govulncheck runs in source mode by default - Reachability filters noise; only reported findings matter
4. go.work is usually not committed - Commit only when modules are developed exclusively together
5. 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

Templates

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 Go 1.26 modernizers

→ 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