ore-mal-pkg-inspector — Détection de paquets malveillants multi-écosystème et scanner de sécurité de la chaîne d'approvisionnement | Kitploit

Je veux...	Utilisez ce chemin	Commencez par
analyser un dépôt maintenant	CLI scan	`orewatch /path/to/project`
protéger le développement local en arrière-plan	moniteur singleton	`orewatch monitor quickstart /path/to/project --client claude_code`
utiliser OreWatch depuis Cursor, Claude Code ou Codex	pont MCP	`orewatch monitor quickstart /path/to/project --client <cursor\|claude_code\|codex>`
intégrer avec VS Code, PyCharm ou Xcode	API localhost	`orewatch monitor quickstart /path/to/project --client vscode`
obtenir des alertes macOS visibles et une interface de révision native	application barre de menus	`orewatch monitor menubar`
valider les builds dans CI	CLI scan ponctuel	`orewatch . --strict-data`

Si vous avez déjà installé `orewatch` avec pipx et souhaitez ajouter plus tard l'application de la barre de menus macOS, injectez les liaisons Cocoa dans le même environnement pipx :```bash
pipx inject orewatch pyobjc-framework-Cocoa

> **Remarque :** Le Homebrew formulaire inclut les liaisons Cocoa requises par
> `orewatch monitor menubar`. Si une ancienne installation Homebrew signale
> `ModuleNotFoundError: No module named 'AppKit'`, exécutez
> `brew update && brew reinstall rapticore/tap/orewatch` pour que le formulaire reconstruise
> son environnement Python isolé avec la prise en charge de la barre de menus.

#### Option 3 — pip

Utilisez `pip` pour les pipelines CI, les images Docker, ou lorsque vous gérez vos propres
environnements virtuels :```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

#### Option 4 — Source Checkout (Contributeurs)```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

#### Notes sur les plateformes

| Plateforme | Source Python | Remarques |
|---|---|---|
| **macOS** (Homebrew Python) | `brew install [email protected]` | Recommandé pour les utilisateurs de Homebrew |
| **macOS** (pyenv) | `pyenv install 3.14` | Idéal pour les configurations multi-versions |
| **Ubuntu / Debian** | `sudo apt install python3.14` ou pyenv | Vérifiez que votre distribution fournit 3.14+ |
| **Fedora / RHEL** | `sudo dnf install python3.14` ou pyenv | — |
| **Windows (WSL)** | pyenv ou paquet système | Windows natif non testé |

> **Python 3.14 est requis.** OreWatch utilise des fonctionnalités de langage introduites dans
> Python 3.14. Les versions plus anciennes échoueront au moment de l'importation.

#### Dépannage de l'installation

| Symptôme | Correctif |
|---|---|
| `command not found: orewatch` | Assurez-vous que le répertoire d'installation est dans votre `PATH`. Pour pipx : exécutez `pipx ensurepath` et redémarrez votre shell. |
| `ModuleNotFoundError` à l'import | Vous avez peut-être plusieurs versions de Python. Vérifiez que l'environnement d'exécution derrière `orewatch` est Python 3.14+ et réinstallez avec l'interpréteur correspondant. |
| L'installation pipx échoue avec des erreurs de résolveur | Mettez à niveau pipx : `python3.14 -m pip install --upgrade pipx` |
| Homebrew `orewatch` introuvable après installation | Exécutez d'abord `brew tap rapticore/tap`, puis réessayez l'installation. |
| Permission refusée lors de l'installation pip | Utilisez `pip install --user orewatch` ou installez dans un environnement virtuel. |

_Remarque : Si les données de menace locales sont manquantes ou obsolètes, les analyses de paquets préparent un candidat de mise à jour en direct et ne le promeuvent qu'après le passage des portes d'anomalie. Si le candidat semble suspect, OreWatch conserve le dernier jeu de données connu comme bon actif._

_CLI installée :_ `orewatch`
_Alias de compatibilité :_ `ore-mal-pkg-inspector`

### Premier scan

**Scannez un répertoire de projet :**```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

Si vous souhaitez qu'OreWatch continue de surveiller le projet après cette première analyse, poursuivez avec [Surveillance en arrière-plan](#background-monitoring) ou allez directement à [docs/adoption-guide.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/main/docs/adoption-guide.md).

---

## Utilisation

### Commandes de base

**Analyser un répertoire (Détection automatique de l'écosystème) :**```bash
# Current directory
orewatch .

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

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

