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

Optional Arguments

--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}]
                     [-P [<password>]] [-g [<id>]] [--gpg-home <path>]
                     [--exclude <pattern> [<pattern> ...]]
                     [--base-path <path>] [--lstrip-paths <path> [<path> ...]]
                     [-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.

Optional Arguments

-t, --key-type

Possible choices: rsa, ed25519

type of key specified by the ‘–key’ option. ‘rsa’ keys are expected in a ‘PEM’ format and ‘ed25519’ 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.
-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}]
                    [-P [<password>]] [-g [<id>]] [--gpg-home <path>]
                    [--exclude <pattern> [<pattern> ...]] [--base-path <path>]
                    [--lstrip-paths <path> [<path> ...]] [-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.

Optional Arguments

-t, --key-type

Possible choices: rsa, ed25519

type of key specified by the ‘–key’ option. ‘rsa’ keys are expected in a ‘PEM’ format and ‘ed25519’ 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.
-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 .