in-toto/community

in-toto is a framework to secure the software supply chain.

in-toto

in-toto provides a framework to protect the integrity of the software supply chain. It does so by verifying that each task in the chain is carried out as planned, by authorized personnel only, and that the product is not tampered with in transit.

in-toto requires a project owner to create a layout. A layout lists the sequence of steps of the software supply chain, and the functionaries authorized to perform these steps. When a functionary performs a step in-toto gathers information about the used command and the related files and stores it in a link metadata file. As a consequence link files provide the required evidence to establish a continuous chain that can be validated against the steps defined in the layout.

The layout, signed by the project owners, together with the links, signed by the designated functionaries, are released as part of the final product, and can be validated manually or via automated tooling in, e.g. a package manager.

Getting Started

Installation

in-toto is available on PyPI and can be installed via pip. See in-toto.readthedocs.io to learn about system dependencies and installation alternatives and recommendations.

pip install in-toto

Create layout, run supply chain steps and verify final product

Layout

The in-toto software supply chain layout consists of the following parts:

• expiration date
• readme (an optional description of the supply chain)
• functionary keys (public keys, used to verify link metadata signatures)
• signatures (one or more layout signatures created with the project owner key(s))
• software supply chain steps correspond to steps carried out by a functionary as part of the software supply chain. The steps defined in the layout list the functionaries who are authorized to carry out the step (by key id). Steps require a unique name to associate them (upon verification) with link metadata that is created when a functionary carries out the step using the in-toto tools. Additionally, steps must have material and product rules which define the files a step is supposed to operate on. Material and product rules are described in the section below.
• inspections define commands to be run during the verification process and can also list material and product rules.

Take a look at the demo layout creation example for further information on how to create an in-toto layout.

Artifact Rules

A software supply chain usually operates on a set of files, such as source code, executables, packages, or the like. in-toto calls these files artifacts. A material is an artifact that will be used when a step or inspection is carried out. Likewise, a product is an artifact that results from carrying out a step.

The in-toto layout provides a simple rule language to authorize or enforce the artifacts of a step and to chain them together. This adds the following guarantees for any given step or inspection:

• Only artifacts authorized by the project owner are created, modified or deleted,
• each defined creation, modification or deletion is enforced, and also
• restricted to the scope of its definition, which chains subsequent steps and inspections together.

Note that it is up to you to properly secure your supply chain, by authorizing, enforcing and chaining materials and products using any and usually multiple of the following rules:

• CREATE <pattern>
• DELETE <pattern>
• MODIFY <pattern>
• ALLOW <pattern>
• DISALLOW <pattern>
• REQUIRE <file>
• MATCH <pattern> [IN <source-path-prefix>] WITH (MATERIALS|PRODUCTS) [IN <destination-path-prefix>] FROM <step>

Rule arguments specified as <pattern> allow for Unix shell-style wildcards as implemented by Python's fnmatch.

in-toto's Artifact Rules, by default, allow artifacts to exist if they are not explicitly disallowed. As such, a DISALLOW * invocation is recommended as the final rule for most step definitions. To learn more about the different rule types, their guarantees and how they are applied, take a look at the Artifact Rules section of the in-toto specification.

Carrying out software supply chain steps

in-toto-run

in-toto-run is used to execute a step in the software supply chain. This can be anything relevant to the project such as tagging a release with git, running a test, or building a binary. The relevant step name and command are passed as arguments, along with materials, which are files required for that step's command to execute, and products which are files expected as a result of the execution of that command. These, and other relevant details pertaining to the step are stored in a link file, which is signed using the functionary's key.

If materials are not passed to the command, the link file generated just doesn't record them. Similarly, if the execution of a command via in-toto-run doesn't result in any products, they're not recorded in the link file. Any files that are modified or used in any way during the execution of the command are not recorded in the link file unless explicitly passed as artifacts. Conversely, any materials or products passed to the command are recorded in the link file even if they're not part of the execution of the command.

See this simple usage example from the demo application for more details. For a detailed list of all the command line arguments, run in-toto-run --help or look at the online documentation.

in-toto-record

