OreWatch

Rilevamento di Pacchetti Dannosi Multi-Ecosistema e Scanner di Sicurezza per la Supply Chain

Uno strumento di sicurezza di livello produttivo per il rilevamento di pacchetti dannosi e minacce alla supply chain negli ecosistemi npm, PyPI, Maven, RubyGems, Go e Cargo. Sfrutta la raccolta automatizzata di intelligence sulle minacce da fonti di sicurezza affidabili per identificare dipendenze compromesse nei tuoi progetti.

OreWatch è il nome del prodotto e del pacchetto PyPI. Il percorso del repository sorgente attuale utilizza ancora ore-mal-pkg-inspector.

Video

Installazione

https://github.com/rapticore/ore-mal-pkg-inspector/issues/2#issue-4215016110

OreWatch e Cursor

https://github.com/rapticore/ore-mal-pkg-inspector/issues/3#issue-4215017945

OreWatch e CodeX

https://github.com/rapticore/ore-mal-pkg-inspector/issues/4#issue-4215019385

OreWatch e Claude-Code

https://github.com/rapticore/ore-mal-pkg-inspector/issues/5#issue-4215021599

Indice

• Il Problema
• La Soluzione
• Caratteristiche Principali
• Perché OreWatch?
• Inizia Qui
• Avvio Rapido
  • Prerequisiti
  • Installazione
  • Prima Scansione
• Utilizzo
  • Comandi di Base
  • Utilizzo Avanzato
  • Riferimento della Riga di Comando
  • Monitoraggio in Background
• Guida all'Adozione
• Distribuzione
  • Distribuzione Gestita su macOS
• Registrazione e Debugging
• Output e Report
• Integrazione CI/CD
• Risoluzione dei Problemi
• FAQ
• Contribuire
• Politica di Sicurezza
• Roadmap
• Licenza
• Supporto
• Riconoscimenti

Il Problema

Gli attacchi alla supply chain sono ora il principale vettore di minaccia per il compromesso del software. Solo nel 2024, migliaia di pacchetti dannosi sono stati pubblicati su npm, PyPI e altri registry di pacchetti, prendendo di mira gli sviluppatori con typosquatting, dependency confusion e campagne malware sofisticate come Shai-Hulud.

La sfida: Organizzazioni e sviluppatori devono:

• Scansionare le dipendenze su più ecosistemi di programmazione
• Rimanere aggiornati con l'intelligence sulle minacce in rapida evoluzione da più fonti
• Rilevare non solo pacchetti dannosi noti ma anche indicatori di compromissione (IoC)
• Integrare la scansione di sicurezza nei flussi di lavoro di sviluppo esistenti
• Rispondere rapidamente alle minacce appena scoperte

Il divario: Le soluzioni esistenti sono spesso:

• Limitate a un singolo ecosistema (solo npm, solo PyPI, ecc.)
• Dipendenti dalla manutenzione manuale delle liste di minacce
• Mancanti di capacità di rilevamento degli IoC
• Difficili da integrare in pipeline automatizzate
• Strumenti proprietari a scatola nera senza trasparenza

La Soluzione

OreWatch affronta queste sfide fornendo:

Copertura Multi-Ecosistema Completa: Strumento singolo per pacchetti npm, PyPI, Maven, RubyGems, Go e Cargo

Intelligence Automatica sulle Minacce: Raccoglie e unisce dinamicamente dati da fonti di ricerca sulla sicurezza affidabili

Rilevamento Attivo degli IoC: Identifica pattern di attacco Shai-Hulud e altri indicatori di codice dannoso oltre la corrispondenza dei nomi dei pacchetti

Pronto per CI/CD: Progettato per un'integrazione senza soluzione di continuità in GitHub Actions, GitLab CI, Jenkins e altre piattaforme di automazione

Open Source e Trasparente: Visibilità completa nella logica di rilevamento, fonti di dati e metodologia di scansione

Caratteristiche Principali

Supporto Multi-Ecosistema Scansiona pacchetti npm, PyPI, Maven, RubyGems, Go e Cargo con rilevamento automatico dell'ecosistema dalla struttura del progetto.

Database Unificato di Intelligence sulle Minacce Controlla rispetto a database di pacchetti dannosi raccolti dinamicamente da fonti di ricerca sulla sicurezza affidabili.

Rilevamento Automatico dell'Ecosistema Identifica intelligentemente gli ecosistemi dalla struttura delle directory, dai nomi dei file e può scansionare più ecosistemi in un'unica esecuzione.

Rilevamento di Indicatori di Compromissione (IoC) Scansiona per pattern di attacco Shai-Hulud (varianti originali e 2.0), hook malevoli, flussi di lavoro sospetti e file payload noti.

Integrazione Shai-Hulud Confronta i pacchetti npm con l'elenco completo dei pacchetti affetti da Shai-Hulud di OreNPMGuard.

Report JSON Strutturati Genera report JSON leggibili dalle macchine con metadati espliciti sui dati delle minacce e posizioni dei file in stile SARIF per i risultati.

Formati di Input Flessibili Supporta file di dipendenze standard (package.json, requirements.txt, ecc.) e elenchi di pacchetti generici (testo, JSON, YAML).

Logging Pronto per la Produzione Livelli di verbosità configurabili con flag --verbose e --debug per risolvere problemi e tracciare audit.

Sicuro e Veloce Operazioni di sola lettura senza modifiche al codice, ottimizzato per la scansione efficiente di grandi codebase.

Perché OreWatch?

vs. Strumenti Monoeisistema La maggior parte degli scanner di sicurezza si concentra su un unico gestore di pacchetti. OreWatch fornisce protezione unificata su sei ecosistemi principali, essenziale per ambienti di sviluppo poliglotta moderni.

vs. Liste di Minacce Manuali Le liste statiche di pacchetti dannosi diventano rapidamente obsolete. I nostri raccoglitori automatizzati recuperano intelligence fresca sulle minacce quotidianamente da più fonti autorevoli.

vs. Rilevamento Solo per Nome del Pacchetto Controllare solo i nomi dei pacchetti non coglie attacchi sofisticati. Il rilevamento IoC identifica pattern di codice dannoso anche in pacchetti non ancora presenti nelle blocklist.

vs. Audit di Sicurezza Manuali Le revisioni manuali delle dipendenze richiedono tempo e sono soggette a errori. La scansione automatizzata consente la validazione continua della sicurezza in ogni build.

vs. Strumenti Commerciali a Scatola Nera Gli strumenti proprietari mancano di trasparenza nella logica di rilevamento. Come progetto open source, ogni regola di rilevamento e fonte dati è verificabile.

Storia delle Origini OreWatch è nato dallo sviluppo di OreNPMGuard, uno scanner specializzato per attacchi Shai-Hulud su npm. Durante quel progetto, abbiamo riconosciuto la necessità di una copertura multi-ecosistema più ampia oltre a npm. A dicembre 2025, abbiamo estratto e migliorato le capacità di rilevamento multi-ecosistema in questo strumento autonomo, mantenendo il focus di OreNPMGuard su npm e consentendo a OreWatch di servire la più ampia comunità di sviluppatori su tutti i principali ecosistemi di pacchetti.

Inizia Qui

Se stai adottando OreWatch per la prima volta, scegli il percorso più piccolo che si adatta al tuo flusso di lavoro:

Sequenza consigliata per la prima esecuzione per la maggior parte degli sviluppatori:

1. Installa OreWatch con pip install . o il pacchetto pubblicato.
2. Esegui orewatch monitor quickstart /path/to/project --client <tuo-client>.
3. Verifica il demone con orewatch monitor status.
4. Se sei su macOS, avvia orewatch monitor menubar per notifiche e un'interfaccia utente locale.

Se desideri una guida all'installazione più breve con comandi copia-incolla, usa docs/adoption-guide.md.

Avvio Rapido

Prerequisiti

• Python 3.14 o superiore
• pip per installare le dipendenze
• Git per clonare il repository
• Connessione Internet per la configurazione iniziale dell'intelligence sulle minacce
• OpenSSL per la generazione di chiavi di snapshot firmate, la pubblicazione e la verifica nei flussi di lavoro di monitoraggio snapshot

Installazione

OreWatch può essere installato tramite pipx (consigliato), Homebrew (macOS), pip, o dal sorgente. Tutti i metodi producono il comando CLI orewatch.

Opzione 1 — pipx (Consigliato)

pipx installa OreWatch in un ambiente isolato rendendo il comando orewatch disponibile a livello globale. Questa è l'opzione migliore per la maggior parte degli sviluppatori.```bash

Install pipx if you don't have it

python3.14 -m pip install --user pipx python3.14 -m pipx ensurepath

Install OreWatch

pipx install --python python3.14 orewatch

If you want the macOS menu bar app on a fresh install, use this instead:

