Documentation
¶
Overview ¶
Package audit is the source-level tripwire behind the one-line guarantee, shared by every binary in this repo. It exists because the first fix of this class was audited by counting print sites BY HAND and came up nine short; every one of the nine was a refusal or a note rather than an event line, which is exactly what hand-counting misses. So the count is mechanical: a binary's test calls PrintedArguments, which reads every non-test file of the package under test, pairs every fmt print argument with the verb that prints it, and classifies each one as
%q, or a numeric verb -- the verb quotes and escapes it, or it is not text
a literal -- a string literal, or a constant declared in the package
escaped -- rendered through oneline.Escape, Field or Err, or a
function the config names as an escaper
exempted -- named in the config, one entry per site, with the reason
Anything else fails, naming the file and line. A new interpolation is a decision from then on, never a drive-by: adding one means either escaping it or writing down why it is safe. A stale exemption fails too, because it is a claim about a site that no longer exists and would silently cover the next one written in its place.
Bypasses closes the gap the classifier cannot see, since it walks fmt calls and therefore knows only one way of putting bytes on a stream: io.WriteString, a bare .Write, a fmt function used as a VALUE rather than called, a local that shadows the escaping path, the print and println builtins, an aliased or unlisted import, and flag.FlagSet.SetOutput with anything but io.Discard, which is how package flag came to print an attacker's argument before any code in the binary ran.
Neither test can see an escape dropped inside a loop that builds a value printed later. That shape is exempted by name where it exists, and each such exemption has a behavioral test of its own in the binary that owns it.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func PrintedArguments ¶
PrintedArguments classifies every argument of every fmt print call in the package under test, and fails on any that is neither quoted, numeric, literal, escaped nor exempted.
Types ¶
type Config ¶
type Config struct {
// Escapers names calls whose result is safe to print, by the source text of the
// callee, beyond the three from package oneline that are always accepted. A binary
// lists its own wrappers here, and each wrapper's body is walked by the same
// classifier, so the claim is checked rather than taken.
Escapers []string
// Exempt maps "file|function|argument source text" to the reason the site is safe.
// One entry per site. The file is in the key because a package is many files.
Exempt map[string]string
// Shadows names identifiers no local may shadow, beyond oneline, Escape, Field and
// Err, which are always refused.
Shadows []string
// Imports lists the import paths the package is allowed, quoted as they appear in
// source. pkg/oneline is always allowed. An import off the list is a writer
// nobody has read yet, and widening the list is a decision made in the test.
Imports []string
// MinClassified is the number of printed arguments the walk must reach, so that a
// walk looking in the wrong place cannot pass by classifying nothing.
MinClassified int
}
Config is one binary's claims about its own source.
Source Files