How to use the command 'in-toto-run' (with examples)

The in-toto-run command is part of the in-toto framework, which is designed to secure the integrity of the supply chain by generating metadata for different supply chain steps. This metadata, called “link metadata,” provides information about the steps performed, such as materials (initial inputs), products (final outputs), and actions executed, allowing you to ascertain whether your supply chain security policies are being followed correctly.

Use case 1: Tag a Git repo and signing the resulting link file

Code:

in-toto-run -n tag --products . -k key_file -- git tag v1.0

Motivation:

Tagging in Git is a common practice to mark specific points in the repository history that represents versions or releases. Using in-toto-run to tag a Git repo while simultaneously generating and signing link metadata ensures that no unauthorized changes have altered the release, adding an additional layer of trustworthiness to the tagging process.

Explanation:

• -n tag: This argument names the step of the supply chain, which in this case is “tag”.
• --products .: Specifies the products of the step, which in the case of Git tagging, include all files in the current directory. The metadata generated will refer to these as the outputs of this step.
• -k key_file: Path to the private key file used for signing the link metadata, ensuring it cannot be tampered with undetected.
• -- git tag v1.0: The command being executed, in this instance, creating a Git tag named v1.0.

Example Output:

The expected result is the creation of a file named tag.<keyid>.link, where <keyid> corresponds to the key used in signing. This file contains metadata about the Git tag operation and signatures that verify the command ran as expected and the integrity was preserved.

Use case 2: Create a tarball, storing files as materials and the tarball as product

Code:

in-toto-run -n package -m project -p project.tar.gz -- tar czf project.tar.gz project

Motivation:

Creating a tarball for a project is a standard operation for bundling files for distribution or archival. Using in-toto-run during this package creation not only records what went into the tarball (materials) and what came out (product), but also verifies the integrity of the process, ensuring no extraneous material is included and maintaining the supply chain’s integrity.

Explanation:

• -n package: Specifies the name of this supply chain step as “package”.
• -m project: Indicates that the files in the “project” directory are the materials or the inputs for this step.
• -p project.tar.gz: Designates the output tarball as the product of this step.
• -- tar czf project.tar.gz project: The actual tar command used to create the compressed archive file (tarball).

Example Output:

A link file, such as package.<keyid>.link, is created. This file lists the files from the “project” directory that were included into the project.tar.gz tarball and ensures that the resulting tarball hasn’t been tampered with post-creation.

Use case 3: Generate signed attestations for review work

Code:

in-toto-run -n review -k key_file -m document.pdf -x

Motivation:

Reviews and approvals in supply chains, especially dealing with sensitive or significant documents like PDFs, require secure and accountable documentation. This use case provides a digital attestation that a given document has been reviewed and passed/failed compliance checks, with the in-toto metadata ensuring authenticity.

Explanation:

• -n review: Names this supply chain step as “review”.
• -k key_file: Used to sign the resulting metadata, thereby protecting it against unauthorized modifications.
• -m document.pdf: The material/input document being reviewed.
• -x: Takes user entry to confirm the sign-off on the review before completing the metadata generation for added accountability.

Example Output:

A file named review.<keyid>.link is generated, containing attestations about the review of document.pdf alongside metadata verifying that document’s integrity throughout the process.

Use case 4: Scan the image using Trivy and generate link file

Code:

in-toto-run -n scan -k key_file -p report.json -- /bin/sh -c "trivy -o report.json -f json <IMAGE>"

Motivation:

Security scanning of Docker images is a critical part of maintaining secure applications. By using in-toto-run, you not only perform the scan but also generate metadata that includes the scan results, demonstrating compliance with security policies throughout the software supply chain lifecycle.

Explanation:

• -n scan: Names this step as “scan” in the supply chain process.
• -k key_file: Provides the key used to sign the resultant link metadata.
• -p report.json: Specifies the product of this operation, the JSON-formatted scan report.
• -- /bin/sh -c "trivy -o report.json -f json <IMAGE>": Executes a shell command to run Trivy on the specified <IMAGE> and output results in JSON format to report.json.

Example Output:

After running the command, a link file scan.<keyid>.link is created. This file includes metadata about the Trivy scan, specifically noting the JSON report generated by the scan and ensuring that the procedure was conducted securely and in alignment with policy requirements.

Conclusion:

The in-toto-run command serves as a powerful tool for ensuring integrity and accountability within the supply chain by generating metadata that verifies exact changes to products and verifies no unauthorized changes have intervened since step execution. Each use case exemplifies how to integrate security into everyday operations, from tagging a Git release to performing a security scan, ensuring processes are transparent and protected from tampering.