PlamenTSV/plamen

Claude Code 및 OpenAI Codex CLI를 위한 자율형 Web3 보안 감사 도구 (security auditor).

스마트 컨트랙트 (smart contracts) 및 **L1 노드-클라이언트 인프라 (L1 node-client infrastructure)**에 대해 검증된 PoC 익스플로잇 (PoC exploits)이 포함된 감사 보고서를 생성하기 위해 8개 단계에 걸쳐 18~100개의 AI 에이전트를 오케스트레이션 (orchestrates)합니다.

EVM/Solidity, Solana/Anchor, Aptos Move, Sui Move, Soroban/Stellar, 그리고 **L1 Go/Rust 노드 클라이언트 (node clients)**를 지원합니다.

Claude Code CLI 또는 OpenAI Codex CLI, Python 3.11-3.12 + pip, Node.js 18+, Git

백엔드 CLI (Backend CLIs). 최소 하나를 설치하세요. 만약 하나만 설치할 시간이 없다면 Claude Code를 선택하세요. Claude Code는 가장 폭넓은 MCP 지원 (Slither, ChromaDB, Solodit)을 제공합니다. Codex는 OpenAI 모델을 사용하고 싶을 때 강력한 대안이 되지만, 순수 LLM (pure-LLM) 단계에서는 MCP를 사용할 수 없는 WebSearch로 대체됩니다. 두 가지를 병행하여 설치할 수 있으며, 감사 위저드 (audit wizard)에서 실행 시마다 선택할 수 있습니다.

Claude Code:
npm install -g @anthropic-ai/claude-code

OpenAI Codex CLI— Homebrew/시스템 Node 설치 시 sudo EACCES 오류를 방지하기 위해 사용자 로컬 npm 접두사 (user-local npm prefix)를 사용하지 않고 설치하세요.

mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc # 또는 ~/.bashrc
npm install -g @openai/codex
Codex는 아직 모든 MCP 서버를 지원하지 않습니다 — 순수 LLM 단계는 WebSearch 폴백 (fallback)을 사용합니다. docs/mcp-servers.md를 참조하세요.

macOS: 또한 xcode-select --install을 실행하세요 (C++ 의존성 컴파일에 필요).

Windows: 설치하기 전에 개발자 모드 (Developer Mode)를 활성화하세요 (심볼릭 링크 (symlinks)에 필요). 설정 > 시스템 > 개발자용 > 켬. 또는 관리자 권한의 PowerShell에서:
reg add HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock /v AllowDevelopmentWithoutDevLicense /t REG_DWORD /d 1 /f

언어별 도구 (Foundry, Solana CLI 등)는 plamen setup을 통해 자동으로 설치됩니다.

PEP 668 / 외부 관리 Python (externally-managed Python): Homebrew Python 및 Ubuntu 23.04 이상에서는 시스템 pip가 시스템 사이트 패키지 (system site-packages)에 쓰는 것을 거부합니다. plamen install은 이를 감지하고 --break-system-packages를 추가합니다.

pip 호출에 이를 추가하고, stderr에 알림을 출력합니다. 만약 가상 환경 (virtualenv)에서 Plamen의 Python 의존성 (deps)을 격리하고 싶다면, plamen install을 실행하기 전에 가상 환경을 활성화하십시오.

그리고 PIP_BREAK_SYSTEM_PACKAGES=0을 설정하여 이 기능을 거부할 수 있습니다.

어떤 프로젝트 디렉토리에서든 Claude Code 또는 Codex CLI를 열고 SETUP.md의 내용을 붙여넣으십시오. 이 문서는 AI 어시스턴트 (AI-assistant)가 소비하도록 설계된 유일한 Plamen 문서입니다. 단계별 오류 처리 (error handling), 예상 출력 앵커 (expected-output anchors)를 포함하고 있으며, 비 TTY 컨텍스트 (non-TTY context)에서 어시스턴트가 무거운 RAG 빌드나 툴체인 위저드 (toolchain wizard)를 실행하는 것을 방지합니다. 어시스턴트는 클로닝 (cloning), 비 대화형 설치 (plamen install), 그리고 Codex가 있는 경우 plamen install --codex를 처리합니다.