**Forcer un écosystème spécifique :**```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

### Utilisation avancée

**Chemin de sortie personnalisé :**```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

Option	Court	Description	Valeur par défaut
`--file`	`-f`	Chemin vers un fichier spécifique à analyser (ignore la détection de répertoire)	Aucun
`--ecosystem`	`-e`	Forcer l'écosystème : `npm`, `pypi`, `maven`, `rubygems`, `go`, `cargo`	Détection automatique
`--output`	`-o`	Chemin de sortie personnalisé pour le rapport JSON principal ; OreWatch écrit également un rapport HTML frère	`scan-output/malicious_packages_report_{timestamp}.json`
`--no-summary`		Ne pas afficher le résumé du rapport dans la console	False
`--no-ioc`		Ignorer l'analyse des IoC (Indicateurs de compromission)	False
`--ioc-only`		Analyser uniquement les IoC, ignorer la vérification des paquets	False
`--latest-data`		Forcer une actualisation en direct par étapes et une promotion filtrée par anomalies avant l'analyse	False
`--strict-data`		Échouer si un écosystème demandé possède des données de menace partielles ou manquantes	False
`--include-experimental-sources`		Inclure les collecteurs expérimentaux lors de l'actualisation des données de menace	False
`--list-supported-files`		Afficher les noms exacts des fichiers manifestes de dépendances pris en charge et quitter	False
`--verbose`	`-v`	Afficher les journaux de niveau INFO (messages de progression)	False
`--debug`		Afficher les journaux de niveau DEBUG (diagnostics détaillés)	False

`monitor quickstart` est le flux recommandé pour la première exécution. Il :

- installe ou rafraîchit le service moniteur singleton
- démarre le moniteur si nécessaire
- ajoute le projet cible à la liste de surveillance
- affiche le bloc de démarrage pour le client sélectionné

Si vous préférez installer le moniteur d'abord et configurer les clients plus tard :```bash
orewatch monitor install
orewatch monitor install --ide-bootstrap
orewatch monitor install --service-manager launchd --no-start

Utilisez ces commandes pour des tâches légèrement différentes :

- `monitor status` affiche si le démon singleton et l'API sont en cours d'exécution
- `monitor connection-info` affiche l'URL de l'API de bouclage, le chemin du jeton, le répertoire home du moniteur et les clients bootstrap supportés
- `monitor doctor` affiche les chemins exacts de la configuration, de la base de données d'état, des journaux et des données partagées sur les menaces

**3. Ajoutez chaque projet que vous souhaitez que le singleton surveille**```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

Client	Transport	Commande d'amorçage	Notes
Claude Code	MCP	`orewatch monitor ide-bootstrap --client claude_code`	Pont MCP de première classe
Codex	MCP	`orewatch monitor ide-bootstrap --client codex`	Pont MCP de première classe
Cursor	MCP	`orewatch monitor ide-bootstrap --client cursor`	Pont MCP de première classe
VS Code	Local API	`orewatch monitor ide-bootstrap --client vscode`	Aucune extension intégrée ; utilisez l'API localhost
JetBrains / PyCharm	Local API	`orewatch monitor ide-bootstrap --client jetbrains`	Aucun plugin intégré ; utilisez l'API localhost
Xcode	Local API	`orewatch monitor ide-bootstrap --client xcode`	Idéal pour les résultats/notifications et les dépôts multilingues

Quand `orewatch monitor ide-bootstrap --client <client>` parvient à résoudre le script console local, il émet désormais ce chemin absolu au lieu de `orewatch` nu. Si vous avez une configuration MCP plus ancienne qui contient encore `"command": "orewatch"`, régénérez-la et remplacez l'ancienne entrée.```json
{
  "orewatch": {
    "baseUrl": "http://127.0.0.1:48736",
    "tokenPath": "/path/to/api.token"
  }
}

Configuration recommandée :

1. Exécutez `orewatch monitor quickstart /path/to/project --client <cursor|claude_code|codex>` une fois.
2. Copiez le bloc MCP imprimé dans le client MCP correspondant.
3. Ouvrez un projet surveillé dans ce client.
4. Laissez le client appeler OreWatch via MCP pour :
   - `orewatch_health`
   - `orewatch_check_dependency_add`
   - `orewatch_check_manifest`
   - `orewatch_override_dependency_add`
   - `orewatch_list_active_findings`
   - `orewatch_list_notifications`

