GheekyByt3/SPHound
GitHub: GheekyByt3/SPHound
一款用于在 SharePoint Online 中发现敏感文件的渗透测试工具，聚焦授权场景下的安全审计与数据定位。
Stars: 0 | Forks: 0
# SPHound
SPHound 是一个用于在 SharePoint Online 中查找敏感文件的渗透测试工具。它结合了快速的 KQL 查询和深度递归文件夹爬取，以暴露凭证、密钥、PII 和错误配置，然后生成干净、适合客户使用的报告。
## 功能特性
- **三种扫描模式** — `search`（快速 KQL 查询）、`crawl`（深度递归遍历）或 `both`（组合去重）
- **52 个内置搜索查询** — 覆盖凭证、密钥、配置、PII 等全面的 KQL 查询
- **四种认证方式** — 浏览器 Cookie、访问令牌、设备代码流（支持 MFA）、客户端凭据
- **双 API 支持** — Microsoft Graph API 和 SharePoint REST API，自动回退
- **双层检测** — 文件名模式匹配（28 条规则）+ 内容正则扫描（16 条规则）
- **内容检查** — 下载并扫描文件内容以查找密钥、凭证、PII（需启用 `--download`）
- **自动令牌刷新** — 长时扫描期间的静默令牌续期
- **可定制规则** — 基于 YAML 的检测规则和搜索查询，易于扩展
- **丰富报告** — 交互式 HTML、CSV 和 JSON 输出
- **速率限制处理** — 自动限流并在收到 429 响应时重试
- **实时控制台输出** — 发现即显示彩色编码的结果
## 安装
```
git clone https://github.com/GheekyByt3/SPHound.git
cd SPHound
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```
## 快速开始
### 选项 1：浏览器 Cookie（最简单）
如果你可以访问目标 SharePoint 网站：
1. 在浏览器中打开目标 SharePoint 网站
2. 按 F12 → 网络（Network）标签 → 按 `_api` 过滤
3. 在控制台（Console）标签中执行任意请求以触发网络请求
4. 点击该请求 → 请求头（Headers）→ 复制完整的 `cookie:` 值
5. 保存到文件：`cookies.txt`
```
python3 sphound.py --cookie-file cookies.txt \
--site-url "https://contoso.sharepoint.com/sites/IT" \
--mode search
```
### 选项 2：设备代码流（支持 MFA）
```
python3 sphound.py --device-code --tenant contoso.onmicrosoft.com \
--site-url "https://contoso.sharepoint.com/sites/IT" \
--mode crawl
```
会显示一个代码，需在 `microsoft.com/devicelogin` 输入。该工具会自动尝试多个 Microsoft 第一方应用 ID 和作用域组合。
### 选项 3：访问令牌
如果你拥有 Microsoft Graph 或 SharePoint API 的访问令牌：
```
python3 sphound.py --token "eyJ0eXAi..." \
--site-url "https://contoso.sharepoint.com/sites/IT" \
--mode both
```
### 选项 4：客户端凭据
如果你已获取具有 SharePoint 权限的 Azure AD 应用程序注册信息：
```
python3 sphound.py --client-id --client-secret --tenant-id \
--mode both --output ./results
```
## 扫描模式
| 模式 | 作用 | 速度 | 完整性 |
|------|------|------|--------|
| `--mode search` | 对 SharePoint 搜索 API 执行 KQL 查询 | 快速 | 查找与已知模式匹配的已索引文件 |
| `--mode crawl` | 对每个文档库进行递归文件夹遍历 | 较慢 | 查找所有可访问文件，包括未索引的 |
| `--mode both` | 搜索 + 爬取结合，结果去重 | 最慢 | 最完整 — 捕获所有内容 |
**推荐的参与工作流程：**
1. 使用 `--mode search` 进行快速表面扫描
2. 对高价值站点运行 `--mode crawl` 进行深度覆盖
3. 仅在需要对特定站点进行内容检查时使用 `--mode crawl --download`
## 使用选项
```
Authentication (choose one):
--token, -t Microsoft Graph / SharePoint API access token
--device-code Device code flow (MFA-compatible)
--client-id Azure AD application client ID
--client-secret Azure AD client secret
--tenant-id Tenant ID (for client credentials)
--tenant Tenant domain (for device code / cookies)
--cookies Browser cookies from SharePoint session
--cookie-file File containing browser cookies
Scope:
--site-url Direct SharePoint site URL to scan
--discover Auto-discover accessible sites via wordlist brute-force
--sites, -s Comma-separated site name filters
--include-onedrive Enumerate user OneDrive accounts
--max-file-size Max file size to download (default: 5)
Mode (required):
--mode, -m search, crawl, or both
--search-queries Custom KQL queries YAML
--search-limit Max results per search query (default: 500)
Detection:
--download Download files for content inspection (off by default)
--rules, -r Custom detection rules YAML
Output:
--output, -o Output directory (default: ./sphound_output)
--delay Delay between API requests (default: 0.2)
```
## 示例
```
# 快速搜索扫描（使用 Cookies）
python3 sphound.py --cookie-file cookies.txt \
--site-url "https://contoso.sharepoint.com/sites/IT" --mode search
# 深度爬取 — 仅匹配所有文件、文件名（不下载）
python3 sphound.py --cookie-file cookies.txt \
--site-url "https://contoso.sharepoint.com/sites/HR" --mode crawl
# 完整扫描并检查内容（下载文件 — 可能有噪音！）
python3 sphound.py --cookie-file cookies.txt \
--site-url "https://contoso.sharepoint.com/sites/IT" --mode crawl --download
# 搜索与爬取结合
python3 sphound.py --cookie-file cookies.txt \
--site-url "https://contoso.sharepoint.com/sites/Finance" --mode both
# 设备码流程（自定义搜索查询）
python3 sphound.py --device-code --tenant contoso.onmicrosoft.com \
--site-url "https://contoso.sharepoint.com/sites/IT" \
--mode search --search-queries custom_queries.yaml
# 自动发现所有可访问站点并进行爬取
python3 sphound.py --cookie-file cookies.txt \
--tenant contoso.onmicrosoft.com --discover --mode crawl
```
## 输出
每次运行都会创建一个带时间戳的目录，包含以下文件：
| 文件 | 描述 |
|------|------|
| `sphound_report.html` | 可交互的 HTML 报告，支持对结果排序和筛选 |
| `sphound_findings.csv` | 用于 Excel 分析的 CSV 导出 |
| `sphound_findings.json` | 包含完整元数据的机器可读 JSON |
| `downloads/` | 下载的文件（仅在使用 `--download` 时生成） |
## 检测规则
### 文件名规则（`config/rules.yaml`）
使用不区分大小写的正则表达式匹配文件名：
```
filename_rules:
- name: "KeePass Database"
pattern: '.*\.(kdbx|kdb)$'
severity: critical
description: "KeePass password database"
```
### 内容规则（`config/rules.yaml`）
匹配文件内容（需要 `--download`）：
```
content_rules:
- name: "AWS Access Key"
pattern: 'AKIA[0-9A-Z]{16}'
severity: critical
description: "AWS Access Key ID"
```
### 搜索查询（`config/search_queries.yaml`）
用于 SharePoint 搜索 API 的 KQL 查询（用于 `--mode search` 和 `--mode both`）：
```
queries:
- name: "PowerShell Credential Scripts"
kql: '(filetype:ps1) AND ("SecureString" OR "PSCredential")'
severity: critical
description: "PowerShell scripts containing credential handling"
```
52 个查询涵盖密码管理器、私钥、Web 配置、远程访问文件、部署镜像、CI/CD 密钥、数据库连接字符串（C#、Java、PHP、Python、Ruby）、内存转储、网络捕获、Shell 历史记录等。
### 严重级别（Snaffler 风格）
- **黑色（Black）** — 直接凭证暴露（密钥、密码、令牌）
- **红色（Red）** — 敏感数据文件（数据库备份、PII、密钥）
- **黄色（Yellow）** — 可能敏感（脚本、配置、财务文档）
- **绿色（Green）** — 信息性（归档文件、内部 IP）
## 架构
```
SPHound Pipeline:
Phase 1: AUTH
├── Cookies / Token / Device Code / Client Credentials
└── Auto-selects Graph API or SharePoint REST API
│
Phase 1.5: DISCOVER (optional, --discover flag)
├── Brute-force 240 common site names (/sites/ + /teams/)
└── Returns list of accessible sites to enumerate
│
Phase 2: ENUMERATE (skipped in search-only mode)
├── Discover document libraries per site
└── Graph API → REST API fallback → direct --site-url
│
Phase 3a: SEARCH (search / both mode)
├── 52 KQL queries against SharePoint Search API
└── Returns file metadata for indexed matches
│
Phase 3b: CRAWL (crawl / both mode)
├── Recursive folder walking via REST API
├── Downloads text files for content inspection (if --download)
└── Returns every accessible file
│
DEDUPLICATE (both mode only)
│
Phase 4: DETECT
├── Layer 1: Filename pattern matching (28 rules)
└── Layer 2: Content regex scanning (16 rules, requires --download)
│
Phase 5: REPORT
├── Interactive HTML with sort/filter
├── CSV for Excel analysis
└── JSON for automation
```
## 项目结构
```
SPHound/
├── sphound.py # Entry point (python3 sphound.py)
├── sphound/
│ ├── __init__.py
│ ├── __main__.py # Module entry point (python3 -m sphound)
│ ├── cli.py # CLI argument parsing and orchestration
│ └── modules/
│ ├── auth.py # Authentication (4 methods + token refresh)
│ ├── enumerator.py # Graph API site/drive discovery
│ ├── sp_enumerator.py # SharePoint REST API site/drive discovery
│ ├── crawler.py # Graph API recursive file crawler
│ ├── sp_crawler.py # SharePoint REST API recursive file crawler
│ ├── searcher.py # KQL search query engine
│ ├── discovery.py # Site brute-force discovery via wordlist
│ ├── detector.py # Filename + content detection engine
│ └── reporter.py # Report generation (HTML, CSV, JSON)
├── config/
│ ├── rules.yaml # Detection rules (28 filename + 16 content)
│ ├── search_queries.yaml # KQL search queries (52 queries)
│ └── site_wordlist.txt # 240 common site names for --discover
├── requirements.txt
├── setup.py
└── README.md
```
## 所需权限
取决于认证方式：
| 方法 | 所需权限 |
|------|----------|
| `--cookies` | 浏览器会话所拥有的全部权限 |
| `--device-code` | 委派权限：`Sites.Read.All`、`Files.Read.All`（或 `.default`） |
| `--token` | 取决于令牌作用域 |
| `--client-id/secret` | 应用程序：`Sites.Read.All`、`Files.Read.All` |
## 操作说明
- **审计日志**：所有 API 调用都会记录在 SharePoint/Azure AD 审计日志中。这是授权测试中的正常行为。
- **下载会触发告警**：`--download` 标志会触发文件下载事件，在 DLP/CASB 中可见。仅在需要时使用。
- **Cookie 过期**：浏览器 Cookie 会过期。如果扫描中途失败，请重新导出新鲜 Cookie。
- **令牌刷新**：设备代码和客户端凭据流程支持自动刷新。直接令牌（`--token`）无法刷新；超过 60 分钟的扫描可能会失败。
- **速率限制**：`--delay` 标志控制请求间隔。建议在大型环境中调大该值。
## 致谢
本工具灵感来源于 Nicolas Heiniger 的 [SnaffPoint](https://github.com/nheiniger/SnaffPoint)。SnaffPoint 率先提出了使用 SharePoint 搜索 API 结合 KQL 查询在渗透测试中查找敏感文件的概念。SPHound 在此基础上增加了递归爬取、内容检查、多种认证方式以及 Cookie 认证支持。
## 许可证
MIT 许可证。仅用于授权的安全测试，请负责任地使用。
标签：API安全, API安全, BeEF, CSV报告, HTML报告, JSON输出, JSON输出, KQL查询, MFA, Microsoft Graph API, Object Callbacks, Python, SharePoint, SharePoint REST API, YAML配置, 二进制发布, 云计算, 令牌管理, 关键词检测, 协议分析, 在线安全评估, 开源工具, 敏感文件探测, 无后门, 权限提升, 漏洞探测, 爬虫, 网络钓鱼, 自动化报告, 规则引擎, 认证绕过, 逆向工具