summaries

Documentation

Overview

Package summaries defines how data flow information can be summarized for a given function. These summaries are only for pre-determined functions (e.g. standard library functions) and are not computed during the analysis.

Index

• Variables
• func IsStdFunction(function *ssa.Function) bool
• func IsStdPackageName(name string) bool
• func IsSummaryRequired(function *ssa.Function) bool
• func IsUserDefinedFunction(function *ssa.Function) bool
• func PkgHasSummaries(pkg *ssa.Package) bool
• type ArgumentSNode
  • func (a ArgumentSNode) String() string
  • func (a ArgumentSNode) WithObjectPath(path string) SummaryNode
• type DetailedSummary
  • func (s DetailedSummary) GetArgFlows(f *ssa.Function) ([][]int, error)
  • func (s DetailedSummary) GetReturnFlows(f *ssa.Function) ([][]int, error)
• type RawSummary
  • func (s RawSummary) Compile() (DetailedSummary, error)
  • func (s RawSummary) MustCompile() DetailedSummary
• type ReceiverSNode
  • func (r ReceiverSNode) String() string
  • func (r ReceiverSNode) WithObjectPath(path string) SummaryNode
• type ReturnSNode
  • func (r ReturnSNode) String() string
  • func (r ReturnSNode) WithObjectPath(path string) SummaryNode
• type Summarizer
  • func SummaryOfFunc(function *ssa.Function) (Summarizer, bool)
• type Summary
  • func (s Summary) GetArgFlows(_ *ssa.Function) ([][]int, error)
  • func (s Summary) GetReturnFlows(_ *ssa.Function) ([][]int, error)
• type SummaryNode
  • func ParseSummaryNode(summary string) (SummaryNode, error)

Variables

var FormatterPropagation = Summary{Args: [][]int{{0}, {1}}, Rets: [][]int{{0}, {0}}}

FormatterPropagation is a summary for functions like Printf where the first and second arguments might be tainted, and this will taint the returned value (for example: an error, a string with Sprintf).

var NoDataFlowPropagation = Summary{Rets: [][]int{}, Args: [][]int{}}

NoDataFlowPropagation is a summary for functions that do not have a data flow. The return value, if used, is a sanitized value.

var SingleVarArgPropagation = Summary{Args: [][]int{{0}}, Rets: [][]int{{0}}}

SingleVarArgPropagation is a summary for functions that have a single (possibly variadic) argument (func f(arg ..any) any {...}) This will propagate the data flow to the return value.

var SingleVarArgTwoRetsPropagation = Summary{Args: [][]int{{0}}, Rets: [][]int{{0, 1}}}

SingleVarArgTwoRetsPropagation is a summary for functions that have a single variadic argument (func f(arg ..any) (any,any) {...}) This will propagate the data flow to both return values.

var TwoArgPropagation = Summary{Args: [][]int{{0}, {1}}, Rets: [][]int{{0}, {0}}}

TwoArgPropagation is a summary for functions that have two arguments and both propagate their data to the return value, but there is no dataflow between arguments.

var TwoArgReceivePropagation = Summary{Args: [][]int{{0}, {1}}, Rets: [][]int{{0}, {0}}}

TwoArgReceivePropagation is a summary for functions that have two arguments and both propagate their data to the return value, and the second argument propagates to the first (typically, functions where the first argument is the receiver)

Functions

func IsStdFunction

func IsStdFunction(function *ssa.Function) bool

IsStdFunction returns true if the input function is a function from the standard library or the runtime.

Returns false if the input is nil.

func IsStdPackageName

func IsStdPackageName(name string) bool

IsStdPackageName returns true if the package name is a package of the standard library

func IsSummaryRequired

func IsSummaryRequired(function *ssa.Function) bool

IsSummaryRequired returns true if the summary of function is needed to build a sound analysis. For example, sync.Once.Do needs to be summarized because its argument will be called only inside the function, and therefore, it cannot be stubbed out.

func IsUserDefinedFunction

func IsUserDefinedFunction(function *ssa.Function) bool

IsUserDefinedFunction returns true when function is a user-defined function. A function is considered to be user-defined if it is not in the standard library (in summaries.stdPackages) or in the runtime. For example, the functions in the non-standard library packages are considered user-defined.

func PkgHasSummaries

func PkgHasSummaries(pkg *ssa.Package) bool

PkgHasSummaries returns true if the input package has summaries. A package has summaries if it is present in the stdPackages.

Returns false if the input package is nil.

Types

type ArgumentSNode

type ArgumentSNode struct {
	Name       string
	Index      int
	ObjectPath string
}

ArgumentSNode is the summary node that corresponds to a argument node. An argument node should be specified with either its name or its index. Because we represent receivers separately, the index is the parameter index is counted from the first non-receiver argument of the function.

func (ArgumentSNode) String

func (a ArgumentSNode) String() string

Repr returns the repr of an argument node, which is either !arg i where i is an integer or !arg <name> where name is a string, which must be between < and >. If the object path is not empty then the base object is wrapped in parentheses and the object path is appended.

func (ArgumentSNode) WithObjectPath

func (a ArgumentSNode) WithObjectPath(path string) SummaryNode

