OreWatch

Detección de Paquetes Maliciosos Multi-Ecosistema y Escáner de Seguridad en la Cadena de Suministro

Una herramienta de seguridad de grado de producción para detectar paquetes maliciosos y amenazas en la cadena de suministro en los ecosistemas npm, PyPI, Maven, RubyGems, Go y Cargo. Aprovecha la recopilación automatizada de inteligencia de amenazas de fuentes de seguridad confiables para identificar dependencias comprometidas en sus proyectos.

OreWatch es el nombre del producto y del paquete de PyPI. La ruta actual del repositorio fuente todavía usa ore-mal-pkg-inspector.

Videos

Instalación

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

OreWatch y Cursor

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

OreWatch y CodeX

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

OreWatch y Claude-Code

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

Tabla de Contenidos

• El Problema
• La Solución
• Características Clave
• Por Qué OreWatch?
• Comience Aquí
• Inicio Rápido
  • Requisitos Previos
  • Instalación
  • Primer Escaneo
• Uso
  • Comandos Básicos
  • Uso Avanzado
  • Referencia de Línea de Comandos
  • Monitoreo en Segundo Plano
• Guía de Adopción
• Distribución
  • Despliegue Gestionado en macOS
• Registro y Depuración
• Salida e Informes
• Integración CI/CD
• Solución de Problemas
• Preguntas Frecuentes
• Contribuir
• Política de Seguridad
• Hoja de Ruta
• Licencia
• Soporte
• Agradecimientos

El Problema

Los ataques a la cadena de suministro son ahora el vector de amenaza principal para el compromiso de software. Solo en 2024, se publicaron miles de paquetes maliciosos en npm, PyPI y otros registros de paquetes, dirigidos a desarrolladores mediante typosquatting, confusión de dependencias y campañas de malware sofisticadas como Shai-Hulud.

El desafío: Las organizaciones y desarrolladores necesitan:

• Escanear dependencias en múltiples ecosistemas de programación
• Mantenerse actualizados con la inteligencia de amenazas en rápida evolución de múltiples fuentes
• Detectar no solo paquetes maliciosos conocidos sino también indicadores de compromiso (IoCs)
• Integrar el escaneo de seguridad en los flujos de trabajo de desarrollo existentes
• Responder rápidamente a amenazas recién descubiertas

La brecha: Las soluciones existentes a menudo son:

• Limitadas a un solo ecosistema (solo npm, solo PyPI, etc.)
• Dependientes del mantenimiento manual de listas de amenazas
• Carentes de capacidades de detección de IoCs
• Difíciles de integrar en tuberías automatizadas
• Herramientas propietarias de caja negra sin transparencia

La Solución

OreWatch aborda estos desafíos proporcionando:

Cobertura Integral Multi-Ecosistema: Una sola herramienta para paquetes de npm, PyPI, Maven, RubyGems, Go y Cargo

Inteligencia de Amenazas Automatizada: Recopila y fusiona dinámicamente datos de fuentes de investigación de seguridad confiables

Detección Activa de IoCs: Identifica patrones de ataque Shai-Hulud y otros indicadores de código malicioso más allá de la coincidencia de nombres de paquetes

Listo para CI/CD: Diseñado para una integración perfecta en GitHub Actions, GitLab CI, Jenkins y otras plataformas de automatización

Código Abierto y Transparente: Visibilidad completa en la lógica de detección, fuentes de datos y metodología de escaneo

Características Clave

Soporte Multi-Ecosistema Escanea paquetes de npm, PyPI, Maven, RubyGems, Go y Cargo con detección automática de ecosistema a partir de la estructura del proyecto.

Base de Datos Unificada de Inteligencia de Amenazas Verifica contra bases de datos de paquetes maliciosos recopiladas dinámicamente de fuentes de investigación de seguridad confiables.

Detección Automática de Ecosistema Identifica inteligentemente ecosistemas a partir de la estructura de directorios, nombres de archivos, y puede escanear múltiples ecosistemas en una sola ejecución.

Detección de Indicadores de Compromiso (IoCs) Escanea patrones de ataque Shai-Hulud (variantes original y 2.0), hooks maliciosos, flujos de trabajo sospechosos y archivos de payload conocidos.

Integración con Shai-Hulud Cruza referencia de paquetes npm con la lista completa de paquetes afectados por Shai-Hulud de OreNPMGuard.

Informes JSON Estructurados Genera informes JSON legibles por máquina con metadatos explícitos de datos de amenazas y ubicaciones de archivos al estilo SARIF para los hallazgos.

Formatos de Entrada Flexibles Soporta archivos de dependencias estándar (package.json, requirements.txt, etc.) y listas de paquetes genéricas (texto, JSON, YAML).

Registro Listo para Producción Niveles de verbosidad configurables con las banderas --verbose y --debug para resolución de problemas y pistas de auditoría.

Seguro y Rápido Operaciones de solo lectura sin modificaciones a su código, optimizado para escanear grandes bases de código de manera eficiente.

Por Qué OreWatch?

vs. Herramientas de Ecosistema Único La mayoría de los escáneres de seguridad se centran en un solo gestor de paquetes. OreWatch proporciona protección unificada en seis ecosistemas principales, esencial para entornos de desarrollo políglotas modernos.

vs. Listas de Amenazas Manuales Las listas estáticas de paquetes maliciosos se vuelven obsoletas rápidamente. Nuestros recolectores automatizados obtienen inteligencia de amenazas fresca diariamente de múltiples fuentes autorizadas.

vs. Detección Solo por Nombre de Paquete Verificar solo los nombres de paquetes pasa por alto ataques sofisticados. La detección de IoCs identifica patrones de código malicioso incluso en paquetes que aún no están en listas negras.

vs. Auditorías de Seguridad Manuales Las revisiones manuales de dependencias consumen tiempo y son propensas a errores. El escaneo automatizado permite la validación continua de seguridad en cada compilación.

vs. Herramientas Comerciales de Caja Negra Las herramientas propietarias carecen de transparencia en la lógica de detección. Como proyecto de código abierto, cada regla de detección y fuente de datos es auditable.

Historia de Origen OreWatch nació del desarrollo de OreNPMGuard, un escáner especializado para ataques Shai-Hulud en npm. Durante ese proyecto, reconocimos la necesidad de una cobertura multi-ecosistema más amplia más allá de npm. En diciembre de 2025, extrajimos y mejoramos las capacidades de detección multi-ecosistema en esta herramienta independiente, manteniendo el enfoque de OreNPMGuard en npm mientras permitimos que OreWatch sirva a la comunidad de desarrolladores más amplia en todos los ecosistemas de paquetes principales.

Comience Aquí

Si está adoptando OreWatch por primera vez, elija la ruta más pequeña que coincida con su flujo de trabajo:

Secuencia recomendada para la primera ejecución para la mayoría de los desarrolladores:

1. Instale OreWatch con pip install . o el paquete publicado.
2. Ejecute orewatch monitor quickstart /ruta/al/proyecto --client <su-cliente>.
3. Verifique el demonio con orewatch monitor status.
4. Si está en macOS, inicie orewatch monitor menubar para notificaciones y una interfaz de usuario local.

