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 통합
• 문제 해결
• FAQ
• 기여
• 보안 정책
• 로드맵
• 라이선스
• 지원
• 감사의 말

문제

공급망 공격은 이제 소프트웨어 손상의 주요 위협 벡터입니다. 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 통합 OreNPMGuard의 포괄적인 Shai-Hulud 영향 패키지 목록과 npm 패키지 교차 참조.

구조화된 JSON 보고서 명시적 위협 데이터 메타데이터 및 발견 사항에 대한 SARIF 스타일 파일 위치가 포함된 기계 판독 가능 JSON 보고서 생성.

유연한 입력 형식 표준 의존성 파일(package.json, requirements.txt 등) 및 일반 패키지 목록(텍스트, JSON, YAML) 지원.

프로덕션 준비 로깅 문제 해결 및 감사 추적을 위한 --verbose 및 --debug 플래그로 구성 가능한 상세 수준.

안전하고 빠름 코드를 수정하지 않는 읽기 전용 작업, 대규모 코드베이스 효율적 스캔에 최적화됨.

왜 OreWatch인가?

vs. 단일 생태계 도구 대부분의 보안 스캐너는 하나의 패키지 관리자에 집중합니다. OreWatch는 현대적인 다중 언어 개발 환경에서 필수적인 6개 주요 생태계에 걸친 통합 보호를 제공합니다.

vs. 수동 위협 목록 정적 악성 패키지 목록은 빠르게 구식이 됩니다. 자동화된 수집기는 여러 권위 있는 출처에서 매일 새로운 위협 인텔리전스를 가져옵니다.

vs. 패키지 이름만 탐지 패키지 이름만 확인하면 정교한 공격을 놓칩니다. IoC 탐지는 차단 목록에 없는 패키지에서도 악성 코드 패턴을 식별합니다.

vs. 수동 보안 감사 수동 의존성 검토는 시간이 많이 소요되고 오류가 발생하기 쉽습니다. 자동화된 스캔은 모든 빌드에서 지속적인 보안 검증을 가능하게 합니다.

vs. 상용 블랙박스 도구 독점 도구는 탐지 로직에 대한 투명성이 부족합니다. 오픈 소스 프로젝트로서 모든 탐지 규칙과 데이터 소스를 감사할 수 있습니다.

기원 이야기 OreWatch는 OreNPMGuard(Shai-Hulud npm 공격 전용 스캐너) 개발 과정에서 탄생했습니다. 해당 프로젝트에서 npm을 넘어 더 넓은 다중 생태계 지원의 필요성을 인식했습니다. 2025년 12월, 다중 생태계 탐지 기능을 추출 및 개선하여 이 독립형 도구를 만들었으며, OreNPMGuard의 npm 집중도를 유지하면서 OreWatch가 모든 주요 패키지 생태계 전반의 더 넓은 개발자 커뮤니티를 지원할 수 있게 했습니다.

여기서 시작하세요

처음으로 OreWatch를 도입하는 경우, 워크플로우에 맞는 가장 간단한 경로를 선택하세요:

대부분의 개발자에게 권장되는 첫 실행 순서:

1. pip install . 또는 게시된 패키지로 OreWatch 설치.
2. orewatch monitor quickstart /path/to/project --client <your-client> 실행.
3. orewatch monitor status로 데몬 확인.
4. macOS를 사용 중이라면 알림 및 로컬 UI를 위해 orewatch monitor menubar 실행.

복사하여 붙여넣기 가능한 명령어가 포함된 더 짧은 설정 가이드는 docs/adoption-guide.md를 참조하세요.

빠른 시작

전제 조건

• Python 3.14 이상
• 의존성 설치를 위한 pip
• 저장소 복제를 위한 Git
• 초기 위협 인텔리전스 설정을 위한 인터넷 연결
• 모니터 스냅샷 워크플로우에서 서명된 스냅샷 키 생성, 게시 및 확인을 위한 OpenSSL

설치

OreWatch는 pipx(권장), Homebrew(macOS), pip, 또는 소스를 통해 설치할 수 있습니다. 모든 방법으로 orewatch CLI 명령어가 제공됩니다.

