OreWatch

Scanner de Deteção de Pacotes Maliciosos Multi-Ecossistema e Segurança na Cadeia de Suprimentos

Uma ferramenta de segurança de nível de produção para detetar pacotes maliciosos e ameaças à cadeia de suprimentos nos ecossistemas npm, PyPI, Maven, RubyGems, Go e Cargo. Utiliza recolha automatizada de inteligência de ameaças a partir de fontes de segurança confiáveis para identificar dependências comprometidas nos seus projetos.

OreWatch é o nome do produto e do pacote PyPI. O caminho atual do repositório fonte ainda usa ore-mal-pkg-inspector.

Vídeos

Instalação

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

OreWatch e Cursor

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

OreWatch e CodeX

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

OreWatch e Claude-Code

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

Índice

• O Problema
• A Solução
• Funcionalidades Principais
• Porquê OreWatch?
• Comece por Aqui
• Início Rápido
  • Pré-requisitos
  • Instalação
  • Primeira Verificação
• Uso
  • Comandos Básicos
  • Uso Avançado
  • Referência da Linha de Comando
  • Monitorização em Segundo Plano
• Guia de Adoção
• Distribuição
  • Implementação Gerida no macOS
• Registo e Depuração
• Saída e Relatórios
• Integração CI/CD
• Resolução de Problemas
• Perguntas Frequentes
• Contribuição
• Política de Segurança
• Roteiro
• Licença
• Suporte
• Agradecimentos

O Problema

Os ataques à cadeia de suprimentos são agora o principal vetor de ameaças para comprometimento de software. Apenas em 2024, milhares de pacotes maliciosos foram publicados em npm, PyPI e outros registos de pacotes, visando programadores com typosquatting, confusão de dependências e campanhas sofisticadas de malware como Shai-Hulud.

O desafio: Organizações e programadores precisam de:

• Examinar dependências em vários ecossistemas de programação
• Manter-se atualizados com a inteligência de ameaças em rápida evolução de múltiplas fontes
• Detetar não apenas pacotes maliciosos conhecidos, mas também indicadores de compromisso (IoCs)
• Integrar a verificação de segurança nos fluxos de trabalho de desenvolvimento existentes
• Responder rapidamente a ameaças recentemente descobertas

A lacuna: As soluções existentes são frequentemente:

• Limitadas a um único ecossistema (apenas npm, apenas PyPI, etc.)
• Dependentes da manutenção manual de listas de ameaças
• Carentes de capacidades de deteção de IoCs
• Difíceis de integrar em pipelines automatizadas
• Ferramentas proprietárias de caixa-preta sem transparência

A Solução

OreWatch aborda estes desafios fornecendo:

Cobertura Abrangente Multi-Ecossistema: Uma única ferramenta para pacotes npm, PyPI, Maven, RubyGems, Go e Cargo

Inteligência de Ameaças Automatizada: Recolhe e combina dinamicamente dados de fontes confiáveis de pesquisa em segurança

Deteção Ativa de IoCs: Identifica padrões de ataque Shai-Hulud e outros indicadores de código malicioso para além da correspondência de nomes de pacotes

Pronto para CI/CD: Projetado para integração perfeita em GitHub Actions, GitLab CI, Jenkins e outras plataformas de automação

Código Aberto e Transparente: Visibilidade completa na lógica de deteção, fontes de dados e metodologia de verificação

Funcionalidades Principais

Suporte Multi-Ecossistema Examina pacotes npm, PyPI, Maven, RubyGems, Go e Cargo com deteção automática de ecossistema a partir da estrutura do projeto.

Base de Dados Unificada de Inteligência de Ameaças Verifica contra bases de dados de pacotes maliciosos recolhidos dinamicamente de fontes confiáveis de pesquisa em segurança.

Deteção Automática de Ecossistema Identifica inteligentemente ecossistemas a partir da estrutura de diretórios, nomes de ficheiros e pode examinar vários ecossistemas numa única execução.

Deteção de Indicadores de Compromisso (IoCs) Examina padrões de ataque Shai-Hulud (variantes original e 2.0), hooks maliciosos, workflows suspeitos e ficheiros payload conhecidos.

Integração Shai-Hulud Cruza referências de pacotes npm com a lista abrangente de pacotes afetados por Shai-Hulud do OreNPMGuard.

Relatórios JSON Estruturados Gera relatórios JSON legíveis por máquina com metadados explícitos de dados de ameaças e localizações de ficheiros no estilo SARIF para as descobertas.

Formatos de Entrada Flexíveis Suporta ficheiros de dependência padrão (package.json, requirements.txt, etc.) e listas genéricas de pacotes (texto, JSON, YAML).

Registo Pronto para Produção Níveis de verbosidade configuráveis com sinalizadores --verbose e --debug para resolução de problemas e trilhos de auditoria.

Seguro e Rápido Operações apenas de leitura sem modificações no seu código, otimizado para examinar grandes bases de código eficientemente.

Porquê OreWatch?

vs. Ferramentas de Ecossistema Único A maioria dos scanners de segurança concentra-se num gestor de pacotes. OreWatch oferece proteção unificada em seis grandes ecossistemas, essencial para ambientes de desenvolvimento poliglotas modernos.

vs. Listas de Ameaças Manuais Listas estáticas de pacotes maliciosos tornam-se rapidamente desatualizadas. Os nossos coletores automatizados obtêm inteligência de ameaças fresca diariamente de múltiplas fontes autoritativas.

vs. Deteção Apenas por Nome de Pacote Verificar apenas nomes de pacotes ignora ataques sofisticados. A deteção de IoCs identifica padrões de código malicioso mesmo em pacotes ainda não listados em listas de bloqueio.

vs. Auditorias de Segurança Manuais As revisões manuais de dependências consomem tempo e são propensas a erros. A verificação automatizada permite validação contínua de segurança em cada compilação.

vs. Ferramentas Comerciais de Caixa-Preta Ferramentas proprietárias carecem de transparência na lógica de deteção. Como projeto de código aberto, cada regra de deteção e fonte de dados é auditável.

História de Origem OreWatch nasceu do desenvolvimento do OreNPMGuard, um scanner especializado para ataques Shai-Hulud no npm. Durante esse projeto, reconhecemos a necessidade de uma cobertura multi-ecossistema mais ampla para além do npm. Em dezembro de 2025, extraímos e aprimorámos as capacidades de deteção multi-ecossistema nesta ferramenta independente, mantendo o foco do OreNPMGuard no npm enquanto permitimos que o OreWatch sirva a comunidade mais ampla de programadores em todos os principais ecossistemas de pacotes.

Comece por Aqui