in-toto-record works similar to in-toto-run but can be used for multi-part software supply chain steps, i.e. steps that are not carried out by a single command. Use in-toto-record start ... to create a preliminary link file that only records the materials, then run the commands of that step or edit files manually and finally use in-toto-record stop ... to record the products and generate the actual link metadata file. For a detailed list of all command line arguments and their usage, run in-toto-record start --help or in-toto-record stop --help, or look at the online documentation.

Release final product

In order to verify the final product with in-toto, the verifier must have access to the layout, the *.link files, and the project owner's public key(s).

Verification

Use in-toto-verify on the final product to verify that

• the layout was signed with the project owner's private key(s),
• has not expired,
• each step was performed and signed by the authorized functionary,
• the functionaries used the commands, they were supposed to use,
• materials and products of each step were in place as defined by the rules, and
• run the defined inspections

For a detailed list of all command line arguments and their usage, run in-toto-verify --help or look at the online documentation.

Signatures

in-toto-sign is a metadata signature helper tool to add, replace, and verify signatures within in-toto Link or Layout metadata, with options to:

• replace (default) or add signature(s), with layout metadata able to be signed by multiple keys at once while link metadata can only be signed by one key at a time
• write signed metadata to a specified path (if no output path is specified, layout metadata is written to the path of the input file while link metadata is written to <name>.<keyid prefix>.link)
• verify signatures

This tool serves well to re-sign test and demo data. For example, it can be used if metadata formats or signing routines change.

For a detailed list of all command line arguments and their usage, run in-toto-sign --help or look at the online documentation.

in-toto demo

You can try in-toto by running the demo application. The demo basically outlines three users viz., Alice (project owner), Bob (functionary) and Carl (functionary) and how in-toto helps to specify a project layout and verify that the layout has been followed in a correct manner.

Specification

You can read more about how in-toto works by taking a look at the specification.

Security Issues and Bugs

See SECURITY.md.

Governance and Contributing

For information about in-toto's governance and contributing guidelines, see GOVERNANCE.md and CONTRIBUTING.md.

Acknowledgments

This project is managed by Prof. Santiago Torres-Arias at Purdue University. It is worked on by many folks in academia and industry, including members of the Secure Systems Lab at NYU and the NJIT Cybersecurity Research Center.

This research was supported by the Defense Advanced Research Projects Agency (DARPA), the Air Force Research Laboratory (AFRL), and the US National Science Foundation (NSF). Any opinions, findings, and conclusions or recommendations expressed in this material are those of the authors and do not necessarily reflect the views of DARPA, AFRL, and NSF. The United States Government is authorized to reproduce and distribute reprints notwithstanding any copyright notice herein.

community's Issues

Move in-toto cross implementing tests to @in-toto

Ref: https://github.com/PradyumnaKrishna/in-toto-testing

@PradyumnaKrishna has written some cross-implementation tests (and in the process discovered some issues). The next step is to have this reviewed and prepared for a move to the in-toto GitHub org.

Exclude adopter from CLOMonitor check

There is an exemptions option for CLO Monitor and I think we could exclude the adopters check because why would we need to mention adopters on the community repo. 😄

For reference this is how its done: https://github.com/cncf/clomonitor/blob/main/docs/metadata/.clomonitor.yml

Mention the check and the reason.

Donation of witness and go-witness

This is a related issue to #15:

• Witness Repository: https://github.com/testifysec/witness
• Go-Witness Repository: https://github.com/testifysec/go-witness

Following the guidance of the ITSC, we'd like this issues to serve as the record of the ITSC's vote and the follow up actions required for and following the donation:

• A majority of the ITSC members vote to accept the donation.
• Labeling of the witness and go-witness libraries as experimental (or according to a future maturity model developed by the ITSC).
• That label can be reviewed once the code of these repositories comes in line with the ITE's described here and once the ITSC formalizes the sub-project maturity model.

Rename in-toto/in-toto and in-toto/docs

The repositories names for the in-toto python implementation (in-toto) and for the in-toto specification (docs) are ambiguous and/or misleading. They can be easily mistaken for a project "landing page" (in-toto) or general project documentation (docs).

Proposed fix