옵션 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 메뉴 바 앱을 추가하려면, 동일한 pipx 환경에 Cocoa 바인딩을 주입하세요:```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 수식에는 `orewatch monitor menubar`가 필요로 하는 Cocoa 바인딩이 포함되어 있습니다. 이전 Homebrew 설치에서 `ModuleNotFoundError: No module named 'AppKit'` 오류가 보고된다면 `brew update && brew reinstall rapticore/tap/orewatch`를 실행하여 수식이 메뉴 막대 지원과 함께 격리된 Python 환경을 다시 빌드하도록 하십시오.

#### 옵션 3 — pip

CI 파이프라인, Docker 이미지 또는 자체 virtualenv를 관리하는 경우 `pip`를 사용하십시오:```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` or pyenv | 자신의 배포판이 3.14+를 제공하는지 확인하세요 |
| **Fedora / RHEL** | `sudo dnf install python3.14` or pyenv | — |
| **Windows (WSL)** | pyenv or system package | 네이티브 Windows는 테스트되지 않음 |

> **Python 3.14가 필요합니다.** OreWatch는 Python 3.14에서 도입된 언어 기능을 사용합니다.
> 이전 버전은 임포트 시 실패합니다.

#### 설치 문제 해결

| 증상 | 해결 방법 |
|---|---|
| `command not found: orewatch` | 설치 위치가 `PATH`에 있는지 확인하세요. pipx의 경우: `pipx ensurepath`를 실행하고 셸을 다시 시작하세요. |
| 임포트 시 `ModuleNotFoundError` | 여러 Python 버전이 있을 수 있습니다. `orewatch`의 런타임이 Python 3.14+인지 확인하고 일치하는 인터프리터로 재설치하세요. |
| pipx 설치 시 확인자 오류로 실패 | pipx 업그레이드: `python3.14 -m pip install --upgrade pipx` |
| Homebrew `orewatch` 설치 후 찾을 수 없음 | 먼저 `brew tap rapticore/tap`을 실행한 후 설치를 다시 시도하세요. |
| pip 설치 중 권한 거부됨 | `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

**Batch Scanning:**```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` 싱글톤 데몬과 API가 실행 중인지 표시합니다
- `monitor connection-info` 루프백 API URL, 토큰 경로, 모니터 홈, 지원되는 부트스트랩 클라이언트를 출력합니다
- `monitor doctor` 정확한 구성, 상태 DB, 로그 및 공유 위협 데이터 경로를 출력합니다

**3. 싱글톤이 감시할 모든 프로젝트를 추가하세요**```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

One 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 bridge를 사용합니다:```bash orewatch monitor mcp

권장 설정:

1. `orewatch monitor quickstart /path/to/project --client <cursor|claude_code|codex>`를 한 번 실행합니다.
2. 출력된 MCP 블록을 해당 MCP 클라이언트에 복사합니다.
3. 감시 중인 프로젝트를 해당 클라이언트에서 엽니다.
4. 클라이언트가 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 통합은 MCP 브리지 대신 싱글톤 localhost API를 사용해야 합니다.

권장 설정:

1. `orewatch monitor quickstart /path/to/project --client vscode`를 실행합니다.
2. `orewatch monitor ide-bootstrap --client vscode`에서 `baseUrl`과 `tokenPath`를 복사합니다.
3. 해당 값을 로컬 VS Code 확장, 작업 또는 도우미에 연결합니다.
4. 종속성 추가, 매니페스트 저장, 알림 새로고침 이벤트에서 API를 호출합니다.

VS Code 통합을 위한 권장 API 사용법:

- 패키지 관리자 설치/추가 흐름 전에 `POST /v1/check/dependency-add` 호출
- 지원되는 매니페스트가 저장되거나 명시적으로 재확인될 때 `POST /v1/check/manifest` 호출
- 백그라운드 탐지를 표시하기 위해 `GET /v1/findings/active` 및 `GET /v1/notifications` 폴링

##### JetBrains / PyCharm

JetBrains 및 PyCharm은 VS Code와 동일한 localhost API 계약을 사용합니다.

권장 설정:

1. `orewatch monitor quickstart /path/to/project --client jetbrains`를 실행합니다.
2. `orewatch monitor ide-bootstrap --client jetbrains`에서 API 블록을 복사합니다.
3. 반환된 `baseUrl`과 `tokenPath`를 JetBrains 플러그인, 외부 도구 또는 로컬 도우미에서 사용합니다.
4. IDE 내에서 동기적 종속성 결정과 저장된 백그라운드 알림을 모두 표시합니다.

JetBrains 통합을 위한 권장 API 사용법:

- `POST /v1/check/dependency-add`로 종속성 추가 확인
- `POST /v1/check/manifest`로 `package.json`, `requirements.txt`, `pyproject.toml`, `pom.xml`, `Gemfile`, `go.mod`, `Cargo.toml` 및 관련 지원 매니페스트 재확인
- 지속적인 알림 패널 또는 도구 창을 위해 `GET /v1/findings/active` 및 `GET /v1/notifications` 가져오기

##### Xcode

Xcode 통합도 싱글톤 localhost API를 사용해야 하지만 중요한 범위 제한이 있습니다. OreWatch는 아직 `Package.resolved`, `Podfile.lock` 또는 `Cartfile`과 같은 기본 Apple 종속성 매니페스트를 구문 분석하지 않습니다. 현재 Xcode 통합은 다음에 가장 적합합니다:

- 도우미, 스크립트 또는 동반 앱에서 백그라운드 분석 결과 및 알림 표시
- Xcode에서 열린 혼합 언어 저장소로 `package.json`, `pyproject.toml` 또는 `Cargo.toml`과 같은 지원 매니페스트도 포함하는 경우
- Xcode에서 작업하는 동안 macOS 메뉴 막대 앱 및 알림 센터 알림을 원하는 팀

권장 설정:

1. `orewatch monitor quickstart /path/to/project --client xcode`를 실행합니다.
2. `orewatch monitor ide-bootstrap --client xcode`에서 API 블록을 복사합니다.
3. 빌드 단계 스크립트, 도우미 프로세스 또는 사용자 정의 Xcode 통합에서 반환된 `baseUrl`과 `tokenPath`를 사용합니다.
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는:

- 싱글톤 모니터 `reports/` 디렉토리 아래에 모니터가 관리하는 JSON 및 HTML 보고서를 작성합니다
- 활성 분석 결과를 모니터 상태 DB에 저장합니다
- 실행 가능한 메시지가 포함된 알림 항목을 저장합니다
- 터미널 알림이 활성화된 경우 터미널 경고를 출력합니다
- 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는 이제 CLI 명령어, MCP 폴링 또는 최선의 알림 센터 팝업에만 의존하지 않고 눈에 보이는 로컬 UI를 원하는 사람들을 위해 macOS 네이티브 메뉴 막대 앱을 포함합니다.

orewatch 명령어를 제공하는 동일한 런타임에 선택적 Cocoa 바인딩을 설치하세요. 설치 방법에 맞는 명령어를 선택하십시오:```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 바인딩을 OreWatch의 격리된 libexec 환경에 설치합니다. orewatch monitor menubar에서 No module named 'AppKit' 오류가 보고되면 brew update && brew reinstall rapticore/tap/orewatch로 포뮬러를 새로 고치십시오. pip, pipx 및 소스 설치의 경우, 선택적 바인딩은 여전히 orewatch 명령을 제공하는 동일한 Python 환경에 추가해야 합니다.

macOS에서 데스크톱 알림이 활성화되면, 단일 와처는 이제 하나의 단일 메뉴 막대 앱을 유지하고 이를 기본 팝업 표면으로 사용합니다. 이렇게 하면 데몬에서 분리된 osascript 호출에만 의존하는 것을 피하고 새로운 발견 사항에 대한 지속적인 네이티브 UI를 제공합니다.

현재 메뉴 막대 빌드는 아이콘 우선입니다. 이전 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를 계속 사용하는 동안 지속적인 네이티브 리뷰 표면을 위해 메뉴 막대 앱을 계속 실행합니다.

도입 가이드

더 쉬운 배포를 위해 전체 README를 처음부터 끝까지 읽는 대신 집중 문서를 사용하세요:

• docs/adoption-guide.md: 로컬 개발자 도입을 위한 최단 경로
• docs/local-api.md: 정확한 localhost 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 스캔 및 선택적 웹훅을 추가합니다.

일일 운영

일반적인 운영 명령:```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 및 서비스 템플릿 디렉토리를 출력합니다.
• 프로젝트별 정책 오버라이드는 프로젝트 루트의 .ore-monitor.yml에 저장할 수 있습니다.
• monitor install은 이제 가능한 경우 사용자 수준의 또는 서비스를 설치하며, 그렇지 않은 경우 로컬 백그라운드 모드로 대체됩니다.

