OmniBOM-CLI 🛡️

OmniBOM-CLI is a unified multi-ecosystem software composition analysis (SCA) and dependency auditing tool. It audits Python (requirements.txt) and Node.js (package.json) dependencies, retrieves package metadata from public package registries, queries the OSV vulnerability database for known vulnerabilities, and generates CycloneDX JSON v1.5 SBOMs alongside CSV audit reports.

OmniBOM-CLI currently supports:

• PyPI — Python dependencies declared in requirements.txt
• npm — Node.js dependencies declared in package.json

Depending on registry availability, OmniBOM-CLI can collect package ownership, author, maintainer, license, cryptographic artifact hash information, and known vulnerability information.

---

Prerequisites

Before using OmniBOM-CLI, ensure you have the following installed on your system:

• Python 3.12 or higher
• pip (Python package installer)
• An active internet connection

Internet access is required for:

• Package metadata retrieval from PyPI and npm
• OSV vulnerability lookups
• Package artifact retrieval when a registry-provided cryptographic hash is unavailable and a hash calculation fallback is required

---

OmniBOM-CLI: Complete User Documentation

OmniBOM-CLI scans configured dependency manifests and produces software supply-chain inventory and vulnerability reports.

For each configured environment, the scanner can generate:

1. A CycloneDX JSON v1.5 SBOM
2. A CSV dependency inventory report
3. A CSV vulnerability report, when vulnerabilities are detected

The scanner is configuration-driven, allowing multiple environments and manifest files to be processed from a single config.json.

---

1. Installation

Ensure that Python 3.12 or newer is installed on your system.

Install OmniBOM-CLI from PyPI using pip:

pip install omnibom-cli

After installation, the omnibom command is available from the command line.

Verify the installation by running:

omnibom --help

---

2. Project Configuration (config.json)

OmniBOM-CLI uses a JSON configuration file to define:

• Organization metadata
• Application/project metadata
• Output location
• Scan targets
• Manifest paths
• Application/environment versions
• Dependency exclusion patterns

Create a file named config.json in your project workspace.

Example config.json

{
  "org_name": "Your Company Name",
  "org_url": "https://www.yourcompany.com",
  "contact_name": "Security & Compliance Team",
  "contact_email": "security@yourcompany.com",
  "project_name_prefix": "my-core-app",
  "output_directory": "./bom_outputs",

  "scan_targets": [
    {
      "environment_label": "backend-api",
      "type": "pypi",
      "manifest_path": "./src/api/requirements.txt",
      "version": "1.2.0"
    },
    {
      "environment_label": "frontend-web",
      "type": "npm",
      "manifest_path": "./src/web/package.json",
      "version": "2.1.4"
    }
  ],

  "excluded_component_patterns": [
    "^@babel\\/.*",
    "^eslint.*",
    "^jest.*",
    "^pytest.*",
    "^typescript$"
  ]
}

Security note: If your project repository is public, do not commit real internal organization metadata, internal URLs, private contact information, credentials, tokens, or other confidential information. Use appropriate placeholders or a private configuration mechanism.

---

Configuration Breakdown

org_name

Organization or manufacturer name associated with the generated SBOM metadata.

Example:

"org_name": "Your Company Name"

This value can appear in the CycloneDX SBOM metadata.

---

org_url

Organization or manufacturer URL.

Example:

"org_url": "https://www.yourcompany.com"

---

contact_name

Contact name associated with the organization/manufacturer metadata in the generated SBOM.

Example:

"contact_name": "Security & Compliance Team"

---

contact_email

Contact email associated with the organization/manufacturer metadata.

Example:

"contact_email": "security@yourcompany.com"

Use an appropriate organizational contact address rather than a personal address where possible.

---

project_name_prefix

Prefix used when constructing the root application component in the generated CycloneDX SBOM.

Example:

"project_name_prefix": "my-core-app"

The environment label is incorporated into the generated application component.

---

output_directory

Location where generated reports will be saved.

Example:

"output_directory": "./bom_outputs"

The directory is created automatically if it does not already exist.

---

3. Scan Targets

The scan_targets array defines the dependency manifests that OmniBOM-CLI should scan.

Example:

"scan_targets": [
  {
    "environment_label": "backend-api",
    "type": "pypi",
    "manifest_path": "./src/api/requirements.txt",
    "version": "1.2.0"
  },
  {
    "environment_label": "frontend-web",
    "type": "npm",
    "manifest_path": "./src/web/package.json",
    "version": "2.1.4"
  }
]

Each scan target contains the following fields.

environment_label

A unique name identifying the environment being scanned.

Example:

"environment_label": "backend-api"

The environment label is also used as part of the generated output filenames.

---

type

Defines the package ecosystem and manifest parser.

Supported values:

Type	Manifest	Ecosystem
pypi	requirements.txt	PyPI
npm	package.json	npm

Example:

"type": "pypi"

or:

"type": "npm"

---

manifest_path

Path to the dependency manifest that should be scanned.

Example:

"manifest_path": "./src/api/requirements.txt"

or:

"manifest_path": "./src/web/package.json"

The path may be relative to the directory from which the scanner is executed.

---

version

Application or environment version associated with the scan.

Example:

"version": "1.2.0"

This version is used for the root application component in the generated SBOM.

It is not used as the version of the individual dependencies. Dependency versions are obtained from the configured manifest.

---

4. Excluded Component Patterns

The excluded_component_patterns configuration contains regular expressions used to exclude dependencies from the generated component inventory.

Example:

"excluded_component_patterns": [
  "^@babel\\/.*",
  "^eslint.*",
  "^jest.*",
  "^pytest.*",
  "^typescript$"
]

These patterns can be used to exclude development-only tooling such as:

• Build tools
• Test frameworks
• Linters
• Formatting tools
• TypeScript tooling
• Other development dependencies

The exact exclusion behavior depends on the regular-expression patterns supplied in the configuration.

Common examples

^@babel\/.*
^eslint.*
^jest.*
^pytest.*
^prettier.*
^typescript$
^react-test-renderer$
^@types\/.*

Use exclusions carefully. Excluding a dependency means that it will not be represented in the scanner's processed component output.

For compliance or production SBOM use cases, exclusions should be reviewed and approved according to your organization's dependency-inventory requirements.

---

5. Running the Scanner

After creating your config.json, open a terminal in the appropriate project directory and execute:

omnibom --config ./config.json

The scanner will:

1. Load the supplied configuration.
2. Read each configured scan target.
3. Parse the specified dependency manifest.
4. Filter dependencies matching configured exclusion patterns.
5. Query package registry metadata.
6. Retrieve package ownership, author, and maintainer information when available.
7. Retrieve license information when available.
8. Retrieve published artifact hash information when available.
9. Calculate an artifact SHA-256 hash when an appropriate registry hash is unavailable and the published artifact can be downloaded.
10. Query the OSV vulnerability database for known vulnerabilities affecting the specified package version.
11. Build a CycloneDX JSON v1.5 SBOM.
12. Generate a CSV dependency inventory report.
13. Generate a separate CSV vulnerability report when vulnerabilities are detected.

---

6. Package Metadata and Hash Handling

OmniBOM-CLI retrieves package metadata from the relevant public package registry.

PyPI

For PyPI packages, the scanner can retrieve:

• Author
• Maintainer
• License information
• Published distribution metadata
• SHA-256 artifact digest

If registry metadata does not provide a usable artifact digest, the scanner can attempt to download the published artifact and calculate its SHA-256 digest.

---

npm

For npm packages, the scanner can retrieve:

• Author
• Maintainers
• License
• Distribution metadata
• npm integrity information

npm integrity values can contain SHA-1, SHA-256, or SHA-512 information. OmniBOM-CLI decodes supported npm Subresource Integrity (SRI) values for use in the generated SBOM.

If an appropriate registry hash is unavailable, the scanner can attempt to download the published npm tarball and calculate a SHA-256 digest.

---

Hash information

When available, the inventory report records both:

Hash
Hash Algorithm

The generated CycloneDX SBOM preserves the corresponding hash information.

Hash availability depends on the metadata and artifacts published by the package registry.

---

7. Vulnerability Detection

OmniBOM-CLI queries the OSV vulnerability database using the package name, version, and ecosystem.

The scanner can identify known vulnerabilities associated with the exact dependency version supplied by the manifest.

For each vulnerability, the scanner can report information such as:

• Vulnerability identifier
• CVE identifier when one is available
• OSV identifier when a CVE identifier is not available
• Severity information when provided
• CVSS information when provided
• OSV or NVD reference URL

The scanner should not be interpreted as guaranteeing detection of every security vulnerability. Vulnerability databases are continuously updated, and vulnerability information may be incomplete or unavailable.

---

8. Generated Reports

OmniBOM-CLI saves generated files inside the directory configured by:

"output_directory"

For example:

"output_directory": "./bom_outputs"

For an environment named:

backend-api

the scanner generates the following reports when applicable.

---

A. CycloneDX SBOM

File:

backend-api_cyclonedx.json

What it is

A machine-readable Software Bill of Materials generated using the CycloneDX JSON v1.5 output format.

The SBOM can contain:

• Root application/component metadata
• Organization/manufacturer metadata
• Component inventory
• Package URLs (PURLs)
• Dependency relationships
• Supplier/owner information
• Author information
• Maintainer properties
• License information where available
• Cryptographic hashes where available
• Lifecycle/component properties

