rezmoss/sbomlyzeGit diff per gli SBOM: confronta documenti CycloneDX, SPDX e Syft, rileva manomissioni e blocca la pipeline CI.
# sbomlyze
**`git diff` per il tuo SBOM.** Confronta due Software Bill of Materials e scopri cosa è cambiato tra build, versioni e release.
sbomlyze confronta gli hash dei componenti, non solo le stringhe di versione. Quando un attaccante sostituisce un pacchetto senza incrementarne la versione, sbomlyze lo segnala. I generatori e gli scanner di vulnerabilità non se ne accorgono.
[![CI][ci-img]][ci]
[![GitHub Marketplace][marketplace-img]][marketplace]
[![GitHub Release][release-img]][release]
[![Go Report Card][go-report-img]][go-report]
[![OpenSSF Scorecard][scorecard-img]][scorecard]
[![OpenSSF Best Practices][best-practices-img]][best-practices]
[![License: Apache-2.0][license-img]][license]
[![Downloads][download-img]][download]
[](https://github.com/rezmoss/sbomlyze-go-spdx-demo/pull/2)
Scopri perché questo segnale è diverso da un diff di manifest o da un normale diff di componenti in
[Manifest diff vs. SBOM diff vs. integrity drift](https://github.com/rezmoss/sbomlyze/blob/main/docs/manifest-vs-sbom-vs-integrity-drift.md).
> I generatori creano SBOM e gli scanner trovano CVE. sbomlyze ti dice cosa è cambiato tra due SBOM e se fidarsi.
> Eseguilo dopo il tuo generatore: `syft image:tag -o cyclonedx-json | sbomlyze - --compliance` analizza e valuta l'SBOM generato senza file temporanei. Confrontalo con una baseline per classificare il drift e controllare la tua pipeline.
## Avvio rapido con GitHub Action
Aggiungi [SBOMlyze Diff da GitHub Marketplace][marketplace] per confrontare un SBOM archiviato nel repository
o generato separatamente con la sua baseline git. Lo SHA immutabile riportato di seguito
è la Action pubblicata `v0.5.1`:```yaml
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
with:
fetch-depth: 0
- uses: rezmoss/sbomlyze@31503690611fda8ebba4ed2bd186eda000442594 # v0.5.1
with:
sbom-path: build/sbom.cdx.json
```
L'Action scrive per impostazione predefinita un Job Summary e può applicare policy, segnalare
drift di integrità, caricare SARIF o mantenere un singolo commento su pull-request. Consulta
[il riferimento completo dell'Action](https://github.com/rezmoss/sbomlyze/blob/main/ACTION.md) per input, output, permessi
e linee guida di sicurezza. Consulta il
[repository dimostrativo live](https://github.com/rezmoss/sbomlyze-action-demo)
per un aggiornamento delle dipendenze superato e una modifica di hash a parità di versione bloccata, con
esecuzioni pubbliche dei workflow ed evidenze SARIF.
Per il dogfood specifico per formato, usa l'esempio pubblico
[Go + SPDX](https://github.com/rezmoss/sbomlyze-go-spdx-demo),
[Node + CycloneDX](https://github.com/rezmoss/sbomlyze-node-cyclonedx-demo) o
[container](https://github.com/rezmoss/sbomlyze-container-demo). Ognuno
contiene cinque scenari di revisione riproducibili. La
[guida beta di 10 minuti](https://github.com/rezmoss/sbomlyze/blob/main/BETA.md) raccoglie quattro domande mirate su attivazione e qualità
del segnale.
Gli SBOM generati non devono essere committati: `baseline: workflow-artifact`
recupera l'artifact corrispondente più recente da un'esecuzione riuscita sul branch predefinito. Un
[workflow companion Syft con versione bloccata](https://github.com/rezmoss/sbomlyze/blob/main/examples/workflows/syft-companion.yml)
mostra la generazione e la pubblicazione della baseline mentre SBOMlyze rimane responsabile
della revisione e della policy.
## Perché sbomlyze?
Molti strumenti generano SBOM. Pochi li confrontano, e ancora meno ti dicono se una modifica è di routine o un campanello d'allarme della supply chain. sbomlyze colma questa lacuna.
| Capacità | **sbomlyze** | cyclonedx-cli | sbomqs | syft / trivy |
|---|:---:|:---:|:---:|:---:|
| **diff** SBOM-to-SBOM | ✅ | base | ❌ | ❌ |
| Drift di **integrità / manomissione** (hash modificato senza versione) | ✅ | ❌ | ❌ | ❌ |
| Diff del grafo delle dipendenze + rischio di profondità transitiva | ✅ | ❌ | ❌ | ❌ |
| Scoring di conformità **NTIA / CISA / BSI** | ✅ | ❌ | ✅ | ❌ |
| Conversione di formato (Syft / CycloneDX / SPDX) | ✅ | ✅ | ❌ | parziale |
| Esploratori **TUI + Web UI** | ✅ | ❌ | ❌ | ❌ |
| Policy gate + SARIF / JUnit / Markdown / HTML / Patch | ✅ | parziale | parziale | parziale |
## Funzionalità
- **Diffing SBOM**: confronta due SBOM e visualizza a colpo d'occhio componenti aggiunti, rimossi e modificati
- **Classificazione del drift**: distingue il drift di versione dal **drift di integrità** (un hash modificato senza un cambio di versione, segnale di manomissione) e dal drift di metadati
- **Scoring di conformità**: valuta qualsiasi SBOM rispetto agli elementi minimi **NTIA**, **CISA 2025** e **BSI TR-03183**
- **Diff del grafo delle dipendenze**: traccia le dipendenze transitive e la profondità della supply chain
- **Supporto multi-formato**: Syft, CycloneDX, SPDX (JSON)
- **Conversione di formato**: converti tra i formati CycloneDX, SPDX e Syft
- **Corrispondenza forte delle identità**: precedenza PURL → CPE → BOM-ref → namespace/name
- **Modalità statistiche**: analizza singoli SBOM per metriche di licenza, dipendenze e integrità
- **Modalità TUI interattiva**: esplora gli SBOM con navigazione da tastiera e ricerca
- **Modalità Web UI**: esploratore SBOM basato su browser con upload drag-and-drop
- **Motore di policy**: applica regole su drift, licenze e punteggio di conformità nelle pipeline CI
- **GitHub Marketplace Action**: blocca le pull request sul drift degli SBOM con Job Summary, SARIF e output opzionale come commento
- **Rilevamento duplicati e collisioni**: trova più versioni dello stesso pacchetto e corrispondenze di identità ambigue
- **Formati di output multipli**: Text, JSON, SARIF, JUnit XML, Markdown, HTML, JSON Patch
- **Parsing tollerante**: continua in caso di errori con warning strutturati
## Installazione
### Homebrew (macOS/Linux)```bash
brew install rezmoss/sbomlyze/sbomlyze
```
### Script di installazione
Lo script di installazione scarica il binario corretto per il tuo sistema operativo/architettura:```bash
# Install to ./bin
curl -sSfL https://raw.githubusercontent.com/rezmoss/sbomlyze/main/install.sh | sh
# Install to /usr/local/bin (requires sudo)
curl -sSfL https://raw.githubusercontent.com/rezmoss/sbomlyze/main/install.sh | sudo sh -s -- -b /usr/local/bin
# Install specific version
curl -sSfL https://raw.githubusercontent.com/rezmoss/sbomlyze/main/install.sh | sh -s -- -v 0.4.0
```
**Opzioni del programma di installazione:**
| Opzione | Descrizione |
|--------|-------------|
| `-b <dir>` | Directory di installazione (predefinita: `./bin`) |
| `-d` | Abilita l'output di debug |
| `-v <ver>` | Installa una versione specifica (predefinita: ultima) |
Il programma di installazione verifica sempre il checksum della release. Quando è installata una GitHub CLI compatibile, verifica anche la provenienza della build della release e fallisce in modo sicuro se tale verifica non ha esito positivo.
### Go Install```bash
go install github.com/rezmoss/sbomlyze/cmd/sbomlyze@latest
```
### Da Binary Release
Scarica l'ultimo binario da [GitHub Releases](https://github.com/rezmoss/sbomlyze/releases).
A partire dalla v0.3.7, gli archivi di release sono pubblicati con attestazioni
di artefatti GitHub. Verifica un download in modo indipendente con:```bash
gh attestation verify ./sbomlyze_0.4.0_Linux_x86_64.tar.gz \
--repo rezmoss/sbomlyze \
--signer-workflow rezmoss/sbomlyze/.github/workflows/release.yml
```
Le istruzioni per i repository apt, rpm e apk non firmati sono state rimosse
finché i repository non supporteranno la verifica delle firme nativa del gestore di pacchetti.
**Utenti macOS:** Rimuovere il flag di quarantena dopo il download:```bash
xattr -d com.apple.quarantine ./sbomlyze
chmod +x ./sbomlyze
```
### Compilazione dal sorgente```bash
git clone https://github.com/rezmoss/sbomlyze.git
cd sbomlyze
go build -o sbomlyze ./cmd/sbomlyze
```
## Avvio rapido```bash
# Compare two SBOMs (the headline use case)
sbomlyze before.json after.json
# Analyze a single SBOM
sbomlyze image.json
# Read an SBOM from standard input
syft image:tag -o cyclonedx-json | sbomlyze -
# Use standard input on either side of a diff
syft image:tag -o cyclonedx-json | sbomlyze baseline.json -
# Score an SBOM against NTIA / CISA / BSI minimum elements
sbomlyze image.json --compliance
# Interactive TUI explorer
sbomlyze image.json -i
# Web UI (opens browser)
sbomlyze -web
# Convert between SBOM formats
sbomlyze convert syft.json --to spdx
sbomlyze convert cdx.json --to syft -o output.json
# JSON output for CI integration
sbomlyze before.json after.json --json
# SARIF output for GitHub Code Scanning
sbomlyze before.json after.json --format sarif
# Markdown report for PR comments
sbomlyze before.json after.json --format markdown
# Apply policy checks
sbomlyze before.json after.json --policy policy.json
```
## Utilizzo```
sbomlyze <sbom1|-> [sbom2|-] [options]
sbomlyze convert <sbom|-> --to <format> [-o output]
Modes:
Single file: sbomlyze <sbom> [--json] Show statistics
Interactive: sbomlyze <sbom> -i Interactive explorer
Convert: sbomlyze convert <sbom> --to <fmt> Convert SBOM format
Web server: sbomlyze -web [--port 8080] Web UI explorer
Two files: sbomlyze <sbom1> <sbom2> [...] Show diff
Use `-` in place of one SBOM path to read it from standard input.
Options:
-i, --interactive Interactive TUI explorer
-web, --web Start web UI server
--port <port> Web server port (default 8080)
--json Output in JSON format (shortcut for --format json)
--format <format> Output format: text, json, sarif, junit, markdown, html, patch
--compliance Show NTIA/CISA/BSI compliance scoring
--policy <file> Policy file for CI checks
--strict Fail on parse warnings
--tolerant Continue on parse warnings (default)
--no-pager Disable automatic paging of output
--to <format> Target format for convert: cyclonedx (cdx), spdx, syft
-o, --output <file> Output file for convert (default: stdout)
--version, -v Show version information
--help, -h Show this help message
```
## Comandi
### Modalità Statistiche (File Singolo)
Analizza un SBOM per ottenere informazioni su componenti, licenze e dipendenze.```bash
sbomlyze image.json
```
L'output include il contesto della scansione, i risultati chiave rilevati automaticamente e le statistiche:```
Scan Context:
Tool: syft 1.40.1
Schema: 16.0.18
Scan Scope: all-layers
Source Type: image
Source: alpine:latest
Key Findings:
💻 OS/Distro: Alpine Linux v3.21
📦 Dominated by apk: 71 of 71 packages (100.0%)
📂 8,542 files tracked on filesystem
🔗 Relationships: 71 containment + 64 dependency
📜 License profile: 72% permissive, 20% copyleft
⚠️ Low hash coverage: 0.0% (71 of 71 missing)
🔍 Top catalogers: apkdb-cataloger (71)
📦 SBOM Statistics
==================
Total Components: 71
By Package Type:
apk 71
Licenses:
With license: 71
Without license: 0
Top Licenses:
MIT 17
BSD-3-Clause 8
GPL-2.0-only 8
Integrity:
With hashes: 0
Without hashes: 71
Dependencies:
Components with deps: 65
Total dep relations: 176
```
#### Risultati principali
sbomlyze genera automaticamente informazioni dettagliate sul tuo SBOM. Per l'analisi di singoli file, queste includono:
| Risultato | Descrizione |
|---------|-------------|
| **Rilevamento OS/distro** | Identifica il sistema operativo o la distribuzione dai metadati dell'SBOM |
| **Ecosistema dominante** | Segnala quando un tipo di pacchetto domina (>60% di tutti i pacchetti) |
| **Impronta del filesystem** | Numero di file tracciati sul filesystem |
| **Densità delle relazioni** | Conteggio delle relazioni di contenimento e di dipendenza |
| **Punti caldi di localizzazione** | Directory principali in cui si trovano i componenti |
| **Profilo di rischio delle licenze** | Ripartizione delle percentuali di licenze permissive/copyleft/sconosciute |
| **Avvisi sulla qualità dei dati** | Avvisa quando la copertura di licenze (<50%), hash (<50%) o PURL (<80%) è bassa |
| **Avvisi sui duplicati** | Segnala gruppi di componenti duplicati |
| **Ripartizione per catalogatore** | Scanner/catalogatori principali che hanno rilevato i componenti (SBOM Syft) |
#### Metriche di copertura
La modalità statistiche calcola le percentuali di copertura per la valutazione della qualità dei dati:
| Metrica | Descrizione |
|--------|-------------|
| **Copertura PURL** | Percentuale di componenti con Package URL |
| **Copertura CPE** | Percentuale di componenti con CPE (prontezza per la scansione delle vulnerabilità) |
| **Copertura licenze** | Percentuale di componenti con almeno una licenza |
| **Copertura hash** | Percentuale di componenti con hash di integrità |
#### Categorizzazione delle licenze
Le licenze vengono automaticamente categorizzate in:
| Categoria | Esempi |
|----------|----------|
| **Copyleft** | GPL, LGPL, AGPL, MPL, EPL, CDDL |
| **Permissive** | MIT, BSD, Apache, ISC, Zlib, Unlicense |
| **Pubblico dominio** | Dediche al pubblico dominio |
| **Sconosciute** | Licenze non riconosciute o mancanti |
### Modalità Convert
Converte gli SBOM tra i formati CycloneDX, SPDX e Syft JSON. Il formato di input viene rilevato automaticamente.```bash
# CycloneDX to SPDX
sbomlyze convert image.cdx.json --to spdx
# Syft to CycloneDX (cdx is an alias for cyclonedx)
sbomlyze convert syft-output.json --to cdx
# SPDX to Syft, writing to a file
sbomlyze convert spdx-output.json --to syft -o converted.json
```
#### Formati di destinazione supportati
| Formato | Valore `--to` | Output |
|--------|-------------|--------|
| CycloneDX 1.5 | `cyclonedx` o `cdx` | CycloneDX JSON con metadati, dipendenze e proprietà |
| SPDX 2.3 | `spdx` | SPDX JSON con pacchetti, relazioni e riferimenti esterni |
| Syft | `syft` | Syft JSON con artefatti, relazioni, sorgente e informazioni sulla distribuzione |
#### Cosa viene preservato
La conversione preserva nomi dei componenti, versioni, PURL, CPE, licenze, hash, informazioni sul fornitore e relazioni di dipendenza. I campi specifici del formato (ad es., linguaggio Syft, foundBy, locations) vengono trasferiti attraverso le proprietà CycloneDX quando si converte in CDX.
### Modalità Diff (Due File)
Confronta due SBOM per vedere cosa è cambiato tra le versioni.```bash
sbomlyze v1.0.json v2.0.json
```
#### Panoramica delle differenze
Il diff inizia con un confronto affiancato dei metadati (nomi dei file, dimensioni, informazioni sul sistema operativo, informazioni sullo strumento, conteggio dei componenti) seguito dai dettagli del contesto della scansione quando disponibili.
#### Output```
📊 Drift Summary:
📦 Version drift: 58 components
⚠️ Integrity drift: 1 component (hash changed without version change!)
📝 Metadata drift: 2 components
🔑 Key Findings:
📈 Attack surface: +5 packages (7.0%), +120 files (3.2%)
🚨 2 version downgrades detected: openssl 3.1.4→3.0.2, curl 8.5.0→8.4.0
🔄 56 version upgrades (2 major, 12 minor, 42 patch) among 65 shared packages
⚠️ Integrity drift (1 total): 1 npm (review recommended)
❌ python ecosystem entirely removed (15 → 0 packages)
➕ New ecosystem: golang (8 packages)
✅ Core system packages stable: apk (71) unchanged
+ Added (2):
+ libgcrypt 1.10.3-r0
+ libgpg-error 1.49-r0
- Removed (3):
- libapk 3.0.3-r1
- libgcc 15.2.0-r2
- nghttp3 1.13.1-r0
~ Changed (58):
~ nginx
version: 1.29.4-r1 -> 1.27.3-r1
~ suspicious-pkg ⚠️ [INTEGRITY]
hash[SHA256]: abc123 -> def456
>> Added dependencies:
pkg:apk/alpine/libxslt: +[so:libgcrypt.so.20]
<< Removed dependencies:
pkg:apk/alpine/libcurl: -[so:libnghttp3.so.9]
🔗 New transitive dependencies (3):
+ pkg:npm/lodash (depth 2)
via: [pkg:npm/my-app pkg:npm/express pkg:npm/lodash]
+ pkg:npm/underscore (depth 3)
via: [pkg:npm/my-app pkg:npm/express pkg:npm/lodash pkg:npm/underscore]
📊 New deps by depth:
Depth 2: 1
Depth 3+ (risky): 2 ⚠️
```
#### Risultati Chiave del Diff
In modalità diff, sbomlyze genera automaticamente approfondimenti più ricchi confrontando entrambi gli SBOM:
| Risultato | Descrizione |
|---------|-------------|
| **Mancata corrispondenza del contesto di scansione** | Avvisa se la versione dello schema o l'ambito della scansione è cambiato tra gli SBOM |
| **Delta della superficie di attacco** | Variazioni del numero di pacchetti, file e relazioni con percentuali |
| **Ecosistemi scomparsi/nuovi** | Tipi di pacchetto che sono interamente comparsi o scomparsi |
| **Migrazione OS/distro** | Rileva cambiamenti nel sistema operativo tra le scansioni |
| **Analisi delle variazioni di versione** | Conta aggiornamenti vs downgrade, classifica i cambiamenti come major/minor/patch |
| **Downgrade di versione** | Segnala i downgrade come segnale di sicurezza con dettagli sui componenti |
| **Contesto della deriva di integrità** | Suddivide la deriva di integrità per tipo di pacchetto con indicazioni sul rischio |
| **Pattern di percorso dominanti** | Cambiamenti concentrati per tipo e percorso del filesystem |
| **Hotspot di rimozione/aggiunta** | Directory principali interessate dai cambiamenti |
| **Tipi stabili** | Tipi di pacchetto con conteggi identici (nucleo invariato) |
| **Spostamenti di categoria di licenza** | Cambiamenti nell'equilibrio copyleft/permissiva |
| **Lacune del catalogatore** | Scanner che hanno trovato pacchetti in Before ma nessuno in After |
#### Campioni di Pacchetti per Tipo
I componenti aggiunti e rimossi sono raggruppati per tipo di pacchetto con elenchi di campioni, rendendo facile vedere cosa è cambiato in ciascun ecosistema.
## Punteggio di Conformità
Assegna un punteggio a qualsiasi SBOM rispetto ai tre principali framework di elementi minimi per rispondere alla domanda che revisori e team di approvvigionamento continuano a porre: **"Questo SBOM è abbastanza completo?"**```bash
# Score a single SBOM
sbomlyze image.json --compliance
# Score alongside a diff
sbomlyze before.json after.json --compliance
# As JSON for CI
sbomlyze image.json --compliance --json
```
### Framework valutati
| Framework | Controlli | Requisiti notevoli |
|-----------|--------|----------------------|
| **NTIA Minimum Elements** (2021) | 7 | nome, versione, fornitore, ID univoci (PURL/CPE), relazioni di dipendenza, autore dell'SBOM, timestamp |
| **CISA 2025 Minimum Elements** (bozza ago 2025) | 10 | aggiunge produttore del software, informazioni sulla licenza, **hash del componente** e nome dello strumento oltre a NTIA |
| **BSI TR-03183-2** (v2.1.0, 2025) | 9 | richiede il contatto del creatore del componente, **hash SHA-512**, licenze in formato SPDX e contatto del creatore dell'SBOM |
### Presentazione del punteggio
Ogni framework riporta una percentuale (controlli superati / controlli totali) più un punteggio complessivo (media tra i framework), con indicatori di stato:
| Indicatore | Punteggio |
|-----------|-------|
| 🟢 | ≥ 90% |
| 🟡 | 70–89% |
| 🟠 | 50–69% |
| 🔴 | < 50% |
L'output JSON (`--compliance --json`) include il report completo con il dettaglio pass/fail per ogni controllo; il formato HTML incorpora il report di conformità nella pagina del report.
### Conformità vincolante in CI
Applica le soglie di conformità tramite il [policy engine](#policy-engine). L'impostazione di qualsiasi soglia attiva la valutazione della conformità senza il flag `--compliance`:```json
{
"min_ntia_score": 85,
"min_cisa_score": 70,
"min_bsi_score": 80,
"min_overall_compliance": 75
}
```
## Installazione
### Requisiti
- Python 3.8+
- pip (gestore di pacchetti Python)
### Installazione da PyPI
```bash
pip install pyxam
```
### Installazione da sorgente
```bash
git clone https://github.com/example/pyxam.git
cd pyxam
pip install -e .
```
### Verifica dell'installazione
```bash
pyxam --version
```
## Utilizzo
### Utilizzo di base
```bash
pyxam scan /path/to/target
```
### Opzioni della riga di comando
```
usage: pyxam [-h] [-v] [-o OUTPUT] [-t THREADS] {scan,analyze,report} ...
PyXAM - Python XSS Analysis and Mitigation
positional arguments:
{scan,analyze,report}
scan Esegue una scansione XSS
analyze Analizza i risultati della scansione
report Genera un report
optional arguments:
-h, --help mostra questo messaggio di aiuto ed esce
-v, --verbose abilita output dettagliato
-o OUTPUT, --output OUTPUT
file di output
-t THREADS, --threads THREADS
numero di thread
```
### Esempi
Scansiona un singolo URL:
```bash
pyxam scan https://example.com
```
Scansiona più URL da un file:
```bash
pyxam scan -f urls.txt
```
Analizza i risultati della scansione:
```bash
pyxam analyze results.json
```
Genera un report HTML:
```bash
pyxam report results.json -o report.html
```
## Configurazione
PyXAM può essere configurato tramite un file di configurazione o variabili d'ambiente.
### File di configurazione
Crea un file `pyxam.yaml` nella directory corrente:
```yaml
scan:
timeout: 30
threads: 10
user_agent: "PyXAM/1.0"
payloads:
- "<script>alert(1)</script>"
- ""
output:
format: json
verbose: false
```
### Variabili d'ambiente
```bash
export PYXAM_TIMEOUT=30
export PYXAM_THREADS=10
export PYXAM_USER_AGENT="PyXAM/1.0"
```
## Moduli
### Modulo Scanner
Il modulo scanner fornisce funzionalità per la scansione di vulnerabilità XSS.
```python
from pyxam import Scanner
scanner = Scanner(target="https://example.com")
results = scanner.scan()
```
### Modulo Analyzer
Il modulo analyzer analizza i risultati della scansione e identifica i falsi positivi.
```python
from pyxam import Analyzer
analyzer = Analyzer(results="results.json")
findings = analyzer.analyze()
```
### Modulo Reporter
Il modulo reporter genera report in vari formati.
```python
from pyxam import Reporter
reporter = Reporter(findings=findings)
reporter.generate(format="html", output="report.html")
```
## Payload
PyXAM include una libreria di payload XSS integrati.
### Payload di base
```html
<script>alert(1)</script>
<svg onload=alert(1)>
```
### Payload di bypass dei filtri
```html
<scr<script>ipt>alert(1)</scr</script>ipt>
<svg><script>alert(1)</script></svg>
```
### Payload personalizzati
Puoi aggiungere payload personalizzati creando un file `payloads.txt`:
```
<custom-payload-1>
<custom-payload-2>
```
## API
### Riferimento API
#### Classe Scanner
```python
class Scanner:
def __init__(self, target, timeout=30, threads=10):
"""Inizializza lo scanner."""
def scan(self):
"""Esegue la scansione XSS."""
def scan_url(self, url):
"""Scansiona un singolo URL."""
```
#### Classe Analyzer
```python
class Analyzer:
def __init__(self, results):
"""Inizializza l'analyzer."""
def analyze(self):
"""Analizza i risultati."""
def filter_false_positives(self):
"""Filtra i falsi positivi."""
```
#### Classe Reporter
```python
class Reporter:
def __init__(self, findings):
"""Inizializza il reporter."""
def generate(self, format="json", output=None):
"""Genera un report."""
``````bash
sbomlyze image.json --policy compliance-policy.json
```
## Diff del Grafo delle Dipendenze
sbomlyze va oltre i semplici diff degli elenchi di componenti per analizzare il grafo completo delle dipendenze, rilevando i rischi della supply-chain introdotti tramite dipendenze transitive.
### Funzionalità
| Funzionalità | Descrizione |
|---------|-------------|
| **Edge diff** | Dipendenze dirette aggiunte/rimosse (A dipende da B) |
| **Transitive reachability** | Nuove dipendenze indirette che compaiono attraverso il grafo |
| **Transitive loss tracking** | Dipendenze transitive che sono state rimosse |
| **Path tracking** | Mostra esattamente come viene raggiunta ogni nuova dipendenza transitiva |
| **Depth tracking** | Quanti salti di distanza separano ogni nuova dipendenza dal tuo codice |
| **Risk summary** | Dipendenze di profondità 3+ contrassegnate come a rischio più elevato |
### Perché la Profondità è Importante
Le dipendenze introdotte più in profondità nel grafo sono:
- Più difficili da verificare e revisionare
- Spesso incluse senza approvazione esplicita
- Vettori comuni per attacchi alla supply chain (ad es., l'incidente event-stream)
Il riepilogo della profondità aiuta a prioritizzare la revisione:
| Profondità | Livello di Rischio | Descrizione |
|-------|------------|-------------|
| **1** | Basso | Dipendenze dirette (le hai scelte tu) |
| **2** | Medio | Dipendenze delle tue dipendenze |
| **3+** | Alto ⚠️ | Dipendenze transitive profonde - revisionare con attenzione |
### Esempio: Rilevare Dipendenze Transitive Profonde```bash
# Before: app -> express (simple, 1 dep)
# After: app -> express -> lodash -> underscore -> deep-lib (chain of 4)
sbomlyze before.json after.json
```
```text
Output:
``````
🔗 New transitive dependencies (3):
+ lodash (depth 2)
via: [app express lodash]
+ underscore (depth 3)
via: [app express lodash underscore]
+ deep-lib (depth 4)
via: [app express lodash underscore deep-lib]
📊 New deps by depth:
Depth 2: 1
Depth 3+ (risky): 2 ⚠️
```
### Output JSON per il grafo delle dipendenze```json
{
"dependencies": {
"added_deps": {
"pkg:npm/express": ["pkg:npm/lodash", "pkg:npm/body-parser"]
},
"removed_deps": {},
"transitive_new": [
{
"target": "pkg:npm/underscore",
"via": ["pkg:npm/my-app", "pkg:npm/express", "pkg:npm/lodash", "pkg:npm/underscore"],
"depth": 3
}
],
"transitive_lost": [],
"depth_summary": {
"depth_1": 0,
"depth_2": 2,
"depth_3_plus": 2
}
}
}
```
## Rilevamento della Deriva
sbomlyze classifica le modifiche dei componenti in tre tipi di deriva, aiutandoti a distinguere gli aggiornamenti normali da modifiche potenzialmente sospette.
### Tipi di Deriva
| Tipo | Indicatore | Descrizione | Gravità |
|------|-----------|-------------|----------|
| **Versione** | 📦 | Numero di versione modificato | Normale |
| **Integrità** | ⚠️ | Hash modificato SENZA cambio di versione | Alta - indagare! |
| **Metadati** | 📝 | Solo i metadati (licenze, ecc.) modificati | Bassa |
### Deriva di Integrità (Segnale di Sicurezza)
La deriva di integrità si verifica quando l'hash di un componente cambia ma la sua versione rimane la stessa. Questo potrebbe indicare:
- **Attacco alla supply chain**: Il pacchetto è stato sostituito con una versione malevola
- **Ricostruzione senza incremento di versione**: Legittima ma cattiva pratica
- **Ambiente di build diverso**: Problemi di riproducibilità```bash
# Example output with integrity drift
~ suspicious-pkg ⚠️ [INTEGRITY]
hash[SHA256]: abc123 -> def456
```
**Raccomandazione**: Indagare sempre sulla deriva dell'integrità. Può essere benigna, ma è un segnale chiave per la sicurezza della supply chain.
### Output JSON per la Deriva
Il riepilogo della deriva è all'interno dell'oggetto `diff`:```json
{
"diff": {
"changed": [
{
"id": "pkg:npm/suspicious-pkg",
"name": "suspicious-pkg",
"changes": ["hash[SHA-256]: abc123 -> def456"],
"drift": {
"type": "integrity",
"hash_changes": {
"changed": {
"SHA-256": {"before": "abc123", "after": "def456"}
}
}
}
}
],
"drift_summary": {
"version_drift": 55,
"integrity_drift": 1,
"metadata_drift": 2
}
}
}
```
**Estrazione del riepilogo della deriva:**```bash
# Get drift summary
sbomlyze before.json after.json --json | jq '.diff.drift_summary'
# Check for integrity drift in CI
sbomlyze before.json after.json --json | jq -e '.diff.drift_summary.integrity_drift > 0'
```
## Rilevamento di duplicati e collisioni
### Rilevamento dei duplicati
sbomlyze identifica i componenti con la stessa identità ma versioni diverse all'interno di un SBOM:```
⚠️ Duplicates Found: 2
lodash: [4.17.20, 4.17.21]
express: [4.18.0, 4.19.2]
```
In modalità diff, il diffing delle versioni duplicate tiene traccia di:
- **Nuovi duplicati**: Componenti che sono diventati duplicati nel nuovo SBOM
- **Duplicati risolti**: Gruppi di duplicati che sono stati consolidati
- **Aggiunte/rimozioni di versioni**: Modifiche di versione all'interno di gruppi di duplicati esistenti
### Rilevamento delle collisioni
Le collisioni sono corrispondenze di identità ambigue in cui i componenti condividono lo stesso ID ma presentano caratteristiche in conflitto:
| Tipo | Descrizione |
|------|-------------|
| **Mancata corrispondenza del nome** | Nomi di componenti diversi mappati allo stesso ID di identità |
| **Mancata corrispondenza dell'hash** | La stessa versione di un componente ha hash diversi (potenziale manomissione) |
## SBOMlyze SBOM Explorer (TUI)```bash
sbomlyze sbom.json -i
```
### Scorciatoie da tastiera della TUI
#### Navigazione
| Tasto | Azione |
|-----|--------|
| `↑` / `k` | Sposta su |
| `↓` / `j` | Sposta giù |
| `PgUp` / `Ctrl+u` | Mezza pagina su |
| `PgDn` / `Ctrl+d` | Mezza pagina giù |
| `Home` / `g` | Vai all'inizio |
| `End` / `G` | Vai alla fine |
| `Enter` | Visualizza i dettagli del componente |
| `Esc` / `Backspace` | Torna indietro |
| `q` / `Ctrl+c` | Esci |
#### Ricerca e filtro
| Tasto | Azione |
|-----|--------|
| `/` | Ricerca approfondita su tutti i campi (nome, PURL, licenze, JSON grezzo) |
| `t` | Filtra per tipo di pacchetto (npm, apk, golang, pypi, ecc.) |
| `c` | Cancella tutti i filtri attivi |
#### Viste
| Tasto | Contesto | Azione |
|-----|---------|--------|
| `j` | Vista dettaglio | Visualizza il JSON grezzo del componente con evidenziazione della sintassi |
| `d` | Vista JSON | Torna alla vista dettaglio |
| `Enter` | Vista JSON | Esporta il JSON del componente su file |
| `?` | Qualsiasi vista | Mostra la guida con tutte le scorciatoie da tastiera |
### Vista dettaglio componente
La vista dettaglio mostra informazioni complete sul componente:
- Informazioni sul pacchetto (nome, versione, PURL, namespace, fornitore)
- Licenze con indicatori visivi
- Hash di integrità
- CPE (Common Platform Enumeration)
- Elenco delle dipendenze
- Identificatori (ID, BOM-ref, SPDX-ID)
## Modalità Web UI
Avvia un esploratore SBOM basato su browser con caricamento file tramite drag-and-drop:```bash
# Start web server on default port 8080
sbomlyze -web
# Start on custom port
sbomlyze -web --port 3000
```
Poi apri http://localhost:8080 nel tuo browser.
<img width="1497" height="1266" alt="Screenshot 2026-02-06 at 17 08 13" src="https://assets.kitploit.com/production/public/readmes/12637/57bcd50bc9b9955714b9078d1de37fc8152be02845a5c25b74a8fd14ff587bf4.png" />
### Funzionalità della Web UI
| Funzionalità | Descrizione |
|---------|-------------|
| **Caricamento Drag & Drop** | Trascina qualsiasi file SBOM (Syft, CycloneDX, SPDX) sulla pagina (fino a 500MB) |
| **Albero delle dipendenze** | Vista ad albero interattiva con navigazione espandi/comprimi (paginata per >5000 componenti) |
| **Dettagli del componente** | Visualizza licenze, hash, dipendenze, informazioni sul fornitore, conteggio file |
| **Vista JSON grezzo** | JSON con evidenziazione della sintassi per ogni componente |
| **Ricerca approfondita** | Cerca in tutti i campi, inclusi i dati JSON grezzi |
| **Dashboard statistiche** | Metriche di copertura, categorie di licenza, distribuzione linguaggi |
| **Browser del filesystem** | Esplora i file all'interno dell'SBOM con navigazione delle directory, ricerca e filtro per layer |
### Statistiche visualizzate
La web UI mostra statistiche complete tra cui:
---
[Read more](https://github.com/rezmoss/sbomlyze)