in-toto-record

Start the record (creates a preliminary link file)

$ in-toto-record start [[-n|--step-name]] [path/to/edit_file1 path/to/edit_file2 ...] -k [path/to/key_file] [[-m|--materials]] [.]

$ in-toto-record stop [[-n|--step-name]] [path/to/edit_file1 path/to/edit_file2 ...] -k [path/to/key_file] [[-p|--products]] [.]

in-toto-record --name <step_name> --key <path_to_private_key> [--materials <path>...] [--products <path>...] [--byproducts <path>...] [--exclude <path>...] [--lstrip-paths <num>] [--template <path>] [--base-path <path>] [--log-level <level>] [--record-environ <VAR>...] [--preserve-environ] [--debug] [--verbose] -- <command> [arguments...]

--name <step_name>
    Specifies the unique name for the supply chain step being recorded (e.g., 'compile', 'test'). This is a mandatory parameter.

--key <path_to_private_key>
    Provides the path to the private key used to sign the generated link metadata file. This key authenticates the actor performing the step and is mandatory.

--materials <path>...
    One or more paths to input files or directories (materials) used by the command. Cryptographic hashes of these paths are recorded, and they are crucial for verification.

--products <path>...
    One or more paths to output files or directories (products) generated by the command. Cryptographic hashes of these paths are recorded, verifying the step's results.

--byproducts <path>...
    One or more paths to additional files or directories (byproducts) to record. These are usually non-critical outputs like logs or temporary files whose hashes are recorded for auditing but are not strictly checked for verification.

--exclude <path>...
    Paths to exclude from the material, product, or byproduct collections. This is useful for ignoring specific files within a specified directory.

--lstrip-paths <num>
    Specifies the number of leading path components to strip when recording materials and products. This helps in achieving path consistency across different environments.

--template <path>
    Path to a step template file to use. The template can define expected materials, products, and other properties for the step.

--base-path <path>
    Specifies a base directory to resolve all relative material, product, and byproduct paths against.

--log-level <level>
    Sets the logging level (e.g., 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL').

--record-environ <VAR>...
    A list of specific environment variables to record as part of the link metadata.

--preserve-environ
    Records all environment variables present during execution. Use with caution as this can expose sensitive information.

--debug
    Enables verbose debug output for troubleshooting.

--verbose
    Enables verbose output, providing more detailed information about the recording process.

--help
    Displays a help message and exits.

--version
    Shows the version information and exits.

--
    Separates in-toto-record's own options from the command and its arguments that are to be executed and recorded. All arguments following this double dash will be treated as part of the command to run.

in-toto-record is a crucial command within the in-toto framework, designed to enhance software supply chain security. It allows users to execute a command (representing a specific step in the software supply chain, e.g., compilation, testing, packaging) and automatically record essential metadata about that execution. This metadata includes cryptographic hashes of input files (materials), output files (products), and any additional files (byproducts) generated during the step. The command also captures details like the executed command itself, its arguments, and relevant environment variables.

After successful execution, in-toto-record creates a cryptographically signed "link" metadata file. This link file serves as an attestation, proving that a specific step was performed, by whom (via the signing key), and with what inputs and outputs. These link files are foundational for building a verifiable supply chain "layout" which can later be checked by in-toto-verify, ensuring that all steps were executed as expected and that no unauthorized modifications occurred. It replaced the in-toto-run command to clarify its specific role in recording.

By using in-toto-record, developers and integrators gain transparency and tamper-evidence, mitigating risks associated with compromised software components or unauthorized build processes. It's an essential tool for implementing robust supply chain integrity policies.

Key Management: The private key used for signing the link file must be securely managed. Compromise of this key can undermine the integrity of your supply chain attestations.

Accurate Path Specification: Correctly identifying and specifying --materials and --products is critical. Errors or omissions can lead to a supply chain that cannot be properly verified or allows undetected tampering.

Path Normalization Consistency: When using --lstrip-paths or --base-path, ensure consistency between recording and subsequent verification steps, otherwise, path mismatches will cause verification failures.

Environment Variables: Be cautious when using --preserve-environ as it can inadvertently record sensitive environment variables into the publicly viewable link metadata.

Upon successful execution, in-toto-record generates a cryptographically signed metadata file, commonly referred to as a "link" file. This file contains the cryptographic hashes of all specified materials, products, and byproducts, along with the details of the executed command and its environment. The link file is named using a combination of the step name and the key ID, typically following the pattern <step_name>.<key_id>.link.

The double dash (--) is a standard convention in shell commands. For in-toto-record, it's critical because it explicitly separates the options meant for in-toto-record itself from the command and its arguments that in-toto-record is meant to execute. Any argument after -- will be treated as part of the command to be run, not as an option for in-toto-record.

The in-toto project originated from research at New York University (NYU), specifically by the Secure Systems Group, led by Justin Cappos. Its development began around 2015-2016, aiming to address critical software supply chain security vulnerabilities. The project was later incubated by the Linux Foundation's Cloud Native Computing Foundation (CNCF) and is now a widely adopted standard for securing software supply chains. in-toto-record specifically evolved from an earlier command, in-toto-run, consolidating its role as the primary utility for creating signed attestations of individual supply chain steps. Its adoption reflects a growing industry focus on provenance and integrity throughout the software development lifecycle.

in-toto-verify(1), in-toto-keygen(1), in-toto-sign(1), in-toto-dump(1)