pipx install --python python3.14 'orewatch[mac-menubar]'

Verify

orewatch --help

Optional macOS menu bar app

orewatch monitor menubar

Se hai già installato `orewatch` con pipx e desideri aggiungere l'app della barra dei menu di macOS in seguito, inietta i binding Cocoa nello stesso ambiente pipx:```bash
pipx inject orewatch pyobjc-framework-Cocoa

Aggiornamento:```bash pipx upgrade orewatch

**Disinstallazione:**```bash
pipx uninstall orewatch

Opzione 2 — Homebrew (macOS)

Per gli utenti macOS che preferiscono installazioni gestite tramite Homebrew:```bash

Add the OreWatch tap

brew tap rapticore/tap

Install

brew install rapticore/tap/orewatch

Verify

orewatch --help

Optional macOS menu bar app

orewatch monitor menubar

**Aggiornamento:**```bash
brew update && brew upgrade orewatch

Disinstallazione:```bash brew uninstall orewatch brew untap rapticore/tap # optional — removes the tap

> **Nota:** La formula Homebrew include i binding Cocoa richiesti da
> `orewatch monitor menubar`. Se un'installazione Homebrew più vecchia segnala
> `ModuleNotFoundError: No module named 'AppKit'`, esegui
> `brew update && brew reinstall rapticore/tap/orewatch` in modo che la formula ricostruisca
> il proprio ambiente Python isolato con il supporto della barra dei menu.

#### Option 3 — pip

Usa `pip` per pipeline CI, immagini Docker o quando gestisci i tuoi
virtualenv:```bash
# Install into an active Python 3.14 virtualenv or user site
python3.14 -m pip install orewatch

# Pin a version for reproducible CI builds
python3.14 -m pip install orewatch==1.3.0

# If you want the macOS menu bar app on a fresh install, use this instead:
# python3.14 -m pip install 'orewatch[mac-menubar]'

# Verify
orewatch --help

Aggiornamento:```bash python3.14 -m pip install --upgrade orewatch

#### Opzione 4 — Checkout del codice sorgente (Contributori)```bash
# Clone the repository
git clone https://github.com/rapticore/ore-mal-pkg-inspector.git
cd ore-mal-pkg-inspector

# Create and activate a Python 3.14 virtual environment (recommended)
python3.14 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode for development
python -m pip install -e .

# Verify
orewatch --help

Verifica post-installazione

Dopo l'installazione con qualsiasi metodo, conferma che OreWatch funzioni:```bash

Check the CLI is accessible

orewatch --help

List supported manifest filenames

orewatch --list-supported-files

Run a quick scan on the current directory

orewatch .

#### Note sulla piattaforma

| Piattaforma | Sorgente Python | Note |
|---|---|---|
| **macOS** (Homebrew Python) | `brew install [email protected]` | Consigliato per utenti Homebrew |
| **macOS** (pyenv) | `pyenv install 3.14` | Migliore per configurazioni multi-versione |
| **Ubuntu / Debian** | `sudo apt install python3.14` o pyenv | Controlla che la tua distribuzione includa la 3.14+ |
| **Fedora / RHEL** | `sudo dnf install python3.14` o pyenv | — |
| **Windows (WSL)** | pyenv o pacchetto di sistema | Windows nativo non testato |

> **Python 3.14 è richiesto.** OreWatch utilizza caratteristiche linguistiche introdotte in
> Python 3.14. Le versioni precedenti falliranno al momento dell'import.

#### Risoluzione dei problemi di installazione

| Sintomo | Rimedio |
|---|---|
| `command not found: orewatch` | Assicurati che la posizione di installazione sia nel tuo `PATH`. Per pipx: esegui `pipx ensurepath` e riavvia il terminale. |
| `ModuleNotFoundError` all'import | Potresti avere più versioni di Python. Conferma che il runtime dietro `orewatch` sia Python 3.14+ e reinstallalo con l'interprete corrispondente. |
| L'installazione con pipx fallisce con errori del resolver | Aggiorna pipx: `python3.14 -m pip install --upgrade pipx` |
| Homebrew `orewatch` non trovato dopo l'installazione | Esegui prima `brew tap rapticore/tap`, poi riprova l'installazione. |
| Permesso negato durante pip install | Usa `pip install --user orewatch` o installa all'interno di un virtualenv. |

_Nota: Se i dati locali sulle minacce sono mancanti o obsoleti, le scansioni dei pacchetti preparano un candidato per l'aggiornamento immediato e lo promuovono solo dopo che i cancelli di anomalia sono stati superati. Se il candidato appare sospetto, OreWatch mantiene attivo l'ultimo dataset noto come buono._

_CLI installato:_ `orewatch`
_Alias di compatibilità:_ `ore-mal-pkg-inspector`

### Prima scansione

**Scansiona una directory di progetto:**```bash
# Auto-detect ecosystem and scan current directory
orewatch .

# Scan specific project path
orewatch /path/to/your/project

# With verbose output to see progress
orewatch /path/to/your/project --verbose

Output previsto:``` Detected multiple ecosystems: npm, pypi Scanning all detected ecosystems...

Scanning npm... Found 2 dependency file(s) for npm Parsing: package.json Parsing: package-lock.json

Scanning pypi... Found 1 dependency file(s) for pypi Parsing: requirements.txt

Extracted 45 unique package(s) across 2 ecosystem(s)

Checking 45 package(s) against malicious databases... Checking 30 npm package(s)... Checking 15 pypi package(s)...

Scanning for Indicators of Compromise...

Generating report...

============================================================ SCAN REPORT SUMMARY

Ecosystem: npm, pypi Total Packages Scanned: 45 Malicious Packages Found: 0 IoCs Found: 0

✅ No malicious packages or IoCs detected

HTML report saved to: scan-output/malicious_packages_report_20251231_120000.html JSON report saved to: scan-output/malicious_packages_report_20251231_120000.json

