diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..0a9e669 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +node_modules/ +public/ +resources/ +.hugo_build.lock +package-lock.json diff --git a/config.yml b/config.yml index 382ca41..0567397 100644 --- a/config.yml +++ b/config.yml @@ -12,13 +12,13 @@ buildExpired: false minify: disableXML: true - minifyOutput: true + minifyOutput: false params: env: production # to enable google analytics, opengraph, twitter-cards and schema. title: SBOMit - description: "Software Bill of Materials on in-toto" - keywords: ["Software Bill of Materials", "in-toto", "attestation"] + description: "SBOMit enriches SBOMs with build-time attestations from Witness (in-toto), producing accurate, verifiable, tamper-evident software component inventories." + keywords: ["Software Bill of Materials", "SBOM", "in-toto", "attestation", "supply chain security", "Witness", "SPDX", "CycloneDX"] author: "SBOMit Maintainers" ## images: [""] DateFormat: "January 2, 2006" @@ -57,27 +57,17 @@ params: # home-info mode homeInfoParams: - Title: "Software Bill of Materials on in-toto (SBOMit)" - Content: | - The SBOMit specification is a SBOM format independent method for attesting components with - additional verification information. These attestation are 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. - - Links: | - - [Specification](https://github.com/SBOMit/specification) - - [About](/about) - + Title: "SBOMit — Treat SBOMs as part of your defense, not a checkbox" Additional: | - ## Meetings - - - Schedule: every other Wednesday (biweekly) at 12pm US Eastern time at [this Zoom meeting](https://nyu.zoom.us/j/91097299041) - - [Notes](https://docs.google.com/document/d/1-nHXMqvWNzgOxAq08O8Wu2BTHz0U60yBoAklrJAMaRc/edit?usp=sharing) + ### Community & Meetings + + - **Meetings**: Wednesdays at 11 AM EST — [Zoom link](https://zoom-lfx.platform.linuxfoundation.org/meeting/94671938246?password=035ca9e9-5194-491c-863b-69b21a596c67) + - **Meeting notes**: [Google Docs](https://docs.google.com/document/d/1-nHXMqvWNzgOxAq08O8Wu2BTHz0U60yBoAklrJAMaRc/edit?usp=sharing) + - **Slack**: [#sbomit on OpenSSF Slack](https://openssf.slack.com/channels/sbomit) socialIcons: - name: github - url: "https://github.com/SBOMit/specification" + url: "https://github.com/SBOMit/sbomit" analytics: google: @@ -105,14 +95,26 @@ params: keys: ["title", "permalink", "summary", "content"] menu: main: + - identifier: getting-started + name: Getting Started + url: /getting-started/ + weight: 5 + - identifier: tool + name: Tool + url: https://github.com/SBOMit/sbomit + weight: 10 + - identifier: witness + name: Witness + url: https://github.com/in-toto/witness + weight: 15 - identifier: specification name: Specification url: https://github.com/SBOMit/specification - weight: 10 - - identifier: about - name: About - url: /about/ weight: 20 + - identifier: faq + name: FAQ + url: /faq/ + weight: 30 # Read: https://github.com/adityatelange/hugo-PaperMod/wiki/FAQs#using-hugos-syntax-highlighter-chroma pygmentsUseClasses: true markup: diff --git a/content/_index.md b/content/_index.md new file mode 100644 index 0000000..85fa4ab --- /dev/null +++ b/content/_index.md @@ -0,0 +1,60 @@ +--- +title: "SBOMit" +--- + +When [Log4Shell (CVE-2021-44228)](https://nvd.nist.gov/vuln/detail/CVE-2021-44228) hit in December 2021, the number of exposed systems exploded from 40,000 to 830,000 in under 72 hours. +Log4j was buried as a transitive dependency, and most teams couldn't answer a simple question: *are we affected?* + +SBOMs were proposed as the solution, a machine-readable inventory of every component in a software artifact, enabling automated vulnerability scanning and rapid impact assessment. +And they are the right answer. + +But the current state of SBOM generation falls short of that potential. This isn't a failure of SBOM tools, they work as designed. +The limitation is the **metadata they have access to**. Most SBOMs are generated either from manifest files before the build, or by scanning the artifact after. +In both cases, the tool is working with an incomplete and often inaccurate snapshot of what's actually inside the software. ([Read more in the FAQ →](/faq)) + +--- + +## What is SBOMit? + +SBOMit addresses this by moving SBOM generation closer to the build. +It integrates with [Witness](https://github.com/in-toto/witness), a supply chain attestation framework built on [in-toto](https://in-toto.io/) to instrument each build step and record cryptographically signed attestations capturing exactly what ran, what files were accessed, what packages were downloaded, and what network calls were made. + +SBOMit is not itself a replacement for SBOM tools. +The goal is for existing tools to consume Witness attestations as an input source and use SBOMit's resolvers to produce a more complete, accurate SBOM. +SBOMit provides the attestation processing layer and **the enrichment** that SBOM tools currently lack access to. + +**When your SBOM is complete and accurate, it becomes a real security asset** not just a compliance checkbox. You can answer "are we affected?" in minutes. You can verify that nothing unexpected happened during the build. You can treat your SBOM as an integral part of your defense. + +--- + +## SBOMit vs. Current SBOM Generation + +A traditional SCA scanner isn't doing anything wrong, it simply doesn't have access to the +right data. SBOMit with Witness gives it that data. + +| | Current SBOM Generation | With SBOMit | +|---|---|---| +| **When generated** | Before build (manifests) or after (scanning) | During the build | +| **Package versions** | From lockfile(often stale or wrong) | Exact versions installed at build time | +| **Native / unmanaged files** | Missed | Captured via file-access tracing | +| **False positives** | Common(packages listed but not installed) | Removed(only what was actually used) | +| **False negatives** | Common(transitive deps, `.so` files missed) | Resolved(everything observed is reported) | +| **Cryptographic proof** | None | Signed in-toto attestations at every step | +| **Tamper resistance** | Easily forged post-hoc | Tamper-evident chain of custody | + +--- + +*Ready to try it? See the [Getting Started guide →](/getting-started)* + +*For a deeper dive into the research and how attestations work, see the [FAQ →](/faq)* + +--- + +## Project Status + +SBOMit is an early-stage but functional open source project under the +[Linux Foundation / OpenSSF](https://openssf.org/) umbrella, governed by a +[Technical Steering Committee](/CHARTER). + +- [SBOMit/sbomit](https://github.com/SBOMit/sbomit) — the enrichment tool +- [in-toto/witness](https://github.com/in-toto/witness) — the attestation framework diff --git a/content/about.md b/content/about.md index a82b121..5326b3e 100644 --- a/content/about.md +++ b/content/about.md @@ -1,57 +1,188 @@ --- author: "SBOMit Maintainers" -title: "About" -ShowToc: false +title: "About SBOMit" +ShowToc: true +TocOpen: false --- ## What is SBOMit? -SBOMit is the name of the project which manages the SBOMit specification format. An 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, can be validated by a party to get a high degree of assurances about the software. +SBOMit is an open source tool that generates **Enriched SBOMs** by combining standard SBOM tooling +with build-time attestations captured by [Witness](https://github.com/in-toto/witness), a supply chain +security framework built on the [in-toto](https://in-toto.io/) specification. -## What does a SBOMit document contain and why? +Where traditional SBOM tools scan software after the fact and guess at its composition, SBOMit +**observes the build as it happens** — recording exactly what was downloaded, compiled, and linked — +then uses that data to produce a complete, verifiable software component inventory. -A SBOMit document is a signed document that consists of a few different components. +--- + +## The Problem: SBOMs Are Incomplete by Design + +Most SBOMs are generated either before the build (from manifest/lockfiles) or after (by scanning the +output artifact). Both approaches have fundamental blind spots: + +**Generated from manifests:** +- Lockfiles are often stale and don't reflect what was actually installed +- Version pinning in manifests may not match what the package resolver chose +- Transitive dependencies may be missing or wrong -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. +**Generated by post-build scanning:** +- Scanning tools use heuristics to infer what happened — they are imperfect by design +- Native libraries and dynamically loaded files (`.so`, `.dylib`) are frequently missed +- Files unknown to the package manager are invisible to scanners +- Different scanners give wildly different results for the same artifact -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. +**Both approaches share a deeper problem:** SBOMs generated outside the build process can be +forged or tampered with after the fact, and they carry no cryptographic proof of how the software +was actually produced. -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. +### Research: Dark Matter in Docker Hub Images -There is also a means to add addendums to an SBOMit document, which will be described later. +We analyzed the top 1,000 Debian-based images on Docker Hub. A significant percentage of files in +many of those images are not attributable to any package manager — what we call **"dark matter" +files**. Some images had 40–100% of their files unaccounted for. -## What are the advantages of a SBOMit document over using a SBOM generation tool that scans the software? +{{< figure src="/images/dark-matter-dockerhub.png" alt="Distribution of dark matter files across top 1,000 Docker Hub images" caption="Distribution of unexplained (dark matter) files across top 1,000 Debian-based Docker Hub images." >}} -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. +This research surfaced real CVEs: -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. +- **CVE-2025-32754** (`jenkins/ssh-agent`) — SSH keys are generated at image build time, so all + containers derived from the image share the same keys. An attacker can connect to a build + container, read the build secret, and leave without a trace. +- **CVE-2025-32111** (`acme.sh`) — a build secret was leaked during the build process. An attacker + with this secret could replace a popular Let's Encrypt client and perform man-in-the-middle + attacks on a large portion of internet traffic. + +Traditional SBOM tools miss these because the files and their origins are invisible at scan time. +SBOMit captures them during the build, where they are observable. + +--- -## What are the advantages of a SBOMit document over simply signing an SBOM? +## How SBOMit Works -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. +SBOMit is built on two components: -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. +### 1. Witness — Build-Time Attestation -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. +[Witness](https://github.com/in-toto/witness) wraps your build process and instruments each step, +recording cryptographic attestations that answer: -For more information on this topic, please see the [What advantages does in-toto provide](https://in-toto.io/in-toto/) on the in-toto website. +- **Who** ran the step: process names, commands, environment +- **What** was accessed: every file read and written, packages downloaded, network calls made +- **How** inputs became outputs: SHA-256 hashes of all artifacts at each stage -## What if a software supply chain contains insecure steps? +Each build step produces a signed attestation collection in the +[in-toto ITE-6](https://github.com/in-toto/ITE/blob/master/ITE/6/README.adoc) format, +covering attestation types including: -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. +| Attestation | Captures | +|---|---| +| `material` | Input files and their hashes | +| `command-run` | Commands executed, stdout/stderr, opened files, network calls | +| `product` | Output files and their hashes | +| `environment` | OS, runtime, tool versions | +| `network-trace` | All network connections (src/dst, protocol) | -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. +### 2. SBOMit — Enriched SBOM Generation + +The `sbomit` tool reads Witness attestation files and: + +1. Parses all attestation types to build a complete picture of the build +2. Runs **language-specific package resolvers** to map file paths back to package names and versions +3. Filters cache artifacts and de-duplicates package references +4. Emits a standard SBOM enriched with accurate, build-observed data + +**Install and run:** + +```bash +go install github.com/sbomit/sbomit@latest +sbomit generate [flags] +``` + +--- -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. +## What Enriched SBOMs Provide + +Compared to a traditional SBOM generated by a tool like Syft alone: + +| Capability | Syft (scan only) | SBOMit (Witness + Syft) | +|---|---|---| +| Observe the build | ✗ | ✓ | +| Record attestations | ✗ | ✓ | +| Accurate package versions | Partial | ✓ — exact install-time versions | +| Native / unmanaged files | ✗ | ✓ — captured via file tracing | +| Network call provenance | ✗ | ✓ — detects dependency confusion | +| Cryptographic provenance | ✗ | ✓ — signed in-toto attestations | +| Generate inventory | ✓ | ✓ | +| Result | Incomplete | Complete | + +### Key benefits + +- **Accurate versions** — captures what the package resolver actually installed, not what the + lockfile says. Stale lockfiles are a common source of false positives and false negatives in + vulnerability scanning. Example: a lockfile may pin `urllib3==1.54.0` but the resolver installs + `1.57.0` — SBOMit reports what was actually installed. +- **File-to-package mapping** — works across package managers, making SBOMit package-manager + agnostic. You don't need to maintain individualized SBOM pipelines for Android, Python, internal + packages, etc. +- **Native library detection** — catches `.so` / `.dylib` files loaded at build time that scanners + miss. For C/C++ projects where libraries may be vendored forks of forks, having file hashes makes + it possible to detect if you are using a malicious version of e.g. `libssl`. +- **Network provenance** — records outbound connections during the build (src, dst, protocol). + Helps detect dependency confusion attacks and unauthorized package registries. Also provides + context behind each action taken during the build. +- **Removes false positives** — if a package appears in a lockfile but is not actually installed + or used during the build, SBOMit will not report it. +- **Adds false negatives** — packages resolved at build time that are absent from the lockfile + (transitive dependencies, dynamically pulled libraries) are captured and reported. +- **Tamper-evident** — all attestations are cryptographically signed; the chain of custody is + verifiable from source to SBOM. +- **Zero Trust alignment** — supports SLSA principles and can be integrated into policy enforcement + pipelines. -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. +--- + +## Supported Languages and Output Formats + +**Language-specific resolvers:** +- Python (pip) +- Go (modules) +- Rust (cargo) +- JavaScript / pnpm + +**SBOM output formats:** +- SPDX 2.2 and 2.3 +- CycloneDX 1.4 and 1.5 + +--- + +## Relationship to in-toto and Witness + +SBOMit sits at the intersection of two established standards: + +- **[in-toto](https://in-toto.io/)** — a framework for securing the software supply chain through + signed attestations and verifiable policies (CNCF project) +- **[Witness](https://github.com/in-toto/witness)** — an in-toto implementation that instruments + builds and produces ITE-6 attestations; donated to the CNCF in-toto ecosystem by TestifySec + +SBOMit does not replace these — it consumes their output to generate compliance-ready SBOMs. + +--- -## 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 +## Project Status and Contributing -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. +SBOMit is an early-stage but functional open source project under the +[Linux Foundation / OpenSSF](https://openssf.org/) umbrella, governed by a +[Technical Steering Committee](/CHARTER). -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. +**Repositories:** +- [SBOMit/sbomit](https://github.com/SBOMit/sbomit) — the enrichment tool +- [in-toto/witness](https://github.com/in-toto/witness) — the attestation framework -## Can I derive an SBOM from an SBOMit document? +Contributions, language resolver additions, and SBOM tool integrations are welcome. +See the open issues for areas where help is most needed, including: -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. \ No newline at end of file +- Additional language/build tooling resolvers +- Guidance from the SBOM specification community on standardizing attestation-backed SBOMs +- Integration with SBOM tools to natively consume attestations diff --git a/content/faq.md b/content/faq.md new file mode 100644 index 0000000..3c04e12 --- /dev/null +++ b/content/faq.md @@ -0,0 +1,123 @@ +--- +author: "SBOMit Maintainers" +title: "FAQ" +ShowToc: true +TocOpen: false +--- + +## Why do we need Accurate SBOMs? + +When [Log4Shell (CVE-2021-44228)](https://nvd.nist.gov/vuln/detail/CVE-2021-44228) hit in December +2021, the number of exposed systems exploded from 40,000 to 830,000 in under 72 hours. Log4j was +buried as a transitive dependency, and most teams had no way to know whether they were running it and where. Incident response turned into an organization-wide mining project. + +{{< figure src="/images/log4shell-growth.png" alt="Log4Shell affected systems grew from 40,000 to 830,000 in 72 hours" caption="Affected systems in the 72 hours following the Log4Shell outbreak." >}} + +Log4Shell made the case for SBOMs clearly: if you had a complete, accurate inventory of every +component in your software, you could answer "are we affected?" in minutes. Since then, SBOMs have +been mandated by executive orders, procurement requirements, and industry frameworks. +The question now is whether the SBOMs being generated are accurate enough to actually use and +for most organizations today, they are not. When the next Log4Shell hits, will your SBOM answer the question and do you trust it? + +--- + +## What can't your package manager/manifest see? + +More than you'd expect. We analyzed the top 1,000 Debian-based images on Docker Hub and found that +a significant percentage of files in many images(sometimes 40–100%) cannot be attributed to any +package manager at all. + +{{< figure src="/images/dark-matter-dockerhub.png" alt="Distribution of untracked files across top 1,000 Docker Hub images" caption="Distribution of files unaccounted for by the package manager across the top 1,000 Debian-based Docker Hub images." >}} + +These are real files, loaded at runtime, potentially vulnerable and invisible to any SBOM tool +that relies on package manager metadata. Our research found exploitable CVEs among them: + +- **CVE-2025-32754** (`jenkins/ssh-agent`) — SSH keys are generated at image build time, so every + container derived from the image shares the same keys. An attacker can connect to a build + container, read the build secret, and leave without a trace. +- **CVE-2025-32111** (`acme.sh`) — a build secret was leaked during the build process. An attacker + with this secret could replace a widely-used Let's Encrypt client and perform man-in-the-middle + attacks on a significant portion of internet traffic. + +A scanner running against the final image would not see these. SBOMit captures them because +Witness observes the build as it happens. + +--- + +## What are in-toto, Witness, and attestations? + +**[in-toto](https://in-toto.io/)** is a CNCF framework for securing software supply chains. It +defines a standard for recording and verifying the steps that produce software like who performed +each step, what files they operated on, and what the outputs were. Each step is recorded as a +signed tamper-evident statement about what happened, signed by the party that performed it. + +**[Witness](https://github.com/in-toto/witness)** is an in-toto implementation that instruments +your build pipeline to produce these attestations automatically. You wrap your build command with +`witness run` and it records a signed attestation collection for that step. +Witness was created by TestifySec and donated to the CNCF in-toto ecosystem. + +**Attestations** are the core primitive. Each one is a signed record of a build step, containing: + +| Attestation | Captures | +|---|---| +| `material` | Input files and their hashes (what went in) | +| `command-run` | Commands run, files opened, processes spawned | +| `product` | Output files and their hashes (what came out) | +| `environment` | OS, runtime, tool versions | +| `network-trace` | All outbound network connections during the step | + +Because every attestation is signed at the time the step runs, the build history is +cryptographically verifiable. + +For more information on this topic, please see [What advantages does in-toto provide](https://in-toto.io/in-toto/) on the in-toto website. + +--- + +## How does SBOMit work? + +The `sbomit` tool reads a Witness attestation file and: + +1. Parses all attestation types to build a complete picture of what happened during the build +2. Runs **language-specific package resolvers** (Python, Go, Rust, JavaScript/pnpm) to map + observed file paths back to package names and exact versions +3. Filters out temporary/cache artifacts and deduplicates package references +4. Emits a standard **SPDX** (2.2/2.3) or **CycloneDX** (1.4/1.5) SBOM enriched with + build-observed data + +The result is an SBOM that reflects what was actually installed and used including accurate versions, native libraries, and files invisible to package managers. See the [Getting Started guide](/getting-started) for installation and usage. + +--- + +## What if my supply chain has insecure steps? + +Attestations are not a substitute for having secure build processes but are a record of what +happened, not a guarantee that what happened was safe. If your build curls a script from the +internet and executes it, Witness will faithfully attest that this occurred. + +What attestations give you is **visibility and accountability**. The `network-trace` attestation +will show that unexpected outbound connection. The `command-run` attestation will record the +process that made it. Nothing can be hidden after the fact, because the attestations are signed at +build time. + +For teams that want to enforce policies on top of this like mandating that builds only pull from +approved registries, that certain steps are always signed by specific keys, or that no unexpected +processes ran, [Witness policy verification](https://github.com/in-toto/witness/blob/main/docs/concepts/policy.md) +and frameworks like [SLSA](https://slsa.dev/) build opinionated security rules on top of in-toto +attestations. SBOMit can be used alongside SLSA compliance scoring to give a +complete picture of both what is in the software and how it was produced. + +--- + +## What's the difference between signing an SBOM and using SBOMit? + +Signing an SBOM provides **integrity** giving guarantee that you know the document hasn't been tampered with since it +was signed. The content may have been wrong or incomplete to +begin with, and you are trusting a single party's assertion about the software at a single point in +time. If the signing key is compromised, or if the signer made errors, the signed SBOM is +worthless. + +With SBOMit and Witness, each attestation is signed **at the time the build step runs**, by the +process performing it. You are not trusting one party's after-the-fact assertion, instead you have +independent, cryptographic evidence from every step of the supply chain. Accidental inaccuracies +(a step that was skipped, a dependency that was quietly swapped) are detectable because they break +the attestation chain. Deliberate tampering is significantly harder to hide. diff --git a/content/getting-started.md b/content/getting-started.md new file mode 100644 index 0000000..61a8483 --- /dev/null +++ b/content/getting-started.md @@ -0,0 +1,201 @@ +--- +author: "SBOMit Maintainers" +title: "Getting Started" +ShowToc: true +TocOpen: true +--- + +This guide walks through setting up [Witness](https://github.com/in-toto/witness) to instrument +your build, then using SBOMit to generate an enriched SBOM from the resulting attestation. + +--- + +## Prerequisites + +- [Go](https://go.dev/doc/install) 1.19 or later +- [openssl](https://www.openssl.org/) +- [jq](https://jqlang.github.io/jq/) +- [base64](https://www.gnu.org/software/coreutils/manual/html_node/base64-invocation.html) (part of GNU coreutils) + +--- + +## Part 1: Witness + +Witness wraps your build process and records signed attestations, a cryptographic audit trail. + +### 1. Install Witness + +```bash +bash <(curl -s https://raw.githubusercontent.com/in-toto/witness/main/install-witness.sh) +``` + +Or download a binary from the [Witness releases page](https://github.com/in-toto/witness/releases). + +### 2. Create a signing keypair + +Witness signs each attestation with a private key. For a quick local test: + +```bash +openssl genpkey -algorithm ed25519 -outform PEM -out testkey.pem +openssl pkey -in testkey.pem -pubout > testpub.pem +``` + +> **Tip:** Witness also supports keyless signing via [SPIRE/SPIFFE](https://spiffe.io/) and +> [Sigstore Fulcio](https://github.com/sigstore/fulcio) for CI/CD environments. + +### 3. Configure Witness + +Create a `.witness.yaml` in your project root. This file is typically committed alongside your +public key: + +```yaml +# .witness.yaml +run: + signer-file-key-path: testkey.pem + trace: false +verify: + attestations: + - "attestation.json" + policy: policy-signed.json + publickey: testpub.pem +``` + +Command-line flags override config file values. Run `witness help` to see all options. + +### 4. Wrap your build + +Prefix your build command with `witness run` to produce an attestation file: + +```bash +witness run --step build -o attestation.json -- +``` + +**Go project:** + +```bash +witness run --step build -o attestation.json -- go build -o myapp . +``` + +**Python project:** + +```bash +witness run --step build -o attestation.json -- pip install -r requirements.txt +``` + +Witness always runs a base set of +attestors — see `witness attestors list` for the full list. + +> **Tip:** For builds that produce many files (e.g. `node_modules`), use +> `--dirhash-glob node_modules/*` to hash the directory contents rather than every individual file. + +### 5. Inspect the attestation + +The attestation file is a signed [DSSE envelope](https://github.com/secure-systems-lab/dsse). +To view the payload: + +```bash +cat attestation.json | jq -r .payload | base64 -d | jq +``` + +You will see an attestation collection containing typed attestations: `material`, `command-run`, +`product`, `environment`, and optionally `network-trace`. This is the data SBOMit uses. + + + +--- + +## Part 2: SBOMit + +With an attestation file in hand, SBOMit generates an enriched SBOM by running language-specific +package resolvers over the build data Witness observed. + +### 1. Install SBOMit + +```bash +go install github.com/sbomit/sbomit@latest +``` + +### 2. Generate an enriched SBOM + +```bash +# SPDX 2.3 (default) +sbomit generate attestation.json + +# SPDX 2.2 +sbomit generate attestation.json -f spdx22 + +# CycloneDX 1.5 +sbomit generate attestation.json -f cdx15 + +# CycloneDX 1.4 +sbomit generate attestation.json -f cdx14 +``` + +### 3. (Optional) --catalog to Capture Dependency Tree + +SBOMit can call Syft as an additional catalog source, merging its output with the attestation-derived +data: + +```bash +sbomit generate attestation.json --catalog syft --project-dir /path/to/project +``` + +SBOMit(right now) produces a **flat list** of dependencies, it knows what was installed and used, but does not reconstruct the full dependency tree. +Syft, for ecosystems where it can resolve the +tree structure (e.g. Go modules, npm), preserves that parent-child relationship in its output. + +By passing `--catalog syft`, SBOMit uses Syft's dependency tree as the foundation and +then complements it with everything Syft cannot see: the actual versions installed at build time, +native libraries, files not tracked by any package manager, and network call provenance captured +by Witness. \ No newline at end of file diff --git a/layouts/_default/list.html b/layouts/_default/list.html new file mode 100644 index 0000000..d474a36 --- /dev/null +++ b/layouts/_default/list.html @@ -0,0 +1,112 @@ +{{- define "main" }} + +{{- if (and site.Params.profileMode.enabled .IsHome) }} +{{- partial "index_profile.html" . }} +{{- else }} {{/* if not profileMode */}} + +{{- if not .IsHome | and .Title }} +
+ {{- partial "breadcrumbs.html" . }} +

