proposal: cmd/go: go audit

[jitsu-net]

Proposal Details

1. Introduction

I propose adding a new go audit command to the go tool. This command will provide a centralized location for all security-related functionality included with the Go standard library.

I further propose a subcommand go audit vuln which will provide a unified way to check Go modules for known vulnerabilities and other security issues. Crucially, it will build upon the existing govulncheck tool and integrate directly into the main Go distribution.

2. Background

The Go team has made significant investments into vulnerability management, including the Go Vulnerability Database (go/vulndb) and the govulncheck tool. By incorporating the existing capabilities of govulncheck into the new go audit vuln command, vulnerability detection will become a standard, easily accessible part of the Go development workflow.

3. Proposal

The basic invocation of the new command will be as follows:

go audit [subcommand]

Example:
$ go audit vuln ./...

The vuln subcommand will analyze specified packages (or the current directory if none are specified) and report known vulnerabilities and other issues. For now the only subcommand supported will be the vuln command.

3.1. Proposed Flags

Go audit vuln reports known vulnerabilities in dependencies.

Usage:

        go audit vuln [flags] [patterns]
        go audit vuln -mode=binary [flags] [binary]

  -C dir
        change to dir before running vuln
  -format value
        specify format output
        The supported values are 'text', 'json', 'sarif', and 'openvex' (default 'text')
  -json
        output JSON (Go compatible legacy flag, see format flag)
  -mode value
        supports 'source', 'binary', and 'extract' (default 'source')
  -scan value
        set the scanning level desired, one of 'module', 'package', or 'symbol' (default 'symbol')
  -show list
        enable display of additional information specified by the comma separated list
        The supported values are 'traces','color', 'version', and 'verbose'
  -tags list
        comma-separated list of build tags
  -test
        analyze test files (only valid for source mode, default false)

See https://golang.org/ref/audit#go-audit-vuln for more about 'go audit vuln'.

3.2. Scope of Audit

Go vet must always produce actionable information. It can never produce false positives. Go audit exists as a separate space where “more fuzzy” “code health” analyzers may require human review. Where go vet would prevent compilation, go audit would suggest to the user possible actions to take in regards to code health.

Initially, go audit will focus on vulnerability detection, effectively being an integration of govulncheck. In the future, its scope could be expanded to include:

• Dependency health: Checking for outdated or deprecated dependencies.
• Best practices: Enforcing best practices for go.mod files and other aspects of Go modules.
• License compliance: Auditing licenses of dependencies.
• Coding Style: Checking for code style standards and best practices related to security
• Modernizations: Checking for modernizations impacting security

3.3. Vulnerability Database

To align with standard Go toolchain best practices, the legacy govulncheck flag -db (previously used to override the default vulnerability database URL at https://vuln.go.dev) is removed. Instead, go audit vuln will read from the GOVULNDB environment variable to configure or override the target vulnerability database URL.

[seankhliao]

Is this going to be vendoring x/vuln codebase into cmd/go?
Or building / invoking govulncheck or another command like how go doc does -http?

[thatnealpatel]

We should certainly try our best to not vendor x/vuln
into cmd/go; it would be preferable to align it with the
existing subcommands.

It seems reasonable to me to build the functionality we want
to lift directly into the idioms in cmd/go and effectively freeze
govulncheck, perhaps even adding a TUI banner of sorts to
hint at redirecting usage to go audit ....

We could even implement x/vuln/cmd/govulncheck in terms
go audit ... by using literal subprocess execution, though
that's likely a discussion outside the scope of this proposal.

[jeanbza]

Is there intended to be other subcommands besides vuln? If we intend to leave it open for future sub-commands, could you share some hypothetical ideas?

---

I will mention one awkwardness: as mentioned in #79896 and implemented as a reference in https://github.com/Netflix-Skunkworks/govulncheck-apply/, it'd be nice to "apply" govulncheck's findings.

Presumedly that would then be go audit vuln apply or something like that. audit makes this a bit awkward: audit feels like a read-only action, whereas any way we follow that by telling vuln to "fix" or "apply" is going to be a write action.

---

Merging my first and two questions: would it make sense for this just to be go vuln?

If the motivation is, "vulnerability detection will become a standard, easily accessible part of the Go development workflow.", then this seems to do just as well without the awkwardness.

But like I mention above, I might be missing some motivating ideas about other... uh, first level?... sub-commands. Let me know if so. =)

[seankhliao]

I've been wondering, but why can't vulncheck functionality be just another analysis pass that can fit in to vet / fix?

[jeanbza]

I've been wondering, but why can't vulncheck functionality be just another analysis pass that can fit in to vet / fix?

That's a neat idea. I think it'd be nice to express it that way.

But, I think that analysis.Analyzers are built to operate on code: https://pkg.go.dev/golang.org/x/tools/go/analysis#Analyzer. Notable issues that I'd expect there to be with trying to do vuln remediation there:

• They operate on source files, not a build list¹.
• They operate at package level, not module level¹.
• They appear to be run with AST information. With vuln remediation, you'd want a mode that doesn't attempt to scan source code (like -scan=module or -scan=package) to avoid all the classes of compilation issues you'd have to deal with.

I have not tried building an analyzer though so could be mistaken.

Footnotes

1. Well, to be fair their Pass has a Module so maybe you could construct a build list? I don't know. ↩ ↩²

[jitsu-net]

I've been wondering, but why can't vulncheck functionality be just another analysis pass that can fit in to vet / fix?

From the proposal, Section "3.2 Scope of Audit":

Go vet must always produce actionable information. It can never produce false positives. Go audit exists as a separate space where “more fuzzy” “code health” analyzers may require human review. Where go vet would prevent compilation, go audit would suggest to the user possible actions to take in regards to code health.