TorBot

<pre>

                         ████████╗ ██████╗ ██████╗     ██████╗  ██████╗ ████████╗
                         ╚══██╔══╝██╔═══██╗██╔══██╗    ██╔══██╗██╔═████╗╚══██╔══╝
                            ██║   ██║   ██║██████╔╝    ██████╔╝██║██╔██║   ██║
                            ██║   ██║   ██║██╔══██╗    ██╔══██╗████╔╝██║   ██║
                            ██║   ╚██████╔╝██║  ██║    ██████╔╝╚██████╔╝   ██║
                            ╚═╝    ╚═════╝ ╚═╝  ╚═╝    ╚═════╝  ╚═════╝    ╚═╝

                            暗网开源情报工具

</pre>

<p align="center">
   <a href="https://owasp.org/www-project-torbot/">
    <img src="https://assets.kitploit.com/production/public/readmes/58461/8902e5836a324eae0ab281a9be7d62683e025d503ce6778cce6768fb908c1089/44f87cefbeddabc12e5302f46a08c8c511e4ec48c814d7fbb70dc1c317e73552-display-v1.webp" width="270" title="OWASP 基金会">
   </a>
   <img src="https://assets.kitploit.com/production/public/readmes/58461/1cc64251df7a699491fb27a2d732f724bf9fe989efb8dd3f7fe750e316f2b333/2a88ed821677ed3b033b12c0815ff31e60d4e86357dbbfc127253fe018096b96-display-v1.webp" width="250" title="Hacktoberfest 2022">
   <img src="https://assets.kitploit.com/production/public/readmes/58461/54bda09bea5708a8bec2bc836b8decebec80caecd37906f84e76799af642bb6a/159aa0dc48e84a932700c3326470bd3053551554561821e67f78d3db2982e745-display-v1.webp" width="160" title="开源">
</p>


