Metadata-Version: 2.4
Name: diffused-lib
Version: 0.3.0
Summary: A vulnerability scan diffing library for container images and SBOMs
Project-URL: documentation, https://github.com/konflux-ci/diffused/tree/main/docs
Project-URL: repository, https://github.com/konflux-ci/diffused
Project-URL: homepage, https://github.com/konflux-ci/diffused
Author: Willian Rampazzo
Author-email: willianr@redhat.com
License-Expression: Apache-2.0
Keywords: container,scanning,security,vulnerability
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Systems Administration
Requires-Python: <4.0,>=3.9
Provides-Extra: black
Requires-Dist: black; extra == 'black'
Provides-Extra: dev
Requires-Dist: diffused[black]; extra == 'dev'
Requires-Dist: diffused[flake8]; extra == 'dev'
Requires-Dist: diffused[isort]; extra == 'dev'
Requires-Dist: diffused[mypy]; extra == 'dev'
Requires-Dist: diffused[pytest]; extra == 'dev'
Requires-Dist: tox; extra == 'dev'
Provides-Extra: flake8
Requires-Dist: flake8; extra == 'flake8'
Provides-Extra: isort
Requires-Dist: isort; extra == 'isort'
Provides-Extra: mypy
Requires-Dist: mypy; extra == 'mypy'
Provides-Extra: pytest
Requires-Dist: pytest; extra == 'pytest'
Requires-Dist: pytest-cov; extra == 'pytest'
Description-Content-Type: text/markdown

# Diffused Library

The core Python library providing vulnerability scanning and diffing functionality for container images and SBOMs (Software Bill of Materials). This library enables programmatic access to vulnerability analysis capabilities.

## Features

- 🔍 **Vulnerability Scanning**: Automated scanning of SBOMs using [Trivy](https://trivy.dev/) or scanning of container images using [RHACS](https://www.redhat.com/pt-br/technologies/cloud-computing/openshift/advanced-cluster-security-kubernetes)
- 📊 **SBOM Diffing**: Direct comparison of SPDX-JSON formatted SBOMs (Trivy only)
- 📄 **Flexible Output**: Programmatic access to vulnerability data
- 🐍 **Python API**: Clean, intuitive Python interface

## Installation

### Prerequisites

1. **Install the scanner**:
    1. **Trivy**: Follow the [official Trivy installation guide](https://aquasecurity.github.io/trivy/latest/getting-started/installation/)
    2. **RHACS**: Follow the [official roxctl installation guide](https://docs.redhat.com/en/documentation/red_hat_advanced_cluster_security_for_kubernetes/4.8/html/roxctl_cli/index)
2. **Python Environment**: Ensure Python 3.9+ is installed

### From Source

```bash
cd diffused
pip install -e .
```

### From PyPI

```bash
pip install diffused-lib
```

## Usage

### Basic Library Usage

#### Comparing Container Images

```python
from diffused.differ import VulnerabilityDiffer

# Create a differ instance for container images
vuln_differ = VulnerabilityDiffer(
    previous_image="ubuntu:20.04",
    next_image="ubuntu:22.04",
    scan_type="image"  # Automatically scans images
)

# Retrieve the vulnerabilities diff (list of fixed CVEs)
fixed_vulnerabilities = vuln_differ.vulnerabilities_diff
print(f"Fixed vulnerabilities: {fixed_vulnerabilities}")

# Get detailed information about each fixed vulnerability
detailed_info = vuln_differ.vulnerabilities_diff_all_info
```

#### Comparing SBOMs

```python
from diffused.differ import VulnerabilityDiffer

# Create a differ instance for SBOMs
vuln_differ = VulnerabilityDiffer(
    previous_sbom="previous.sbom.json",
    next_sbom="current.sbom.json",
    scan_type="sbom"  # Automatically scans SBOMs
)

# Retrieve the vulnerabilities diff
fixed_vulnerabilities = vuln_differ.vulnerabilities_diff
```

#### Using Different Scanners

```python
from diffused.differ import VulnerabilityDiffer

# Use Trivy scanner (default)
trivy_differ = VulnerabilityDiffer(
    previous_image="nginx:1.20",
    next_image="nginx:1.21",
    scanner="trivy",
    scan_type="image"
)

# Use ACS scanner (requires ROX_ENDPOINT and ROX_API_TOKEN environment variables)
acs_differ = VulnerabilityDiffer(
    previous_image="nginx:1.20",
    next_image="nginx:1.21",
    scanner="acs",
    scan_type="image"
)
```