docs/setup.md 또는 docs/getting-started.md를 AI에게 붙여넣지 마십시오. 이 문서들은 인간을 위한 긴 형식의 매뉴얼이며 RAG 빌드 내용이 인라인 (inline)으로 포함되어 있습니다.

붙여넣기 설정을 마친 후, 체인 툴체인 (chain toolchains) (Foundry, Solana CLI, Anchor 등)을 설치하려면 실제 터미널에서 직접 plamen setup을 실행하고, 선택 사항인 취약점 DB (~6GB RAM)를 빌드하려면 plamen rag를 실행하십시오.

Linux / macOS:

git clone --recurse-submodules https://github.com/PlamenTSV/plamen.git ~/.plamen
cd ~/.plamen && python3 plamen.py install
python3 plamen.py install --codex # 선택 사항: Codex CLI 백엔드 추가

Windows (PowerShell):

git clone --recurse-submodules https://github.com/PlamenTSV/plamen.git $HOME\.plamen
cd $HOME\.plamen; python plamen.py install
python plamen.py install --codex # 선택 사항: Codex CLI 백엔드 추가

사용법. 이 저장소는 git clone --recurse-submodules 방식을 사용하며, custom-mcp/slither-mcp/ 및 custom-mcp/farofino-mcp/를 git 서브모듈 (submodules)로 포함합니다. ZIP 다운로드 방식은 이를 조용히 누락시킵니다. 만약 이미 --recurse-submodules 없이 클론했다면, plamen install을 실행하기 전에 ~/.plamen/ 내부에서 git submodule update --init --recursive를 실행하십시오.

:install vs setup
plamen install

plamen install은 비대화형(non-interactive) 방식이며(심볼릭 링크(symlinks) + 설정(config) + Python 의존성(deps) + dangling-hook 자가 치유 포함), Claude Code Bash, Codex shell, CI, headless 서버 등 어떤 환경에서도 안전하게 실행됩니다.

plamen setup은 설치를 수행한 후 대화형 툴체인 위저드(Foundry, Solana CLI 등)로 진입합니다. 이 명령은 실제 터미널에서 실행하십시오. 비-TTY(non-TTY) 환경에서 plamen setup을 실행하면, 선택기(picker)에서 충돌하는 대신 설치 후 깔끔하게 종료됩니다.

RAG 데이터베이스를 구축하기 전에, SOLODIT_API_KEY를 다음 위치에 추가하십시오:

~/.claude/settings.json → "env" 섹션
(또는 Codex의 경우 ~/.codex/config.toml → [env] 섹션)

키는 solodit.cyfrin.io에서 무료로 받을 수 있습니다. 이곳은 plamen rag와 감사 에이전트(audit agent) 서브프로세스(subprocesses) 모두에게 키가 안정적으로 노출되는 유일한 장소입니다. 터미널의 export 명령만으로는 충분하지 않습니다. Claude Code와 Codex CLI는 .bashrc / .zshrc를 소싱(source)하지 않는 비대화형 서브쉘(non-interactive subshells)을 생성하기 때문입니다. Python 의존성(dependencies)은 첫 실행 시 자동으로 설치됩니다. macOS/Linux에서는 python3를 사용하고, Windows에서는 python을 사용하십시오.

설치 후, 어디서든 plamen을 실행할 수 있도록 PATH에 추가하십시오:

Linux (bash):
echo 'export PATH="$HOME/.plamen:$PATH"' >> ~/.bashrc && source ~/.bashrc

macOS (zsh):
echo 'export PATH="$HOME/.plamen:$PATH"' >> ~/.zshrc && source ~/.zshrc

Windows (PowerShell, 1회 실행):
[System.Environment]::SetEnvironmentVariable("Path", "$env:USERPROFILE\.plamen;" + [System.Environment]::GetEnvironmentVariable("Path", "User"), "User")

