README

Extended "nogo" analysis

This package provides a build aspect that perform nogo analysis. This will be automatically injected to all relevant libraries when using the default go_binary and go_library rules.

It exists for several reasons.

• The default nogo provided by bazel is insufficient with respect to the possibility of binary analysis. This package allows us to analyze the generated binary in addition to using the standard analyzers.

• The configuration provided in this package is much richer than the standard nogo JSON blob. Specifically, it allows us to exclude specific structures from the composite rules (such as the Ranges that are common with the set types).

• The bazel version of nogo is run directly against the go_library and go_binary targets, meaning that any change to the configuration requires a rebuild from scratch (for some reason included all C++ source files in the process). Using an aspect is more efficient in this regard.

• The checks supported by this package are exported as tests, which makes it easier to reason about and plumb into the build system.

• For uninteresting reasons, it is impossible to integrate the default nogo analyzer provided by bazel with internal Google tooling. To provide a consistent experience, this package allows those systems to be unified.

To use this package, import nogo_test from defs.bzl and add a single dependency which is a go_binary or go_library rule.

Documentation

Overview

Package nogo implements binary analysis similar to bazel's nogo, or the unitchecker package. It exists in order to provide additional facilities for analysis, namely plumbing through the output from dumping the generated binary (to analyze actual produced code).

Index

• Variables
• func WriteFindingsToBytes(findings []Finding) ([]byte, error)
• func WriteFindingsToFile(findings []Finding, filename string) error
• type AnalyzerConfig
• type AnalyzerName
• type Config
  • func (c *Config) Compile() error
  • func (c *Config) Merge(other *Config)
  • func (c *Config) ShouldReport(finding Finding) bool
• type Finding
  • func CheckPackage(config *PackageConfig, analyzers []*analysis.Analyzer, ...) (findings []Finding, factData []byte, err error)
  • func CheckStdlib(config *StdlibConfig, analyzers []*analysis.Analyzer) (allFindings []Finding, facts []byte, err error)
  • func ExtractFindingsFromBytes(content []byte) (findings []Finding, err error)
  • func ExtractFindingsFromFile(filename string) ([]Finding, error)
  • func (f *Finding) String() string
• type Group
• type GroupName
• type ItemConfig
• type PackageConfig
• type StdlibConfig

Constants

This section is empty.

Variables

var AllAnalyzers = []*analysis.Analyzer{
	asmdecl.Analyzer,
	assign.Analyzer,
	atomic.Analyzer,
	bools.Analyzer,
	buildtag.Analyzer,
	cgocall.Analyzer,
	composite.Analyzer,
	copylock.Analyzer,
	errorsas.Analyzer,
	httpresponse.Analyzer,
	loopclosure.Analyzer,
	lostcancel.Analyzer,
	nilfunc.Analyzer,
	nilness.Analyzer,
	printf.Analyzer,
	shift.Analyzer,
	stdmethods.Analyzer,
	stringintconv.Analyzer,
	shadow.Analyzer,
	structtag.Analyzer,
	tests.Analyzer,
	unmarshal.Analyzer,
	unreachable.Analyzer,
	unsafeptr.Analyzer,
	unusedresult.Analyzer,
	checkescape.Analyzer,
	checkunsafe.Analyzer,
	checklocks.Analyzer,
}

AllAnalyzers is a list of all available analyzers.

var ErrSkip = errors.New("skipped")

ErrSkip indicates the package should be skipped.

Functions

func WriteFindingsToBytes

func WriteFindingsToBytes(findings []Finding) ([]byte, error)

WriteFindingsToBytes serializes findings as bytes.

func WriteFindingsToFile

func WriteFindingsToFile(findings []Finding, filename string) error

WriteFindingsToFile writes findings to a file.

Types

type AnalyzerConfig

type AnalyzerConfig map[GroupName]*ItemConfig

AnalyzerConfig is the configuration for a single analyzers.

This map is keyed by individual Group names, to allow for different configurations depending on what Group the file belongs to.

type AnalyzerName

type AnalyzerName string

AnalyzerName is a named analyzer.

type Config