+ {{ .Title }} + {{- if and (or (eq .Kind `term`) (eq .Kind `section`)) (.Param "ShowRssButtonInSectionTermList") }} + + + + + + + + {{- end }} +

+ {{- if .Description }} +
+ {{ .Description | markdownify }} +
+ {{- end }} +
+{{- end }} + +{{- if and .Content (not .IsHome) }} +
+ {{- if not (.Param "disableAnchoredHeadings") }} + {{- partial "anchored_headings.html" .Content -}} + {{- else }}{{ .Content }}{{ end }} +
+{{- end }} + +{{- $pages := union .RegularPages .Sections }} + +{{- if .IsHome }} +{{- $pages = where site.RegularPages "Type" "in" site.Params.mainSections }} +{{- $pages = where $pages "Params.hiddenInHomeList" "!=" "true" }} +{{- end }} + +{{- $paginator := .Paginate $pages }} + +{{- if and .IsHome site.Params.homeInfoParams (eq $paginator.PageNumber 1) }} +{{- partial "home_info.html" . }} +{{- end }} + +{{- $term := .Data.Term }} +{{- range $index, $page := $paginator.Pages }} + +{{- $class := "post-entry" }} + +{{- $user_preferred := or site.Params.disableSpecial1stPost site.Params.homeInfoParams }} +{{- if (and $.IsHome (eq $paginator.PageNumber 1) (eq $index 0) (not $user_preferred)) }} +{{- $class = "first-entry" }} +{{- else if $term }} +{{- $class = "post-entry tag-entry" }} +{{- end }} + +
+ {{- $isHidden := (site.Params.cover.hidden | default site.Params.cover.hiddenInList) }} + {{- partial "cover.html" (dict "cxt" . "IsHome" true "isHidden" $isHidden) }} +
+