Notes :

- `monitor mcp` est un serveur stdio. Si vous le lancez manuellement, il semblera inactif en attendant un client MCP.
- Le pont MCP vérifie l'API locale au démarrage et peut démarrer automatiquement le moniteur singleton lorsque `auto_start_on_client` est activé.
- Pour un démarrage fiable de l'IDE, installez le moniteur d'arrière-plan une fois avec `monitor install` pour que le démon soit déjà disponible avant que le pont MCP ne démarre.

##### VS Code

Les intégrations VS Code doivent utiliser l'API singleton localhost plutôt que le pont MCP.

Configuration recommandée :

1. Exécutez `orewatch monitor quickstart /path/to/project --client vscode`.
2. Copiez `baseUrl` et `tokenPath` depuis `orewatch monitor ide-bootstrap --client vscode`.
3. Intégrez ces valeurs dans votre extension, tâche ou assistant VS Code local.
4. Appelez l'API lors des événements dependency-add, manifest-save et alert-refresh.

Utilisation recommandée de l'API pour une intégration VS Code :

- appelez `POST /v1/check/dependency-add` avant les flux d'installation/ajout du gestionnaire de paquets
- appelez `POST /v1/check/manifest` lorsqu'un manifeste pris en charge est sauvegardé ou explicitement revérifié
- interrogez `GET /v1/findings/active` et `GET /v1/notifications` pour afficher les détections en arrière-plan

##### JetBrains / PyCharm

JetBrains et PyCharm utilisent le même contrat d'API localhost que VS Code.

Configuration recommandée :

1. Exécutez `orewatch monitor quickstart /path/to/project --client jetbrains`.
2. Copiez le bloc API depuis `orewatch monitor ide-bootstrap --client jetbrains`.
3. Utilisez `baseUrl` et `tokenPath` retournés dans un plugin JetBrains, un outil externe ou un assistant local.
4. Affichez à la fois les décisions synchrones de dépendances et les alertes d'arrière-plan stockées dans l'IDE.

Utilisation recommandée de l'API pour une intégration JetBrains :

- vérifiez les ajouts de dépendances avec `POST /v1/check/dependency-add`
- revérifiez `package.json`, `requirements.txt`, `pyproject.toml`, `pom.xml`, `Gemfile`, `go.mod`, `Cargo.toml`, et les manifestes pris en charge associés avec `POST /v1/check/manifest`
- récupérez `GET /v1/findings/active` et `GET /v1/notifications` pour des panneaux d'alerte ou fenêtres d'outils persistants

##### Xcode

Les intégrations Xcode doivent également utiliser l'API singleton localhost, mais il y a une limite importante : OreWatch ne parse pas encore les manifestes de dépendances Apple natifs comme `Package.resolved`, `Podfile.lock` ou `Cartfile`. Aujourd'hui, l'intégration Xcode est idéale pour :

- afficher les résultats d'arrière-plan et les notifications dans un assistant, un script ou une application compagnon
- les dépôts multi-langages ouverts dans Xcode qui contiennent également des manifestes pris en charge comme `package.json`, `pyproject.toml` ou `Cargo.toml`
- les équipes qui souhaitent l'application de la barre de menus macOS et les alertes du Centre de notifications tout en travaillant dans Xcode

Configuration recommandée :

1. Exécutez `orewatch monitor quickstart /path/to/project --client xcode`.
2. Copiez le bloc API depuis `orewatch monitor ide-bootstrap --client xcode`.
3. Utilisez `baseUrl` et `tokenPath` retournés depuis un script de phase de build, un processus assistant ou une intégration Xcode personnalisée.
4. Interrogez `GET /v1/findings/active` et `GET /v1/notifications` pour des alertes visibles par l'utilisateur.
5. Si l'espace de travail Xcode contient des manifestes non-Apple pris en charge, appelez `POST /v1/check/manifest` pour ces fichiers dans le cadre de votre flux de travail.

Statut actuel de l'intégration :

