soaap

package module
v0.0.0-...-405f224 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 15, 2019 License: BSD-2-Clause Imports: 10 Imported by: 3

README

gosoaap

A Go library for working with SOAAP results, as they are emitted by the SOAAP tool in the textual JSON format.

Installation

  1. Install Go

  2. FreeBSD: pkg install go

  3. Mac OS X: brew install go

  4. From source

  5. Set the GOPATH environment variable, e.g.:

    $ export GOPATH=$HOME/.go

  6. Fetch and build this repository:

    $ go get github.com/CTSRD-SOAAP/gosoaap

Commands

The library includes some command-line tools:

soaap-parse

This tool parses the JSON output from SOAAP and converts it to a binary format that other Go SOAAP tools can read. The .gob file extension (see gob package documentation) is recommended so that other tools can detect the use of the binary format without having to examine the file itself:

$ soaap-parse --output=soaap.gob soaap-output.json
soaap-graph

This tool opens a JSON or .gob file and converts it to a call graph in the GraphViz DOT format. It currently only supports graphing the calls reachable from SOAAP past-vulnerability warnings. Usage:

$ soaap-graph --output=soaap.dot soaap.gob
$ dot -Tpdf -o soaap.pdf soaap.dot

Library API

API documentation can be viewed at godoc.org.

Documentation

Overview

Library for working with SOAAP results.

See:

Index

Constants

View Source 
const (
	Contained   = "#ffff33"
	PrivateData = "#3399ff"
	Sandboxed   = "#66ff66"
	Unspecified = "#999999"
	Vulnerable  = "#ff6666"
)

Colours that represent different kinds of sandboxes, data, etc.

Variables

This section is empty.

Functions

func GraphAnalyses 

func GraphAnalyses() []string

func UpdateCalls 

func UpdateCalls(current *[]Call, calls ...Call)

Types

type Analyser 

type Analyser func(*CallGraph) (CallGraph, error)

A function that can produce a CallGraph when given a CallGraph.

type CVE 

type CVE struct {
	ID string
}

func (CVE) String 

func (c CVE) String() string

type Call 

type Call struct {
	// Identifier of the caller.
	Caller string

	// Identifier of the callee.
	Callee string

	// Location of the call.
	CallSite SourceLocation

	// The name of the sandbox the call is occurring in
	// (or the empty string if unsandboxed).
	Sandbox string
}

func (Call) Dot 

func (c Call) Dot(graph CallGraph, weight int, flow bool) string

Output GraphViz for a Call.

func (Call) String 

func (c Call) String() string

type CallGraph 

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

func ApplyAnalysis 

func ApplyAnalysis(spec string, cg *CallGraph, results *Results,
	depth int, report func(string)) (CallGraph, error)

Apply an analysis to a CallGraph using an already-loaded Results file.

Possible analyses include:

  • "+graphtype": union with "graphtype" from the Results
  • "^graphtype": intersection with "graphtype" from the Results
  • ".graphtype": union-of-intersection with "graphtype"
  • ":spec": filter leaf nodes according to "spec" (see Filter)

where "graphtype" can be:

  • vuln: the callgraph of previously-vulnerable code
  • privaccess: the call-and-data-flow graph of access to private data

func Filter 

func Filter(cg CallGraph, spec string) (CallGraph, error)

Filter a graph according to a colon-separated list of filter specifications, where each element can be:

  • "*": add all leaf nodes in the graph
  • "+regex": keep leaf nodes that match a pattern
  • "-regex": remove leaf nodes that match a pattern

Examples: 

":*:-foo:-bar" keeps all leaf nodes except "foo" and "bar"

":+.*foo.*:+.*bar.*" keeps only those leaf nodes (plus ancestors)
with "foo" and "bar" in their names

func Legend 

func Legend() CallGraph

Create a CallGraph that contains one of each type of node.

func LoadGraph 

func LoadGraph(f *os.File, report func(string)) (CallGraph, error)

