🦡 codebadger

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

Новости

codebadger и сопутствующая статья — Bridging Code Property Graphs and Language Models for Program Analysis — были приняты на Семинар по управлению уязвимостями программного обеспечения @ ICSE 2026. 🎉

Related MCP server: Joern MCP Server

Цитирование

@article{lekssays2026bridging,
  title={Bridging Code Property Graphs and Language Models for Program Analysis},
  author={Lekssays, Ahmed},
  journal={arXiv preprint arXiv:2603.24837},
  year={2026}
}

Нашли уязвимость с помощью codebadger?

Если codebadger помог вам обнаружить реальную уязвимость, мы будем рады узнать об этом. Откройте pull request, добавив её в TROPHIES.md — укажите идентификатор CVE, проект, краткое описание и дату.

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

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

• 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: Обнаружение потоков данных от источников к приемникам (анализ taint).

• 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: Поиск вероятных разыменований нулевого указателя.

• 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), когда локальные переменные используются до присвоения им значения.

Пользовательские инструменты

Вы можете добавлять свои собственные детекторы, не изменяя основную кодовую базу:

1. Напишите шаблон запроса Scala в src/tools/queries/your_query.scala.

2. Зарегистрируйте функцию инструмента Python в src/tools/custom_tools.py.

3. Перезапустите сервер — инструмент автоматически появится в каждом клиенте MCP.

См. CUSTOM_TOOLS_GUIDE.md для получения полного пошагового руководства, справочника CPGQL и информации о проектных решениях.

Вклад и тесты

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

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

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