Se está a adotar o OreWatch pela primeira vez, escolha o caminho mais pequeno que corresponda ao seu fluxo de trabalho:

Sequência recomendada para primeira execução para a maioria dos programadores:

1. Instale o OreWatch com pip install . ou o pacote publicado.
2. Execute orewatch monitor quickstart /caminho/para/projeto --client <seu-cliente>.
3. Verifique o daemon com orewatch monitor status.
4. Se estiver no macOS, lance orewatch monitor menubar para notificações e uma interface local.

Se desejar um guia de configuração mais curto com comandos para copiar e colar, use docs/adoption-guide.md.

Início Rápido

Pré-requisitos

• Python 3.14 ou superior
• pip para instalar dependências
• Git para clonar o repositório
• Conexão à Internet para configuração inicial de inteligência de ameaças
• OpenSSL para geração de chaves de snapshots assinados, publicação e verificação em fluxos de trabalho de snapshots do monitor

Instalação

O OreWatch pode ser instalado via pipx (recomendado), Homebrew (macOS), pip, ou a partir do código fonte. Todos os métodos produzem o comando CLI orewatch.

Opção 1 — pipx (Recomendado)

pipx instala o OreWatch no seu próprio ambiente isolado enquanto torna o comando orewatch disponível globalmente. Esta é a melhor opção para a maioria dos programadores.```bash

Install pipx if you don't have it

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

Install OreWatch

pipx install --python python3.14 orewatch

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

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

Verify

orewatch --help

Optional macOS menu bar app

orewatch monitor menubar

Se você já instalou `orewatch` com pipx e deseja adicionar o aplicativo da barra de menus do macOS posteriormente, injete as ligações Cocoa no mesmo ambiente pipx:```bash
pipx inject orewatch pyobjc-framework-Cocoa

Atualização:```bash pipx upgrade orewatch

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

Opção 2 — Homebrew (macOS)

Para usuários de macOS que preferem instalações gerenciadas pelo 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

**Atualização:**```bash
brew update && brew upgrade orewatch

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

> **Nota:** A fórmula do Homebrew inclui as bindings Cocoa necessárias para
> `orewatch monitor menubar`. Se uma instalação antiga do Homebrew relatar
> `ModuleNotFoundError: No module named 'AppKit'`, execute
> `brew update && brew reinstall rapticore/tap/orewatch` para que a fórmula reconstrua
> seu ambiente Python isolado com suporte à barra de menu.

#### Opção 3 — pip

Use `pip` para pipelines de CI, imagens Docker, ou quando você gerencia seus próprios
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

Atualização:```bash python3.14 -m pip install --upgrade orewatch

#### Opção 4 — Checkout da Fonte (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

Verificação Pós-Instalação

Após instalar com qualquer método, confirme que o OreWatch está funcionando:```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 sobre as Plataformas

| Plataforma | Fonte Python | Notas |
|---|---|---|
| **macOS** (Homebrew Python) | `brew install [email protected]` | Recomendado para utilizadores do Homebrew |
| **macOS** (pyenv) | `pyenv install 3.14` | Melhor para configurações com múltiplas versões |
| **Ubuntu / Debian** | `sudo apt install python3.14` ou pyenv | Verifique se sua distribuição inclui 3.14+ |
| **Fedora / RHEL** | `sudo dnf install python3.14` ou pyenv | — |
| **Windows (WSL)** | pyenv ou pacote do sistema | Windows nativo não foi testado |

> **Python 3.14 é obrigatório.** O OreWatch utiliza funcionalidades da linguagem introduzidas no
> Python 3.14. Versões mais antigas falharão na importação.

#### Resolução de Problemas na Instalação

| Sintoma | Solução |
|---|---|
| `command not found: orewatch` | Certifique-se de que o local de instalação está no seu `PATH`. Para pipx: execute `pipx ensurepath` e reinicie o seu shell. |
| `ModuleNotFoundError` na importação | Pode ter várias versões do Python. Confirme que o runtime por trás do `orewatch` é Python 3.14+ e reinstale com o interpretador correspondente. |
| A instalação do pipx falha com erros de resolução | Atualize o pipx: `python3.14 -m pip install --upgrade pipx` |
| O Homebrew `orewatch` não é encontrado após a instalação | Execute `brew tap rapticore/tap` primeiro e depois tente novamente a instalação. |
| Permissão negada durante a instalação com pip | Use `pip install --user orewatch` ou instale dentro de um ambiente virtual. |

_Nota: Se os dados de ameaças locais estiverem ausentes ou desatualizados, as análises de pacotes colocam em cena um candidato a atualização ao vivo e só o promovem após os portões de anomalia passarem. Se o candidato parecer suspeito, o OreWatch mantém o conjunto de dados do último conhecido como bom ativo._

_CLI instalada:_ `orewatch`
_Alias de compatibilidade:_ `ore-mal-pkg-inspector`

### Primeira Análise

**Analisar um diretório de projeto:**```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

Saída 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

Se você quiser que o OreWatch continue observando o projeto após esta primeira verificação, continue com [Monitoramento em Segundo Plano](#background-monitoring) ou vá direto para [docs/adoption-guide.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/adoption-guide.md).

---

## Uso

### Comandos Básicos

**Escaneie Diretório (Detecção automática de ecossistema):**```bash
# Current directory
orewatch .

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

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

Escanear Arquivos de Dependência 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

**Forçar Ecossistema 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 Pacotes Genéricas:```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 Avançado

**Caminho de Saída Personalizado:**```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

Controle de Varredura 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 Dados de Ameaças:```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

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

Referência da Linha de Comando

Opções do Scanner

Monitoramento em Segundo Plano

O repositório agora inclui um monitor de segundo plano local que mantém os dados de ameaça atualizados, monitora projetos que optaram por participar em busca de alterações no manifesto e no fluxo de trabalho, executa verificações com debounce e registra notificações para descobertas novas ou em escopo. A configuração e o estado de propriedade do monitor são armazenados fora do repositório, em diretórios de propriedade do usuário, para que um repositório clonado não possa pré-selecionar o comportamento do monitor.

O OreWatch agora trata o monitor como um singleton por usuário. Um único daemon pode monitorar muitos projetos em qualquer lugar do disco e atender a vários clientes simultâneos de Claude Code, Codex, Cursor, VS Code, JetBrains / PyCharm e Xcode.

Configuração Completa do Monitor

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

First project + first client

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

`monitor quickstart` é o fluxo recomendado para primeira execução. Ele:

- instala ou atualiza o serviço monitor singleton
- inicia o monitor se necessário
- adiciona o projeto alvo à lista de observação
- imprime o bloco de inicialização para o cliente selecionado

Se preferir instalar o monitor primeiro e conectar os clientes depois:```bash
orewatch monitor install
orewatch monitor install --ide-bootstrap
orewatch monitor install --service-manager launchd --no-start