The SBOM establishes the relationship between the configured application/environment and its scanned upstream dependencies.

How to use it

The generated SBOM can be imported into tools that support CycloneDX, including:

• OWASP Dependency-Track
• Software composition analysis platforms
• Vulnerability management platforms
• Software supply-chain and compliance systems

Do not manually edit generated SBOM files unless you understand the impact on their integrity and downstream processing.

---

B. Audit Inventory Report

File:

backend-api_inventory_report.csv

What it is

A human-readable CSV inventory containing the processed third-party dependencies detected by the scanner.

Depending on package registry availability, the report can contain:

• Environment
• Package URL identifier
• Component name
• Version
• Ecosystem
• Supplier/owner
• Author
• Maintainer
• License
• Cryptographic hash
• Hash algorithm
• CVE/vulnerability status
• Lifecycle status

How to use it

The CSV report can be opened using:

• Microsoft Excel
• Google Sheets
• LibreOffice Calc
• Other spreadsheet and data-analysis tools

Review fields such as:

• Owner
• Author
• Maintainer
• License
• Version
• Hash
• Vulnerability status

These fields can support software supply-chain inventory, licensing review, dependency governance, and security assessment.

The scanner reports package metadata; it does not independently determine that a dependency is abandoned or unsafe solely from its ownership or maintainer information.

---

C. Security Vulnerability Report

File:

backend-api_security_vulnerabilities.csv

What it is

A dedicated CSV vulnerability report containing vulnerabilities returned by the OSV vulnerability database for the scanned dependency versions.

When vulnerabilities are reported, the CSV can contain:

• Target environment
• Component PURL
• Component name
• Version
• Vulnerability ID
• Severity
• CVSS score
• OSV/NVD reference URL

Vulnerabilities detected

Review:

• Vulnerability ID
• CVE identifier, where available
• Severity
• CVSS information
• Affected component
• Affected version
• Registry/reference URL

Use this information to:

1. Investigate affected dependencies.
2. Determine whether the vulnerability applies to your deployment.
3. Review available remediation or upgrade options.
4. Verify the appropriate patched version.
5. Re-run the scanner after remediation.

No vulnerabilities detected

The vulnerability report is generated when vulnerability records are present.

If no vulnerabilities are detected for an environment, the scanner may not create the vulnerability CSV for that environment.

Do not interpret the absence of a vulnerability report as proof that the software contains no security vulnerabilities. The scanner only reports vulnerabilities available through the queried OSV data at the time of the scan.

---

9. Output Example

Given the following target:

{
  "environment_label": "backend-api",
  "type": "pypi",
  "manifest_path": "./src/api/requirements.txt",
  "version": "1.2.0"
}

the output directory can contain:

bom_outputs/
├── backend-api_cyclonedx.json
├── backend-api_inventory_report.csv
└── backend-api_security_vulnerabilities.csv

The vulnerability report may be absent when no vulnerabilities are returned for the scanned components.

---

10. Troubleshooting

Reports are missing

First check the scanner terminal output.

Verify that:

• The configuration file is valid JSON.
• The output directory is writable.
• The configured manifest exists.
• The manifest contains dependencies in the expected format.
• The scanner has network access when registry or OSV lookups are required.

A successful CycloneDX generation displays a message similar to:

Saved CycloneDX JSON:

---

Missing source files

If you see:

Tracked source path missing

verify the manifest_path value in config.json.

For Python, verify that the path points to the intended:

requirements.txt

For Node.js, verify that the path points to the intended:

package.json

Example:

{
  "environment_label": "backend-api",
  "type": "pypi",
  "manifest_path": "./src/api/requirements.txt",
  "version": "1.2.0"
}

---

Invalid package.json

If an npm target produces no components, verify that:

• package.json contains valid JSON.
• Dependencies are declared under dependencies or devDependencies.
• Dependency names and versions are valid.

The scanner combines dependencies and devDependencies before applying the configured exclusion patterns.

---

Requirements parsing issues

Ensure that the Python dependency file contains standard requirement declarations.

For example:

requests==2.34.2
urllib3>=2.0.0
package-name~=1.5

Comments and empty lines are ignored.

---

Network Issues

OmniBOM-CLI requires network access for external package and vulnerability information.

Network access may be required for:

• PyPI metadata
• npm metadata
• OSV vulnerability queries
• Published artifact downloads used for hash calculation

If network requests fail, some metadata or vulnerability information may be unavailable.

The scanner should therefore be run in an environment where outbound access to the required public services is permitted.

---

Unknown package version

If a dependency does not provide a specific version in the supported manifest format, vulnerability lookup cannot be performed for that dependency.

The scanner represents unknown versions as:

unknown

Such components should be reviewed separately because version-specific vulnerability matching cannot be performed without a known version.

---

11. Supported Ecosystems