### 状态/社交链接
[![Pytest](https://github.com/DedSecInside/TorBot/actions/workflows/pytest.yml/badge.svg)](https://github.com/DedSecInside/TorBot/actions/workflows/pytest.yml)
[![Flake8](https://github.com/DedSecInside/TorBot/actions/workflows/flake8.yml/badge.svg?branch=dev)](https://github.com/DedSecInside/TorBot/actions/workflows/flake8.yml)
[![Slack Invite](https://img.shields.io/badge/Join-Slack-informational?style=flat-square&logo=slack)](https://join.slack.com/t/dedsec-inside/shared_invite/zt-i4jcgj8w-1ecHiSdRubwuppAzz8~yfg)
[![Code Triage](https://www.codetriage.com/dedsecinside/torbot/badges/users.svg)](https://www.codetriage.com/dedsecinside/torbot)
[![](https://img.shields.io/badge/Built%20with-%E2%9D%A4-orange.svg?style=flat-square)]()
[![](https://img.shields.io/badge/Made%20with-Python-red.svg?style=flat-square)]()

### 功能特性
1. Onion 爬虫（.onion）
2. 返回页面标题，若无页面标题则返回主机名，并附带地址及站点简短描述。
3. 将链接保存到数据库（未完成）
4. 输出站点的 HTML 或将其保存为 HTML 文件。（未完成）
5. 将链接树保存为 JSON 文件。
6. 爬取自定义域名
7. 检查链接是否存活
8. 内置更新器
9. 构建链接关系的可视化树，可快速查看或保存到文件

### 近期改进
- CLI 现在允许 `--version` 和 `--update` 在无需提供 URL 的情况下运行。
- 爬虫现在会基于当前页面解析相对链接，并更优雅地跳过不支持或格式错误的 href。
- 可选的 TorBotApp 桌面 UI 在作为同级检出安装时，可通过 CLI 使用 `torbot app` 启动。

...(将更新)

### 依赖项
- Tor（可选）
- Python 3.10+
- pip

## 快速开始

### 本地安装
```sh
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip install -e .
```

### 使用 OTinstaller 安装（Linux）
[OTinstaller](https://github.com/OSINTVerseHQ/OTinstaller) 是一个第三方工具管理器，它会将 `torbot` 的 PyPI 发行版安装到其独立的 virtualenv 中。它不由 TorBot 团队维护，因此请[在 OTinstaller 的问题跟踪器上](https://github.com/OSINTVerseHQ/OTinstaller/issues)报告与其相关的问题。
```sh
pipx install otinstaller
otinstaller init
otinstaller install torbot
# url:... is passed to TorBot as -u; the other flags go through unchanged
otinstaller run torbot -- url:https://example.com --depth 2 --visualize table
```

### 运行 CLI
```sh
python main.py --help
python main.py --version
python main.py -u https://example.com --depth 2 --visualize table
```

### 常见示例
```sh
# Gather basic site information
python main.py -u https://example.com --info

# Save the crawl tree as JSON
python main.py -u https://example.com --depth 2 --save json

# Disable SOCKS5 if you are not using Tor locally
python main.py -u https://example.com --disable-socks5 --visualize tree

# Launch the optional desktop app when TorBotApp is installed
torbot app
```

### 证据优先的 AI 分析

保存带版本号的爬取结果，并将其转化为带引用的调查包：

```sh
torbot --url https://example.com --disable-socks5 \
  --save result --result-file crawl-result.json
torbot analyze crawl-result.json --provider ollama --model qwen3 \
  --output investigation/
```

Analyst 默认使用本地 Ollama 端点。远程 OpenAI 兼容提供商需要显式指定 `--allow-remote` 标志。每个受支持的发现都必须引用已捕获的证据，并且提供商故障绝不会阻止确定性证据包的写入。有关离线快速入门、输出格式、隐私边界和 schema，请参阅 [TorBot Analyst](https://github.com/dedsecinside/torbot/blob/dev/docs/ANALYST.md)。

### 选项
```text
usage: Gather and analyze data from Tor sites.

optional arguments:
  -u URL, --url URL     Specify a website link to crawl
  --depth DEPTH         Specify max depth of crawler (default 1)
  -h, --help            Show this help message and exit
  --host                Set IP address for SOCKS5 proxy (defaults to 127.0.0.1)
  --port                Set port for SOCKS5 proxy (defaults to 9050)
  -v                    Displays DEBUG level logging, default is INFO
  --version             Show the current version of TorBot.
  --update              Update TorBot to the latest stable version
  --app                 Run optional TorBot desktop app
  --app-dir APP_DIR     Path to a TorBotApp checkout
  -q, --quiet           Prevents display of header and IP address
  --save FORMAT         Save results in a file. (tree, JSON)
  --visualize FORMAT    Visualizes tree of data gathered. (tree, JSON, table)
  -i, --info            Info displays basic info of the scanned site
  --disable-socks5      Executes HTTP requests without using SOCKS5 proxy
```

> `-u/--url` 对于 `--info`、`--save` 和 `--visualize` 等与爬取相关的命令是必需的。

如果你在本地使用 Tor，请保持 SOCKS5 代理启用。如果你不使用 Tor，请添加 `--disable-socks5` 以避免代理连接错误。

在此处阅读有关 torrc 的更多信息：[Torrc](https://github.com/DedSecInside/TorBoT/blob/master/Tor.md)

## 可选的桌面应用

TorBot 仍然是一个以 CLI 为先的 Python 工具。桌面 UI 位于单独的
[TorBotApp](https://github.com/KingAkeem/TorBotApp) Electron 项目中，因此 CLI 用户
不需要 Node 和 Electron。

要从此 CLI 启动它，请将 TorBotApp 安装为同级检出：

```text
code/
+-- TorBot/
+-- TorBotApp/
```

然后运行：

```sh
torbot app
```

如果 TorBotApp 位于其他位置，请使用以下任一方式：

```sh
TORBOT_APP_DIR=/path/to/TorBotApp torbot app
torbot --app --app-dir /path/to/TorBotApp
```

有关 CLI、可选 UI 和后端服务如何协同工作，请参阅 [桌面应用架构](https://github.com/dedsecinside/torbot/blob/dev/docs/DESKTOP_APP.md)。

## 精选功能
- [x] 可视化模块重构
- [x] 为网络爬虫实现 BFS 搜索
- [x] 提升稳定性（优雅地处理错误、扩大测试覆盖范围等）
- [x] 提高测试覆盖率
- [ ] 将最近的搜索结果保存到数据库
- [ ] 随机化 Tor 连接（随机请求头和身份）
- [ ] 关键词/短语搜索
- [ ] 社交媒体集成
- [ ] 增强匿名性
- [ ] 截图捕获


## 贡献指南

### 发现了问题？

如果您在项目中遇到任何问题，请通过[此处](https://github.com/DedSecInside/TorBot/issues/new/choose)创建新 issue 告知我们。

### 开发者指南

我们欢迎对本项目的贡献！以下是需要遵循的几条指南：

1. Fork 仓库并为您的贡献创建一个新分支。
2. 在向 `dev` 分支提交 pull request 之前，请运行 `pytest` 确保您的代码通过所有测试。
3. 遵循 Python 代码的 [PEP8](https://www.python.org/dev/peps/pep-0008/) 风格指南。
4. 请务必为任何新功能或更改添加适当的文档。
5. 提交 pull request 时，请提供所做更改的详细描述。

## 参考资料

    1.  M. Glassman 和 M. J. Kang，“Intelligence in the internet age: The emergence and evolution of Open Source Intelligence (OSINT),” Comput. Human Behav., vol. 28, no. 2, pp. 673–682, 2012.
    2.  D. Bradbury，“In plain view: open source intelligence,” Comput. Fraud Secur., vol. 2011, no. 4, pp. 5–9, 2011.
    3.  B. Butler、B. Wardman 和 N. Pratt，“REAPER: an automated, scalable solution for mass credential harvesting and OSINT,” 2016 APWG Symp. Electron. Crime Res., pp. 1–10, 2016.
    4.  B. Zantout 和 R. A. Haraty，“I2P Data Communication System I2P Data Communication System,” no. April 2002, 2014.
    5.  J. Qin、Y. Zhou、G. Lai、E. Reid、M. Sageman 和 H. Chen，“The dark web portal project: collecting and analyzing the presence of terrorist groups on the web,” in Proceedings of the 2005 IEEE international conference on Intelligence and Security Informatics, 2005, pp. 623–624.
    6.  D. Moore、T. Rid、D. Moore 和 T. Rid，“Cryptopolitik and the Darknet Cryptopolitik and the Darknet,” vol. 6338, 2016.
    7.  G. Weimann，“Going dark: Terrorism on the dark Web,” Stud. Confl. Terror., vol. 39, no. 3, pp. 195–206, 2016.
    8.  A. T. Zulkarnine、R. Frank、B. Monk、J. Mitchell 和 G. Davies，“Surfacing collaborated networks in dark web to find illicit and criminal content,” in Intelligence and Security Informatics (ISI), 2016 IEEE Conference on, 2016, pp. 109–114.
    9.  T. Minárik 和 A.-M. Osula，“Tor does not stink: Use and abuse of the Tor anonymity network from the perspective of law,” Comput. Law Secur. Rev., vol. 32, no. 1, pp. 111–127, 2016.
    10. K. Loesing、S. J. Murdoch 和 R. Dingledine，“A Case Study on Measuring Statistical Data in the {T}or Anonymity Network,” in Proceedings of the Workshop on Ethics in Computer Security Research (WECSR 2010), 2010.
    11. B. Nafziger，“Data Mining in the Dark : Darknet Intelligence Automation,” 2017.
    12. I. Sanchez-Rola、D. Balzarotti 和 I. Santos，“The onions have eyes: A comprehensive structure and privacy analysis of tor hidden services,” in Proceedings of the 26th International Conference on World Wide Web, 2017, pp. 1251–1260.
    13. Mouli VR, Jevitha KP. “Web Services Attacks and Security-A Systematic Literature Review.”, Procedia Computer Science. 2016 Jan 1;93:870-7.
    14. Cova M, Felmetsger V, Vigna G. "Vulnerability analysis of web-based applications. InTest and Analysis of Web Services" 2007 (pp. 363-394). Springer, Berlin, Heidelberg.
    15. B. R. Holland，“Enabling Open Source Intelligence (OSINT) in private social networks,” 2012.
    16. S. Nakamoto，“Bitcoin: A Peer-to-Peer Electronic Cash System,” Cryptogr. Mail. List https//metzdowd.com, 2009.
    17. M. Wesam、A. Nabki、E. Fidalgo、E. Alegre 和 I. De Paz，“Classifying Illegal Activities on Tor Network Based on Web Textual Contents”, vol. 1, pp. 35–43, 2017.
    18. Sathyadevan S, Gangadharan S.“Crime analysis and prediction using data mining”. In Networks & Soft Computing (ICNSC), 2014 First International Conference on 2014 Aug 19 (pp. 406-412). IEEE.
    19. Chau M, Chen H. "A machine learning approach to web page filtering using content and structure analysis. Decision Support Systems." 2008 Jan 1;44(2):482-94.
    20. Ani R, Jose J, Wilson M, Deepa OS. “Modified Rotation Forest Ensemble Classifier for Medical Diagnosis in Decision Support Systems”, In Progress in Advanced Computing and Intelligent Engineering 2018 (pp. 137-146). Springer, Singapore.
    21. Ani R, Augustine A, Akhil N.C. 和 Deepa O.S., 2016. “Random Forest Ensemble Classifier to Predict the Coronary Heart Disease Using Risk Factors”, In Proceedings of the International Conference on Soft Computing Systems (pp. 701-710). Springer, New Delhi.


## 维护者

- [X] [PS Narayanan](https://github.com/PSNAppz) - 共同所有者
- [X] [KingAkeem](https://github.com/KingAkeem) - 共同所有者

## 衷心感谢我们的贡献者

<a href="https://github.com/DedSecInside/TorBot/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=DedSecInside/TorBot" />
</a>

## 许可证
[GNU 公共许可证](https://github.com/DedSecInside/TorBot/blob/dev/LICENSE.md)