이제 어디서든 plamen을 사용할 수 있습니다:

plamen # 대화형 감사 위저드 (interactive audit wizard)
plamen doctor # 설치 확인 (감사 실행 및 API 호출 없음)
plamen setup # 툴체인 위저드 + 선택적 RAG 구축
...

중요: PATH를 설정한 후에는 항상 plamen을 사용하십시오(python3 plamen.py가 아님). python3 plamen.py 방식은 ~/.plamen/ 내부에서만 작동합니다.

설치 프로그램 (plamen install):

• ~/.plamen에서 ~/.claude/로 심볼릭 링크(symlinks)를 생성하여 Claude Code가 Plamen의 에이전트(agents), 규칙(rules), 프롬프트(prompts) 및 명령(commands)을 발견할 수 있도록 합니다.
• Plamen의 권한(permissions)을 기존의 ~/.claude/settings.json에 병합(merges)합니다.

(추가 전용 — 기존 항목을 삭제하지 않음) - ~/.claude/mcp.json에 MCP 서버 정의를 병합(merges)합니다.

(기존 서버를 덮어쓰지 않음) - <!-- PLAMEN:START/END --> 마커 사이에 Plamen 지침을 ~/.claude/CLAUDE.md에 주입(injects)합니다 (사용자의 콘텐츠를 보존함).

Python 의존성(dependencies)을 설치합니다 (RAG 데이터베이스는 plamen rag를 통해 별도로 구축됩니다).

Codex CLI 지원을 위해 plamen install --codex도 실행하십시오. 이는 ~/.codex/plamen/ (~/.plamen/에서 심볼릭 링크(symlinked)됨)를 다음과 같이 설정합니다:

• codex-adapter/AGENTS.md에서 생성된 ~/.codex/AGENTS.md 내 Codex 오케스트레이터(orchestrator) 설정 (CLAUDE.md와 동일)
• codex-adapter/config.toml에서 생성된 ~/.codex/config.toml 내 MCP/도구(tool) 설정 (settings.json + mcp.json과 동일)
• codex-adapter/commands/에서 생성된 ~/.codex/commands/ 내 Codex 전용 슬래시 명령어(slash commands)

기존의 Claude Code 및 Codex CLI 설정은 보존됩니다.

심볼릭 링크(symlinks) 작동 방식

Plamen 저장소는 ~/.plamen에 유지됩니다. 설치 프로그램은 ~/.plamen/을 가리키는 심볼릭 링크(symlinks, 바로가기)를 생성합니다:

Claude Code (plamen install): ~/.claude/ 내로 심볼릭 링크 생성 — 에이전트(agents), 규칙(rules), 기술(skills), 프롬프트(prompts), 명령어(commands)

Codex CLI (plamen install --codex): ~/.codex/plamen/ → ~/.plamen/ 심볼릭 링크 (방법론 공유), 그리고 codex-adapter/{AGENTS.md,config.toml,agents/,skills/,commands/}를 ~/.codex/로 복사

AI 런타임(runtime)이 ~/.claude/agents/depth-edge-case.md (또는 ~/.codex/plamen/agents/depth-edge-case.md)를 읽을 때, 운영체제(OS)는 투명하게 ~/.plamen/agents/depth-edge-case.md를 읽습니다. 이는 다음을 의미합니다:

• ~/.plamen에서 git pull을 수행하면 심볼릭 링크된 파일들(에이전트, 규칙, 기술, 프롬프트)이 두 백엔드(backends) 모두에 대해 자동으로 업데이트됩니다.
• 여전히 다음 작업이 필요합니다 — pull 이후 plamen install (및 plamen install --codex)을 실행해야 합니다. CLAUDE.md / AGENTS.md, settings.json / config.toml, 그리고 mcp.json은 심볼릭 링크가 아니라 주입/병합된 복사본이기 때문입니다. 재설치하지 않으면 오케스트레이터가 오래된 규칙을 따르게 됩니다. docs/updating.md를 참조하십시오.
• ~/.claude/에 있는 사용자 본인의 파일들