+ {{- .Title }} + {{- if .Draft }}  [draft]{{- end }} +

+
+ {{- if (ne (.Param "hideSummary") true) }} +
+

{{ .Summary | plainify | htmlUnescape }}{{ if .Truncated }}...{{ end }}

+
+ {{- end }} + {{- if not (.Param "hideMeta") }} +
+ {{- partial "post_meta.html" . -}} +
+ {{- end }} + +
+{{- end }} + +{{- if gt $paginator.TotalPages 1 }} + +{{- end }} + +{{- end }}{{/* end profileMode */}} + +{{- end }}{{- /* end main */ -}} diff --git a/layouts/partials/home_info.html b/layouts/partials/home_info.html index f02a380..3b39ce9 100644 --- a/layouts/partials/home_info.html +++ b/layouts/partials/home_info.html @@ -1,14 +1,21 @@ +{{- $page := . -}} {{- with site.Params.homeInfoParams }}

{{ .Title | markdownify }}

-
+
+ {{- if $page.Content }} + {{ $page.Content }} + {{- else }} {{ .Content | markdownify }} + {{- end }}
-
- {{ .Links | markdownify }} + {{- with .Additional }} +
+ {{ . | markdownify }}
+ {{- end }} diff --git a/static/images/dark-matter-dockerhub.png b/static/images/dark-matter-dockerhub.png new file mode 100644 index 0000000..d669c26 Binary files /dev/null and b/static/images/dark-matter-dockerhub.png differ diff --git a/static/images/log4shell-growth.png b/static/images/log4shell-growth.png new file mode 100644 index 0000000..112b78a Binary files /dev/null and b/static/images/log4shell-growth.png differ