🦡 codebadger

Java, C/C++, JavaScript, Python, Go, Kotlin, C#, Ghidra, Jimple, PHP, Ruby 및 Swift를 지원하는 Joern의 코드 속성 그래프(CPG) 기술을 사용하여 정적 코드 분석을 제공하는 컨테이너화된 MCP(Model Context Protocol) 서버입니다.

사전 요구 사항

시작하기 전에 다음 사항이 준비되어 있는지 확인하세요:

• Docker 및 Docker Compose 설치

• Python 3.10+ (Python 3.13 권장)

• pip (Python 패키지 관리자)

설정을 확인하려면:

docker --version
docker-compose --version
python --version

빠른 시작

1. Python 의존성 설치

# Create a virtual environment (optional but recommended)
python -m venv venv

# Install dependencies
pip install -r requirements.txt

2. Docker 서비스 시작 (Joern)

docker compose up -d

이 명령은 다음을 시작합니다:

• Joern 서버: 정적 코드 분석 엔진 (CPG 생성 및 쿼리 실행)

서비스가 실행 중인지 확인:

docker compose ps

3. MCP 서버 시작

# Start the server
python main.py &

MCP 서버는 http://localhost:4242에서 사용할 수 있습니다.

4. 모든 서비스 중지

# Stop MCP server (Ctrl+C in terminal)

# Stop Docker services
docker-compose down
# Optional: Clean up everything
bash cleanup.sh

정리 스크립트

제공된 정리 스크립트를 사용하여 환경을 초기화하세요:

bash cleanup.sh

이 스크립트는 다음을 수행합니다:

• Docker 컨테이너 중지 및 제거

• 고아 Joern/MCP 프로세스 종료

• Python 캐시 정리 (__pycache__, .pytest_cache)

• 선택적으로 플레이그라운드 디렉토리(CPG 및 캐시된 코드베이스) 정리

통합

GitHub Copilot 통합

VS Code(GitHub Copilot)용 MCP 구성 파일을 편집하세요:

경로:

~/.config/Code/User/mcp.json

구성 예시:

{
  "inputs": [],
  "servers": {
    "codebadger": {
      "url": "http://localhost:4242/mcp",
      "type": "http"
    }
  }
}

Claude Code 통합

codebadger를 Claude Desktop에 통합하려면 다음을 편집하세요:

경로:

Claude → Settings → Developer → Edit Config → claude_desktop_config.json

다음 내용을 추가하세요:

{
  "mcpServers": {
    "codebadger": {
      "url": "http://localhost:4242/mcp",
      "type": "http"
    }
  }
}

사용 가능한 도구

핵심(Core)

• generate_cpg: 코드베이스(로컬 경로 또는 GitHub URL)에 대한 코드 속성 그래프(CPG)를 생성합니다.

• get_cpg_status: CPG 존재 여부를 확인하고 상태 메타데이터를 가져옵니다.

• run_cpgql_query: CPG에 대해 원시 CPGQL 쿼리를 실행하고 구조화된 결과를 반환합니다.

• get_cpgql_syntax_help: CPGQL 구문 도우미, 팁 및 일반적인 오류 수정 방법을 표시합니다.

코드 탐색

• list_methods: 정규식/파일 필터를 사용하여 메서드/함수 목록을 나열합니다.

• list_files: 소스 파일을 페이지가 나뉜 트리 뷰로 표시합니다.

• get_method_source: 지정된 메서드의 소스 코드를 가져옵니다.

• list_calls: 함수 간의 호출 지점(호출자 → 피호출자)을 나열합니다.

• get_call_graph: 사람이 읽을 수 있는 호출 그래프(수신 또는 발신)를 생성합니다.

• list_parameters: 메서드의 매개변수 이름, 유형 및 순서를 가져옵니다.

• get_codebase_summary: 상위 수준 메트릭(파일, 메서드, 호출, 언어)을 가져옵니다.

• get_code_snippet: 시작/종료 줄 번호로 파일 스니펫을 반환합니다.

의미론적 분석

• get_cfg: 메서드에 대한 제어 흐름 그래프(노드 및 엣지)를 생성합니다.

• get_type_definition: 구조체/클래스 유형 및 해당 멤버를 검사합니다.

• get_macro_expansion: 매크로가 확장된 것으로 보이는 호출을 휴리스틱하게 탐지합니다.

오염 및 취약점 분석

• find_taint_sources: 외부 입력 지점(소스)을 찾습니다.

• find_taint_sinks: 오염된 데이터가 흐를 수 있는 위험한 싱크를 찾습니다.

• find_taint_flows: 소스에서 싱크로의 데이터 흐름을 탐지합니다(오염 분석).

• get_program_slice: 호출에 대한 역방향/순방향 프로그램 슬라이스를 생성합니다.

• get_variable_flow: 특정 위치에서 변수에 대한 데이터 종속성을 추적합니다.

