FineYoungCannibals/trawler

# Trawler ### 一款用于筛选数据转储的终端 TUI —— 将文件放入目录，快速搜索，上报重要内容。 Trawler 为您提供键盘驱动的界面，无需搭建任何基础设施，即可在泄露数据、漏洞和其他非结构化转储中运行 regex、ripgrep、YARA 和语义向量搜索。 ## 功能特性 - **Regex 搜索** —— 对所有文件进行逐行模式匹配 - **Ripgrep** —— 使用 ripgrep 标志进行快速全文搜索 - **YARA 规则** —— 根据 `src/trawler/rules/` 中的规则扫描文件 - **语义搜索** —— 通过 ChromaDB + sentence-transformers 进行向量相似度搜索（本地运行，无需 API key） - **增量索引** —— 仅重新嵌入自上次运行以来发生变化的文件 - **文件类型与大小过滤** —— 在索引前跳过二进制、结构化或超大文件 - **Tab 路径补全** —— 在命令栏中直接补全目录路径 - **剪贴板导出** —— `ctrl+y` 将所有结果复制到剪贴板 ## 环境要求 - Python 3.10+ - [uv](https://github.com/astral-sh/uv) - macOS / Linux（剪贴板导出在 macOS 上使用 `pbcopy`） ## 安装 ``` git clone https://github.com/FineYoungCannibals/trawler cd trawler uv sync ``` ## 运行 ``` uv run python main.py ``` ## 命令 | 命令 | 描述 | |---------|-------------| | `/search ` | 对所有配置的目录进行 Regex 搜索 | | `/rg [opts] ` | Ripgrep 搜索（支持 `-i`, `-m` 标志） | | `/yara [rule-glob]` | 运行 YARA 规则；glob 按规则名称过滤（例如 `email*`） | | `/semantic [--dir ]` | 向量相似度搜索；`--dir` 限定为某一目录 | | `/index` | 将配置的目录嵌入并索引到 ChromaDB | | `/config [subcommand]` | 管理配置 —— 不带参数运行可查看所有选项 | | `/reset` | 清除向量存储和索引历史（需要确认） | | `/help` | 显示命令参考 | | `/exit` | 退出 | ### 配置子命令 ``` /config show full configuration summary /config add add a watched directory (Tab completes the path) /config rm remove a watched directory /config filesize set max file size for indexing (e.g. 500KB, 2MB, 0=unlimited) /config ext list show extension whitelist and skiplist /config ext add <.ext> whitelist an extension for indexing /config ext rm <.ext> move an extension to the skiplist /config ext reset reset extensions to defaults /config rules set a custom YARA rules directory /config rules reset revert to the bundled rules directory /config proxy set HTTP/HTTPS proxy (e.g. http://proxy.corp.com:8080) /config proxy reset clear proxy setting ``` ### 键盘快捷键 | 按键 | 动作 | |-----|--------| | `Tab` | 接受自动补全建议 | | `ctrl+y` | 复制结果到剪贴板 | | `ctrl+c` | 退出（如果正在索引则取消） | | `Enter` (空输入) | 返回主屏幕 | ## 配置 配置存储在工作目录下的 `.trawler/config.toml` 中。所有数据（配置、索引状态、向量存储）均位于项目本地并被 gitignore 忽略。 **文件大小限制** —— 首次运行 `/index` 时，系统会提示您设置最大文件大小。大文件会显著减慢嵌入速度。对于文本内容，500 KB 是一个合理的默认值。 **扩展名白名单** —— 首次索引时，任何未知文件类型都会触发提示，询问是否包含它们。您可以随时使用 `/config ext add/rm` 调整白名单。 ### 默认索引的扩展名 `.txt` `.md` `.rst` `.text` `.html` `.htm` `.eml` `.mbox` `.log` ### 默认跳过的扩展名 二进制文件、结构化数据、归档文件、图像、音频、视频 —— 所有无法产生有用语义内容的文件。 ## YARA 规则 默认情况下，规则从 `src/trawler/rules/` 加载（与包捆绑）。您可以通过 `/config rules ` 指向自己的规则目录，该设置会跨会话保留。运行 `/config rules reset` 可恢复默认设置。 将 `.yar` 或 `.yara` 文件放在您的规则目录中 —— 它们都会在每次 `/yara` 调用时被编译并运行。 `src/trawler/rules/example.yar` 中包含了一个示例规则，涵盖电子邮件地址和凭据模式。 ``` rule email_address { strings: $email = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/ condition: $email } ``` 使用 glob 按规则名称过滤：`/yara email*` 仅运行名称以 `email` 开头的规则。 ## 语义搜索 语义搜索使用 [sentence-transformers](https://www.sbert.net/) 在本地嵌入文件内容，并将向量存储在 ChromaDB 中。数据不会离开您的机器。 **模型**：默认为 `all-MiniLM-L6-v2`（快速，约 80 MB）。可通过 `/config` 更改 → 编辑 `.trawler/config.toml` 中的 `embedding_model`。 **设备**：MPS (Apple Silicon) → CUDA → CPU，自动检测。 **适用场景**：语义搜索最适合自然语言内容（电子邮件、日志、笔记）。它不太适合结构化数据（JSON, CSV, SQL） —— 这类数据请使用 `/rg`。 **索引**：运行 `/index` 以嵌入您的目录。重新运行是增量的 —— 仅重新嵌入已更改的文件。首次索引大型目录需要一些时间；后续运行会很快。 ## 代理支持 如果您在企业代理后面，设置一次即可跨会话保留： ``` /config proxy http://proxy.corp.com:8080 /config proxy reset # clear it ``` 这会在运行中的进程里设置 `HTTP_PROXY` 和 `HTTPS_PROXY`，下载嵌入模型或进行任何外部请求时，`requests`、`huggingface_hub` 和 `sentence-transformers` 会读取该设置。 如果已配置代理，启动时会自动应用。 ### 强制重新下载模型 要测试代理行为或从损坏的下载中恢复，请删除缓存的模型： ``` rm -rf ~/.cache/huggingface/hub/models--sentence-transformers--all-MiniLM-L6-v2 ``` 下一次 `/index` 运行将通过配置的代理重新下载它。 ## 开发 ``` # 安装 deps（包括 dev） uv sync # 运行 tests uv run pytest # 运行单个 test uv run pytest tests/test_config.py::test_save_load_roundtrip # 启动 TUI uv run python main.py ``` ## 架构 ``` src/trawler/ ├── app.py # TrawlerApp — main Textual application ├── config.py # TrawlerConfig — TOML-backed settings ├── index_state.py # IndexState — tracks which files are embedded ├── rules/ # YARA rule files (.yar / .yara) ├── search/ │ ├── basic.py # Regex line search │ ├── ripgrep.py # python-ripgrep wrapper │ ├── yara_scan.py # YARA scanning backend │ └── semantic.py # LangChain + ChromaDB vector search └── widgets/ ├── command_bar.py # Input widget with command + path autocomplete ├── results_panel.py# RichLog results display ├── sidebar.py # Directory list with indexing stats └── status_bar.py # Single-line status indicator ``` 项目本地数据位于 `.trawler/` (被 gitignore 忽略)： ``` .trawler/ ├── config.toml # Settings ├── index_state.json # Per-file mtime + size records └── chroma/ # ChromaDB vector store ```

标签：AMSI绕过, ChromaDB, ESC4, HTTP工具, OSINT, Python, Python安全, Ripgrep, TUI, YARA, 云资产可视化, 代码示例, 分类与分级, 取证工具, 向量搜索, 威胁检测, 情报分析, 敏感信息发现, 数据分析, 数据泄露, 文件搜索, 无后门, 本地部署, 终端用户界面, 网络安全, 网络安全审计, 网络诊断, 语义搜索, 逆向工具, 键盘驱动, 隐私保护