analyzer

Documentation

Index

• Constants
• func CapabilityGraph(pkgs []*packages.Package, queriedPackages map[*types.Package]struct{}, ...)
• func GetCapabilityCounts(pkgs []*packages.Package, queriedPackages map[*types.Package]struct{}, ...) *cpb.CapabilityCountList
• func GetCapabilityInfo(pkgs []*packages.Package, queriedPackages map[*types.Package]struct{}, ...) *cpb.CapabilityInfoList
• func GetCapabilityStats(pkgs []*packages.Package, queriedPackages map[*types.Package]struct{}, ...) *cpb.CapabilityStatList
• func GetClassifier(excludeUnanalyzed bool) *interesting.Classifier
• func GetQueriedPackages(pkgs []*packages.Package) map[*types.Package]struct{}
• func LoadPackages(packageNames []string, lcfg LoadConfig) ([]*packages.Package, error)
• func RunCapslock(args []string, output string, pkgs []*packages.Package, ...) error
• type CapabilityCounter
• type CapabilitySet
  • func NewCapabilitySet(cs string) (*CapabilitySet, error)
  • func (cs *CapabilitySet) Has(c cpb.Capability) bool
• type Classifier
• type Config
• type DifferenceFoundError
  • func (d DifferenceFoundError) Error() string
• type Granularity
  • func GranularityFromString(g string) (Granularity, error)
• type GraphOutputCallFn
• type GraphOutputCapabilityFn
• type GraphOutputNodeFn
• type LoadConfig

Constants

const PackagesLoadModeNeeded packages.LoadMode = packages.NeedName |
	packages.NeedFiles |
	packages.NeedCompiledGoFiles |
	packages.NeedImports |
	packages.NeedDeps |
	packages.NeedTypes |
	packages.NeedSyntax |
	packages.NeedTypesInfo |
	packages.NeedTypesSizes |
	packages.NeedModule

PackagesLoadModeNeeded is a packages.LoadMode that has all the bits set for the information that this package uses to perform its analysis. Users should load packages for analysis using this LoadMode (or a superset.)

Functions

func CapabilityGraph

func CapabilityGraph(pkgs []*packages.Package,
	queriedPackages map[*types.Package]struct{},
	config *Config,
	outputNode GraphOutputNodeFn,
	outputCall GraphOutputCallFn,
	outputCapability GraphOutputCapabilityFn,
	filter func(capability cpb.Capability) bool,
)

CapabilityGraph analyzes the callgraph for the packages in pkgs.

It outputs the graph containing all paths from a function belonging to one of the packages in queriedPackages to a function which has some capability.

outputNode is called for each node in the graph. Along with the node itself, it is passed the state of the BFS search from the queried packages, and the state of the BFS search from functions with a capability, so that the user can reconstruct an example call path including the node.

outputCall is called for each edge between two nodes.

outputCapability is called for each node in the graph that has some capability.

If filter is non-nil, it is called once for each capability. If it returns true, then CapabilityGraph generates a call graph for that individual capability and calls the relevant output functions, before proceeding to the next capability. If filter is nil, a single graph is generated including paths for all capabilities.

func GetCapabilityCounts

func GetCapabilityCounts(pkgs []*packages.Package, queriedPackages map[*types.Package]struct{}, config *Config) *cpb.CapabilityCountList

GetCapabilityCount analyzes the packages in pkgs. For each function in those packages which have a path in the callgraph to an "interesting" function (see the "interesting" package), we give an aggregate count of the capability usage.

func GetCapabilityInfo

func GetCapabilityInfo(pkgs []*packages.Package, queriedPackages map[*types.Package]struct{}, config *Config) *cpb.CapabilityInfoList

GetCapabilityInfo analyzes the packages in pkgs. It finds functions in those packages that have a path in the callgraph to a function with a capability.

GetCapabilityInfo does not return every possible path (see the function CapabilityGraph for a way to get all paths). Which entries are returned depends on the value of Config.Granularity:

• For "function" granularity (the default), one CapabilityInfo is returned for each combination of capability and function in pkgs.
• For "package" granularity, one CapabilityInfo is returned for each combination of capability and package in pkgs.
• For "intermediate" granularity, one CapabilityInfo is returned for each combination of capability and package that is in a path from a function in pkgs to a function with a capability.

func GetCapabilityStats

func GetCapabilityStats(pkgs []*packages.Package, queriedPackages map[*types.Package]struct{}, config *Config) *cpb.CapabilityStatList

GetCapabilityStats analyzes the packages in pkgs. For each function in those packages which have a path in the callgraph to an "interesting" function (see the "interesting" package), we give aggregated statistics about the capability usage.

