GitMaster

中文 | English

---

English

GitMaster is an independently written Python tool for recovering source files from an exposed .git/ directory.

It supports repositories that use:

• loose objects
• packfiles
• mixed loose + pack storage
• packed-refs

This project is focused on practical recovery of modern exposed Git repositories, especially those already processed by git gc or git repack.

Use only on systems you own or are explicitly authorized to assess.

Features

• Parse .git/index
• Recover files from loose objects
• Recover files from packfiles
• Recover files from mixed repositories
• Mirror useful Git metadata locally
• Use the local git binary for object resolution when available
• Preserve original paths when writing recovered files
• Maintain a local .git/ mirror inside the output directory
• Show a visual progress bar during recovery

Requirements

• Python 3.9+
• Git installed in PATH for full packfile support
• Python dependencies listed in requirements.txt

Install dependencies:

pip install -r requirements.txt

Usage

python gitmaster.py http://target/.git/

Example:

python gitmaster.py http://192.168.56.102/.git/

Optional arguments:

python gitmaster.py http://target/.git/ -o recovered_repo -t 8 --timeout 10

Output

Recovered files are written into a directory named after the target host unless -o is provided.

192.168.56.102/
├── .git/
├── index.php
├── config.php
└── class/

How it works

1. Download .git/index
2. Parse file paths and blob hashes from the Git index
3. Mirror available metadata such as:
   • HEAD
   • packed-refs
   • objects/info/packs
   • objects/pack/*.pack
   • objects/pack/*.idx
4. Resolve objects locally
5. Recover blob contents and rebuild the working tree layout

When Git is installed locally, GitMaster uses git cat-file and git index-pack to work with packfile-backed repositories.

Why packfile support matters

Many older exposed-.git recovery scripts only work when objects are accessible as loose files:

.git/objects/ab/cdef...

But many real repositories have already been compacted with git gc or git repack, so the actual data is stored in:

.git/objects/pack/*.pack
.git/objects/pack/*.idx

In those cases, file names may still be visible via .git/index, but object download via objects/xx/... returns 404.

GitMaster is designed to recover from that situation.

Files in this repository

• gitmaster.py — main recovery script
• requirements.txt — Python dependencies
• README.md — bilingual project overview and usage
• NOTICE — implementation note
• LICENSE — license for this rewritten release

Legal / Ethical Notice

This project is intended for:

• authorized security testing
• lab environments
• incident response
• defensive validation

Do not use it against systems without permission.

---

中文说明

GitMaster 是一个独立重写的 Python 工具，用于从暴露的 .git/ 目录中恢复源代码文件。

它支持以下 Git 对象存储形式：

• loose objects（松散对象）
• packfiles（打包对象）
• loose + pack 混合存储
• packed-refs

本项目重点解决真实环境中常见的 .git 泄露恢复问题，尤其适用于已经执行过 git gc 或 git repack 的仓库。

仅可用于你拥有或明确获得授权的目标系统。

功能特性

• 解析 .git/index
• 从 loose objects 恢复文件
• 从 packfiles 恢复文件
• 支持混合对象仓库恢复
• 本地镜像关键 Git 元数据
• 在本地有 Git 时使用 git 命令解析对象
• 按原始目录结构恢复文件
• 在输出目录中保留本地 .git/ 镜像
• 恢复过程中显示可视化进度条

运行要求

• Python 3.9+
• 为完整支持 packfile，建议系统 PATH 中可直接调用 git
• Python 依赖见 requirements.txt

安装依赖：

pip install -r requirements.txt

使用方法

python gitmaster.py http://target/.git/

示例：

python gitmaster.py http://192.168.56.102/.git/

可选参数：

python gitmaster.py http://target/.git/ -o recovered_repo -t 8 --timeout 10

输出结果

如果未指定 -o，恢复结果默认写入以目标主机名命名的目录中。

192.168.56.102/
├── .git/
├── index.php
├── config.php
└── class/

工作原理

1. 下载 .git/index
2. 从 Git index 中解析文件路径和 blob 哈希
3. 镜像远端可访问的关键元数据，例如：
   • HEAD
   • packed-refs
   • objects/info/packs
   • objects/pack/*.pack
   • objects/pack/*.idx
4. 在本地解析对象
5. 恢复 blob 内容并重建工作区目录结构

如果本地安装了 Git，GitMaster 会调用 git cat-file 和 git index-pack 来处理 packfile 仓库。

为什么 packfile 支持很重要

很多较早的 .git 恢复脚本只支持这种松散对象路径：

.git/objects/ab/cdef...

但真实环境中的很多仓库都已经被 git gc 或 git repack 处理过，对象实际保存在：

.git/objects/pack/*.pack
.git/objects/pack/*.idx

这时通常仍然可以从 .git/index 中看到文件名，但访问 objects/xx/... 会得到 404。

GitMaster 正是为这种场景设计的。

仓库文件说明

• gitmaster.py — 主恢复脚本
• requirements.txt — Python 依赖
• README.md — 中英双语说明文档
• NOTICE — 实现说明
• LICENSE — 当前重写版项目许可

法律 / 使用声明

本项目仅面向：

• 已授权安全测试
• 实验环境
• 应急响应
• 防御验证

请勿在未获授权的系统上使用。