Add comments for path_interposer.

// See the License for the specific language governing permissions and

// limitations under the License.

// This tool tries to prohibit access to tools on the system on which the build

// is run.

//

// The rationale is that if the build uses a binary that is not shipped in the

// source tree, it is unknowable which version of that binary will be installed

// and therefore the output of the build will be unpredictable. Therefore, we

// should make every effort to use only tools under our control.

//

// This is currently implemented by a "sandbox" that sets $PATH to a specific,

// single directory and creates a symlink for every binary in $PATH in it. That

// symlink will point to path_interposer, which then uses an embedded

// configuration to determine whether to allow access to the binary (in which

// case it calls the original executable) or not (in which case it fails). It

// can also optionally log invocations.

//

// This, of course, does not help if one invokes the tool in question with its

// full path.

package main

import (

	LinuxOnlyPrebuilt bool

}

// These binaries can be run from $PATH, nonhermetically. There should be as

// few as possible of these, since this means that the build depends on tools

// that are not shipped in the source tree and whose behavior is therefore

// unpredictable.

var Allowed = PathConfig{

	Symlink: true,

	Log:     false,

	Error:   false,

}

// This tool is specifically disallowed and calling it will result in an

// "executable no found" error.

var Forbidden = PathConfig{

	Symlink: false,

	Log:     true,

	Error:   true,

}

// This tool is allowed, but access to it will be logged.

var Log = PathConfig{

	Symlink: true,

	Log:     true,

// The configuration used if the tool is not listed in the config below.

// Currently this will create the symlink, but log and error when it's used. In

// the future, I expect the symlink to be removed, and this will be equivalent

// to Forbidden.

// to Forbidden. This applies to every tool not specifically mentioned in the

// configuration.

var Missing = PathConfig{

	Symlink: true,

	Log:     true,

	Error:   true,

}

// This is used for binaries for which we have prebuilt versions, but only for

// Linux. Thus, their execution from $PATH is only allowed on Mac OS.

var LinuxOnlyPrebuilt = PathConfig{

	Symlink:           false,

	Log:               true,

	return Missing

}

// This list specifies whether a particular binary from $PATH is allowed to be

// run during the build. For more documentation, see path_interposer.go .

var Configuration = map[string]PathConfig{

	"bash":    Allowed,

	"dd":      Allowed,