func GetClassifier

func GetClassifier(excludeUnanalyzed bool) *interesting.Classifier

GetClassifier returns a classifier for mapping packages and functions to the appropriate capability. If excludedUnanalyzed is true, the UNANALYZED capability is never returned.

func GetQueriedPackages

func GetQueriedPackages(pkgs []*packages.Package) map[*types.Package]struct{}

GetQueriedPackages builds a set of *types.Package matching the input query so that we can limit the output to only functions in these packages, not their dependencies too.

func LoadPackages

func LoadPackages(packageNames []string, lcfg LoadConfig) ([]*packages.Package, error)

func RunCapslock

func RunCapslock(args []string, output string, pkgs []*packages.Package, queriedPackages map[*types.Package]struct{},
	config *Config) error

Types

type CapabilityCounter

type CapabilityCounter struct {
	// contains filtered or unexported fields
}

type CapabilitySet

type CapabilitySet struct {
	// contains filtered or unexported fields
}

CapabilitySet represents a set of Capslock capabilities. A nil *CapabilitySet represents the set of all capabilities.

func NewCapabilitySet

func NewCapabilitySet(cs string) (*CapabilitySet, error)

NewCapabilitySet returns a *CapabilitySet parsed from a string.

If cs is empty, a nil *CapabilitySet is returned, which represents the set of all capabilities. Otherwise, cs should be a comma-separated list of capabilities. Optionally, all capabilities can be prefixed with '-' to specify the capabilities to exclude from the set.

func (*CapabilitySet) Has

func (cs *CapabilitySet) Has(c cpb.Capability) bool

Has returns whether c is a member of cs.

type Classifier

type Classifier interface {
	// FunctionCategory returns a Category for the given function specified by
	// a package name and function name.  Examples of function names include
	// "math.Cos", "(time.Time).Clock", and "(*sync.Cond).Signal".
	//
	// If the return value is Unspecified, then we have not declared it to be
	// either safe or unsafe, so its descendants will have to be considered by the
	// static analysis.
	FunctionCategory(pkg string, name string) cpb.Capability

	// IncludeCall returns true if a call from one function to another should be
	// considered when searching for transitive capabilities.  Usually this should
	// return true, unless there is some reason to know that the particular call
	// cannot lead to additional capabilities for a function.
	IncludeCall(edge *callgraph.Edge) bool
}

Classifier is an interface for types that help map code features to capabilities.

type Config

type Config struct {
	// Classifier is used to assign capabilities to functions.
	Classifier Classifier
	// DisableBuiltin disables some additional source-code analyses that find
	// more capabilities in functions.
	DisableBuiltin bool
	// Granularity determines whether capability sets are examined per-package
	// or per-function when doing comparisons.
	Granularity Granularity
	// CapabilitySet is the set of capabilities to use for graph output mode.
	// If CapabilitySet is nil, all capabilities are used.
	CapabilitySet *CapabilitySet
	// OmitPaths disables output of example call paths.
	OmitPaths bool
}

Config holds configuration for the analyzer.

type DifferenceFoundError

type DifferenceFoundError struct{}

DifferenceFoundError indicates that a comparison was successfully run, and a difference was found.

func (DifferenceFoundError) Error

func (d DifferenceFoundError) Error() string

type Granularity

type Granularity int8

Granularity determines the kind of comparison done by compare.

const (
	GranularityUnset        Granularity = iota // use default granularity
	GranularityPackage                         // compare capabilities per package
	GranularityFunction                        // compare capabilities per function
	GranularityIntermediate                    // compare capabilities per intermediate package
)

func GranularityFromString

func GranularityFromString(g string) (Granularity, error)

type GraphOutputCallFn

type GraphOutputCallFn func(edge *callgraph.Edge)

GraphOutputCallFn represents a function which is called by CapabilityGraph for each edge.

type GraphOutputCapabilityFn

type GraphOutputCapabilityFn func(fn *callgraph.Node, c cpb.Capability)

GraphOutputCapabilityFn represents a function which is called by CapabilityGraph for each function capability.

type GraphOutputNodeFn

type GraphOutputNodeFn func(fromQuery bfsStateMap, node *callgraph.Node, toCapability bfsStateMap)

GraphOutputNodeFn represents a function which is called by CapabilityGraph for each node.

type LoadConfig

type LoadConfig struct {
	BuildTags string
	GOOS      string
	GOARCH    string
}

LoadConfig specifies the build tags, GOOS value, and GOARCH value to use when loading packages. These will be used to determine when a file's build constraint is satisfied. See https://pkg.go.dev/cmd/go#hdr-Build_constraints for more information.