• find_bounds_checks: 버퍼 액세스 근처에서 경계 검사를 검색합니다.

• find_use_after_free: Use-After-Free 패턴을 휴리스틱하게 탐지합니다.

• find_double_free: 잠재적인 Double-Free 문제를 탐지합니다.

• find_null_pointer_deref: Null 포인터 역참조 가능성을 찾습니다.

• find_integer_overflow: 정수 오버플로 패턴을 탐지합니다.

• find_format_string_vulns: printf 계열 함수에 리터럴이 아닌 형식 인수가 전달되는 형식 문자열 취약점(CWE-134)을 탐지합니다.

• find_heap_overflow: 힙 버퍼에 대한 쓰기가 할당된 크기를 초과할 수 있는 힙 오버플로 취약점(CWE-122)을 탐지합니다.

• find_stack_overflow: 고정 크기 로컬 배열(예: char buf[64])에 대한 쓰기가 선언된 크기를 초과할 수 있는 스택 버퍼 오버플로 취약점(CWE-121)을 탐지합니다.

• find_toctou: access()/stat()으로 파일을 확인한 후 별도의 단계에서 열거나 조작하는 TOCTOU(Time-of-Check-Time-of-Use) 경쟁 상태(CWE-367)를 탐지합니다.

• find_uninitialized_reads: 로컬 변수가 값 할당 전에 사용되는 초기화되지 않은 변수 읽기(CWE-457)를 탐지합니다.

기여 및 테스트

기여해 주셔서 감사합니다! 테스트 실행 및 코드 기여를 시작하기 위한 간단한 가이드입니다.

사전 요구 사항

• Python 3.10+ (CI에서는 3.13 사용)

• Docker 및 Docker Compose (통합 테스트용)

로컬 개발 설정

1. 가상 환경을 만들고 의존성을 설치합니다.

python -m venv venv
pip install -r requirements.txt

2. Docker 서비스 시작 (통합 테스트용)

docker-compose up -d

3. 단위 테스트 실행

pytest tests/ -q

4. 통합 테스트 실행 (Docker Compose 실행 필요)

# Start MCP server in background
python main.py &

# Run integration tests
pytest tests/integration -q

# Stop MCP server
pkill -f "python main.py"

5. 모든 테스트 실행

pytest tests/ -q

6. 테스트 후 정리

bash cleanup.sh
docker-compose down

코드 기여

기여 시 다음 지침을 따라주세요:

1. 저장소 규칙을 따릅니다.

2. 동작 변경에 대한 테스트를 작성합니다.

3. PR을 제출하기 전에 모든 테스트를 통과하는지 확인합니다.

4. PR 설명에 명확한 변경 로그를 포함합니다.

5. 필요한 경우 문서를 업데이트합니다.

구성

MCP 서버는 환경 변수 또는 config.yaml을 통해 구성할 수 있습니다.

환경 변수

주요 설정 (선택 사항 - 기본값 표시):

# Server
MCP_HOST=0.0.0.0
MCP_PORT=4242

# Joern
JOERN_BINARY_PATH=joern
JOERN_JAVA_OPTS="-Xmx4G -Xms2G -XX:+UseG1GC -Dfile.encoding=UTF-8"

# CPG Generation
CPG_GENERATION_TIMEOUT=600
MAX_REPO_SIZE_MB=500

# Query
QUERY_TIMEOUT=30
QUERY_CACHE_ENABLED=true
QUERY_CACHE_TTL=300

# Telemetry (OpenTelemetry)
OTEL_ENABLED=false
OTEL_SERVICE_NAME=codebadger
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

구성 파일

config.example.yaml에서 config.yaml을 생성합니다:

cp config.example.yaml config.yaml

그런 다음 필요에 따라 사용자 정의합니다.

텔레메트리 (OpenTelemetry)

CodeBadger는 분산 추적을 위한 OpenTelemetry 지원이 내장되어 있습니다. 활성화되면 모든 MCP 도구 호출이 자동으로 추적되며, CPG 생성, Joern 서버 관리 및 쿼리 실행에 대한 사용자 지정 스팬도 포함됩니다.

빠른 시작

1. 텔레메트리 의존성 설치 (requirements.txt에 포함됨):

pip install opentelemetry-sdk opentelemetry-exporter-otlp

2. 환경 변수를 통해 활성화:

export OTEL_ENABLED=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
python main.py

또는 config.yaml을 통해 활성화:

telemetry:
  enabled: true
  service_name: codebadger
  otlp_endpoint: http://localhost:4317
  otlp_protocol: grpc  # or "http/protobuf"

Jaeger를 사용한 로컬 개발

# Start Jaeger (provides UI at http://localhost:16686)
docker run -d --name jaeger \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# Start CodeBadger with telemetry
OTEL_ENABLED=true python main.py

추적 대상

구성 참조

텔레메트리가 비활성화된 경우(기본값), 모든 추적은 오버헤드 없이 no-op으로 처리됩니다.