in-toto-run

in-toto-run is the main command line interface for generating link metadata while carrying out a supply chain step. To do this, it wraps the passed command, and attempts to track all relevant information about the wrapped command’s execution. It records paths and hashes of ‘materials’ (files before command execution) and ‘products’ (files after command execution) and writes them together with other information (executed command, return value, stdout and stderr) to a link metadata file, which is signed with the passed key. It returns a non-zero value on failure and zero otherwise.

usage: in-toto-run <named arguments> [options] \
	 -- <command> [args]

Required Named Arguments

-n, --step-name

name for the resulting link metadata file, which is written to ‘<name>.<keyid prefix>.link’. It is also used to associate the link with a step defined in an in-toto layout.

-k, --key

path to a private key file to sign the resulting link metadata. The keyid prefix is used as an infix for the link metadata filename, i.e. ‘<name>.<keyid prefix>.link’. See ‘–key-type’ for available formats. Passing one of ‘–key’ or ‘–gpg’ is required.

-g, --gpg

GPG keyid to sign the resulting link metadata. When ‘–gpg’ is passed without the keyid, the default GPG key is used. The keyid prefix is used as an infix for the link metadata filename, i.e. ‘<name>.<keyid prefix>.link’. Passing one of ‘–key’ or ‘–gpg’ is required.

--signing-key

replacement for ‘–key’ using a standard PKCS8/PEM format. Key type is detected automatically and need not be specified with ‘–key-type’. Use ‘–password [<password>]’ to pass a decryption password or toggle a prompt, if the key es encrypted.

Positional Arguments

<command>

command to be executed. It is separated from named and optional arguments by a double dash ‘–‘.

Options

-m, --materials

paths to files or directories, for which paths and hashes are stored in the resulting link metadata before the command is executed. Symlinks to files are followed.

-p, --products

paths to files or directories, for which paths and hashes are stored in the resulting link metadata after the command is executed. Symlinks to files are followed.

-s, --record-streams

duplicate ‘stdout’ and ‘stderr’ of the executed command and store the contents in the resulting link metadata. Do not use with interactive commands.

Default: False

-x, --no-command

generate link metadata without executing a command, e.g. for a signed-off-by step.

Default: False

-t, --key-type

Possible choices: rsa, ed25519, ecdsa

type of key specified by the ‘–key’ option. ‘rsa’ keys are expected in a ‘PEM’ format. ‘ed25519’ and ‘ecdsa’ are expected to be in a custom ‘securesystemslib/json’ format. Default is ‘rsa’.

Default: “rsa”

-P, --password

password for encrypted key specified with ‘–key’. Passing ‘-P’ without <password> opens a prompt. If no password is passed, or entered on the prompt, the key is treated as unencrypted. (Do not confuse with ‘-p/–products’!)

--gpg-home

path to a GPG home directory used to load a GPG key identified by ‘–gpg’. If ‘–gpg-home’ is not passed, the default GPG home directory is used.

--exclude

path patterns to match paths that should not be recorded as ‘materials’ or ‘products’. Passed patterns override patterns defined in environment variables or config files. See Config docs for details.

--base-path

base path for relative paths passed via ‘–materials’ and ‘–products’. It is used to locate and record artifacts, and is not included in the resulting link metadata. Default is the current working directory.

--lstrip-paths

path prefixes used to left-strip artifact paths before storing them to the resulting link metadata. If multiple prefixes are specified, only a single prefix can match the path of any artifact and that is then left-stripped. All prefixes are checked to ensure none of them are a left substring of another.

-d, --metadata-directory

path to a directory to dump metadata. If ‘–metadata-directory’ is not passed, the current working direcotry is used.

--use-dsse

generate metadata using dsse (experimental).

Default: False

--run-timeout

integer that represents the max timeout in seconds for the in-toto-run command. Default is ‘10’ seconds.

Default: 10

-v, --verbose

show more output

Default: False

-q, --quiet

suppress all output

Default: False

--version

show program’s version number and exit

Example Usage

Tag a git repo, storing files in CWD as products, signing the resulting link file with the private key loaded from ‘key_file’.

in-toto-run -n tag -p . -k key_file -- git tag v1.0

Create a tarball, storing files in ‘project’ directory as materials and the tarball as product, signing the link file with a GPG key ‘…7E0C8A17’.

in-toto-run -n package -m project -p project.tar.gz \
       -g 8465A1E2E0FB2B40ADB2478E18FB3F537E0C8A17 \
       -- tar czf project.tar.gz project

Not all supply chain steps require that a command be executed. in-toto can still generate signed attestations, e.g. for review work. In that case, files may be marked as materials for the manual review process and the command be omitted.

in-toto-run -n review -k key_file -m document.pdf -x

If an artifact that should be recorded is not in the current working directory (or one of its subdirectories) it can be located using the base path option. Note that in this example only the relative path, ‘document.pdf’ is stored along with its hash in the resulting link metadata file.

in-toto-run -n review -k key_file -m document.pdf \
       --base-path /my/review/docs/ -x

Similarly, it is possible to pass the full path to the artifact that should be recorded together with a left-strip path, to only store a relative path, e.g. ‘document.pdf’.

in-toto-run -n review -k key_file \
       -m /tmp/my/review/docs/document.pdf \
       --lstrip-paths /tmp/my/review/docs/ -x