2. Verifique se o monitor está funcionando corretamente```bash orewatch monitor status orewatch monitor connection-info orewatch monitor doctor

Use estes comandos para tarefas ligeiramente diferentes:

- `monitor status` mostra se o daemon singleton e a API estão em execução
- `monitor connection-info` imprime a URL da API de loopback, o caminho do token, o diretório base do monitor e os clientes de bootstrap suportados
- `monitor doctor` imprime os caminhos exatos da configuração, banco de dados de estado, log e dados de ameaças compartilhados

**3. Adicione todos os projetos que deseja que o singleton monitore**```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

Um daemon OreWatch pode monitorar todos esses projetos de uma só vez. Você não precisa de um monitor separado por repositório ou por espaço de trabalho da IDE.

Receitas de Integração de Cliente

OreWatch suporta dois transportes de integração:

Os comandos de inicialização imprimem uma destas formas:```json { "mcpServers": { "orewatch": { "command": "/absolute/path/to/orewatch", "args": [ "monitor", "mcp" ] } } }

Quando `orewatch monitor ide-bootstrap --client <client>` consegue resolver o script do console local, agora emite esse caminho absoluto em vez de `orewatch` simples. Se você tiver uma configuração MCP antiga que ainda diz `"command": "orewatch"`, regenere-a e substitua a entrada antiga.```json
{
  "orewatch": {
    "baseUrl": "http://127.0.0.1:48736",
    "tokenPath": "/path/to/api.token"
  }
}

Cursor, Claude Code, and Codex

Todos esses clientes utilizam a mesma ponte MCP local:```bash orewatch monitor mcp

Configuração recomendada:

1. Execute `orewatch monitor quickstart /path/to/project --client <cursor|claude_code|codex>` uma vez.
2. Copie o bloco MCP impresso para o cliente MCP correspondente.
3. Abra um projeto monitorado nesse cliente.
4. Deixe o cliente chamar OreWatch via 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` é um servidor stdio. Se você o iniciar manualmente, ele parecerá ocioso enquanto aguarda um cliente MCP.
- A ponte MCP verifica a API local na inicialização e pode iniciar automaticamente o monitor singleton uma vez quando `auto_start_on_client` estiver ativado.
- Para uma inicialização confiável da IDE, instale o monitor de fundo uma vez com `monitor install` para que o daemon já esteja disponível antes da ponte MCP iniciar.

##### VS Code

As integrações do VS Code devem usar a API localhost singleton em vez da ponte MCP.

Configuração recomendada:

1. Execute `orewatch monitor quickstart /path/to/project --client vscode`.
2. Copie o `baseUrl` e `tokenPath` de `orewatch monitor ide-bootstrap --client vscode`.
3. Conecte esses valores na sua extensão, tarefa ou auxiliar local do VS Code.
4. Chame a API nos eventos de adição de dependência, salvamento de manifesto e atualização de alerta.

Uso recomendado da API para uma integração com VS Code:

- chame `POST /v1/check/dependency-add` antes dos fluxos de instalação/adição do gerenciador de pacotes
- chame `POST /v1/check/manifest` quando um manifesto suportado for salvo ou reexaminado explicitamente
- consulte `GET /v1/findings/active` e `GET /v1/notifications` para exibir detecções em segundo plano

##### JetBrains / PyCharm

JetBrains e PyCharm usam o mesmo contrato de API localhost que o VS Code.

Configuração recomendada:

1. Execute `orewatch monitor quickstart /path/to/project --client jetbrains`.
2. Copie o bloco de API de `orewatch monitor ide-bootstrap --client jetbrains`.
3. Use o `baseUrl` e `tokenPath` retornados em um plugin JetBrains, ferramenta externa ou auxiliar local.
4. Exiba tanto as decisões síncronas de dependência quanto os alertas de fundo armazenados dentro da IDE.

Uso recomendado da API para uma integração com JetBrains:

- verifique adições de dependência com `POST /v1/check/dependency-add`
- reexamine `package.json`, `requirements.txt`, `pyproject.toml`, `pom.xml`, `Gemfile`, `go.mod`, `Cargo.toml` e manifestos suportados relacionados com `POST /v1/check/manifest`
- obtenha `GET /v1/findings/active` e `GET /v1/notifications` para painéis de alerta persistentes ou janelas de ferramentas

##### Xcode

As integrações com Xcode também devem usar a API localhost singleton, mas há um limite de escopo importante: OreWatch ainda não analisa manifestos de dependência nativos da Apple, como `Package.resolved`, `Podfile.lock` ou `Cartfile`. Hoje, a integração com Xcode é melhor para:

- exibir descobertas e notificações de fundo em um auxiliar, script ou aplicativo complementar
- repositórios de linguagem mista abertos no Xcode que também contêm manifestos suportados, como `package.json`, `pyproject.toml` ou `Cargo.toml`
- equipes que desejam o aplicativo da barra de menus do macOS e alertas da Central de Notificações enquanto trabalham no Xcode

Configuração recomendada:

1. Execute `orewatch monitor quickstart /path/to/project --client xcode`.
2. Copie o bloco de API de `orewatch monitor ide-bootstrap --client xcode`.
3. Use o `baseUrl` e `tokenPath` retornados de um script de fase de construção, um processo auxiliar ou uma integração personalizada do Xcode.
4. Consulte `GET /v1/findings/active` e `GET /v1/notifications` para alertas visíveis ao usuário.
5. Se o espaço de trabalho do Xcode contiver manifestos suportados não-Apple, chame `POST /v1/check/manifest` para esses arquivos como parte do seu fluxo de trabalho.

Status atual da integração:

- Claude Code, Codex e Cursor: ponte MCP de primeira classe incluída neste repositório
- VS Code: contrato de API local documentado, mas nenhuma extensão de primeira parte agrupada ainda
- JetBrains / PyCharm: contrato de API local documentado, mas nenhum plugin de primeira parte agrupado ainda
- Xcode: API local e integração com barra de menus documentadas, mas nenhuma extensão de primeira parte do Xcode e nenhum analisador de manifesto nativo da Apple ainda

#### Quando OreWatch Encontra Algo

Quando o monitor de fundo detecta um pacote comprometido ou IoC em um projeto monitorado, OreWatch:

- escreve relatórios JSON e HTML gerenciados pelo monitor no diretório `reports/` do monitor singleton
- armazena a descoberta ativa no banco de dados de estado do monitor
- armazena uma entrada de notificação com uma mensagem acionável
- emite um aviso no terminal se as notificações do terminal estiverem ativadas
- no macOS, prefere o aplicativo da barra de menus singleton como canal de pop-up quando está em execução
- mantém o alerta mais recente digno de atenção fixado no topo do menu suspenso da barra de menus para revisão rápida
- caso contrário, recorre a uma notificação direta de desktop de melhor esforço se as notificações de desktop estiverem ativadas
- pode enviar uma notificação opcional via webhook para ambientes remotos ou headless

Use a superfície de revisão interna da CLI para inspecionar esses 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

A API local e a ponte MCP expõem os mesmos dados para IDEs e 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

Este é o caminho suportado para IDEs, clientes MCP e agentes de codificação exibirem detecções em segundo plano após a varredura original ter sido concluída.

Os avisos de atualização de pacotes são apenas notificativos. O OreWatch informa versões mais recentes para dependências de projetos monitorados e para o próprio OreWatch, mas não modifica manifestos, arquivos de bloqueio (lockfiles) ou pacotes instalados.

Aplicativo Nativo da Barra de Menu do macOS

O OreWatch agora inclui um aplicativo nativo da barra de menu do macOS para pessoas que desejam uma interface local visível em vez de depender apenas de comandos CLI, consultas MCP ou popups do Centro de Notificações de melhor esforço.

Instale as ligações opcionais do Cocoa no mesmo ambiente de execução que fornece o comando orewatch. Escolha o comando que corresponde ao seu método de instalação:```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

Em seguida, inicie o aplicativo da barra de menu:```bash
orewatch monitor menubar

Por padrão, monitor menubar reinicia o aplicativo em segundo plano e retorna imediatamente ao prompt do shell. Use orewatch monitor menubar --foreground apenas quando você explicitamente quiser mantê-lo anexado ao terminal para depuração.

O aplicativo da barra de menus se anexa ao mesmo monitor singleton. Ele não inicia uma segunda instância do monitor. Se o monitor ainda não estiver instalado e em execução, o aplicativo irá instalá-lo/iniciá-lo no primeiro lançamento.

O Homebrew instala as ligações Cocoa no ambiente isolado libexec do OreWatch. Se orewatch monitor menubar reportar No module named 'AppKit', atualize a fórmula com brew update && brew reinstall rapticore/tap/orewatch. Para instalações via pip, pipx e fonte, as ligações opcionais ainda precisam ser adicionadas ao mesmo ambiente Python que fornece o comando orewatch.

Quando as notificações de desktop estão habilitadas no macOS, o watcher singleton agora mantém um aplicativo singleton da barra de menus ativo e o utiliza como superfície primária de pop-up. Isso evita depender apenas de uma invocação osascript destacada do daemon e fornece uma interface nativa persistente para novas descobertas.

A versão atual da barra de menus é focada em ícone primeiro. A antiga abreviatura OW e a redação anterior do ícone do OreWatch devem ser tratadas como referências legadas; o aplicativo agora prefere o ícone com marca incorporado e recorre a texto compacto ou emblemas apenas quando o macOS não consegue renderizar a imagem ou precisa de uma contagem de alerta.

O que o aplicativo da barra de menus do macOS oferece:

• um item de status persistente na barra de menus que prefere o ícone com marca incorporado, com fallback de texto compacto ou emblemas de alerta quando necessário
• um estado de alerta compacto em vermelho/negrito para alertas recém-detectados que permanece visível até que você abra o menu
• um resumo ao vivo de descobertas ativas e maior gravidade
• uma seção de Atualizações de Pacotes de primeira classe com atualizações de dependências do projeto, estado de autoatualização do OreWatch, status da última verificação e comandos sugeridos copiáveis
• notificações recentes em um menu suspenso nativo
• pop-ups nativos da Central de Notificações para alertas de monitor recém-armazenados
• uma ação Add Workspace Folder... que inscreve um projeto no watcher singleton e executa uma varredura rápida inicial
• alternâncias de configuração incorporadas para notificações de desktop, notificações de terminal, keepalive da barra de menus e popups acionados pela barra de menus
• ações com um clique para abrir relatórios, página inicial do monitor e o log do monitor
• ações com um clique para abrir o arquivo de configuração do monitor e a pasta de configuração
• ações de menu para verificar atualizações de pacotes, atualizar inteligência de ameaças, executar varreduras rápidas/completas e iniciar/reiniciar/parar o monitor singleton

Fluxo recomendado para Mac:

1. Execute orewatch monitor quickstart /caminho/para/projeto --client claude_code uma vez.
2. Instale as ligações opcionais no mesmo ambiente que o orewatch.
3. Inicie orewatch monitor menubar.
4. Mantenha o aplicativo da barra de menus em execução para uma superfície de revisão nativa persistente enquanto seus IDEs e agentes de codificação continuam usando MCP ou a API local.

Guia de Adoção

Para uma implantação mais fácil, use os documentos focados em vez de ler o README completo do início ao fim:

• docs/adoption-guide.md: caminho mais curto para adoção por desenvolvedores locais
• docs/local-api.md: contrato exato da API local e MCP
• docs/e2e-testing.md: fluxo de trabalho para contribuidores e validação

Ordem de adoção recomendada:

1. Comece com um repositório e um usuário.
2. Habilite o monitor singleton com monitor quickstart.
3. Conecte um cliente: Cursor, Claude Code, Codex, VS Code, PyCharm ou Xcode.
4. Confirme que as descobertas aparecem em orewatch monitor findings e orewatch monitor notifications.
5. No macOS, adicione monitor menubar para que os usuários obtenham uma superfície de revisão persistente e entrega de pop-ups.
6. Após a adoção local estar estável, adicione varreduras CI e webhooks opcionais.

Operações Diárias

Comandos operacionais comuns:```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

**Ações manuais de snapshot e assinatura:**```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

Monitor behavior:

• Varreduras rápidas são focadas em pacotes e executadas em um cronograma e após alterações genéricas de manifesto.
• Varreduras completas incluem detecção de IoCs e executadas noturnamente, mediante solicitação manual e após alterações de fluxo de trabalho ou arquivos de payload.
• No Linux, a configuração padrão é ~/.config/orewatch/singleton/ e o estado padrão é ~/.local/state/orewatch/singleton/.
• No macOS, a configuração padrão é ~/Library/Application Support/OreWatch/singleton/ e o estado padrão é ~/Library/Application Support/OreWatch/State/singleton/.
• Os dados de ameaças compartilhados agora ficam no diretório de estado do singleton em threat-data/final-data/.
• monitor doctor imprime o exato config_path, state_db, log_file, final_data_dir e o diretório de modelo de serviço para o monitor singleton.
• As substituições de política por projeto podem ser armazenadas em .ore-monitor.yml na raiz do projeto.

Superfície de integração local:

• O OreWatch agora expõe uma API apenas localhost em 127.0.0.1:48736 por padrão quando o daemon do monitor está em execução.
• A API usa um token bearer por usuário armazenado no diretório de configuração do monitor em api.token com permissões apenas do proprietário.
• Requisições diretas para 127.0.0.1:48736 sem Authorization: Bearer <token> retornarão corretamente 401 Unauthorized.
• Clientes agente e IDE devem descobrir o monitor via orewatch monitor connection-info em vez de adivinhar caminhos, e devem enviar o project_path real em que estão operando dentro das requisições de verificação de dependência.
• Claude Code, Codex e Cursor podem usar a ponte MCP incluída, que expõe orewatch_health, orewatch_check_dependency_add, orewatch_check_manifest, orewatch_override_dependency_add, orewatch_list_active_findings, , e .

Configuração opcional de atualização ao vivo com portão de anomalias:```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

- Os candidatos ativos são construídos primeiro em uma área de preparação; eles não sobrescrevem os bancos de dados ativos durante a coleta.
- Grandes quedas, regressões de ecossistema, ecossistemas vazios e remoções em massa bloqueiam a promoção.
- Falhas na fonte principal são apenas de aviso por padrão para atualizações ativas de código aberto; quedas e remoções em nível de ecossistema ainda bloqueiam promoções ruins.
- Anomalias apenas de aviso são registradas no status e relatórios, mas não impedem a promoção.
- Candidatos rejeitados mantêm o último conjunto de dados conhecido como bom ativo quando já existe um.
- A inicialização pela primeira vez a partir de feeds ativos é permitida se pelo menos uma fonte principal for bem-sucedida e o candidato produzir dados de ecossistema utilizáveis.

**Configuração opcional de webhook de notificação:**```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

Defina webhook_format: slack ao direcionar um webhook de entrada do Slack. Nesse modo, o OreWatch envia uma carga útil simples text.

Distribuição

O projeto agora tem duas superfícies de distribuição distintas:

1. O código da CLI e do monitor
2. Os snapshots de dados de ameaças consumidos pelo monitor

Eles devem ser distribuídos separadamente.

Distribuição de Pacotes Recomendada

Melhor padrão para desenvolvedores: publique o scanner como um pacote Python normal no PyPI e recomende a instalação com pipx.

Por que esta é a melhor opção:

• O projeto é uma CLI Python e um monitor de fundo, portanto uma wheel universal mais distribuição de fonte é o artefato de lançamento mais direto.
• pipx oferece aos desenvolvedores uma instalação isolada em nível de usuário sem poluir os virtualenvs do projeto.
• A CI ainda pode instalar a mesma versão com python3.14 -m pip install orewatch==<version>.
• Isso mantém o caminho de atualização da CLI simples enquanto deixa as atualizações de dados de ameaças para o canal de snapshots assinados.

Forma de lançamento recomendada:

• Publique artefatos sdist e wheel universal no PyPI.
• Exponha o ponto de entrada do console orewatch.
• Mantenha ore-mal-pkg-inspector como um alias de compatibilidade temporário.
• Documente pipx install --python python3.14 orewatch para instalações locais de desenvolvedores.
• Documente python3.14 -m pip install orewatch==<version> para CI e automação com versão fixa.

Canal secundário disponível: o Homebrew tap agora está disponível para usuários macOS que preferem instalações gerenciadas pelo Brew:```bash brew install rapticore/tap/orewatch

Homebrew continua sendo uma camada de conveniência sobre a versão publicada no PyPI, não o artefato de lançamento principal.

**Melhor opção para contribuidores:** mantenha o fluxo atual de checkout do código-fonte:```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 .

Implementação Gerenciada do macOS

Se você está implementando o OreWatch com Kandji, Jamf Pro, Intune, Munki, ou outro sistema de distribuição de software macOS, o modelo recomendado é diferente do caminho do desenvolvedor via pipx.

Realidade atual do produto:

• hoje o repositório fornece um pacote Python, não um pacote de instalação macOS notarizado de primeira parte
• para frotas gerenciadas, o artefato recomendado é um .pkg achatado e assinado construído em torno da wheel publicada do OreWatch
• os snapshots de dados de ameaças devem ainda ser distribuídos separadamente do pacote do aplicativo/runtime

Modelo de implementação empresarial recomendado:

1. Instalação do dispositivo
   • implemente um .pkg assinado que instale o runtime do OreWatch e um shim de CLI orewatch estável
   • opcionalmente inclua o extra mac-menubar se quiser o aplicativo nativo da barra de menu em Macs gerenciados
2. Ativação do usuário
   • execute orewatch monitor quickstart /caminho/para/projeto --client <cliente> ou um bootstrap equivalente no contexto do usuário
   • esta etapa é separada porque o monitor do OreWatch é intencionalmente por usuário e usa um LaunchAgent do usuário mais configuração/token/estado de propriedade do usuário
3. Atualizações contínuas
   • atualize o pacote runtime no seu ciclo de vida normal de software
   • atualize os snapshots de dados de ameaças independentemente através do canal de snapshots assinados ou caminho de atualização ao vivo

Por que essa divisão é importante:

• ferramentas MDM são boas para instalar código na máquina
• o monitor, token de API e serviço launchd do OreWatch são de escopo do usuário, portanto devem ser criados no contexto do usuário logado, e não forçados a partir de uma instalação de pacote em escopo de máquina

Forma recomendada do pacote para macOS gerenciado:

• um runtime dedicado sob um caminho estável como /Library/Application Support/OreWatch/runtime
• um shim estável como /usr/local/bin/orewatch
• metadados de pacote versionados para que plataformas MDM possam detectar upgrades de forma limpa
• assinatura de código e notarização onde sua política de frota esperar

Orientações específicas por fornecedor:

• Kandji
  • use um App Personalizado com um Pacote de Instalação (.pkg)
  • prefira .pkg em vez de .dmg ou .zip para OreWatch porque o runtime não é um app de arrastar e soltar
  • use o Self Service ou uma etapa de integração voltada ao usuário para a primeira ativação do monitor
• Jamf Pro
  • faça upload do .pkg como um Pacote e implemente-o com uma Política ou Self Service
  • mantenha a ativação do usuário separada da implementação do pacote na máquina, a menos que tenha uma etapa deliberada de bootstrap no contexto do usuário
• Microsoft Intune
  • use um aplicativo LOB para macOS com um .pkg assinado
  • o Intune é mais restritivo que os outros canais: espera um .pkg real, assinado com um certificado Developer ID Installer, e o pacote deve conter um payload
• Munki
  • publique o .pkg mais metadados do pacote e trate o OreWatch como qualquer outro software macOS gerenciado
  • Munki é uma boa escolha quando você quer um repositório de pacotes e adoção opcional no estilo Self Service

