🦡 codebadger

Контейнеризированный сервер протокола контекста модели (MCP), обеспечивающий статический анализ кода с использованием технологии графа свойств кода (CPG) от Joern с поддержкой Java, C/C++, JavaScript, Python, Go, Kotlin, C#, Ghidra, Jimple, PHP, Ruby и Swift.

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

Перед началом убедитесь, что у вас установлены:

• 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 Server: движок статического анализа кода (выполняет генерацию 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)

• Опционально очистить директорию playground (CPG и кэшированные кодовые базы)

Интеграции

Интеграция с GitHub Copilot

Отредактируйте файл конфигурации MCP для VS Code (GitHub Copilot):

Путь:

~/.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"
    }
  }
}

Доступные инструменты

Основные

• generate_cpg: Генерация графа свойств кода (CPG) для кодовой базы (локальный путь или URL GitHub).

• get_cpg_status: Проверка существования CPG и получение метаданных статуса.

• run_cpgql_query: Выполнение необработанного запроса CPGQL к CPG и возврат структурированных результатов.

• 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: Эвристическое обнаружение вероятных вызовов с раскрытыми макросами.

Анализ загрязнения (Taint) и уязвимостей

• 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: Обнаружение потенциальных проблем двойного освобождения памяти.

• find_null_pointer_deref: Поиск вероятных разыменований нулевого указателя.

• find_integer_overflow: Обнаружение шаблонов переполнения целых чисел.

• find_format_string_vulns: Обнаружение уязвимостей форматной строки (CWE-134), когда нелитеральные аргументы формата передаются функциям семейства printf.

• find_heap_overflow: Обнаружение уязвимостей переполнения кучи (CWE-122), когда запись в буферы кучи может превысить их выделенный размер.

• find_stack_overflow: Обнаружение уязвимостей переполнения стекового буфера (CWE-121), когда запись в локальные массивы фиксированного размера (например, char buf[64]) может превысить их объявленное измерение.

• find_toctou: Обнаружение состояний гонки Time-of-Check-Time-of-Use (CWE-367), когда файл проверяется с помощью access()/stat(), а затем открывается или используется на отдельном шаге.

• find_uninitialized_reads: Обнаружение чтения неинициализированных переменных (CWE-457), когда локальные переменные используются до присвоения им значения.

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

Спасибо за ваш вклад! Вот краткое руководство, как начать запускать тесты и вносить свой вклад в код.

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

• Python 3.10+ (3.13 используется в CI)

• 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. Включите четкий список изменений (changelog) в описание вашего 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.yaml из config.example.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) с нулевыми накладными расходами.