- Claude Code, Codex et Cursor : pont MCP de première qualité inclus dans ce dépôt
- VS Code : contrat d'API local documenté, mais aucune extension officielle fournie pour le moment
- JetBrains / PyCharm : contrat d'API local documenté, mais aucun plugin officiel fourni pour le moment
- Xcode : API locale et intégration barre de menus documentées, mais aucune extension Xcode officielle et aucun analyseur de manifeste Apple natif pour le moment

#### Quand OreWatch trouve quelque chose

Lorsque le moniteur d'arrière-plan détecte un paquet compromis ou un IoC dans un projet surveillé, OreWatch :

- écrit des rapports JSON et HTML gérés par le moniteur dans le répertoire `reports/` du moniteur singleton
- stocke le résultat actif dans la base de données d'état du moniteur
- stocke une entrée de notification avec un message actionnable
- émet un avertissement dans le terminal si les notifications terminal sont activées
- sur macOS, privilégie l'application de la barre de menus singleton comme canal de popup lorsqu'elle est en cours d'exécution
- garde l'alerte la plus récente digne d'attention épinglée en haut du menu déroulant de la barre de menus pour un examen rapide
- sinon, utilise une notification de bureau directe au mieux si les notifications de bureau sont activées
- peut envoyer une notification webhook optionnelle pour les environnements distants ou sans tête

Utilisez l'interface de revue CLI intégrée pour inspecter ces alertes :```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

**Actions manuelles d'instantané et de signature :**```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

Les analyses rapides sont axées sur les paquets et s'exécutent selon un planning et après des modifications génériques des manifestes.
Les analyses complètes incluent la détection d'IoC et s'exécuent chaque nuit, sur demande manuelle, et après des modifications de workflow ou de fichiers payload.
Sur Linux, la configuration par défaut est ~/.config/orewatch/singleton/ et l'état par défaut est ~/.local/state/orewatch/singleton/.
Sur macOS, la configuration par défaut est ~/Library/Application Support/OreWatch/singleton/ et l'état par défaut est ~/Library/Application Support/OreWatch/State/singleton/.
Les données de menaces partagées résident désormais dans le répertoire d'état singleton à threat-data/final-data/.
monitor doctor affiche les chemins exacts config_path, state_db, log_file, final_data_dir et le répertoire des modèles de service pour le moniteur singleton.
Les écrasements de politique par projet peuvent être stockés dans .ore-monitor.yml à la racine du projet.
monitor install installe désormais un service launchd ou systemd au niveau utilisateur lorsque disponible, et revient au mode arrière-plan local sinon.
monitor quickstart /path/to/project --client claude_code est le flux de première exécution le plus simple pour une configuration d'agent LLM local.
--workspace-root /path/to/workspace est toujours accepté pour une version comme alias de compatibilité obsolète, mais il ne modifie plus l'identité du moniteur, l'emplacement du jeton ou le nommage du service.
En mode auto, si la configuration native launchd ou systemd échoue, OreWatch revient désormais au mode arrière-plan local au lieu d'abandonner l'installation.
monitor install --ide-bootstrap affiche des extraits d'amorçage copiables pour Claude Code, Codex, Cursor, VS Code, JetBrains / PyCharm et Xcode.
monitor connection-info affiche l'URL de base de l'API loopback, le chemin du jeton, la portée/répertoire personnel du moniteur singleton et si le démon est déjà en cours d'exécution.
monitor ide-bootstrap réaffiche les extraits d'amorçage MCP/API actuels sans rien réinstaller.
monitor mcp exécute un pont MCP local qui expose les vérifications de dépendances d'OreWatch à Claude Code, Codex et Cursor.
monitor findings, monitor notifications et monitor package-updates fournissent l'interface d'examen intégrée pour les détections en arrière-plan et les avis de mise à jour.
monitor menubar lance une application native de la barre de menus macOS soutenue par le moniteur singleton et le magasin de résultats.
monitor mcp est un serveur stdio, donc il attendra un client MCP après le démarrage. Il écrit désormais l'état de préparation et de démarrage automatique sur stderr, pas sur stdout.
Pour le démarrage d'IDE ou de client MCP, utilisez monitor install de sorte que le démon d'arrière-plan soit déjà disponible lorsque le client lance monitor mcp ou appelle l'API.
make test-e2e-clients prépare l'espace de travail synthétique et exécute la matrice de clients MCP/API multi-écosystèmes pour Claude Code, Codex et Cursor.
Les installations open-source/communautaires utilisent par défaut les mises à jour en direct avec contrôle d'anomalies à partir des flux centraux en amont (openssf et osv). Les données candidates sont mises en scène dans le répertoire d'état du moniteur appartenant à l'utilisateur, vérifiées pour des baisses/suppressions anormales, puis promues dans les bases de données actives.
Les installations gérées/entreprises peuvent plutôt utiliser un descripteur de canal signé ou un manifeste configuré dans le fichier de configuration du moniteur appartenant à l'utilisateur via snapshots.channel_url ou snapshots.manifest_url, et le moniteur les vérifie avec snapshots.public_key_path.
Les workflows d'instantanés signés nécessitent actuellement openssl sur la machine locale.
Les directives de test d'intégration client multi-écosystèmes sont documentées dans docs/e2e-testing.md.

