squid-protocol1/gitgalaxyЭвристический движок графа знаний без AST для глубокого анализа репозитория и сканирования безопасности с нулевым доверием. Интегрируется как компонент GitLab CI/CD, блокирует враждебный код и экспортирует телеметрию SARIF в GitLab Security Dashboard.
# GitGalaxy
**Структурный анализ в масштабе репозитория без компиляции.**
[Документация](https://squid-protocol.github.io/gitgalaxy/) ·
[Визуализатор](https://gitgalaxy.io/) ·
[Language Crucible](https://github.com/squid-protocol/language-crucible) ·
[Keyword Rosetta](https://github.com/squid-protocol/keyword-rosetta) ·
[Необработанный вывод](https://github.com/squid-protocol/gitgalaxy-raw-output)
**1 сканирование · 97 структурных сигналов · 50+ языков · без компиляции · 17
категорий риска · 6 выходных форматов**
## Кратко
GitGalaxy строит **не зависящий от языка структурный граф всего
репозитория** непосредственно из исходного текста — без сборки, без
инструментальных цепочек для отдельных языков.
Он предназначен для репозиториев, которые являются мультиязычными, частично
неработоспособными, устаревшими, перегруженными вендорным кодом или иным
образом сложными для анализа через подход «сначала сборка»:
``` text
Go + C++ + Python + Java + Bash + YAML
+ generated code + vendored code + legacy code
+ half-migrated modules + broken dependencies
```
Вместо отдельного парсера для каждого языка GitGalaxy извлекает общий
словарь **структурных сигнатур** — функции, классы, аргументы,
поток управления, мутации состояния, ввод-вывод, API, зависимости — и нормализует их
в одну детерминированную модель репозитория, которая питает анализ архитектуры,
приоритизацию рисков, генерацию SBOM, рефакторинг и анализ
ответственности, контекст кодовой базы для ИИ и шлюзы CI/CD.
> **Центральный тезис:** полный разбор языка не всегда необходим для
> извлечения крайне полезной структурной информации в масштабе репозитория.
Как этот тезис проверяется — против Tree-sitter и Ctags, против
специально подготовленного контрольного корпуса, а затем против истории Git — кратко изложено в
[Accuracy, measured](#accuracy-measured) ниже и подробно описано в
[программе валидации](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/validation.md).
------------------------------------------------------------------------
## Что даёт сканирование
Одна команда:
``` bash
pip install gitgalaxy
galaxyscope path/to/repo
```
Шесть согласованных представлений одного детерминированного сканирования:
| Выход | Назначение |
|---|---|
| **LLM architecture brief** | Компактный машинно-/агентно-ориентированный контекст (ниже) |
| **SARIF** | Интеграция с CI/панелями безопасности |
| **CycloneDX SBOM** | Инвентаризация зависимостей/соответствие требованиям |
| **SQLite** | Запрашиваемый граф знаний репозитория |
| **JSON audit data** | Форензика/автоматизированные сценарии |
| **3D visualization data** | Интерактивная топология репозитория |
### Архитектурный бриф
Флагманский отчёт — это единый Markdown-бриф, созданный для того, чтобы дать инженеру — или
ИИ-агенту — рабочую ментальную модель репозитория, которого он никогда не видел. Это
самодостаточный пакет: уравнения риска напечатаны в самом отчёте,
а встроенный промпт для интерпретации позволяет любой LLM описать его, не
галлюцинируя о значении чисел. Разделы охватывают макросостояние и языковой
состав, топологию сети (модульность, точки сочленения, циклическую
плотность), узкие места зависимостей, самые тяжёлые функции и файлы, структурные
сигнатуры по файлам с радиусом поражения PageRank, целевые и кумулятивные
хит-листы риска, аудиты цепочки поставок и цели рефакторинга, ранжированные по волатильности и
централизации авторства — плюс поимённый список каждого файла, который он *отказался*
сканировать, и почему.
Два примера, просканированные 2026-08-31 текущим движком. Оба репозитория
публичны — клонируйте любой и запустите `galaxyscope --llm-only <path>`, чтобы воспроизвести
полный бриф:
**curl** — 4 250 артефактов, 696 просканировано, 112 653 строк кода на C, Perl, Python,
Shell, M4 и Makefile. Бриф ставит `src/tool_setup.h` на первое место
среди структурных опор (80 входящих связей) и помещает *Perl*-функцию —
`APPEND_imap` в `tests/ftpserver.pl`, Impact 2135, 1 672 строки кода — на вершину
общерепозиторного хит-листа функций, в том же рейтинге, что и код на C. Этот
кросс-языковой граф и есть продукт: единый сопоставимый набор сигналов по всем
языкам репозитория. Честная оговорка в том же брифе: просканировано лишь 16,4%
артефактов — фильтр приёма агрессивно отбрасывает бинарники, сгенерированный код
и тестовые данные, а §5 брифа перечисляет каждое исключение по
расширению и причине.
**cics-genapp** (образец CICS COBOL/DB2 от IBM) — просканировано 92,1%: 44 программы
на COBOL, 29 заданий JCL. Кумулятивный хит-лист структурной поверхности возглавляет
`base/src/lgupdb01.cbl` (поверхность мутаций ~100%, нагрузка сложности 92%), а
самый тяжёлый параграф в репозитории — `UPDATE-POLICY-DB2-INFO` — логика
блокировки строк `SELECT FOR UPDATE`, именно там, куда сопровождающий этой программы
захотел бы заглянуть в первую очередь. Тот же бриф также наглядно показывает ограничение:
на плоской архитектуре без реального графа импортов список «структурных опор»
вырождается в файлы с нулевыми связями, и отчёт советует проверять
счётчики связей, прежде чем ему доверять.
Сотни неотредактированных брифов для независимо выбранных репозиториев
зафиксированы в
[gitgalaxy-raw-output](https://github.com/squid-protocol/gitgalaxy-raw-output);
собственный всегда актуальный бриф самосканирования этого репозитория находится в
[`docs/gitgalaxy_architecture_brief.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/gitgalaxy_architecture_brief.md).
### Один граф, множество потребителей
| Потребитель | Вопрос |
|---|---|
| Архитектура | Из чего состоит этот репозиторий? |
| Структурный анализ | Где находятся функции, классы, API, зависимости и управляющие структуры? |
| Structural Surface Profile (ранее Risk exposure) | Где сконцентрирован заданный структурный/контентный паттерн? |
| Рефакторинг | Какие файлы сложны, часто меняются или несут нагрузку? |
| Цепочка поставок | Какие зависимости физически существуют на диске? |
| Контекст для ИИ | Какую архитектуру и связи должен знать агент? |
| Миграция легаси | Где находятся структурные единицы для преобразования? |
| Исторический анализ | Как измеренная экспозиция меняется по мере эволюции репозитория? |
------------------------------------------------------------------------
## Точность, измеренная
Две постоянные программы измерений подкрепляют приведённые выше утверждения, а третья,
для графов зависимостей и вызовов, находится в разработке. Полное повествование —
методология, вердикты, ограничения и что дальше — находится в
[программе валидации](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/validation.md); здесь — краткое изложение.
### Структурная валидация: GitGalaxy против Tree-sitter против Ctags
GitGalaxy сравнивается с **Tree-sitter и Universal Ctags** на закреплённом
корпусе [Language Crucible](https://github.com/squid-protocol/language-crucible)
— для 24 из 45 языков доступны все три инструмента, ещё для 13 — два, и каждое
расхождение исследуется по реальному исходному коду и фиксируется с вердиктом
(валидировано 200 из 201 зафиксированных форм расхождений). На этом корпусе
валидированная точность GitGalaxy по функциям составляет 100% для всех 31 языка,
сопоставимого с tree-sitter, и он никогда не оказывается инструментом, признанным
ошибочным в валидированном расхождении по классу или аргументу. Ограничение: три
структурные цели, один фиксированный корпус —
не «разбирает так же точно, как AST» в общем случае.
### Валидация графов: импорты и вызовы (в процессе)
Радиус поражения, PageRank и «структурные опоры» происходят из **графа импортов**. Рейтинги
на уровне функций происходят из **графа вызовов**. Ни один из графов пока не измерен для всех
языков, и диаграмма ниже показывает, для каких именно:
- Измеренные языки показывают точность и полноту с n.
- Каждый ещё не измеренный язык перечислен по имени.
По состоянию на 2026-09-26, из 59 языков:
- **Граф импортов измерен для 20.** Рёбра движка проверяются против собственных
операторов импорта каждого языка на закреплённых реальных репозиториях
([`import_graph_accuracy.py`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/tests/tools/import_graph_accuracy.py)).
- **Имена вызываемых измерены для 11**, против tree-sitter.
- **Разрешение вызовов измерено для 3**, против эталонного анализатора:
- Python, против pyan3: точность 99,8% на 1 806 оценённых связях, полнота 51,6%;
- TypeScript, против проверки типов TypeScript 6.0.2: точность 99,9% на 1 520 оценённых связях,
полнота 57,1%;
- Java, против scip-java (собственное разрешение javac): точность 92,7% на 3 474 оценённых связях,
полнота 41,0%. Вызов перегруженного метода связывается только тогда, когда количество его аргументов выбирает
одну перегрузку ([#3835](https://github.com/squid-protocol/gitgalaxy/issues/3835)).
Связь вызова, когда она установлена, обычно верна, но примерно половина или более вызовов остаются
несвязанными. Таким образом, fan-in и PageRank на уровне функций — это нижняя граница.
Ограничения:
- Графы остальных 38 языков строятся так же, но **не измерены**.
- Несколько измеренных языков опираются на один репозиторий с менее чем 100 импортами. Диаграмма затемняет
такие случаи.
- `*` отмечает число с расхождениями, всё ещё ожидающими вердикта по исходному коду.
План закрытия этих пробелов —
[эпик #3772](https://github.com/squid-protocol/gitgalaxy/issues/3772).
### Кросс-языковая согласованность: контрольный корпус Keyword Rosetta
Более новая программа задаёт противоположный вопрос: **измеряет ли GitGalaxy
идентичное намерение идентично во всех языках?** Корпус
[keyword-rosetta](https://github.com/squid-protocol/keyword-rosetta) размещает одну и ту же программу из 12 проб
во всех 50 поддерживаемых языках с точно известными
счётчиками сигналов — так что любое расхождение по построению является измеренным языковым смещением.
Диаграмма окрашивает каждое отклонение по *причине*, а не по величине: красный — открытый дефект движка
(правило, сопоставляющее не ту конструкцию, или вес оценки, попавший внутрь
счётчика); серый — задокументированная вариация, которую подтвердил реестр — язык
не может выразить конструкцию, намеренный выбор оценки или эхо другой
строки. Текущий ответ: в среднем 94% языков находятся в пределах ±25% от
кросс-языковой медианы по каждой гейтируемой метрике (56 отображаемых метрик, 54 удерживают ≥80%),
а **доля открытых дефектов составляет 0,0% (1 из 2 844 сопоставимых ячеек по 59 гейтируемым
метрикам)** — единственная необъяснённая ячейка, `classes_found` в недавно добавленном
корпусе `bms` (CICS Basic Mapping Support); каждая другая выходящая за пределы ячейка — это
вариация, подтверждённая реестром (страта строгости, конструкция, которую
язык не может выразить, эхо другой строки или намеренный выбор оценки),
а не открытый дефект движка. Самые слабые метрики названы, а не
скрыты — `cog_raw` удерживает 74% языков в диапазоне, `raw_arch_api` 78%,
`avg_func_args` 80% — но их ячейки вне диапазона задокументированы, а не являются дефектами.
Утверждение также выдерживает расширение: когда корпус разместил свою первую
пробу с точки зрения безопасности — один идентичный захардкоженный секрет во всех языках —
`credential_material` (ранее `risk_secrets_risk`; имя `risk_*` остаётся
именем столбца БД — см. [`docs/vectors.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/vectors.md)) показал **единообразную
оценку по всем 50 языкам** (идентичные 25.000 на столбец). Два
исключения инертных форматов, которые линза изначально пропускала, и измеренная
зависимость формулы от длины были внесены в реестр и зарегистрированы в тот же день
([#2978](https://github.com/squid-protocol/gitgalaxy/issues/2978),
[#2979](https://github.com/squid-protocol/gitgalaxy/issues/2979)). #2978
закрыт: линза теперь работает со всеми пятью инертными форматами
(plaintext/markdown/json/yaml/csv), с опцией конфигурации `SECURITY_SCAN_INERT_FORMATS`
для репозиториев, где это обменивает слишком много шума документации/конфигурации на
покрытие, а повторная верификация корпуса keyword-rosetta против объединённого исправления
теперь полностью попадает в диапазон (запись реестра `secrets-lens-inert-formats`).
Каждое отклонение записано в валидированный реестр, работа отслеживается по семействам причин
в рамках [дорожной карты контрактов](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/contract_roadmap.md), а
классы дефектов, найденные таким образом,
[зарегистрированы как issues GitGalaxy](https://github.com/squid-protocol/keyword-rosetta/blob/main/docs/findings_by_language.md).
Контрольный корпус доказывает неравенство измерений при идентичном намерении; он ничего
не говорит о точности на реальном коде (это задача три-сравнения выше) — и
постоянное смещение по файлам всё равно сохраняет ранжирование *внутри* языка.
[Отчёт о распространённости](https://github.com/squid-protocol/keyword-rosetta/blob/main/docs/incidence_report.md)
оценивает каждую подтверждённую форму на реальном лицензированном коде.
------------------------------------------------------------------------
## Реальный масштаб
Пример: **Kubernetes** — ~1,39 млн строк на Go, YAML, JSON, Shell и Proto.
Сканирование от начала до конца: **50,83 секунды**. Время сканирования следует подогнанной двухрежимной модели
(плоское ~0,11 с ниже ~4,3 тыс. строк кода, затем `time(s) ≈ 3.36e-05 × LOC^0.969`, R²=0,88
по 599 репозиториям) — так что несколько выбросов размером 20M+ строк кода всё ещё занимают минуты, а
быстрое сканирование доказывает пропускную способность, а не качество инсайтов; вопрос точности
рассматривается отдельно ниже.
Смотрите [репозиторий необработанного
вывода](https://github.com/squid-protocol/gitgalaxy-raw-output) для
неотредактированных артефактов.
------------------------------------------------------------------------
# Structural Surface Profile: что утверждает GitGalaxy (ранее «Risk exposure»)
13 пофайловых векторов GitGalaxy изначально назывались `risk_*` и описывались как
**измерения риск-экспозиции**. Вопрос, который этот раздел раньше оставлял открытым —
«эмпирически ли эти сигнатуры связаны со значимыми классами
программного риска?» — с тех пор был проверен, а не просто задан. Программа валидации
temporal-crucible (эпик
[#2982](https://github.com/squid-protocol/gitgalaxy/issues/2982), ~3 550
просканированных снимков, два репозитория, три семейства меток, каждый тест
предварительно зарегистрирован до просмотра данных) провела этот эксперимент до
исчерпания, и честный результат привёл к переименованию
([#2991](https://github.com/squid-protocol/gitgalaxy/issues/2991)):
векторы теперь называются **Structural Surface Profile**. `risk_*` остаётся
именем столбца БД / ключа JSON для совместимости (см.
[`docs/vectors.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/vectors.md) для полной таблицы имён и
примечания об устаревании).
**Что показала запись, изложенное честно:**
- **Постоянный пофайловый риск — опровергнут.** Исходная гипотеза — что
уровень `risk_*` файла или его изменение после исправления отслеживает вероятность
дефекта — не подтвердилась. Медианная структурная дельта после исправления безопасности
составила +0.000 (эквивалентность подтверждена как близкая к нулю на втором, независимом
репозитории, а не просто незначимость); суммарная структурная экспозиция заняла
*последнее* место из шести признаков для предсказания файлов, затронутых исправлениями; 26-сигнальный
многомерный структурный вектор показал результат на уровне случайного (AUC 0.479) при
временном разбиении, ниже простого подсчёта строк (0.531). Полный реестр находится в
`docs/HYPOTHESES.md` temporal-crucible и связан из
[#2982](https://github.com/squid-protocol/gitgalaxy/issues/2982).
- **Для чего векторы действительно прошли валидацию:** для описания **активности и
контента**, а не вероятности дефекта. Композит формы исправления надёжно
отслеживает градиент security-fix → ordinary-fix → control → revert; дельты
соответствуют реальным событиям в коде (добавлен защитный код, введена многопоточность,
размыты маркеры долга). Это тот рентген, который данный документ теперь называет
точно — см. [`docs/vectors.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/vectors.md) вектор за вектором.
- **Сигнал системного уровня / истории, переформулированный как фактическая прогнозная
находка.** Два признака *всё же* выдержали валидацию: **рецидивизм** (файл,
в котором было последнее исправление, получает следующее — самый воспроизводимый
результат программы, p<1e-4 на обоих репозиториях) и **энтропия изменений /
Hassan HCM**, валидированная вне выборки на свежих метках багов (AUC 0.868 против
0.830 у подсчёта строк). Обе — метрики **истории**, а не структурного
контента — и обе в настоящее время обнулены в каждом сканировании
(`GITGALAXY_DISABLE_GIT_HISTORY`, отслеживается в
[temporal-crucible#29](https://github.com/squid-protocol/temporal-crucible/issues/29)).
Это семя отдельного, честно названного **прогнозного слоя** — векторы
`hist_stability`/`hist_churn` названы так, чтобы явно обозначить этот статус —
обусловленного выпуском режима с включённой историей и последующим выполнением
контракта продвижения по дефектам из
[#2987](https://github.com/squid-protocol/gitgalaxy/issues/2987).
Высокое значение Structural Surface Profile означает:
> **В этом месте присутствует больше заданного структурного/контентного паттерна
> относительно остальной части репозитория.**
Оно не означает:
> «Этот код с большей вероятностью содержит дефект» — пофайловая версия
> этого утверждения была проверена и не подтвердилась.
Лежащие в основе сигнатуры охватывают паттерны, связанные с такими областями, как:
- секреты
- поверхность инъекций
- небезопасные/работы с памятью
- динамическое исполнение
- ввод-вывод
- конкурентность
- мутация состояния
- рефлексия
- API
- зависимости
- энтропия
- другие структурные/безопасностные характеристики
См. [`docs/vectors.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/vectors.md) для таблицы переименования по векторам,
доказательств и уместного/неуместного использования, а также
`docs/HYPOTHESES.md` в
[temporal-crucible](https://github.com/squid-protocol/temporal-crucible) для полного реестра валидации, который обобщает этот раздел.
------------------------------------------------------------------------
# Доказательства, а не просто утверждения
### Language Crucible
Закреплённый корпус реального исходного кода, включающий такие проекты, как Godot, Roslyn,
curl, Kubernetes и бортовое ПО Apollo 11.
[Language Crucible](https://github.com/squid-protocol/language-crucible)
### Регрессия golden-master
Реальный исходный код пересканируется и сравнивается с зафиксированным в репозитории ожидаемым выводом, так что
изменения парсера дают наблюдаемый diff. Регенерируется с помощью
[`tests/tools/update_golden_master.py`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/tests/tools/update_golden_master.py),
никогда не редактируется вручную.
### Три-сравнение
Тот же корпус анализируется против GitGalaxy, Tree-sitter и Ctags там, где
есть покрытие — для 24 из 45 языков доступны все три инструмента, валидировано 200 из 201 зафиксированных
расхождений. На закреплённом корпусе GitGalaxy никогда не оказывается инструментом,
признанным ошибочным в валидированном расхождении по точности функций, классу или аргументу,
и совпадает с полнотой tree-sitter по функциям везде, кроме одного вложенного определения shell,
которое он пропускает намеренно. См.
[методологию](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/self_scan/tri_comparison_README.md) и
[программу валидации](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/validation.md) для полной картины и её
ограничений.
### Контрольный корпус Keyword Rosetta
Одна и та же программа из 12 проб, размещённая во всех 50 поддерживаемых языках с точно
---
[Read more](https://gitlab.com/squid-protocol1/gitgalaxy)