in-toto-run

Tag a Git repo and signing the resulting link file

$ in-toto-run [[-n|--step-name]] [tag] [[-p|--products]] [.] --signing-key [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] --signing-key [key_file] [[-m|--materials]] [document.pdf] [[-x|--no-command]]

$ in-toto-run [[-n|--step-name]] [scan] --signing-key [key_file] [[-p|--products]] [report.json] -- /bin/sh -c "trivy --output report.json --format json [path/to/image]"

in-toto-run [OPTIONS] -- COMMAND [ARGS...]

-k, --key KEY
    Signing key identifier (default: 'layout-key').

--key-type {ed25519|rsa}
    Signing key type (default: ed25519).

--key-path PATH
    Directory for key files (default: ~/.in_toto).

--use-name-key
    Look up keys by name, not path.

--record-self
    Include own metadata (default: true).

--record-subcommands
    Include subcommands metadata (default: true).

--dir-excludes REGEX
    Exclude directories matching regex (repeatable).

--exclude-prefix PREFIX
    Exclude paths with prefix (repeatable).

--env-excludes REGEX
    Exclude env vars matching regex (repeatable).

--hash-algorithm {sha256|sha384|sha512}
    Hash algorithm (default: sha256).

-V, --version
    Print version and exit.

-h, --help
    Show help and exit.

in-toto-run is a tool from the in-toto project for securing software supply chains. It executes a specified command while capturing pre- and post-execution states to produce signed link metadata. This metadata includes environment variables, directory trees, file hashes, stdout/stderr, return code, and execution time, enabling verification of supply chain steps.

Designed for reproducible builds and attestations, it helps detect tampering or deviations. Links connect sequential steps, forming a chain verifiable against a layout. Ideal for CI/CD pipelines, container builds, or deployment workflows.

By default, it uses Ed25519 keys from ~/.in_toto, records self and subcommands, and excludes noisy paths/envs. Metadata is saved as <name>_link.json in the current directory, ready for verification with in-toto-verify.

Promotes transparency without trusting runners, aligning with SLSA and sigstore ecosystems.

Requires pre-generated keys; non-idempotent commands may produce varying metadata; writes files to CWD; Python-based, install via pip.

Produces <COMMAND>_<KEY>_link.json with signed metadata.

Generate keys with in-toto-keygen; supports Ed25519/rsa; env var IN_TOTO_KEY_PATH overrides.

Developed by NYU researchers starting 2017; in-toto entered CNCF Sandbox 2020; in-toto-run added for link generation; aligns with SLSA frameworks.

in-toto-verify(1), in-toto-layout(1), in-toto-keygen(1), cosign(1)