TL;DR, What is in-toto?
in-toto is an open-source framework that helps you secure your software supply chain from development to deployment. Created to defend against high-profile attacks, in-toto gives you "farm-to-table" guarantees for your software. The framework creates a verifiable record of every defined step in the development lifecycle, ensuring authorized personnel perform each task as planned and detecting any tampering with the artifacts.
For DevSecOps teams, in-toto helps solve key pain points by giving you visibility into build processes, detecting unauthorized changes, and verifying software integrity. Your end users also gain transparency into the process, letting them confirm what steps were performed and who performed them. After starting as a project at NYU Tandon School of Engineering, in-toto is now a Cloud Native Computing Foundation (CNCF) graduated project.
Software Supply Chain Security [Cheat Sheet]
Learn how to secure the software supply chain end-to-end – from managing third-party dependencies and open-source libraries to protecting build pipelines.
At-A-Glance
GitHub: https://github.com/in-toto/in-toto
Official Website: https://in-toto.io/
License: Apache-2.0
Primary Language: Python
Stars: 949 ⭐
Last Release: v3.0.0 (May 14, 2024)
Topics/Tags: software-supply-chain-security, supply-chain-security, security, slsa, attestations, integrity
Common use cases
1. CI/CD pipeline security: You can secure build pipelines by automatically generating verifiable attestations for each stage, like code checkout, compilation, and testing. The resulting process creates a secure, auditable record of the build without requiring major changes to your existing CI/CD workflows.
2. Regulatory compliance and auditing: You can fulfill strict regulatory requirements like NIST SSDF and FedRAMP by providing a complete, cryptographically verifiable audit trail. Having this trail enables you to prove that your software was built and delivered according to specific security policies.
3. Container image security: in-toto enhances container security by creating and verifying attestations for image builds and vulnerability scans. The framework helps ensure that only trusted and scanned images, with a verifiable history, are pushed to container registries.
4. Secure Kubernetes deployments: You can integrate in-toto with Kubernetes admission controllers to enforce policies at deployment time. Your clusters can then automatically verify that only container images with a complete and valid chain of attestations are allowed to run in production via controllers/policy engines that evaluate in-toto attestations.
5. Open-source supply chain verification: You can mitigate risks from third-party dependencies by verifying the integrity of open-source components using signed in-toto metadata and a trusted key/identity root. The framework allows you to enforce policies that require upstream software providers to include in-toto attestations, which helps you detect supply chain compromises early.
How does in-toto work?
in-toto secures a software supply chain by creating a verifiable, end-to-end record of how artifacts are built. First, project maintainers define and sign a “layout,” which is a blueprint that specifies authorized functionary keys (and thresholds), required steps, and artifact rules. When someone executes a step, they use in-toto tooling to generate cryptographically signed “link metadata” that attests to the actions performed. Finally, consumers use the original layout to cryptographically verify the chain of link metadata, making sure every step followed the policy and that no one tampered with the process.
Key components include:
Layout: A cryptographically signed policy that defines the supply chain’s expected workflow, including authorized keys/thresholds and inspection rules for all artifacts
Link metadata: Signed evidence generated for each supply chain step; the metadata records the command run, materials used, and products created, all signed by the responsible functionary’s key
Verification engine: An engine that checks the layout's rules against the collected link metadata to confirm that an authorized key correctly performed each step
Core Capabilities
1. Cryptographic supply chain layouts: in-toto defines comprehensive, signed policies called “layouts” that act as a verifiable blueprint for the supply chain. These layouts specify authorized functionary keys/thresholds, expected commands, and rules for artifact handoffs, which allow for policy-based verification.
2. Automated link metadata generation: The framework tools (e.g., in-toto-run) generate cryptographically signed “link metadata” at each supply chain step. The metadata captures the exact commands executed, input files, and output files, creating a tamper-evident and transparent audit trail.
3. End-to-end verification workflow: in-toto provides a verification engine that audits the entire supply chain against the predefined layout. The engine ensures an authorized key performs every step, commands run as expected, and no one tampered with artifacts between steps, offering strong integrity guarantees.
4. Flexible attestation framework: in-toto supports a wide range of attestation types beyond basic provenance, including SLSA provenance attestations, vulnerability scan results, and custom security predicates. Because the framework is extensible, you can capture and enforce different security and quality gates throughout the software lifecycle.
5. Integration with modern DevOps tooling: in-toto integrates with existing CI/CD pipelines, container platforms, and cloud-native ecosystems. Using tools like Witness and integrations for GitHub Actions and Kubernetes, you can embed supply chain security directly into developer workflows with minimal friction.
Limitations
1. Implementation complexity: Adopting the framework requires a solid understanding of its core concepts, like layouts, link metadata, and cryptographic verification. The initial setup can have a steep learning curve for teams new to supply chain security.
2. Key management overhead: The framework's reliance on cryptographic signatures for every person and step creates significant key management duties. You must implement strong processes for generating, distributing, revoking, and securing private keys.
3. Requires full adoption: To get end-to-end verification, you must instrument every step in the software supply chain to generate attestations. A partial implementation gives you limited security guarantees, so in-toto's full value requires buy-in from all of your development and operations teams.
4. Ecosystem and tooling dependency: While integrations exist, using in-toto often depends on supporting tools and platforms such as Sigstore Cosign, Tekton Chains, or Witness. If your organization uses niche or legacy systems, you may need to develop custom integrations to bridge tooling gaps.
5. Potential performance overhead: Generating, signing, and storing detailed metadata for every action in a pipeline can create performance and storage overhead. In high-frequency CI/CD environments, the extra steps might impact build times and require careful infrastructure planning.
If you're using in-toto to verify your software supply chain, it’s a good idea to pair its integrity guarantees with a separate cloud security posture tool. While in-toto provides cryptographic proof that your build process was secure, a CSPM platform like Wiz can independently assess whether the resulting software is exposed in your cloud environment, helping connect assurances about how code was built to runtime exposure and potential attack paths in production.
Getting Started
Step 1: Install in-toto using pip.
pip install in-totoStep 2: Create and sign a supply chain layout file that describes your steps, authorized functionary keys/thresholds, and artifact rules. Use in-toto-sign to sign the layout with the project owner's key. The in-toto documentation provides detailed guidance.
Step 3: Generate public/private key pairs for project owners and other authorized people who will sign metadata and steps using in-toto-keygen. (e.g., in-toto-keygen --type ed25519 <name>).
Step 4: Use in-toto-run to execute supply chain steps, providing the step name, command, and specifying relevant materials and products.
in-toto-run --step <step-name> --key <functionary-key> **--materials <path...> --products <path...>** -- <command>Step 5: To verify your supply chain, run: in-toto-verify --layout <layout file> --layout-keys <public-key> (owner public key; include all owners if threshold > 1).
You're now ready to enforce and verify your software supply chain using in-toto!
FAQ
Alternatives
| Feature | in-toto | Sigstore | The Update Framework |
|---|---|---|---|
| Primary Focus | End-to-end supply chain integrity verification using signed layouts and link metadata | Simplifying artifact signing and verification using keyless certificates and a public transparency log | Securing the software update process against various attacks |
| Supply Chain Policy | Defines comprehensive, cryptographically signed “layouts” that specify the entire supply chain process | Does not have a built-in policy definition framework like in-toto's layoutsRelies on external policy engines (e.g., Sigstore Policy Controller, Kubernetes admission policies) | Uses a role-based system with thresholds and key rotation to define trust and policies for software updates |
| Attestation/Metadata | Generates detailed, signed “link” metadata for each step, creating a verifiable audit trailSupports multiple attestation types | Generates signed attestations (e.g., SLSA provenance) and records them in the Rekor transparency log | Creates signed metadata files that describe the state of a repository and the available software artifacts |
| Verification | Provides a verification engine to check the entire supply chain against the defined layout | Uses “cosign” to verify signatures and attestations against the public transparency log | Verifies the integrity and authenticity of software updates by checking metadata signatures and repository state |
| Key Management | Relies on traditional key management practices, where functionaries manage their own keys | Offers “keyless” signing using ephemeral certificates from the Fulcio Certificate Authority | Provides a robust framework for key rotation and revocation to minimize the impact of key compromise |
| Active Maintenance | Yes, it is a CNCF graduated project with ongoing development | Yes, it is an OpenSSF project with active development and a large community | Yes, it is a CNCF graduated project with active maintenance |