Load a CallGraph from a binary-encoded file.

func NewCallGraph 

func NewCallGraph() CallGraph

Create a new, empty CallGraph with enough capacity to hold some calls.

func PrivAccessGraph 

func PrivAccessGraph(results Results, progress func(string)) (CallGraph, error)

Construct a callgraph of sandbox-private data accesses outside of sandboxes.

func VulnGraph 

func VulnGraph(results Results, progress func(string)) (CallGraph, error)

Construct a callgraph from SOAAP's vulnerability analysis.

func (*CallGraph) AddCall 

func (cg *CallGraph) AddCall(call Call)

func (*CallGraph) AddCalls 

func (cg *CallGraph) AddCalls(call Call, weight int)

func (*CallGraph) AddFlow 

func (cg *CallGraph) AddFlow(flow Call)

func (*CallGraph) AddFlows 

func (cg *CallGraph) AddFlows(flow Call, weight int)

func (*CallGraph) AddIntersecting 

func (cg *CallGraph) AddIntersecting(g CallGraph, depth int) error

Add intersecting nodes to this graph, where the call traces leading to any two leaf nodes must intersect within `depth` calls.

func (*CallGraph) AddNode 

func (cg *CallGraph) AddNode(node GraphNode)

func (CallGraph) Ancestors 

func (cg CallGraph) Ancestors(root string, depth int) strset

Find ancestors of this node by walking both its call graph and its data flow graph.

Note that this is different from walking the call-and-data-flow graph: it's possible to have calls in one direction and flows in the other, yielding cycles in the combined graph.

func (*CallGraph) CollectNodes 

func (cg *CallGraph) CollectNodes(root string,
	selector func(GraphNode) strset, depth int) strset

func (CallGraph) Filter 

func (cg CallGraph) Filter(keep strset) CallGraph

Filter a callgraph to only contain the specified nodes.

func (CallGraph) Intersect 

func (cg CallGraph) Intersect(g CallGraph, depth int,
	keepBacktrace bool) (CallGraph, error)

Compute the intersection of two CallGraphs, where the call traces leading to any two leaf nodes must intersect within `depth` calls.

If `keepBacktrace` is true, in addition to the intersecting nodes, the new graph will also contain the full backtrace from each node to its root.

func (CallGraph) Save 

func (cg CallGraph) Save(f *os.File) error

Save a CallGraph to an os.File using a binary encoding.

func (CallGraph) Simplified 

func (cg CallGraph) Simplified() CallGraph

Simplify a CallGraph by collapsing call chains and dropping any unreferenced calls.

func (CallGraph) Size 

func (cg CallGraph) Size() (int, int, int)

Report the size of the graph (number of nodes and number of edges).

func (*CallGraph) Union 

func (cg *CallGraph) Union(g CallGraph) error

Compute the union of two CallGraphs.

func (CallGraph) WriteDot 

func (cg CallGraph) WriteDot(out io.Writer, groupBy string) error

type CallSite 

type CallSite struct {
	Function  string
	Location  SourceLocation
	Trace     int
	TraceName string `json:"trace_ref"`
}

A node in the call graph.

This is a location of either a SOAAP warning or else a call to another function in a warning's call stack.

func (CallSite) String 

func (c CallSite) String() string

type CallTrace 

type CallTrace struct {
	CallSites []CallSite
	Next      int
}

A single call trace, from a warning location to the root function.

Common elements of multiple traces may be refactored into separate traces: if this trace has a predecessor, it is identified by `Next`.

func (CallTrace) Foreach 

func (t CallTrace) Foreach(traces []CallTrace, fn func(CallSite)) error

Apply a function to every CallSite in a trace, starting at the SOAAP warning location and moving to the root, passing through other traces contained in `traces` as necessary.

Example: ```go trace.Foreach(traces, func(cs CallSite) { fmt.Println(cs.Function) }) ```

type DataSource 

