in-toto-run
Execute a command and record its provenance
TLDR
Tag a Git repo and signing the resulting link file
Create a tarball, storing files as materials and the tarball as product
Generate signed attestations for review work
Scan the image using Trivy and generate link file
SYNOPSIS
in-toto-run [options] -- command [arguments...]
PARAMETERS
-n NAME, --name=NAME
Specifies the unique name for this step, as defined in the in-toto layout. This is a mandatory option.
-p PATH, --key=PATH
Path to the private key used for signing the generated link metadata. This is a mandatory option unless --gpg is used.
-k KEYID, --keyid=KEYID
The ID of the private key used for signing. Can be omitted if the key path is unique for the signing key.
-m MATERIALS, --materials=MATERIALS
Files or directories consumed by the command. Multiple paths can be provided separated by commas. These will be hashed and recorded.
-o PRODUCTS, --products=PRODUCTS
Files or directories produced by the command. Multiple paths can be provided separated by commas. These will be hashed and recorded.
--lstrip-paths=NUM
Removes NUM leading path components from all material and product paths before recording them in the link metadata. Useful for creating portable layouts.
--normalize-line-endings
Normalizes line endings (LF vs. CRLF) for text files before hashing, ensuring consistent hashes across different operating systems.
--no-command-output
Suppresses the output (stdout and stderr) of the executed command.
--gpg=KEYID
Uses GPG to sign the link metadata instead of an in-toto private key. KEYID specifies the GPG key to use.
--gpg-home=DIR
Specifies the GPG home directory when using --gpg.
--metadata-directory=DIR
Specifies the directory where the generated link metadata file will be stored. Defaults to current directory.
--exclude=PATTERN
Excludes paths matching the given PATTERN from being hashed within materials or products. Can be specified multiple times.
--allow-other-as-owner
Allows files and directories owned by other users or groups to be included as materials or products. By default, in-toto-run only processes files owned by the current user.
--attest=ATTESTATION_PATH
Path to a file containing additional attestation data to be embedded in the link metadata. The content is recorded as 'byproducts'.
--attest-in=ATTESTATION_INPUT_PATH
Path to a file containing additional attestation data related to the input materials. The content is recorded as 'byproducts'.
--attest-out=ATTESTATION_OUTPUT_PATH
Path to a file containing additional attestation data related to the output products. The content is recorded as 'byproducts'.
DESCRIPTION
The in-toto-run command is a core component of the in-toto framework, designed to enhance software supply chain security. It executes a specified command and securely records evidence of its execution as a link metadata file. This evidence includes the exact command executed, cryptographic hashes of all files consumed (materials) and produced (products) by the command, and a digital signature from the responsible party.
By creating these signed link files, in-toto-run provides an auditable and verifiable record of each step in a software supply chain. This is crucial for detecting unauthorized modifications, ensuring integrity, and promoting transparency throughout the build and release process. The generated link files are later used by in-toto-verify to attest that the software was produced according to a predefined supply chain layout.
CAVEATS
Key Management: Requires proper management of private keys for signing. Compromised keys undermine security guarantees.
Completeness: Integrity guarantees depend on correctly identifying all materials and products. Omissions can lead to verification failures.
Execution Environment: While in-toto-run records, it does not sandbox the command; it runs with the invoking user's privileges.
Error Handling: If the wrapped command fails, in-toto-run still generates a link file, capturing the failure. Verification depends on the layout's expectations.
Metadata Size: Hashing many files, especially large ones, can consume significant time and produce large link metadata files.
LINK METADATA FILES
Upon successful execution, in-toto-run generates a JSON-formatted link metadata file (typically with a .link extension). This file contains:
• The name of the step (-n).
• The exact command that was executed.
• Cryptographic hashes (e.g., SHA256) of all input materials and output products, indexed by their paths.
• A timestamp of execution.
• The digital signature of the key used to sign the metadata.
This file serves as irrefutable evidence of a specific supply chain step's execution.
ROLE IN SUPPLY CHAIN SECURITY
in-toto-run empowers developers and operators to create a cryptographically verifiable 'trail of custody' for their software. Each time a build, test, or packaging step is performed, in-toto-run records what happened and signs it. When a consumer receives the software, they can use in-toto-verify to check if all steps in the supply chain were executed as expected, by authorized parties, and without unauthorized modifications. This helps mitigate risks like backdoor injection, dependency hijacking, and tampering during transit or distribution.
HISTORY
in-toto-run is a key component of the in-toto framework, an open-source project initiated at New York University (NYU) and TU Delft, with contributions from various organizations including Google and Purdue University. The project's primary motivation was to address prevalent vulnerabilities in software supply chains, where untrusted or compromised steps can introduce malicious code. in-toto gained significant attention as a solution to enhance the integrity and security of software artifacts from source code to deployment. in-toto-run was developed early on as the mechanism for recording cryptographic evidence of discrete supply chain steps, forming the foundation for auditable and verifiable software delivery.
SEE ALSO
in-toto-verify(1), in-toto-sign(1), in-toto-gen-layout(1), in-toto-metadata(5)