-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[docs]: update main readme and refractor section to seperate docs
Signed-off-by: Vivek Kumar Sahu <[email protected]>
- Loading branch information
1 parent
4fc5c8f
commit d117ff8
Showing
3 changed files
with
113 additions
and
128 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -6,146 +6,76 @@ sbommv - Your primary tool to transfer SBOM's between different systems. | |
|
|
||
| sbommv is designed to allow transfer sboms across systems. The tool supports input, translation, enrichment & output adapters which allow it to be extensible in the future. Input adapters are responsbile to interface with services and provide various methods to extract sboms. The output adapters handles all the complexity related to uploading sboms. | ||
|
|
||
| **Examples** | ||
| ## 🔹 Why sbommv? The Motivation Behind Its Creation | ||
|
|
||
| 1. **Generate & Transfer SBOM's for all repositories in Github org of Interlynk to interlynk SBOM' platform**: | ||
| Generate & Transfer SBOM's from all repositories in the interlynk github organization using github apis, and transfer them to interlynk. If interlynk platform does not contain projects it will create them. | ||
| The **Interlynk platform** is a powerful **SBOM (Software Bill of Materials) compiler**, designed to: | ||
|
|
||
| ```bash | ||
| export GITHUB_TOKEN=ghp_klgJBxKukyaoWA****** | ||
| export INTERLYNK_SECURITY_TOKEN=lynk_api****** | ||
| sbommv transfer --input-adapter=github --in-github-url="https://github.com/interlynk-io" --output-adapter=interlynk --out-interlynk-url="http://localhost:3000/lynkapi" | ||
| ``` | ||
| ✅ **Analyze SBOMs** → Extract insights and understand software components | ||
| ✅ **Perform Compliance Checks** → Ensure SBOMs meet regulatory and security requirements | ||
| ✅ **Manage Vulnerabilities** → Identify risks and track security issues across SBOMs | ||
| ✅ **Enforce SBOM-related Policies** → Maintain consistency and governance over SBOMs | ||
|
|
||
| 2. **DRY RUN: Transfer SBOM from the latest version of sbomqs to interlynk platform**: | ||
| This will look for the latest release of the repository and check if SBOMs are generated, in dry-run mode, it will just iterate the sboms found, and check if login to the output adapter works. | ||
| To **leverage these capabilities**, the **Interlynk platform requires SBOMs** to be available for processing. However, the challenge lies in **how SBOMs are supplied to the platform**. In short remember Interlynk as a SBOM compiler. | ||
|
|
||
| ```bash | ||
| export GITHUB_TOKEN=ghp_klgJBxKukyaoWA****** | ||
| export INTERLYNK_SECURITY_TOKEN=lynk_api****** | ||
| sbommv transfer --input-adapter=github --in-github-url=https://github.com/interlynk-io/sbomqs --in-github-method="release" --output-adapter=interlynk --out-interlynk-url=https://api.interlynk.io/lynkapi --dry-run | ||
| ``` | ||
| ### 🚀 The Need for sbommv: Bridging the Gap in SBOM Management | ||
|
|
||
| There are **two main ways** to feed SBOMs into Interlynk: | ||
|
|
||
| ## Data Flow | ||
| ``` | ||
| +---------------------+ +------------------------------+ +----------------------+ | ||
| | Input Adapter | --> | Enrichment/Translation | --> | Output Adapter | | ||
| |-------------------- | |------------------------------| |----------------------| | ||
| | - GitHub | | - SBOM Translation* | | - Interlynk | | ||
| | - BitBucket* | | - Enrichment* | | - Dependency-Track* | | ||
| | - Dependency-Track*| +------------------------------+ | - Folder* | | ||
| | - Folder* | | | | ||
| +---------------------+ +-----------------------+ | ||
| * Coming Soon | ||
| ``` | ||
|
|
||
| ## Adapters | ||
|
|
||
|
|
||
| ### Input Adapters | ||
|
|
||
| #### GitHub | ||
|
|
||
| The **GitHub adapter** allows you to extract/download SBOMs from GitHub. The adapter provides the following methods of extracting SBOMs: | ||
|
|
||
| - **Release**: | ||
| This method looks at the releases for the repository and extracts all the SBOMs that follow the recognized file patterns as described by **CycloneDX** & **SPDX** specs. | ||
|
|
||
| - **API** *(Default)*: | ||
| This method uses the GitHub API to download **SPDX** SBOM for the repository, if available. | ||
|
|
||
| - **Tool**: | ||
| This method clones the repository and runs your tool of choice to generate the SBOM. | ||
|
|
||
| --- | ||
|
|
||
| **Command-line Parameters Supported by the Adapter** | ||
|
|
||
| - `--in-github-url`: Takes the repository or owner URL for GitHub. | ||
| - `--in-github-include-repos`: Specifies repositories from which SBOMs should be extracted. | ||
| - `--in-github-exclude-repos`: Specifies repositories to exclude from SBOM extraction. | ||
| - `--in-github-method`: Specifies the method of extraction (`release`, `api`, or `tool`). | ||
| #### Locally Available SBOMs | ||
|
|
||
| --- | ||
| For SBOMs **already present on your system**, you can: | ||
|
|
||
| **Usage Examples** | ||
| - **Manual Upload** → Directly upload an SBOM through the Interlynk web platform. | ||
| - **pylynk Integration** → Use the `pylynk` CLI tool to automate SBOM uploads from local storage. | ||
|
|
||
| 1. **For the latest release version of `sbomqs` using the release method**: | ||
| This will look for the latest release of the repository and check if SBOMs are generated. | ||
| 📌 **Limitation:** These methods work **only for SBOMs already generated and stored locally**, requiring **manual effort** or **pre-existing automation**. | ||
|
|
||
| ```bash | ||
| --in-github-url=https://github.com/interlynk-io/sbomqs | ||
| --in-github-method="release" | ||
| ``` | ||
| ### Externally Available SBOMs (The sbommv Solution) | ||
|
|
||
| 2. **For a particular release (`v1.0.0`) of `sbomqs` using the release method**: | ||
| Many SBOMs **are not locally available** but exist in **external systems** like: | ||
|
|
||
| ```bash | ||
| --in-github-url=https://github.com/interlynk-io/[email protected] | ||
| --in-github-method="release" | ||
| ``` | ||
| - **GitHub Repositories** → SBOMs generated in CI/CD pipelines | ||
| - **Public Websites** → Organizations publishing SBOMs externally | ||
| - **Other SBOM Repositories** → Systems storing SBOMs for compliance tracking | ||
|
|
||
| 3. **For only certain repositories (`sbomqs`, `sbomasm`) of `interlynk-io` using the API method**: | ||
| 🛑 **The Challenge:** | ||
| Manually fetching SBOMs from **multiple sources** and **uploading them individually** is **slow, repetitive, and error-prone**. | ||
|
|
||
| ```bash | ||
| --in-github-url=https://github.com/interlynk-io \ | ||
| --in-github-include-repos=sbomqs,sbomasm | ||
| ``` | ||
| ✅ **The sbommv Solution:** | ||
| **sbommv automates the transfer of SBOMs from external sources to Interlynk.** It: | ||
|
|
||
| 4. **To exclude specific repositories (`sbomqs`) from `interlynk-io` using the API method**: | ||
| 🔹 **Extracts SBOMs from external systems** (e.g., GitHub) | ||
| 🔹 **Handles different GitHub methods** (`release`, `api`, `tool`) for fetching SBOMs | ||
| 🔹 **Uploads SBOMs seamlessly to Interlynk** | ||
| 🔹 **Supports dry-run mode** to preview SBOMs before actual upload | ||
| 🔹 **Ensures interoperability** for better **automation and scalability** | ||
|
|
||
| ```bash | ||
| --in-github-url=https://github.com/interlynk-io \ | ||
| --in-github-exclude-repos=sbomqs | ||
| ``` | ||
| ## What's next 🚀 ?? | ||
|
|
||
| 4. **All repositories from `interlynk-io` using the API method**: | ||
| - **Getting started with sbommv:** <https://github.com/interlynk-io/sbommv/blob/main/docs/getting_started.md> | ||
| - **Try out more examples:** <https://github.com/interlynk-io/sbommv/blob/main/docs/examples.md> | ||
| - **To get with detailed CLI command and it's flag usage:** <https://github.com/interlynk-io/sbommv/blob/main/docs/flag_usage.md> | ||
| - To know more about Input and Output adapters: <https://github.com/interlynk-io/sbommv/blob/main/docs/adapters.md> | ||
|
|
||
| ```bash | ||
| --in-github-url=https://github.com/interlynk-io | ||
| ``` | ||
| ## Data Flow | ||
|
|
||
| --- | ||
|
|
||
|
|
||
| ### Output Adapters | ||
|
|
||
| #### Interlynk | ||
|
|
||
| The **Interlynk adapter** allows you to upload SBOMs to Interlynk Enterprise Platform. If no repository name is specified, it will auto-create projects & the env on the platform. | ||
| To access this platform `INTERLYNK_SECURITY_TOKEN`, will be required. | ||
|
|
||
| --- | ||
|
|
||
| **Command-line Parameters Supported by the Adapter** | ||
|
|
||
| - `--out-interlynk-url` [Optional]: URL for the interlynk service. Defaults to `https://api.interlynk.io/lynkapi` | ||
| - `--out-interlynk-project-name` [Optional]: Name of the project to upload the SBOM to, this is optional, if not-provided then it auto-creates it. | ||
| - --out-interlynk-project-env` [Optional]: Defaults to the "default" env. | ||
|
|
||
| --- | ||
|
|
||
| **Usage Examples** | ||
|
|
||
| 1. **Upload SBOMs to a particular project**: | ||
|
|
||
| ```bash | ||
| --out-interlynk-project-name=abc | ||
| ``` | ||
| ``` | ||
| +---------------------+ +------------------------------+ +----------------------+ | ||
| | Input Adapter | --> | Enrichment/Translation | --> | Output Adapter | | ||
| |-------------------- | |------------------------------| |----------------------| | ||
| | - GitHub | | - SBOM Translation* | | - Interlynk | | ||
| | - BitBucket* | | - Enrichment* | | - Dependency-Track* | | ||
| | - Dependency-Track*| +------------------------------+ | - Folder* | | ||
| | - Folder* | | | | ||
| +---------------------+ +-----------------------+ | ||
| 2. **Upload SBOMs to a particular project and env**: | ||
| * Coming Soon | ||
| ``` | ||
|
|
||
| ```bash | ||
| --out-interlynk-project-name=abc | ||
| --out-interlynk-project-env=production | ||
| ``` | ||
|
|
||
| ### Enrichment Adapters | ||
| ## License | ||
|
|
||
| ### Conversion Adapters | ||
|
|
||
| ## SPDX -> CDX | ||
|
|
||
| ## CDX -> SPDX | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
|
|
||
| # ⚙️ SBOMMV Command Flags & Usage Guide | ||
|
|
||
| This guide provides a **detailed breakdown** of the available flags for `sbommv transfer`, explaining their purpose and how to use them effectively. | ||
|
|
||
| ## 🟢 Global Flags | ||
|
|
||
| These flags apply to **all commands**, regardless of input or output adapters. | ||
|
|
||
| - `-D, --debug` : Enables **debug logging** to provide detailed insights into execution. Useful for troubleshooting. | ||
| - `--dry-run` : **Simulates the transfer process** without actually uploading SBOMs. This allows users to preview the results before making real changes. | ||
| - `-h, --help` : Displays the help menu for the `sbommv transfer` command. | ||
|
|
||
| ## 🔹 Input Adapter: GitHub Flags | ||
|
|
||
| The **GitHub adapter** allows fetching SBOMs from repositories or organizations. The following flags control how SBOMs are retrieved. | ||
|
|
||
| - `--input-adapter=github`: **Specifies GitHub as the input system** to fetch SBOMs. **(Required for GitHub input)** | ||
| - `--in-github-url <URL>`: **GitHub repository or organization URL** from which to fetch SBOMs. **Supports both individual repositories & organizations.** | ||
| - `--in-github-method <method>`: Specifies the method for retrieving SBOMs. **Options:** `"release"`, `"api"`, `"tool"`. Default: `"api"`. | ||
| - `--in-github-branch <branch>`: **(Tool Method Only)** Specifies a branch when using the **`tool` method** (e.g., `"main"`, `"develop"`). **Ignored for API and Release methods.** | ||
| - `--in-github-include-repos <repos>`: **(Org-Level Fetching Only)** Comma-separated list of repositories to **include** when fetching SBOMs from a GitHub organization. Not used for single repos. | ||
| - `--in-github-exclude-repos <repos>`: **(Org-Level Fetching Only)** Comma-separated list of repositories to **exclude** when fetching SBOMs from a GitHub organization. **Cannot be used with `--in-github-include-repos` simultaneously.** | ||
|
|
||
| ### 📌 When to use these Github Input Adalpter flags? | ||
|
|
||
| - **For a specific repository** → Use `--in-github-url="<repo_url>"` | ||
| - Example: `--in-github-url=https://github.com/sigstore/cosign` | ||
| - **For an entire organization** → Use `--in-github-url="<org_url>"` with `--in-github-include-repos` OR `--in-github-exclude-repos` | ||
| - Example: `--in-github-url=https://github.com/sigstore` | ||
| - **For a specific branch** → Use `--in-github-branch="<branch_name>"` (only with the tool method) | ||
|
|
||
| ## 🔹 Output Adapter: Interlynk Flags | ||
|
|
||
| The **Interlynk adapter** is used for uploading SBOMs to **Interlynk’s SBOM Management Platform**. | ||
|
|
||
| - `--output-adapter=interlynk`: **Specifies Interlynk as the output system.** **(Required for Interlynk output)** | ||
| - `--out-interlynk-url <URL>`: **Interlynk API URL**. Defaults to `"https://api.interlynk.io/lynkapi"`. Can be overridden for self-hosted instances. | ||
| - `--out-interlynk-project-name <name>`: **Name of the Interlynk project** to upload SBOMs to. If not provided, a project is auto-created based on the repository name. | ||
| - `--out-interlynk-project-env <env>`: **Project environment in Interlynk.** Default: `"default"`. Other options: `"development"`, `"production"`. | ||
|
|
||
| ### 📌 When to use these Interlynk Output Adapter flags? | ||
|
|
||
| - **Uploading to a specific Interlynk project** → Use `--out-interlynk-project-name="<name>"` | ||
| - **Uploading to a custom environment** → Use `--out-interlynk-project-env="development"` | ||
| - **NOTE**: For entire organization, no need to provide specific project, it will be automatically created as per requirements. | ||
|
|
||
| ## 📌 Summary | ||
|
|
||
| ✅ **GitHub Flags** → Control how SBOMs are fetched | ||
| ✅ **Interlynk Flags** → Control how SBOMs are uploaded | ||
| ✅ **Test with `--dry-run`** before uploading | ||
|
|
||
| 📌 **Looking for command examples?** → [Check out the Example Guide](https://github.com/interlynk-io/sbommv/blob/main/docs/examples.md) | ||
| 📌 **Want to get started quickly?** → [Read Getting Started with sbommv]([./docs/GettingStarted.md](https://github.com/interlynk-io/sbommv/blob/main/docs/getting_started.md)) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters