# protocolfuzz

**Repository Path**: little77/protocolfuzz

## Basic Information

- **Project Name**: protocolfuzz
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-26
- **Last Updated**: 2025-11-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 协议模糊测试工具 - Protocol Fuzzer

一个功能强大、易于扩展的协议模糊测试工具，专为网络协议安全性测试和漏洞发现设计。

## 项目简介

Protocol Fuzzer 是一个基于 Python 的协议模糊测试框架，用于自动化检测网络协议实现中的安全漏洞。该工具基于修改版的 Boofuzz 库，提供了灵活的扩展接口和丰富的协议支持，特别适用于网络协议和工控协议的安全性测试。

### 主要特性

- **多协议支持**：内置 HTTP 等常见协议支持，易于扩展新协议
- **自定义模糊策略**：可配置的模糊测试参数和策略
- **目标监控**：支持进程监控和自动重启功能
- **详细日志**：完整的测试日志和结果记录
- **可扩展架构**：模块化设计，便于添加新功能和协议支持
- **Docker 支持**：提供容器化部署方案
- **协议模板管理**：支持多种格式的协议模板导入导出
- **协议语法验证**：提供协议语法规则验证功能

## 安装指南

### 环境要求

- Python 3.10 或更高版本
- pip 包管理器

### 安装步骤

1. 克隆项目仓库：

```bash
git clone <repository-url>
cd protocol
```

2. 创建虚拟环境（推荐）：

```bash
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate  # Windows
```

3. 安装依赖：

```bash
pip install -e .
```

## 使用方法

### 基本用法

#### 命令行接口

```bash
# 列出可用协议
protocol_fuzzer --list-protocols

# 对 HTTP 服务进行模糊测试
protocol_fuzzer --protocol=http --host=127.0.0.1 --port=8080 --connection=tcp

# 使用配置文件
protocol_fuzzer --config=config.json
```

### 配置选项

#### 命令行参数

- `--protocol`：目标协议类型（如 http）
- `--host`：目标主机地址
- `--port`：目标端口
- `--connection`：连接类型（tcp/udp/ssl）
- `--timeout`：连接超时时间（秒）
- `--sleep-time`：每次请求间的延迟（秒）
- `--restart-interval`：目标重启间隔（请求数）
- `--log-level`：日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL）
- `--log-file`：日志文件路径
- `--proc-name`：监控的进程名称
- `--proc-id`：监控的进程ID
- `--start-cmd`：目标服务启动命令
- `--stop-cmd`：目标服务停止命令

#### 配置文件

支持 JSON 或 YAML 格式的配置文件，包含上述所有选项。

## 示例

### HTTP 模糊测试示例

```bash
# 对本地运行的 HTTP 服务进行模糊测试
protocol_fuzzer --protocol=http --host=127.0.0.1 --port=8080 --connection=tcp
```

也可以参考项目中的示例文件：
- `http_fuzzer_example.py`：HTTP 协议模糊测试示例
- `tcp_fuzzer_example.py`：TCP 协议模糊测试示例

## 项目结构
protocol/
├── main.py                # 主入口文件
├── protocol_fuzzer/       # 核心代码目录
│   ├── core/              # 核心组件（会话管理、目标管理等）
│   ├── protocols/         # 协议实现
│   ├── api/               # API 接口
│   ├── models/            # 数据模型
│   └── utils/             # 工具函数
├── boofuzz/               # 修改版 Boofuzz 库
├── docs/                  # 文档
│   ├── boofuzz_extension_guide.md  # Boofuzz扩展开发指南
│   ├── README_fuzzer_examples.md   # 模糊测试示例说明
│   └── design/            # 设计文档
├── examples/              # 示例代码
├── logs/                  # 日志目录
├── results/               # 测试结果目录
└── tests/                 # 测试代码


## 扩展指南

### 添加新协议

要添加新协议支持，请参考 `docs/boofuzz_extension_guide.md` 文档，或按照以下步骤：

1. 在 `protocol_fuzzer/protocols/` 目录下创建新的协议处理类
2. 实现必要的请求模型和响应处理逻辑
3. 在 `main.py` 的 `create_protocol_handler` 函数中注册新协议

### 自定义模糊策略

可以通过继承和扩展现有类来自定义模糊测试策略：

1. 创建自定义的请求模型类
2. 实现自定义的模糊规则和数据生成逻辑
3. 在测试前添加到会话管理器

## Docker 支持

### 使用 Docker 运行

```bash
# 构建镜像
docker build -t protocol_fuzzer .

# 运行容器
docker run --network=host protocol_fuzzer --protocol=http --host=127.0.0.1 --port=8080
```

### 使用 Docker Compose

```bash
docker-compose up
```

## 测试

### 运行单元测试

```bash
pytest tests/unit/
```

### 运行集成测试

```bash
pytest tests/integration/
```

### 运行功能测试

```bash
pytest tests/functional/
```

## 最佳实践

1. **先备份**：在测试重要系统前，确保有完整备份
2. **隔离环境**：最好在隔离的测试环境中运行模糊测试
3. **逐步增加强度**：先使用较少的模糊用例，确认测试流程正常后再增加
4. **监控资源**：模糊测试可能消耗大量CPU和内存资源
5. **记录日志**：工具会自动记录测试过程，便于分析发现的问题
6. **定期检查**：长时间运行的模糊测试应定期检查是否发现问题

## 注意事项

- **安全警告**：模糊测试可能导致目标服务崩溃或数据损坏，仅在授权环境中使用
- **网络使用**：大量的模糊测试请求可能产生大量网络流量，请确保网络环境允许
- **性能考量**：某些模糊测试场景可能需要较长时间，请合理设置参数

## 许可证

MIT License

## 联系方式

Protocol Fuzzer Team
team@protocol-fuzzer.io