oss-analyzer

오픈소스(또는 소스가 있는 저장소)를 단위별로 빠짐없이 전수 분석하는 MCP 툴킷. REA(배포물 리버스 엔지니어링 툴킷)의 근거·미확인 설계를 소스 분석에 적용했다.

• 모든 결론에 근거(파일:줄, 고정 커밋, 스니펫 해시) — 기록할 때 실제 코드와 대조해 검증
• 확정 못 한 것은 미확인 목록으로 — 해결하려면 요구 등급 이상의 근거가 필요
• 숨은 빈틈 0 — 기준 목록은 git. 모든 파일 분류 + 모든 심볼 검토 + 엔진이 못 본 곳은 자동 미확인
• 검증 등급 L0(구조 지도·직접 읽기) / L1(LSP) / L2(데이터 흐름, Joern) / L3(실행 검증, 예정)
• 실제 URL 목록: 동적으로 조립되는 경로까지 정적으로 펼침 (헬퍼 함수 호출부의 경로 표, 설정 기본값, 마운트·클래스 접두)

구성

Claude Code ──MCP──▶ oss-analyzer (Python, Apache-2.0)
서브에이전트 ──CLI──┘  ├ 원장 SQLite  ~/.oss-analyzer/projects/<id>/ledger.db (병렬 프로세스 안전)
                      ├ 규칙팩       src/oss_analyzer/rulepacks/*.yml (진입점)
                      └ 외부 엔진 (서브프로세스, 필요할 때만 기동)
                         git · codebase-memory-mcp(구조 지도) · ast-grep(진입점)
                         multilspy→언어 서버(LSP) · Joern(데이터 흐름)

설치

py -3.11 -m venv .venv
.venv/Scripts/python -m pip install -e ".[dev]"
.venv/Scripts/oss-analyzer doctor

외부 엔진은 doctor 의 install_hints 를 따른다.

• codebase-memory-mcp: 릴리스 zip 을 checksums.txt 로 검증 후 ~/.oss-analyzer/bin/
• ast-grep: npm i -g @ast-grep/cli
• Rust: rustup component add rust-analyzer / Java: JDK 17+ / Python: 자동
• TS·JS: Node.js + npm i -g typescript-language-server + 툴킷 전용 TypeScript 5 npm install --prefix ~/.oss-analyzer/node typescript@5 (TypeScript 7 은 tsserver.js 가 없어 호환 안 됨. 분석 대상에 npm install 은 하지 않는다)
• Joern: 릴리스 joern-cli-<os>.zip(sha512 검증) → ~/.oss-analyzer/engines/joern-cli, JDK 21+

Claude Code 등록:

claude mcp add -s user oss-analyzer -- <설치 경로>/.venv/Scripts/oss-analyzer-mcp.exe

스킬: skills/oss-analyze/ 를 ~/.claude/skills/oss-analyze/ 로 복사 (CLI 사용법은 CLI.md).

사용

Claude Code 에서 "이 저장소 전수 분석해줘" → oss-analyze 스킬이 절차를 따른다. 큰 저장소는 서브에이전트 여러 개가 각자 agent id 로 next 를 호출해 병렬 분석한다 (임대로 충돌 방지).

oss-analyzer open <경로|URL> [--ref <커밋>]
oss-analyzer inventory <project_id>
oss-analyzer features <project_id>          # 실제 URL 카탈로그
oss-analyzer dataflow <project_id> --build-only   # L2 용 CPG 미리 생성 (처음 한 번 오래 걸림)
oss-analyzer coverage <project_id>
oss-analyzer export <project_id>

실측 — Meilisearch v1.56.0 (2026-10-29)

Meilisearch (Rust, actix-web, 파일 1,750개, Rust 721개)로 검증했다.

재현:

git clone --depth 1 --branch v1.56.0 https://github.com/meilisearch/meilisearch.git
oss-analyzer open ./meilisearch && oss-analyzer inventory meilisearch-47567abc
curl -LO https://github.com/meilisearch/meilisearch/releases/download/v1.56.0/meilisearch-openapi.json
python eval/routes_vs_openapi.py meilisearch-47567abc meilisearch-openapi.json

검증하면서 드러나 고친 것: Windows 긴 경로 clone 실패, 대상 저장소의 rust-toolchain.toml 때문에 rust-analyzer 가 즉시 죽고 클라이언트가 무한 대기하던 문제(툴체인 고정 + 기동 감시), 죽은 프로세스의 잠금 회수(PID), dev-dependency 로 인한 프레임워크 오탐, 테스트 스냅샷 860개 미분류, 코드 식별자(token: &str)까지 가리던 비밀값 마스킹.

안전 원칙

• 분석 대상 코드를 실행하지 않는다. rust-analyzer 의 빌드 스크립트·proc-macro·cargo check 를 꺼서 띄운다 (multilspy 기본값은 켜져 있어 남의 코드가 컴파일·실행됨). 그래서 proc-macro 생성 항목은 미확인으로 남긴다.
• 비밀 파일은 secret 범주 — 읽지 않고, 근거로 쓸 수 없고, 구조 지도 엔진에도 넘기지 않는다(.cbmignore). 일반 파일 속 비밀값(설정의 password·key·token, URL 자격증명, 토큰 패턴)은 코드 출력 시 **** 로 가린다.
• 분석은 전용 clone 에서 고정 커밋으로만 한다 — 원본 작업 트리(커밋 안 된 변경 포함)는 반영되지 않는다.

알려진 한계

라이선스

Apache-2.0. 의존성·외부 엔진은 THIRD_PARTY.md.