├── .github └── ISSUE_TEMPLATE │ ├── feature_request.md │ └── issue.md ├── CODE-OF-CONDUCT.md ├── CONTRIBUTING.md ├── GOVERNANCE.md ├── LICENSE.md ├── MAINTAINERS.md ├── README.md ├── SECURITY.md ├── design-doc.md ├── images ├── image1.png └── image2.png └── specification.md /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature Request 3 | about: Suggest an idea for improvement 4 | --- 5 | 6 | ## Feature Request 7 | 8 | **Description:** 9 | A clear and concise description of the feature request. 10 | 11 | **Motivation:** 12 | Explain why this feature is relevant or provide context. 13 | 14 | **Proposed Solution:** 15 | If you have ideas on how to implement the feature, describe them here. 16 | 17 | **Additional Context:** 18 | Any additional information or context that might be helpful. 19 | 20 | **Screenshots or Mockups (if applicable):** 21 | Include screenshots or design mockups if they help convey information. 22 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/issue.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: General Issue 3 | about: Create a new issue 4 | --- 5 | 6 | ## Issue 7 | 8 | **Description:** 9 | A clear and concise description of the issue or topic. 10 | 11 | **Motivation (if applicable):** 12 | Explain why this issue is relevant or provide context. 13 | 14 | **Proposed Solution (if applicable):** 15 | If you have ideas on how to address the issue, describe them here. 16 | 17 | **Additional Context:** 18 | Any additional information or context that might be helpful. 19 | 20 | **Screenshots (if applicable):** 21 | Include screenshots or images if they help convey information. 22 | 23 | **Environment (if applicable):** 24 | - Operating System: [e.g., Windows 10, macOS, Linux] 25 | - Browser (if applicable): [e.g., Chrome, Firefox, Safari] 26 | - Version/Commit (if applicable): [e.g., 1.2.3 or commit hash] 27 | 28 | **Related Issues (if any):** 29 | List any related issues here. 30 | 31 | **Labels (optional):** 32 | Specify any relevant labels to categorize this issue. 33 | 34 | **Assignees (optional):** 35 | Assign this issue to specific contributors, if applicable. 36 | -------------------------------------------------------------------------------- /CODE-OF-CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | We as members, contributors, and leaders pledge to make participation in this 6 | project and our community a harassment-free experience for everyone, regardless 7 | of age, body size, visible or invisible disability, ethnicity, sex 8 | characteristics, gender identity and expression, level of experience, 9 | education, socio-economic status, nationality, personal appearance, race, 10 | religion, or sexual identity and orientation. 11 | 12 | We pledge to act and interact in ways that contribute to an open, welcoming, 13 | diverse, inclusive, and healthy community. 14 | 15 | ## Our Standards 16 | 17 | Examples of behavior that contributes to a positive environment for our 18 | community include: 19 | 20 | * Demonstrating empathy and kindness toward other people 21 | * Being respectful of differing opinions, viewpoints, and experiences 22 | * Giving and gracefully accepting constructive feedback 23 | * Accepting responsibility and apologizing to those affected by our mistakes, 24 | and learning from the experience 25 | * Focusing on what is best not just for us as individuals, but for the 26 | overall community 27 | 28 | Examples of unacceptable behavior include: 29 | 30 | * The use of sexualized language or imagery, and sexual attention or 31 | advances of any kind 32 | * Trolling, insulting or derogatory comments, and personal or political attacks 33 | * Public or private harassment 34 | * Publishing others' private information, such as a physical or email 35 | address, without their explicit permission 36 | * Other conduct which could reasonably be considered inappropriate in a 37 | professional setting 38 | 39 | ## Enforcement Responsibilities 40 | 41 | Community leaders are responsible for clarifying and enforcing our standards of 42 | acceptable behavior and will take appropriate and fair corrective action in 43 | response to any behavior that they deem inappropriate, threatening, offensive, 44 | or harmful. 45 | 46 | Community leaders have the right and responsibility to remove, edit, or reject 47 | comments, commits, code, wiki edits, issues, and other contributions that are 48 | not aligned to this Code of Conduct, and will communicate reasons for moderation 49 | decisions when appropriate. 50 | 51 | ## Scope 52 | 53 | This Code of Conduct applies within all community spaces, and also applies when 54 | an individual is officially representing the community in public spaces. 55 | Examples of representing our community include using an official e-mail address, 56 | posting via an official social media account, or acting as an appointed 57 | representative at an online or offline event. 58 | 59 | ## Enforcement 60 | 61 | Instances of abusive, harassing, or otherwise unacceptable behavior may be 62 | reported to the community leaders responsible for enforcement by contacting any 63 | non-emeritus [SBOMit maintainer](MAINTAINERS.md). All complaints will be 64 | reviewed and investigated promptly and fairly. 65 | 66 | All community leaders and maintainers are obligated to respect the privacy and 67 | security of the reporter of any incident. 68 | 69 | ## Enforcement Guidelines 70 | 71 | 72 | Community leaders will follow these Community Impact Guidelines in determining 73 | the consequences for any action they deem in violation of this Code of Conduct: 74 | 75 | 1. Correction 76 | 77 | **Community Impact**: Use of inappropriate language or other behavior deemed 78 | unprofessional or unwelcome in the community. 79 | 80 | **Consequence**: A private, written warning from community leaders, providing 81 | clarity around the nature of the violation and an explanation of why the 82 | behavior was inappropriate. A public apology may be requested. 83 | 84 | 2. Warning 85 | 86 | **Community Impact**: A violation through a single incident or series 87 | of actions. 88 | 89 | **Consequence**: A warning with consequences for continued behavior. No 90 | interaction with the people involved, including unsolicited interaction with 91 | those enforcing the Code of Conduct, for a specified period of time. This 92 | includes avoiding interactions in community spaces as well as external channels 93 | like social media. Violating these terms may lead to a temporary or 94 | permanent ban. 95 | 96 | 3. Temporary Ban 97 | 98 | **Community Impact**: A serious violation of community standards, including 99 | sustained inappropriate behavior. 100 | 101 | **Consequence**: A temporary ban from any sort of interaction or public 102 | communication with the community for a specified period of time. No public or 103 | private interaction with the people involved, including unsolicited interaction 104 | with those enforcing the Code of Conduct, is allowed during this period. 105 | Violating these terms may lead to a permanent ban. 106 | 107 | 4. Permanent Ban 108 | 109 | **Community Impact**: Demonstrating a pattern of violation of community 110 | standards, including sustained inappropriate behavior, harassment of an 111 | individual, or aggression toward or disparagement of classes of individuals. 112 | 113 | **Consequence**: A permanent ban from any sort of public interaction within 114 | the community. 115 | 116 | # Attribution 117 | 118 | This Code of Conduct is adapted from the [Contributor Covenant, 119 | version 2.0](https://www.contributor-covenant.org/version/2/0/code_of_conduct.html). 120 | 121 | Community Impact Guidelines were inspired by [Mozilla's code of conduct 122 | enforcement ladder](https://github.com/mozilla/diversity). 123 | 124 | For answers to common questions about this code of conduct, see the FAQ at 125 | https://www.contributor-covenant.org/faq. Translations are available at 126 | https://www.contributor-covenant.org/translations. 127 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing To SBOMit 2 | 3 | We welcome contributions to the SBOMit project! By participating in this project, you agree to abide by the [Code of Conduct](code-of-conduct.md). 4 | 5 | ## Getting Started 6 | 7 | To contribute to the SBOMit specification repository, follow these steps: 8 | 9 | 1. Fork the repository. 10 | 2. Create a new branch for your contribution: 11 | ``` 12 | git checkout -b feature/new-feature 13 | ``` 14 | 3. Make your desired changes to the codebase. 15 | 4. Commit your changes with a descriptive commit message. 16 | 5. Push your branch to your forked repository: 17 | ``` 18 | git push origin feature/new-feature 19 | ``` 20 | 6. Open a pull request against the `main` branch of the SBOMit specification repository. 21 | 22 | For larger changes, please discuss your ideas with the community in an issue before starting to work on them. 23 | 24 | ## Feature Request 25 | 26 | If you wish to propose a new feature, we kindly request that you adhere to our established procedures by following the official [feature request template](/.github/ISSUE_TEMPLATE/feature_request.md) feature request template. The template provides essential guidance to ensure a comprehensive and structured submission of your feature request. Thank you for your cooperation and commitment to our project's standards. 27 | 28 | ## Maintainers 29 | 30 | For questions, guidance, and assistance with specific areas of the codebase, please contact the relevant maintainers listed in the [MAINTAINERS.md](MAINTAINERS.md) file. 31 | 32 | ## Create an Issue or Bug 33 | 34 | If you encounter any issues/bugs or have suggestions for improvements, please open an issue on the [issue tracker](https://github.com/SBOMit/specification/issues) and follow the [issue template](/.github/ISSUE_TEMPLATE/issue.md) for guidance on creating a issue/bug. 35 | 36 | ## Developer Certificate of Origin 37 | 38 | To ensure a clear licensing history and proper attribution, code commits in the project require a signoff. The signoff indicates that you have read and agree to the Developer Certificate of Origin (DCO), which states that you have the right to contribute the code and that it does not infringe on any copyright or intellectual property rights. The DCO signoff helps protect the project and its contributors. 39 | 40 | By making a contribution to this project, I certify that: 41 | 42 | 1. The contribution was created in whole or in part by me and I have the right to submit it under the open source license indicated in the file; or 43 | 44 | 2. The contribution is based upon previous work that, to the best of my knowledge, is covered under an appropriate open source license and I have the right under that license to submit that work with modifications, whether created in whole or in part by me, under the same open source license (unless I am permitted to submit under a different license), as indicated in the file; or 45 | 46 | 3. The contribution was provided directly to me by some other person who certified 1., 2. or 3. and I have not modified it. 47 | 48 | 4. I understand and agree that this project and the contribution are public and that a record of the contribution (including all personal information I submit with it, including my sign-off) is maintained indefinitely and may be redistributed consistent with this project or the open source license(s) involved. 49 | 50 | ## License 51 | 52 | When contributing to the SBOMit project, it is important to understand and agree to the licensing terms. All contributions to the project will be licensed under the Community Specification License 1.0. By submitting a pull request, you are agreeing to these terms. 53 | 54 | Thank you for contributing to SBOMit project! We appreciate your help in making our project better. -------------------------------------------------------------------------------- /GOVERNANCE.md: -------------------------------------------------------------------------------- 1 | # SBOMit project governance 2 | This document covers the project's governance and committer process. The 3 | project consists of the 4 | [SBOMit specification](https://github.com/SBOMit/specification), related documentation, and 5 | implemenations hosted under the organization. 6 | 7 | ## Code of Conduct 8 | 9 | The SBOMit community abides by the Open Source Software Foundation's [code of conduct](/CODE-OF-CONDUCT.md). An excerpt follows: 10 | 11 | > We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, 12 | > regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, 13 | > level of experience, education, socio-economic status, nationality, personal appearance, race, caste, color, religion, or sexual 14 | > identity and orientation. 15 | 16 | SBOMit community members represent the project and their fellow contributors. We value our 17 | community tremendously, and we'd like to keep cultivating a friendly and collaborative environment 18 | for our contributors and users. We want everyone in the community to have a positive experience. 19 | 20 | We also interact closely with other open source groups and projects, most notably the [CNCF project](https://www.cncf.io/) 21 | [in-toto](https://in-toto.io). Maintaining a productive and healthy collaborative relationship with projects hosted at other open 22 | source foundations is also a major goal. 23 | 24 | 25 | ## Maintainership and Consensus Builder 26 | The project is maintained by the people indicated in 27 | [MAINTAINERS.txt](MAINTAINERS.txt). A maintainer is expected to (1) submit and 28 | review GitHub pull requests and (2) open issues. 29 | A maintainer has the authority to approve or reject pull requests submitted by 30 | contributors. Any maintainer may also interact with the OpenSSF TAC on behalf of the 31 | project. 32 | 33 | 34 | ## Specification Contributions 35 | A contributor can submit GitHub pull requests to the project's repositories. 36 | They must follow the project's [code of 37 | conduct](CODE-OF-CONDUCT.md) and the [Developer Certificate of 38 | Origin (DCO)](https://developercertificate.org/). Submitted pull 39 | requests undergo review for the following required items: 40 | 41 | * Checks for *Signed-off-by* commits via [Probot: DCO](https://probot.github.io/apps/dco/) 42 | * Review by one or more [maintainers](MAINTAINERS.txt) 43 | 44 | Note that the depth of maintainer review will depend on the scope of the change. 45 | A minor clarification or typo may be approved by a single maintainer, while a 46 | change in project scope or a design change, will involve a discussion period 47 | where all maintainers have time to review and participate. 48 | 49 | At this time, we do not formalize the process of proposing and accepting changes, 50 | but expect as the specification matures that this will be added as is needed. 51 | We likely will model in-toto's ITE process to keep strong alignment with that 52 | project. 53 | 54 | ## Changes in maintainership 55 | Active contributors may be offered or request to be granted maintainer status. 56 | This requires approval from a 2/3 majority of currently voting maintainers with at 57 | least a 72 hour public voting period. 58 | 59 | Maintainers may be moved to emeritus status. This is done at the request of the 60 | maintainer moving to emeritus at any time. Alternatively, moving a maintainer to 61 | emeritus status may be proposed by any maintainer and will be passed with a 2/3 62 | majority of voting maintainers with at least a 72 hour public voting period. 63 | Emeritus maintainers are listed in the MAINTAINERS.txt file as acknowledgment for 64 | their prior service to the project, but no longer have code review, voting, or other 65 | maintainer privileges for the project. 66 | 67 | ## Changes in governance 68 | The maintainers supervise changes in governance. Changes are approved by a 2/3 69 | majority of voting maintainers with a 72 hour public voting / discussion period. 70 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | # Community Specification License 1.0 2 | 3 | **The Purpose of this License.** This License sets forth the terms under which 1) Contributor will participate in and contribute to the development of specifications, standards, best practices, guidelines, and other similar materials under this Working Group, and 2) how the materials developed under this License may be used. It is not intended for source code. Capitalized terms are defined in the License’s last section. 4 | 5 | **1. Copyright.** 6 | 7 | **1.1. Copyright License.** Contributor grants everyone a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) copyright license, without any obligation for accounting, to reproduce, prepare derivative works of, publicly display, publicly perform, and distribute any materials it submits to the full extent of its copyright interest in those materials. Contributor also acknowledges that the Working Group may exercise copyright rights in the Specification, including the rights to submit the Specification to another standards organization. 8 | 9 | **1.2. Copyright Attribution.** As a condition, anyone exercising this copyright license must include attribution to the Working Group in any derivative work based on materials developed by the Working Group. That attribution must include, at minimum, the material’s name, version number, and source from where the materials were retrieved. Attribution is not required for implementations of the Specification. 10 | 11 | **2. Patents.** 12 | 13 | **2.1. Patent License.** 14 | 15 | **2.1.1. As a Result of Contributions.** 16 | 17 | **2.1.1.1. As a Result of Contributions to Draft Specifications.** Contributor grants Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims in 1) Contributor’s Contributions and 2) to the Draft Specification that is within Scope as of the date of that Contribution, in both cases for Licensee’s Implementation of the Draft Specification, except for those patent claims excluded by Contributor under Section 3. 18 | 19 | **2.1.1.2. For Approved Specifications.** Contributor grants Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims included the Approved Specification that are within Scope for Licensee’s Implementation of the Approved Specification, except for those patent claims excluded by Contributor under Section 3. 20 | 21 | **2.1.2. Patent Grant from Licensee.** Licensee grants each other Licensee a non-sublicensable, perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as expressly stated in this License) license to its Necessary Claims for its Implementation, except for those patent claims excluded under Section 3. 22 | 23 | **2.1.3. Licensee Acceptance.** The patent grants set forth in Section 2.1 extend only to Licensees that have indicated their agreement to this License as follows: 24 | 25 | **2.1.3.1. Source Code Distributions.** For distribution in source code, by including this License in the root directory of the source code with the Implementation; 26 | 27 | **2.1.3.2. Non-Source Code Distributions.** For distribution in any form other than source code, by including this License in the documentation, legal notices, via notice in the software, and/or other written materials provided with the Implementation; or 28 | 29 | **2.1.3.3. Via Notices.md.** By issuing pull request or commit to the Specification’s repository’s Notices.md file by the Implementer’s authorized representative, including the Implementer’s name, authorized individual and system identifier, and Specification version. 30 | 31 | **2.1.4. Defensive Termination.** If any Licensee files or maintains a claim in a court asserting that a Necessary Claim is infringed by an Implementation, any licenses granted under this License to the Licensee are immediately terminated unless 1) that claim is directly in response to a claim against Licensee regarding an Implementation, or 2) that claim was brought to enforce the terms of this License, including intervention in a third-party action by a Licensee. 32 | 33 | **2.1.5. Additional Conditions.** This License is not an assurance (i) that any of Contributor’s copyrights or issued patent claims cover an Implementation of the Specification or are enforceable or (ii) that an Implementation of the Specification would not infringe intellectual property rights of any third party. 34 | 35 | **2.2. Patent Licensing Commitment.** In addition to the rights granted in Section 2.1, Contributor agrees to grant everyone a no charge, royalty-free license on reasonable and non-discriminatory terms to Contributor’s Necessary Claims that are within Scope for: 36 | 1) Implementations of a Draft Specification, where such license applies only to those Necessary Claims infringed by implementing Contributor's Contribution(s) included in that Draft Specification, and 37 | 2) Implementations of the Approved Specification. 38 | 39 | This patent licensing commitment does not apply to those claims subject to Contributor’s Exclusion Notice under Section 3. 40 | 41 | **2.3. Effect of Withdrawal.** Contributor may withdraw from the Working Group by issuing a pull request or commit providing notice of withdrawal to the Working Group repository’s Notices.md file. All of Contributor’s existing commitments and obligations with respect to the Working Group up to the date of that withdrawal notice will remain in effect, but no new obligations will be incurred. 42 | 43 | **2.4. Binding Encumbrance.** This License is binding on any future owner, assignee, or party who has been given the right to enforce any Necessary Claims against third parties. 44 | 45 | **3. Patent Exclusion.** 46 | 47 | **3.1. As a Result of Contributions.** Contributor may exclude Necessary Claims from its licensing commitments incurred under Section 2.1.1 by issuing an Exclusion Notice within 45 days of the date of that Contribution. Contributor may not issue an Exclusion Notice for any material that has been included in a Draft Deliverable for more than 45 days prior to the date of that Contribution. 48 | 49 | **3.2. As a Result of a Draft Specification Becoming an Approved Specification.** Prior to the adoption of a Draft Specification as an Approved Specification, Contributor may exclude Necessary Claims from its licensing commitments under this Agreement by issuing an Exclusion Notice. Contributor may not issue an Exclusion Notice for patents that were eligible to have been excluded pursuant to Section 3.1. 50 | 51 | **4. Source Code License.** Any source code developed by the Working Group is solely subject the source code license included in the Working Group’s repository for that code. If no source code license is included, the source code will be subject to the MIT License. 52 | 53 | **5. No Other Rights.** Except as specifically set forth in this License, no other express or implied patent, trademark, copyright, or other rights are granted under this License, including by implication, waiver, or estoppel. 54 | 55 | **6. Antitrust Compliance.** Contributor acknowledge that it may compete with other participants in various lines of business and that it is therefore imperative that they and their respective representatives act in a manner that does not violate any applicable antitrust laws and regulations. This License does not restrict any Contributor from engaging in similar specification development projects. Each Contributor may design, develop, manufacture, acquire or market competitive deliverables, products, and services, and conduct its business, in whatever way it chooses. No Contributor is obligated to announce or market any products or services. Without limiting the generality of the foregoing, the Contributors agree not to have any discussion relating to any product pricing, methods or channels of product distribution, division of markets, allocation of customers or any other topic that should not be discussed among competitors under the auspices of the Working Group. 56 | 57 | **7. Non-Circumvention.** Contributor agrees that it will not intentionally take or willfully assist any third party to take any action for the purpose of circumventing any obligations under this License. 58 | 59 | **8. Representations, Warranties and Disclaimers.** 60 | 61 | **8.1. Representations, Warranties and Disclaimers.** Contributor and Licensee represents and warrants that 1) it is legally entitled to grant the rights set forth in this License and 2) it will not intentionally include any third party materials in any Contribution unless those materials are available under terms that do not conflict with this License. IN ALL OTHER RESPECTS ITS CONTRIBUTIONS ARE PROVIDED "AS IS." The entire risk as to implementing or otherwise using the Contribution or the Specification is assumed by the implementer and user. Except as stated herein, CONTRIBUTOR AND LICENSEE EXPRESSLY DISCLAIM ANY WARRANTIES (EXPRESS, IMPLIED, OR OTHERWISE), INCLUDING IMPLIED WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, FITNESS FOR A PARTICULAR PURPOSE, CONDITIONS OF QUALITY, OR TITLE, RELATED TO THE CONTRIBUTION OR THE SPECIFICATION. IN NO EVENT WILL ANY PARTY BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Any obligations regarding the transfer, successors in interest, or assignment of Necessary Claims will be satisfied if Contributor or Licensee notifies the transferee or assignee of any patent that it knows contains Necessary Claims or necessary claims under this License. Nothing in this License requires Contributor to undertake a patent search. If Contributor is 1) employed by or acting on behalf of an employer, 2) is making a Contribution under the direction or control of a third party, or 3) is making the Contribution as a consultant, contractor, or under another similar relationship with a third party, Contributor represents that they have been authorized by that party to enter into this License on its behalf. 62 | 63 | **8.2. Distribution Disclaimer.** Any distributions of technical information to third parties must include a notice materially similar to the following: “THESE MATERIALS ARE PROVIDED “AS IS.” The Contributors and Licensees expressly disclaim any warranties (express, implied, or otherwise), including implied warranties of merchantability, non-infringement, fitness for a particular purpose, or title, related to the materials. The entire risk as to implementing or otherwise using the materials is assumed by the implementer and user. IN NO EVENT WILL THE CONTRIBUTORS OR LICENSEES BE LIABLE TO ANY OTHER PARTY FOR LOST PROFITS OR ANY FORM OF INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES OF ANY CHARACTER FROM ANY CAUSES OF ACTION OF ANY KIND WITH RESPECT TO THIS DELIVERABLE OR ITS GOVERNING AGREEMENT, WHETHER BASED ON BREACH OF CONTRACT, TORT (INCLUDING NEGLIGENCE), OR OTHERWISE, AND WHETHER OR NOT THE OTHER MEMBER HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.” 64 | 65 | **9. Definitions.** 66 | 67 | **9.1. Affiliate.** “Affiliate” means an entity that directly or indirectly Controls, is Controlled by, or is under common Control of that party. 68 | 69 | **9.2. Approved Specification.** “Approved Specification” means the final version and contents of any Draft Specification designated as an Approved Specification as set forth in the accompanying Governance.md file. 70 | 71 | **9.3. Contribution.** “Contribution” means any original work of authorship, including any modifications or additions to an existing work, that Contributor submits for inclusion in a Draft Specification, which is included in a Draft Specification or Approved Specification. 72 | 73 | **9.4. Contributor.** “Contributor” means any person or entity that has indicated its acceptance of the License 1) by making a Contribution to the Specification, or 2) by entering into the Community Specification Contributor License Agreement for the Specification. Contributor includes its Affiliates, assigns, agents, and successors in interest. 74 | 75 | **9.5. Control.** “Control” means direct or indirect control of more than 50% of the voting power to elect directors of that corporation, or for any other entity, the power to direct management of such entity. 76 | 77 | **9.6. Draft Specification.** “Draft Specification” means all versions of the material (except an Approved Specification) developed by this Working Group for the purpose of creating, commenting on, revising, updating, modifying, or adding to any document that is to be considered for inclusion in the Approved Specification. 78 | 79 | **9.7. Exclusion Notice.** “Exclusion Notice” means a written notice made by making a pull request or commit to the repository’s Notices.md file that identifies patents that Contributor is excluding from its patent licensing commitments under this License. The Exclusion Notice for issued patents and published applications must include the Draft Specification’s name, patent number(s) or title and application number(s), as the case may be, for each of the issued patent(s) or pending patent application(s) that the Contributor is excluding from the royalty-free licensing commitment set forth in this License. If an issued patent or pending patent application that may contain Necessary Claims is not set forth in the Exclusion Notice, those Necessary Claims shall continue to be subject to the licensing commitments under this License. The Exclusion Notice for unpublished patent applications must provide either: (i) the text of the filed application; or (ii) identification of the specific part(s) of the Draft Specification whose implementation makes the excluded claim a Necessary Claim. If (ii) is chosen, the effect of the exclusion will be limited to the identified part(s) of the Draft Specification. 80 | 81 | **9.8. Implementation.** “Implementation” means making, using, selling, offering for sale, importing or distributing any implementation of the Specification 1) only to the extent it implements the Specification and 2) so long as all required portions of the Specification are implemented. 82 | 83 | **9.9. License.** “License” means this Community Specification License. 84 | 85 | **9.10. Licensee.** “Licensee” means any person or entity that has indicated its acceptance of the License as set forth in Section 2.1.3. Licensee includes its Affiliates, assigns, agents, and successors in interest. 86 | 87 | **9.11. Necessary Claims.** “Necessary Claims” are those patent claims, if any, that a party owns or controls, including those claims later acquired, that are necessary to implement the required portions (including the required elements of optional portions) of the Specification that are described in detail and not merely referenced in the Specification. 88 | 89 | **9.12. Specification.** “Specification” means a Draft Specification or Approved Specification included in the Working Group’s repository subject to this License, and the version of the Specification implemented by the Licensee. 90 | 91 | **9.13. Scope.** “Scope” has the meaning as set forth in the accompanying Scope.md file included in this Specification’s repository. Changes to Scope do not apply retroactively. If no Scope is provided, each Contributor’s Necessary Claims are limited to that Contributor’s Contributions. 92 | 93 | **9.14. Working Group.** “Working Group” means this project to develop specifications, standards, best practices, guidelines, and other similar materials under this License. 94 | 95 | 96 | 97 | *The text of this Community Specification License is Copyright 2020 Joint Development Foundation and is licensed under the Creative Commons Attribution 4.0 International License available at https://creativecommons.org/licenses/by/4.0/.* 98 | 99 | SPDX-License-Identifier: CC-BY-4.0 -------------------------------------------------------------------------------- /MAINTAINERS.md: -------------------------------------------------------------------------------- 1 | The project is managed by the following set of maintainers. 2 | Please see GOVERNANCE.md for the project's governance and maintainership. 3 | 4 | # Maintainers 5 | 6 | ## Justin Cappos 7 | * Email: jcappos@nyu.edu 8 | * GitHub username: [@JustinCappos](https://github.com/JustinCappos) 9 | * PGP fingerprint: E9C0 59EC 0D32 64FA B35F 94AD 465B F9F6 F8EB 475A 10 | 11 | ## Ian Dunbar-Hall 12 | * Email: ian.dunbar-hall@lmco.com 13 | * GitHub username: [@idunbarh](https://github.com/idunbarh) 14 | 15 | ## Cole Kennedy 16 | * Email: colek42@gmail.com 17 | * GitHub username: [@colek42](https://github.com/colek42) 18 | 19 | ## Marina Moore 20 | * Email: mm9693@nyu.edu 21 | * GitHub username: [@mnm678](https://github.com/mnm678) 22 | 23 | # Emeritus 24 | 25 | ## Trishank Karthik Kuppusamy 26 | * Email: trishank.kuppusamy@datadoghq.com 27 | * GitHub username: [@trishankatdatadog](https://github.com/trishankatdatadog) 28 | * Keybase: [@trishankatdatadog](https://keybase.io/trishankdatadog) 29 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # SBOMit specification 2 | 3 | [TODO: This is where we will write a specification.] 4 | 5 | The SBOMit specification is licensed under the [Creative Commons Attribution 4.0 International Public License](LICENSE.md). 6 | 7 | # Meetings 8 | 9 | * Schedule: every Wednesday (weekly) at 11am US Eastern time at [this Zoom meeting](https://nyu.zoom.us/j/91097299041) 10 | * [Notes](https://docs.google.com/document/d/1-nHXMqvWNzgOxAq08O8Wu2BTHz0U60yBoAklrJAMaRc/edit?usp=sharing) 11 | * Code of Conduct 12 | * Let others talk (don't interrupt) 13 | * Be polite when you disagree 14 | * Be respectful of others' time (e.g., no rambling, and limit piggybacking in agreement) 15 | * We’ll tend to defer things that start to dominate to a future meeting and put a fixed slot up for it 16 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Reporting Security Issues 2 | 3 | Please report security issues **confidentially** using 4 | [GitHub's form](https://github.com/SBOMit/specification/security/advisories/new). 5 | 6 | **Note:** Please do not report such issues publicly on the issue tracker. The 7 | *issue tracker is intended for bug reports and feature requests. 8 | 9 | ## Responding to Reports 10 | 11 | A SBOMit maintainer will respond to the report as soon as possible. After the 12 | report is triaged and the vulnerability is confirmed, a fix will be prepared 13 | under embargo. Once the fix is accepted, a new release will be prepared along 14 | with a report detailing the vulnerability. This report will identify the 15 | reporter unless they request to be kept anonymous. Finally, a CVE may be 16 | requested if appropriate for the vulnerability report. 17 | -------------------------------------------------------------------------------- /design-doc.md: -------------------------------------------------------------------------------- 1 | # SBOMit Design Document 2 | 3 | ## What is SBOMit? 4 | 5 | SBOMit is the name of the project which manages the SBOMit specification format. A SBOMit document is effectively an SBOM, only with additional verification information added that was generated at the time the supply chain was generated. This verification information, which uses in-toto attestations and layouts, is able to be validated by a party to get a high degree of assurances about the software. 6 | 7 | ## What does a SBOMit document contain and why? 8 | 9 | A SBOMit document is a signed document that consists of a few different components. 10 | 11 | First and foremost, it contains a series of in-toto attestations that were generated as the described software was created. This includes detailed information about different steps of the software supply chain, including about the version control system, build process, unit testing, dependencies used, fuzzing, license compliance checks, packaging, etc. For example, the build system used to compile the software in the SBOM has in-toto metadata with the names and secure hashes for the files that were taken from the VCS to be compiled, the names and secure hashes of the files created during compilation, a series of information about the compiler, and a signature by a private key held by the compiler. 12 | 13 | This attestation information can be used in coordination with the second item in the SBOMit document: an in-toto layout. The in-toto layout is signed by the project owner and describes what valid attestation metadata for the project looks like. The layout specifies the private keys for the parties performing the attestations as well as how the steps interconnect. For example, the VCS must have a signed git tag, which the build system then operates over. The files compiled by the build system must be the files that were run through the unit tests, which must have passed. Importantly, an in-toto layout provides a machine-readable policy that can validate the in-toto attestations to ensure that all of those steps were followed, in the right order, on the right items, and with nothing added, skipped, or removed. 14 | 15 | The final item that always appears in the SBOMit document is the supplemental SBOM information. This information along with the in-toto attestations and in-toto layout can be used to derive an actual SBOM in a variety of formats. The supplemental SBOM information may include things such as the company name or other information which isn’t included by in-toto but which is desirable to be included in the resulting SBOM. In this way, an SBOM generated from an SBOMit document, can include supplemental information that was not part of the in-toto process. 16 | 17 | There is also a means to add addendums to an SBOMit document, which will be described later. 18 | 19 | ## What are the advantages of a SBOMit document over using a SBOM generation tool that scans the software? 20 | 21 | Scanning tools are by their nature looking at a piece of software and then trying to determine what happened before. By their nature, they are imperfect because they use incomplete information to try to recover what happened in the past. Practical use has shown that different scanning tools give wildly different results for the same software. 22 | 23 | The in-toto attestation portions of an SBOMit document are generated at the time the software is being processed through the software supply chain. As a result, this information will be much more accurate because in-toto attestations collect detailed information at the time the software product is being made. This makes an SBOMit document much more accurate, by its nature. 24 | 25 | ## What are the advantages of a SBOMit document over simply signing an SBOM? 26 | 27 | A signed SBOM is a signed statement by someone holding the signing key at an organization that says that the SBOM is accurate. If the key is stolen, or the party signing the SBOM is incorrect about how the software was made, then the SBOM will be inaccurate. 28 | 29 | An SBOMit document contains cryptographically signed metadata about all of the steps that went into making the software and describes the policy that must be followed. It is much harder for accidental inaccuracies like skipping a step (which has historically been a problem) or for malicious actions to be undetected. In-toto also provides greater ability to securely recover from a compromise and to detect and resist malicious actions by a party within an organization. 30 | 31 | To use an analogy, an SBOM today is much like a list of ingredients on a product. Only in practice, this information is commonly inaccurate, could be changed by a malicious party, and is not verified. Signing an SBOM helps to stop it from being changed by a malicious party, so you know that the ingredient list you are getting was approved by a specific company. A SBOMit document also describes in detail the process that went into making the product and has metadata and signatures from all the parties involved, including verification that the keys used were current at that time. So, in the case of an SBOMit document, you have a high degree of assurance that the proper policies and procedures were followed. 32 | 33 | For more information on this topic, please see the [What advantages does in-toto provide] FAQ on the in-toto website. 34 | 35 | ## What if a software supply chain contains insecure steps? 36 | 37 | in-toto attestations are not a substitute for having appropriately secure steps in the software supply chain. For example, if you use an insecure process of building software that just curls and builds software from a website, in-toto layouts can list this insecure action and verify signed attestations indicating that you did this insecure action. 38 | 39 | This is why projects like SLSA and FRSCA are built as an opinionated set of rules on top of in-toto steps. They specify which actions are more important for software supply chain security and mandate certain actions. 40 | 41 | These projects are solving different problems at different levels. In-toto allows you to capture information about your steps, ensure policies about them are applied, handle trust of keys, etc. Frameworks like SLSA and FRSCA use in-toto as a mechanism to capture and enforce a specific set of policies that result in more secure supply chains. 42 | 43 | There are efforts to make automated tooling for SLSA and FRSCA to work over in-toto layouts and validate compliance. When these tools mature, they can be integrated to parse an SBOMit document and provide the appropriate scoring level for the software supply chain described therein. Thus a user may then configure their system to only accept SLSA level 4 or better software, which also has a valid SBOMit document. 44 | 45 | ## What if an SBOMit document needs to be changed over time? E.g., asserting it does not have a certain exploitable vulnerability, adding supplemental information later that wasn’t needed at creation time, etc. 46 | 47 | An SBOMit document may have a series of post-facto addendums. These are added after the fact and must be ultimately signed by the original SBOMit document’s master key. These serve to modify the various fields in the SBOMit document or add supplemental information. 48 | 49 | Using addendums versus creating a new SBOMit document has an advantage. In this way both the original document and any addendums will be verifiable and the history of these changes are all contained in the SBOMit document. Thus addendums are the recommended model for handling changes to an SBOMit document. 50 | 51 | 52 | ## Can I derive an SBOM from an SBOMit document? 53 | 54 | Yes! There are various tools in the works that will derive an SBOM from an SBOMit document. You can get SBOMs in a variety of different formats by using different tools. 55 | 56 | 57 | 58 | -------------------------------------------------------------------------------- /images/image1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SBOMit/specification/8c7a8ab51eddcde842530624b0598f3781a4efdd/images/image1.png -------------------------------------------------------------------------------- /images/image2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/SBOMit/specification/8c7a8ab51eddcde842530624b0598f3781a4efdd/images/image2.png -------------------------------------------------------------------------------- /specification.md: -------------------------------------------------------------------------------- 1 | # SBOMit Specification 2 | 3 | This document serves as the 0.1.0 specifications for SBOMit (SBOM on in-toto). The specification should not be considered stable at this time. 4 | 5 | ## 1 Introduction 6 | 7 | ### 1.1 Scope 8 | 9 | This project, SBOMit, an emergent open-source initiative, aims to fortify software supply chain security by enhancing the reliability and integrity of Software Bills of Materials (SBOMs). By making SBOMs tamper-proof and accurate, it mitigates the risk of malicious attacks. Backed by the reach of OpenSSF and the Linux Foundation, the project helps deploy these security standards globally. It also enhances transparency in the software supply chain by offering standardized, dependable information about software elements. Its open-source design promotes industry-wide collaboration, leading to a tool that evolves to meet dynamic security needs. 10 | 11 | ### 1.2 Motivation 12 | 13 | Software Bills of Materials (SBOMs) often suffer from inaccuracy, primarily due to a retrospective approach to software analysis that fails to accurately track components. This challenge is becoming more pressing with the rise of sophisticated supply chain attacks requiring advanced technology and robust frameworks like the Secure Software Development Framework (SSDF) for comprehensive security. The SSDF emphasizes security at every development stage and, in combination with accurate and tamper-proof SBOMs, significantly bolsters supply chain security. Thus, an accurate SBOM forms a solid foundation for enhancing the software supply chain's resilience against increasingly complex and frequent cyberattacks. 14 | 15 | This specification proposes a means to generate metadata for an SBOM while the software is being created. Furthermore, the means by which this information is captured uses [in-toto](https://in-toto.io) attestations and layouts. This provides cryptographic validation that this information is correct, handles key distribution and management to indicate which parties should be trusted for each step, and captures information about the environment in which the steps are run. 16 | 17 | As a result, using SBOMit provides a more accurate SBOM when parties are honest. When malicious parties interfere in the process, SBOMit provides a mix of traceability (knowing which party was malicious) and prevention (blocking malicious software from being trusted), depending on how the in-toto steps are configured. 18 | 19 | ### 1.3 History and credit 20 | 21 | July, 2023 -- Version 0.1.0 of this document is drafted 22 | 23 | ### 1.4 Context 24 | 25 | A Software Bill of Materials (SBOM) is an inventory of all components in a piece of software. These components can be anything from open-source libraries, proprietary modules, or previously written code snippets, which are all considered to be part of the larger, final product. SBOMs are becoming increasingly important in the context of software security, compliance, and quality, as they provide a transparent view of the building blocks of a software product. 26 | 27 | ### 1.5 Terminology 28 | 29 | * **SIT:** refers to an SBOM (Software Bill of Materials) that has been derived from an SBOMit document. It can be formatted in any SBOM style and references the originating SBOMit document used for its creation. 30 | * **SBOMit Document:** is a comprehensive document containing ample information to validate the correctness of the supply chain process. It can be utilized to generate one or more SITs. 31 | * **Software Supply Chain (SSC)**: This represents the sequence of actions taken to create a software product, generally starting from users committing to a version control system and ending with the installation of the software product on a client's system. 32 | * **Supply Chain Layou**t: Also referred to as a layout or layout metadata, this is a signed file that defines the series of steps to be followed in the SSC to create a final product. It details ordered steps, requirements for these steps, and the list of actors or functionaries responsible for executing each step. The steps within the supply chain are established by a project owner. Sublayout: A supply chain layout that describes steps as part of another supply chain layout. 33 | * **Project Owner**: This person is the authoritative figure within a project. The project owner dictates which steps are to be carried out in the supply chain, and who is authorized to carry out each step (i.e., define the layout). 34 | * **Functionary**: This term refers to an individual or an automated script tasked with performing an action within the supply chain. For instance, the entity in charge of compiling a project's source code is a functionary. 35 | * **Supply Chain Step**: This represents a single action in the software supply chain, executed by a functionary. 36 | * **Link**: This refers to metadata information collected while executing a supply chain step or inspection, signed by the functionary that carried out the step or the client who performed the inspection. The metadata can include information such as materials, products, and byproducts. 37 | * **Materials**: These are the elements (e.g., files) utilized to perform a step in the supply chain. Files generated by one step can be materials for a subsequent step. 38 | * **Product**: This is the outcome of a step. Products are usually persistent (e.g., files) and are often used as materials in subsequent steps. Products are recorded as part of link metadata. 39 | * **Artifact**: This term can refer to either a material or a product. 40 | * **Byproducts**: These are the indirect outcomes of performing a step, typically used to verify the correctness of a step. Byproducts are information that won't be used as material in a subsequent step but can provide insight into the process. Examples of byproducts include stdout, stderr, and return values. Byproducts are recorded as part of link metadata. 41 | * **Final Product**: This is the bundle containing all the files required for the software's installation on the client's system. This includes link metadata, layout metadata, target files, and any additional metadata required for the product's verification. 42 | * **Client Inspection Step**: This is a step carried out on the client's machine to verify the information contained in the final product. Client inspection steps also generate link metadata that can be utilized by sub-layouts and other inspection steps. 43 | * **Verification**: This is the process whereby the data and metadata included in the final product are used to ascertain its correctness. Verification is performed by the client by checking the supply chain layout and links for correctness and by performing the inspection steps. 44 | * **Target Files**: These are any files that are not part of in-toto metadata (i.e., not a layout or a link file). In the case of an installer, these files will often be unpacked from within the final product and prepared for use on the user’s system. 45 | 46 | ### 1.6 Goals 47 | 48 | SBOMit seeks to address existing vulnerabilities by facilitating the generation of Software Bills of Materials (SBOMs) that act as a robust shield against software supply chain weaknesses. These SBOMs offer cryptographic validation of the materials used in the software supply chain. Our goal is to improve SBOM accuracy and significantly raise the bar for any attempts to tamper with the supply chains they represent. 49 | 50 | #### 1.6.1 Goals for Implementation 51 | 52 | 1. The framework's client-side implementation should be simple and compatible with any programming language and platform that supports the necessary cryptographic functions. 53 | 2. Integration of the framework should be effortless with existing tools, such as installers, build systems, testing frameworks, version control systems, and software update systems. 54 | 3. The framework should be easily customizable to work with any cryptographic library. 55 | 4. The procedures for functionaries to gather metadata about the steps carried out should be simple and nonintrusive. The same simplicity and non intrusiveness should apply to the processes by which project owners define the supply chain. 56 | 57 | #### 1.6.2 Goals and Non-goals 58 | 59 | **Goals:** 60 | 61 | Goals for Compatibility and User Experience: 62 | 63 | * Maintain compatibility with existing SBOM formats (potentially generating these existing SBOMs), with a preference for operability with initiatives like SPDX, CycloneDX, and similar efforts. 64 | * Define use cases and outcomes, prioritizing end-user experience and machine readability. 65 | * Prioritize usability and user onboarding, a facet recognized as crucial by various stakeholders. 66 | * Incorporate multilingual tooling for broader accessibility. 67 | 68 | Goals for Security and Verification: 69 | 70 | * Ensure cryptographic verification that precisely reflects the steps performed as outlined in the SBOMit document, addressing OSS-RISK-9 and OSS-RISK-5. 71 | * Adopt a threat model that accounts for an attacker capable of compromising any part of the software supply chain, addressing numerous attacks listed under OSS-RISK-2. 72 | * Clearly define the elements of the resulting SBOM that are cryptographically verifiable from in-toto attestations and policies. 73 | * Utilize the in-toto delivery bundle for the distribution of a single file. 74 | * Clearly define a threat model that can uncover potential vulnerabilities, significantly strengthening the system's overall security posture. ([in-toto Security Audit Response](https://www.testifysec.com/blog/in-toto-sec-audit-response/)) 75 | 76 | Goals for Data Capture and Accuracy: 77 | 78 | * Facilitate the optional capture of pertinent information about the runtime environment of supply chain steps, including pre-build, post-build, and all other phases, which aids in addressing many attacks in OSS-RISK-2. 79 | * Ensure a comprehensive and accurate representation of the software described in the resulting SBOMit document, aiding users in identifying issues associated with OSS-RISK-1, OSS-RISK-5, and various other listed items. 80 | * Enable the optional capture of output from scanning tools or similar that may generate inferences. While this information might be based on incomplete or incorrect data, its presentation can be beneficial. 81 | 82 | Goals for Documentation and Clarity: 83 | 84 | * Provide a clear specification that other groups can implement for SBOMit. 85 | * Offer examples of the necessary tooling for generating and processing SBOMit documents. 86 | * Ensure that users of SBOMit documents can clearly understand the steps performed, potentially facilitated by plugins through tools like Testify, SLSA, GUAC, FRSCA, etc. 87 | 88 | **Non-goals:** 89 | 90 | Things we couldn’t handle, but other tools may help. 91 | 92 | Our endeavor is not established to champion a particular SBOM format such as SPDX or CycloneDX. Moreover, it abstains from involvement in the mechanism by which users determine the accurate name or root of trust for the software they install, an issue related to OSS-RISK-3. The project also does not extend its ambit to examine the components, such as packages inside a container image, if the build process doesn't inherently do so, a situation associated with OSS-RISK-6. As the tooling and the utilization of in-toto amplifies, it is anticipated that this concern will be organically addressed with time. 93 | 94 | **Our project is not structured to make judgments about whether a particular action amounts to a sound security practice**, an issue linked to OSS-RISK-8. Concerns about the quality of tool implementation or security processes that describe how the SBOM or artifact was produced, which also correspond to OSS-RISK-8, are not immediate obligations of the project. 95 | 96 | In addition, we are not mandated to conclude whether a dependent software project is adequately maintained and appropriate, an issue associated with OSS-RISK-4 and OSS-RISK-10. Lastly, the accountability of determining the appropriateness of a specific license, an issue related to OSS-RISK-7, is beyond our project's commitments. These issues are more suitably handled by a structure like SLSA or deferred to the user's judgment. 97 | 98 | #### 1.6.3 Assumptions 99 | 100 | First, client-side tools should handle key-management on behalf of the user. Except for the layout key, the client isn't obligated to retrieve or provide keys for verification. We've detailed how complementary frameworks like The Update Framework (TUF) can securely distribute a layout and its keys. When it's relevant, a functionary should be able to delegate full or partial trust to other functionaries to execute steps on their behalf. Additionally, support for remote attestation adds another layer of security, ensuring that the device is running authentic, unaltered software. 101 | 102 | #### 1.6.4 System properties 103 | 104 | To achieve the goals stated above, we present a system with the following properties: 105 | 106 | 1. Firstly, it assures final product authentication and integrity. The client can be confident that the product they receive was created by the intended functionary and that it matches bit-by-bit the contents of the final product reported by the last step in the supply chain. 107 | 2. Secondly, it guarantees process compliance and auditability. The client's product adheres to the layout specified by the project owner. All described steps are correctly linked, and, if audited by a third party, they can verify that all steps were performed as described. For instance, the in-toto metadata may reveal the unit test server’s signed confirmation that the software passed all its unit tests, or it may validate that a certain code review policy was employed by checking git commit signatures. 108 | 3. Furthermore, it ensures traceability and attestation, facilitating the identification of conditions under which each supply chain step was performed, the materials used, and the resulting products. 109 | 4. The system also provides step authentication, meaning that the actor executing various supply chain steps provides unforgeable evidence of the step. For example, if Alice tagged a release, the provided evidence could only be produced by Alice. 110 | 5. Moreover, the system facilitates task and privilege separation, allowing different supply chain steps to be assigned to different functionaries. For example, if only Alice is authorized to tag a release, releases tagged by Bob will not be trusted in the supply chain. 111 | 6. Lastly, the framework should offer an interface to interact with client systems that further verify the integrity of each step. 112 | 113 | ## 2 System Overview 114 | 115 | The main goal of SBOMit is to construct decentralized trust mechanisms with the intention of making the process of deploying software more efficient and straightforward. It accomplishes this by providing a flexible and customized approach, thereby accommodating individual organizational processes. By moving away from conventional code signing methodologies, SBOMit is engineered to offer supplemental information, even if it is not entirely trusted. The goal is to encapsulate and convey code signing trust information effectively, ensuring it resonates with end-users across various communities. 116 | 117 | The following are the high-level steps for deploying the framework, as seen from the viewpoint of an adopter. This is an error-free case: 118 | 119 | 1. Examination and Candidate Description Creation: A developer, aspiring to fortify their software supply chain and generate an SBOM (or equivalent), runs a specific tool on their constructed software. This tool yields a candidate SBOMit layout for the developer. Although this step is technically optional, it facilitates the ensuing step. 120 | 2. Data Collection through Pipeline Instrumentation: Subsequently, the developer recreates their software release process with an encompassing wrapper that collects software supply chain metadata in in-toto attestations. This method automatically generates cryptographic identities for each host involved in the software supply chain steps. Any discrepancies are relayed to the developer for either approval or inspection. 121 | 3. Data Verification against Policy/Layout: The final stage of the release process is set up as verification. Upon completion, the developer can cryptographically confirm that their supply chain has executed the actions specified in the SBOMit document, through validation on the SBOMit document itself. 122 | 123 | ### **2.1 Involved parties and their roles** 124 | 125 | In the context of SBOMit, a role is a set of duties and actions that an actor must perform. 126 | 127 | In the following role descriptions, keep in mind that the framework has been engineered to allow significant flexibility to accommodate various use cases. Given that each project employs a unique set of tools and practices, this is a necessary feature for SBOMit. 128 | 129 | There are three primary roles within the framework: 130 | 131 | 1. **Project Owner**: This role is entrusted with the task of defining the layout of the software supply chain, serving as the root of trust within the system 132 | 2. **Functionary**: This role performs a step in the generation of SBOMs and furnishes a piece of link metadata as a record demonstrating that such a step was carried out 133 | 3. **Client/Verifier**: This role is responsible for performing verification on the final product by checking the provided layout and link metadata. 134 | 135 | These roles are further elaborated on below: 136 | 137 | #### **2.1.1 Project Owner** 138 | 139 | As previously outlined, the project owner determines the steps to be performed in the supply chain. For each step, they specify the requirements and the specific public keys that can sign for evidence of the step to ensure compliance and accountability. Additionally, they write the policy (in-toto layout) and the layout file will contain the definition of inspection steps to be executed when verifying the final product. 140 | 141 | #### **2.1.2 Functionaries** 142 | 143 | Functionaries are tasked with performing steps within the supply chain and providing evidence of this by means of link metadata. 144 | 145 | A functionary is uniquely identified by the public key they use to sign a piece of link metadata, serving as evidence that a step within the supply chain was performed. 146 | 147 | A functionary may perform a step or a series of steps (e.g. adds supplemental information that will appear in an SIT) in the supply chain to a third-party via a sublayout. In this scenario, a subset of the steps to be performed is defined by the functionary, who assumes the role of a project owner for this sublayout. 148 | 149 | #### **2.1.3 Clients/Verifier** 150 | 151 | Clients are either users or automated tools that intend to use the SBOMit. 152 | 153 | In the final stages of the process, the client performs comprehensive verification of the product. This procedure involves several key steps: 154 | 155 | 1. Verification of the layout metadata: The client checks the structure and integrity of the layout to ensure it adheres to the predefined specifications. 156 | 157 | 2. Alignment check between link metadata and layout: This step confirms that the provided link metadata is consistent with the layout detailed in the metadata. 158 | 159 | 3. Execution of inspection steps: The client carries out inspections to verify if the additional metadata and target files comply with the criteria outlined in the layout for this specific inspection step. 160 | 161 | 4. In-toto layout verification: This involves examining the in-toto layout over the provided in-toto metadata to ensure its consistency and correctness. 162 | 163 | 5. SIT verification and generation: Each Software Inventory Template (SIT) is checked to ensure it is appropriately signed by the correct SIT generator. Furthermore, each SIT is generated using relevant tooling, facilitating a detailed examination of the mutator behavior. Through these stringent measures, the client can ensure the robustness of the final product, aligning with the high-security standards set by the project. 164 | 165 | ### 2.2 Threat model 166 | 167 | One key goal of our design is to provide as much security as possible in all cases. Security should degrade gracefully when the attacker gains new capabilities. Hence, we will consider attacker models where the attacker is exceedingly powerful and try to restrict the damage they can do even in those cases. 168 | 169 | There are two types of protection SBOMit commonly provides: 170 | 171 | * traceability -- this enables a party with an SBOMit document and the supply chain to later determine which parties acted in a malicious manner. Note that this may require some further manual analysis (e.g., to determine if an emitted binary is actually a correct output of a build server given a set of source code). However, importantly, properties like non-repudiation hold, so that a party cannot appear to be innocent given a re-execution of a supply chain with all honest participants. 172 | * prevention -- this is when an attack is blocked from having any impact. This often occurs because an attack causes some aspect of validation to fail, resulting in no impact to the end user. This can include situations like an inability to inject malicious metadata into the supply chain, a policy check in an in-toto layout causing a resulting SBOMit document to be rejected, or an inability to sign because of a lack of access to a private key trusted for that signature. 173 | 174 | Note that a party verifying a SIT (only) does not gain the same security guarantees. They instead gain the same sort of guarantees that signed SBOMs have today. However, the SIT contains a reference to the SBOM document, so it may be used to obtain the necessary information to perform more complete verification. 175 | 176 | The actors of the system are the following, each of whom possesses a unique private key: 177 | 178 | * a series of in-toto functionaries that perform the actual steps of the software supply chain. For example, a build server is a functionary. 179 | * a SIT mutator (per SIT), which is a process that adds supplemental information that will appear in an SIT. This is likely performed by a combination of human actions (e.g., listing supplemental information) and automated tooling (e.g., adding information for a specific extended SBOM format). 180 | * a SIT generator (per SIT), which generates the actual SIT file. 181 | * an in-toto layout creator, who specifies the keys used by other parties and writes the policy (in-toto layout) that indicates how different steps of the software supply chain interrelate. This party also serves as the SBOMit root-of-trust. 182 | * a (possibly empty) set of in-toto sub-layout creators. These are identical in action to the in-toto layout creator, but they are only trusted for the subset of the layout which the layout creator delegates. 183 | 184 | We are able to limit attacker damage and/or trace the location of the compromise(s) in cases where: 185 | 186 | * an attacker may possess cryptographic keys for any of the functionaries (the parties performing the software supply chain steps) in the system. \ 187 | _Impact:_ Prevents modification of items not allowed by the in-toto layout. Provides traceability in all cases. No impact without the ability to interject this metadata into the supply chain. 188 | * an attacker may tamper with one or more steps of the software supply chain. For example, the build process, testing, packaging, etc. \ 189 | _Impact:_ Identical to the prior case. 190 | * an attacker obtains a sub-layout key. Note that this also requires the ability to inject sublayout metadata into the supply chain such that other parties include it. _Impact:_The impact could be prevented depending on the restrictions placed upon the delegated sub-layout. However, traceability always exists. This is also similar to a functionary compromise. 191 | * an attacker may become a man-in-the-middle between any steps of the system. _Impact:_Without further capabilities, this has no impact. 192 | * an attacker may possess the key used to sign the SBOM resulting from the SBOMit process. \ 193 | _Impact:_ Prevention for parties performing full SBOMit verification. Traceability otherwise. 194 | * an attacker may compromise an SBOM mutator key or an SBOM mutator may act maliciously. \ 195 | _Impact:_ Traceability in all cases. Depending on the changes made to the SBOM, this may be detected by review of the resulting SBOM. Changes that override in-toto derived information are specifically flagged and unlikely to be accepted. 196 | * an attacker is able to compromise a SIT generator key or a SIT generator directly. \ 197 | _Impact:_ Protection for clients who obtain the SBOMit document. Traceability for other clients. Note that the SIT will contain a reference to the SBOMit document, but this also may be modified in this case. However, the client should have the in-toto layout key and so will notice this action if retrieving the SBOMit document from the SIT. 198 | * an attacker is able to compromise the in-toto layout key, which serves as the root-of-trust for the system. \ 199 | _Impact:_ Traceability. Later analysis can show this was the cause, but users will trust a new, maliciously generated layout which replaces signing keys. 200 | 201 | From [Endor Lab's top 10 OSS risks](https://www.endorlabs.com/blog/introducing-the-top-10-open-source-software-oss-risks), our design largely addresses: 202 | 203 | * OSS-RISK-1 204 | * OSS-RISK-2 205 | * OSS-RISK-5 206 | * OSS-RISK-9 207 | 208 | Orthogonal systems that can be used along with SBOMit: 209 | 210 | * A software supply chain tool which attests to the quality of steps, such as FRSCA and SLSA. This helps with knowing that an individual action is actually a good security practice, could judge the quality of implementation for different tools, determine if the code base metrics are indicative of quality, understand if the license is appropriate, etc. This helps to address OSS-RISK-4, OSS-RISK-8, and OSS-RISK-10. OSS-RISK-7 may also be addressed either by this or by end user diligence. 211 | * Some means like Sigstore's root of trust is needed to handle how users know the correct name / root of trust for the software they are installing. This relates to OSS-RISK-3. 212 | * Recursing into components like the packages inside of a container image when the build process does not otherwise do so. This relates to OSS-RISK-6. As both tooling and in-toto adoption increase, this issue should naturally be addressed as more metadata becomes available. 213 | 214 | There is also a more detailed analysis that shows why these properties hold. 215 | 216 | ### 2.3 SBOMit components 217 | 218 | An implementation of SBOMit is composed of four primary components: 219 | 220 | 1. In-toto Layout Management Tool: Dictates the supply chain policy, including details about keys for each SIT and the SIT generation process. It is signed with a trusted layout key. 221 | 2. In-toto Metadata Collection Tool: Manages a range of in-toto metadata like sub-layouts, link metadata, and attestations, which are validated and signed by the appropriate parties. 222 | 3. SBOM Mutation Tool: Creates metadata for mutating the derived SBOM information to enhance its completeness. The metadata is in ISO or JSON patch format. 223 | 4. Addendum Handling Tool: Handles addendums or modifications, represented as diffs to the previous document sections, preserving historical information. Also uses JSON patch format. 224 | 225 | ### 2.4 System Workflow Example 226 | 227 | ![System Workflow Example](images/image1.png) 228 | 229 | #### **2.4.1 Actual Implementation:** 230 | 231 | Step 1: To make an easier adoption path for existing software, the first (optional) step is to generate a candidate layout. To do this, we would utilize a scanning tool like [SBOM X-ray](https://sched.co/182GT) to generate a candidate SBOM or an in-toto layout by inspecting a provided software package or binary. However, we wouldn't fully populate the in-toto layout with functionary keys or detailed verification for link metadata for two reasons. Firstly, we lack accurate knowledge of the materials and products passed between links as we haven't witnessed the earlier parts of the software supply chain in sufficient detail. Secondly, it's better to have keys generated on systems performing the software supply chain steps, so the public keys of the functionaries can't be included in the in-toto layout at this stage. 232 | 233 | Step 2: Each step of software creation would be executed with a wrapper script. A registry like [Testify’s Archivist](http://github.com/testifysec/archivist) or could be used for data tracking, or the data could be manually copied alongside the software artifact being built. The wrapper script would operate similarly to 'in-toto run,' possibly with an option to generate functionary keys. The script should perform the following for each supply chain step it executes: 234 | 235 | * Capture link metadata for the performed step. Integration of this action in scripts and CI/CD systems is encouraged for consistent performance. 236 | * Optionally capture environmental information, installed packages, etc. One option is to use runtime trace attestations to gather this information. Again, this could be integrated into scripts for consistent performance. 237 | * Stitch links into the layout as it runs, adding supplemental information into the SBOM areas. This includes matching materials and products from other link steps. 238 | * Periodically run 'in-toto verify' over the partial Verifiable SBOM to provide immediate feedback to developers, enabling prompt resolution of missing steps and issues. Developers can resolve issues in several ways: 239 | 1. They can indicate how a step, corresponding to a link, fits into the layout if an error was made by the tooling. 240 | 2. If the scanning tool missed a step, they can add a link for that step and update the layout accordingly. 241 | 3. If an expected step in the layout isn't present in the actual project, they can remove it. 242 | 4. If there's an unexpected or unwanted step in the supply chain, they can modify the project to remove it. Missing steps and information are highlighted, ideally using a visualization tool like [GUAC](https://security.googleblog.com/2022/10/announcing-guac-great-pairing-with-slsa.html), which offers a comprehensive view of the process and mitigates [https://github.com/in-toto/docs/security/advisories/GHSA-p86f-xmg6-9q4x](https://github.com/in-toto/docs/security/advisories/GHSA-p86f-xmg6-9q4x) 243 | * Depending on the developer or organization's needs, the wrapper could have multiple modes: fail-safe (halting the build if any step is invalid), Notify (providing real-time notifications), and Log (providing a summary of actions after the artifact is packaged). 244 | 245 | Step 3: Set up 'in-toto-verify' to run on the layout and only proceed with the release if it passes. Distribute the link metadata and Verifiable SBOM to end users, potentially via a registry. The method to refer to link metadata and other Verifiable SBOMs can be either via hashed references to an attestation or a bundled file containing everything. 246 | 247 | Stable State: In-toto verification will run every time a release is performed. This provides strong guarantees and should be essentially automatic. If steps change, the Verifiable SBOM’s in-toto layout will need modifications, and Step 2 may need to be performed for the new functionary. The Verifiable SBOM can be exported into various SBOM formats, including SPDX, CycloneDX, etc. Any information required for these that aren't needed for an in-toto layout (and thus not used for verification) can be modified independently in the Verifiable SBOM, and the document may be re-signed for authenticity and integrity verification. 248 | 249 | #### **2.4.2 Use Case Scenarios:** 250 | 251 | 1. Large financial corporations and major defense contractors are examples of entities that receive Software Bills of Materials (SBOMs) in the cycloneDX format and require verification of the deliverable's integrity. 252 | 2. In the case of a prominent bank, they require validation of the supply chain security posture of an external build or SBOM generation environment against a specific policy. The attested information relevant to this process is then stored in an SBOMit document. 253 | 3. For major defense contractors, the use case involves the generation of signed SBOMs (cycloneDX) of deliverables across disconnected environments. These SBOMs are subsequently inspected by Security Officers. 254 | 4. In the context of big financial institutions, there's a need to validate the supply chain security posture of an external source in a codified manner. This extra data helps determine whether to trust the external source or SBOM. This could potentially be achieved by examining and attesting to the security posture of the Software Development Life Cycle (SDLC) or tooling used to build the software and SBOM. This attested information would then be referenced in the SBOMit document." 255 | 256 | ## 3 The Final Product 257 | 258 | The final product is the bundle of a series of in-toto attestations, a complete (standard) in-toto layout, and any additional supplemental information that may be required. 259 | 260 | ### 3.1 Contents 261 | 262 | #### 3.1.1 in-toto attestations 263 | 264 | Primarily, the bundle encompasses a sequence of in-toto attestations, each of which is generated throughout the creation of the described software. These attestations provide a granular view into different stages of the software supply chain, which could include elements such as version control system, build process, unit testing, dependencies, fuzzing, license compliance checks, and packaging among others. For instance, an in-toto attestation for the build system used to compile the software in the SBOM might comprise the names and secure hashes of files sourced from the VCS for compilation, the names and secure hashes of files generated during the compilation process, comprehensive data about the compiler, and a signature endorsed by the compiler's private key. 265 | 266 | #### 3.1.2 in-toto layout 267 | 268 | Working in tandem with these attestations is the in-toto layout, another key component in the SBOMit document. Authenticated by the project owner's signature, the layout provides a blueprint of what constitutes valid attestation metadata for the project. It stipulates the private keys for entities performing the attestations and elucidates the interconnections between different steps. This means it could specify, for example, that a signed git tag from the VCS should be the basis for the build system's operation, and that the files compiled by this system should be the same ones subjected to unit tests, all of which must be passed. Crucially, an in-toto layout translates to a machine-readable policy capable of validating in-toto attestations, thereby ensuring every stipulated step was executed in the right sequence, on the correct items, and without any steps being skipped, added, or omitted. 269 | 270 | #### 3.1.3 Additional supplemental information 271 | 272 | Finally, the SBOMit document includes supplemental SBOM information. Together with the in-toto attestations and layout, this information can be utilized to generate a final SBOM in a variety of formats. The supplemental SBOM data might encompass details such as the company name and other specifics that aren't incorporated in-toto but are nonetheless relevant for inclusion in the resultant SBOM. Thus, an SBOM derived from an SBOMit document can feature supplementary data that wasn't part of the in-toto procedure. 273 | 274 | ## 4 Document Formats/Required Fields 275 | 276 | ### 4.1 SBOMit Document 277 | 278 | #### 4.1.1 Overview 279 | 280 | There are four items in a SBOMit document: 281 | 282 | * An in-toto layout. This specifies the policy that the supply chain followed. This includes information about the key used to sign each SIT and corresponding the SIT generation process for each. It must be signed by the layout key trusted for the SBOMit document. 283 | * A collection of in-toto metadata. This includes sub-layouts, link metadata, and attestations. This must validate according to the in-toto layout and so must be signed by the appropriate functionaries and sub-layout creators. 284 | * The SBOM mutation. This metadata describes how to mutate the SBOM information derived from the in-toto metadata. It essentially serves to flesh out the derived SBOM to make it more complete that what can be strictly verified. This is in ISO or JSON patch format. 285 | * Zero or more addendums. These are represented as diffs to the prior sections of the document. It enables one to easily append or modify information while retaining historical information. These are also in JSON patch format. 286 | 287 | #### 4.1.2 Detailed format 288 | 289 | ![Detailed format](images/image2.png) 290 | 291 | ### 4.2 SIT 292 | 293 | #### 4.2.1 Overview 294 | 295 | A SIT is a valid SBOM (of any type), with the following two constraints: 296 | 297 | * it has a field indicating the SBOMit document that it was derived from. 298 | * it is signed by the functionary key listed in the related step of the in-toto layout 299 | 300 | #### 4.2.2 Detailed format 301 | 302 | TODO… 303 | 304 | ## 5 Detailed Workflows 305 | 306 | There are two main workflows for SBOMit documents and SITs: generation and verification. 307 | 308 | ### 5.1 Generation 309 | 310 | #### 5.1.1 SBOMit document 311 | 312 | To generate a SBOMit document, one must generate the constituent parts. For the in-toto layouts, sub-layouts, attestations, and links, this process is described in the in-toto project's documentation. Note, however, that for the purposes of SBOMit, the layout is required to include certain information such as, … so that this information may be used to populate the SIT. 313 | 314 | Generating the mutator by hand may be done by starting with a null mutator and then using tooling to generate a SIT in the correct format. The SIT file may be modified and the JSON diff may be computed. 315 | 316 | Similarly, if a SBOMit document is modified, one may elect to add an addendum to modify it instead of generating a fresh document. This is easily done by generating the new SBOMit document and then creating a JSON diff. 317 | 318 | #### 5.1.2 SIT 319 | 320 | The SIT is generated by first deriving common information from in-toto and placing it in an intermediate format called X. This format is effectively an SBOM itself which matches the NTIA format. 321 | 322 | Then the tool specified in the layout may be used to derive the SIT in the appropriate end format. Note also, that multiple SITs may be generated from the same SBOMit document. So, for example, one SBOMit document could generate both a SPDX SIT and a CycloneDX SIT. 323 | 324 | An important part of generating the SIT is applying the mutator to the output of the tool used to derive the SIT. This adds or modifies information in the resulting SIT as instructed. This works as though applying a JSON patch to the SIT document. 325 | 326 | It is recommended that the SIT generation tool provides a warning if the mutator modifies (e.g., replaces or removes) portions of the SIT derived from the in-toto information. This is because this will be flagged as a security risk when verification of the SBOMit document is performed. 327 | 328 | ### 5.2 Verification 329 | 330 | #### 5.2.1 SBOMit document 331 | 332 | SBOMit document verification proceeds by the following steps: 333 | 334 | * verifying the in-toto layout over the provided in-toto metadata. 335 | * checking each SIT to ensure they are signed by the correct SIT generator 336 | * generate each SIT using the relevant tooling to examine the mutator behavior. Any parts of the SIT that the mutator has chosen to overwrite or remove represent a substantial security risk. These are specifically flagged during validation. The user must specify a flag like --insecure-allow-in-toto-override or respond to a similarly scary alert to install the software. 337 | 338 | If this matches the generated SITs, then the SBOMit document verification has succeeded. 339 | 340 | #### 5.2.2 SIT 341 | 342 | A SIT may be verified in two ways. 343 | 344 | First, the SBOMit document may be downloaded and then verified. This provides strong security guarantees but is a fairly heavyweight operation. 345 | 346 | Second, the SIT may have its signature checked, much like any signed SBOM. This provides a much weaker set of security guarantees. However, assuming the SIT generator performs verification correctly and is uncompromised, this does provide a meaningful level of security. 347 | 348 | ## 6 Learn More 349 | 350 | This document presents SBOMit, a project that oversees the SBOMit specification format. A SBOMit document is essentially an enhanced SBOM, enriched with additional verification data. This data, collected in real time during the execution of the software supply chain, utilizes in-toto attestations and layouts to offer users a high degree of assurance about the software's integrity. The primary goal is to empower end users to effortlessly generate SBOMs that offer cryptographic validation of the actions performed in the software supply chain. We extend a warm invitation to all parties interested in SBOMit. 351 | 352 | We invite all interested parties to evaluate our reference implementation, explore our examples, or delve into the extensive information about SBOMit available on our platform. 353 | --------------------------------------------------------------------------------