Comportement clé :
- Les candidats en direct sont d'abord construits dans une zone de préparation ; ils ne remplacent pas les bases de données actives pendant la collecte.
- Les chutes importantes, les régressions d'écosystème, les écosystèmes vides et les suppressions massives bloquent la promotion.
- Les pannes de source principale ne sont par défaut qu'un avertissement pour les mises à jour en direct open-source ; les chutes et suppressions au niveau de l'écosystème bloquent toujours les mauvaises promotions.
- Les anomalies avec avertissement uniquement sont enregistrées dans le statut et les rapports mais n'empêchent pas la promotion.
- Les candidats rejetés conservent le dernier jeu de données connu comme bon actif lorsqu'il en existe déjà un.
- Le bootstrap initial à partir des flux en direct est autorisé si au moins une source principale réussit et que le candidat produit des données d'écosystème utilisables.

**Configuration facultative du webhook de notification :**```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

Homebrew reste une couche de commodité par dessus la version publiée sur PyPI, et non l'artefact de publication principal.

**Meilleure option pour les contributeurs :** gardez le flux actuel de source-checkout :```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 .

**La sortie inclut:**
- Résultats de détection d'écosystèmes
- Progression de l'analyse des fichiers
- Comptes d'extraction de paquets
- Détails de requête de base de données
- Progression de l'analyse des IoC

**Exemple:**```
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

**Output includes :**
- Tous les messages de niveau INFO
- Les chemins de fichiers analysés
- Les détails d'exécution des requêtes SQL
- Les calculs de hachage
- Les résultats de correspondance de motifs
- Les informations d'état interne

**Cas d'utilisation :**
- Enquêter sur les raisons pour lesquelles un paquet n'a pas été détecté
- Déboguer les problèmes de détection automatique d'écosystème
- Signaler des problèmes avec un contexte détaillé
- Auditer le comportement du scanner

### Journalisation pour les collecteurs

Les collecteurs de renseignements sur les menaces prennent également en charge les modes verbeux et de débogage :```bash
cd collectors

# See collection progress
python3 orchestrator.py --verbose

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

{
    "_type": "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"
    }
  ]
}

  - 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/

**Avancé avec échec à la détection :**```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

### 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
        }
    }
}

**Remarque :** Si cela persiste, vérifiez la connectivité réseau, les permissions du système de fichiers, et si vous avez intentionnellement demandé des sources expérimentales.

#### "Aucun paquet détecté" Avertissement

**Symptôme :**```
WARNING: No packages detected in /path/to/project

Mauvais répertoire : Assurez-vous de scanner le répertoire de projet correct. ```bash ls /path/to/project # Verify package.json or requirements.txt exists
Manifeste non pris en charge ou inattendu : Imprimer les noms de fichiers exacts pris en charge ```bash orewatch --list-supported-files
Permissions de fichiers: Assurez-vous que les fichiers sont lisibles ```bash ls -la /path/to/project/package.json

Réessayer avec augmentation du délai d'attente: Edit collectors/config.yaml: ```yaml osv: timeout: 600 # Increase from default 300
Utilisez les données en cache : Si vous avez déjà téléchargé des données : ```bash python3 orchestrator.py --skip-build # Skip download, rebuild from cache

**Solution:**```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

#### Faux positifs

**Symptôme :** Paquet légitime signalé comme malveillant.

**Étapes :**

1. **Vérifier la constatation :** Examiner les détails du rapport, y compris la gravité et la description