• Rename docs to specification
• Rename in-toto to in-toto-python (like in-toto-golang, in-toto-java, in-toto-rs), or python-in-toto (like python-tuf, go-witness)
• Use language -typical doc platforms for API documentation (e.g. readthedocs, godoc, etc.)
• Use in-toto.io as project landing page and place for general project documentation
  • Repurposing in-toto or docs would be nice, but it seems safer to not reuse the names and instead use forwarding to preserve existing links
  • in-toto.io could include quick start guides with cli examples, where the used programming language doesn't matter (should probably only pick one of the (3!) co-existing in-toto cli)

Develop a user doc contribution policy

UPDATE 05/27/2024 (transfer issue from in-toto/docs)

• Specify user doc source location. Source files for all web-based user doc content goes into [https://github.com/in-toto/docs]/source in-toto.io/docs (see in-toto/in-toto.io#34)
• Specify user doc approvers and resources.
  Add specific information in the contribution policy about who can review and approve changes and additions to user docs, and resources available to writers and editors. Include or link to:
  • Contact info for maintainer/reviewer for documentation contributions.
  • Available doc style guides/templates (as well as code standards)
  • Usage guidelines for RTD (or other doc tool) and any project-specific usage standards.
  • Current doc architecture plan.
  • Map to documentation source files.

Facing Verification Error in a simple PoC.

I am doing a poc with in-toto. PoC contains the following steps:

1. Build : where I create a simple app.js file with text "hello in-toto"
2. Copy: copy app.js from target folder to dist folder
   I created the following layout.
   {
   "signatures": [
   {
   "keyid": "57c82af1f601373488cc340eefe7b75ade898bac3865240c5213738c6654636a",
   "sig": "7cb014f21f86a69b42b34d298edb0a903423147fae850a461bed8c6361c15091fa3d64509214e9f28ed71fff3a151287b9b3451d328a1504b61d9d4772bca47b5b313e8d560c24bed286bdabbe668fa615a298d2380ab94e56bc7add7ef36becd550721c1f2b3b0cf7ed04ee365eaa6b3ec264c13cbed9b292faf4ec34fe605214a58db50347ec2b8beb8c342cf0c13f8d32f81d47e381076994ca0328c705e674a7823e64fc143373f723707f8cc0c91ce81d4e32a69bf85037b27780ab8be18927589b5a162800c861429ecdc0c22830399da270df451498951fb767b28191e5a527e66b2005b0221e3bc45af5012e0eb886114f9f2fc3ea204bffef2030fe"
   }
   ],
   "signed": {
   "_type": "layout",
   "expires": "2024-05-04T07:23:50Z",
   "inspect": [
   {
   "_type": "inspection",
   "expected_materials": [
   [
   "MATCH",
   "target/app.js",
   "WITH",
   "PRODUCTS",
   "FROM",
   "build"
   ]
   ],
   "expected_products": [
   [
   "MATCH",
   "dist/app.js",
   "WITH",
   "PRODUCTS",
   "FROM",
   "copy"
   ]
   ],
   "name": "check",
   "run": []
   }
   ],
   "keys": {
   "57c82af1f601373488cc340eefe7b75ade898bac3865240c5213738c6654636a": {
   "keyid": "57c82af1f601373488cc340eefe7b75ade898bac3865240c5213738c6654636a",
   "keyid_hash_algorithms": [
   "sha256",
   "sha512"
   ],
   "keytype": "rsa",
   "keyval": {
   "private": "",
   "public": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqeRMXBGIm5M9Eld+mih9\n4qxc3KMp0G8pYwOVRf/cQZQzqPWKen69mIaeRcJEzvcIwHPS3az6nfEVS37L6iz5\njf5bOr9JJyyO3kzyR1N5HoWO/JisiF5KJS4LpOLRd2C1yX7IbjbQFAuxAwUyG5w4\nDdlwXt9tXw0eqQ13CO4ugGYbiFfh5dqF6YzzQUfAiRBfvk2uQldFMyxCyV6K4Wov\nalrRG9z63xU3ivs356It0R7igZbuBFbQEGhSllQt44dtyhxPN36tbKpql9W92XJb\naMRhaldU3lOjHpBlzVLb/4wMDMiSo4Lygz0A6nfrWsA93PlNpZcAXar1AyCYCH/S\nFQIDAQAB\n-----END PUBLIC KEY-----"
   },
   "scheme": "rsassa-pss-sha256"
   }
   },
   "readme": "",
   "steps": [
   {
   "_type": "step",
   "expected_command": [],
   "expected_materials": [],
   "expected_products": [
   [
   "CREATE",
   "target/*.js"
   ]
   ],
   "name": "build",
   "pubkeys": [
   "57c82af1f601373488cc340eefe7b75ade898bac3865240c5213738c6654636a"
   ],
   "threshold": 1
   },
   {
   "_type": "step",
   "expected_command": [],
   "expected_materials": [
   [
   "MATCH",
   "target/app.js",
   "WITH",
   "PRODUCTS",
   "FROM",
   "build"
   ]
   ],
   "expected_products": [
   [
   "CREATE",
   "dist/app.js"
   ]
   ],
   "name": "copy",
   "pubkeys": [
   "57c82af1f601373488cc340eefe7b75ade898bac3865240c5213738c6654636a"
   ],
   "threshold": 1
   }
   ]
   }
   }

Once I created the layout, I started executed the following commands. Consider I am in a test folder, I created 2 more folders target and dist inside test folder and executed the following commands

1. in-toto-record start --step-name build --key /home/azureuser/chenthilraj/intoto/intoto_private_key.pem --materials target/app.js --verbose

echo "Hello in-toto" > target/app.js

in-toto-record stop --step-name build --key /home/azureuser/chenthilraj/intoto/intoto_private_key.pem --products target/app.js --verbose

Note: target/app.js got created with content "Hello in-toto".

in-toto-record start --step-name copy --key /home/azureuser/chenthilraj/intoto/intoto_private_key.pem --materials target/app.js --verbose

cp target/app.js dist/app.js

Note: file copy successful.

in-toto-record stop --step-name copy --key /home/azureuser/chenthilraj/intoto/intoto_private_key.pem --products dist/app.js --verbose

I ensured that the same file app.js is present in both target and dist folder. Then I execute

in-toto-verify -l /home/azureuser/chenthilraj/intoto/root.layout --layout-key /home/azureuser/chenthilraj/intoto/intoto_public_key.pem --verbose

but the verification fails. Please note there is no key error since the moment I remove the inspection section from the layout, verification is successful.

I verified the build link file and copy link file and checked the sha key is same for both target/app.js and dist/app.js as shown below

build link file:

{
"signatures": [
{
"keyid": "57c82af1f601373488cc340eefe7b75ade898bac3865240c5213738c6654636a",
"sig": "8771ac06997dc809e8262b0fcbaefab8c47bb16bff6705855d97fe0ecb4d3f70755e74eca336194e75324876a19c77e73b5fa6b791e047a50772118ef76355dc6e213f68b8eaba849bd21631095c93b549c2ccc57a318db9c2da6f8735e0d763e012606b57dcb4fc383fcb95bb215d31679f2d42b87cbaa6142640a130b40453d49d16fc1876a40bee2ef3bd8ae124397c36113920e4f3e02433acf1a043f42749bc25a93eff89592e3ad67dcd693f11917b88578d08e3788e8fba6189b17fd838a2702832edb0de33c832e4e2428341bddfc19462933863d3f487ec8f181bb6eb87187236c9a1c0f50e4d1b263ff492259eba95531dd265e50f91acd1ba7614"
}
],
"signed": {
"_type": "link",
"byproducts": {},
"command": [],
"environment": {},
"materials": {},
"name": "build",
"products": {
"target/app.js": {
"sha256": "e40dcf0c464bf4b89a5d8384fe2a0209dccc9052c82946732111f64433b0bfd3"
}
}
}
}

Copy Link File:
{
"signatures": [
{
"keyid": "57c82af1f601373488cc340eefe7b75ade898bac3865240c5213738c6654636a",
"sig": "0295e4b57753e677a30a8e53035ae86c1bb28a97a403ceea8b664b795da494d775b96f6bab6694092438fe5870282890576291d87506bd8d13e00bee8c780a110376e861a777d84e704382b8f732034257b4a29b58a2023eba563886e4f63c2472f28a5ef0ffdb3c04ac9625c8d2aa2a92d684bc8fecdc02dd9ac735cad1355b29adace4968e0c49f42815a02f2b22d314cb122ffe27d845edf2f5b57d44ea4a0609ce8465b0f7f3fbb5780de18ece053a6f49fc81761293279ffdd6d47af5ab94394b7f536178ed3e5b3e8b2ad863db74d25ce090600699507e2d332b46f1a40f3c27a0fb700d1c5391ce08cbeea40b4a42d88a28d979cf0d9714b25bb8f8bc"
}
],
"signed": {
"_type": "link",
"byproducts": {},
"command": [],
"environment": {},
"materials": {
"target/app.js": {
"sha256": "e40dcf0c464bf4b89a5d8384fe2a0209dccc9052c82946732111f64433b0bfd3"
}
},
"name": "copy",
"products": {
"dist/app.js": {
"sha256": "e40dcf0c464bf4b89a5d8384fe2a0209dccc9052c82946732111f64433b0bfd3"
}
}
}
}

I am using version 2.1.1.

Develop a reference doc contribution policy

UPDATE 05/27/2024 (transfer issue from in-toto/docs)

• Specify how and where developers provide reference docs for new implementations.
  Reference documentation should go with the implementation repo in GitHub, with sources and generation information in a doc subdirectory.
• Specify what to document for an implementation.
  Use the Python Reference Implementation's reference docs to see what needs to be documented.
  These are generated using source files and a makefile in the implementation's doc subdirectory.
• Add the policy to https://github.com/in-toto/community/blob/main/CONTRIBUTING.md

Transfer SCAI predicate APIs/tooling and demos into in-toto org

Hello!

I've been implementing CLI tools for generating/verifying SCAI predicate metadata, as well as implementing a number of example use cases. This implementation includes Go and Python APIs for generation, and Go APIs that were modeled to fit with the ITE-10/11 in-toto-attestation-verifier that @adityasaky has been implementing.

Everything can be found at: https://github.com/IntelLabs/supply-chain-attribute-integrity/

From discussions with @SantiagoTorres about this work, we think the in-toto org would be a great home for this repo. While the tools currently focus on SCAI, they hopefully also facilitate completing the transition to ITE-6/ITE-9 in in-toto-python and in-toto-golang.

I'd appreciate any and all feedback from the community about this transfer. Thanks!

Transfer in-toto-attestation-verifier to in-toto org

I've been working on a prototype implementation of ITEs 10 and 11. Currently, this lives in my GitHub namespace: https://github.com/adityasaky/in-toto-attestation-verifier.

I propose moving this prototype to the in-toto namespace for further development, likely as https://github.com/in-toto/attestation-verifier. I've discussed with @marcelamelara about helping co-maintain the verifier until it's ready to be archived and integrated into other in-toto implementations.

Improve introductory docs

in-toto has grown quite a bit in the last few years and a lot of the work happening in the project is in distinct repositories that aren't easy to find or grok. This has meant that people who are unfamiliar with the project have difficulty coherently understanding the project as a whole. Even folks who are acquainted with in-toto are often surprised to learn about other capabilities. For example, one person I was talking to in the supply chain security space knew of in-toto for its attestation framework and was surprised to learn of the main specification with in-toto layouts etc. Now that the main specification has reached v1 and the attestation framework has also matured, I think we should spend some time on introducing people to in-toto as a whole.

Updates to in-toto.io

The website is now quite outdated. Until recently, it didn't even call out the attestation framework. I propose revamping the website and making the content of https://in-toto.io/in-toto/ much more concrete, possibly with examples.

in-toto 101

In addition, it might be helpful to provide slightly more detailed posts that explore in-toto attestations, layouts, and how they come together. We lack quite a bit here as our existing material may not be geared to newcomers.

Videos?

Finally, I think it might be helpful to have short intro videos, likely no more than three or four, that provide an overview of in-toto, how and where it's used, and how to get started with adopting in-toto. I wonder if the CNCF can help us out here?

And more?

I've listed some initial ideas but there's room for more! For example, we could further flesh out in-toto/friends and turn them into user stories / adoption blog posts on the CNCF blog.

Donation of Archivista

This is a related issue to #15:

• Archivista Repository: https://github.com/testifysec/archivista

Following the guidance of the ITSC, we'd like this issues to serve as the record of the ITSC's vote and the follow up actions required for and following the donation:

• A majority of the ITSC members vote to accept the donation.
• Labeling of archivista as experimental (or according to a future maturity model developed by the ITSC).
• That label can be reviewed once the ITSC formalizes the sub-project maturity model.

Donation of Witness, Archivista, and related repositories

Hello in-toto community! 👋

TestifySec (@colek42, @mikhailswift, and myself) would like to propose the donation of Witness 🦉 & Archivista to the in-toto project.

As a company, we are committed to open source software and the success of the in-toto project. We believe that the donation of these projects can help enable experimentation, development, and adoption of in-toto as the industry standard framework for creating and validating attestations.

In alignment with our "default open" approach to developing software, we're making this proposal before these projects are perfect. I will keep a list of outstanding issues to resolve and follow up tasks below, based on feedback from the community and ITSC.

Additionally, in light of our company's sponsorship of these projects, we'd also like to ensure the community and ITSC's review of the governance model, as it applies to these projects. There are no outstanding gaps that I see but, we want the continued development of these projects to be above board and in alignment with the highest standards of the CNCF and in-toto project.

Thank you for your consideration and feedback. 🙇‍♂️

👇 Additional background below 👇

Without going into extreme detail of each project, I'd like to highlight how I see Witness and Archivista accomplishing the above goal of enabling the continued success of the in-toto project.

Witness

Witness is a pluggable framework for supply chain security, enabled by an attestor model to create in-toto attestations. Witness attestors are pieces of code that assert facts about a system and store those facts in a versioned schema. The attestors follow a lifecycle that can coordinate the ordering and creation of predicates during the observation of a command.

The pluggable model of attestors enables experimentation with new predicate types by allowing an implementation to focus on the predicate details to be gathered, and not the common code required to implement a DSSE envelope, signing of that envelope with different key providers, or instrumenting a command to be observed. From a consumer perspective, witness can be used without enabling the attestors that are in a state of experimentation or development.

This attestation model can also be verified by a Witness policy. While this model may be slightly diverged from ITE-10 and ITE-11, we plan to soon align with @adityasaky's in-toto-attestation-verifier.

Archivista

If an attestation is created but, never verified, is it really an attestation? As the amount of supply chain metadata continues to increase, the management of those attestations becomes a harder problem to manually solve. There's no way around the need of the attestations created by a supply chain to verify a policy written for that supply chain.

Archivista is our proposed solution to that problem. This solution is constrained to the problem-space of storing and retrieving attestations. When attestations are stored, a graph is created based on the predicate-type and subjects of that attestation. This allows the validation of a policy, without having to specify each and every attestation that was created for an artifact.

This solution may not be an one-size-fits-all encompassing solution but, it will enable for iteration on more complex policies that combine multiple attestations and layouts without an excessive burden on a consumer. TestifySec operates a publicly available instance of Archivista here.

Related Projects

A list of related project summaries can be found on our community page. The repositories range from "Getting Started" guides to showcases of advanced uses of in-toto attestations. The advanced use-cases include:

• a Witness Github Action for creating attestations during a Github Actions workflow
• a Gatekeeper external data provider to enable admission control of container images based on policy compliance

Outstanding Issues to Resolve ✅

• Communication of proposal during in-toto community call
• License and Copyright review of all projects
• Establishment of project maintainers across multiple companies/organizations
• ITSC Approval

Label repositories with maturity and other attributes.

We should label the repos in the org with information about the maturity and other aspects (experimental, etc.)

First ITSC election thread

Hi All,

With the charter and election process ready to merge, we are all set to carry out elections.
I'll be collecting the name of nominated candidates, and you can add yourself to the list as follows:

1. By replying to this issue with your name and indicating your interest to nominate yourself, or somebody else.
2. By reaching out to me through my email/slack if you don't want to broadcast this
3. By reaching out in the corresponding email thread in a similar way to above

I'll be collecting the names for a couple of days, and then announce the vote site. As a reminder, here's the timeline

1. Self-nominations will be received through an issue in the /community repository in the in-toto project's GitHub site on March 6th, 2023
2. Nominations will be collected until March 15th
3. The election site will be collected until March 31st, 2023
4. The results will be announced on April 1st, 2023
5. The ITSC will start activities on April 18th, 2023

Please let me know if you have any questions or concerns about the process!

Add blog-contribution-guidelines

Description:

We need to establish clear guidelines for contributing blog posts to our project. This will help maintain the quality and consistency of our blog content and make it easier for new contributors to understand our expectations and processes.