Ecosystem	Manifest	Registry Metadata	OSV Lookup	CycloneDX
PyPI	requirements.txt	Yes	Yes	Yes
npm	package.json	Yes	Yes	Yes

Additional ecosystems are not supported unless explicitly implemented in the scanner.

---

12. CycloneDX and Package URLs

Each dependency is represented using a Package URL (PURL) to provide a standardized package identifier.

Examples include:

pkg:pypi/requests@2.34.2

and:

pkg:npm/example-package@1.2.3

PURLs are used as component identifiers in the generated CycloneDX SBOM and vulnerability inventory.

---

13. Security and Data Considerations

OmniBOM-CLI processes dependency manifest information and queries public package/vulnerability services.

Before running the scanner in a sensitive environment, review your organization's:

• Network security requirements
• Software supply-chain policies
• Data-handling requirements
• Proxy requirements
• External API access policies
• SBOM distribution requirements

Do not place secrets, credentials, API keys, access tokens, private keys, or other confidential information inside requirements.txt, package.json, or config.json unless there is a specific and secure reason to do so.

The scanner configuration may contain organization metadata that is subsequently included in generated SBOM metadata. Protect generated SBOMs and reports according to your organization's information-classification requirements.

---

14. Limitations

OmniBOM-CLI is a dependency manifest scanner and software composition analysis utility. It does not perform a complete security assessment of an application.

It does not guarantee detection of:

• Zero-day vulnerabilities
• Vulnerabilities not present in the queried vulnerability sources
• Application-specific vulnerabilities
• Runtime configuration vulnerabilities
• Vulnerabilities introduced by custom source code
• Malicious packages that have not been identified by available security databases
• All licensing risks
• All software supply-chain risks

A package with no vulnerability returned by OSV should not automatically be interpreted as completely secure.

Likewise, a vulnerability reported by OSV should be reviewed in the context of the application's actual usage, deployment, exposure, and affected functionality.

---

15. Recommended Workflow

A typical workflow is:

Dependency Manifest
       │
       ▼
OmniBOM-CLI
       │
       ├── Parse dependencies
       │
       ├── Retrieve registry metadata
       │
       ├── Resolve package ownership/license/hash data
       │
       ├── Query OSV vulnerability database
       │
       ├── Generate CycloneDX SBOM
       │
       └── Generate CSV reports
              │
              ├── Inventory Report
              │
              └── Vulnerability Report

After generating the reports:

1. Review the dependency inventory.
2. Review vulnerability findings.
3. Validate affected package versions.
4. Investigate applicable vulnerabilities.
5. Upgrade or otherwise remediate affected dependencies where appropriate.
6. Re-run OmniBOM-CLI.
7. Compare the new reports against the previous scan.
8. Retain the SBOM and audit reports according to your organization's software-supply-chain and compliance requirements.

---

16. Example Complete Workflow

Create the configuration:

mkdir omnibom-scan
cd omnibom-scan

Create:

config.json

Configure your targets:

{
  "org_name": "Your Company Name",
  "org_url": "https://www.yourcompany.com",
  "contact_name": "Security & Compliance Team",
  "contact_email": "security@yourcompany.com",
  "project_name_prefix": "my-core-app",
  "output_directory": "./bom_outputs",

  "scan_targets": [
    {
      "environment_label": "backend-api",
      "type": "pypi",
      "manifest_path": "./src/api/requirements.txt",
      "version": "1.2.0"
    },
    {
      "environment_label": "frontend-web",
      "type": "npm",
      "manifest_path": "./src/web/package.json",
      "version": "2.1.0"
    }
  ]
}

Run:

omnibom --config ./config.json

Review:

bom_outputs/

The generated SBOMs can then be consumed by compatible CycloneDX tooling, while the CSV reports can be used for manual review, audit, and downstream analysis.

---

17. License

OmniBOM-CLI is distributed under the MIT License.

See the project's LICENSE file for the complete license terms.

---

Disclaimer

OmniBOM-CLI is a software composition analysis (SCA) and dependency auditing tool.

The software uses publicly available package metadata and vulnerability information, including data from package registries and the OSV vulnerability database, to assist with software inventory and identification of known vulnerabilities.

Security results, SBOM files, package metadata, and audit reports are provided for informational, security-assessment, and compliance-assistance purposes only.

OmniBOM-CLI does not guarantee detection of every vulnerability, security issue, licensing risk, malicious package, or software supply-chain threat. Vulnerability and package metadata are dependent on the external sources available at the time of the scan.

Users are responsible for independently validating scanner results before making security, compliance, deployment, or business decisions.

The scanner should be considered one component of a broader software security and supply-chain management process and should not be treated as a substitute for application security testing, manual security review, or organizational compliance processes.

Use of OmniBOM-CLI is subject to the project's applicable license terms.