smirnoffmg/deeper
GitHub: smirnoffmg/deeper
Deeper 是一款基于模块化插件架构的 OSINT 信息收集工具，通过 trace 追踪机制从多种在线来源自动发现并关联开源情报。
Stars: 3 | Forks: 1
# 深入
```
██████ ███████ ███████ ██████ ███████ ██████
██ ██ ██ ██ ██ ██ ██ ██ ██
██ ██ █████ █████ ██████ █████ ██████
██ ██ ██ ██ ██ ██ ██ ██
██████ ███████ ███████ ██ ███████ ██ ██
```
Deeper 是一款 OSINT（开源情报）工具，旨在帮助用户从各种在线来源收集信息。该工具基于“traces”（痕迹）的概念运行。每个 trace 代表一条信息，例如电子邮件、电话号码、域名或用户名。该工具利用插件来追踪这些 trace，并在此过程中发现新的 trace。每个插件专门处理特定类型的 trace，并根据输入生成新的 trace。这种模块化的方式使得该工具易于扩展和定制，以满足各种 OSINT 需求。
## 🚀 功能特性
- **模块化插件架构**：易于通过新插件进行扩展
- **并发处理**：高效的并行 trace 处理
- **全面的错误处理**：结构化的错误类型和日志记录
- **配置管理**：基于环境变量的配置
- **测试覆盖率**：全面的单元测试
- **速率限制**：内置 HTTP 速率限制和重试逻辑
- **结构化日志**：基于 JSON 且支持可配置级别的日志记录
## 🏗️ 架构
该项目遵循 SOLID 原则和整洁架构模式：
### 核心组件
- **Engine**：统筹 trace 处理工作流
- **Processor**：通过插件处理并发 trace 处理
- **Display**：管理结果的呈现和格式化
- **Config**：集中的配置管理
- **Errors**：结构化的错误处理和类型
- **HTTP**：带有重试逻辑和速率限制的共享 HTTP client
### 插件系统
插件实现了 `DeeperPlugin` 接口，并会被自动发现和注册。每个插件专门处理特定的 trace 类型，并可以生成新的 trace。
## 📦 安装说明
### 前置条件
- Go 1.26 或更高版本
- Git
### 从源码构建
```
# Clone 仓库
git clone https://github.com/smirnoffmg/deeper.git
cd deeper
# 安装 dependencies
make deps
# Build application
make build
# 运行 application
./build/deeper
```
### 快速开始
```
# 使用默认 input 运行
make run
# 使用自定义 input 运行
make run-custom INPUT=your_input_here
# 以 development mode 和 hot reload 运行
make dev
```
## ⚙️ 配置
Deeper 使用环境变量进行配置：
| 变量 | 默认值 | 描述 |
| ------------------------ | ------------ | ---------------------------------------- |
| `DEEPER_HTTP_TIMEOUT` | `30s` | HTTP 请求超时时间 |
| `DEEPER_MAX_CONCURRENCY` | `10` | 最大并发操作数 |
| `DEEPER_RATE_LIMIT` | `5` | 每秒请求数 |
| `DEEPER_LOG_LEVEL` | `info` | 日志级别 (debug, info, warn, error) |
| `DEEPER_USER_AGENT` | `Deeper/1.0` | HTTP 请求的 User Agent |
| `DEEPER_MAX_RETRIES` | `3` | 最大重试次数 |
| `DEEPER_RETRY_DELAY` | `1s` | 重试之间的延迟时间 |
示例：
```
export DEEPER_LOG_LEVEL=debug
export DEEPER_MAX_CONCURRENCY=20
./deeper username
```
## 🧪 测试
该项目包含全面的测试覆盖：
```
# 运行所有 tests
make test
# 运行 tests 并生成 coverage report
make test-coverage
# 运行 tests 并开启 race detector
make test-race
# 运行 benchmarks
make benchmark
```
## 🔧 开发
### 项目结构
```
deeper/
├── cmd/
│ └── deeper/
│ └── main.go # Application entry point
├── internal/
│ ├── app/deeper/
│ │ ├── cli/ # Cobra CLI commands (scan, plugins, health, …)
│ │ ├── display/ # Result presentation
│ │ ├── engine/ # Core orchestration
│ │ └── processor/ # Trace processing and worker pool integration
│ └── pkg/
│ ├── config/ # Configuration management
│ ├── database/ # SQLite storage and caching
│ ├── entities/ # Data models and validation
│ ├── errors/ # Structured error handling
│ ├── http/ # HTTP client utilities
│ ├── metrics/ # Performance monitoring
│ ├── plugins/ # Plugin implementations
│ ├── state/ # Global plugin registry
│ └── workerpool/ # Concurrent task processing
├── configs/ # Default configuration
├── docs/ # Documentation and diagrams
├── Makefile # Build and development tasks
└── README.md # This file
```
### 添加新插件
1. 在 `internal/pkg/plugins/` 中创建一个新目录
2. 实现 `DeeperPlugin` 接口：
```
package your_plugin
import (
"github.com/smirnoffmg/deeper/internal/pkg/entities"
"github.com/smirnoffmg/deeper/internal/pkg/state"
)
const InputTraceType = entities.Username
func init() {
p := NewPlugin()
if err := p.Register(); err != nil {
log.Error().Err(err).Msgf("Failed to register plugin %s", p)
}
}
type YourPlugin struct{}
func NewPlugin() *YourPlugin {
return &YourPlugin{}
}
func (p *YourPlugin) Register() error {
state.RegisterPlugin(InputTraceType, p)
return nil
}
func (p *YourPlugin) FollowTrace(trace entities.Trace) ([]entities.Trace, error) {
if trace.Type != InputTraceType {
return nil, nil
}
// Your plugin logic here
var newTraces []entities.Trace
// ... process trace and generate new traces
return newTraces, nil
}
func (p *YourPlugin) String() string {
return "YourPlugin"
}
```
3. 在 `cmd/deeper/main.go` 中导入该插件：
```
_ "github.com/smirnoffmg/deeper/internal/pkg/plugins/your_plugin"
```
### 开发命令
```
# Format code
make fmt
# 运行 linter
make lint
# 为 testing 生成 mocks
make mocks
# 运行 security scan
make security
# 显示所有可用命令
make help
```
## 🔒 安全
该项目包含多项安全特性：
- **输入验证**：对所有输入进行全面验证
- **速率限制**：防止滥用外部 API
- **错误处理**：安全的错误消息，防止信息泄露
- **安全扫描**：使用 gosec 进行自动化安全检查
## 📊 性能
- **并发处理**：高效的并行执行
- **连接池**：可重用的 HTTP 连接
- **内存管理**：适当的资源清理
- **批处理**：针对大型数据集的可配置批处理大小
## 📝 许可证
该项目基于 MIT 许可证授权 - 详情请参阅 [LICENSE](LICENSE) 文件。
## 🆘 支持
- **Issues**：在 GitHub 上报告 bug 和功能请求
- **Discussions**：加入社区讨论
- **文档**：查看 [docs](docs/) 目录获取详细文档
## 🔄 更新日志
### v1.0.0（当前版本）
- ✅ 模块化插件架构
- ✅ 并发 trace 处理
- ✅ 全面的错误处理
- ✅ 配置管理
- ✅ 测试覆盖
- ✅ 速率限制和重试逻辑
- ✅ 结构化日志
- ✅ 安全性改进
## 📈 路线图
- [x] 带有子命令的 CLI 框架（`scan`, `plugins`, `health`, `metrics`, `database`, `rate-limit`, `benchmark`）
- [ ] 插件生命周期管理
- [x] 指标与监控
- [x] 用于 trace 存储的数据库集成
- [ ] Web 界面
- [ ] API 服务器模式
- [ ] 插件市场
- [ ] 高级过滤和搜索
- [ ] 导出功能（JSON, CSV 等）
- [ ] 与外部 OSINT 工具的集成
**注意**：该工具专为合法的 OSINT 研究和安全测试而设计。在将其用于您不拥有的任何系统或网络之前，请确保您已获得适当的授权。
标签：ESC4, EVTX分析, Go, OSINT, Retryablehttp, Ruby工具, 信息搜集, 实时处理, 开源情报收集, 插件化架构, 日志审计