type DataSource struct {
	Location SourceLocation
	Trace    int
	TraceRef string `json:"trace_ref"`
}

type GraphNode 

type GraphNode struct {
	Name string

	// The name of the function this node is in / represents.
	Function string

	// The library that the function is defined in.
	Library string

	// The sandbox that this code is being executed in.
	//
	// Note that SOAAP can discriminate among the same function executing
	// in different sandboxes.
	Sandbox string

	// A vulnerability (current or previous) is known at this location.
	CVE strset

	// The name of the sandbox(es) that own the data being accessed.
	Owners strset

	CallsIn  []Call
	CallsOut []Call
	FlowsIn  []Call
	FlowsOut []Call

	Tags strset
}

A node in a call graph.

This is derived from a call site or other program location, but can have an arbitrary name and description appropriate to a particular analysis.

func (GraphNode) AllInputs 

func (n GraphNode) AllInputs() strset

func (GraphNode) AllOutputs 

func (n GraphNode) AllOutputs() strset

func (GraphNode) Callees 

func (n GraphNode) Callees() strset

func (GraphNode) Callers 

func (n GraphNode) Callers() strset

func (GraphNode) DataSinks 

func (n GraphNode) DataSinks() strset

func (GraphNode) DataSources 

func (n GraphNode) DataSources() strset

func (GraphNode) Dot 

func (n GraphNode) Dot() string

Construct a GraphViz Dot description of a GraphNode.

This applies SOAAP-specific styling depending on a node's tags.

func (GraphNode) IsSimple 

func (n GraphNode) IsSimple() bool

A node is "simple" (or uninteresting, or boring) if none of the following "interesting" characteristics apply:

  • it has multiple inputs (it joins chains together)
  • it has no inputs (it's a root node)
  • it has multiple outputs (it splits chains apart)
  • it has no outputs (it's a leaf node)
  • it has been marked as previously-vulnerable
  • it accesses private data

func (*GraphNode) Update 

func (n *GraphNode) Update(g GraphNode)

type PrivAccess 

type PrivAccess struct {
	CallSite

	Sandboxes []SandboxName `json:"sandbox_private"`
	Sources   []DataSource
}

Information SOAAP reports about access to sandbox-private data outside of the sandbox.

func (PrivAccess) DataOwners 

func (p PrivAccess) DataOwners() strset

type Results 

type Results struct {
	Vulnerabilities []Vuln       `json:"vulnerability_warning"`
	PrivateAccess   []PrivAccess `json:"private_access"`
	Traces          []CallTrace  `json:"traces"`
}

The results of running SOAAP on an application.

The fields of this structure represent different analyses that SOAAP performs, as well as the complete graph of function calls that are referenced from these analyses.

func LoadResults 

func LoadResults(f *os.File, report func(string)) (Results, error)

Load SOAAP results from an os.File (either binary- or JSON-encoded).

func ParseJSON 

func ParseJSON(f *os.File, progress func(string)) (Results, error)

Parse a JSON file emitted by SOAAP.

The `progress` callback will be notified when major events occur (top-level JSON parsing begins/ends, traces are parsed, etc.).

func (Results) ExtractGraph 

func (r Results) ExtractGraph(analysis string, progress func(string)) (CallGraph, error)

func (Results) Save 

func (r Results) Save(f *os.File) error

type SandboxName 

type SandboxName struct {
	Name string
}

type SourceLocation 

type SourceLocation struct {
	File    string
	Line    int
	Library string
}

A location in source code.

func (SourceLocation) String 

func (l SourceLocation) String() string

type Vuln 

type Vuln struct {
	CallSite

	Sandbox    string
	Type       string
	CVE        []CVE
	Restricted bool `json:"restricted_rights"`
}

Information that SOAAP reports about a vulnerability.

func (Vuln) CVEs 

func (v Vuln) CVEs() strset

Source Files

View all Source files

Directories

Path Synopsis
cmd
soaap-combine
soaap-graph
soaap-parse

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.