in-toto-run

Tag a Git repo and signing the resulting link file

$ in-toto-run [[-n|--step-name]] [tag] [[-p|--products]] [.] -k [key_file] -- [git tag v1.0]

$ in-toto-run [[-n|--step-name]] [package] [[-m|--materials]] [project] [[-p|--products]] [project.tar.gz] -- [tar czf project.tar.gz project]

$ in-toto-run [[-n|--step-name]] [review] -k [key_file] [[-m|--materials]] [document.pdf] [[-x|--no-command]]

$ in-toto-run [[-n|--step-name]] [scan] -k [key_file] [[-p|--products]] [report.json] -- [/bin/sh -c "trivy [[-o|--output]] report.json [[-f|--format]] json <IMAGE>"]

in-toto-run [options] -- command [arguments...]

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

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.

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.

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.

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.

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.

in-toto-verify(1), in-toto-sign(1), in-toto-gen-layout(1), in-toto-metadata(5)