OreWatch

Многоэкосистемное обнаружение вредоносных пакетов и сканер безопасности цепочек поставок

Инструмент безопасности производственного уровня для обнаружения вредоносных пакетов и угроз цепочки поставок в экосистемах npm, PyPI, Maven, RubyGems, Go и Cargo. Использует автоматизированный сбор данных об угрозах из доверенных источников безопасности для выявления скомпрометированных зависимостей в ваших проектах.

OreWatch — это название продукта и пакета на PyPI. Текущий путь репозитория исходного кода по-прежнему использует ore-mal-pkg-inspector.

Видео

Установка

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

OreWatch и Cursor

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

OreWatch и CodeX

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

OreWatch и Claude-Code

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

Содержание

• Проблема
• Решение
• Ключевые особенности
• Почему OreWatch?
• Начало работы
• Быстрый старт
  • Предварительные требования
  • Установка
  • Первое сканирование
• Использование
  • Основные команды
  • Продвинутое использование
  • Справочник командной строки
  • Фоновый мониторинг
• Руководство по внедрению
• Распространение
  • Управляемый запуск на macOS
• Логирование и отладка
• Вывод и отчёты
• Интеграция с CI/CD
• Устранение неполадок
• Часто задаваемые вопросы
• Участие в разработке
• Политика безопасности
• План развития
• Лицензия
• Поддержка
• Благодарности

Проблема

Атаки на цепочки поставок теперь являются основным вектором угроз для компрометации программного обеспечения. Только в 2024 году тысячи вредоносных пакетов были опубликованы в npm, PyPI и других реестрах пакетов, нацеленных на разработчиков с помощью тайпсквоттинга, путаницы зависимостей и сложных кампаний вредоносного ПО, таких как Shai-Hulud.

Проблема: Организациям и разработчикам необходимо:

• Сканировать зависимости в нескольких экосистемах программирования
• Быть в курсе быстро меняющейся информации об угрозах из нескольких источников
• Обнаруживать не только известные вредоносные пакеты, но и индикаторы компрометации (IoC)
• Интегрировать сканирование безопасности в существующие рабочие процессы разработки
• Быстро реагировать на недавно обнаруженные угрозы

Пробел: Существующие решения часто:

• Ограничены одной экосистемой (только npm, только PyPI и т.д.)
• Полагаются на ручное обслуживание списков угроз
• Не имеют возможностей обнаружения IoC
• Трудно интегрируются в автоматизированные конвейеры
• Являются проприетарными инструментами типа «чёрный ящик» без прозрачности

Решение

OreWatch решает эти проблемы, предоставляя:

Комплексное многоэкосистемное покрытие: Единый инструмент для пакетов npm, PyPI, Maven, RubyGems, Go и Cargo

Автоматизированная информация об угрозах: Динамически собирает и объединяет данные из доверенных источников исследований безопасности

Активное обнаружение IoC: Выявляет шаблоны атак Shai-Hulud и другие индикаторы вредоносного кода, помимо сопоставления имён пакетов

Готовность к CI/CD: Разработан для бесшовной интеграции с GitHub Actions, GitLab CI, Jenkins и другими платформами автоматизации

Открытый исходный код и прозрачность: Полная видимость логики обнаружения, источников данных и методологии сканирования

Ключевые особенности

Поддержка нескольких экосистем Сканирует пакеты npm, PyPI, Maven, RubyGems, Go и Cargo с автоматическим определением экосистемы из структуры проекта.

Единая база данных об угрозах Проверяет по динамически собираемым базам данных вредоносных пакетов из доверенных источников исследований безопасности.

Автоматическое определение экосистемы Интеллектуально определяет экосистемы по структуре каталогов, именам файлов и может сканировать несколько экосистем за один запуск.

Обнаружение индикаторов компрометации (IoC) Сканирует шаблоны атак Shai-Hulud (оригинальные и версии 2.0), вредоносные хуки, подозрительные рабочие процессы и известные файлы полезной нагрузки.

Интеграция с Shai-Hulud Перекрёстно ссылается пакеты npm с полным списком затронутых пакетов Shai-Hulud из OreNPMGuard.

Структурированные отчёты в JSON Создаёт машиночитаемые отчёты в формате JSON с явными метаданными данных об угрозах и расположением файлов в стиле SARIF для найденных результатов.

Гибкие форматы ввода Поддерживает стандартные файлы зависимостей (package.json, requirements.txt и т.д.) и общие списки пакетов (текст, JSON, YAML).

Готовое к производству логирование Настраиваемые уровни детализации с флагами --verbose и --debug для устранения неполадок и аудиторских следов.

Безопасность и скорость Операции только для чтения без изменений вашего кода, оптимизированы для быстрого сканирования больших кодовых баз.

Почему OreWatch?

Против одноэкосистемных инструментов Большинство сканеров безопасности фокусируются на одном менеджере пакетов. OreWatch обеспечивает единую защиту в шести основных экосистемах, что необходимо для современных мультиязычных сред разработки.

Против ручных списков угроз Статические списки вредоносных пакетов быстро устаревают. Наши автоматические сборщики ежедневно получают свежие данные об угрозах из нескольких авторитетных источников.

Против обнаружения только по имени пакета Проверка только имён пакетов пропускает сложные атаки. Обнаружение IoC выявляет вредоносные шаблоны кода даже в пакетах, ещё не внесённых в чёрные списки.

Против ручных аудитов безопасности Ручные проверки зависимостей отнимают много времени и подвержены ошибкам. Автоматическое сканирование обеспечивает непрерывную проверку безопасности в каждой сборке.

Против коммерческих инструментов типа «чёрный ящик» Проприетарные инструменты не имеют прозрачности логики обнаружения. Как проект с открытым исходным кодом, каждое правило обнаружения и источник данных подлежат аудиту.

История создания OreWatch родился из разработки OreNPMGuard, специализированного сканера атак Shai-Hulud на npm. В ходе этого проекта мы осознали необходимость более широкого многоэкосистемного охвата за пределами npm. В декабре 2025 года мы выделили и улучшили возможности многоэкосистемного обнаружения в этот отдельный инструмент, сохранив фокус OreNPMGuard на npm и одновременно позволив OreWatch обслуживать более широкое сообщество разработчиков во всех основных экосистемах пакетов.

Начало работы

Если вы впервые внедряете OreWatch, выберите самый короткий путь, соответствующий вашему рабочему процессу:

Рекомендуемая последовательность первого запуска для большинства разработчиков:

1. Установите OreWatch с помощью pip install . или опубликованного пакета.
2. Запустите orewatch monitor quickstart /path/to/project --client <ваш-клиент>.
3. Проверьте работу демона с помощью orewatch monitor status.
4. Если вы на macOS, запустите orewatch monitor menubar для уведомлений и локального интерфейса.

Если вам нужно более краткое руководство по установке с командами для копирования, используйте docs/adoption-guide.md.

Быстрый старт

Предварительные требования

• Python 3.14 или выше
• pip для установки зависимостей
• Git для клонирования репозитория
• Подключение к интернету для первоначальной настройки данных об угрозах
• OpenSSL для генерации подписанного ключа снэпшота, публикации и проверки в рабочих процессах мониторинга снэпшотов

Установка

OreWatch может быть установлен через pipx (рекомендуется), Homebrew (macOS), pip или из исходного кода. Все методы создают команду CLI orewatch.

Вариант 1 — pipx (рекомендуется)

pipx устанавливает OreWatch в собственную изолированную среду, делая команду orewatch доступной глобально. Это лучший вариант для большинства разработчиков.```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

Если вы уже установили `orewatch` с помощью pipx и хотите добавить приложение для строки меню macOS
позже, внедрите привязки Cocoa в то же окружение pipx:```bash
pipx inject orewatch pyobjc-framework-Cocoa

Обновление:```bash pipx upgrade orewatch

**Деинсталляция:**```bash
pipx uninstall orewatch

Вариант 2 — Homebrew (macOS)

Для пользователей macOS, предпочитающих установку через 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

**Обновление:**```bash
brew update && brew upgrade orewatch

Удаление:```bash brew uninstall orewatch brew untap rapticore/tap # optional — removes the tap

> **Примечание:** Формула Homebrew включает привязки Cocoa, необходимые для
> `orewatch monitor menubar`. Если старая установка Homebrew сообщает
> `ModuleNotFoundError: No module named 'AppKit'`, выполните
> `brew update && brew reinstall rapticore/tap/orewatch`, чтобы формула пересобрала
> свою изолированную среду Python с поддержкой строки меню.

#### Вариант 3 — pip

Используйте `pip` для конвейеров CI, образов Docker или если вы управляете своими
собственными виртуальными окружениями:```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

Обновление:```bash python3.14 -m pip install --upgrade orewatch

#### Опция 4 — Выгрузка исходного кода (Участники)```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

Проверка после установки

После установки любым способом убедитесь, что OreWatch работает:```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 .

#### Примечания по платформам

| Платформа | Источник Python | Примечания |
|---|---|---|
| **macOS** (Homebrew Python) | `brew install [email protected]` | Рекомендуется для пользователей Homebrew |
| **macOS** (pyenv) | `pyenv install 3.14` | Лучший вариант для работы с несколькими версиями |
| **Ubuntu / Debian** | `sudo apt install python3.14` или pyenv | Проверьте, поставляется ли в вашем дистрибутиве Python 3.14+ |
| **Fedora / RHEL** | `sudo dnf install python3.14` или pyenv | — |
| **Windows (WSL)** | pyenv или системный пакет | Родная Windows не тестировалась |

> **Требуется Python 3.14.** OreWatch использует возможности языка, появившиеся в
> Python 3.14. Старые версии вызовут ошибку при импорте.

#### Устранение неполадок при установке

| Симптом | Решение |
|---|---|
| `command not found: orewatch` | Убедитесь, что каталог установки находится в вашем `PATH`. Для pipx: выполните `pipx ensurepath` и перезапустите оболочку. |
| `ModuleNotFoundError` при импорте | Возможно, у вас несколько версий Python. Убедитесь, что среда выполнения за `orewatch` — Python 3.14+, и переустановите с помощью соответствующего интерпретатора. |
| pipx install завершается с ошибками разрешения | Обновите pipx: `python3.14 -m pip install --upgrade pipx` |
| Homebrew `orewatch` не найден после установки | Сначала выполните `brew tap rapticore/tap`, затем повторите установку. |
| Отказано в доступе во время pip install | Используйте `pip install --user orewatch` или установите внутри виртуального окружения. |

_Примечание: Если локальные данные об угрозах отсутствуют или устарели, при сканировании пакетов создается кандидат на обновление в реальном времени и он продвигается только после прохождения аномальных шлюзов. Если кандидат выглядит подозрительно, OreWatch сохраняет последний известный рабочий набор данных активным._

_Установленный CLI:_ `orewatch`
_Псевдоним для совместимости:_ `ore-mal-pkg-inspector`

### Первое сканирование

**Сканировать каталог проекта:**```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

Ожидаемый вывод:``` 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

Если вы хотите, чтобы OreWatch продолжал отслеживать проект после этого первого сканирования, перейдите к разделу [Фоновое отслеживание](#background-monitoring) или перейдите сразу к [docs/adoption-guide.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/adoption-guide.md).

---

## Использование

### Основные команды

**Сканировать директорию (Автоопределение экосистемы):**```bash
# Current directory
orewatch .

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

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

Сканировать конкретные файлы зависимостей:```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

**Принудительная экосистема:**```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

Сканирование общих списков пакетов:```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

### Расширенное использование

**Пользовательский путь вывода:**```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

Управление сканированием 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

**Тихий режим:**```bash
# Generate report without console summary (useful for scripts)
orewatch /path/to/project --no-summary

Контроль данных угроз:```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

**Пакетное сканирование:**```bash
# Scan multiple projects
for dir in ~/projects/*/; do
    echo "Scanning $dir"
    orewatch "$dir" --output "reports/$(basename $dir).json"
done

Справочник по командной строке

Параметры сканера

Фоновый мониторинг

Репозиторий теперь включает локальный фоновый монитор, который поддерживает актуальность данных об угрозах, отслеживает изменения манифестов и рабочих процессов в выбранных проектах, запускает сканирования с дебаунсингом и записывает уведомления о новых или ухудшенных находках. Конфигурация и состояние, принадлежащие монитору, хранятся вне репозитория в каталогах, принадлежащих пользователю, поэтому клонированный репозиторий не может предварительно повлиять на поведение монитора.

OreWatch теперь рассматривает монитор как одноэлементный экземпляр для каждого пользователя. Один демон может отслеживать множество проектов в любом месте на диске и обслуживать множество одновременных клиентов Claude Code, Codex, Cursor, VS Code, JetBrains / PyCharm и Xcode.

Сквозная настройка монитора

1. Установите и загрузите одноэлементный монитор```bash

First project + first client

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

`monitor quickstart` — это рекомендуемый рабочий процесс для первого запуска. Он:

- устанавливает или обновляет синглтон-службу монитора
- запускает монитор при необходимости
- добавляет целевой проект в список наблюдения
- выводит блок начальной загрузки для выбранного клиента

Если вы предпочитаете сначала установить монитор, а затем подключать клиентов:```bash
orewatch monitor install
orewatch monitor install --ide-bootstrap
orewatch monitor install --service-manager launchd --no-start

2. Убедитесь, что монитор исправен```bash orewatch monitor status orewatch monitor connection-info orewatch monitor doctor

Используйте эти команды для выполнения различных задач:

- `monitor status` показывает, работают ли singleton-демон и API
- `monitor connection-info` выводит URL loopback API, путь к токену, домашнюю директорию монитора и поддерживаемые клиенты начальной загрузки
- `monitor doctor` выводит точные пути к конфигурации, базе данных состояния, журналу и общим данным угроз

**3. Добавьте каждый проект, за которым вы хотите, чтобы следил singleton**```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

Один демон OreWatch может одновременно отслеживать все эти проекты. Вам не нужен отдельный монитор для каждого репозитория или рабочего пространства IDE.

Рецепты интеграции с клиентами

OreWatch поддерживает два транспортных протокола интеграции:

Команды начальной загрузки выводят один из следующих шаблонов:```json { "mcpServers": { "orewatch": { "command": "/absolute/path/to/orewatch", "args": [ "monitor", "mcp" ] } } }

Когда `orewatch monitor ide-bootstrap --client <client>` может найти локальный консольный скрипт, теперь он возвращает абсолютный путь вместо просто `orewatch`. Если у вас есть старая конфигурация MCP, в которой всё ещё указано `"command": "orewatch"`, перегенерируйте её и замените старую запись.```json
{
  "orewatch": {
    "baseUrl": "http://127.0.0.1:48736",
    "tokenPath": "/path/to/api.token"
  }
}

Cursor, Claude Code, and Codex

Эти клиенты все используют один и тот же локальный мост MCP:```bash orewatch monitor mcp

Рекомендуемая настройка:

1. Выполните `orewatch monitor quickstart /path/to/project --client <cursor|claude_code|codex>` один раз.
2. Скопируйте напечатанный блок MCP в соответствующий MCP-клиент.
3. Откройте отслеживаемый проект в этом клиенте.
4. Разрешите клиенту вызывать OreWatch через MCP для:
   - `orewatch_health`
   - `orewatch_check_dependency_add`
   - `orewatch_check_manifest`
   - `orewatch_override_dependency_add`
   - `orewatch_list_active_findings`
   - `orewatch_list_notifications`

Примечания:

- `monitor mcp` — это stdio-сервер. Если вы запускаете его вручную, он будет казаться бездействующим, пока ожидает MCP-клиента.
- MCP-мост при запуске проверяет локальный API и может автоматически запустить монитор-одиночку один раз, если включена опция `auto_start_on_client`.
- Для надежного запуска в IDE после установки один раз выполните `monitor install`, чтобы демон был уже доступен до запуска MCP-моста.

##### VS Code

Интеграции с VS Code должны использовать API локального хоста одиночки, а не MCP-мост.

Рекомендуемая настройка:

1. Выполните `orewatch monitor quickstart /path/to/project --client vscode`.
2. Скопируйте `baseUrl` и `tokenPath` из `orewatch monitor ide-bootstrap --client vscode`.
3. Подставьте эти значения в ваше локальное расширение VS Code, задачу или вспомогательный инструмент.
4. Вызывайте API при событиях: добавление зависимости, сохранение манифеста и обновление предупреждений.

Рекомендуемое использование API для интеграции с VS Code:

- вызывайте `POST /v1/check/dependency-add` перед потоками установки/добавления пакетного менеджера
- вызывайте `POST /v1/check/manifest`, когда поддерживаемый манифест сохраняется или явно перепроверяется
- опрашивайте `GET /v1/findings/active` и `GET /v1/notifications` для отображения фоновых обнаружений

##### JetBrains / PyCharm

JetBrains и PyCharm используют тот же контракт локального API, что и VS Code.

Рекомендуемая настройка:

1. Выполните `orewatch monitor quickstart /path/to/project --client jetbrains`.
2. Скопируйте блок API из `orewatch monitor ide-bootstrap --client jetbrains`.
3. Используйте возвращённые `baseUrl` и `tokenPath` в плагине JetBrains, внешнем инструменте или локальном помощнике.
4. Отображайте как синхронные решения о зависимостях, так и сохранённые фоновые оповещения внутри IDE.

Рекомендуемое использование API для интеграции с JetBrains:

- проверяйте добавление зависимостей с помощью `POST /v1/check/dependency-add`
- перепроверяйте `package.json`, `requirements.txt`, `pyproject.toml`, `pom.xml`, `Gemfile`, `go.mod`, `Cargo.toml` и другие поддерживаемые манифесты с помощью `POST /v1/check/manifest`
- получайте `GET /v1/findings/active` и `GET /v1/notifications` для постоянных панелей оповещений или окон инструментов

##### Xcode

Интеграции с Xcode также должны использовать API локального хоста одиночки, но здесь есть важное ограничение по области действия: OreWatch пока не анализирует собственные манифесты зависимостей Apple, такие как `Package.resolved`, `Podfile.lock` или `Cartfile`. Сегодня интеграция с Xcode лучше всего подходит для:

- отображения фоновых находок и уведомлений в помощнике, скрипте или сопутствующем приложении
- репозиториев со смешанными языками, открытых в Xcode, которые также содержат поддерживаемые манифесты, такие как `package.json`, `pyproject.toml` или `Cargo.toml`
- команд, которые хотят использовать приложение в строке меню macOS и уведомления Центра уведомлений при работе в Xcode

Рекомендуемая настройка:

1. Выполните `orewatch monitor quickstart /path/to/project --client xcode`.
2. Скопируйте блок API из `orewatch monitor ide-bootstrap --client xcode`.
3. Используйте возвращённые `baseUrl` и `tokenPath` из скрипта фазы сборки, вспомогательного процесса или пользовательской интеграции Xcode.
4. Опрашивайте `GET /v1/findings/active` и `GET /v1/notifications` для видимых пользователю оповещений.
5. Если рабочее пространство Xcode содержит поддерживаемые манифесты не от Apple, вызывайте `POST /v1/check/manifest` для этих файлов в рамках вашего рабочего процесса.

Текущее состояние интеграции:

- Claude Code, Codex и Cursor: встроенный MCP-мост включён в этот репозиторий
- VS Code: контракт локального API задокументирован, но собственное расширение пока не прилагается
- JetBrains / PyCharm: контракт локального API задокументирован, но собственный плагин пока не прилагается
- Xcode: локальный API и интеграция со строкой меню задокументированы, но собственное расширение Xcode и анализатор собственных манифестов Apple пока отсутствуют

#### Когда OreWatch что-то находит

Когда фоновый монитор обнаруживает скомпрометированный пакет или IoC в отслеживаемом проекте, OreWatch:

- записывает управляемые монитором отчёты в форматах JSON и HTML в каталог `reports/` монитора-одиночки
- сохраняет активную находку в БД состояния монитора
- сохраняет запись уведомления с полезным сообщением
- выводит предупреждение в терминал, если включены терминальные уведомления
- на macOS предпочитает приложение в строке меню одиночки в качестве канала всплывающих окон, когда оно запущено
- держит самое новое уведомление, требующее внимания, закреплённым в верхней части выпадающего списка строки меню для быстрого просмотра
- в противном случае использует наилучшее прямое уведомление на рабочем столе, если включены уведомления рабочего стола
- может отправлять дополнительное вебхук-уведомление для удалённых сред или сред без графического интерфейса

Используйте встроенную поверхность проверки в CLI для просмотра этих оповещений:```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

Локальный API и мост MCP предоставляют одинаковые данные для IDE и агентов:

• 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

Это поддерживаемый путь для IDE, клиентов MCP и агентов кодирования, чтобы отображать фоновые обнаружения после завершения первоначального сканирования.

Уведомления об обновлениях пакетов предназначены только для информирования. OreWatch сообщает о более новых версиях для наблюдаемых зависимостей проекта и самого OreWatch, но не изменяет манифесты, файлы блокировок или установленные пакеты.

Нативное приложение для строки меню macOS

Теперь OreWatch включает нативное приложение для строки меню macOS для тех, кто хочет видимый локальный интерфейс вместо того, чтобы полагаться только на команды CLI, опрос MCP или всплывающие уведомления Центра уведомлений (по возможности).

Установите дополнительные привязки Cocoa в ту же среду выполнения, которая предоставляет команду orewatch. Выберите команду, соответствующую вашему методу установки:```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

Затем запустите приложение строки меню:```bash
orewatch monitor menubar

По умолчанию monitor menubar перезапускает приложение в фоне и сразу возвращает приглашение оболочки. Используйте orewatch monitor menubar --foreground только если вы явно хотите оставить его привязанным к терминалу для отладки.

Приложение в строке меню подключается к тому же единственному экземпляру монитора. Оно не запускает второй экземпляр монитора. Если монитор еще не установлен и не запущен, приложение установит/запустит его при первом запуске.

Homebrew устанавливает привязки Cocoa в изолированную среду libexec OreWatch. Если orewatch monitor menubar сообщает No module named 'AppKit', обновите формулу командой brew update && brew reinstall rapticore/tap/orewatch. Для установок через pip, pipx и из исходного кода дополнительные привязки все еще необходимо добавить в то же окружение Python, которое предоставляет команду orewatch.

Когда уведомления рабочего стола включены в macOS, единственный экземпляр наблюдателя теперь поддерживает одно приложение в строке меню и использует его в качестве основной поверхности для всплывающих уведомлений. Это позволяет не полагаться только на вызов osascript из демона и дает вам постоянный нативный интерфейс для новых результатов.

Текущая сборка строки меню ориентирована на иконку. Старое сокращение OW и предыдущие формулировки иконки OreWatch следует рассматривать как устаревшие ссылки; приложение теперь предпочитает встроенную фирменную иконку и переключается на компактный текст или значки только когда macOS не может отобразить изображение или требуется счетчик предупреждений.

Что дает вам приложение в строке меню macOS:

• постоянный элемент строки состояния, который предпочитает встроенную фирменную иконку, с компактным текстовым запасным вариантом или значками предупреждений при необходимости
• компактное красное/жирное состояние предупреждения для недавно обнаруженных оповещений, которое остается видимым, пока вы не откроете меню
• живую сводку активных результатов и наивысшего уровня серьезности
• раздел обновлений пакетов первого класса с обновлениями зависимостей проекта, состоянием самообновления OreWatch, статусом последней проверки и копируемыми предлагаемыми командами
• последние уведомления в нативном выпадающем меню
• нативные всплывающие уведомления Центра уведомлений для недавно сохраненных оповещений монитора
• действие Add Workspace Folder..., которое добавляет проект в единственный экземпляр наблюдателя и запускает первоначальное быстрое сканирование
• встроенные переключатели конфигурации для уведомлений рабочего стола, уведомлений терминала, поддержания активности строки меню и всплывающих окон, управляемых строкой меню
• действия в один клик для открытия отчетов, домашней страницы монитора и журнала монитора
• действия в один клик для открытия файла конфигурации монитора и папки конфигурации
• действия меню для проверки обновлений пакетов, обновления данных об угрозах, запуска быстрого/полного сканирования, а также запуска/перезапуска/остановки единственного экземпляра монитора

Рекомендуемый рабочий процесс для Mac:

1. Однократно выполните orewatch monitor quickstart /path/to/project --client claude_code.
2. Установите дополнительные привязки в ту же среду, что и orewatch.
3. Запустите orewatch monitor menubar.
4. Держите приложение в строке меню запущенным для постоянного нативного интерфейса проверки, пока ваши IDE и агенты кодирования продолжают использовать MCP или локальный API.

Adoption Guide

Для более простого внедрения используйте целенаправленные документы вместо чтения полного README от начала до конца:

• docs/adoption-guide.md: кратчайший путь для внедрения локальными разработчиками
• docs/local-api.md: точный контракт локального API и MCP
• docs/e2e-testing.md: рабочий процесс для участников и валидации

Рекомендуемый порядок внедрения:

1. Начните с одного репозитория и одного пользователя.
2. Включите единственный экземпляр монитора с помощью monitor quickstart.
3. Подключите один клиент: Cursor, Claude Code, Codex, VS Code, PyCharm или Xcode.
4. Подтвердите, что результаты отображаются в orewatch monitor findings и orewatch monitor notifications.
5. В macOS добавьте monitor menubar, чтобы пользователи получили постоянную поверхность для проверки и доставку всплывающих уведомлений.
6. После стабилизации локального внедрения добавьте сканирование CI и опциональные вебхуки.

Daily Operations

Типовые операционные команды:```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

**Ручные действия по созданию снимка и подписанию:**```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

Поведение монитора:

• Быстрое сканирование ориентировано на пакеты и выполняется по расписанию и после общих изменений манифеста.
• Полное сканирование включает обнаружение IoC и выполняется каждую ночь, по ручному запросу, а также после изменений рабочего процесса или файлов полезной нагрузки.
• В Linux конфигурация по умолчанию находится в ~/.config/orewatch/singleton/, а состояние — в ~/.local/state/orewatch/singleton/.
• В macOS конфигурация по умолчанию находится в ~/Library/Application Support/OreWatch/singleton/, а состояние — в ~/Library/Application Support/OreWatch/State/singleton/.
• Общие данные об угрозах теперь находятся в каталоге состояния единственного экземпляра по пути threat-data/final-data/.
• Команда monitor doctor выводит точные значения config_path, state_db, log_file, final_data_dir и каталог шаблонов служб для монитора единственного экземпляра.
• Переопределения политик для каждого проекта могут храниться в файле в корне проекта.

Локальная интеграционная поверхность:

• OreWatch теперь предоставляет API, доступное только с localhost, на 127.0.0.1:48736 по умолчанию, когда демон монитора запущен.
• API использует персональный bearer token, хранящийся в каталоге конфигурации монитора по пути api.token с правами только для владельца.
• Прямые запросы к 127.0.0.1:48736 без заголовка Authorization: Bearer <token> будут корректно возвращать 401 Unauthorized.
• Агенты и IDE-клиенты должны обнаруживать монитор через команду orewatch monitor connection-info, а не угадывать пути, и должны отправлять фактический project_path, с которым они работают, внутри запросов проверки зависимостей.
• Claude Code, Codex и Cursor могут использовать встроенный MCP-мост, который предоставляет методы orewatch_health, orewatch_check_dependency_add, orewatch_check_manifest, orewatch_override_dependency_add, , , и .

Необязательная конфигурация живых обновлений с аномальным шлюзом:```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

Key behavior:
- Живые кандидаты сначала собираются в промежуточной области; они не перезаписывают активные базы данных во время сбора.
- Крупные падения, регрессии экосистем, пустые экосистемы и массовые удаления блокируют продвижение.
- Сбои основных источников по умолчанию являются только предупреждениями для обновлений открытых источников в реальном времени; падения и удаления на уровне экосистем по-прежнему блокируют неудачные продвижения.
- Аномалии только для предупреждений фиксируются в статусе и отчетах, но не препятствуют продвижению.
- Отклоненные кандидаты сохраняют активным последний известный корректный набор данных, если таковой уже существует.
- Первоначальная загрузка из потоков в реальном времени разрешена, если хотя бы один основной источник успешно сработал и кандидат предоставляет пригодные для использования данные экосистемы.

**Необязательная конфигурация вебхука уведомлений:**```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

Установите webhook_format: slack при нацеливании на входящий вебхук Slack. В этом режиме OreWatch отправляет простую полезную нагрузку text.

Распространение

Теперь у проекта есть две разные поверхности распространения:

1. Код CLI и монитора
2. Снимки данных угроз, потребляемые монитором

Их следует распространять отдельно.

Рекомендуемое распространение пакетов

Лучший вариант по умолчанию для разработчиков: публиковать сканер как обычный Python-пакет на PyPI и рекомендовать установку с помощью pipx.

Почему это лучший вариант:

• Проект представляет собой Python CLI и фоновый монитор, поэтому универсальное колесо плюс исходный дистрибутив — самый прямой артефакт выпуска.
• pipx предоставляет разработчикам изолированную установку на уровне пользователя, не загрязняя проектные виртуальные окружения.
• CI все еще может установить ту же версию с помощью python3.14 -m pip install orewatch==<version>.
• Это упрощает путь обновления CLI, оставляя обновления данных угроз подписанному каналу снимков.

Рекомендуемая форма выпуска:

• Публикуйте артефакты sdist и универсального колеса на PyPI.
• Откройте точку входа консоли orewatch.
• Сохраните ore-mal-pkg-inspector как временный псевдоним совместимости.
• Задокументируйте pipx install --python python3.14 orewatch для локальных установок разработчиками.
• Задокументируйте python3.14 -m pip install orewatch==<version> для CI и фиксированной автоматизации.

Доступный вторичный канал: теперь доступен tap Homebrew для пользователей macOS, предпочитающих установки под управлением Brew:```bash brew install rapticore/tap/orewatch

Homebrew remains a convenience layer over the published PyPI release, not the primary release artifact.

**Best option for contributors:** keep the current source-checkout flow:```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 .

Управляемый запуск на macOS

Если вы разворачиваете OreWatch с помощью Kandji, Jamf Pro, Intune, Munki или другой системы распространения ПО на macOS, рекомендуемая модель отличается от пути разработчика через pipx.

Текущая реальность продукта:

• сегодня репозиторий поставляет Python-пакет, а не собственный нотаризованный пакет установщика macOS
• для управляемых парков рекомендуемый артефакт — подписанный плоский .pkg, собранный на основе опубликованного колеса OreWatch
• снимки данных угроз по-прежнему должны распространяться отдельно от пакета приложения/среды выполнения

Рекомендуемая модель корпоративного развертывания:

1. Установка на устройство
   • разверните подписанный .pkg, который устанавливает среду выполнения OreWatch и стабильную обёртку CLI orewatch
   • опционально включите дополнение mac-menubar, если хотите иметь нативное приложение в строке меню на управляемых Mac
2. Активация пользователя
   • запустите orewatch monitor quickstart /path/to/project --client <client> или эквивалентную загрузку в контексте пользователя
   • этот шаг отделён, поскольку монитор OreWatch намеренно для каждого пользователя и использует пользовательский LaunchAgent, а также конфигурацию, токен и состояние, принадлежащие пользователю
3. Постоянные обновления
   • обновляйте пакет среды выполнения в соответствии с вашим обычным жизненным циклом ПО
   • обновляйте снимки данных угроз независимо через подписанный канал снимков или путь живого обновления

Почему это разделение важно:

• Инструменты MDM хороши для установки кода на машину
• Монитор OreWatch, токен API и служба launchd ограничены пользователем, поэтому их следует создавать в контексте вошедшего пользователя, а не навязывать из установки пакета в масштабе машины

Рекомендуемая форма пакета для управляемого macOS:

• выделенная среда выполнения по стабильному пути, например /Library/Application Support/OreWatch/runtime
• стабильная обёртка, например /usr/local/bin/orewatch
• метаданные пакета с версиями, чтобы платформы MDM могли чисто обнаруживать обновления
• подпись кода и нотаризация там, где этого требует политика вашего парка

Рекомендации для конкретных вендоров:

• Kandji
  • используйте Custom App с Installer Package (.pkg)
  • предпочитайте .pkg вместо .dmg или .zip для OreWatch, поскольку среда выполнения не является приложением для перетаскивания
  • используйте Self Service или шаг адаптации для пользователя при первой активации монитора
• Jamf Pro
  • загрузите .pkg как Package и разверните его с помощью Policy или Self Service
  • держите активацию пользователя отдельно от развертывания пакета на машине, если у вас нет намеренного шага загрузки в контексте пользователя
• Microsoft Intune
  • используйте macOS LOB приложение с подписанным .pkg
  • Intune строже, чем другие каналы: он ожидает настоящий .pkg, подписанный сертификатом Developer ID Installer, и пакет должен содержать полезную нагрузку
• Munki
  • опубликуйте .pkg вместе с метаданными pkg и обращайтесь с OreWatch как с другим управляемым ПО macOS
  • Munki хорошо подходит, когда вам нужен репозиторий пакетов и необязательное внедрение в стиле Self Service

Для более полного сценария развертывания см. docs/managed-rollout.md.

Рекомендуемое распространение снимков

Снимки данных угроз не должны быть встроены в Python-пакет. Они меняются с другой периодичностью и уже поддерживаются как подписанные размещенные артефакты.

По умолчанию для open-source/сообщества: получайте openssf и osv напрямую через путь живого обновления с контролем аномалий. По умолчанию для предприятия: публикуйте версионные подписанные снимки на статическом HTTPS-хостинге и позволяйте клиентам обновлять их независимо.

Рекомендуемые цели размещения:

• Ресурсы GitHub Releases
• S3 или Cloudflare R2 через HTTPS
• Любое статическое ведро на CDN, которое обслуживает неизменяемые версионные файлы

Рекомендуемая структура снимков:

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

Рекомендуемая модель доверия:

• Храните закрытый ключ подписи офлайн
• Поставляйте только открытый ключ проверки с конфигурацией клиента или пакетом
• Проверяйте каждый дескриптор канала и манифест перед загрузкой/применением

Рекомендуемая общая модель

Для производственного выпуска самая чистая настройка:

• Распространяйте приложение как PyPI-пакет
• Устанавливайте локально с помощью pipx
• Устанавливайте в CI с помощью pip
• Распространяйте данные угроз как подписанные каналы снимков через HTTPS
• Относитесь к копированию исходного кода как к пути разработки, а не как к основному способу установки для конечного пользователя

Логирование и отладка

По умолчанию сканер показывает только предупреждения, ошибки и итоговую сводку. Для устранения неполадок или детального отслеживания прогресса используйте флаги логирования:

Подробный режим

Просмотр сообщений о ходе выполнения и статистики сбора:```bash orewatch /path/to/project --verbose

**Output includes:**
- Результаты определения экосистемы
- Прогресс анализа файлов
- Количество извлечённых пакетов
- Детали запросов к базе данных
- Прогресс сканирования IoC

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

Режим отладки

Смотрите подробную диагностическую информацию для устранения неполадок:```bash orewatch /path/to/project --debug

**Вывод включает:**
- Все сообщения уровня INFO
- Сканируемые пути к файлам
- Детали выполнения SQL-запросов
- Вычисления хешей
- Результаты сопоставления шаблонов
- Информацию о внутреннем состоянии

**Сценарии использования:**
- Выяснение, почему пакет не был обнаружен
- Отладка проблем автоопределения экосистемы
- Сообщение о проблемах с подробным контекстом
- Аудит поведения сканера

### Логирование для сборщиков

Сборщики данных об угрозах также поддерживают режимы verbose и debug:```bash
cd collectors

# See collection progress
python3 orchestrator.py --verbose

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

Примечание: Все журналы выводятся в stderr, что позволяет оставить stdout чистым для вывода отчёта в формате JSON. Это даёт возможность передавать результаты сканирования другим инструментам без помех от сообщений журнала.

Вывод и отчёты

Структура отчёта

Отчёты сохраняются в каталог scan-output/ по умолчанию (или в пользовательский путь с помощью --output). OreWatch создаёт машиночитаемый отчёт в формате JSON и стилизованный HTML-отчёт с тем же базовым именем. Артефакт JSON включает метаданные о доступности данных об угрозах и использует объекты physicalLocation в стиле SARIF для данных о пакетах, но не является полноценным документом SARIF 2.1.0.

Пример отчёта:```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" } ] }

**Поля данных угроз:**
- `data_status`: `complete`, `partial`, `failed` или `not_applicable`
- `sources_used`: источники, предоставившие полезные данные об угрозах для запрошенных экосистем
- `experimental_sources_used`: экспериментальные источники, включенные в данные сканирования
- `missing_ecosystems`: запрошенные экосистемы, для которых не было полезной базы данных угроз пакетов
- `promotion_decision`: пусто для сканирований существующих данных, в противном случае `promoted`, `bootstrapped` или `rejected`
- `kept_last_known_good`: `true`, когда живой кандидат был отклонен, но предыдущий активный набор данных остался полезным
- `anomalies`: предупреждения/блокирующие аномалии, возникшие во время попытки обновления в реальном времени

### Понимание результатов

**Уровни серьезности:**
- **CRITICAL:** Известный вредоносный код с активными эксплойтами или утечкой данных
- **HIGH:** Сильные признаки злонамеренных намерений или тайпсквоттинга
- **MEDIUM:** Подозрительные шаблоны или потенциальные уязвимости
- **LOW:** Незначительные проблемы или информационные находки

**Рекомендуемые действия:**
1. **Критические/высокие находки:** Немедленно удалите затронутые пакеты и исследуйте влияние
2. **Просмотрите IoCs:** Проверьте, выполнился ли вредоносный код (логи, сетевая активность)
3. **Обновите зависимости:** Замените вредоносные пакеты на легитимные альтернативы
4. **Повторите сканирование:** Проверьте устранение с последующим сканированием
5. **Сообщите:** Рассмотрите возможность сообщения мейнтейнерам реестра пакетов

---

## Интеграция CI/CD

### GitHub Actions

**Базовая проверка безопасности:**```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/

Продвинутый с отказом при обнаружении:```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
    }
}

}

### Pre-commit хук

Добавьте в `.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"

Устранение неполадок

Распространенные проблемы

Ошибка «База данных не найдена»

Симптом:``` ERROR: No usable threat data available for requested ecosystems: npm

**Причина:** Сбор данных об угрозах не удался, метаданные неполные, или запрошенные экосистемы еще не имеют пригодных локальных баз данных.

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

Примечание: Если это продолжается, проверьте сетевое подключение, права доступа к файловой системе и не запрашивали ли вы намеренно экспериментальные источники.

Предупреждение «Пакеты не обнаружены»

Симптом:``` WARNING: No packages detected in /path/to/project

**Возможные причины и решения:**

1. **Неправильная директория:** Убедитесь, что вы сканируете правильную директорию проекта   ```bash
   ls /path/to/project  # Verify package.json or requirements.txt exists

2. Неподдерживаемый или неожиданный манифест: Вывести точные поддерживаемые имена файлов ```bash orewatch --list-supported-files
   root@kitploit:~

3. Права доступа к файлам: Убедитесь, что файлы доступны для чтения ```bash ls -la /path/to/project/package.json
   root@kitploit:~

Ошибки подключения при обновлении

Симптом:``` ERROR: Error downloading npm: <urlopen error [Errno -3] Temporary failure in name resolution>

**Решения:**

1. **Проверьте подключение к интернету:**   ```bash
   ping google.com

2. Повторить с увеличением таймаута: Edit collectors/config.yaml: ```yaml osv: timeout: 600 # Increase from default 300
   root@kitploit:~

3. Используйте кешированные данные: Если вы ранее загружали данные: ```bash python3 orchestrator.py --skip-build # Skip download, rebuild from cache
   root@kitploit:~

Ошибки отказа в доступе

Симптом:``` ERROR: Error creating directory collectors/raw-data: Permission denied

**Решение:**```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 использует слишком много места на диске

Симптом: ~/Library/Application Support/OreWatch (macOS) или $XDG_STATE_HOME/orewatch (Linux) разросся до десятков гигабайт.

Причина (до версии 1.2.3): При каждом обновлении в реальном времени архивировалась полная копия предыдущих баз данных угроз (~300 МБ) без ограничения срока хранения. Долго работающий монитор накапливал по одному снимку за каждый цикл бесконечно.

Исправление: Обновитесь до 1.2.3 или новее. Резервные копии теперь представляют собой манифесты SHA-256 размером ~1 КБ, по умолчанию хранятся последние 30, и доступна явная команда очистки:```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

#### Ложные срабатывания

**Симптом:** Легитимный пакет помечен как вредоносный.

**Шаги:**

1. **Проверьте результат:** Просмотрите детали отчета, включая серьезность и описание

2. **Проверьте версию:** Помеченная версия может быть конкретной:   ```bash
   orewatch /path/to/project --verbose

3. Сообщить о ложном срабатывании: Если подтверждено, что это ошибка:
   • Откройте issue на https://github.com/rapticore/ore-mal-pkg-inspector/issues с подробностями

Режим отладки для расследования

Включить подробное логирование:```bash

Scanner debug mode

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

Collector debug mode

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

**Review logs:** Проверьте `debug.log` для подробной трассировки выполнения, включая:
- Сканированные пути файлов
- Выполненные SQL-запросы
- Результаты сопоставления с шаблонами
- Трассировки стека ошибок

---

## Часто задаваемые вопросы

### Как часто нужно обновлять данные об угрозах?

**Рекомендация:**
- **Рабочие/CI среды:** Ежедневные автоматические обновления
- **Рабочие станции разработчиков:** Минимум еженедельные обновления
- **После новостей о безопасности:** Немедленное обновление при объявлении новых угроз

Вредоносные пакеты публикуются непрерывно. Ежедневные обновления обеспечивают актуальную защиту.

### Как обновить данные об угрозах?

Запустите сканер с флагом `--latest-data`, чтобы принудительно обновить данные:```bash
orewatch /path/to/project --latest-data

Для автоматических обновлений в CI/CD планируйте периодические сканирования с флагом --latest-data (например, ежедневно). Добавляйте --include-experimental-sources только если вы явно хотите включить данные из Phylum в перестроение.

Примечание: Первые сканирования автоматически собирают данные, поэтому ручные обновления нужны только для обновления существующих баз данных.

Откуда берутся данные об угрозах?

Базы данных по умолчанию строятся из основных источников угроз проекта:

• openssf
• osv

Сканер также может включать экспериментальный набор источников проекта:

• phylum с --include-experimental-sources

socketdev присутствует в репозитории как отключённый плейсхолдер и не является частью стандартного пути сбора.

Технические подробности об источниках данных, сборе и обработке см. в ARCHITECTURE.md.

Изменяет ли этот инструмент мой код или зависимости?

Нет. OreWatch выполняет операции только на чтение. Он:

• ✅ Читает файлы зависимостей
• ✅ Запрашивает базы данных угроз
• ✅ Сканирует шаблоны файлов
• ✅ Генерирует отчёты

Он никогда:

• ❌ Не изменяет файлы пакетов
• ❌ Не устанавливает и не удаляет пакеты
• ❌ Не меняет конфигурацию проекта
• ❌ Не выполняет код пакетов

Что делать, если мой пакет помечен как вредоносный?

Действия:

1. Проверьте результат: Изучите отчёт для получения деталей и уровня серьёзности
2. Просмотрите доказательства: Ознакомьтесь с описанием и обнаруженным поведением
3. Проверьте версии: Определите, затронуты ли конкретные версии
4. Если легитимен:
   • Сообщите о ложном срабатывании ответственным за источник данных
   • Откройте issue на нашем GitHub с подробностями
5. Если действительно вредоносный:
   • Немедленно удалите пакет
   • Просмотрите недавние коммиты кода на предмет ущерба
   • Проверьте логи на подозрительную активность
   • Обновитесь до безопасной альтернативы

Можно ли использовать офлайн?

Частично.

Офлайн-сканирование: ✅ Да, после инициализации баз данных```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:** ❌ Нет, для сбора данных об угрозах требуется доступ в интернет для получения информации из источников безопасности.

**Изолированные среды:** Вы можете:
1. Загрузить базы данных на машину с доступом в интернет
2. Перенести SQLite-файлы в единственный `final_data_dir`, указанный командой `orewatch monitor doctor`
3. Выполнять сканирование офлайн с потенциально устаревшими данными

### Как это сравнивается с npm audit или pip-audit?

**Разные цели:**

**npm audit / pip-audit:**
- Сосредоточены на известных уязвимостях CVE
- Проверяют версии пакетов по базам данных рекомендаций
- Поддерживаются командами реестров пакетов

**OreWatch:**
- Сосредоточен на вредоносных пакетах (не только уязвимых)
- Обнаруживает typosquatting, вредоносное ПО, атаки на цепочки поставок
- Межэкосистемное покрытие
- Обнаружение IoC для активных угроз

**Лучшая практика:** Используйте **оба** инструмента:```bash
# Check for vulnerabilities
npm audit
pip-audit

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

Работает ли это с частными реестрами пакетов?

Сканирование зависимостей: ✅ Да, сканер читает ваши файлы зависимостей независимо от происхождения пакетов.

Threat intelligence (аналитика угроз): ⚠️ Ограниченно. Наши базы данных охватывают публичные реестры (npmjs.com, pypi.org и т.д.). Вредоносные пакеты из частных реестров не будут обнаружены, если вы не добавите собственные данные об угрозах.

Собственные данные об угрозах: Вы можете расширить базы данных своими списками вредоносных пакетов. Свяжитесь с нами для получения рекомендаций по этому продвинутому сценарию использования.

Какова производительность?

Время сканирования:

• Небольшие проекты (< 50 пакетов): < 5 секунд
• Средние проекты (50-500 пакетов): 5-30 секунд
• Крупные проекты (500+ пакетов): 30-120 секунд

Факторы:

• Сканирование индикаторов компрометации (IoC) добавляет 10-50% накладных расходов (отключите с помощью --no-ioc, если не требуется)
• Первый запуск может быть медленнее, так как базы данных загружаются в память

Советы по оптимизации:```bash

Scan specific files instead of entire directory

orewatch --file package.json

---

## Участие в разработке

Мы приветствуем вклад! Независимо от того, сообщаете ли вы об ошибках, предлагаете функции или вносите код, ваша помощь улучшает OreWatch для всех.

**Сообщить об ошибках или предложить функции:**
- GitHub Issues: https://github.com/rapticore/ore-mal-pkg-inspector/issues

**Внести код:**
- См. [CONTRIBUTING.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/CONTRIBUTING.md) для подробных рекомендаций по настройке среды разработки, стилю кода, тестированию и процессу pull request

**Вопросы или обсуждения:**
- GitHub Discussions: https://github.com/rapticore/ore-mal-pkg-inspector/discussions

---

## Политика безопасности

Безопасность — наш главный приоритет. OreWatch — это инструмент безопасности, и мы серьёзно относимся к уязвимостям.

### Сообщение об уязвимостях

**НЕ открывайте публичные GitHub Issues для уязвимостей.**

Вместо этого сообщайте приватно:

**Email:** [email protected]

**Укажите:**
- Описание уязвимости
- Шаги для воспроизведения
- Потенциальное воздействие
- Предлагаемое исправление (если применимо)
- Вашу контактную информацию для обратной связи

### Сроки ответа

- **Подтверждение:** в течение 48 часов
- **Первичная оценка:** в течение 7 дней
- **Сроки исправления:** зависят от критичности
  - Критическая: 7-14 дней
  - Высокая: 14-30 дней
  - Средняя/Низкая: 30-60 дней

### Лучшие практики безопасности

При использовании OreWatch:

**Делайте:**
- ✅ Запускайте с минимальными привилегиями (не требуется root/admin)
- ✅ Регулярно обновляйте данные об угрозах
- ✅ Своевременно просматривайте отчёты сканирования
- ✅ Интегрируйте в CI/CD для непрерывной защиты
- ✅ Обновляйте инструмент до последней версии

**Не делайте:**
- ❌ Игнорируйте результаты сканирования без расследования
- ❌ Отключайте сканирование IoC в производственных средах
- ❌ Делитесь файлами базы данных из ненадёжных источников
- ❌ Запускайте с повышенными привилегиями без необходимости

### Раскрытие уязвимостей

Мы следуем координированному раскрытию:
1. Уязвимость сообщается приватно
2. Разрабатывается и тестируется исправление
3. Публикуется бюллетень безопасности
4. Публичное раскрытие после доступности исправления

### Зал славы безопасности

Мы признаём исследователей безопасности, ответственно сообщающих об уязвимостях:

*Список будет пополняться по мере получения отчётов*

---

### Запросы сообщества

Голосуйте или предлагайте функции:
- **GitHub Discussions:** https://github.com/rapticore/ore-mal-pkg-inspector/discussions
- **Feature Requests:** https://github.com/rapticore/ore-mal-pkg-inspector/issues

### Участие в дорожной карте

Мы расставляем приоритеты функций на основе:
- Влияния на безопасность
- Востребованности сообществом
- Устойчивости сопровождения
- Соответствия целям проекта

Чтобы повлиять на дорожную карту:
1. Откройте запрос функции с подробным сценарием использования
2. Участвуйте в обсуждениях
3. Вносите реализации (PR приветствуются!)

---

## Дорожная карта

OreWatch уже сегодня применим для:

- локальных CLI-сканирований в npm, PyPI, Maven, RubyGems, Go и Cargo
- одного фонового монитора на пользователя для многих проектов
- интеграций MCP для Cursor, Claude Code и Codex
- интеграций через localhost API для VS Code, JetBrains / PyCharm и Xcode helpers
- панели меню macOS и всплывающих уведомлений

Ближайшие приоритеты:

- примеры интеграции первого уровня для VS Code и JetBrains / PyCharm или тонкие плагины
- более сильные рабочие процессы уведомлений для пользователей, выходящие за рамки локальных всплывающих окон
- более чёткое управление политиками проектов из CLI и UI
- более богатая отчётность монитора и документация по внедрению

Среднесрочные приоритеты:

- более широкие рабочие процессы сканирования проектов из монитора и поверхности MCP
- более качественные рекомендации по развёртыванию на уровне организации
- более надёжные каналы внешней доставки оповещений и эскалации
- более глубокая IDE-специфичная UX вместо интеграции только через API

Известное текущее ограничение:

- Интеграция с Xcode на данный момент наилучшим образом подходит для видимости предупреждений и репозиториев со смешанными языками. OreWatch пока не анализирует нативные манифесты Apple, такие как `Package.resolved`, `Podfile.lock` или `Cartfile`.

Долгосрочное направление:

- поддержка манифестов нативной экосистемы Apple
- более мощные интеграции редакторов первого уровня
- более широкая согласованность UX операционных систем за пределами текущего пути панели меню macOS

См. [docs/roadmap.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/roadmap.md) для более подробного представления дорожной карты, ориентированной на внедрение.

---

## Лицензия

Лицензия MIT

Copyright (c) 2025 Rapticore

Настоящим предоставляется бесплатное разрешение любому лицу, получившему копию данного программного обеспечения и сопутствующей документации (далее — «Программное обеспечение»), без ограничений, включая, без ограничения, права на использование, копирование, изменение, слияние, публикацию, распространение, сублицензирование и/или продажу копий Программного обеспечения, а также разрешение лицам, которым предоставляется Программное обеспечение, делать это при соблюдении следующих условий:

Вышеуказанное уведомление об авторских правах и данное уведомление о разрешении должны быть включены во все копии или существенные части Программного обеспечения.

ПРОГРАММНОЕ ОБЕСПЕЧЕНИЕ ПРЕДОСТАВЛЯЕТСЯ «КАК ЕСТЬ», БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ, ЯВНЫХ ИЛИ ПОДРАЗУМЕВАЕМЫХ, ВКЛЮЧАЯ, НО НЕ ОГРАНИЧИВАЯСЬ, ГАРАНТИЯМИ ТОВАРНОЙ ПРИГОДНОСТИ, СООТВЕТСТВИЯ ОПРЕДЕЛЁННОЙ ЦЕЛИ И ОТСУТСТВИЯ НАРУШЕНИЙ. НИ В КОЕМ СЛУЧАЕ АВТОРЫ ИЛИ ПРАВООБЛАДАТЕЛИ НЕ НЕСУТ ОТВЕТСТВЕННОСТИ ПО КАКИМ-ЛИБО ИСКАМ, УБЫТКАМ ИЛИ ИНЫМ ТРЕБОВАНИЯМ, ВОЗНИКАЮЩИМ ИЗ ДОГОВОРА, ДЕЛИКТА ИЛИ ИНЫМ ОБРАЗОМ ИЗ ИЛИ В СВЯЗИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ, ЕГО ИСПОЛЬЗОВАНИЕМ ИЛИ ИНЫМИ ДЕЙСТВИЯМИ С ПРОГРАММНЫМ ОБЕСПЕЧЕНИЕМ.

---

## Поддержка

### Получение помощи

**Документация:** Вы её читаете! Начните отсюда для большинства вопросов.

**GitHub Discussions:** Для вопросов, идей и взаимодействия с сообществом:
- https://github.com/rapticore/ore-mal-pkg-inspector/discussions

**GitHub Issues:** Для отчётов об ошибках и запросов функций:
- https://github.com/rapticore/ore-mal-pkg-inspector/issues

**Email:** Для сообщений об уязвимостях и частных запросов:
- [email protected]

### Профессиональная поддержка

Для организаций, которым требуется:
- Пользовательские интеграции
- Поддержка с соглашением об уровне обслуживания (SLA)
- Помощь в частном развёртывании
- Пользовательские каналы данных об угрозах

Контакт: [email protected]

---

## Благодарности

### Происхождение проекта

Этот проект был выделен из репозитория [OreNPMGuard](https://github.com/rapticore/OreNPMGuard) для сохранения чёткой направленности проекта при расширении возможностей.

**OreNPMGuard** (декабрь 2025) специализируется на обнаружении атак Shai-Hulud npm с более чем 738 затронутыми пакетами и глубоким анализом IoC. В ходе его разработки мы осознали необходимость более широкой межэкосистемной защиты, что привело к созданию OreWatch как самостоятельного инструмента, служащего всему сообществу разработчиков во всех основных экосистемах пакетов.

### Связанные проекты

- **[OreNPMGuard](https://github.com/rapticore/OreNPMGuard)** — специализированный сканер Shai-Hulud для npm

---

**Создано командой безопасности Rapticore**

*Защита цепочек поставок программного обеспечения, одно сканирование за раз.*