type Config struct {
	// Prefixes defines a set of regular expressions that
	// are standard "prefixes", so that files can be grouped
	// and specific rules applied to individual groups.
	Groups []Group `yaml:"groups"`

	// Global is the global analyzer config.
	Global AnalyzerConfig `yaml:"global"`

	// Analyzers are individual analyzer configurations. The
	// key for each analyzer is the name of the analyzer. The
	// value is either a boolean (enable/disable), or a map to
	// the groups above.
	Analyzers map[AnalyzerName]AnalyzerConfig `yaml:"analyzers"`
}

Config is a nogo configuration.

func (*Config) Compile

func (c *Config) Compile() error

Compile compiles a configuration to make it useable.

func (*Config) Merge

func (c *Config) Merge(other *Config)

Merge merges two configurations.

func (*Config) ShouldReport

func (c *Config) ShouldReport(finding Finding) bool

ShouldReport returns true iff the finding should match the Config.

type Finding

type Finding struct {
	Category AnalyzerName
	Position token.Position
	Message  string
}

Finding is a single finding.

func CheckPackage

func CheckPackage(config *PackageConfig, analyzers []*analysis.Analyzer, importCallback func(string) error) (findings []Finding, factData []byte, err error)

CheckPackage runs all given analyzers.

The implementation was adapted from [1], which was in turn adpated from [2]. This returns a list of matching analysis issues, or an error if the analysis could not be completed.

[1] bazelbuid/rules_go/tools/builders/nogo_main.go [2] golang.org/x/tools/go/checker/internal/checker

func CheckStdlib

func CheckStdlib(config *StdlibConfig, analyzers []*analysis.Analyzer) (allFindings []Finding, facts []byte, err error)

CheckStdlib checks the standard library.

This constructs a synthetic package configuration for each library in the standard library sources, and call CheckPackage repeatedly.

Note that not all parts of the source are expected to build. We skip obvious test files, and cmd files, which should not be dependencies.

func ExtractFindingsFromBytes

func ExtractFindingsFromBytes(content []byte) (findings []Finding, err error)

ExtractFindingsFromBytes loads findings from bytes.

func ExtractFindingsFromFile

func ExtractFindingsFromFile(filename string) ([]Finding, error)

ExtractFindingsFromFile loads findings from a file.

func (*Finding) String

func (f *Finding) String() string

String implements fmt.Stringer.String.

type Group

type Group struct {
	// Name is the short name for the group.
	Name GroupName `yaml:"name"`

	// Regex matches all full paths in the group.
	Regex string `yaml:"regex"`

	// Default determines the default group behavior.
	//
	// If Default is true, all Analyzers are enabled for this
	// group. Otherwise, Analyzers must be individually enabled
	// by specifying a (possible empty) ItemConfig for the group
	// in the AnalyzerConfig.
	Default bool `yaml:"default"`
	// contains filtered or unexported fields
}

Group represents a named collection of files.

type GroupName

type GroupName string

GroupName is a named group.

type ItemConfig

type ItemConfig struct {
	// Exclude are analyzer exclusions.
	//
	// Exclude is a list of regular expressions. If the corresponding
	// Analyzer emits a Finding for which Finding.Position.String()
	// matches a regular expression in Exclude, the finding will not
	// be reported.
	Exclude []string `yaml:"exclude,omitempty"`

	// Suppress are analyzer suppressions.
	//
	// Suppress is a list of regular expressions. If the corresponding
	// Analyzer emits a Finding for which Finding.Message matches a regular
	// expression in Suppress, the finding will not be reported.
	Suppress []string `yaml:"suppress,omitempty"`
	// contains filtered or unexported fields
}

ItemConfig is an (Analyzer,Group) configuration.

type PackageConfig

type PackageConfig struct {
	ImportPath  string
	GoFiles     []string
	NonGoFiles  []string
	Tags        []string
	GOOS        string
	GOARCH      string
	ImportMap   map[string]string
	FactMap     map[string]string
	StdlibFacts string
}

PackageConfig is serialized as the configuration.

This contains everything required for single package analysis.

type StdlibConfig

type StdlibConfig struct {
	Srcs   []string
	GOOS   string
	GOARCH string
	Tags   []string
}

StdlibConfig is serialized as the configuration.

This contains everything required for stdlib analysis.