로컬 통합 인터페이스:

• OreWatch는 이제 모니터 데몬이 실행 중일 때 기본적으로 127.0.0.1:48736에서 localhost 전용 API를 노출합니다.
• API는 소유자 전용 권한으로 모니터 설정 디렉토리의 api.token에 저장된 사용자별 Bearer 토큰을 사용합니다.
• Authorization: Bearer <token> 없이 127.0.0.1:48736에 직접 요청하면 올바르게 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, orewatch_list_active_findings, orewatch_list_notifications, 및 를 노출합니다.

선택적 이상 탐지 기반 실시간 업데이트 설정:```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

핵심 동작:
- 실시간 후보군은 먼저 스테이징 영역에 구축되며, 수집 중 활성 데이터베이스를 덮어쓰지 않습니다.
- 대규모 감소, 생태계 회귀, 빈 생태계, 대량 제거는 프로모션을 차단합니다.
- 핵심 소스 중단은 오픈소스 실시간 새로고침의 경우 기본적으로 경고 전용입니다. 생태계 수준의 감소 및 제거는 여전히 잘못된 프로모션을 차단합니다.
- 경고 전용 이상은 상태 및 보고서에 기록되지만 프로모션을 방해하지는 않습니다.
- 거부된 후보군은 이전에 알려진 양호한 데이터셋이 이미 존재하는 경우 이를 활성 상태로 유지합니다.
- 최초 실행 부트스트랩은 최소한 하나의 핵심 소스가 성공하고 후보군이 사용 가능한 생태계 데이터를 생성하는 경우 실시간 피드에서 허용됩니다.

**선택적 알림 웹후크 구성:**```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

Set webhook_format: slack when targeting a Slack incoming webhook. In that mode OreWatch sends a simple text payload.

배포

프로젝트는 이제 두 가지 별개의 배포 표면을 가지고 있습니다:

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를 문서화합니다.
• CI 및 고정 자동화를 위해 python3.14 -m pip install orewatch==<version>를 문서화합니다.

사용 가능한 보조 채널: 이제 Brew 관리 설치를 선호하는 macOS 사용자를 위해 Homebrew 탭이 활성화되었습니다:```bash brew install rapticore/tap/orewatch

Homebrew는 게시된 PyPI 릴리스 위에 있는 편의 계층일 뿐, 기본 릴리스 아티팩트가 아닙니다.

**기여자를 위한 최선의 방법:** 현재 소스 체크아웃 흐름을 유지하세요:```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 배포

Kandji, Jamf Pro, Intune, Munki 또는 다른 macOS 소프트웨어 배포 시스템으로 OreWatch를 배포하는 경우, 권장 모델은 개발자 pipx 경로와 다릅니다.

현재 제품 현실:

• 현재 이 저장소는 Python 패키지를 제공하며, 자체 서명된 공증된 macOS 설치 프로그램 패키지는 아닙니다.
• 관리형 플릿의 경우 권장 아티팩트는 게시된 OreWatch 휠을 기반으로 빌드된 서명된 플랫 .pkg 입니다.
• 위협 데이터 스냅샷은 앱/런타임 패키지와 별도로 배포되어야 합니다.

권장 엔터프라이즈 배포 모델:

1. 기기 설치
   • OreWatch 런타임과 안정적인 orewatch CLI 심을 설치하는 서명된 .pkg를 배포합니다.
   • 관리형 Mac에서 기본 메뉴 막대 앱을 원하는 경우 선택적으로 mac-menubar 추가 기능을 포함합니다.
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
  • **설치 프로그램 패키지(.pkg)**와 함께 사용자 지정 앱을 사용합니다.
  • OreWatch의 경우 런타임이 드래그 앤 드롭 앱이 아니므로 .dmg나 .zip보다 .pkg를 선호합니다.
  • 처음 모니터를 활성화할 때는 Self Service 또는 사용자 대면 온보딩 단계를 사용합니다.
• Jamf Pro
  • .pkg를 패키지로 업로드하고 정책 또는 Self Service를 통해 배포합니다.
  • 의도적인 사용자 컨텍스트 부트스트랩 단계가 없는 한 사용자 활성화는 시스템 패키지 배포와 분리하여 유지합니다.
• Microsoft Intune
  • 서명된 .pkg와 함께 macOS LOB 앱을 사용합니다.
  • Intune은 다른 채널보다 엄격합니다. 실제 .pkg이며 Developer ID Installer 인증서로 서명되어야 하고, 패키지에 페이로드가 포함되어야 합니다.
• Munki
  • .pkg 및 pkg 메타데이터를 게시하고 OreWatch를 다른 관리형 macOS 소프트웨어와 동일하게 취급합니다.
  • Munki는 패키지 저장소와 선택적 Self Service 스타일 도입을 원할 때 적합합니다.
• 기타 시스템
  • 일반 macOS 플랫 패키지를 배포하고 선택적으로 사용자 부트스트랩 단계를 실행할 수 있는 모든 패키지 배포 시스템이 OreWatch를 지원할 수 있습니다.

더 자세한 배포 플레이북은 docs/managed-rollout.md를 참조하세요.

권장 스냅샷 배포

위협 데이터 스냅샷은 Python 패키지 내에 번들로 포함되어서는 안 됩니다. 이들은 다른 주기로 변경되며 이미 서명된 호스팅 아티팩트로 지원됩니다.

오픈소스/커뮤니티 기본값: 이상 징후 게이트 실시간 업데이트 경로를 통해 openssf 및 osv를 직접 사용합니다. 엔터프라이즈 기본값: 버전이 지정된 서명된 스냅샷을 정적 HTTPS 호스팅에 게시하고 클라이언트가 독립적으로 새로 고치도록 합니다.

권장 호스팅 대상:

• GitHub 릴리스 자산
• HTTPS 뒤의 S3 또는 Cloudflare R2
• 변경 불가능한 버전 파일을 제공하는 모든 정적 CDN 기반 버킷

권장 스냅샷 레이아웃:

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

권장 신뢰 모델:

• 개인 서명 키를 오프라인으로 유지합니다.
• 클라이언트 구성 또는 패키지와 함께 공개 확인 키만 제공합니다.
• 다운로드/적용 전에 모든 채널 설명자와 매니페스트를 확인합니다.

권장 전체 모델

프로덕션 릴리스의 경우 가장 깔끔한 설정은 다음과 같습니다.

• 애플리케이션을 PyPI 패키지로 배포합니다.
• 로컬에서 pipx로 설치합니다.
• CI에서 pip로 설치합니다.
• 위협 데이터를 HTTPS를 통해 서명된 스냅샷 채널로 배포합니다.
• 소스 체크아웃을 기본 최종 사용자 설치가 아닌 개발 경로로 취급합니다.

로깅 및 디버깅

기본적으로 스캐너는 경고, 오류 및 최종 요약만 표시합니다. 문제 해결 또는 자세한 진행 상황 추적을 위해 로깅 플래그를 사용하세요.

상세 모드

진행 메시지 및 수집 통계 보기:```bash orewatch /path/to/project --verbose

**출력 내용:**
- 생태계 탐지 결과
- 파일 파싱 진행 상황
- 패키지 추출 횟수
- 데이터베이스 쿼리 세부 정보
- IoC 스캔 진행 상황

**예시:**```
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 쿼리 실행 세부 정보
- 해시 계산
- 패턴 매칭 결과
- 내부 상태 정보

**사용 사례:**
- 패키지가 감지되지 않은 이유 조사
- 에코시스템 자동 감지 문제 디버깅
- 상세한 컨텍스트와 함께 문제 보고
- 스캐너 동작 감사

### 수집기 로깅

위협 인텔리전스 수집기는 또한 자세한 모드 및 디버그 모드를 지원합니다:```bash
cd collectors

# See collection progress
python3 orchestrator.py --verbose

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

참고: 모든 로그는 stderr로 전송되어 JSON 보고서 출력을 위해 stdout을 깨끗하게 유지합니다. 이를 통해 로그 메시지 간섭 없이 스캐너 결과를 다른 도구로 파이프할 수 있습니다.

출력 및 보고서

보고서 구조

보고서는 기본적으로 scan-output/ 디렉토리에 저장됩니다(--output으로 사용자 지정 경로 가능). OreWatch는 기계가 읽을 수 있는 JSON 보고서와 동일한 기본 이름의 스타일이 지정된 HTML 동반 보고서를 작성합니다. JSON 아티팩트에는 위협 데이터 가용성 메타데이터가 포함되어 있으며 패키지 발견을 위해 SARIF 스타일의 physicalLocation 객체를 사용하지만, 완전한 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. **Critical/High 발견:** 영향을 받은 패키지를 즉시 제거하고 영향 조사
2. **IoC 검토:** 악성 코드가 실행되었는지 확인 (로그, 네트워크 활동)
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
    }
}

}

### 사전 커밋 훅

`.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. 타임아웃 증가로 재시도: 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 이전): 모든 실시간 업데이트 프로모션에서 이전 위협 데이터 데이터베이스의 전체 복사본(~300MB)을 보존 없이 보관했습니다. 장기 실행 모니터는 주기당 하나의 스냅샷을 무기한 누적했습니다.

해결책: 1.2.3 이상으로 업그레이드하세요. 이제 백업은 약 1KB SHA-256 매니페스트이며, 보존 기본값은 최근 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. 가양성 보고: 오탐으로 확인된 경우:
   • 자세한 내용을 포함하여 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

**로그 검토:** `debug.log`를 확인하여 상세 실행 추적 정보를 확인하세요:
- 스캔된 파일 경로
- 실행된 SQL 쿼리
- 패턴 매칭 결과
- 오류 스택 추적

---

## 자주 묻는 질문

### 위협 인텔리전스를 얼마나 자주 업데이트해야 하나요?

**권장 사항:**
- **프로덕션/CI 환경:** 매일 자동 업데이트
- **개발 워크스테이션:** 최소 주 1회 업데이트
- **보안 뉴스 후:** 새로운 위협이 발표되면 즉시 업데이트

악성 패키지는 지속적으로 게시됩니다. 매일 업데이트하면 최신 보호를 보장합니다.

### 위협 인텔리전스 데이터를 어떻게 업데이트하나요?

`--latest-data` 플래그를 사용하여 스캐너를 실행하면 강제로 업데이트됩니다:```bash
orewatch /path/to/project --latest-data

CI/CD 자동 업데이트를 위해 --latest-data 플래그로 정기적인 스캔을 예약하세요 (예: 매일). --include-experimental-sources는 재빌드에 Phylum에서 파생된 데이터를 명시적으로 포함하려는 경우에만 추가하세요.

참고: 첫 번째 스캔은 자동으로 데이터를 수집하므로, 수동 업데이트는 기존 데이터베이스를 새로 고치는 경우에만 필요합니다.

위협 데이터는 어디서 오나요?

기본 데이터베이스는 프로젝트의 핵심 위협 소스로부터 구축됩니다:

• openssf
• osv

스캐너는 프로젝트의 실험적 소스 세트도 포함할 수 있습니다:

• --include-experimental-sources와 함께 phylum

socketdev는 비활성화된 플레이스홀더로 저장소에 존재하며 기본 수집 경로에 포함되지 않습니다.

데이터 소스, 수집, 처리에 대한 기술적 세부 사항은 ARCHITECTURE.md를 참조하세요.

이 도구가 내 코드나 의존성을 수정하나요?

아니요. OreWatch는 읽기 전용 작업을 수행합니다. 다음을 수행합니다:

• ✅ 의존성 파일 읽기
• ✅ 위협 데이터베이스 조회
• ✅ 파일 패턴 스캔
• ✅ 보고서 생성

절대 수행하지 않습니다:

• ❌ 패키지 파일 수정
• ❌ 패키지 설치 또는 제거
• ❌ 프로젝트 구성 변경
• ❌ 패키지 코드 실행

내 패키지가 악성으로 플래그되면 어떻게 하나요?

수행할 단계:

1. 결과 확인: 보고서에서 세부 정보와 심각도 확인
2. 증거 검토: 설명과 감지된 동작 검토
3. 버전 확인: 특정 버전이 영향을 받는지 확인
4. 합법적인 경우:
   • 데이터 소스 관리자에게 오탐지 신고
   • 세부 정보와 함께 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:** ❌ 아니요, 위협 인텔리전스 수집은 보안 소스에서 가져오기 위해 인터넷 접속이 필요합니다.

**Airgapped environments:** 다음을 수행할 수 있습니다:
1. 인터넷에 연결된 머신에서 데이터베이스 다운로드
2. SQLite 파일을 `orewatch monitor doctor`가 표시하는 단일 `final_data_dir`로 전송
3. 잠재적으로 오래된 데이터로 오프라인 스캔 실행

### npm audit 또는 pip-audit과 어떻게 비교되나요?

**다른 목적:**

**npm audit / pip-audit:**
- 알려진 CVE 취약점에 초점
- 패키지 버전을 권고 데이터베이스와 비교 확인
- 패키지 레지스트리 팀이 유지 관리

**OreWatch:**
- 악성 패키지(취약한 패키지뿐만 아니라)에 초점
- 타이포스쿼팅, 악성코드, 공급망 공격 탐지
- 크로스 생태계 커버리지
- 활성 위협에 대한 IoC 탐지

**모범 사례:** **둘 다** 사용:```bash
# Check for vulnerabilities
npm audit
pip-audit

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

Does this work with private package registries?

Dependency scanning: ✅ Yes, the scanner reads your dependency files regardless of where packages come from.

Threat intelligence: ⚠️ Limited. Our databases cover public registries (npmjs.com, pypi.org, etc.). Malicious packages on private registries won't be detected unless you add custom threat data.

Custom threat data: You can extend the databases with your own malicious package lists. Contact us for guidance on this advanced use case.

What's the performance impact?

Scan time:

• Small projects (< 50 packages): < 5 seconds
• Medium projects (50-500 packages): 5-30 seconds
• Large projects (500+ packages): 30-120 seconds

Factors:

• IoC scanning adds 10-50% overhead (disable with --no-ioc if not needed)
• First run may be slower as databases load into memory

Optimization tips:```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)를 참고하세요.

**질문 또는 토론:**
- GitHub Discussions: https://github.com/rapticore/ore-mal-pkg-inspector/discussions

---

## 보안 정책

보안은 최우선 과제입니다. OreWatch는 보안 도구이며, 취약점을 매우 중요하게 생각합니다.

### 보안 취약점 보고

**보안 취약점은 공개 GitHub Issue로 제기하지 마십시오.**

대신 다음으로 비공개로 보고해 주십시오:

**이메일:** [email protected]

**포함 내용:**
- 취약점 설명
- 재현 단계
- 잠재적 영향
- 제안된 수정 사항 (해당되는 경우)
- 후속 연락을 위한 연락처 정보

### 응답 일정

- **접수 확인:** 48시간 이내
- **초기 평가:** 7일 이내
- **수정 일정:** 심각도에 따라 다름
  - 긴급(Critical): 7-14일
  - 높음(High): 14-30일
  - 중간/낮음(Medium/Low): 30-60일

### 보안 모범 사례

OreWatch 사용 시:

**권장 사항:**
- ✅ 최소 권한으로 실행 (루트/관리자 권한 불필요)
- ✅ 위협 인텔리전스 정기적 업데이트
- ✅ 스캔 보고서 신속히 검토
- ✅ 지속적 보호를 위해 CI/CD에 통합
- ✅ 도구를 최신 버전으로 유지

**금지 사항:**
- ❌ 스캔 결과를 조사 없이 무시
- ❌ 프로덕션 환경에서 IoC 스캔 비활성화
- ❌ 신뢰할 수 없는 출처의 데이터베이스 파일 공유
- ❌ 불필요하게 상승된 권한으로 실행

### 취약점 공개

우리는 조정된 공개 방식을 따릅니다:
1. 취약점 비공개 보고
2. 수정 사항 개발 및 테스트
3. 보안 권고 게시
4. 수정 사항 제공 후 공개 공개

### 보안 명예의 전당

취약점을 책임감 있게 공개한 보안 연구자를 인정합니다:

*보고서가 접수되면 목록이 유지됩니다*

---

### 커뮤니티 요청

기능에 투표하거나 제안해 주세요:
- **GitHub Discussions:** https://github.com/rapticore/ore-mal-pkg-inspector/discussions
- **기능 요청:** https://github.com/rapticore/ore-mal-pkg-inspector/issues

### 로드맵 기여

다음 기준에 따라 기능 우선순위를 정합니다:
- 보안 영향
- 커뮤니티 수요
- 유지 관리 지속 가능성
- 프로젝트 목표와의 정렬

로드맵에 영향을 미치려면:
1. 상세한 사용 사례와 함께 기능 요청을 여세요
2. 토론에 참여하세요
3. 구현에 기여하세요 (PR 환영!)

---

## 로드맵

OreWatch는 현재 다음 작업에 사용할 수 있습니다:

- npm, PyPI, Maven, RubyGems, Go 및 Cargo에 대한 로컬 CLI 스캔
- 여러 프로젝트에 대한 사용자당 하나의 백그라운드 모니터
- Cursor, Claude Code 및 Codex를 위한 MCP 통합
- VS Code, JetBrains / PyCharm 및 Xcode 헬퍼를 위한 localhost API 통합
- macOS 메뉴 막대 검토 및 팝업 알림

단기 우선순위:

- 자체 VS Code 및 JetBrains / PyCharm 통합 예제 또는 경량 플러그인
- 로컬 팝업을 넘어서는 더 강력한 사용자 대상 알림 워크플로우
- CLI 및 UI에서 더 명확한 프로젝트 정책 관리
- 더 풍부한 모니터 보고 및 채택 문서

중기 우선순위:

- 모니터 및 MCP 표면에서 더 광범위한 프로젝트 스캔 워크플로우
- 조직 수준 롤아웃 지침 개선
- 더 견고한 외부 알림 전달 및 에스컬레이션 채널
- API 전용 통합 가이드 대신 더 깊이 있는 IDE별 UX

현재 알려진 한계:

- Xcode 통합은 현재 알림 가시성과 혼합 언어 리포지토리에 최적입니다. OreWatch는 아직 `Package.resolved`, `Podfile.lock` 또는 `Cartfile`과 같은 네이티브 Apple 매니페스트를 분석하지 않습니다.

장기 방향:

- 네이티브 Apple 생태계 매니페스트 지원
- 더 강력한 자사 편집기 통합
- 현재 macOS 메뉴 막대 경로를 넘어서는 더 넓은 운영 체제 UX 동등성

채택 중심 로드맵은 [docs/roadmap.md](https://github.com/rapticore/ore-mal-pkg-inspector/blob/HEAD/docs/roadmap.md)를 참조하세요.

---

## 라이선스

MIT License

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 protected]

### 전문 지원

다음이 필요한 조직:
- 맞춤형 통합
- SLA 기반 지원
- 비공개 배포 지원
- 맞춤형 위협 인텔리전스 피드

연락처: [email protected]

---

## 감사의 말

### 프로젝트 기원

이 프로젝트는 명확한 프로젝트 초점을 유지하면서 기능을 확장하기 위해 [OreNPMGuard](https://github.com/rapticore/OreNPMGuard) 저장소에서 분리되었습니다.

**OreNPMGuard** (2025년 12월)는 738개 이상의 영향을 받은 패키지와 심층 IoC 분석을 통해 Shai-Hulud npm 공격 탐지를 전문으로 합니다. 개발 과정에서 더 넓은 다중 생태계 보호의 필요성을 인식하여 모든 주요 패키지 생태계에 걸쳐 더 넓은 개발자 커뮤니티를 위한 독립형 도구인 OreWatch를 만들게 되었습니다.

### 관련 프로젝트

- **[OreNPMGuard](https://github.com/rapticore/OreNPMGuard)** - 전문화된 Shai-Hulud npm 스캐너

---

**Rapticore 보안 연구팀 제작**

*소프트웨어 공급망을 한 번의 스캔으로 보호합니다.*