또는 ~/.codex/

(커스텀 에이전트 (custom agents), 명령어 (commands))는 건드리지 않습니다 - ~/.plamen을 삭제하면 두 백엔드(backends) 모두의 심볼릭 링크 (symlinks)가 깨지게 됩니다 — Plamen이 설치되어 있는 동안에는 이를 삭제하지 마십시오.

플랫폼 (Platform)	링크 생성 방식	요구 사항
Linux / macOS	표준 심볼릭 링크 (Standard symlinks, os.symlink)	없음
Windows (디렉토리)	정션 (Junctions, mklink /J)	없음
Windows (파일)	심볼릭 링크 (Symlinks, os.symlink)	개발자 모드 (Developer Mode) 활성화

~/.claude에 직접 설치된 v1.0.x 버전에서 마이그레이션 (Migrating) 하는 방법: 먼저 Claude Code (및 실행 중인 경우 Codex CLI)를 종료한 다음, 다음을 실행하십시오:

cd ~/.plamen 2>/dev/null || cd ~/.claude # 존재하는 디렉토리로 이동
python3 plamen.py migrate # 또는 Windows에서는 python plamen.py migrate``

plamen migrate는 ~/.claude/settings.json에서 끊어진 Plamen 훅 (hook) 참조를 제거합니다 (이를 제거하지 않으면 PreToolUse Bash가 차단되어 Claude Code에서 셸 명령어 (shell commands) 사용이 불가능해집니다). 그 후 리포지토리 (repo)를 ~/.plamen으로 이동시키고, 비대화형 설치 (non-interactive install)를 실행하며, CLAUDE.md 마커 블록 (marker block)을 검증합니다. 수동 경로를 선호하는 경우:

Linux/macOS:
mv ~/.claude ~/.plamen && cd ~/.plamen && python3 plamen.py install

Windows (PowerShell):
Rename-Item $HOME\.claude $HOME\.plamen; cd $HOME\.plamen; python plamen.py install

두 경로 모두 리포지토리를 ~/.plamen으로 이동시키고, 심볼릭 링크 (symlinks)와 병합된 설정 (merged config)을 사용하여 ~/.claude를 재생성합니다. 이동과 설치 사이의 단계 동안에는 Claude Code가 작동하지 않으므로 — 함께 실행하십시오 (또는 단순히 plamen migrate를 사용하십시오). Codex 지원을 위해서는 plamen install --codex를 이어서 실행하십시오.

클릭하여 확장 (~5-10분)

옵션 B가 이를 자동으로 처리합니다. 이 명령어들은 참조용으로만 제공됩니다.

cd ~/.plamen
# 1. Python 의존성 (Python deps) (~2GB 다운로드 — 임베딩 (embeddings)을 위한 PyTorch)
pip install -r requirements.txt
...

Windows + Solana: 빌드하기 전에 개발자 모드 (Developer Mode)를 활성화하고 (설정 > 시스템 > 개발자용), OpenSSL을 설치하십시오 (winget install ShiningLight.OpenSSL.Dev). docs/dependencies.md를 참조하십시오.

언어별 모든 필수 요구 사항이 포함된 전체 가이드는 docs/setup.md를 참조하십시오.

cd ~/.plamen && git pull && plamen install
plamen install --codex # Codex 백엔드(backend)를 사용하는 경우

이것으로 끝입니다. plamen install은

멱등성(idempotent)을 가집니다 — 심볼릭 링크(symlinks)를 다시 연결하고, 업데이트된 CLAUDE.md를 다시 주입(re-inject)하며, 새로운 settings.json / mcp.json 항목을 병합(merge)합니다. --codex를 추가하면 AGENTS.md 및 config.toml에 대해서도 동일한 작업을 수행합니다. RAG 데이터베이스를 삭제하거나, 툴체인(toolchains)을 재설치하거나, API 키를 덮어쓰지 않습니다.

왜 (재설치가 필요한가)?
대부분의 파일은 심볼릭 링크(symlinks)를 통해 자동으로 업데이트되지만, 주입/병합된 파일(pull 이후의 plamen install을 통한 CLAUDE.md / AGENTS.md, settings.json / config.toml, mcp.json)은 심볼릭 링크가 아닌 복사본입니다. 재설치(re-install)를 하지 않으면, 다른 모든 것이 업데이트되는 동안 오케스트레이터(orchestrator)는 오래된 규칙을 따르게 됩니다. plamen은 버전 불일치가 감지되면 경고를 보냅니다.

무엇이 자동으로 업데이트되고 무엇이 그렇지 않은지에 대한 자세한 내용은 docs/updating.md를 참조하십시오.

plamen # 대화형 위저드(interactive wizard)가 포함된 터미널 래퍼(terminal wrapper)

또는 Claude Code 내부에서: /plamen

· Codex CLI 내부에서: $plamen core /path/to/project

모드 (Mode)	계획 (Plan)	에이전트 (Agents)	예상 비용 (Indicative Cost)	주요 특징 (Key Features)
Light	Pro	~18-22	~$1–5 / ~10-25분	빠른 스캔, 모두 Sonnet 사용, 퍼징(fuzzing) 없음
Core	Max	~30-50	~$10–30 / ~30-90분	전체 깊이 탐색, Medium+ 수준의 PoC 검증
Thorough	Max	~40-100	~$30–100+ / ~1-4시간	반복적 깊이 탐색, 불변량 퍼징(invariant fuzzing), Medusa, skeptic-judge

비용/실행 시간은 Claude 구독(subscription)을 사용하는 약 5,000행 규모의 코드베이스에 대한 대략적인 지표입니다. 더 큰 코드베이스는 대략 선형적으로 규모가 확장됩니다. 위저드(wizard)는 각 감사(audit) 전에 plamen --estimate를 실행하여 라인 수, 범위 및 대상 계획을 기반으로 프로젝트별 수치를 보여줍니다 — 예산 책정에 이를 활용하십시오. API 키 사용자(종량제, pay-as-you-go)는 구독 사용자보다 비용이 약 2~3배 더 높게 나타납니다.

전체 비교는 docs/audit-modes.md를 참조하십시오.

Plamen은 또한 L1 노드 클라이언트 및 블록체인 인프라 — Go 및 Rust로 작성된 합의 엔진(consensus engines), P2P 네트워킹, 멤풀(mempool) 로직, RPC 표면(surfaces), 그리고 검증인 라이프사이클(validator lifecycle) 코드를 감사합니다.

plamen l1 core /path/to/node-client

또는 Claude Code 내부에서: /plamen l1 core

· Codex CLI 내부에서: $plamen l1 core /path/to/node-client

L1 모드에서 추가되는 기능:

22개 이상의 주입 가능한 기술 (injectable skills): 합의 안전성 (consensus safety), 포크 선택 (fork choice), P2P DoS/eclipse 공격, 멤풀 비대칭 DoS (mempool asymmetric DoS), BLS 집계 (BLS aggregation), 라이트 클라이언트 증명 (light client proofs), 상태 동기화/프루닝 (state sync/pruning), 실행 클라이언트 강화 (execution client hardening), 검증인 라이프사이클 (validator lifecycle) 등을 포함합니다.

2개의 새로운 뎁스 에이전트 (depth agents):
depth-consensus-invariant 및 depth-network-surface

Phase 0.5 "Bake": 뎁스 에이전트가 실행되기 전, scip-go / rust-analyzer SCIP를 사용하여 리포지토리를 배치 인덱싱 (batch-indexes) 합니다.

L1 전용 심각도 매트릭스 (severity matrix): Immunefi v2.3 분류 체계와 정렬되어 있습니다.

Go 및 Rust 언어 지원: 동시성 안전성 (concurrency safety) 및 unsafe-block 감사 (auditing)를 지원합니다.

전체 L1 아키텍처는 docs/l1-mode/design.md를 참조하세요.

터미널 래퍼 (Terminal wrapper) (권장 — 설정 및 비용 추정 포함):