README
¶
Go Flow Levee
This static analysis tool works to ensure your program's data flow does not spill beyond its banks.
An input program's data flow is explored using a combination of pointer analysis, static single assignment analysis, and taint analysis. "Sources" must not reach "sinks" without first passing through a "sanitizer." Additionally, source data can "taint" neighboring variables during a "propagation" function call, such as writing a source to a string. Such tainted variables also must not reach any sink.
Such analysis can be used to prevent the accidental logging of credentials or personally identifying information, defend against maliciously constructed user input, and enforce data communication restrictions between processes.
User Guide
See guides/ for guided introductions on:
- How to configure and run the analyzer
- More topics coming soon!
Motivation
Much data should not be freely shared. For instance, secrets (e.g, OAuth tokens, passwords), personally identifiable information (e.g., name, email or mailing address), and other sensitive information (e.g., user payment info, information regulated by law) should typically be serialized only when necessary and should almost never be logged. However, as a program's type hierarchy becomes more complex or as program logic grows to warrant increasingly detailed logging, it is easy to overlook when a class might contain these sensitive data and which log statements might accidentally expose them.
Technical design
See design/.
Configuration
See configuration/ for configuration details.
Reporting bugs
Static taint propagation analysis is a hard problem. In fact, it is undecidable. Concretely, this means two things:
- False negatives: the analyzer may fail to recognize that a piece of code is unsafe.
- False positives: the analyzer may incorrectly claim that a safe piece of code is unsafe.
Since taint propagation is often used as a security safeguard, we care more deeply about false negatives. If you discover unsafe code that the analyzer is not recognizing as unsafe, please open an issue here. Conversely, false positives waste developer time and should also be addressed. If the analyzer produces a report for code that you consider to be safe, please open an issue here.
For general bug reports (e.g. crashes), please open an issue here.
Contributing
See CONTRIBUTING.md for details.
Developing
See DEVELOPING.md for details.
Disclaimer
This is not an officially supported Google product.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
guides
|
|
|
quickstart
full path: github.com/google/go-flow-levee/guides/quickstart
|
full path: github.com/google/go-flow-levee/guides/quickstart |
|
internal
|
|
|
pkg/config/regexp
Package regexp contains functionality for unmarshalling regular expressions from a config.
|
Package regexp contains functionality for unmarshalling regular expressions from a config. |
|
pkg/debug/dump
Package dump contains functions for writing a function's SSA as SSA or DOT source to a file.
|
Package dump contains functions for writing a function's SSA as SSA or DOT source to a file. |
|
pkg/debug/node
Package node contains utility functions for working with SSA nodes.
|
Package node contains utility functions for working with SSA nodes. |
|
pkg/earpointer
Package earpointer introduces a pointer analysis based on unifying equivalent abstract references (EAR), which implements Steensgaard's algorithm.
|
Package earpointer introduces a pointer analysis based on unifying equivalent abstract references (EAR), which implements Steensgaard's algorithm. |
|
pkg/fieldpropagator
Package fieldpropagator implements identification of field propagators.
|
Package fieldpropagator implements identification of field propagators. |
|
pkg/fieldtags
Package fieldtags defines an analyzer that identifies struct fields identified as sources via a field tag.
|
Package fieldtags defines an analyzer that identifies struct fields identified as sources via a field tag. |
|
pkg/propagation
Package propagation implements the core taint propagation analysis that can be used to determine what ssa Nodes are tainted if a given Node is a source.
|
Package propagation implements the core taint propagation analysis that can be used to determine what ssa Nodes are tainted if a given Node is a source. |
|
pkg/propagation/summary
Package summary provides function summaries for a range of standard library functions that could be involved in a taint propagation.
|
Package summary provides function summaries for a range of standard library functions that could be involved in a taint propagation. |
|
pkg/sanitizer
Package sanitizer contains the logic responsible for determining whether sources are sanitized before they are being sent to sinks.
|
Package sanitizer contains the logic responsible for determining whether sources are sanitized before they are being sent to sinks. |
|
pkg/source
Package source can be used to identify SSA values that are Sources.
|
Package source can be used to identify SSA values that are Sources. |
|
pkg/sourceinfer
Package infer defines an analyzer that identifies Sources that either 1.
|
Package infer defines an analyzer that identifies Sources that either 1. |
|
pkg/sourcetype
Package sourcetype handles identification of sources based on their type.
|
Package sourcetype handles identification of sources based on their type. |
|
pkg/suppression
Package suppression defines an analyzer that identifies calls suppressed by a comment.
|
Package suppression defines an analyzer that identifies calls suppressed by a comment. |
|
pkg/utils
Package utils contains various utility functions.
|
Package utils contains various utility functions. |
|
pkg
|
|
|
levee
Package levee exports the levee Analyzer.
|
Package levee exports the levee Analyzer. |