Ayush-Pathania/C2-Framework-Learning-Project-
GitHub: Ayush-Pathania/C2-Framework-Learning-Project-
一个用于防御性安全研究的最小化 C2 框架概念验证项目，通过 Python 和 C 实现双向通信以帮助理解命令与控制机制。
Stars: 0 | Forks: 0
# C2 框架 — 概念验证
**状态：** = **语言：** Python 3, C | **平台：** Windows (agent), 跨平台 (teamserver)
## 目录
| 章节 | 描述 |
|------------------------------|--------------------------------------|
| [概述](#overview) | 本项目是什么以及它是如何工作的|
| [架构](#architecture) | Teamserver 和 Agent 设计 |
| [协议](#protocol) | 二进制消息格式和命令代码 |
| [项目结构](#project-structure) | 文件和目录 |
| [构建](#building) | 前置条件和构建步骤 |
| [运行](#running) | 如何启动 teamserver 和 agent|
| [测试](#testing) | 测试套件和结果 |
| [文档](#documentation) | 规范、路线图和状态的链接|
| [目的](#purpose) | 教育目标 |
| [许可证](#license) | 使用条款 |
## 概述
一个包含两个组件的极简双向 C2 (Command and Control) 框架：
| 组件 | 语言 | 平台 | 角色 |
|---------------|------------|---------------------|---------------------------------------|
| **Teamserver**| Python 3 | 跨平台 | TCP 监听器, 会话管理器, CLI |
| **Agent** | C | Windows (Winsock2) | 连接到 teamserver，执行命令 |
通信使用自定义的基于长度前缀的二进制协议，通过原始 TCP socket 进行。该项目针对防御性安全研究——了解 C2 系统的运作方式以改进检测。
## 架构
### Teamserver
- 监听可配置的 TCP 端口（默认为 `127.0.0.1:8888`）
- 接受传入的 agent 连接，并为每个 agent 创建一个会话
- 存储会话元数据：主机名、进程 ID、socket 句柄
- 提供一个交互式 CLI，操作员可以在其中选择一个会话并发送命令
- 将所有事件和错误记录到 `teamserver.log`
- 实现了一个监控线程，该线程使用 `MSG_PEEK` 来检测 agent 断开连接，而无需消耗 socket 缓冲区中的数据
### Agent
- 使用 MinGW/TCC 和 Winsock2 构建
- 接受服务器 IP 和端口作为命令行参数
- 建立到 teamserver 的 TCP 连接
- 发送包含系统主机名和进程 ID 的握手消息
- 进入接收循环，等待来自服务器的命令包
- 执行接收到的命令并将确认 (ACK) 发送回服务器
- 将所有活动和错误记录到 `agent.log`
### 通信流程
```
Agent Teamserver
| |
| --- TCP Connect ------------> |
| | Accept connection
| | Create session
| |
| --- Handshake (Cmd 0x00) --> |
| (hostname, PID) | Parse & store session
| |
| Operator types command in CLI
| <-- Send Command (0x01) ---- |
| |
| Execute command locally |
| |
| --- Send ACK (Cmd 0x02) ---> |
| (status: success) | Receive & display to operator
| |
| --- Disconnect ------------> |
| | Monitor detects removal
```
## 协议
所有消息均使用长度前缀的二进制格式：
```
+------------+----------+------------------+
| 4 bytes | 1 byte | N bytes |
| length | cmd_type | payload |
| (big-endian)| (code) | (variable-length)|
+------------+----------+------------------+
```
### 命令类型
| 代码 | 名称 | 方向 | 载荷 |
|--------|-----------|-----------------|--------------------------------------|
| `0x00` | 握手 | Agent -> Server | 主机名 (字符串), PID (uint32) |
| `0x01` | 命令 | Server -> Agent | 命令字符串 (可变长度) |
| `0x02` | ACK | Agent -> Server | 状态字节 (`0x00` = 成功) |
### 消息封装 (C)
```
// Pack: [4-byte BE length] [1-byte cmd] [payload]
unsigned char* pack_message(
unsigned char cmd,
unsigned char *data,
int data_len,
int *packet_len
);
```
## 项目结构
```
project_github/
├── build.bat
│ Windows build script (compiles agent.c -> agent.exe)
├── Makefile
│ Makefile for Unix-like environments
├── teamserver.py
│ Main teamserver -- TCP listener, session manager, CLI
├── agent.c
│ Agent source code (Windows, Winsock2, C11)
│
├── core/
│ ├── mock_server.py
│ │ Mock server for testing protocol logic
│ └── simple_server.py
│ Simplified server for quick testing
│
├── test/
│ ├── test_c2.py
│ │ End-to-end C2 protocol tests
│ ├── test_protocol.py
│ │ Binary protocol pack/unpack tests
│ ├── test_winsock.c
│ │ Winsock2 minimal test program
│ ├── winsock2_minimal.h
│ │ Minimal Winsock2 header for Windows builds
│ ├── test_bugs_1_3.py
│ │ Tests for session cleanup and race condition fixes
│ ├── test_bug7_ack_timeout.py
│ │ Tests for monitor ACK timeout behavior
│ └── test_bugs_4_5_6.c
│ C-level test for protocol bugs 4-6
│
├── documentation/
│ ├── README.md
│ │ This file
│ ├── C2_Project_Specification.md
│ │ Full technical specification
│ ├── ROADMAP.md
│ │ 5-phase development roadmap
│ └── PROJECT_STATUS.md
│ Current implementation and test status
│
├── diagnostics/
│ ├── repro_stale_session.py
│ │ Reproduces stale session bug
│ └── run_error_tests.py
│ Runs error scenario tests
│
└── lib/
└── tcc/
├── include/
│ Platform headers (Winsock2, Windows SDK)
├── lib/
│ Import libraries (kernel32, ws2_32, user32, etc.)
├── struct.c
│ TCC source (builds tcc.exe)
└── tcc.exe
TCC compiler binary for Windows
```
## 构建
### 前置条件
- **Windows**（用于构建 agent）
- `lib/tcc/` 中内置的 TCC 编译器（无需安装外部 MinGW）
- **Python 3.x**（用于 teamserver 和测试）
### 构建 Agent
```
build.bat
```
或者使用内置的 TCC 编译器手动构建：
```
lib\tcc\tcc.exe -o agent.exe agent.c -lws2_32
```
### 构建 Teamserver
Teamserver 直接使用 Python 3 运行——无需编译。
```
python teamserver.py
```
## 运行
1. 启动 teamserver：
python teamserver.py
2. 在 Windows 机器上运行 agent：
agent.exe 127.0.0.1 8888
3. teamserver CLI 会显示已连接的 agent。选择一个会话并输入要发送的命令。
## 测试
在项目根目录下运行完整的测试套件：
```
python -m pytest test/ -v
```
### 测试结果
| 测试文件 | 测试数 | 状态 |
|------------------------------|-------|--------------------|
| `test_bug1_stale_sessions.py` | 2 | 通过 |
| `test_bug2_cleanup.py` | 3 | 通过 |
| `test_bug3_race.py` | 1 | 通过 |
| `test_c2.py` | 1 | 失败 (需要 `agent.exe`) |
| `test_bug7_ack_timeout.py` | 3 | 通过 |
| `test_bugs_4_5_6.py` | 3 | 通过 |
| `test_protocol.py` | 2 | 通过 |
| **总计** | **12**| **10 通过, 2 失败** |
2 个失败的测试需要已编译的 `agent.exe` 二进制文件（通过 `build.bat` 构建）。其余 10 个测试验证了协议逻辑、会话管理、监控行为和错误修复，而无需编译的 agent 二进制文件。
## 文档
| 文件 | 描述 |
|------------------------------|--------------------------------------------------|
| `PROJECT_STATUS.md` | 当前实现状态、测试结果 |
| `C2_Project_Specification.md`| 完整协议规范、组件设计 |
| `ROADMAP.md` | 5 阶段开发路线图 (PoC 到企业级) |
有关最新的实现和测试状态，请参阅 [PROJECT_STATUS.md](PROJECT_STATUS.md)。
## 目的
本项目是作为一项教育研究练习创建的，旨在了解：
- C2 框架如何建立和管理双向通信
- 用于命令和控制通道的自定义二进制协议设计
- 会话管理和已连接 agent 的跟踪
- 检测工程——了解 C2 系统会产生哪些网络和行为签名
本项目仅供防御性安全研究和学习使用。它不是为未经授权访问计算机系统而设计或意图用于此目的的。
## 许可证
仅供教育使用。请勿用于未经授权的活动。
标签：C2框架, Gophish, Python, 二进制协议, 安全学习资源, 无后门, 概念验证, 网络安全, 隐私保护