/opt/chainguard/in-toto/bin/in-toto-run

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

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.

Required Named Arguments:
  -n <name>, --step-name <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.
  -g [<id>], --gpg [<id>]
                        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 '--signing-key' or '--gpg' is required.
  --signing-key <path>  signing key in a standard PKCS8/PEM format. Supported keytypes are rsa,
                        ed25519, ecdsa (nistp256). Use '--password [<password>]' to pass a
                        decryption password or toggle a prompt, if the key is encrypted.

Positional Arguments:
  <command>             command to be executed. It is separated from named and optional arguments
                        by a double dash '--'.

Options:
  -h, --help            show this help message and exit
  -m <path> [<path> ...], --materials <path> [<path> ...]
                        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 <path> [<path> ...], --products <path> [<path> ...]
                        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.
  -x, --no-command      generate link metadata without executing a command, e.g. for a signed-off-
                        by step.
  -P [<password>], --password [<password>]
                        password for encrypted key specified with '--signing-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>     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 <pattern> [<pattern> ...]
                        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 <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> [<path> ...]
                        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 <directory>, --metadata-directory <directory>
                        path to a directory to dump metadata. If '--metadata-directory' is not
                        passed, the current working directory is used.
  --use-dsse            generate metadata using dsse (experimental).
  --run-timeout RUN_TIMEOUT
                        integer that represents the max timeout in seconds for the in-toto-run
                        command. Default is '10' seconds.
  -v, --verbose         show more output
  -q, --quiet           suppress all output
  --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 . --signing-key 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 --signing-key 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 --signing-key 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 --signing-key key_file \
         -m /tmp/my/review/docs/document.pdf \
         --lstrip-paths /tmp/my/review/docs/ -x