Metadata-Version: 2.4
Name: omnibom-cli
Version: 1.0.2
Summary: OmniBOM-CLI is a unified multi-ecosystem manifest scanner that audits Python (requirements.txt) and Node.js (package.json) dependencies. It queries live OSV registry data for real-time CVE and vulnerability detection, automatically exporting compliant CycloneDX JSON v1.5 tracking bills of materials alongside flat auditing CSV data sheets.
Author-email: SURENDHAR S <surendhar.s.projects@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests==2.34.2
Requires-Dist: cyclonedx-bom==7.3.0
Requires-Dist: packageurl-python==0.17.6
Dynamic: license-file

# OmniBOM-CLI 🛡️

**OmniBOM-CLI** is a unified multi-ecosystem manifest scanner. It audits Python (`requirements.txt`) and Node.js (`package.json`) dependencies, queries live OSV registry data for real-time CVE vulnerability detection, and automatically generates compliant **CycloneDX JSON v1.5** Bills of Materials (SBOM) and flat-file audit reports.

---

## 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 (required to query the live OSV vulnerability database)

---
# OmniBOM-CLI: Complete User Documentation

**OmniBOM-CLI** is a unified multi-ecosystem manifest scanner. It audits Python (`requirements.txt`) and Node.js (`package.json`) dependencies, queries live OSV registry data for real-time CVE vulnerability detection, and automatically generates compliant **CycloneDX JSON v1.5** Bills of Materials (SBOM) alongside flat-file audit reports.

---

# 1. Installation

Ensure you have Python 3.12+ installed on your system.

You can install OmniBOM-CLI globally directly from PyPI using pip:

```bash
pip install omnibom-cli
```

---

# 2. Project Configuration (`config.json`)

OmniBOM-CLI uses a single JSON configuration file to manage your organization's metadata, output locations, and the target environments you want to scan.

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

## Example `config.json`

```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$"
  ]
}
```

---

## Configuration Breakdown

### `output_directory`

Location where generated reports will be saved.

---

### `scan_targets`

Defines the environments and manifests to scan.

Supported package ecosystems:

- `pypi` → Python projects using `requirements.txt`
- `npm` → Node.js projects using `package.json`

Each target requires:

- `environment_label`  
  Unique name for the scanned environment.

- `type`  
  Package ecosystem type (`pypi` or `npm`).

- `manifest_path`  
  Direct path to your dependency manifest file.

- `version`  
  Version identifier of your application/environment.

---

### `excluded_component_patterns`

Regex patterns used to ignore development-only dependencies.

Examples:

- Build tools
- Test frameworks
- Local development packages

Common exclusions:

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

This prevents development tooling from polluting production SBOM output.

---

# 3. Running the Scanner

After preparing your `config.json`, open a terminal in the same directory and execute:

```bash
omnibom --config ./config.json
```

The scanner will:

1. Read configured scan targets.
2. Parse dependency manifests.
3. Query registry metadata.
4. Check packages against Google OSV vulnerability data.
5. Generate SBOM and audit reports.

---

# 4. Locating and Reading Your Reports

OmniBOM-CLI saves generated files inside the folder specified in:

```json
"output_directory"
```

For every scanned environment, three files are generated.

Example environment:

```text
backend-api
```

Generated outputs:

---

# A. CycloneDX SBOM

File:

```text
backend-api_cyclonedx.json
```

## What it is

A machine-readable Software Bill of Materials formatted according to the **CycloneDX JSON v1.5 specification**.

It contains:

- Organizational metadata
- Component inventory
- Cryptographic hashes
- Package URLs (PURLs)
- Dependency information

## How to use it

Do not manually edit this file.

Import it into:

- OWASP Dependency-Track
- Enterprise vulnerability management platforms
- Compliance and cybersecurity audit systems

---

# B. Audit Inventory Report

File:

```text
backend-api_inventory_report.csv
```

## What it is

A human-readable spreadsheet containing a complete inventory of every detected third-party open-source dependency.

Includes dependency information such as:

- Package details
- Ownership information
- Maintainer data
- Registry metadata

## How to use it

Open using:

- Microsoft Excel
- Google Sheets
- Spreadsheet analysis tools

Review fields like:

- Owner
- Maintainer

to identify abandoned or poorly maintained dependencies.

---

# C. Security Risk Report

File:

```text
backend-api_security_vulnerabilities.csv
```

## What it is

A dedicated vulnerability report that compares exact package versions against the live **Google OSV vulnerability database**.

## How to use it

### No vulnerabilities found

If the file is empty:

```text
No known CVEs were detected.
```

Your dependencies currently have no publicly known vulnerabilities.

### Vulnerabilities detected

Review:

- Severity
- CVSS Score
- Vulnerability ID
- Registry-Link

Use these details to:

1. Prioritize fixes.
2. Upgrade affected dependencies.
3. Verify patch requirements.

---

# 5. Troubleshooting

## Reports are missing

Check the scanner terminal output.

Successful execution should show:

```text
💾 Saved CycloneDX JSON:
```

---

## Missing source files

If you see:

```text
⚠️ Tracked source path missing
```

verify your `manifest_path` value inside `config.json`.

Ensure it points to the correct:

- `requirements.txt`
- `package.json`

location.

---

## Network Issues

OmniBOM-CLI requires an active internet connection.

Network access is needed for:

- Package registry lookups
- Metadata retrieval
- OSV vulnerability scanning

---

# Copyright and License

Copyright (c) 2026 Surendhar S.

OmniBOM-CLI is free to use for personal, educational, research, and commercial dependency auditing purposes.

All source code, architecture, design, documentation, branding, and related intellectual property remain the exclusive property of the copyright holder.

Permission is granted to install and use this software package through official distribution channels.

You may not copy, modify, redistribute, repackage, resell, sublicense, or claim ownership of the OmniBOM-CLI source code without explicit written permission from the copyright holder.

All Rights Reserved.

# Disclaimer

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

The software uses publicly available package metadata and vulnerability sources, including the OSV vulnerability database, to identify known security issues.

Security results, SBOM files, and audit reports are provided for informational and compliance assistance purposes only.

OmniBOM-CLI does not guarantee detection of every vulnerability, security issue, licensing risk, or supply-chain threat.

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

The copyright holder shall not be liable for any damages, security incidents, data loss, business interruption, or other consequences resulting from the use of this software.

Use of OmniBOM-CLI indicates acceptance of these terms.