Si desea una guía de configuración más corta con comandos para copiar y pegar, use docs/adoption-guide.md.

Inicio Rápido

Requisitos Previos

• Python 3.14 o superior
• pip para instalar dependencias
• Git para clonar el repositorio
• Conexión a internet para la configuración inicial de inteligencia de amenazas
• OpenSSL para generación, publicación y verificación de claves de instantáneas firmadas en flujos de trabajo de instantáneas del monitor

Instalación

OreWatch se puede instalar mediante pipx (recomendado), Homebrew (macOS), pip, o desde código fuente. Todos los métodos producen el comando CLI orewatch.

Opción 1 — pipx (Recomendado)

pipx instala OreWatch en su propio entorno aislado mientras hace que el comando orewatch esté disponible globalmente. Esta es la mejor opción para la mayoría de los desarrolladores.```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

Si ya instalaste `orewatch` con pipx y deseas agregar la aplicación de la barra de menú de macOS más tarde, inyecta los enlaces de Cocoa en el mismo entorno de pipx:```bash
pipx inject orewatch pyobjc-framework-Cocoa

Actualización:```bash pipx upgrade orewatch

**Desinstalar:**```bash
pipx uninstall orewatch

Opción 2 — Homebrew (macOS)

Para usuarios de macOS que prefieren instalaciones gestionadas por 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

**Actualización:**```bash
brew update && brew upgrade orewatch

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

> **Nota:** La fórmula de Homebrew incluye los bindings de Cocoa requeridos por
> `orewatch monitor menubar`. Si una instalación anterior de Homebrew reporta
> `ModuleNotFoundError: No module named 'AppKit'`, ejecuta
> `brew update && brew reinstall rapticore/tap/orewatch` para que la fórmula reconstruya
> su entorno Python aislado con soporte para la barra de menú.

#### Opción 3 — pip

Usa `pip` para pipelines de CI, imágenes de Docker, o cuando gestiones tus propios
virtualenvs:```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

Actualización:```bash python3.14 -m pip install --upgrade orewatch

#### Opción 4 — Verificación de Fuente (Contribuidores)```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

Verificación posterior a la instalación

Después de instalar con cualquier método, confirme que OreWatch funciona:```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 .

#### Notas de la plataforma

| Plataforma | Fuente de Python | Notas |
|---|---|---|
| **macOS** (Homebrew Python) | `brew install [email protected]` | Recomendado para usuarios de Homebrew |
| **macOS** (pyenv) | `pyenv install 3.14` | Mejor para configuraciones con múltiples versiones |
| **Ubuntu / Debian** | `sudo apt install python3.14` o pyenv | Verifica que tu distribución incluya 3.14+ |
| **Fedora / RHEL** | `sudo dnf install python3.14` o pyenv | — |
| **Windows (WSL)** | pyenv o paquete del sistema | Windows nativo no ha sido probado |

> **Python 3.14 es necesario.** OreWatch utiliza características del lenguaje introducidas en
> Python 3.14. Las versiones anteriores fallarán al importar.

#### Solución de problemas de instalación

| Síntoma | Solución |
|---|---|
| `command not found: orewatch` | Asegúrate de que la ubicación de instalación esté en tu `PATH`. Para pipx: ejecuta `pipx ensurepath` y reinicia tu terminal. |
| `ModuleNotFoundError` al importar | Puede que tengas múltiples versiones de Python. Confirma que el runtime detrás de `orewatch` sea Python 3.14+ y reinstala con el intérprete correspondiente. |
| pipx install falla con errores de resolución | Actualiza pipx: `python3.14 -m pip install --upgrade pipx` |
| Homebrew `orewatch` no encontrado después de instalar | Ejecuta `brew tap rapticore/tap` primero, luego reintenta la instalación. |
| Permiso denegado durante pip install | Usa `pip install --user orewatch` o instala dentro de un virtualenv. |

_Nota: Si los datos de amenazas locales faltan o están desactualizados, los escaneos de paquetes preparan un candidato de actualización en vivo y solo lo promueven después de que las puertas de anomalías pasen. Si el candidato parece sospechoso, OreWatch mantiene activo el último conjunto de datos conocido como bueno._

_CLI instalado:_ `orewatch`
_Alias de compatibilidad:_ `ore-mal-pkg-inspector`

### Primer escaneo

**Escanea un directorio de proyecto:**```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

Salida esperada:``` 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

Si desea que OreWatch siga monitoreando el proyecto después de este primer análisis, continúe con [Monitoreo en Segundo Plano](#background-monitoring) o vaya directamente a [docs/adoption-guide.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/adoption-guide.md).

---

## Uso

### Comandos Básicos

**Escanear Directorio (Detección automática del ecosistema):**```bash
# Current directory
orewatch .

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

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

Escanear archivos de dependencias específicos:```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

**Forzar Ecosistema Específico:**```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

Escanear listas de paquetes genéricos:```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 Avanzado

**Ruta de salida personalizada:**```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

Control de escaneo de 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

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

Controles de Datos de Amenazas:```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

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

Referencia de línea de comandos

Opciones del escáner

Monitoreo en segundo plano

El repositorio ahora incluye un monitor en segundo plano local que mantiene los datos de amenazas actualizados, observa los proyectos que han optado por cambios en el manifiesto y el flujo de trabajo, ejecuta escaneos con debounce y registra notificaciones para hallazgos nuevos o escalados. La configuración y el estado propiedad del monitor se almacenan fuera del repositorio en directorios propiedad del usuario, de modo que un repositorio clonado no pueda preconfigurar el comportamiento del monitor.

OreWatch ahora trata al monitor como un singleton por usuario. Un demonio puede observar muchos proyectos en cualquier lugar del disco y atender a múltiples clientes concurrentes de Claude Code, Codex, Cursor, VS Code, JetBrains / PyCharm y Xcode.

Configuración completa del monitor

1. Instalar e inicializar el monitor singleton```bash

First project + first client

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

`monitor quickstart` es el flujo recomendado para la primera ejecución. Hace lo siguiente:

- instala o actualiza el servicio monitor singleton
- inicia el monitor si es necesario
- agrega el proyecto de destino a la lista de vigilancia
- imprime el bloque de arranque para el cliente seleccionado

Si prefieres instalar el monitor primero y conectar los clientes después:```bash
orewatch monitor install
orewatch monitor install --ide-bootstrap
orewatch monitor install --service-manager launchd --no-start

2. Verificar que el monitor esté saludable```bash orewatch monitor status orewatch monitor connection-info orewatch monitor doctor

Utilice estos comandos para tareas ligeramente diferentes:

- `monitor status` muestra si el daemon singleton y la API están en ejecución
- `monitor connection-info` imprime la URL del bucle de retorno, la ruta del token, el directorio home del monitor y los clientes bootstrap compatibles
- `monitor doctor` imprime la configuración exacta, la base de datos de estado, los registros y las rutas de datos de amenazas compartidas

**3. Agregue cada proyecto que desee que el singleton supervise**```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 solo demonio de OreWatch puede vigilar todos estos proyectos a la vez. No necesitas un monitor separado por repositorio o por espacio de trabajo del IDE.

Recetas de Integración de Clientes

OreWatch soporta dos transportes de integración:

Los comandos de arranque imprimen una de estas formas:```json { "mcpServers": { "orewatch": { "command": "/absolute/path/to/orewatch", "args": [ "monitor", "mcp" ] } } }

Cuando `orewatch monitor ide-bootstrap --client <client>` puede resolver el script de consola local, ahora emite esa ruta absoluta en lugar del simple `orewatch`. Si tienes una configuración MCP anterior que aún dice `"command": "orewatch"`, regenérala y reemplaza la antigua entrada.```json
{
  "orewatch": {
    "baseUrl": "http://127.0.0.1:48736",
    "tokenPath": "/path/to/api.token"
  }
}

Cursor, Claude Code, and Codex

Estos clientes todos usan el mismo puente MCP local:```bash orewatch monitor mcp

Configuración recomendada:

1. Ejecuta `orewatch monitor quickstart /path/to/project --client <cursor|claude_code|codex>` una vez.
2. Copia el bloque MCP impreso en el cliente MCP correspondiente.
3. Abre un proyecto monitoreado en ese cliente.
4. Deja que el cliente llame a OreWatch a través de MCP para:
   - `orewatch_health`
   - `orewatch_check_dependency_add`
   - `orewatch_check_manifest`
   - `orewatch_override_dependency_add`
   - `orewatch_list_active_findings`
   - `orewatch_list_notifications`

Notas:

- `monitor mcp` es un servidor stdio. Si lo inicias manualmente, aparecerá inactivo mientras espera un cliente MCP.
- El puente MCP verifica la API local al inicio y puede iniciar automáticamente el monitor singleton una vez cuando `auto_start_on_client` está habilitado.
- Para un inicio confiable del IDE, instala el monitor de fondo una vez con `monitor install` para que el daemon ya esté disponible antes de que se inicie el puente MCP.

##### VS Code

Las integraciones con VS Code deben usar la API localhost singleton en lugar del puente MCP.

Configuración recomendada:

1. Ejecuta `orewatch monitor quickstart /path/to/project --client vscode`.
2. Copia `baseUrl` y `tokenPath` de `orewatch monitor ide-bootstrap --client vscode`.
3. Conecta esos valores en tu extensión, tarea o ayudante local de VS Code.
4. Llama a la API en los eventos dependency-add, manifest-save y alert-refresh.

Uso recomendado de la API para una integración con VS Code:

- llama a `POST /v1/check/dependency-add` antes de los flujos de instalación/agregar del gestor de paquetes
- llama a `POST /v1/check/manifest` cuando un manifiesto compatible se guarda o se vuelve a verificar explícitamente
- consulta `GET /v1/findings/active` y `GET /v1/notifications` para mostrar detecciones de fondo

##### JetBrains / PyCharm

JetBrains y PyCharm usan el mismo contrato de API localhost que VS Code.

Configuración recomendada:

1. Ejecuta `orewatch monitor quickstart /path/to/project --client jetbrains`.
2. Copia el bloque de API de `orewatch monitor ide-bootstrap --client jetbrains`.
3. Usa el `baseUrl` y `tokenPath` devueltos en un plugin de JetBrains, herramienta externa o ayudante local.
4. Muestra tanto las decisiones de dependencia síncronas como las alertas de fondo almacenadas dentro del IDE.

Uso recomendado de la API para una integración con JetBrains:

- verifica las adiciones de dependencia con `POST /v1/check/dependency-add`
- vuelve a verificar `package.json`, `requirements.txt`, `pyproject.toml`, `pom.xml`, `Gemfile`, `go.mod`, `Cargo.toml` y manifiestos compatibles relacionados con `POST /v1/check/manifest`
- obtén `GET /v1/findings/active` y `GET /v1/notifications` para paneles de alerta persistentes o ventanas de herramientas

##### Xcode

Las integraciones con Xcode también deberían usar la API localhost singleton, pero hay un límite de alcance importante: OreWatch aún no analiza los manifiestos de dependencias nativos de Apple como `Package.resolved`, `Podfile.lock` o `Cartfile`. Hoy, la integración con Xcode es mejor para:

- mostrar hallazgos y notificaciones de fondo en un ayudante, script o aplicación complementaria
- repositorios de varios lenguajes abiertos en Xcode que también contienen manifiestos compatibles como `package.json`, `pyproject.toml` o `Cargo.toml`
- equipos que desean la aplicación de la barra de menú de macOS y las alertas del Centro de Notificaciones mientras trabajan en Xcode

Configuración recomendada:

1. Ejecuta `orewatch monitor quickstart /path/to/project --client xcode`.
2. Copia el bloque de API de `orewatch monitor ide-bootstrap --client xcode`.
3. Usa el `baseUrl` y `tokenPath` devueltos desde un script de fase de compilación, un proceso auxiliar o una integración personalizada de Xcode.
4. Consulta `GET /v1/findings/active` y `GET /v1/notifications` para alertas visibles para el usuario.
5. Si el espacio de trabajo de Xcode contiene manifiestos no Apple compatibles, llama a `POST /v1/check/manifest` para esos archivos como parte de tu flujo de trabajo.

Estado actual de la integración:

- Claude Code, Codex y Cursor: puente MCP de primera clase incluido en este repositorio
- VS Code: contrato de API local documentado, pero aún no se incluye una extensión de primera parte
- JetBrains / PyCharm: contrato de API local documentado, pero aún no se incluye un plugin de primera parte
- Xcode: API local e integración con la barra de menú documentadas, pero aún no hay una extensión de Xcode de primera parte ni analizador de manifiestos nativos de Apple

#### Cuando OreWatch Encuentra Algo

Cuando el monitor de fondo detecta un paquete comprometido o un IoC en un proyecto monitoreado, OreWatch:

- escribe informes JSON y HTML gestionados por el monitor en el directorio `reports/` del monitor singleton
- almacena el hallazgo activo en la base de datos de estado del monitor
- almacena una entrada de notificación con un mensaje accionable
- emite una advertencia en la terminal si las notificaciones de terminal están habilitadas
- en macOS, prefiere la aplicación de la barra de menú singleton como canal de ventana emergente cuando se está ejecutando
- mantiene la alerta más reciente digna de atención fijada en la parte superior del menú desplegable de la barra de menú para una revisión rápida
- de lo contrario, recurre a una notificación de escritorio directa de mejor esfuerzo si las notificaciones de escritorio están habilitadas
- puede enviar una notificación webhook opcional para entornos remotos o sin cabeza

Usa la superficie de revisión CLI incorporada para inspeccionar esas alertas:```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

El puente de API local y MCP expone los mismos datos para IDEs y agentes:

• 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

Esta es la ruta compatible para IDEs, clientes MCP y agentes de codificación para mostrar detecciones en segundo plano después de que el análisis original haya finalizado.

Los avisos de actualización de paquetes son solo de notificación. OreWatch informa sobre versiones más recientes de las dependencias del proyecto vigilado y del propio OreWatch, pero no modifica manifiestos, archivos de bloqueo ni paquetes instalados.

Aplicación nativa de la barra de menú de macOS

OreWatch ahora incluye una aplicación nativa de la barra de menú de macOS para quienes deseen una interfaz de usuario local visible sin depender únicamente de comandos CLI, sondeo MCP o ventanas emergentes del Centro de Notificaciones de mejor esfuerzo.

Instale los enlaces Cocoa opcionales en el mismo entorno de ejecución que proporciona el comando orewatch. Elija el comando que coincida con su método de instalación:```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

Luego, inicia la aplicación de la barra de menú:```bash
orewatch monitor menubar

Por defecto, monitor menubar reinicia la aplicación en segundo plano y devuelve el indicador del shell inmediatamente. Use orewatch monitor menubar --foreground solo cuando quiera mantenerlo explícitamente adjunto a la terminal para depuración.

La aplicación de la barra de menú se adjunta al mismo monitor singleton. No inicia una segunda instancia del monitor. Si el monitor no está ya instalado y ejecutándose, la aplicación lo instalará/iniciará en el primer lanzamiento.

Homebrew instala los enlaces Cocoa en el entorno aislado libexec de OreWatch. Si orewatch monitor menubar reporta No module named 'AppKit', actualice la fórmula con brew update && brew reinstall rapticore/tap/orewatch. Para instalaciones con pip, pipx y desde fuente, los enlaces opcionales aún deben agregarse al mismo entorno de Python que proporciona el comando orewatch.

Cuando las notificaciones de escritorio están habilitadas en macOS, el vigilante singleton ahora mantiene viva una aplicación singleton de la barra de menú y la utiliza como superficie emergente principal. Eso evita depender solo de una invocación separada de osascript desde el demonio y le brinda una interfaz de usuario nativa persistente para nuevos hallazgos.

La compilación actual de la barra de menú prioriza los iconos. La antigua abreviatura OW y la redacción anterior del icono de OreWatch deben tratarse como referencias heredadas; la aplicación ahora prefiere el icono de marca incluido y solo recurre a texto compacto o insignias cuando macOS no puede renderizar la imagen o necesita un contador de alertas.

Lo que la aplicación de la barra de menú de macOS le ofrece:

• un elemento de estado persistente en la barra de menú que prefiere el icono de marca incluido, con texto compacto de respaldo o insignias de alerta cuando sea necesario
• un estado de alerta compacto en rojo/negrita para alertas recién detectadas que permanece visible hasta que abre el menú
• un resumen en vivo de hallazgos activos y la severidad más alta
• una sección de Actualizaciones de Paquetes de primera clase con actualizaciones de dependencias del proyecto, estado de autoactualización de OreWatch, estado de la última verificación y comandos sugeridos copiables
• notificaciones recientes en un menú desplegable nativo
• ventanas emergentes nativas del Centro de Notificaciones para alertas de monitor recién almacenadas
• una acción Agregar Carpeta de Trabajo... que inscribe un proyecto en el vigilante singleton y ejecuta un escaneo rápido inicial
• alternancias de configuración integradas para notificaciones de escritorio, notificaciones de terminal, keepalive de la barra de menú y ventanas emergentes controladas por la barra de menú
• acciones con un clic para abrir informes, la página principal del monitor y el registro del monitor
• acciones con un clic para abrir el archivo de configuración del monitor y la carpeta de configuración
• acciones de menú para verificar actualizaciones de paquetes, actualizar inteligencia de amenazas, ejecutar escaneos rápidos/completos e iniciar/reiniciar/detener el monitor singleton

Flujo recomendado para Mac:

1. Ejecute orewatch monitor quickstart /path/to/project --client claude_code una vez.
2. Instale los enlaces opcionales en el mismo entorno que orewatch.
3. Inicie orewatch monitor menubar.
4. Mantenga la aplicación de la barra de menú ejecutándose para una superficie de revisión nativa persistente mientras sus IDE y agentes de codificación continúan usando MCP o la API local.

Guía de Adopción

Para una implementación más fácil, use los documentos enfocados en lugar de leer el README completo de principio a fin:

• docs/adoption-guide.md: la ruta más corta para la adopción local por desarrolladores
• docs/local-api.md: contrato exacto de API localhost y MCP
• docs/e2e-testing.md: flujo de trabajo para contribuyentes y validación

Orden de adopción recomendado:

1. Comience con un repositorio y un usuario.
2. Habilite el monitor singleton con monitor quickstart.
3. Conecte un cliente: Cursor, Claude Code, Codex, VS Code, PyCharm o Xcode.
4. Confirme que los hallazgos aparecen en orewatch monitor findings y orewatch monitor notifications.
5. En macOS, agregue monitor menubar para que los usuarios obtengan una superficie de revisión persistente y entrega de ventanas emergentes.
6. Después de que la adopción local sea estable, agregue escaneos de CI y webhooks opcionales.

Operaciones Diarias

Comandos operativos comunes:```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

**Acciones manuales de snapshot y 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

Comportamiento del monitor:

• Los escaneos rápidos están enfocados en paquetes y se ejecutan según un cronograma y después de cambios genéricos en el manifiesto.
• Los escaneos completos incluyen detección de IoC y se ejecutan todas las noches, a solicitud manual, y después de cambios en el flujo de trabajo o archivos de payload.
• En Linux, la configuración por defecto es ~/.config/orewatch/singleton/ y el estado por defecto es ~/.local/state/orewatch/singleton/.
• En macOS, la configuración por defecto es ~/Library/Application Support/OreWatch/singleton/ y el estado por defecto es ~/Library/Application Support/OreWatch/State/singleton/.
• Los datos de amenazas compartidos ahora residen en el directorio de estado singleton en threat-data/final-data/.
• monitor doctor imprime la ruta exacta de config_path, state_db, log_file, final_data_dir y el directorio de plantillas de servicio para el monitor singleton.
• Las anulaciones de política por proyecto se pueden almacenar en en la raíz del proyecto.

Superficie de integración local:

• OreWatch ahora expone una API solo de localhost en 127.0.0.1:48736 de forma predeterminada cuando el daemon del monitor está en ejecución.
• La API utiliza un token bearer por usuario almacenado en el directorio de configuración del monitor en api.token con permisos solo del propietario.
• Las solicitudes directas a 127.0.0.1:48736 sin Authorization: Bearer <token> devolverán correctamente 401 Unauthorized.
• Los clientes agente e IDE deben descubrir el monitor a través de orewatch monitor connection-info en lugar de adivinar rutas, y deben enviar el project_path real en el que están operando dentro de las solicitudes de verificación de dependencias.
• Claude Code, Codex y Cursor pueden usar el puente MCP incluido, que expone orewatch_health, orewatch_check_dependency_add, orewatch_check_manifest, orewatch_override_dependency_add, , , y .

Configuración opcional de actualización en vivo controlada por anomalías:```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

Comportamiento clave:
- Los candidatos en vivo se construyen primero en un área de preparación; no sobrescriben las bases de datos activas durante la recopilación.
- Las caídas grandes, las regresiones del ecosistema, los ecosistemas vacíos y las eliminaciones masivas bloquean la promoción.
- Las interrupciones de fuentes principales son solo de advertencia por defecto para las actualizaciones en vivo de código abierto; las caídas y eliminaciones a nivel de ecosistema aún bloquean las promociones incorrectas.
- Las anomalías solo de advertencia se registran en el estado y los informes, pero no impiden la promoción.
- Los candidatos rechazados mantienen activo el último conjunto de datos conocido bueno cuando ya existe uno.
- Se permite el arranque inicial desde fuentes en vivo si al menos una fuente principal tiene éxito y el candidato produce datos de ecosistema utilizables.

**Configuración opcional del webhook de notificación:**```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

Establece webhook_format: slack al apuntar a un webhook entrante de Slack. En ese modo, OreWatch envía un payload simple de text.

Distribución

El proyecto ahora tiene dos superficies de distribución distintas:

1. El código del CLI y del monitor
2. Las instantáneas de datos de amenazas consumidas por el monitor

Deben distribuirse por separado.

Distribución de Paquete Recomendada

Mejor opción predeterminada para desarrolladores: publicar el escáner como un paquete Python normal en PyPI y recomendar la instalación con pipx.

Por qué esta es la mejor opción:

• El proyecto es un CLI de Python y un monitor en segundo plano, por lo que una rueda universal más una distribución fuente es el artefacto de lanzamiento más directo.
• pipx proporciona a los desarrolladores una instalación aislada a nivel de usuario sin contaminar los entornos virtuales del proyecto.
• CI aún puede instalar la misma versión con python3.14 -m pip install orewatch==<version>.
• Esto mantiene simple la ruta de actualización del CLI mientras deja las actualizaciones de datos de amenazas al canal de instantáneas firmadas.

Forma de lanzamiento recomendada:

• Publica artefactos de sdist y rueda universal en PyPI.
• Expone el punto de entrada de consola orewatch.
• Mantén ore-mal-pkg-inspector como un alias de compatibilidad temporal.
• Documenta pipx install --python python3.14 orewatch para instalaciones locales de desarrolladores.
• Documenta python3.14 -m pip install orewatch==<version> para CI y automatización fija.

Canal secundario disponible: el tap de Homebrew ya está disponible para usuarios de macOS que prefieren instalaciones gestionadas por Brew:```bash brew install rapticore/tap/orewatch

Homebrew sigue siendo una capa de conveniencia sobre la versión publicada en PyPI, no el artefacto de lanzamiento principal.

**Mejor opción para contribuidores:** mantener el flujo actual de checkout de código fuente:```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 .

Implementación administrada de macOS

Si está implementando OreWatch con Kandji, Jamf Pro, Intune, Munki u otro sistema de distribución de software para macOS, el modelo recomendado es diferente a la ruta del desarrollador pipx.

Realidad actual del producto:

• hoy el repositorio distribuye un paquete de Python, no un paquete de instalador de macOS notarizado de primera parte
• para flotas administradas, el artefacto recomendado es un .pkg plano firmado construido alrededor de la rueda publicada de OreWatch
• las instantáneas de datos de amenazas aún deben distribuirse por separado del paquete de aplicación/tiempo de ejecución

Modelo de implementación empresarial recomendado:

1. Instalación del dispositivo
   • implemente un .pkg firmado que instale el tiempo de ejecución de OreWatch y un shim CLI orewatch estable
   • opcionalmente incluya el extra mac-menubar si desea la aplicación nativa de la barra de menú en Macs administrados
2. Activación del usuario
   • ejecute orewatch monitor quickstart /path/to/project --client <client> o un bootstrap equivalente en contexto de usuario
   • este paso es separado porque el monitor de OreWatch es intencionalmente por usuario y usa un LaunchAgent de usuario más configuración/token/estado propiedad del usuario
3. Actualizaciones continuas
   • actualice el paquete de tiempo de ejecución en su ciclo de vida de software normal
   • actualice las instantáneas de datos de amenazas de forma independiente a través del canal de instantáneas firmado o la ruta de actualización en vivo

Por qué esta división es importante:

• Las herramientas MDM son buenas instalando código en la máquina
• El monitor de OreWatch, el token API y el servicio launchd están en el ámbito del usuario, por lo que deben crearse en el contexto del usuario conectado en lugar de forzarse desde una instalación de paquete a nivel de máquina

Forma de paquete recomendada para macOS administrado:

• un tiempo de ejecución dedicado bajo una ruta estable como /Library/Application Support/OreWatch/runtime
• un shim estable como /usr/local/bin/orewatch
• metadatos de paquete versionados para que las plataformas MDM puedan detectar actualizaciones limpiamente
• firma de código y notarización donde su política de flota lo espere

Guía específica para proveedores:

• Kandji
  • use una Aplicación Personalizada con un Paquete de Instalador (.pkg)
  • prefiera .pkg sobre .dmg o .zip para OreWatch porque el tiempo de ejecución no es una aplicación de arrastrar y soltar
  • use Self Service o un paso de incorporación orientado al usuario para la activación del monitor por primera vez
• Jamf Pro
  • cargue el .pkg como un Paquete e impleméntelo con una Política o Self Service
  • mantenga la activación del usuario separada de la implementación del paquete de la máquina a menos que tenga un paso de bootstrap deliberado en contexto de usuario
• Microsoft Intune
  • use una aplicación LOB de macOS con un .pkg firmado
  • Intune es más estricto que los otros canales: espera un .pkg real, firmado con un certificado Developer ID Installer, y el paquete debe contener una carga útil
• Munki
  • publique el .pkg más metadatos de pkg y trate a OreWatch como otro software administrado de macOS
  • Munki es una buena opción cuando desea un repositorio de paquetes y una adopción opcional al estilo Self Service

Para un manual de implementación más completo, consulte docs/managed-rollout.md.

Distribución recomendada de instantáneas

Las instantáneas de datos de amenazas no deben incluirse dentro del paquete de Python. Cambian en una cadencia diferente y ya son compatibles como artefactos firmados alojados.

Predeterminado de código abierto/comunidad: consuma openssf y osv directamente a través de la ruta de actualización en vivo con compuerta de anomalía. Predeterminado empresarial: publique instantáneas firmadas versionadas en un alojamiento HTTPS estático y permita que los clientes las actualicen de forma independiente.

Destinos de alojamiento recomendados:

• Assets de GitHub Releases
• S3 o Cloudflare R2 detrás de HTTPS
• Cualquier bucket respaldado por CDN estático que sirva archivos versionados inmutables

Diseño de instantánea recomendado:

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

Modelo de confianza recomendado:

• Mantenga la clave de firma privada fuera de línea
• Distribuya solo la clave de verificación pública con la configuración o el paquete del cliente
• Verifique cada descriptor de canal y manifiesto antes de la descarga/aplicación

Modelo general recomendado

Para un lanzamiento de producción, la configuración más limpia es:

• Distribuya la aplicación como un paquete PyPI
• Instale localmente con pipx
• Instale en CI con pip
• Distribuya los datos de amenazas como canales de instantáneas firmadas a través de HTTPS
• Trate la copia del código fuente como una ruta de desarrollo, no como la instalación principal para el usuario final

Registro y depuración

Por defecto, el escáner muestra solo advertencias, errores y el resumen final. Para solucionar problemas o realizar un seguimiento detallado del progreso, use las banderas de registro:

Modo detallado

Vea mensajes de progreso y estadísticas de recolección:```bash orewatch /path/to/project --verbose

**La salida incluye:**
- Resultados de detección de ecosistema
- Progreso de análisis de archivos
- Conteos de extracción de paquetes
- Detalles de consulta de base de datos
- Progreso de escaneo de IoC

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

Modo de depuración

Vea información detallada de diagnóstico para solucionar problemas:```bash orewatch /path/to/project --debug

**Output includes:**
- Todos los mensajes de nivel INFO
- Rutas de archivo siendo escaneadas
- Detalles de ejecución de consultas SQL
- Cálculos de hash
- Resultados de coincidencia de patrones
- Información de estado interno

**Use cases:**
- Investigar por qué no se detectó un paquete
- Depurar problemas de detección automática de ecosistemas
- Reportar problemas con contexto detallado
- Auditar el comportamiento del escáner

### Logging for Collectors

The threat intelligence collectors also support verbose and debug modes:```bash
cd collectors

# See collection progress
python3 orchestrator.py --verbose

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

Nota: Todos los registros van a stderr, manteniendo stdout limpio para la salida del informe JSON. Esto permite canalizar los resultados del escáner a otras herramientas sin interferencia de mensajes de registro.

Output & Reports

Report Structure

Los informes se guardan en el directorio scan-output/ por defecto (o en una ruta personalizada con --output). OreWatch escribe un informe JSON legible por máquina y un informe HTML complementario con estilo con el mismo nombre base. El artefacto JSON incluye metadatos de disponibilidad de datos de amenazas y utiliza objetos physicalLocation estilo SARIF para hallazgos de paquetes, pero no es un documento SARIF 2.1.0 completo.

Example 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" } ] }

**Campos de datos de amenazas:**
- `data_status`: `complete`, `partial`, `failed` o `not_applicable`
- `sources_used`: fuentes que contribuyeron con datos de amenazas utilizables para los ecosistemas solicitados
- `experimental_sources_used`: fuentes experimentales incluidas en los datos del escaneo
- `missing_ecosystems`: ecosistemas solicitados que no tenían una base de datos de amenazas de paquetes utilizable
- `promotion_decision`: vacío para escaneos de datos existentes, de lo contrario `promoted`, `bootstrapped` o `rejected`
- `kept_last_known_good`: `true` cuando un candidato en vivo fue rechazado pero el conjunto de datos activo anterior permaneció utilizable
- `anomalies`: anomalías de advertencia/bloqueo que surgieron durante un intento de actualización en vivo

### Interpretación de los resultados

**Niveles de severidad:**
- **CRITICAL:** Código malicioso conocido con exploits activos o exfiltración de datos
- **HIGH:** Indicadores sólidos de intención maliciosa o typosquatting
- **MEDIUM:** Patrones sospechosos o posibles vulnerabilidades
- **LOW:** Problemas menores o hallazgos informativos

**Acciones recomendadas:**
1. **Hallazgos críticos/altos:** Eliminar inmediatamente los paquetes afectados e investigar el impacto
2. **Revisar IoCs:** Verificar si se ha ejecutado código malicioso (registros, actividad de red)
3. **Actualizar dependencias:** Reemplazar paquetes maliciosos con alternativas legítimas
4. **Escanear de nuevo:** Verificar la remediación con un escaneo de seguimiento
5. **Reportar:** Considerar reportar a los mantenedores del registro de paquetes

---

## Integración CI/CD

### GitHub Actions

**Escaneo de seguridad básico:**```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/

Avanzado con fallo en la detección:```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 de pre-commit

Añadir 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"

Solución de problemas

Problemas comunes

Error "Database not found"

Síntoma:``` ERROR: No usable threat data available for requested ecosystems: npm

**Causa:** Falló la recolección de datos de amenazas, los metadatos están incompletos o los ecosistemas solicitados aún no tienen bases de datos locales utilizables.

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

Nota: Si esto persiste, verifique la conectividad de red, los permisos del sistema de archivos y si solicitó intencionadamente fuentes experimentales.

"No se detectaron paquetes" Advertencia

Síntoma:``` WARNING: No packages detected in /path/to/project

**Posibles causas y soluciones:**

1. **Directorio incorrecto:** Asegúrate de estar escaneando el directorio correcto del proyecto   ```bash
   ls /path/to/project  # Verify package.json or requirements.txt exists

2. Manifiesto no compatible o inesperado: Imprimir los nombres de archivo compatibles exactos ```bash orewatch --list-supported-files
   root@kitploit:~

3. Permisos de archivos: Asegúrate de que los archivos sean legibles ```bash ls -la /path/to/project/package.json
   root@kitploit:~

Errores de conexión durante la actualización

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

**Soluciones:**

1. **Verificar la conexión a internet:**   ```bash
   ping google.com

2. Reintentar con aumento de tiempo de espera: Editar collectors/config.yaml: ```yaml osv: timeout: 600 # Increase from default 300
   root@kitploit:~

3. Usar datos en caché: Si ha descargado datos previamente: ```bash python3 orchestrator.py --skip-build # Skip download, rebuild from cache
   root@kitploit:~

Errores de Permiso Denegado

Síntoma:``` ERROR: Error creating directory collectors/raw-data: Permission denied

**Solución:**```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 está usando demasiado disco

Síntoma: ~/Library/Application Support/OreWatch (macOS) o $XDG_STATE_HOME/orewatch (Linux) ha crecido hasta decenas de gigabytes.

Causa (anterior a 1.2.3): Cada promoción de actualización en vivo archivaba una copia completa de las bases de datos de datos de amenazas anteriores (~300 MB) sin retención. Un monitor de larga duración acumulaba una instantánea por ciclo indefinidamente.

Solución: Actualiza a 1.2.3 o posterior. Ahora las copias de seguridad son manifiestos SHA-256 de ~1 KB, la retención predeterminada es de las 30 más recientes, y hay un comando explícito de limpieza disponible:```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

#### Falsos Positivos

**Síntoma:** Paquete legítimo marcado como malicioso.

**Pasos:**

1. **Verificar el hallazgo:** Revisar los detalles del informe incluyendo la gravedad y la descripción