2. **Vérifier la version :** La version signalée peut être spécifique :   ```bash
   orewatch /path/to/project --verbose

**Consultez les logs :** Vérifiez `debug.log` pour la trace d'exécution détaillée incluant :
- Chemins de fichiers scannés
- Requêtes SQL exécutées
- Résultats de correspondance de motifs
- Traces de pile d'erreurs

---

## FAQ

### À quelle fréquence dois-je mettre à jour les renseignements sur les menaces ?

**Recommandation :**
- **Environnements de production/CI :** Mises à jour automatisées quotidiennes
- **Postes de développement :** Mises à jour hebdomadaires au minimum
- **Après des actualités de sécurité :** Mise à jour immédiate lorsque de nouvelles menaces sont annoncées

Les paquets malveillants sont publiés en continu. Les mises à jour quotidiennes garantissent les dernières protections.

### Comment mettre à jour les données de renseignement sur les menaces ?

Exécutez le scanner avec l'option `--latest-data` pour forcer une mise à jour :```bash
orewatch /path/to/project --latest-data

**Mises à jour hors ligne :** ❌ Non, la collecte de renseignements sur les menaces nécessite un accès à Internet pour récupérer les données des sources de sécurité.

**Environnements isolés (airgap) :** Vous pouvez :
1. Télécharger les bases de données sur une machine connectée à Internet
2. Transférer les fichiers SQLite dans le répertoire `final_data_dir` singleton affiché par `orewatch monitor doctor`
3. Exécuter des analyses hors ligne avec des données potentiellement obsolètes

### En quoi cela se compare-t-il à npm audit ou pip-audit ?

**Objectifs différents :**

**npm audit / pip-audit :**
- Se concentrent sur les vulnérabilités CVE connues
- Vérifient les versions de paquets par rapport aux bases de données d'avis
- Maintenus par les équipes des registres de paquets

**OreWatch :**
- Se concentre sur les paquets malveillants (pas seulement les vulnérables)
- Détecte le typosquatting, les malwares, les attaques sur la chaîne d'approvisionnement
- Couverture multi-écosystèmes
- Détection d'IoC pour les menaces actives

