in-toto-record

in-toto-record creates a signed link metadata file in two steps, in order to provide evidence for supply chain steps that cannot be carried out by a single command (for which ‘in-toto-run’ should be used). It returns a non-zero value on failure and zero otherwise.

usage: in-toto-record [-h] [--version] {start,stop} ...

Positional Arguments

command

Possible choices: start, stop

Options

--version

show program’s version number and exit

Sub-commands

start

creates a preliminary link file recording the paths and hashes of the passed materials and signs it with the passed functionary’s key. The resulting link file is stored as ‘.<name>.<keyid prefix>.link-unfinished’.

in-toto-record start [-h] -n <name> [-k <path>] [-t {rsa,ed25519,ecdsa}]
                     [-P [<password>]] [-g [<id>]] [--gpg-home <path>]
                     [--signing-key <path>]
                     [--exclude <pattern> [<pattern> ...]]
                     [--base-path <path>] [--lstrip-paths <path> [<path> ...]]
                     [--use-dsse] [-v | -q] [-m <path> [<path> ...]]

Required Named Arguments

-n, --step-name

name for the resulting link metadata file. 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.

Options

-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.

--use-dsse

generate metadata using dsse (experimental).

Default: False

-v, --verbose

show more output

Default: False

-q, --quiet

suppress all output

Default: False

-m, --materials

paths to files or directories, whose paths and hashes are stored in the resulting link metadata’s material section when running the ‘start’ subcommand. Symlinks to files are followed.

stop

expects preliminary link file ‘.<name>.<keyid prefix>.link-unfinished’ in the CWD, signed by the passed functionary’s key. If found, it records and adds the paths and hashes of the passed products to the link metadata file, updates the signature and renames the file to ‘<name>.<keyid prefix>.link’.

in-toto-record stop [-h] -n <name> [-k <path>] [-t {rsa,ed25519,ecdsa}]
                    [-P [<password>]] [-g [<id>]] [--gpg-home <path>]
                    [--signing-key <path>]
                    [--exclude <pattern> [<pattern> ...]] [--base-path <path>]
                    [--lstrip-paths <path> [<path> ...]] [--use-dsse]
                    [-v | -q] [-p <path> [<path> ...]] [-d <directory>]

Required Named Arguments

-n, --step-name

name for the resulting link metadata file. 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.

Options

-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.

--use-dsse

generate metadata using dsse (experimental).

Default: False

-v, --verbose

show more output

Default: False

-q, --quiet

suppress all output

Default: False

-p, --products

paths to files or directories, whose paths and hashes are stored in the resulting link metadata’s product section when running the ‘stop’ subcommand. Symlinks to files are followed.

-d, --metadata-directory

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

Example Usage

Create link metadata file in two commands, signing it with the private key loaded from ‘key_file’, recording all files in the CWD as materials (on start), and as products (on stop).

in-toto-record start -n edit-files -k path/to/key_file -m .
in-toto-record stop -n edit-files -k path/to/key_file -p .

Create link metadata file signed with the default GPG key from the default GPG home directory and record a file named ‘foo’ as material and product.

in-toto-record start -n edit-foo --gpg -m path/to/foo
in-toto-record stop -n edit-foo --gpg -p path/to/foo

Create link metadata file signed with the private key loaded from ‘key_file’, record all files in the CWD as material and product, and dump finished link file to the target directory (on stop).

in-toto-record start -n edit-files -k path/to/key_file -m .
in-toto-record stop -d path/to/target/dir -n edit-files -k path/to/key_file -p .