amirofski/github_osint
GitHub: amirofski/github_osint
一款用于在 GitHub 公开仓库中搜索和分析代码泄露、敏感凭证及危险代码模式的开源情报工具。
Stars: 1 | Forks: 0
# 🔍 GitHub OSINT 情报工具
一款强大的**开源情报 (OSINT)** 工具，用于搜索和分析 GitHub 仓库、代码模式、文件和提交记录。发现 GitHub 公开仓库中的敏感信息、安全漏洞、API 密钥、私密凭证以及危险的代码模式。
## 📋 目录
- [功能](#-features)
- [前置条件](#-prerequisites)
- [安装说明](#-installation)
- [配置](#-configuration)
- [用法](#-usage)
- [示例](#-examples)
- [高级功能](#-advanced-features)
- [输出格式](#-output-formats)
- [故障排除](#-troubleshooting)
- [项目结构](#-project-structure)
- [贡献](#-contributing)
- [许可证](#-license)
## ✨ 功能
### 🎯 核心功能
- **多源搜索**：跨代码、仓库、issue 和 commit 进行搜索
- **模式检测**：自动检测私钥、助记词、API 密钥等危险模式
- **基于文件的搜索**：按名称查找特定文件（例如 `.env`、`hardhat.config.js`、`.git`）
- **内容提取**：直接从仓库获取并分析文件内容
- **智能速率限制**：自动处理 GitHub API 的速率限制
- **状态管理**：跟踪已搜索的模式并避免重复结果
- **持续监控**：通过自动状态持久化运行持续搜索
### 📊 输出选项
- **JSON 格式**：用于程序化分析的结构化数据导出
- **CSV 格式**：兼容电子表格的数据分析导出
- **丰富元数据**：包含仓库统计信息、文件详细信息和时间戳的增强结果
### 🔐 安全功能
- 检测硬编码凭证（API 密钥、助记词、私钥）
- 识别敏感配置文件
- 搜索危险代码模式
- 跟踪仓库更新以发现新的易受攻击代码
### ⚙️ 高级选项
- 用于实时查询的交互模式
- 自动搜索所有危险模式
- 具有状态持久化的持续监控模式
- 可自定义的结果限制（每种模式最多 1,000 个）
- 可选的文件内容获取
## 📌 前置条件
在安装之前，请确保您具备：
### 必需项
- **Python 3.8 或更高版本**
- **GitHub 账户**（用于 API token）
- **互联网连接**（用于访问 GitHub API）
### 推荐项
- Git（用于克隆仓库）
- pip（通常随 Python 一起提供）
- 虚拟环境（用于隔离依赖项）
## 🚀 安装说明
### 第 1 步：安装 Python
#### **Windows**
1. 从 [python.org](https://www.python.org/downloads/) 下载 Python
2. 运行安装程序
3. ✅ **重要**：在安装过程中勾选“Add Python to PATH”
4. 点击“Install Now”
5. 验证安装：
python --version
pip --version
#### **macOS**
使用 Homebrew（推荐）：
```
brew install python3
```
或者从 [python.org](https://www.python.org/downloads/) 下载
验证安装：
```
python3 --version
pip3 --version
```
#### **Linux (Ubuntu/Debian)**
```
sudo apt update
sudo apt install python3 python3-pip python3-venv -y
python3 --version
pip3 --version
```
#### **Linux (Fedora/RHEL)**
```
sudo dnf install python3 python3-pip -y
python3 --version
pip3 --version
```
### 第 2 步：克隆仓库
```
# 使用 Git
git clone https://github.com/amirofski/github_osint.git
cd github_osint
# 或者下载 ZIP 文件并解压
```
### 第 3 步：创建虚拟环境（推荐）
#### **Windows**
```
python -m venv venv
venv\Scripts\activate
```
#### **macOS/Linux**
```
python3 -m venv venv
source venv/bin/activate
```
激活后，您的终端应显示 `(venv)` 前缀。
### 第 4 步：安装依赖项
```
pip install -r requirements.txt
```
这将安装：
- `requests` - 用于 API 调用的 HTTP 库
- `python-dotenv` - 环境变量管理
### 第 5 步：获取 GitHub API Token
1. 前往 [GitHub Settings - Personal Access Tokens](https://github.com/settings/tokens)
2. 点击“Generate new token (classic)”
3. 为其起一个描述性的名称（例如，“OSINT Tool”）
4. 选择权限范围：
- ✅ `public_repo` - 访问公开仓库
- ✅ `read:user` - 读取用户数据
5. 点击“Generate token”
6. **立即复制 token**（您将无法再次看到它）
### 第 6 步：配置环境变量
在项目根目录下创建一个 `.env` 文件：
```
# Windows
echo GITHUB_TOKEN=your_token_here > .env
echo OUTPUT_FORMAT=json >> .env
echo OUTPUT_FILE=results.json >> .env
# macOS/Linux
cat > .env << EOF
GITHUB_TOKEN=your_token_here
OUTPUT_FORMAT=json
OUTPUT_FILE=results.json
EOF
```
**将 `your_token_here` 替换为您的实际 GitHub token**
或者手动创建 `.env` 并填入以下内容：
```
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
OUTPUT_FORMAT=json
OUTPUT_FILE=results.json
```
## ⚙️ 配置
### 环境变量
| 变量 | 描述 | 默认值 | 示例 |
|----------|-------------|---------|---------|
| `GITHUB_TOKEN` | GitHub API token（必需） | None | `ghp_xxx...` |
| `OUTPUT_FORMAT` | 输出文件格式 | `json` | `json` 或 `csv` |
| `OUTPUT_FILE` | 默认输出文件名 | 自动生成 | `results.json` |
## 📖 用法
### **交互模式**
最适合探索和测试查询：
```
python main.py --interactive
```
交互命令：
- 直接输入搜索查询
- 使用 `auto` 搜索所有危险模式
- 使用 `exit`、`quit` 或 `q` 退出
- 自定义结果限制、格式和内容获取
### **CLI 模式 - 基本搜索**
搜索特定模式：
```
# 搜索私钥
python main.py "privateKey"
# 搜索特定文件
python main.py filename:hardhat.config.js
# 使用自定义最大结果数进行搜索
python main.py "mnemonic" --max-results 500
# 输出到 CSV
python main.py "alchemy" --format csv --output results.csv
```
### **CLI 模式 - 自动搜索**
自动搜索所有危险模式：
```
# 单次运行
python main.py --auto
# 使用自定义设置
python main.py --auto --max-results 200 --format csv --output danger.csv
# 跳过文件内容获取（更快）
python main.py --auto --no-fetch-content
```
### **持续监控模式**
持续搜索并跟踪新结果：
```
# 启动持续监控
python main.py --auto --continuous --output ongoing_results.json
# 使用 state file 实现持久化
python main.py --auto --continuous --state-file my_state.json --output results.json
```
按 `Ctrl+C` 停止持续模式。
## 💡 示例
### 示例 1：搜索硬编码的 API 密钥
```
python main.py "infura" --max-results 100 --format json --output infura_keys.json
```
**输出**：包含“infura”的所有仓库及其文件内容和元数据。
### 示例 2：查找环境配置文件
```
python main.py filename:.env --max-results 500
```
**输出**：在 GitHub 上公开找到的所有 `.env` 文件。
### 示例 3：搜索私钥模式
```
python main.py "-----BEGIN PRIVATE KEY-----" --max-results 200 --output pem_keys.csv --format csv
```
### 示例 4：综合模式检测
```
python main.py --auto --continuous \
--max-results 100 \
--format json \
--output comprehensive_scan.json \
--state-file tracking.json
```
### 示例 5：具有自定义功能的交互式会话
```
python main.py --interactive
```
然后进行交互：
```
Enter search query: filename:hardhat.config.js
Max results (default 100, max 1000): 50
Fetch file content? (y/n, default: y): y
Output format (json/csv, default: json): json
```
## 🔧 高级功能
### 状态管理
跟踪您已经搜索过的内容以避免重复：
```
python main.py --auto --continuous \
--state-file github_intel_state.json \
--output results.json
```
**状态文件跟踪**：
- 已搜索的模式
- 最后处理的页面
- 最后的结果时间
- 已见的唯一仓库
### 速率限制处理
该工具会自动管理 GitHub API 速率限制：
- **已认证**：每小时 5,000 次请求
- **未认证**：每小时 60 次请求（不推荐）
- 接近限制时自动等待
- 优雅处理速率限制重置
### 内容获取控制
```
# 获取内容（默认）- 数据更多，速度较慢
python main.py "privateKey"
# 跳过内容 - 更快，仅包含基本信息
python main.py "privateKey" --no-fetch-content
```
## 📊 输出格式
### JSON 格式（默认）
```
[
{
"search_type": "code",
"repository": {
"name": "example-repo",
"owner": "username",
"full_name": "username/example-repo",
"url": "https://github.com/username/example-repo",
"stars": 150,
"forks": 45,
"language": "JavaScript",
"updated_at": "2024-01-15T10:30:00Z"
},
"file": {
"name": ".env",
"path": ".env",
"url": "https://github.com/username/example-repo/blob/main/.env",
"sha": "abc123...",
"content": "PRIVATE_KEY=0x1234567890..."
},
"matched_pattern": "filename:.env"
}
]
```
### CSV 格式
```
search_type,repo_owner,repo_name,file_name,file_path,file_url,repo_url,content,matched_pattern
code,username,example-repo,.env,.env,https://...,https://...,PRIVATE_KEY=0x...,filename:.env
```
## 🐛 故障排除
### ❌ 错误：“GITHUB_TOKEN environment variable is required”
**解决方案**：
```
# 使用你的 token 创建 .env 文件
echo GITHUB_TOKEN=your_token_here > .env
# 或者直接设置环境变量
# Windows
set GITHUB_TOKEN=your_token_here
python main.py --auto
# macOS/Linux
export GITHUB_TOKEN=your_token_here
python main.py --auto
```
### ❌ 错误：“Rate limit exceeded”
**解决方案**：该工具会自动等待，但您可以：
1. 使用较少的结果：`--max-results 50`
2. 使用 `--no-fetch-content` 减少 API 调用
3. 等待 1 小时重置速率限制
4. 使用具有更高速率限制的 token
### ❌ 错误：“No module named 'requests'”
**解决方案**：
```
pip install -r requirements.txt
```
### ❌ 错误：“ModuleNotFoundError: No module named 'dotenv'”
**解决方案**：
```
pip install python-dotenv
# 或重新安装所有
pip install -r requirements.txt
```
### ❌ 错误：“Invalid query format”
**解决方案**：使用正确的 GitHub 搜索语法：
```
# ✅ 正确
python main.py "privateKey"
python main.py filename:hardhat.config.js
python main.py filename:.env
# ❌ 避免
python main.py "user@email.com" # Special characters need escaping
```
### ❌ 错误：“Connection timeout”
**解决方案**：
1. 检查互联网连接
2. GitHub API 可能已宕机
3. 稍后重试
4. 使用 `--no-fetch-content` 减少耗时
## 📁 项目结构
```
github_osint/
├── main.py # Main entry point, CLI interface
├── github_client.py # GitHub API interaction
├── search_engine.py # Search logic and pattern matching
├── config.py # Configuration and constants
├── patterns.py # Dangerous patterns definition
├── output_handler.py # Result export (JSON/CSV)
├── state_manager.py # State persistence for tracking
├── extractor.py # Data extraction utilities
├── requirements.txt # Python dependencies
├── .env # Environment variables (create locally)
└── README.md # This file
```
## 🤝 贡献
欢迎任何贡献！可以改进的领域：
- [ ] 添加更多危险模式
- [ ] 支持额外的输出格式（XML、SQLite）
- [ ] 代理支持
- [ ] 数据库集成
- [ ] Web UI
- [ ] 结果过滤和分析
## 📝 许可证
本项目仅供教育和安全研究目的使用。
**免责声明**：负责任地使用，并且仅在您拥有权限的仓库上使用。未经授权访问计算机系统是违法行为。
## ⚠️ 法律与道德声明
- **仅供教育用途**：此工具专为安全研究人员和授权的渗透测试而设计。
- **合法合规**：仅搜索公开仓库并确保您已获得授权。
- **负责任的披露**：如果您发现真实的漏洞，请向相关方报告。
- **无担保**：使用风险自负。作者不承担任何责任。
## 🔗 快速链接
- [GitHub API 文档](https://docs.github.com/en/rest)
- [GitHub Token 设置](https://github.com/settings/tokens)
- [GitHub 搜索语法](https://docs.github.com/en/search-github/searching-on-github/searching-code)
## 📞 支持
如遇问题和疑问：
1. 查看上方的**故障排除**部分
2. 查看 GitHub Issues
3. 查看现有文档
4. 创建一个包含详细信息的新 issue
## 🙏 致谢
专为安全研究人员和开源社区打造，用于发现和修复公开共享代码中的漏洞。
**最后更新**：2026 年 1 月
**版本**：1.0.0
**作者**：amirofski
标签：ESC4, OSINT, StruQ, 字符串匹配, 安全助手, 逆向工具