Para um guia de implementação mais completo, veja docs/managed-rollout.md.

Distribuição Recomendada de Snapshots

Os snapshots de dados de ameaças não devem ser empacotados dentro do pacote Python. Eles mudam em uma cadência diferente e já são suportados como artefatos assinados hospedados.

Padrão open-source/comunitário: consuma openssf e osv diretamente pelo caminho de atualização ao vivo com gate de anomalia. Padrão empresarial: publique snapshots assinados versionados em hospedagem HTTPS estática e deixe os clientes atualizá-los independentemente.

Destinos de hospedagem recomendados:

• Assets de Releases do GitHub
• S3 ou Cloudflare R2 por HTTPS
• Qualquer bucket estático com CDN que sirva arquivos versionados imutáveis

Estrutura recomendada de snapshots:

• versions/<versão>/manifest.json
• versions/<versão>/*.db
• channels/stable.json

Modelo de confiança recomendado:

• Mantenha a chave privada de assinatura offline
• Envie apenas a chave pública de verificação com a configuração ou pacote do cliente
• Verifique cada descritor de canal e manifesto antes do download/aplicação

Modelo Geral Recomendado

Para uma versão de produção, a configuração mais limpa é:

• Distribuir o aplicativo como um pacote PyPI
• Instalar localmente com pipx
• Instalar em CI com pip
• Distribuir dados de ameaças como canais de snapshot assinados por HTTPS
• Tratar o checkout do código fonte como um caminho de desenvolvimento, não a instalação principal do usuário final

Logging & Depuração

Por padrão, o scanner mostra apenas avisos, erros e o resumo final. Para solução de problemas ou acompanhamento detalhado do progresso, use as flags de logging:

Modo Verboso

Ver mensagens de progresso e estatísticas de coleta:```bash orewatch /path/to/project --verbose

**A saída inclui:**
- Resultados da detecção de ecossistema
- Progresso da análise de arquivos
- Contagens de extração de pacotes
- Detalhes da consulta ao banco de dados
- Progresso da varredura de IoCs

**Exemplo:**```
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 Depuração

Veja informações detalhadas de diagnóstico para solução de problemas:```bash orewatch /path/to/project --debug

**Output inclui:**
- Mensagens de nível INFO
- Caminhos de arquivos sendo escaneados
- Detalhes de execução de consultas SQL
- Cálculos de hash
- Resultados de correspondência de padrões
- Informações de estado interno

**Casos de uso:**
- Investigar por que um pacote não foi detectado
- Depurar problemas de detecção automática de ecossistema
- Reportar problemas com contexto detalhado
- Auditar comportamento do scanner

### Registro para Coletores

Os coletores de inteligência de ameaças também suportam modos verbose e debug:```bash
cd collectors

# See collection progress
python3 orchestrator.py --verbose

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

Nota: Todos os logs vão para stderr, mantendo o stdout limpo para saída do relatório JSON. Isso permite canalizar os resultados do scanner para outras ferramentas sem interferência de mensagens de log.

Saída e Relatórios

Estrutura do Relatório

Os relatórios são salvos no diretório scan-output/ por padrão (ou em um caminho personalizado com --output). O OreWatch escreve um relatório JSON legível por máquina e um relatório HTML estilizado com o mesmo nome base. O artefato JSON inclui metadados de disponibilidade de dados de ameaça e usa objetos physicalLocation no estilo SARIF para descobertas de pacotes, mas não é um documento SARIF 2.1.0 completo.

Exemplo de relatório:```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 dados de ameaças:**
- `data_status`: `complete`, `partial`, `failed`, ou `not_applicable`
- `sources_used`: fontes que contribuíram com dados de ameaças utilizáveis para os ecossistemas solicitados
- `experimental_sources_used`: fontes experimentais incluídas nos dados de verificação
- `missing_ecosystems`: ecossistemas solicitados que não possuíam uma base de dados de ameaças de pacotes utilizável
- `promotion_decision`: vazio para verificações de dados existentes; caso contrário, `promoted`, `bootstrapped`, ou `rejected`
- `kept_last_known_good`: `true` quando um candidato ativo foi rejeitado mas o conjunto de dados anterior permaneceu utilizável
- `anomalies`: anomalias de aviso/bloqueio levantadas durante uma tentativa de atualização ativa

### Compreendendo os Resultados

**Níveis de Gravidade:**
- **CRÍTICO:** Código malicioso conhecido com explorações ativas ou exfiltração de dados
- **ALTO:** Fortes indícios de intenção maliciosa ou typosquatting
- **MÉDIO:** Padrões suspeitos ou potenciais vulnerabilidades
- **BAIXO:** Preocupações menores ou descobertas informativas

**Ações Recomendadas:**
1. **Descobertas Críticas/Altas:** Remova imediatamente os pacotes afetados e investigue o impacto
2. **Revisar IoCs:** Verifique se o código malicioso foi executado (logs, atividade de rede)
3. **Atualizar dependências:** Substitua pacotes maliciosos por alternativas legítimas
4. **Verificar novamente:** Confirme a correção com uma verificação de acompanhamento
5. **Reportar:** Considere reportar aos mantenedores do registro de pacotes

---

## Integração CI/CD

### GitHub Actions

**Verificação de Segurança Básica:**```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/

Avançado com Falha na Detecção:```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 pré-commit

Adicione em `.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"

Resolução de Problemas

Problemas Comuns

Erro "Banco de dados não encontrado"

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

**Causa:** Falha na coleta de dados de ameaças, metadados incompletos ou os ecossistemas solicitados ainda não possuem bancos de dados locais utilizáveis.

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

Nota: Se isso persistir, verifique a conectividade de rede, as permissões do sistema de arquivos e se você solicitou intencionalmente fontes experimentais.

Aviso "Nenhum pacote detectado"

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

**Possíveis causas e soluções:**

1. **Diretório errado:** Certifique-se de que está escaneando o diretório correto do projeto   ```bash
   ls /path/to/project  # Verify package.json or requirements.txt exists

2. Manifesto não suportado ou inesperado: Imprima os nomes de arquivo suportados exatos ```bash orewatch --list-supported-files
   root@kitploit:~

3. Permissões de arquivo: Certifique-se de que os arquivos sejam legíveis ```bash ls -la /path/to/project/package.json
   root@kitploit:~

Erros de Conexão Durante a Atualização

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

**Soluções:**

1. **Verifique a conexão com a internet:**   ```bash
   ping google.com

2. Repetir com aumento de tempo limite: Edit collectors/config.yaml: ```yaml osv: timeout: 600 # Increase from default 300
   root@kitploit:~

3. Usar dados em cache: Se você já baixou dados anteriormente: ```bash python3 orchestrator.py --skip-build # Skip download, rebuild from cache
   root@kitploit:~

Erros de Permissão Negada

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

**Solução:**```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 Muito Disco

Sintoma: ~/Library/Application Support/OreWatch (macOS) ou $XDG_STATE_HOME/orewatch (Linux) cresceu para dezenas de gigabytes.

Causa (pré-1.2.3): Cada promoção de atualização ao vivo arquivava uma cópia completa dos bancos de dados de dados de ameaças anteriores (~300 MB) sem retenção. Um monitor em execução prolongada acumulava um instantâneo por ciclo indefinidamente.

Correção: Atualize para 1.2.3 ou superior. Os backups agora são manifestos SHA-256 de ~1 KB, a retenção padrão é para os 30 mais recentes, e um comando explícito de limpeza está disponível:```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

**Sintoma:** Pacote legítimo sinalizado como malicioso.

**Passos:**

1. **Verifique a descoberta:** Revise os detalhes do relatório, incluindo gravidade e descrição

2. **Verifique a versão:** A versão sinalizada pode ser específica:   ```bash
   orewatch /path/to/project --verbose

3. Reportar falso positivo: Se confirmado incorreto:
   • Abra um issue em https://github.com/rapticore/ore-mal-pkg-inspector/issues com detalhes

Modo de Depuração para Investigação

Ativar registro detalhado:```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

**Registos de revisão:** Verifique `debug.log` para um registo detalhado da execução, incluindo:
- Caminhos de ficheiros analisados
- Consultas SQL executadas
- Resultados de correspondência de padrões
- Rastreios de erros (stack traces)

---

## FAQ

### Com que frequência devo atualizar as informações de ameaças (threat intelligence)?

**Recomendação:**
- **Ambientes de produção/CI:** Atualizações automáticas diárias
- **Workstations de desenvolvimento:** Atualizações semanais, no mínimo
- **Após notícias de segurança:** Atualização imediata quando novas ameaças forem anunciadas

Pacotes maliciosos são publicados continuamente. Atualizações diárias garantem as proteções mais recentes.

### Como atualizar os dados de informações de ameaças?

Execute o scanner com a opção `--latest-data` para forçar uma atualização:```bash
orewatch /path/to/project --latest-data

Para atualizações automatizadas em CI/CD, agende varreduras periódicas com a flag --latest-data (ex.: diariamente). Adicione --include-experimental-sources apenas se você quiser explicitamente incluir dados derivados do Phylum na reconstrução.

Nota: As primeiras varreduras coletam dados automaticamente, então atualizações manuais são necessárias apenas para renovar bancos de dados existentes.

De onde vêm os dados de ameaças?

Os bancos de dados padrão são construídos a partir das fontes de ameaças principais do projeto:

• openssf
• osv

O scanner também pode incluir o conjunto de fontes experimentais do projeto:

• phylum com --include-experimental-sources

socketdev está presente no repositório como um placeholder desabilitado e não faz parte do caminho de coleta padrão.

Para detalhes técnicos sobre fontes de dados, coleta e processamento, consulte ARCHITECTURE.md.

Esta ferramenta modifica meu código ou dependências?

Não. O OreWatch realiza operações somente leitura. Ele:

• ✅ Lê arquivos de dependência
• ✅ Consulta bancos de dados de ameaças
• ✅ Escaneia por padrões de arquivos
• ✅ Gera relatórios

Ele nunca:

• ❌ Modifica arquivos de pacotes
• ❌ Instala ou remove pacotes
• ❌ Altera a configuração do projeto
• ❌ Executa código de pacotes

E se meu pacote for sinalizado como malicioso?

Passos a seguir:

1. Verifique a descoberta: Consulte o relatório para obter detalhes e gravidade
2. Revise as evidências: Examine a descrição e os comportamentos detectados
3. Verifique versões: Determine se versões específicas são afetadas
4. Se legítimo:
   • Relate falso positivo aos mantenedores da fonte de dados
   • Abra uma issue no nosso GitHub com detalhes
5. Se realmente malicioso:
   • Remova o pacote imediatamente
   • Revise commits recentes de código em busca de danos
   • Verifique logs em busca de atividade suspeita
   • Atualize para uma alternativa segura

Posso usar isso offline?

Parcialmente.

Varredura offline: ✅ Sim, uma vez que os bancos de dados estejam inicializados```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

**Offline updates:** ❌ Não, a coleta de inteligência de ameaças requer acesso à internet para obter dados de fontes de segurança.

**Ambientes isolados (airgapped):** Você pode:
1. Baixar bancos de dados em uma máquina conectada à internet
2. Transferir os arquivos SQLite para o diretório `final_data_dir` mostrado pelo comando `orewatch monitor doctor`
3. Executar varreduras offline com dados potencialmente desatualizados

### Como isso se compara ao npm audit ou pip-audit?

**Propósitos diferentes:**

**npm audit / pip-audit:**
- Foco em vulnerabilidades CVE conhecidas
- Verifica versões de pacotes em relação a bancos de dados de avisos (advisory databases)
- Mantido pelas equipes de registro de pacotes

**OreWatch:**
- Foco em pacotes maliciosos (não apenas vulneráveis)
- Detecta typosquatting, malware, ataques à cadeia de suprimentos
- Cobertura entre ecossistemas
- Detecção de IoC para ameaças ativas

**Melhor prática:** Use **ambos**:```bash
# Check for vulnerabilities
npm audit
pip-audit

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

Isso funciona com registros de pacotes privados?

Varredura de dependências: ✅ Sim, o scanner lê seus arquivos de dependência independentemente de onde os pacotes vêm.

Inteligência de ameaças: ⚠️ Limitada. Nossos bancos de dados cobrem registros públicos (npmjs.com, pypi.org, etc.). Pacotes maliciosos em registros privados não serão detectados, a menos que você adicione dados de ameaças personalizados.

Dados de ameaças personalizados: Você pode ampliar os bancos de dados com suas próprias listas de pacotes maliciosos. Entre em contato conosco para orientação sobre este caso de uso avançado.

Qual é o impacto no desempenho?

Tempo de varredura:

• Projetos pequenos (< 50 pacotes): < 5 segundos
• Projetos médios (50-500 pacotes): 5-30 segundos
• Projetos grandes (500+ pacotes): 30-120 segundos

Fatores:

• A varredura de IoC adiciona 10-50% de sobrecarga (desative com --no-ioc se não for necessário)
• A primeira execução pode ser mais lenta, pois os bancos de dados carregam na memória

Dicas de otimização:```bash

Scan specific files instead of entire directory

orewatch --file package.json

---

## Contribuindo

Aceitamos contribuições! Seja relatando bugs, sugerindo funcionalidades ou contribuindo com código, sua ajuda melhora o OreWatch para todos.

**Relate bugs ou solicite funcionalidades:**
- GitHub Issues: https://github.com/rapticore/ore-mal-pkg-inspector/issues

**Contribua com código:**
- Consulte [CONTRIBUTING.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/CONTRIBUTING.md) para diretrizes detalhadas sobre configuração de desenvolvimento, estilo de código, testes e processo de pull request

**Dúvidas ou discussões:**
- GitHub Discussions: https://github.com/rapticore/ore-mal-pkg-inspector/discussions

---

## Política de Segurança

A segurança é nossa prioridade máxima. OreWatch é uma ferramenta de segurança e levamos as vulnerabilidades a sério.

### Reportando Vulnerabilidades de Segurança

**NÃO abra issues públicas no GitHub para vulnerabilidades de segurança.**

Em vez disso, reporte em particular:

**Email:** [email protected]

**Inclua:**
- Descrição da vulnerabilidade
- Passos para reproduzir
- Impacto potencial
- Correção sugerida (se aplicável)
- Suas informações de contato para acompanhamento

### Cronograma de Resposta

- **Reconhecimento:** Dentro de 48 horas
- **Avaliação inicial:** Dentro de 7 dias
- **Cronograma de correção:** Varia conforme a gravidade
  - Crítico: 7-14 dias
  - Alto: 14-30 dias
  - Médio/Baixo: 30-60 dias

### Melhores Práticas de Segurança

Ao usar o OreWatch:

**Faça:**
- ✅ Execute com privilégios mínimos (sem necessidade de root/admin)
- ✅ Atualize a inteligência de ameaças regularmente
- ✅ Revise os relatórios de varredura rapidamente
- ✅ Integre ao CI/CD para proteção contínua
- ✅ Mantenha a ferramenta atualizada para a versão mais recente

**Não faça:**
- ❌ Ignore descobertas de varredura sem investigação
- ❌ Desabilite a varredura de IoCs em ambientes de produção
- ❌ Compartilhe arquivos de banco de dados de fontes não confiáveis
- ❌ Execute com privilégios elevados desnecessariamente

### Divulgação de Vulnerabilidades

Seguimos divulgação coordenada:
1. Vulnerabilidade relatada em particular
2. Correção desenvolvida e testada
3. Aviso de segurança publicado
4. Divulgação pública após a correção estar disponível

### Hall da Fama de Segurança

Reconhecemos pesquisadores de segurança que divulgam vulnerabilidades de forma responsável:

*Lista será mantida à medida que os relatórios forem recebidos*

---

### Solicitações da Comunidade

Vote ou sugira funcionalidades:
- **GitHub Discussions:** https://github.com/rapticore/ore-mal-pkg-inspector/discussions
- **Feature Requests:** https://github.com/rapticore/ore-mal-pkg-inspector/issues

### Contribuindo para o Roadmap

Priorizamos funcionalidades com base em:
- Impacto na segurança
- Demanda da comunidade
- Sustentabilidade da manutenção
- Alinhamento com os objetivos do projeto

Para influenciar o roadmap:
1. Abra uma solicitação de funcionalidade com caso de uso detalhado
2. Participe de discussões
3. Contribua com implementações (PRs são bem-vindos!)

---

## Roadmap

OreWatch é utilizável hoje para:
- varreduras locais via CLI em npm, PyPI, Maven, RubyGems, Go e Cargo
- um monitor em segundo plano por usuário para vários projetos
- integrações MCP para Cursor, Claude Code e Codex
- integrações de API localhost para VS Code, JetBrains / PyCharm e auxiliares do Xcode
- revisão da barra de menu do macOS e notificações popup

Prioridades de curto prazo:
- exemplos de integração de primeira parte para VS Code e JetBrains / PyCharm ou plugins leves
- fluxos de notificação mais robustos voltados ao usuário além de popups locais
- gerenciamento mais claro de políticas de projeto a partir da CLI e IU
- relatórios de monitor mais ricos e documentação de adoção

Prioridades de médio prazo:
- fluxos de varredura de projetos mais amplos a partir do monitor e superfície MCP
- melhores orientações de implantação em nível de organização
- canais de entrega de alertas externos e escalonamento mais robustos
- UX mais profunda específica para IDE em vez de orientação de integração apenas por API

Limitação atual conhecida:
- A integração com Xcode é atualmente melhor para visibilidade de alertas e repositórios com múltiplas linguagens. O OreWatch ainda não analisa manifestos nativos da Apple como `Package.resolved`, `Podfile.lock` ou `Cartfile`.

Direção de longo prazo:
- suporte nativo a manifestos do ecossistema Apple
- integrações mais robustas de editores de primeira parte
- paridade de UX mais ampla entre sistemas operacionais além do atual caminho da barra de menu do macOS

Consulte [docs/roadmap.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/roadmap.md) para uma visão do roadmap mais focada em adoção.

---

## Licença

MIT License

Copyright (c) 2025 Rapticore

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

## Suporte

### Obtendo Ajuda

**Documentação:** Você está lendo! Comece aqui para a maioria das perguntas.

**GitHub Discussions:** Para dúvidas, ideias e interação com a comunidade:
- https://github.com/rapticore/ore-mal-pkg-inspector/discussions

**GitHub Issues:** Para relatos de bugs e solicitações de funcionalidades:
- https://github.com/rapticore/ore-mal-pkg-inspector/issues

**Email:** Para vulnerabilidades de segurança e consultas privadas:
- [email protected]

### Suporte Profissional

Para organizações que necessitam de:
- Integrações personalizadas
- Suporte com SLA
- Assistência para implantação privada
- Feeds personalizados de inteligência de ameaças

Contato: [email protected]

---

## Agradecimentos

### Origem do Projeto

Este projeto foi extraído do repositório [OreNPMGuard](https://github.com/rapticore/OreNPMGuard) para manter o foco claro do projeto enquanto expande as capacidades.

**OreNPMGuard** (Dezembro de 2025) é especializado em detecção de ataques Shai-Hulud no npm com mais de 738 pacotes afetados e análise profunda de IoCs. Durante seu desenvolvimento, reconhecemos a necessidade de proteção mais ampla em múltiplos ecossistemas, levando à criação do OreWatch como uma ferramenta independente que atende à comunidade de desenvolvedores em todos os principais ecossistemas de pacotes.

### Projetos Relacionados

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

**Construído pela Equipe de Pesquisa de Segurança da Rapticore**

*Protegendo cadeias de suprimentos de software, uma varredura de cada vez.*