gitgalaxy — 已更新!
免 AST 的启发式知识图谱引擎，用于深度仓库智能分析和零信任安全扫描。可作为 GitLab CI/CD 组件集成，阻止恶意代码，并将 SARIF 遥测数据导出至 GitLab Security Dashboard。
GitGalaxy
无需编译的仓库级结构智能。
1 次扫描 · 97 项结构信号 · 50+ 种语言 · 无需编译 · 19 类风险暴露 · 6 种输出
简而言之
GitGalaxy 直接从源代码文本构建整个仓库的语言无关结构图。
它专为多语言、部分损坏、遗留、重度依赖第三方、或通过构建优先工作流难以分析的其他类型仓库而设计。
GitGalaxy 无需为每种语言提供成功的构建和单独的解析器/工具链，而是提取一组通用的结构签名词汇——函数、类、参数、控制流、状态变更、I/O、API、依赖及其他信号——并将这些观察结果归一化为一个统一的仓库模型。
同一张图随后可服务于：
- 架构分析
- 风险暴露优先级排序
- 依赖/SBOM 分析
- 重构与所有权分析
- 遗留代码分析
- 面向 AI 的代码库上下文
- CI/CD 工作流
- 历史风险分析
核心论点： 在仓库规模下恢复高度有用的结构信息，并不总是需要完整的语言解析。
问题所在
大型仓库通常包含：``` text Go + C++ + Python + Java + Bash + YAML
- generated code + vendored code + legacy code
- half-migrated modules + broken dependencies
传统语言工具在其预期范围内可能表现出色，但仍会让仓库因语言特定的表示方式而变得碎片化。
GitGalaxy 做出了不同的取舍：``` text
Source repository
|
v
Structural signatures
|
v
Normalized entities + risk signals
|
v
Deterministic repository graph
|
+---- Architecture
+---- Risk exposure
+---- Dependencies / SBOM
+---- AI context
+---- Refactoring
+---- Git-history analysis
目标不是逐字复刻每种语言的每一个句法细节。
目标是恢复下游仓库情报实际需要的结构信息。
一张图，众多使用者
GitGalaxy 的核心输出是仓库的确定性结构表示。
使用者 问题
架构 这个仓库由什么构成？
结构分析 函数、类、API、依赖和控制结构在哪里？
风险暴露 潜在的重要风险模式集中在何处？
重构 哪些文件复杂、变更频繁或承担关键负载？
供应链 磁盘上实际存在哪些依赖？
AI 上下文 智能体应了解哪些架构和关系？
遗留系统迁移 需要转换的结构单元在哪里？
历史分析 随着仓库演进，测得的暴露如何变化？
结构提取论点
GitGalaxy 刻意不从为每种语言构建完整 AST 开始。
它使用大约 97 类结构信号类别来识别诸如以下内容：
- 函数和方法边界
- 类和声明
- 参数
- 分支和控制流
- 状态变更
- I/O
- API 和路由
- 导入和依赖
- 不安全操作
- 反射和动态执行
- 并发
- 闭包
- 全局变量
- 熵和物理文件异常
这形成了一个具体、可检验的假设：
对于仓库级情报，有针对性的结构提取可以在无需为每个文件配备完整语言解析器的情况下，恢复代码情报所需的关键实体。
该假设正在被实证检验。
结构验证：GitGalaxy vs Tree-sitter vs Ctags
这目前是项目中最重要的验证计划之一。
GitGalaxy 正在与 Tree-sitter 和 Universal Ctags 在相同的 Language Crucible 语料库上进行对比评估。
首批结构目标包括：
- 函数
- 类
- 参数
该基准刻意不被视为三工具的人气竞赛。
当工具产生分歧时：
- 记录分歧；
- 检查源代码；
- 调查每个工具的行为；
- 当 GitGalaxy 出错时修复 GitGalaxy；
- 当比较器出错时修复比较器/适配器代码；
- 记录真实的工具局限性；
- 重新测量结果。
45 种语言中有 24 种获得全部三个工具的对比，另有 16 种获得两个工具的对比，还有 5 种仅由 GitGalaxy 覆盖的语言（abap、dockerfile、jcl、livecode、yaml）采用人工审查的手动验证，而非跨工具一致性。在迄今记录的 180 种差异形态中，87 种已获验证（48%）——即经过阅读、调查并记录结论，而不仅仅是计数。
目标是完成审计、修复剩余的 GitGalaxy 缺陷、在必要时建立独立的基准真值，然后发布最终的精确率/召回率测量结果。有关匹配机制、台账生命周期和 CI 强制执行的工作方式，请参阅三向比较方法论文档。
参见：
tests/tools/tri_comparison_chart.pydocs/self_scan/tri_comparison_ledger.json— 完整的、按形态验证的记录docs/self_scan/tri_comparison_points_of_interest.md— 同一台账，按信号强度渲染并排序docs/self_scan/how_to_investigate_a_discrepancy.mddocs/self_scan/manual_verification.json
该基准实际在问什么
不是：
“GitGalaxy 是比 Tree-sitter 更好的解析器吗？”
而是：
“对于 GitGalaxy 构建其仓库图谱所需的结构实体，与成熟的解析和索引系统相比，有针对性的结构提取能以多高的准确度恢复它们？”
这才是该实验能够支持的更窄的论断。
缺乏合适比较器覆盖的语言
某些语言目前没有合适的独立 Tree-sitter/Ctags 比较路径。
这些语言被归入单独的取证类别，并使用已提交的手动验证，而非假装存在跨工具一致性。
目前这包括诸如以下语言：
- ABAP
- Dockerfile
- JCL
- LiveCode
- YAML
在可行的情况下，下一步是添加独立的词法、基于语法或领域特定的比较器。在不存在可信的独立比较器时，人工验证的基准真值仍是适当的类别。
验证是一架阶梯
GitGalaxy 的证据正围绕逐步增强的问题来组织。
1. 结构有效性
GitGalaxy 能否正确识别代码结构？
Tree-sitter + Ctags + 独立调查的分歧。参见上文“结构验证”。
2. 回归有效性
实现能否在真实代码上保持稳定？
针对 Language Crucible 的黄金主测试。
3. 规模有效性
它能否在真实仓库上工作？
来自数百个仓库的未经编辑的原始扫描输出。
4. 模型有效性
结构签名是否对应于它们旨在代表的暴露类别？
针对独立可观察结果的统计分析——而不仅仅是针对 GitGalaxy 自身的方程。
5. 时间有效性
随着软件变化，暴露是否表现合理？
比较真实变更前后仓库状态的 Git 历史分析。
6. 外部有效性
暴露变化是否对应于独立记录的安全或维护结果？
未来工作：安全修复、回归、公告、缺陷及其他外部事件数据集。
这一区分至关重要：一个分数可以在内部保持一致，却未必具有外部意义。
风险暴露：GitGalaxy 的主张
GitGalaxy 产生风险暴露测量，而非漏洞判定。
高暴露意味着：
相对于仓库的其他部分，此位置值得关注。
它并不意味着：
“这段代码肯定存在漏洞。”
当前系统在仓库范围内产生归一化的暴露类别，并将结构实体的信息通过文件、文件夹和仓库级视图进行汇总。
底层签名涵盖涉及以下领域的模式：
- 机密信息
- 注入面
- 不安全/内存操作
- 动态执行
- I/O
- 并发
- 状态变更
- 反射
- API
- 依赖
- 熵
- 其他结构/安全特征
重要的研究问题是，这些签名是否在经验上与有意义的软件风险类别相关联，而不仅仅是与 GitGalaxy 自身数学构造的分数相关。
这一区分将推动下一阶段。
下一项验证：Git 历史中的风险
一旦结构验证足够成熟，GitGalaxy 就可以对其暴露模型进行纵向检验。``` text Git history | v security-relevant event | +-------------------+ | | v v parent state changed state | | v v GitGalaxy scan GitGalaxy scan | | +---------+---------+ | v exposure delta | v independent event class
核心实验是：
> **被独立识别为安全修复的提交，是否通常会降低相应的 GitGalaxy 暴露度？**
阴性对照同样重要：
> 普通开发提交是否表现出相同的行为？
最终：
> 安全回归是否会增加暴露度？
计划中的测试框架将保留提交 SHA、父状态、变更的文件/函数、暴露前后值、暴露增量、结构变更和事件分类。
这将检验：
**结构 → 暴露 → 真实软件演化**
而不仅仅是检验暴露模型内部数学的正确性。
------------------------------------------------------------------------
# 证据，而非仅仅是主张
### 语言熔炉
一个固定的真实世界源码语料库，涵盖 Godot、Roslyn、curl、Kubernetes 和 Apollo 11 飞行软件等项目。
[Language Crucible](https://github.com/squid-protocol/language-crucible)
### 黄金主回归测试
真实源码会被重新扫描，并与已检入的预期输出进行比对，从而使解析器变更产生可观察的差异。通过
[`tests/tools/update_golden_master.py`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/tests/tools/update_golden_master.py)
重新生成，绝不手工编辑。
### 三方对比
同一语料库在覆盖范围内会分别使用 GitGalaxy、Tree-sitter 和 Ctags 进行分析——45 种语言中有 24 种可同时使用全部三种工具，迄今已验证 180 条记录差异中的 87 条。完整情况请参阅
[方法论](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/self_scan/tri_comparison_README.md) 和
[上文“结构验证”一节](#structural-validation-gitgalaxy-vs-tree-sitter-vs-ctags)。
### 原始仓库输出
数百个独立选定的仓库均保留未经编辑的 GitGalaxy 输出。
[Raw Output](https://github.com/squid-protocol/gitgalaxy-raw-output)
### 回归测试套件
默认测试套件（`python -m pytest tests/`）包含 **7,043 项测试**，其中 **6,165 项** 是针对全部 45 种具有结构签名的语言的逐签名测试——包括正向匹配、显式排除以及对抗性/ReDoS 输入。详细分类请参阅 [`tests/README.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/tests/README.md)，关于此提取在特定场景下优于 AST 读取的具体实证案例，请参阅 [`docs/why_gitgalaxy_beats_ast_here.md`](https://gitlab.com/squid-protocol1/gitgalaxy/-/blob/main/docs/why_gitgalaxy_beats_ast_here.md)。
### 历史验证
下一层研究将检验暴露度测量是否与 Git 历史中的真实安全和维护事件相对应。
------------------------------------------------------------------------
# GitGalaxy 是什么——以及不是什么
### GitGalaxy 是
- 仓库规模的结构智能
- 语言无关的源码分析
- 跨异构代码的统一结构表示
- 风险暴露度优先级排序
- 架构映射
- 面向 CI 的证据生成
- 适用于损坏/未编译的仓库
- 专为本地/离线运行而设计
### GitGalaxy 不是
- CodeQL 深度数据流分析的替代品
- Semgrep 规则生态系统的替代品
- 依赖 CVE 数据库的替代品
- 可利用性的证明
- 运行时分析器
- 完整的语言解析器
- 高暴露度即漏洞的保证
-----------------------------------------------------------------------
工具 核心问题
----------------------------------- -----------------------------------
**GitGalaxy** 整个仓库在结构上是什么样子的，
注意力应首先放在哪里？
Tree-sitter 该源码包含何种句法结构？
Ctags 可导航的代码实体位于何处？
Semgrep 该代码是否匹配指定模式？
CodeQL 更深层的分析能建立哪些数据/控制
关系？
SCA/CVE 工具 该依赖/版本是否与已知公告相关？
-----------------------------------------------------------------------
------------------------------------------------------------------------
# 真实世界规模
GitGalaxy 面向那些过于异构或损坏、无法采用传统单语言先构建后分析工作流的仓库。
示例：**Kubernetes**
Go、YAML、JSON、Shell 和 Proto 合计约 139 万行。
端到端扫描：**50.83 秒**。
未经编辑的产物请参阅[原始输出
仓库](https://github.com/squid-protocol/gitgalaxy-raw-output)。
------------------------------------------------------------------------
# 输出
输出 用途
---------------------------- ----------------------------------------
**SARIF** CI/安全仪表板集成
**CycloneDX SBOM** 依赖清单/合规
**SQLite** 可查询的仓库知识图谱
**LLM 架构简报** 紧凑的机器/代理导向上下文
**JSON 审计数据** 取证/自动化工作流
**3D 可视化数据** 交互式仓库拓扑
这些是同一确定性扫描的不同视图，而非相互独立的分析引擎。
------------------------------------------------------------------------
# Git 历史与架构
GitGalaxy 已将 Git 历史纳入以下信号中：
- 变更频率（churn）
- 贡献者集中度
- 公交因子暴露度
- 重构热点
- 文件所有权
- 时间活动
研究方向是将此从**作为上下文信号的历史**扩展为**作为暴露模型外部验证来源的历史**。
------------------------------------------------------------------------
# 隐私与部署
GitGalaxy 专为本地和隔离环境运行而设计。
- 源码不会发送到 GitGalaxy 云服务。
- 扫描和向量化均在本地进行。
- 扫描器无运行时网络需求。
- CI/CD 执行可保持在用户环境内。
- 浏览器可视化器基于本地提供的数据运行。
------------------------------------------------------------------------
# 安装``` bash
pip install gitgalaxy
参见文档了解 当前命令和配置。
CI/CD
提供了以下模板：
- GitHub Actions
- GitLab CI
- Bitbucket Pipelines
- Azure Pipelines
- 通用的 shell 可调用 CI 环境
探索证据
资源 包含内容
文档 架构、声明和 方法论
Language Crucible 跨语言基准和黄金 语料库
原始输出 真实仓库的未编辑扫描结果
tests/README.md 回归和黄金主版本
方法论
tri_comparison_ledger.json 逐项分歧
验证记录
manual_verification.json 已审查的、比较器
覆盖不可用的案例
how_to_investigate_a_discrepancy.md 比较器分歧方法论
可视化工具 基于浏览器的本地仓库 可视化
当前研究方向
GitGalaxy 正在经历一系列难度递增的问题：
我们能否在不编译的情况下扫描异构源代码？
↓
我们能否可靠地恢复理解代码所需的结构实体？
↓
这些结构度量是否对应有意义的风险暴露？
↓
随着真实软件的发展，测得的暴露是否表现正确？
Tree-sitter/Ctags 验证目前大约完成了一半。 当务之急是在将初步度量转化为更强的主张之前完成这项审计。
下一个主要实验是：
Git 历史 → 独立识别的变更/修复事件 → GitGalaxy 前后扫描 → 暴露增量 → 统计分析。
这正是 GitGalaxy 可以开始测试的地方——不仅测试它是否看到 结构，还测试其结构模型是否追踪真实软件中有意义的变化。
许可证
版权所有 (c) 2026 Joe Esquibel
GitGalaxy 根据 PolyForm 非商业许可证 1.0.0 分发。
完整条款请参见仓库许可证。