2. **Verificar la versión:** La versión marcada puede ser específica:   ```bash
   orewatch /path/to/project --verbose

3. Reportar falso positivo: Si se confirma incorrecto:
   • Abrir un issue en https://github.com/rapticore/ore-mal-pkg-inspector/issues con detalles

Modo de depuración para investigación

Habilitar registro detallado:```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

**Revise los registros:** Consulte `debug.log` para obtener un rastro detallado de ejecución, incluyendo:
- Rutas de archivos escaneadas
- Consultas SQL ejecutadas
- Resultados de coincidencia de patrones
- Trazas de pila de errores

---

## Preguntas frecuentes

### ¿Con qué frecuencia debo actualizar la inteligencia de amenazas?

**Recomendación:**
- **Entornos de producción/CI:** Actualizaciones automáticas diarias
- **Estaciones de trabajo de desarrollo:** Mínimo actualizaciones semanales
- **Después de noticias de seguridad:** Actualización inmediata cuando se anuncien nuevas amenazas

Los paquetes maliciosos se publican continuamente. Las actualizaciones diarias garantizan las protecciones más recientes.

### ¿Cómo actualizo los datos de inteligencia de amenazas?

Ejecute el escáner con la bandera `--latest-data` para forzar una actualización:```bash
orewatch /path/to/project --latest-data

Para actualizaciones automatizadas en CI/CD, programe escaneos periódicos con la bandera --latest-data (por ejemplo, diariamente). Agregue --include-experimental-sources solo si desea explícitamente que los datos derivados de Phylum se incluyan en la reconstrucción.

Nota: Los escaneos por primera vez recopilan datos automáticamente, por lo que las actualizaciones manuales solo son necesarias para actualizar las bases de datos existentes.

¿De dónde provienen los datos de amenazas?

Las bases de datos predeterminadas se construyen a partir de las fuentes principales de amenazas del proyecto:

• openssf
• osv

El escáner también puede incluir el conjunto de fuentes experimentales del proyecto:

• phylum con --include-experimental-sources

socketdev está presente en el repositorio como un marcador de posición deshabilitado y no forma parte de la ruta de recopilación predeterminada.

Para detalles técnicos sobre las fuentes de datos, la recopilación y el procesamiento, consulte ARCHITECTURE.md.

¿Modifica esta herramienta mi código o dependencias?

No. OreWatch realiza operaciones de solo lectura. Puede:

• ✅ Leer archivos de dependencias
• ✅ Consultar bases de datos de amenazas
• ✅ Escanear patrones de archivos
• ✅ Generar informes

Nunca:

• ❌ Modifica archivos de paquetes
• ❌ Instala o elimina paquetes
• ❌ Cambia la configuración del proyecto
• ❌ Ejecuta código de paquetes

¿Qué pasa si mi paquete es marcado como malicioso?

Pasos a seguir:

1. Verifique el hallazgo: Revise el informe para obtener detalles y gravedad
2. Revise la evidencia: Examine la descripción y los comportamientos detectados
3. Verifique las versiones: Determine si versiones específicas están afectadas
4. Si es legítimo:
   • Reporte falso positivo a los mantenedores de la fuente de datos
   • Abra un problema en nuestro GitHub con detalles
5. Si es realmente malicioso:
   • Elimine el paquete inmediatamente
   • Revise los commits recientes en busca de daños
   • Verifique los registros en busca de actividad sospechosa
   • Actualice a una alternativa segura

¿Puedo usar esto sin conexión?

Parcialmente.

Escaneo sin conexión: ✅ Sí, una vez que las bases de datos estén inicializadas```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

**Actualizaciones sin conexión:** ❌ No, la recopilación de inteligencia de amenazas requiere acceso a internet para obtenerla de fuentes de seguridad.

**Entornos aislados:** Puedes:
1. Descargar bases de datos en una máquina con conexión a internet
2. Transferir los archivos SQLite al directorio singleton `final_data_dir` mostrado por `orewatch monitor doctor`
3. Ejecutar escaneos sin conexión con datos potencialmente desactualizados

### ¿Cómo se compara esto con npm audit o pip-audit?

**Propósitos diferentes:**

**npm audit / pip-audit:**
- Se centran en vulnerabilidades CVE conocidas
- Verifican versiones de paquetes contra bases de datos de avisos
- Mantenidos por los equipos de los registros de paquetes

**OreWatch:**
- Se centra en paquetes maliciosos (no solo vulnerables)
- Detecta typosquatting, malware, ataques a la cadena de suministro
- Cobertura entre ecosistemas
- Detección de IoC para amenazas activas

**Mejor práctica:** Usa **ambos**:```bash
# Check for vulnerabilities
npm audit
pip-audit

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

¿Funciona esto con registros de paquetes privados?

Escaneo de dependencias: ✅ Sí, el escáner lee tus archivos de dependencia sin importar de dónde provengan los paquetes.

Inteligencia de amenazas: ⚠️ Limitada. Nuestras bases de datos cubren registros públicos (npmjs.com, pypi.org, etc.). Los paquetes maliciosos en registros privados no se detectarán a menos que añadas datos de amenazas personalizados.

Datos de amenazas personalizados: Puedes ampliar las bases de datos con tus propias listas de paquetes maliciosos. Contáctanos para obtener orientación sobre este caso de uso avanzado.

¿Cuál es el impacto en el rendimiento?

Tiempo de escaneo:

• Proyectos pequeños (< 50 paquetes): < 5 segundos
• Proyectos medianos (50-500 paquetes): 5-30 segundos
• Proyectos grandes (500+ paquetes): 30-120 segundos

Factores:

• El escaneo de IoC añade un 10-50% de sobrecarga (deshabilítalo con --no-ioc si no es necesario)
• La primera ejecución puede ser más lenta mientras las bases de datos se cargan en memoria

Consejos de optimización:```bash

Scan specific files instead of entire directory

orewatch --file package.json

---

## Contribuciones

¡Agradecemos las contribuciones! Ya sea que reportes errores, sugieras funciones o contribuyas con código, tu ayuda mejora OreWatch para todos.

**Reportar errores o solicitar funciones:**
- GitHub Issues: https://github.com/rapticore/ore-mal-pkg-inspector/issues

**Contribuir código:**
- Consulta [CONTRIBUTING.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/CONTRIBUTING.md) para obtener pautas detalladas sobre configuración de desarrollo, estilo de código, pruebas y proceso de solicitudes de extracción (pull requests).

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

---

## Política de Seguridad

La seguridad es nuestra máxima prioridad. OreWatch es una herramienta de seguridad y nos tomamos las vulnerabilidades muy en serio.

### Reportar Vulnerabilidades de Seguridad

**NO abras issues públicos de GitHub por vulnerabilidades de seguridad.**

En su lugar, reporta de forma privada:

**Correo electrónico:** [email protected]

**Incluye:**
- Descripción de la vulnerabilidad
- Pasos para reproducir
- Impacto potencial
- Corrección sugerida (si aplica)
- Tu información de contacto para seguimiento

### Cronograma de Respuesta