WithObjectPath returns the argument node with the specified object path. The original object path is ignored.

type DetailedSummary

type DetailedSummary struct {
	Flows map[SummaryNode][]SummaryNode
}

A DetailedSummary is a more human-friendly and more precise version of a summary.

func (DetailedSummary) GetArgFlows

func (s DetailedSummary) GetArgFlows(f *ssa.Function) ([][]int, error)

GetArgFlows returns the indexed flows from parameters to returns of the detailed summary.

func (DetailedSummary) GetReturnFlows

func (s DetailedSummary) GetReturnFlows(f *ssa.Function) ([][]int, error)

GetReturnFlows returns the indexed flows from parameter to returns of the detailed summary.

type RawSummary

type RawSummary struct {
	Flows map[string][]string
}

RawSummary is a summary of flows for a function where the flow nodes still need to be parsed into SummaryNode to form a DetailedSummary. A RawSUmmary is not a Summarizer; it needs to be compiled first.

func (RawSummary) Compile

func (s RawSummary) Compile() (DetailedSummary, error)

Compile parses the raw summary as a map from string representation of summary nodes to list of summary nodes to its parsed version using structs.

func (RawSummary) MustCompile

func (s RawSummary) MustCompile() DetailedSummary

MustCompile is the version of IntoDetailedSummary that panics instead of returning an error.

type ReceiverSNode

type ReceiverSNode struct {
	ObjectPath string
}

ReceiverSNode is the suymmary that corresponds to a receiver. A receiver is a special parameter that is the receiver of a method.

func (ReceiverSNode) String

func (r ReceiverSNode) String() string

Repr returns the string representation of the node. The returned string can be parsed back using ParseSummaryNode

func (ReceiverSNode) WithObjectPath

func (r ReceiverSNode) WithObjectPath(path string) SummaryNode

WithObjectPath returns the receiver node with the specified object path, ignoring the original object path.

type ReturnSNode

type ReturnSNode struct {
	Index      int
	ObjectPath string
}

ReturnSNode is the summary node that corresponds to the return, with an index specifying the element of the tuple.

func (ReturnSNode) String

func (r ReturnSNode) String() string

Repr returns the string representation of the node. It always return the index reprsentation of the node, although the parsing function also accepts the syntax "!ret" as short for "!ret 0"

func (ReturnSNode) WithObjectPath

func (r ReturnSNode) WithObjectPath(path string) SummaryNode

WithObjectPath returns the return node with the specified object path, ignoring the original object path.

type Summarizer

type Summarizer interface {
	// GetArgFlows returns a matrix of integers that represent the directed flow edges betwen the functions
	// argument indices.
	GetArgFlows(f *ssa.Function) ([][]int, error)
	// GetReturnFlows returns a matrix of integers that reprsent the directed flow edges between the function's
	// arguments and the return tuple indices
	GetReturnFlows(f *ssa.Function) ([][]int, error)
}

A Summarizer is a summary that exposes the necessary functionality to build a dataflow summary from it. The basic Summary and the DetailedSummary expose this interface.

func SummaryOfFunc

func SummaryOfFunc(function *ssa.Function) (Summarizer, bool)

SummaryOfFunc returns the summary of function and true if function has a summary, otherwise it returns an empty summary and false.

Returns (Summary{}, false) if function is nil.

type Summary

type Summary struct {
	// Args is an array A that maps input argument positions to the arguments that are tainted
	// if the input argument is tainted. For example,  A[0] = [0,1] means that if the first argument
	// of the function is tainted, then when the function returns, the first and the last argument
	// are tainted. TODO word this better for data flows (and not taints)
	// A[1] = [] means that the second argument is sanitized.
	// A[1] = [1] means that the taint on the second argument is conserved, but no other argument is tainted.
	Args [][]int
	// Rets is an array A that links information between input arguments and outputs.
	// A[0] = [0] marks a data flow from argument 0 to the first returned value.
	Rets [][]int
}

Summary summarizes data flow information for a function. This makes an analysis faster because it does not have to compute this information for the pre-summarized functions.

func (Summary) GetArgFlows

func (s Summary) GetArgFlows(_ *ssa.Function) ([][]int, error)

GetArgFlows for the summary simply returns the Args field.

func (Summary) GetReturnFlows

func (s Summary) GetReturnFlows(_ *ssa.Function) ([][]int, error)

GetReturnFlows for the summary simply returns the Rets field.

type SummaryNode

type SummaryNode interface {
	fmt.Stringer
	WithObjectPath(path string) SummaryNode
}

A SummaryNode is a dataflow node that can be specified in a summary: Those nodes are: - receiver nodes, - argument nodes, - return nodes. Typically we do not allow to express internal call nodes in the summary.

func ParseSummaryNode

func ParseSummaryNode(summary string) (SummaryNode, error)

ParseSummaryNode parses the string representation of a summary node. A summary node is represented by a string (<base>)objectPath, or <base> where base can be:

- !receiver for a receiver, - !arg "name" for an argument selected by name, - !arg i for an argument selected by index i, - !ret i for a return, where i is the tuple index.

The objectPath is the field or array path specifier, always after a closing parenthesis.