**Meilleure pratique :** Utilisez les **deux** :```bash
# Check for vulnerabilities
npm audit
pip-audit

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

---

## Contribuer

Nous accueillons volontiers les contributions ! Que vous signaliez des bogues, suggériez des fonctionnalités ou contribuiez du code, votre aide améliore OreWatch pour tout le monde.

**Signaler des bogues ou demander des fonctionnalités :**
- GitHub Issues : https://github.com/rapticore/ore-mal-pkg-inspector/issues

**Contribuer du code :**
- Voir [CONTRIBUTING.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/main/CONTRIBUTING.md) pour des directives détaillées sur la configuration de développement, le style de code, les tests et le processus de pull request

**Questions ou discussions :**
- GitHub Discussions : https://github.com/rapticore/ore-mal-pkg-inspector/discussions

---

## Politique de sécurité

La sécurité est notre priorité absolue. OreWatch est un outil de sécurité, et nous prenons les vulnérabilités au sérieux.

### Signaler des vulnérabilités de sécurité

**N'ouvrez PAS de GitHub Issues publiques pour les vulnérabilités de sécurité.**

Signalez plutôt en privé :

**E-mail :** [email protected]

**Inclure :**
- Description de la vulnérabilité
- Étapes pour reproduire
- Impact potentiel
- Correctif suggéré (le cas échéant)
- Vos coordonnées pour le suivi

### Calendrier de réponse

- **Accusé de réception :** Sous 48 heures
- **Évaluation initiale :** Sous 7 jours
- **Délai de correction :** Varie selon la gravité
  - Critique : 7 à 14 jours
  - Élevé : 14 à 30 jours
  - Moyen/Faible : 30 à 60 jours

### Bonnes pratiques de sécurité

Lorsque vous utilisez OreWatch :

**À faire :**
- ✅ Exécuter avec le moindre privilège (pas de root/admin requis)
- ✅ Mettre à jour régulièrement les renseignements sur les menaces
- ✅ Examiner rapidement les rapports d'analyse
- ✅ Intégrer dans CI/CD pour une protection continue
- ✅ Maintenir l'outil à jour vers la dernière version

**À ne pas faire :**
- ❌ Ignorer les résultats d'analyse sans investigation
- ❌ Désactiver l'analyse des IoC dans les environnements de production
- ❌ Partager des fichiers de base de données provenant de sources non fiables
- ❌ Exécuter avec des privilèges élevés inutilement

### Divulgation des vulnérabilités

Nous suivons une divulgation coordonnée :
1. Vulnérabilité signalée en privé
2. Correctif développé et testé
3. Avis de sécurité publié
4. Divulgation publique après la disponibilité du correctif

### Tableau d'honneur de la sécurité

Nous reconnaissons les chercheurs en sécurité qui divulguent de manière responsable les vulnérabilités :

*La liste sera tenue à jour à mesure que les rapports seront reçus*

---

### Demandes de la communauté

Votez ou suggérez des fonctionnalités :
- **GitHub Discussions :** https://github.com/rapticore/ore-mal-pkg-inspector/discussions
- **Demandes de fonctionnalités :** https://github.com/rapticore/ore-mal-pkg-inspector/issues

### Contribuer à la feuille de route

Nous priorisons les fonctionnalités en fonction de :
- L'impact sur la sécurité
- La demande de la communauté
- La pérennité de la maintenance
- L'alignement avec les objectifs du projet

Pour influencer la feuille de route :
1. Ouvrir une demande de fonctionnalité avec un cas d'utilisation détaillé
2. Participer aux discussions
3. Contribuer des implémentations (les PR sont les bienvenues !)

---

## Feuille de route

OreWatch est utilisable aujourd'hui pour :

- analyses CLI locales dans npm, PyPI, Maven, RubyGems, Go et Cargo
- un moniteur d'arrière-plan par utilisateur pour de nombreux projets
- intégrations MCP pour Cursor, Claude Code et Codex
- intégrations API localhost pour VS Code, JetBrains / PyCharm et les assistants Xcode
- barre de menus macOS avec revue et notifications contextuelles

Priorités à court terme :

- premiers exemples d'intégration ou plugins légers pour VS Code et JetBrains / PyCharm
- workflows de notification utilisateur plus solides au‑delà des popups locales
- gestion de politique de projet plus claire depuis la CLI et l'interface utilisateur
- documentation enrichie sur les rapports d'analyse et l'adoption

Priorités à moyen terme :

- workflows d'analyse de projet plus étendus depuis le moniteur et la surface MCP
- meilleures directives de déploiement au niveau organisationnel
- canaux de livraison et d'escalade d'alertes externes plus robustes
- expérience utilisateur IDE plus approfondie au lieu d'une simple guidance d'intégration via API

Limite actuelle connue :

- L'intégration Xcode est actuellement la meilleure pour la visibilité des alertes et les dépôts multilingues. OreWatch n'analyse pas encore les manifests natifs Apple tels que `Package.resolved`, `Podfile.lock` ou `Cartfile`.

Direction à plus long terme :

- prise en charge native des manifests de l'écosystème Apple
- intégrations éditeur propriétaires plus solides
- parité d'expérience utilisateur système d'exploitation plus large au‑delà du chemin actuel de la barre de menus macOS

Voir [docs/roadmap.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/main/docs/roadmap.md) pour la vue plus axée sur l'adoption.

---

## Licence

Licence MIT

Copyright (c) 2025 Rapticore

Permission est accordée, gratuitement, à toute personne obtenant une copie
de ce logiciel et des fichiers de documentation associés (le "Logiciel"), de traiter
le Logiciel sans restriction, y compris sans limitation les droits
d'utiliser, copier, modifier, fusionner, publier, distribuer, sous‑licencier et/ou vendre
des copies du Logiciel, et de permettre aux personnes à qui le Logiciel est
fourni de le faire, sous réserve des conditions suivantes :

L'avis de copyright ci‑dessus et cet avis d'autorisation doivent être inclus dans toutes
les copies ou parties substantielles du Logiciel.

LE LOGICIEL EST FOURNI "EN L'ÉTAT", SANS GARANTIE D'AUCUNE SORTE, EXPRESSE OU
IMPLICITE, Y COMPRIS MAIS SANS S'Y LIMITER LES GARANTIES DE QUALITÉ MARCHANDE,
D'ADÉQUATION À UN USAGE PARTICULIER ET D'ABSENCE DE CONTREFAÇON. EN AUCUN CAS LES
AUTEURS OU TITULAIRES DU DROIT D'AUTEUR NE POURRONT ÊTRE TENUS RESPONSABLES DE TOUTE
RÉCLAMATION, DOMMAGE OU AUTRE RESPONSABILITÉ, QUE CE SOIT DANS LE CADRE D'UNE ACTION
CONTRACTUELLE, DÉLICTUELLE OU AUTRE, DÉCOULANT DE, OU EN LIEN AVEC LE LOGICIEL OU SON
UTILISATION, OU D'AUTRES INTERACTIONS AVEC LE LOGICIEL.

---

## Support

### Obtenir de l'aide

**Documentation :** Vous la lisez ! Commencez ici pour la plupart des questions.

**GitHub Discussions :** Pour les questions, idées et interactions avec la communauté :
- https://github.com/rapticore/ore-mal-pkg-inspector/discussions

**GitHub Issues :** Pour les rapports de bogues et demandes de fonctionnalités :
- https://github.com/rapticore/ore-mal-pkg-inspector/issues

**E-mail :** Pour les vulnérabilités de sécurité et demandes privées :
- [email protected]

### Support professionnel

Pour les organisations nécessitant :
- Intégrations personnalisées
- Support avec SLA
- Assistance pour déploiement privé
- Flux de renseignements sur les menaces personnalisés

Contact : [email protected]

---

## Remerciements

### Origine du projet

Ce projet a été extrait du dépôt [OreNPMGuard](https://github.com/rapticore/OreNPMGuard) pour maintenir une orientation claire du projet tout en élargissant les capacités.

**OreNPMGuard** (décembre 2025) se spécialise dans la détection des attaques npm Shai‑Hulud avec plus de 738 paquets affectés et une analyse approfondie des IoC. Au cours de son développement, nous avons reconnu le besoin d'une protection plus large multi‑écosystème, ce qui a conduit à la création d'OreWatch en tant qu'outil autonome au service de la communauté des développeurs dans tous les grands écosystèmes de paquets.

### Projets connexes

- **[OreNPMGuard](https://github.com/rapticore/OreNPMGuard)** - Scanner npm spécialisé pour Shai‑Hulud
---

**Construit par l'équipe de recherche en sécurité de Rapticore**

*Protéger les chaînes d'approvisionnement logicielles, une analyse à la fois.*

ore-mal-pkg-inspector

Populaires

OreWatch

Vidéos

Installation

OreWatch et Cursor

OreWatch et CodeX

OreWatch et Claude-Code

Table des matières

Le problème

La solution

Fonctionnalités clés

Pourquoi OreWatch ?

Démarrer ici

Démarrage rapide

Prérequis

Installation

Option 1 — pipx (Recommandé)

Install pipx if you don't have it

Install 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

Optional macOS menu bar app

Option 2 — Homebrew (macOS)

Add the OreWatch tap

Install

Verify

Optional macOS menu bar app

Vérification après installation

Check the CLI is accessible

List supported manifest filenames

Run a quick scan on the current directory

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

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

Ecosystem auto-detected from filename

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

JSON file with package array

YAML file

Full scan (packages + IoCs) - default behavior

Skip IoC scanning for faster package-only checks

Only scan for IoCs, skip package database checking

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

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

Include experimental sources during collection

Print the exact dependency filenames the scanner recognizes

Référence de la ligne de commande

Options du scanner

Surveillance en arrière-plan

Configuration complète du moniteur

First project + first client

Recettes d'intégration des clients

Cursor, Claude Code, and Codex

Application native de barre de menus macOS

pip / source-checkout install

existing pipx install

Homebrew install

Guide d'adoption

Opérations quotidiennes

Background service lifecycle

Run the daemon in the foreground

Launch the native macOS menu bar UI

Trigger immediate scans

Review detections and alerts

Reclaim disk space — prune accumulated backup manifests and orphaned staging

Distribution

Distribution de paquet recommandée

Déploiement macOS géré

Distribution recommandée des instantanés

Modèle global recommandé

Journalisation et débogage

Mode verbeux

Mode de débogage

Sortie et Rapports

Structure du rapport

Comprendre les résultats

Intégration CI/CD

GitHub Actions

GitLab CI```yaml

Hook Pre-commit