- **Acuse de recibo:** Dentro de 48 horas
- **Evaluación inicial:** Dentro de 7 días
- **Cronograma de corrección:** Varía según la gravedad
  - Crítica: 7-14 días
  - Alta: 14-30 días
  - Media/Baja: 30-60 días

### Buenas Prácticas de Seguridad

Al usar OreWatch:

**Sí:**
- ✅ Ejecuta con el menor privilegio (no requiere root/admin)
- ✅ Actualiza la inteligencia de amenazas regularmente
- ✅ Revisa los informes de escaneo rápidamente
- ✅ Integra en CI/CD para protección continua
- ✅ Mantén la herramienta actualizada a la última versión

**No:**
- ❌ Ignorar hallazgos de escaneo sin investigación
- ❌ Deshabilitar el escaneo de IoC en entornos de producción
- ❌ Compartir archivos de base de datos de fuentes no confiables
- ❌ Ejecutar con privilegios elevados innecesariamente

### Divulgación de Vulnerabilidades

Seguimos una divulgación coordinada:
1. La vulnerabilidad se reporta de forma privada
2. Se desarrolla y prueba la corrección
3. Se publica un aviso de seguridad
4. Divulgación pública después de que la corrección esté disponible

### Salón de la Fama de Seguridad

Reconocemos a los investigadores de seguridad que divulgan responsablemente vulnerabilidades:

*La lista se mantendrá a medida que se reciban reportes*

---

### Solicitudes de la Comunidad

Vota o sugiere funciones:
- **GitHub Discussions:** https://github.com/rapticore/ore-mal-pkg-inspector/discussions
- **Feature Requests:** https://github.com/rapticore/ore-mal-pkg-inspector/issues

### Contribuir a la Hoja de Ruta

Priorizamos funciones basándonos en:
- Impacto en seguridad
- Demanda de la comunidad
- Sostenibilidad del mantenimiento
- Alineación con los objetivos del proyecto

Para influir en la hoja de ruta:
1. Abre una solicitud de función con un caso de uso detallado
2. Participa en discusiones
3. Contribuye con implementaciones (¡PRs bienvenidos!)

---

## Hoja de Ruta

OreWatch es utilizable hoy para:

- escaneos CLI locales en npm, PyPI, Maven, RubyGems, Go y Cargo
- un monitor en segundo plano por usuario para muchos proyectos
- integraciones MCP para Cursor, Claude Code y Codex
- integraciones API localhost para ayudantes de VS Code, JetBrains / PyCharm y Xcode
- revisión de la barra de menú de macOS y notificaciones emergentes

Prioridades a corto plazo:

- ejemplos de integración de primera parte o plugins ligeros para VS Code y JetBrains / PyCharm
- flujos de trabajo de notificaciones más sólidos para el usuario más allá de las ventanas emergentes locales
- gestión de políticas de proyecto más clara desde CLI y UI
- informes de monitoreo más completos y documentación de adopción

Prioridades a medio plazo:

- flujos de trabajo de escaneo de proyectos más amplios desde el monitor y la superficie MCP
- mejor guía de implementación a nivel de organización
- canales de entrega de alertas externas y escalado más robustos
- UX más profunda específica del IDE en lugar de guía de integración solo API

Límite actual conocido:

- La integración con Xcode es actualmente la mejor para visibilidad de alertas y repositorios con múltiples lenguajes. OreWatch aún no analiza manifiestos nativos de Apple como `Package.resolved`, `Podfile.lock` o `Cartfile`.

Dirección a largo plazo:

- soporte de manifiestos nativos del ecosistema Apple
- integraciones de editores de primera parte más sólidas
- paridad de UX de sistema operativo más amplia más allá de la ruta actual de la barra de menú de macOS

Consulta [docs/roadmap.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/roadmap.md) para la vista de hoja de ruta más centrada en la adopción.

---

## Licencia

Licencia MIT

Copyright (c) 2025 Rapticore

Por la presente se concede permiso, libre de cargos, a cualquier persona que obtenga una copia de este software y de los archivos de documentación asociados (el "Software"), para tratar el Software sin restricción, incluyendo sin limitación los derechos de uso, copia, modificación, fusión, publicación, distribución, sublicencia, y/o venta de copias del Software, y para permitir a las personas a las que se les proporcione el Software hacer lo mismo, sujeto a las siguientes condiciones:

El aviso de copyright anterior y este aviso de permiso deberán incluirse en todas las copias o partes sustanciales del Software.

EL SOFTWARE SE PROPORCIONA "TAL CUAL", SIN GARANTÍA DE NINGÚN TIPO, EXPRESA O IMPLÍCITA, INCLUYENDO PERO NO LIMITADO A LAS GARANTÍAS DE COMERCIABILIDAD, IDONEIDAD PARA UN PROPÓSITO PARTICULAR Y NO INFRACCIÓN. EN NINGÚN CASO LOS AUTORES O TITULARES DEL COPYRIGHT SERÁN RESPONSABLES POR CUALQUIER RECLAMO, DAÑOS U OTRA RESPONSABILIDAD, YA SEA EN UNA ACCIÓN DE CONTRATO, AGRAVIO O CUALQUIER OTRO MOTIVO, QUE SURJA DE O EN CONEXIÓN CON EL SOFTWARE O EL USO U OTRO TIPO DE ACCIONES EN EL SOFTWARE.

---

## Soporte

### Obtener Ayuda

**Documentación:** ¡La estás leyendo! Comienza aquí para la mayoría de las preguntas.

**Discusiones de GitHub:** Para preguntas, ideas e interacción comunitaria:
- https://github.com/rapticore/ore-mal-pkg-inspector/discussions

**Issues de GitHub:** Para reportes de errores y solicitudes de funciones:
- https://github.com/rapticore/ore-mal-pkg-inspector/issues

**Correo electrónico:** Para vulnerabilidades de seguridad y consultas privadas:
- [email protected]

### Soporte Profesional

Para organizaciones que requieren:
- Integraciones personalizadas
- Soporte con SLA
- Asistencia para despliegue privado
- Fuentes de inteligencia de amenazas personalizadas

Contacto: [email protected]

---

## Agradecimientos

### Origen del Proyecto

Este proyecto fue extraído del repositorio [OreNPMGuard](https://github.com/rapticore/OreNPMGuard) para mantener un enfoque claro del proyecto mientras se expanden las capacidades.

**OreNPMGuard** (diciembre de 2025) se especializa en la detección de ataques Shai-Hulud npm con más de 738 paquetes afectados y análisis profundo de IoC. Durante su desarrollo, reconocimos la necesidad de una protección más amplia en múltiples ecosistemas, lo que llevó a la creación de OreWatch como una herramienta independiente que sirve a la comunidad de desarrolladores en todos los ecosistemas de paquetes principales.

### Proyectos Relacionados

- **[OreNPMGuard](https://github.com/rapticore/OreNPMGuard)** - Escáner especializado Shai-Hulud npm

---

**Construido por el Equipo de Investigación de Seguridad de Rapticore**

*Protegiendo las cadenas de suministro de software, un escaneo a la vez.*