Community
Questions Library
Docs
Blog
Events
Swag
Github
Slack
JupiterOne
Discussions
Release Notes
Contact Us
Generating a Software Bill of Materials (SBOM) - AskJ1 Community
<main> <article class="userContent"> <p>A software bill of materials (SBOM) allows you to quickly see and assess vulnerability and security risks in your organization. JupiterOne generates a SBOM for the assets you have configured with J1, examining the list of vulnerabilities in relation to your assets.</p> <h3 data-id="prerequisite">Prerequisite</h3> <p>To generate the SBOM file, you must have Administrator access to your assets. Your environment must also contain:</p> <ul><li><p>An active GitHub, BitBucket, or GitLab integration in J1</p></li> <li><p>An active NPM or Artifactory integration in J1</p></li> <li><p><code class="code codeInline" spellcheck="false" tabindex="0">CodeRepo that USES CodeModule</code> relationships for your integrated GitHub, BitBucket, or GitLab integrations</p></li> <li><p>Installed version of <a rel="nofollow" href="cyclonedx-bom">CycloneDX</a> or something similar</p></li> </ul><p>The instructions in this article are based on using NPM as a package manager of node.js and the <a rel="nofollow" href="https://cyclonedx.org/">OWASP CycloneDX Software Bill of Materials (SBOM) Standard</a>.</p> <h3 data-id="install-and-invoke-the-cyclonedx-sbom-tool">Install and Invoke the CycloneDX SBOM Tool</h3> <p>To install the tool</p> <ol><li><p>Run <code class="code codeInline" spellcheck="false" tabindex="0">npm install -g @cyclonedx/bom</code>, if you have not already installed the tool.</p></li> <li><p>Run <code class="code codeInline" spellcheck="false" tabindex="0">cyclonedx-bom -o sbom.json</code> to change the format of the SBOM from the default XML format to JSON.</p> <p>If you want to include developer dependencies, you can use <code class="code codeInline" spellcheck="false" tabindex="0">cyclonedx-bom -o sbom.json -d</code>. Developer dependencies helps us understand if there are developer machines that may have been compromised as a result of an NPM package being compromised.</p></li> </ol><h3 data-id="pull-dependency-distinctions">Pull Dependency Distinctions</h3> <p>The CycloneDX file does not maintain which developer dependencies are direct vs, transitive or developer vs productions, therefore, it is necessary to add annotations.</p> <p>The <code class="code codeInline" spellcheck="false" tabindex="0">package.json</code> file of the NPM project is a JSON structure that contains <code class="code codeInline" spellcheck="false" tabindex="0">devDependencies</code> and <code class="code codeInline" spellcheck="false" tabindex="0">dependency</code> arrays that represent the distinctions you need to make. Use a command-line JSON processor to extract these arrays and redirect them to an output file that you use as for the input parameters for the ingestion script. The following code uses the <a rel="nofollow" href="https://github.com/stedolan/jq">jq tool</a>.</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">jq '.devDependencies | keys' package.json > devDeps.json </pre> <pre class="code codeBlock" spellcheck="false" tabindex="0">jq '.dependencies | keys' package.json > directDeps.json </pre> <h3 data-id="ingest-the-cyclonedx-sbom-into-j1">Ingest the CycloneDX SBOM into J1</h3> <p>The ingestion script required two arguments. One is the SBOM and a path to your SBOM file that CycloneDX generated. The other required argument is the repository, which specifies the name of the code repository that you are ingesting against. Include the two optional arguments for developer dependencies and direct dependencies.</p> <p><strong>Note</strong>: For the purposes of this ingestion script, the repo you ingest against must already exist in the JupiterOne graph database, so ensure you integrate your source code management (SCM) tool of choice, such as GitHub, Bitbucket, or GitLab.</p> <p>Ingestion script:</p> <p><img src="https://us.v-cdn.net/6035534/uploads/OTZS0B0HW62V/sbom-script1.png" alt="" class="embedImage-img importedEmbed-img"></img></p> <p>The full command for this example:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">ingest-cyclonedx –sbom ./sbom.json –repo jupiter-mapper –devDeps ./devDeps.json –directDeps ./directDeps.json </pre> <p>Alternatively, if you are also using an NPM project, and you do not want to perform the first two steps above, you can invoke the <a rel="nofollow" href="https://github.com/JupiterOne/secops-automation-examples/tree/main/npm-inventory"><code class="code codeInline" spellcheck="false" tabindex="0">npm-inventory</code> script. </a> This script only ingests direct dependencies by default, but is an equivalent method to ingesting NPM dependency data into the JupiterOne graph database.</p> <h3 data-id="extract-data-from-the-j1-graph-database-by-script">Extract Data from the J1 Graph Database by Script</h3> <p>JupiterOne, like other graph databases, looks at relationships between assets. In this specific example, you are looking at the <code class="code codeInline" spellcheck="false" tabindex="0">CodeRepo -USES-> CodeModules</code> relationship because the <code class="code codeInline" spellcheck="false" tabindex="0">USES</code> relationship provides the distinctions of developer vs. production and direct vs. transitive dependencies.</p> <p>This script generates the SBOM. In this example, the alias <code class="code codeInline" spellcheck="false" tabindex="0">generate-sbom</code> initiates a query of the J1 graph database to <code class="code codeInline" spellcheck="false" tabindex="0">Find CodeModule THAT USES CodeRepo</code>. You can filter the query to only show direct dependencies that are production.</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">generate-sbom "Find npm_package THAT USES as u CodeRepo WHERE u.directDependencies=true and u.devDependencies=false" </pre> <p>if you annotate your code repos in GitHub with tagging information, you can adjust the query to build a tag-specific SBOM:</p> <pre class="code codeBlock" spellcheck="false" tabindex="0">generate-sbom "Find CodeModule THAT USES CodeRepo WITH tag.Component='<insert tag name>'" </pre> <h3 data-id="extract-data-from-the-j1-graph-database-in-j1-assets">Extract Data from the J1 Graph Database in J1 Assets</h3> <p>To generate an SBOM:</p> <ol><li><p>In J1, go to <strong>Apps <img src="https://us.v-cdn.net/6035534/uploads/P64XB3PR3E7D/apps.png" alt="" class="embedImage-img importedEmbed-img"></img> > Assets</strong>.</p></li> <li><p>In the top-right corner, click <strong>Generate SBOM</strong>.<br> </p> <p><img src="https://us.v-cdn.net/6035534/uploads/0JOJZWJ3VB6F/sbom.png" alt="" class="embedImage-img importedEmbed-img"></img></p> <p></p></li> <li><p>If you have met the prerequisite criteria above, then you can click <strong>Generate Download</strong>, and J1 downloads the SBOM in the form of a JSON file.</p></li> </ol><p>If you do not meet any of the prerequisite criteria, you see a red X next to the criteria. Click the red X for more information about the error.</p> <p><img src="https://us.v-cdn.net/6035534/uploads/TQTW9MI3K325/sbom-errors.png" alt="" class="embedImage-img importedEmbed-img"></img></p> <p>Follow the corrective instructions in the error message, and try to generate your SBOM again.</p> <p><img src="https://us.v-cdn.net/6035534/uploads/XAPHCWM6CYIJ/sbom-code-repo-error.png" alt="" class="embedImage-img importedEmbed-img"></img></p> </article> </main>
.png)