Se vuoi che OreWatch continui a monitorare il progetto dopo questa prima scansione, prosegui con [Monitoraggio in background](#background-monitoring) o vai direttamente a [docs/adoption-guide.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/adoption-guide.md).

---

## Utilizzo

### Comandi di base

**Scansiona directory (Rilevamento automatico dell'ecosistema):**```bash
# Current directory
orewatch .

# Specific directory
orewatch /home/user/projects/my-app

# With an absolute path
orewatch /home/user/projects/backend-api

Scansiona file di dipendenza specifici:```bash

Ecosystem auto-detected from filename

orewatch --file package.json orewatch --file requirements.txt orewatch --file pom.xml orewatch --file Gemfile orewatch --file go.mod orewatch --file Cargo.toml

**Forza l'ecosistema specifico:**```bash
# Override auto-detection
orewatch /path/to/project --ecosystem npm
orewatch /path/to/project --ecosystem pypi
orewatch /path/to/project --ecosystem maven
orewatch /path/to/project --ecosystem rubygems
orewatch /path/to/project --ecosystem go
orewatch /path/to/project --ecosystem cargo

Scansiona elenchi di pacchetti generici:```bash

Text file (one package per line) - must specify ecosystem

orewatch --file packages.txt --ecosystem pypi

JSON file with package array

orewatch --file packages.json --ecosystem npm

YAML file

orewatch --file packages.yaml --ecosystem npm

### Uso Avanzato

**Percorso di Output Personalizzato:**```bash
# Save to custom location
orewatch /path/to/project --output /tmp/scan_report.json

# Save to specific subdirectory
orewatch /path/to/project --output reports/security/$(date +%Y%m%d).json

Controllo scansione IoC:```bash

Full scan (packages + IoCs) - default behavior

orewatch /path/to/project

Skip IoC scanning for faster package-only checks

orewatch /path/to/project --no-ioc

Only scan for IoCs, skip package database checking

orewatch /path/to/project --ioc-only

**Modalità Silenziosa:**```bash
# Generate report without console summary (useful for scripts)
orewatch /path/to/project --no-summary

Controlli dei Dati sulle Minacce:```bash

Force a staged live refresh of the default core sources before scanning

orewatch /path/to/project --latest-data

Fail if any requested ecosystem only has partial or missing threat data

orewatch /path/to/project --strict-data

Include experimental sources during collection

orewatch /path/to/project --latest-data --include-experimental-sources

Print the exact dependency filenames the scanner recognizes

orewatch --list-supported-files

**Scansione batch:**```bash
# Scan multiple projects
for dir in ~/projects/*/; do
    echo "Scanning $dir"
    orewatch "$dir" --output "reports/$(basename $dir).json"
done

Riferimento da riga di comando

Opzioni dello scanner

Monitoraggio in background

Il repository ora include un monitoraggio in background locale che mantiene aggiornati i dati sulle minacce, osserva i progetti attivi per modifiche ai manifest e ai workflow, esegue scansioni con debounce e registra notifiche per nuovi risultati o risultati aumentati. La configurazione e lo stato di proprietà del monitor sono archiviati al di fuori del repository in directory di proprietà dell'utente, in modo che un repository clonato non possa preimpostare il comportamento del monitor.

OreWatch ora tratta il monitor come un singleton per utente. Un demone può osservare molti progetti ovunque sul disco e servire molti client concorrenti Claude Code, Codex, Cursor, VS Code, JetBrains / PyCharm e Xcode.

Configurazione end-to-end del monitor

1. Installa e avvia il monitor singleton```bash

First project + first client

orewatch monitor quickstart /path/to/project --client claude_code

`monitor quickstart` è il flusso consigliato per la prima esecuzione. Esso:

- installa o aggiorna il servizio monitor singleton
- avvia il monitor se necessario
- aggiunge il progetto di destinazione alla watch list
- stampa il blocco di bootstrap per il client selezionato

Se preferisci installare prima il monitor e collegare i client in seguito:```bash
orewatch monitor install
orewatch monitor install --ide-bootstrap
orewatch monitor install --service-manager launchd --no-start

2. Verifica che il monitor sia sano```bash orewatch monitor status orewatch monitor connection-info orewatch monitor doctor

Utilizza questi comandi per compiti leggermente diversi:

- `monitor status` mostra se il demone singleton e l'API sono in esecuzione
- `monitor connection-info` stampa l'URL API di loopback, il percorso del token, la home del monitor e i client bootstrap supportati
- `monitor doctor` stampa i percorsi esatti di config, database di stato, log e dati di minacce condivise

**3. Aggiungi ogni progetto che vuoi che il singleton osservi**```bash
orewatch monitor watch add /path/to/project-a
orewatch monitor watch add /path/to/project-b
orewatch monitor watch list
orewatch monitor watch remove /path/to/project-b

Un singolo demone OreWatch può monitorare tutti questi progetti contemporaneamente. Non è necessario un monitor separato per repository o per spazio di lavoro IDE.

Ricette di Integrazione Client

OreWatch supporta due trasporti di integrazione:

I comandi di bootstrap stampano una di queste forme:```json { "mcpServers": { "orewatch": { "command": "/absolute/path/to/orewatch", "args": [ "monitor", "mcp" ] } } }

Quando `orewatch monitor ide-bootstrap --client <client>` riesce a risolvere lo script della console locale, ora emette quel percorso assoluto invece di `orewatch` nudo. Se hai una configurazione MCP più vecchia che dice ancora `"command": "orewatch"`, rigenerala e sostituisci la vecchia voce.```json
{
  "orewatch": {
    "baseUrl": "http://127.0.0.1:48736",
    "tokenPath": "/path/to/api.token"
  }
}

Cursor, Claude Code e Codex

Questi client utilizzano tutti lo stesso bridge MCP locale:```bash orewatch monitor mcp

Setup consigliato:

1. Esegui `orewatch monitor quickstart /path/to/project --client <cursor|claude_code|codex>` una volta.
2. Copia il blocco MCP stampato nel client MCP corrispondente.
3. Apri un progetto monitorato in quel client.
4. Lascia che il client chiami OreWatch tramite MCP per:
   - `orewatch_health`
   - `orewatch_check_dependency_add`
   - `orewatch_check_manifest`
   - `orewatch_override_dependency_add`
   - `orewatch_list_active_findings`
   - `orewatch_list_notifications`

Note:

- `monitor mcp` è un server stdio. Se lo avvii manualmente, apparirà inattivo in attesa di un client MCP.
- Il bridge MCP controlla l'API locale all'avvio e può avviare automaticamente il monitor singleton una volta quando `auto_start_on_client` è abilitato.
- Per un avvio affidabile dell'IDE, installa il monitor in background una volta con `monitor install` in modo che il demone sia già disponibile prima che il bridge MCP si avvii.

##### VS Code

Le integrazioni con VS Code dovrebbero usare l'API localhost singleton piuttosto che il bridge MCP.

Setup consigliato:

1. Esegui `orewatch monitor quickstart /path/to/project --client vscode`.
2. Copia `baseUrl` e `tokenPath` da `orewatch monitor ide-bootstrap --client vscode`.
3. Collega quei valori alla tua estensione VS Code locale, task o helper.
4. Chiama l'API sugli eventi di dependency-add, manifest-save e alert-refresh.

Utilizzo consigliato dell'API per un'integrazione VS Code:

- chiama `POST /v1/check/dependency-add` prima dei flussi di installazione/aggiunta del gestore pacchetti
- chiama `POST /v1/check/manifest` quando un manifest supportato viene salvato o esplicitamente ricontrollato
- interroga `GET /v1/findings/active` e `GET /v1/notifications` per visualizzare rilevamenti in background

##### JetBrains / PyCharm

JetBrains e PyCharm utilizzano lo stesso contratto API localhost di VS Code.

Setup consigliato:

1. Esegui `orewatch monitor quickstart /path/to/project --client jetbrains`.
2. Copia il blocco API da `orewatch monitor ide-bootstrap --client jetbrains`.
3. Usa `baseUrl` e `tokenPath` restituiti in un plugin JetBrains, strumento esterno o helper locale.
4. Visualizza sia le decisioni sincrone sulle dipendenze che gli avvisi in background memorizzati all'interno dell'IDE.

Utilizzo consigliato dell'API per un'integrazione JetBrains:

- controlla le aggiunte di dipendenze con `POST /v1/check/dependency-add`
- ricontrolla `package.json`, `requirements.txt`, `pyproject.toml`, `pom.xml`, `Gemfile`, `go.mod`, `Cargo.toml` e altri manifest supportati con `POST /v1/check/manifest`
- recupera `GET /v1/findings/active` e `GET /v1/notifications` per pannelli di avviso persistenti o finestre degli strumenti

##### Xcode

Le integrazioni con Xcode dovrebbero anche utilizzare l'API localhost singleton, ma c'è un importante limite di ambito: OreWatch non analizza ancora i manifest di dipendenza nativi Apple come `Package.resolved`, `Podfile.lock` o `Cartfile`. Oggi, l'integrazione con Xcode è migliore per:

- mostrare rilevamenti e notifiche in background in un helper, script o app companion
- repository con linguaggi misti aperti in Xcode che contengono anche manifest supportati come `package.json`, `pyproject.toml` o `Cargo.toml`
- team che desiderano l'app della barra dei menu macOS e gli avvisi del Centro Notifiche mentre lavorano in Xcode

Setup consigliato:

1. Esegui `orewatch monitor quickstart /path/to/project --client xcode`.
2. Copia il blocco API da `orewatch monitor ide-bootstrap --client xcode`.
3. Usa `baseUrl` e `tokenPath` restituiti da uno script di fase di build, un processo helper o un'integrazione Xcode personalizzata.
4. Interroga `GET /v1/findings/active` e `GET /v1/notifications` per avvisi visibili all'utente.
5. Se il workspace Xcode contiene manifest non Apple supportati, chiama `POST /v1/check/manifest` per quei file come parte del tuo flusso di lavoro.

Stato attuale dell'integrazione:

- Claude Code, Codex e Cursor: bridge MCP di prima classe incluso in questo repository
- VS Code: contratto API locale documentato, ma nessuna estensione first-party inclusa ancora
- JetBrains / PyCharm: contratto API locale documentato, ma nessun plugin first-party incluso ancora
- Xcode: API locale e integrazione nella barra dei menu documentate, ma nessuna estensione Xcode first-party e nessun parser di manifest nativi Apple ancora

#### Quando OreWatch Trova Qualcosa

Quando il monitor in background rileva un pacchetto compromesso o un IoC in un progetto monitorato, OreWatch:

- scrive report JSON e HTML gestiti dal monitor nella directory `reports/` del monitor singleton
- memorizza il rilevamento attivo nel DB di stato del monitor
- memorizza una voce di notifica con un messaggio azionabile
- emette un avviso nel terminale se le notifiche terminale sono abilitate
- su macOS, preferisce l'app della barra dei menu singleton come canale popup quando è in esecuzione
- mantiene l'avviso più recente degno di attenzione bloccato in cima al menu a discesa della barra dei menu per una rapida revisione
- altrimenti ricade su una notifica desktop diretta best-effort se le notifiche desktop sono abilitate
- può inviare una notifica webhook opzionale per ambienti remoti o headless

Usa la superficie di revisione CLI integrata per ispezionare quegli avvisi:```bash
orewatch monitor findings
orewatch monitor findings --project /path/to/project --min-severity high
orewatch monitor notifications
orewatch monitor notifications --project /path/to/project
orewatch monitor package-updates
orewatch monitor package-updates --check

L'API locale e il bridge MCP espongono gli stessi dati per IDE e agenti:

• API:
  • GET /v1/findings/active
  • GET /v1/notifications
  • GET /v1/package-updates
  • POST /v1/package-updates/check
• MCP:
  • orewatch_list_active_findings
  • orewatch_list_notifications
  • orewatch_list_package_updates
  • orewatch_check_package_updates

Questo è il percorso supportato per IDE, client MCP e agenti di codifica per mostrare le rilevazioni in background dopo che la scansione originale è terminata.

Gli avvisi di aggiornamento dei pacchetti sono solo notifiche. OreWatch segnala versioni più recenti per le dipendenze dei progetti monitorati e per OreWatch stesso, ma non modifica manifest, lockfile o pacchetti installati.

App nativa per la barra dei menu di macOS

OreWatch ora include un'app nativa per la barra dei menu di macOS per chi desidera un'interfaccia utente locale visibile invece di affidarsi solo a comandi CLI, polling MCP o popup del Centro Notifiche a discrezione del sistema.

Installa i binding Cocoa opzionali nello stesso runtime che fornisce il comando orewatch. Scegli il comando che corrisponde al tuo metodo di installazione:```bash

pip / source-checkout install

python3.14 -m pip install 'orewatch[mac-menubar]'

existing pipx install

pipx inject orewatch pyobjc-framework-Cocoa

Homebrew install

brew install rapticore/tap/orewatch

Poi avvia l'app della barra dei menu:```bash
orewatch monitor menubar

Per impostazione predefinita, monitor menubar riavvia l'app in background e restituisce immediatamente il prompt della shell. Usa orewatch monitor menubar --foreground solo quando vuoi esplicitamente mantenerlo collegato al terminale per il debug.

L'app della barra dei menu si collega allo stesso monitor singleton. Non avvia una seconda istanza del monitor. Se il monitor non è già installato e in esecuzione, l'app lo installerà/avvierà al primo avvio.

Homebrew installa i binding Cocoa nell'ambiente isolato libexec di OreWatch. Se orewatch monitor menubar segnala No module named 'AppKit', aggiorna la formula con brew update && brew reinstall rapticore/tap/orewatch. Per le installazioni pip, pipx e da sorgente, i binding opzionali devono comunque essere aggiunti allo stesso ambiente Python che fornisce il comando orewatch.

Quando le notifiche desktop sono abilitate su macOS, il watcher singleton mantiene ora attiva un'app singleton della barra dei menu e la utilizza come superficie principale per i popup. Ciò evita di fare affidamento solo su un'invocazione osascript staccata dal demone e ti fornisce un'interfaccia nativa persistente per i nuovi risultati.

L'attuale build della barra dei menu è orientata alle icone. La vecchia abbreviazione OW e la precedente dicitura dell'icona di OreWatch devono essere considerate come riferimenti legacy; l'app ora preferisce l'icona brandizzata inclusa e ricorre solo a testo compatto o badge quando macOS non riesce a renderizzare l'immagine o ha bisogno di un conteggio di avvisi.

Cosa ti offre l'app della barra dei menu su macOS:

• un elemento di stato persistente nella barra dei menu che preferisce l'icona brandizzata inclusa, con fallback a testo compatto o badge di avviso quando necessario
• uno stato di avviso compatto in rosso/grassetto per gli avvisi appena rilevati che rimane visibile fino all'apertura del menu
• un riepilogo in tempo reale dei risultati attivi e della gravità più alta
• una sezione di aggiornamenti dei pacchetti di prima classe con aggiornamenti delle dipendenze del progetto, stato di auto-aggiornamento di OreWatch, stato dell'ultimo controllo e comandi suggeriti copiabili
• notifiche recenti in un menu a discesa nativo
• popup nativi del Centro Notifiche per gli avvisi del monitor appena memorizzati
• un'azione Add Workspace Folder... che inserisce un progetto nel watcher singleton ed esegue una scansione rapida iniziale
• interruttori di configurazione integrati per notifiche desktop, notifiche terminale, keepalive della barra dei menu e popup guidati dalla barra dei menu
• azioni con un clic per aprire report, home del monitor e log del monitor
• azioni con un clic per aprire il file di configurazione del monitor e la cartella di configurazione
• azioni di menu per controllare gli aggiornamenti dei pacchetti, aggiornare le informazioni sulle minacce, eseguire scansioni rapide/complete e avviare/riavviare/fermare il monitor singleton

Flusso consigliato per Mac:

1. Esegui orewatch monitor quickstart /path/to/project --client claude_code una volta.
2. Installa i binding opzionali nello stesso ambiente di orewatch.
3. Avvia orewatch monitor menubar.
4. Mantieni attiva l'app della barra dei menu per una superficie di revisione nativa persistente mentre i tuoi IDE e agenti di codifica continuano a usare MCP o l'API locale.

Guida all'adozione

Per un'implementazione più semplice, usa la documentazione mirata invece di leggere il README completo dall'inizio alla fine:

• docs/adoption-guide.md: percorso più breve per l'adozione da parte degli sviluppatori locali
• docs/local-api.md: contratto esatto dell'API localhost e MCP
• docs/e2e-testing.md: flusso di lavoro per contributori e validazione

Ordine di adozione consigliato:

1. Inizia con un repository e un utente.
2. Abilita il monitor singleton con monitor quickstart.
3. Collega un client: Cursor, Claude Code, Codex, VS Code, PyCharm o Xcode.
4. Conferma che i risultati appaiano in orewatch monitor findings e orewatch monitor notifications.
5. Su macOS, aggiungi monitor menubar in modo che gli utenti ottengano una superficie di revisione persistente e la consegna dei popup.
6. Dopo che l'adozione locale è stabile, aggiungi scansioni CI e webhook opzionali.

Operazioni quotidiane

Comandi operativi comuni:```bash

Background service lifecycle

orewatch monitor start orewatch monitor restart orewatch monitor stop orewatch monitor uninstall

Run the daemon in the foreground

orewatch monitor run

Launch the native macOS menu bar UI

orewatch monitor menubar

Trigger immediate scans

orewatch monitor scan-now orewatch monitor scan-now /path/to/project

Review detections and alerts

orewatch monitor findings orewatch monitor notifications

Reclaim disk space — prune accumulated backup manifests and orphaned staging

orewatch monitor cleanup orewatch monitor cleanup --keep-backups 5 --staging-max-age-seconds 3600

**Snapshot manuale e azioni di firma:**```bash
# Generate a signing keypair
orewatch monitor snapshot keygen /tmp/ore-keys

# Build and apply local threat-data snapshots
orewatch monitor snapshot build /tmp/ore-snapshot \
  --private-key /tmp/ore-keys/snapshot_signing_private.pem \
  --public-key /tmp/ore-keys/snapshot_signing_public.pem
orewatch monitor snapshot apply /tmp/ore-snapshot/manifest.json \
  --public-key /tmp/ore-keys/snapshot_signing_public.pem

# Publish a hosted snapshot channel
orewatch monitor snapshot publish /tmp/ore-snapshots \
  --base-url https://example.com/ore-snapshots \
  --channel stable \
  --private-key /tmp/ore-keys/snapshot_signing_private.pem \
  --public-key /tmp/ore-keys/snapshot_signing_public.pem

Comportamento del monitor:

• Le scansioni rapide sono focalizzate sui pacchetti e vengono eseguite secondo una pianificazione e dopo modifiche generiche ai manifest.
• Le scansioni complete includono il rilevamento di IoC e vengono eseguite ogni notte, su richiesta manuale e dopo modifiche ai workflow o ai file dei payload.
• Su Linux, la configurazione predefinita è ~/.config/orewatch/singleton/ e lo stato predefinito è ~/.local/state/orewatch/singleton/.
• Su macOS, la configurazione predefinita è ~/Library/Application Support/OreWatch/singleton/ e lo stato predefinito è ~/Library/Application Support/OreWatch/State/singleton/.
• I dati di minaccia condivisi ora risiedono nella directory dello stato singleton in threat-data/final-data/.
• monitor doctor stampa esattamente il config_path, state_db, log_file, final_data_dir e la directory del template di servizio per il monitor singleton.
• Le sovrascritture delle policy per progetto possono essere memorizzate in nella root del progetto.

Superficie di integrazione locale:

• OreWatch ora espone un'API solo su localhost su 127.0.0.1:48736 per impostazione predefinita quando il demone del monitor è in esecuzione.
• L'API utilizza un token bearer per utente memorizzato nella directory di configurazione del monitor in api.token con permessi di solo proprietario.
• Le richieste dirette a 127.0.0.1:48736 senza Authorization: Bearer <token> restituiranno correttamente 401 Unauthorized.
• I client agente e IDE dovrebbero scoprire il monitor tramite orewatch monitor connection-info invece di indovinare i percorsi, e dovrebbero inviare l'actual project_path su cui stanno operando all'interno delle richieste di controllo delle dipendenze.
• Claude Code, Codex e Cursor possono utilizzare il bridge MPC integrato, che espone orewatch_health, orewatch_check_dependency_add, orewatch_check_manifest, orewatch_override_dependency_add, , , e .

Configurazione opzionale degli aggiornamenti live con controllo anomalie:```yaml live_updates: enabled: true mode: gated bootstrap_from_live: true block_on_core_source_failure: false max_drop_ratio: 0.40 max_drop_absolute: 200 max_removal_ratio: 0.25 max_removal_absolute: 100 warn_growth_ratio: 5.0 warn_growth_absolute: 2000

Comportamento chiave:
- I candidati live vengono costruiti prima in un'area di staging; non sovrascrivono i database attivi durante la raccolta.
- Grandi cali, regressioni dell'ecosistema, ecosistemi vuoti e rimozioni di massa bloccano la promozione.
- Le interruzioni delle fonti principali sono solo avvisi per impostazione predefinita per gli aggiornamenti live open-source; i cali e le rimozioni a livello di ecosistema bloccano comunque le promozioni errate.
- Le anomalie di solo avviso vengono registrate nello stato e nei report ma non impediscono la promozione.
- I candidati rifiutati mantengono attivo l'ultimo dataset noto come valido quando già esiste.
- Il bootstrap iniziale dai feed live è consentito se almeno una fonte principale ha successo e il candidato produce dati di ecosistema utilizzabili.

**Configurazione opzionale del webhook di notifica:**```yaml
notifications:
  desktop: true
  terminal: true
  webhook_url: https://hooks.example.com/orewatch
  webhook_format: generic
  webhook_timeout_ms: 5000
  webhook_headers:
    Authorization: Bearer change-me

Imposta webhook_format: slack quando si utilizza un webhook in entrata di Slack. In quella modalità, OreWatch invia un semplice payload text.

Distribuzione

Il progetto ora ha due superfici di distribuzione distinte:

1. Il codice CLI e il monitor
2. Gli snapshot dei dati di minaccia consumati dal monitor

Dovrebbero essere distribuiti separatamente.

Distribuzione del pacchetto consigliata

Migliore impostazione predefinita per sviluppatori: pubblicare lo scanner come un normale pacchetto Python su PyPI e consigliare l'installazione con pipx.

Perché è la scelta migliore:

• Il progetto è un CLI Python e un monitor in background, quindi una wheel universale più una distribuzione sorgente è l'artefatto di rilascio più diretto.
• pipx offre agli sviluppatori un'installazione isolata a livello utente senza inquinare i virtualenv del progetto.
• La CI può comunque installare la stessa versione con python3.14 -m pip install orewatch==<version>.
• Questo mantiene semplice il percorso di aggiornamento del CLI, lasciando gli aggiornamenti dei dati di minaccia al canale di snapshot firmati.

Forma di rilascio consigliata:

• Pubblicare gli artefatti sdist e wheel universale su PyPI.
• Esporre il punto di ingresso della console orewatch.
• Mantenere ore-mal-pkg-inspector come alias di compatibilità temporaneo.
• Documentare pipx install --python python3.14 orewatch per installazioni locali degli sviluppatori.
• Documentare python3.14 -m pip install orewatch==<version> per CI e automazione vincolata.

Canale secondario disponibile: il tap Homebrew è ora attivo per gli utenti macOS che preferiscono installazioni gestite da Brew:```bash brew install rapticore/tap/orewatch

Homebrew rimane un livello di convenienza sopra il rilascio pubblicato su PyPI, non l'artefatto di rilascio principale.

**Opzione migliore per i contributori:** mantenere il flusso corrente di checkout del codice sorgente:```bash
git clone https://github.com/rapticore/ore-mal-pkg-inspector.git
cd ore-mal-pkg-inspector
python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

Implementazione gestita di macOS

Se stai distribuendo OreWatch con Kandji, Jamf Pro, Intune, Munki o un altro sistema di distribuzione software per macOS, il modello consigliato è diverso dal percorso dello sviluppatore con pipx.

Realtà attuale del prodotto:

• oggi il repository fornisce un pacchetto Python, non un pacchetto di installazione macOS notarizzato di prima parte
• per i parchi gestiti, l'artefatto consigliato è un .pkg flat firmato costruito attorno al wheel pubblicato di OreWatch
• gli snapshot dei dati sulle minacce dovrebbero comunque essere distribuiti separatamente dal pacchetto dell'app/runtime

Modello di rollout enterprise consigliato:

1. Installazione del dispositivo
   • distribuisci un .pkg firmato che installi il runtime di OreWatch e uno shim CLI orewatch stabile
   • includi opzionalmente l'extra mac-menubar se desideri l'app nativa della barra dei menu sui Mac gestiti
2. Attivazione dell'utente
   • esegui orewatch monitor quickstart /path/to/project --client <client> o un bootstrap equivalente nel contesto utente
   • questo passaggio è separato perché il monitor di OreWatch è intenzionalmente per-utente e utilizza un LaunchAgent utente più configurazione/token/stato di proprietà dell'utente
3. Aggiornamenti continui
   • aggiorna il pacchetto runtime secondo il tuo normale ciclo di vita del software
   • aggiorna gli snapshot dei dati sulle minacce indipendentemente tramite il canale di snapshot firmato o il percorso di aggiornamento live

Perché questa suddivisione è importante:

• gli strumenti MDM sono bravi a installare codice sulla macchina
• il monitor di OreWatch, il token API e il servizio launchd sono con ambito utente, quindi dovrebbero essere creati nel contesto dell'utente connesso piuttosto che forzati da un'installazione di pacchetto con ambito macchina

Forma consigliata del pacchetto per macOS gestito:

• un runtime dedicato in un percorso stabile come /Library/Application Support/OreWatch/runtime
• uno shim stabile come /usr/local/bin/orewatch
• metadati del pacchetto con versione in modo che le piattaforme MDM possano rilevare pulitamente gli aggiornamenti
• firma del codice e notarizzazione dove la tua politica del parco lo richiede

Guida specifica per fornitore:

• Kandji
  • usa un'App Personalizzata con un Pacchetto Installer (.pkg)
  • preferisci .pkg a .dmg o .zip per OreWatch perché il runtime non è un'app drag-and-drop
  • usa Self Service o un passaggio di onboarding rivolto all'utente per l'attivazione iniziale del monitor
• Jamf Pro
  • carica il .pkg come Pacchetto e distribuiscilo con una Policy o Self Service
  • mantieni l'attivazione utente separata dalla distribuzione del pacchetto macchina a meno che tu non abbia un passaggio di bootstrap deliberato nel contesto utente
• Microsoft Intune
  • usa un'app LOB macOS con un .pkg firmato
  • Intune è più severo degli altri canali: si aspetta un vero .pkg, firmato con un certificato Developer ID Installer, e il pacchetto deve contenere un payload
• Munki
  • pubblica il .pkg più i metadati del pacchetto e tratta OreWatch come qualsiasi altro software macOS gestito
  • Munki è una buona scelta quando vuoi un repository di pacchetti e un'adozione opzionale in stile Self Service

Per un playbook di rollout più completo, vedi docs/managed-rollout.md.

Distribuzione consigliata degli snapshot

Gli snapshot dei dati sulle minacce non dovrebbero essere inclusi all'interno del pacchetto Python. Cambiano con una cadenza diversa e sono già supportati come artefatti firmati ospitati.

Predefinito open-source/community: consuma openssf e osv direttamente tramite il percorso di aggiornamento live con gate di anomalie. Predefinito enterprise: pubblica snapshot firmati con versione su hosting HTTPS statico e lascia che i client li aggiornino indipendentemente.

Destinazioni di hosting consigliate:

• Asset di GitHub Releases
• S3 o Cloudflare R2 dietro HTTPS
• Qualsiasi bucket statico basato su CDN che serva file immutabili con versione

Struttura consigliata degli snapshot:

• versions/<version>/manifest.json
• versions/<version>/*.db
• channels/stable.json

Modello di fiducia consigliato:

• Mantieni la chiave privata di firma offline
• Fornisci solo la chiave pubblica di verifica con la configurazione o il pacchetto client
• Verifica ogni descrittore di canale e manifest prima del download/applicazione

Modello generale consigliato

Per un rilascio in produzione, la configurazione più pulita è:

• Distribuire l'applicazione come pacchetto PyPI
• Installare localmente con pipx
• Installare in CI con pip
• Distribuire i dati sulle minacce come canali di snapshot firmati su HTTPS
• Considerare il checkout del sorgente come un percorso di sviluppo, non l'installazione principale per l'utente finale

Logging e Debugging

Per impostazione predefinita, lo scanner mostra solo avvisi, errori e il riepilogo finale. Per la risoluzione dei problemi o il monitoraggio dettagliato dei progressi, usa i flag di logging:

Modalità Verbosa

Visualizza messaggi di progresso e statistiche di raccolta:```bash orewatch /path/to/project --verbose

**L'output include:**
- Risultati del rilevamento dell'ecosistema
- Avanzamento dell'analisi dei file
- Conteggi dell'estrazione dei pacchetti
- Dettagli delle query del database
- Avanzamento della scansione degli IoC

**Esempio:**```
INFO: Detected ecosystems: npm, pypi
INFO: Loaded database for npm: 15234 malicious packages
INFO: Loaded database for pypi: 8421 malicious packages
INFO: Extracted 45 packages from 3 files
INFO: Checking 30 npm packages against database...
INFO: Checking 15 pypi packages against database...
INFO: IoC scan complete: 0 indicators found

Modalità Debug

Vedi informazioni diagnostiche dettagliate per la risoluzione dei problemi:```bash orewatch /path/to/project --debug

**L'output include:**
- Tutti i messaggi di livello INFO
- Percorsi dei file scansionati
- Dettagli di esecuzione delle query SQL
- Calcoli hash
- Risultati del pattern matching
- Informazioni sullo stato interno

**Casi d'uso:**
- Indagare perché un pacchetto non è stato rilevato
- Debug di problemi di auto-rilevamento dell'ecosistema
- Segnalare problemi con contesto dettagliato
- Verificare il comportamento dello scanner

### Registrazione per i Collector

I collector di threat intelligence supportano anche le modalità verbose e debug:```bash
cd collectors

# See collection progress
python3 orchestrator.py --verbose

# Debug data source issues
python3 orchestrator.py --debug

Nota: Tutti i log vanno su stderr, mantenendo stdout pulito per l'output del report JSON. Ciò consente di reindirizzare i risultati dello scanner ad altri strumenti senza interferenze di messaggi di log.

Output e Report

Struttura del Report

I report vengono salvati nella directory scan-output/ per impostazione predefinita (o in un percorso personalizzato con --output). OreWatch scrive un report JSON leggibile dalla macchina e un report HTML stilizzato come companion con lo stesso nome base. L'artefatto JSON include metadati sulla disponibilità dei dati di minaccia e utilizza oggetti physicalLocation in stile SARIF per i risultati dei pacchetti, ma non è un documento SARIF 2.1.0 completo.

Esempio di report:```json { "scan_timestamp": "2025-12-31T12:00:00Z", "ecosystem": "npm", "scanned_path": "/path/to/project", "total_packages_scanned": 150, "data_status": "complete", "sources_used": ["openssf", "osv"], "experimental_sources_used": [], "missing_ecosystems": [], "malicious_packages_found": 2, "iocs_found": 3, "malicious_packages": [ { "name": "malicious-pkg", "version": "1.0.0", "severity": "critical", "sources": ["threat-intel-db", "research-community"], "description": "Malicious code executes unauthorized operations", "detected_behaviors": ["malicious_code", "data_exfiltration"] } ], "iocs": [ { "type": "malicious_bundle_js", "path": "node_modules/suspect-pkg/bundle.js", "hash": "46faab8ab153fae6e80e7cca38eab363075bb524edd79e42269217a083628f09", "severity": "CRITICAL", "variant": "original", "description": "Known malicious payload file from Shai-Hulud attack" }, { "type": "malicious_postinstall", "path": "package.json", "pattern": "node bundle.js", "severity": "CRITICAL", "variant": "original", "description": "Malicious postinstall hook executes payload" } ] }

**Campi dei dati sulle minacce:**
- `data_status`: `complete`, `partial`, `failed` o `not_applicable`
- `sources_used`: sorgenti che hanno contribuito con dati sulle minacce utilizzabili per gli ecosistemi richiesti
- `experimental_sources_used`: sorgenti sperimentali incluse nei dati di scansione
- `missing_ecosystems`: ecosistemi richiesti che non avevano un database utilizzabile di minacce sui pacchetti
- `promotion_decision`: vuoto per scansioni di dati esistenti, altrimenti `promoted`, `bootstrapped` o `rejected`
- `kept_last_known_good`: `true` quando un candidato live è stato rifiutato ma il precedente dataset attivo è rimasto utilizzabile
- `anomalies`: anomalie di avviso/blocco sollevate durante un tentativo di aggiornamento live

### Interpretazione dei risultati

**Livelli di gravità:**
- **CRITICAL:** Codice malevolo noto con exploit attivi o esfiltrazione di dati
- **HIGH:** Forti indicatori di intento malevolo o typosquatting
- **MEDIUM:** Pattern sospetti o potenziali vulnerabilità
- **LOW:** Preoccupazioni minori o risultati informativi

**Azioni consigliate:**
1. **Risultati Critici/Alti:** Rimuovere immediatamente i pacchetti interessati e indagare sull'impatto
2. **Revisionare gli IoC:** Verificare se il codice malevolo è stato eseguito (log, attività di rete)
3. **Aggiornare le dipendenze:** Sostituire i pacchetti malevoli con alternative legittime
4. **Scansionare di nuovo:** Verificare la correzione con una scansione successiva
5. **Segnalare:** Considerare la segnalazione ai manutentori del registro dei pacchetti

---

## Integrazione CI/CD

### GitHub Actions

**Scansione di sicurezza di base:**```yaml
name: Security Scan - Malicious Packages
on: [push, pull_request]

jobs:
  malicious-package-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.14'

      - name: Install OreWatch
        run: |
          git clone https://github.com/rapticore/ore-mal-pkg-inspector.git scanner
          cd scanner
          pip install .

      - name: Scan for malicious packages
        run: |
          cd scanner
          orewatch ${{ github.workspace }} --latest-data

      - name: Upload scan report
        uses: actions/upload-artifact@v4
        if: always()
        with:
          name: security-scan-report
          path: scanner/scan-output/

Avanzato con Fallimento sulla Rilevazione:```yaml - name: Scan and fail on malicious packages run: | cd scanner orewatch ${{ github.workspace }} --latest-data --output report.json

      # Check if malicious packages were found
      MALICIOUS_COUNT=$(jq '.malicious_packages_found' report.json)
      IOC_COUNT=$(jq '.iocs_found' report.json)

      if [ "$MALICIOUS_COUNT" -gt 0 ] || [ "$IOC_COUNT" -gt 0 ]; then
        echo "🚨 SECURITY ALERT: Malicious packages or IoCs detected!"
        echo "Malicious packages: $MALICIOUS_COUNT"
        echo "IoCs found: $IOC_COUNT"
        exit 1
      fi

### GitLab CI```yaml
malicious-package-scan:
  image: python:3.14
  stage: security
  before_script:
    - git clone https://github.com/rapticore/ore-mal-pkg-inspector.git scanner
    - cd scanner && pip install .
  script:
    - orewatch $CI_PROJECT_DIR --latest-data --strict-data --output scan-report.json
  artifacts:
    paths:
      - scan-report.json
    when: always
  allow_failure: false

Jenkins Pipeline```groovy

pipeline { agent any

stages {
    stage('Setup Scanner') {
        steps {
            sh '''
                git clone https://github.com/rapticore/ore-mal-pkg-inspector.git scanner
                cd scanner
                python3.14 -m pip install .
            '''
        }
    }

    stage('Security Scan') {
        steps {
            sh '''
                cd scanner
                orewatch ${WORKSPACE} --latest-data
            '''
        }
    }
}

post {
    always {
        archiveArtifacts artifacts: 'scanner/scan-output/*.json', fingerprint: true
    }
}

}

### Hook di pre-commit

Aggiungi a `.git/hooks/pre-commit`:```bash
#!/bin/bash

echo "Running malicious package scan..."

cd /path/to/ore-mal-pkg-inspector
orewatch $PROJECT_DIR --no-summary

if [ $? -ne 0 ]; then
    echo "❌ Malicious packages or IoCs detected! Commit blocked."
    echo "Review the scan report in scan-output/"
    exit 1
fi

echo "✅ Security scan passed"

Risoluzione dei problemi

Problemi comuni

Errore "Database non trovato"

Sintomo:``` ERROR: No usable threat data available for requested ecosystems: npm

**Causa:** Raccolta dei dati sulle minacce fallita, metadati incompleti o gli ecosistemi richiesti non hanno ancora database locali utilizzabili.

**Soluzione:**```bash
# Force recollection and require a complete result for the requested ecosystems
orewatch /path/to/project --latest-data --strict-data

Nota: Se persiste, controlla la connettività di rete, i permessi del file system e se hai richiesto intenzionalmente sorgenti sperimentali.

"Nessun pacchetto rilevato" Avviso

Sintomo:``` WARNING: No packages detected in /path/to/project

**Possibili cause e soluzioni:**

1. **Directory sbagliata:** Assicurati di eseguire la scansione della directory del progetto corretta   ```bash
   ls /path/to/project  # Verify package.json or requirements.txt exists

2. Manifesto non supportato o imprevisto: Stampa i nomi esatti dei file supportati ```bash orewatch --list-supported-files
   root@kitploit:~

3. Autorizzazioni file: Assicurati che i file siano leggibili ```bash ls -la /path/to/project/package.json
   root@kitploit:~

Errori di connessione durante l'aggiornamento

Sintomo:``` ERROR: Error downloading npm: <urlopen error [Errno -3] Temporary failure in name resolution>

**Soluzioni:**

1. **Controlla la connessione internet:**   ```bash
   ping google.com

2. Riprova con aumento del timeout: Modifica collectors/config.yaml: ```yaml osv: timeout: 600 # Increase from default 300
   root@kitploit:~

3. Use cached data: Se hai precedentemente scaricato dati: ```bash python3 orchestrator.py --skip-build # Skip download, rebuild from cache
   root@kitploit:~

Errori di Autorizzazione Negata

Sintomo:``` ERROR: Error creating directory collectors/raw-data: Permission denied

**Soluzione:**```bash
# Ensure proper ownership
sudo chown -R $USER:$USER /path/to/ore-mal-pkg-inspector

# Or run from user-writable location
cd ~/
git clone https://github.com/rapticore/ore-mal-pkg-inspector.git
cd ore-mal-pkg-inspector

OreWatch sta usando troppo spazio su disco

Sintomo: ~/Library/Application Support/OreWatch (macOS) o $XDG_STATE_HOME/orewatch (Linux) è cresciuto fino a decine di gigabyte.

Causa (pre-1.2.3): Ogni promozione di aggiornamento in tempo reale archiviava una copia completa dei database dei dati sulle minacce precedenti (~300 MB) senza conservazione. Un monitor eseguito per molto tempo accumulava uno snapshot per ciclo indefinitamente.

Soluzione: Aggiornare alla versione 1.2.3 o successiva. I backup ora sono manifesti SHA-256 di ~1 KB, la conservazione predefinita è limitata agli ultimi 30, ed è disponibile un comando esplicito di pulizia:```bash

Apply the configured retention policy now (default: keep 30 manifests,

remove staging entries older than 1 hour).

orewatch monitor cleanup

Reclaim everything except the most recent 5 backups and purge staging.

orewatch monitor cleanup --keep-backups 5 --staging-max-age-seconds 0

Tune retention in monitor config (live_updates section):

retain_backups: # how many backup manifests to keep

staging_max_age_seconds: # stale candidate-* staging cutoff

#### Falsi Positivi

**Sintomo:** Pacchetto legittimo segnalato come dannoso.

**Passaggi:**

1. **Verifica il risultato:** Esamina i dettagli del rapporto, inclusi gravità e descrizione

2. **Controlla la versione:** La versione segnalata potrebbe essere specifica:   ```bash
   orewatch /path/to/project --verbose

3. Segnala falso positivo: Se confermato errato:
   • Apri un issue su https://github.com/rapticore/ore-mal-pkg-inspector/issues con i dettagli

Modalità debug per l'investigazione

Abilita registrazione dettagliata:```bash

Scanner debug mode

orewatch /path/to/project --debug 2> debug.log

Collector debug mode

cd collectors python3 orchestrator.py --debug 2> collector-debug.log

**Review logs:** Controlla `debug.log` per una traccia di esecuzione dettagliata che include:
- Percorsi dei file scansionati
- Query SQL eseguite
- Risultati del pattern matching
- Stack trace degli errori

---

## FAQ

### Con quale frequenza dovrei aggiornare le intelligence sulle minacce?

**Raccomandazione:**
- **Ambienti di produzione/CI:** Aggiornamenti automatici giornalieri
- **Workstation di sviluppo:** Aggiornamenti almeno settimanali
- **Dopo notizie di sicurezza:** Aggiornamento immediato quando vengono annunciate nuove minacce

I pacchetti dannosi vengono pubblicati continuamente. Gli aggiornamenti giornalieri garantiscono le protezioni più recenti.

### Come aggiorno i dati delle intelligence sulle minacce?

Esegui lo scanner con il flag `--latest-data` per forzare un aggiornamento:```bash
orewatch /path/to/project --latest-data

Per aggiornamenti automatici in CI/CD, pianifica scansioni periodiche con il flag --latest-data (ad esempio, giornalmente). Aggiungi --include-experimental-sources solo se vuoi esplicitamente includere i dati derivati da Phylum nella ricostruzione.

Nota: Le scansioni iniziali raccolgono automaticamente i dati, quindi gli aggiornamenti manuali sono necessari solo per aggiornare i database esistenti.

Da dove provengono i dati sulle minacce?

I database predefiniti sono costruiti dalle fonti di minaccia principali del progetto:

• openssf
• osv

Lo scanner può anche includere il set di fonti sperimentali del progetto:

• phylum con --include-experimental-sources

socketdev è presente nel repository come segnaposto disabilitato e non fa parte del percorso di raccolta predefinito.

Per dettagli tecnici sulle fonti di dati, la raccolta e l'elaborazione, consulta ARCHITECTURE.md.

Questo strumento modifica il mio codice o le dipendenze?

No. OreWatch esegue operazioni di sola lettura. Esso:

• ✅ Legge i file delle dipendenze
• ✅ Interroga i database delle minacce
• ✅ Scansiona per pattern di file
• ✅ Genera rapporti

Esso mai:

• ❌ Modifica i file dei pacchetti
• ❌ Installa o rimuove pacchetti
• ❌ Modifica la configurazione del progetto
• ❌ Esegue il codice dei pacchetti

Cosa succede se il mio pacchetto viene segnalato come dannoso?

Passi da seguire:

1. Verifica il risultato: Controlla il rapporto per dettagli e gravità
2. Esamina le prove: Esamina la descrizione e i comportamenti rilevati
3. Controlla le versioni: Determina se versioni specifiche sono interessate
4. Se legittimo:
   • Segnala un falso positivo ai manutentori della fonte dati
   • Apri un problema sul nostro GitHub con i dettagli
5. Se veramente dannoso:
   • Rimuovi immediatamente il pacchetto
   • Rivedi i commit recenti per eventuali danni
   • Controlla i log per attività sospette
   • Aggiorna a un'alternativa sicura

Posso usarlo offline?

Parzialmente.

Scansione offline: ✅ Sì, una volta inizializzati i database```bash

Online: Initial setup (one-time - runs automatically on first scan)

orewatch /path/to/project

Offline: Subsequent scans work with local databases

orewatch /path/to/project

**Aggiornamenti offline:** ❌ No, la raccolta di threat intelligence richiede accesso a Internet per recuperare da fonti di sicurezza.

**Ambienti air-gapped:** Puoi:
1. Scaricare i database su una macchina connessa a Internet
2. Trasferire i file SQLite nella directory singola `final_data_dir` mostrata da `orewatch monitor doctor`
3. Eseguire scansioni offline con dati potenzialmente obsoleti

### Come si confronta con npm audit o pip-audit?

**Scopi diversi:**

**npm audit / pip-audit:**
- Si concentrano sulle vulnerabilità CVE note
- Verificano le versioni dei pacchetti rispetto ai database di advisory
- Mantenuti dai team dei registry di pacchetti

**OreWatch:**
- Si concentra su pacchetti dannosi (non solo vulnerabili)
- Rileva typosquatting, malware, attacchi alla supply chain
- Copertura cross-ecosistema
- Rilevamento IoC per minacce attive

**Buona pratica:** Utilizza **entrambi**:```bash
# Check for vulnerabilities
npm audit
pip-audit

# Check for malicious packages
orewatch /path/to/project

Funziona con registri di pacchetti privati?

Scansione delle dipendenze: ✅ Sì, lo scanner legge i tuoi file di dipendenza indipendentemente dalla provenienza dei pacchetti.

Intelligence sulle minacce: ⚠️ Limitata. I nostri database coprono i registri pubblici (npmjs.com, pypi.org, ecc.). I pacchetti malevoli su registri privati non verranno rilevati a meno che non si aggiungano dati personalizzati sulle minacce.

Dati personalizzati sulle minacce: Puoi estendere i database con i tuoi elenchi di pacchetti malevoli. Contattaci per ricevere indicazioni su questo caso d'uso avanzato.

Qual è l'impatto sulle prestazioni?

Tempo di scansione:

• Progetti piccoli (< 50 pacchetti): < 5 secondi
• Progetti medi (50-500 pacchetti): 5-30 secondi
• Progetti grandi (500+ pacchetti): 30-120 secondi

Fattori:

• La scansione IoC aggiunge un overhead del 10-50% (disabilitala con --no-ioc se non necessaria)
• La prima esecuzione potrebbe essere più lenta mentre i database vengono caricati in memoria

Suggerimenti per l'ottimizzazione:```bash

Scan specific files instead of entire directory

orewatch --file package.json

---

## Contribuire

Accogliamo con favore i contributi! Che si tratti di segnalare bug, suggerire funzionalità o contribuire con codice, il tuo aiuto migliora OreWatch per tutti.

**Segnala bug o richiedi funzionalità:**
- GitHub Issues: https://github.com/rapticore/ore-mal-pkg-inspector/issues

**Contribuisci con codice:**
- Vedi [CONTRIBUTING.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/CONTRIBUTING.md) per linee guida dettagliate su configurazione dello sviluppo, stile del codice, test e processo di pull request.

**Domande o discussioni:**
- GitHub Discussions: https://github.com/rapticore/ore-mal-pkg-inspector/discussions

---

## Politica di Sicurezza

La sicurezza è la nostra massima priorità. OreWatch è uno strumento di sicurezza e prendiamo sul serio le vulnerabilità.

### Segnalazione di Vulnerabilità di Sicurezza

**NON aprire issue pubbliche su GitHub per vulnerabilità di sicurezza.**

Invece, segnala privatamente:

**Email:** [email protected]

**Includi:**
- Descrizione della vulnerabilità
- Passaggi per riprodurla
- Impatto potenziale
- Correzione suggerita (se applicabile)
- I tuoi recapiti per follow-up

### Tempi di Risposta

- **Ricevuta:** Entro 48 ore
- **Valutazione iniziale:** Entro 7 giorni
- **Tempistiche di correzione:** Variano in base alla gravità
  - Critica: 7-14 giorni
- Alta: 14-30 giorni
- Media/Bassa: 30-60 giorni

### Buone Pratiche di Sicurezza

Quando usi OreWatch:

**Da fare:**
- ✅ Eseguire con il minimo privilegio (non richiede root/admin)
- ✅ Aggiornare regolarmente le intelligence sulle minacce
- ✅ Esaminare tempestivamente i report di scansione
- ✅ Integrare in CI/CD per una protezione continua
- ✅ Mantenere lo strumento aggiornato all'ultima versione

**Da non fare:**
- ❌ Ignorare i risultati della scansione senza indagare
- ❌ Disabilitare la scansione IoC in ambienti di produzione
- ❌ Condividere file di database provenienti da fonti non affidabili
- ❌ Eseguire con privilegi elevati inutilmente

### Divulgazione delle Vulnerabilità

Seguiamo la divulgazione coordinata:
1. Vulnerabilità segnalata privatamente
2. Correzione sviluppata e testata
3. Advisory di sicurezza pubblicato
4. Divulgazione pubblica dopo che la correzione è disponibile

### Hall of Fame della Sicurezza

Riconosciamo i ricercatori di sicurezza che divulgano responsabilmente le vulnerabilità:

*L'elenco verrà mantenuto man mano che verranno ricevuti i report*

---

### Richieste della Community

Vota o suggerisci funzionalità:
- **GitHub Discussions:** https://github.com/rapticore/ore-mal-pkg-inspector/discussions
- **Richiesta Funzionalità:** https://github.com/rapticore/ore-mal-pkg-inspector/issues

### Contribuire alla Roadmap

Diamo priorità alle funzionalità in base a:
- Impatto sulla sicurezza
- Domanda della community
- Sostenibilità della manutenzione
- Allineamento con gli obiettivi del progetto

Per influenzare la roadmap:
1. Apri una richiesta di funzionalità con un caso d'uso dettagliato
2. Partecipa alle discussioni
3. Contribuisci con implementazioni (PR benvenute!)

---

## Roadmap

OreWatch è utilizzabile oggi per:

- scansioni CLI locali su npm, PyPI, Maven, RubyGems, Go e Cargo
- un monitor di sottofondo per utente per molti progetti
- integrazioni MCP per Cursor, Claude Code e Codex
- integrazioni API localhost per VS Code, JetBrains / PyCharm e helper Xcode
- barra dei menu macOS e notifiche popup

Priorità a breve termine:

- primi esempi di integrazione o plugin leggeri per VS Code e JetBrains / PyCharm
- flussi di notifica più robusti per l'utente oltre ai popup locali
- gestione più chiara delle policy di progetto da CLI e UI
- reportistica di monitoraggio più ricca e documentazione per l'adozione

Priorità a medio termine:

- flussi di scansione di progetto più ampi dal monitor e dalla superficie MCP
- migliori linee guida per l'implementazione a livello organizzativo
- canali di consegna e escalation di alert esterni più robusti
- esperienza utente IDE più profonda invece di semplici linee guida per l'integrazione API

Limite attuale noto:

- L'integrazione Xcode è attualmente migliore per la visibilità degli alert e per repository con linguaggi misti. OreWatch non analizza ancora manifest nativi Apple come `Package.resolved`, `Podfile.lock` o `Cartfile`.

Direzione a lungo termine:

- supporto nativo per manifest dell'ecosistema Apple
- integrazioni editor di prima parte più forti
- maggiore parità di esperienza utente tra sistemi operativi oltre all'attuale percorso della barra dei menu macOS

Vedi [docs/roadmap.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/roadmap.md) per la visuale della roadmap più focalizzata sull'adozione.

---

## Licenza

Licenza MIT

Copyright (c) 2025 Rapticore

Con la presente viene concessa l'autorizzazione, gratuitamente, a chiunque ottenga una copia
di questo software e dei relativi file di documentazione (il "Software"), di utilizzare
il Software senza restrizioni, inclusi, senza limitazione, i diritti
di utilizzare, copiare, modificare, unire, pubblicare, distribuire, concedere in sublicenza e/o vendere
copie del Software, e di consentire alle persone a cui il Software è
fornito di fare altrettanto, alle seguenti condizioni:

L'avviso di copyright sopra e questa nota di autorizzazione devono essere inclusi in tutte
le copie o parti sostanziali del Software.

IL SOFTWARE VIENE FORNITO "COSÌ COM'È", SENZA GARANZIA DI ALCUN TIPO, ESPRESSA O
IMPLICITA, INCLUSI MA NON LIMITATI A GARANZIE DI COMMERCIABILITÀ,
IDONEITÀ PER UNO SCOPO PARTICOLARE E NON VIOLAZIONE. IN NESSUN CASO GLI
AUTORI O I TITOLARI DEL COPYRIGHT SARANNO RESPONSABILI PER QUALSIASI RECLAMO, DANNO O ALTRA
RESPONSABILITÀ, SIA IN UN'AZIONE CONTRATTUALE, ILLECITO O ALTRO, DERIVANTE DA,
O IN CONNESSIONE CON IL SOFTWARE O L'USO O ALTRE OPERAZIONI NEL
SOFTWARE.

---

## Supporto

### Ottenere Aiuto

**Documentazione:** La stai leggendo! Inizia da qui per la maggior parte delle domande.

**GitHub Discussions:** Per domande, idee e interazione con la community:
- https://github.com/rapticore/ore-mal-pkg-inspector/discussions

**GitHub Issues:** Per segnalazioni di bug e richieste di funzionalità:
- https://github.com/rapticore/ore-mal-pkg-inspector/issues

**Email:** Per vulnerabilità di sicurezza e richieste private:
- [email protected]

### Supporto Professionale

Per organizzazioni che necessitano di:
- Integrazioni personalizzate
- Supporto con SLA
- Assistenza per distribuzione privata
- Feed di intelligence sulle minacce personalizzati

Contatta: [email protected]

---

## Ringraziamenti

### Origine del Progetto

Questo progetto è stato estratto dal repository [OreNPMGuard](https://github.com/rapticore/OreNPMGuard) per mantenere un focus chiaro del progetto mentre si espandevano le capacità.

**OreNPMGuard** (dicembre 2025) è specializzato nel rilevamento degli attacchi Shai-Hulud su npm con oltre 738 pacchetti interessati e analisi IoC approfondita. Durante il suo sviluppo, abbiamo riconosciuto la necessità di una protezione più ampia multi-ecosistema, portando alla creazione di OreWatch come strumento autonomo al servizio della più ampia comunità di sviluppatori in tutti i principali ecosistemi di pacchetti.

### Progetti Correlati

- **[OreNPMGuard](https://github.com/rapticore/OreNPMGuard)** - Scanner npm specializzato per Shai-Hulud

---

**Realizzato dal Team di Ricerca sulla Sicurezza di Rapticore**

*Proteggere le supply chain del software, una scansione alla volta.*