MrCl0wnLab/string-x-modules
GitHub: MrCl0wnLab/string-x-modules
为 String-X 提供基于外部工具编排的扩展模块集合，通过 subprocess 调用 nmap、httpx 等二进制文件并将其输出接入 String-X 流水线。
Stars: 3 | Forks: 0
# STRING-X 模块
**特殊模块**集合，用于扩展工具
[String-X](https://github.com/MrCl0wnLab/string-x) 的标准行为。每个模块都会**编排
安装在机器上的外部工具**（`nmap`、`httpx`、`SimpleReconSubdomain`，
…）：通过 `subprocess` 调用二进制文件，传递目标并解析输出。
这些模块**不**用 Python 重新实现逻辑——只是将工具集成到
String-X 的 pipeline 中。
- String-X: https://github.com/MrCl0wnLab/string-x
- 参考模块: https://github.com/MrCl0wnLab/string-x/tree/main/src/stringx/utils/auxiliary
## 工作原理
String-X 采用模块化架构：**一个 `.py` 文件 = 一个继承自
`BaseModule` 的类**。模块的**类型**决定了其在 CLI 中使用的子文件夹和前缀
（`tipo:nome`）。CLI 中的模块名称始终**与文件名相同**（不带 `.py`）。
| 类型 | 代码 | 目录 | 描述 |
|------|--------|-----------|-----------|
| **Extractor** | `ext` | `ext/` | 数据提取（email、URL、domain、phone） |
| **Collector** | `clc` | `clc/` | 收集/聚合（DNS、whois、外部工具） |
| **Output** | `out` | `out/` | 格式化和发送结果（DB、API、files） |
| **Connection** | `con` | `con/` | 专用连接（SSH、FTP 等） |
| **AI** | `ai` | `ai/` | 与 LLMs 集成 |
仓库结构：
```
string-x-modules/
├── default.json # variáveis (STRX_*) das ferramentas externas
├── install.py # merge da config + cópia dos módulos para o String-X
├── clc/ con/ ext/ out/ ai/ # módulos, uma subpasta por tipo
```
## `default.json` 文件
模块使用的外部工具并未硬编码在代码中——它们的
路径和参数声明在本仓库根目录的 `default.json` 中。
所有键都遵循固定的 **`STRX_*`** 模式，并由 `install.py` 合并到 String-X 的配置中，
在模块内部可以通过 `self.setting` 的属性进行访问
（例如：`self.setting.STRX_NMAP_PATH`）。
对于任何**对执行至关重要**且依赖于环境、或用户可能希望重置为默认值（如**二进制文件路径、
二进制文件名、timeout、wordlist** 等）的值，请使用 `STRX_*`。
```
{
"STRX_SIMPLERECON_PATH": "",
"STRX_SIMPLERECON_PYTHON": "",
"STRX_SIMPLERECON_TIMEOUT": 900,
"STRX_NMAP_PATH": "",
"STRX_NMAP_TIMEOUT": 600,
"STRX_HTTPX_PATH": "",
"STRX_HTTPX_TIMEOUT": 300
}
```
填写完成的文件示例
```
{
"STRX_SIMPLERECON_PATH": "/home/osint/Documentos/SimpleReconSubdomain",
"STRX_SIMPLERECON_PYTHON": "python3.12",
"STRX_SIMPLERECON_TIMEOUT": 900,
"STRX_NMAP_PATH": "/bin/nmap",
"STRX_NMAP_TIMEOUT": 600,
"STRX_HTTPX_PATH": "httpx",
"STRX_HTTPX_TIMEOUT": 300
}
```
在模块内部，请始终使用 `getattr` 读取（该键仅在
`install.py` 合并了 `default.json` **之后**才会存在）：
```
nmap_bin = str(getattr(self.setting, 'STRX_NMAP_PATH', '') or '')
timeout = self.options.get('timeout') or getattr(self.setting, 'STRX_NMAP_TIMEOUT', 600)
```
## 前置条件（运行前需安装的内容）
1. **String-X** - 安装这些模块所需的基础工具：
https://github.com/MrCl0wnLab/string-x
2. 每个模块调用的**外部工具**。只需安装您要使用的模块所需的工具，
并将相应的 `STRX_*` 键指向该二进制文件/文件：
| 工具 | 获取方式 | `STRX_*` 键 |
|------------|-----------|----------------|
| `nmap`（+ NSE `dns-brute`） | 包管理器（`apt install nmap`） | `STRX_NMAP_PATH` |
| **ProjectDiscovery** 的 `httpx`（非 Python 库） | `go install github.com/projectdiscovery/httpx/cmd/httpx@latest` | `STRX_HTTPX_PATH` |
| [SimpleReconSubdomain](https://github.com/MrCl0wnLab/SimpleReconSubdomain) | 克隆仓库 + 使用 `httpx[socks]`、`aiodns`、`dnspython`、`beautifulsoup4` 创建 venv | `STRX_SIMPLERECON_PATH`（+ `STRX_SIMPLERECON_PYTHON` 指向 venv） |
## 安装说明
`install.py` 以**幂等**方式执行：(1) 将本地的
`default.json` 与 String-X 的 `default.json` 进行**非破坏性合并**（保留现有键；备份在
`default.json.bak` 中；`--force` 会覆盖）以及 (2) 将各类型文件夹
（`ext/clc/out/con/ai`）中的模块**复制**到 String-X 的 `utils/auxiliary/` 目录中。
```
# 预览（不记录任何内容）
python install.py --path /caminho/para/string-x --dry-run
# 安装
python install.py --path /caminho/para/string-x
# 强制覆盖已存在的 config 密钥
python install.py --path /caminho/para/string-x --force
```
## 当前模块
所有当前模块均为 **collectors (`clc`)**，并通过 `{STRING}` 接收目标。
每个模块的选项均记录在各自的文件（`clc/.py`）中。
| 调用方式 | 工具 | 收集内容 |
|-----------|-----------|--------|
| `clc:simplerecon_subdomain` | SimpleReconSubdomain | 枚举的子域名 |
| `clc:simplerecon_ip` | SimpleReconSubdomain | 存活主机的 IP |
| `clc:simplerecon_url` | SimpleReconSubdomain | 发现的 URLs |
| `clc:simplerecon_full` | SimpleReconSubdomain | 子域名 + IPs + URLs + takeovers |
| `clc:nmap_subdomain` | nmap (NSE dns-brute) | 子域名（主机名） |
| `clc:nmap_ip` | nmap (NSE dns-brute) | 发现主机的唯一 IP |
| `clc:httpx_url` | httpx (ProjectDiscovery) | 存活的 URLs + 重定向目标 |
| `clc:httpx_ip` | httpx (ProjectDiscovery) | 主机的 IP |
| `clc:httpx_email` | httpx (ProjectDiscovery) | 响应正文中的 Emails |
| `clc:httpx_check` | httpx (ProjectDiscovery) | 在线 URLs 及其状态码 |
## 运行方式
`{STRING}` 是每行目标的变量。`-pm` 仅打印模块的输出；
`-pmc` 将每个链式模块的输出保持独立。
```
# 单个 module
echo "example.com" > domains.txt
strx -l domains.txt -st "echo {STRING}" -module "clc:simplerecon_subdomain" -pm
strx -l domains.txt -st "echo {STRING}" -module "clc:nmap_ip" -pm
# 串联 module（一个的输出作为下一个的输入）
strx -l domains.txt -st "echo {STRING}" -module "clc:simplerecon_subdomain|clc:httpx_check" -pmc
```
## 模块代码示例
这是一个封装了外部二进制文件的 collector 骨架。该文件
（`clc/ffuf_paths.py`）读取 `STRX_*` 变量，构建命令，**执行机器上的
二进制文件**并输出结果。
```
"""Collector de exemplo: envolve o binário externo ffuf."""
import os
import json
import subprocess
from stringx.core.basemodule import BaseModule
class FfufPaths(BaseModule):
def __init__(self):
super().__init__()
self.meta = {
'name': 'Ffuf Paths Collector',
'author': 'Seu Nome',
'version': '1.0',
'description': 'Fuzzing de paths web envolvendo o binário externo ffuf',
'type': 'collector', # casa com o prefixo CLI: clc
'example': './strx -l urls.txt -st "echo {STRING}" -module "clc:ffuf_paths" -pm'
}
self.options = {
'data': str(), # alvo, vem do pipeline do String-X
'timeout': None, # default: STRX_FFUF_TIMEOUT
'retry': 0,
'retry_delay': None,
}
def run(self) -> None:
try:
target = self.options.get('data', '').strip()
if not target:
return
# Variáveis fundamentais vindas do default.json (STRX_*)
ffuf_bin = str(getattr(self.setting, 'STRX_FFUF_PATH', '') or '')
wordlist = str(getattr(self.setting, 'STRX_FFUF_WORDLIST', '') or '')
timeout = self.options.get('timeout') or getattr(self.setting, 'STRX_FFUF_TIMEOUT', 300)
if not ffuf_bin or not os.path.isfile(ffuf_bin):
self.handle_error(
FileNotFoundError('STRX_FFUF_PATH'),
'Binário ffuf não encontrado - configure STRX_FFUF_* no default.json'
)
return
url = target if 'FUZZ' in target else target.rstrip('/') + '/FUZZ'
cmd = [ffuf_bin, '-u', url, '-w', wordlist, '-of', 'json', '-o', '-', '-s']
self.log_debug(f"[*] Executando: {' '.join(cmd)}")
result = subprocess.run(cmd, capture_output=True, text=True, timeout=int(timeout))
if result.returncode != 0:
self.handle_error(
subprocess.SubprocessError(result.stderr.strip()[:500]),
f'ffuf retornou código {result.returncode} para {target}'
)
return
for item in json.loads(result.stdout or '{}').get('results', []):
self.set_result(item.get('url', ''))
except Exception as e:
self.handle_error(e, 'Erro na coleta de paths (ffuf)')
```
使用方法：在 `default.json` 中声明 `STRX_FFUF_*` 键，运行
`python install.py --path /caminho/para/string-x` 并使用
`-module "clc:ffuf_paths"` 调用。
## 👨💻 作者
**MrCl0wn**
- 🌐 **博客**: [http://blog.mrcl0wn.com](http://blog.mrcl0wn.com)
- 🐙 **GitHub**: [@MrCl0wnLab](https://github.com/MrCl0wnLab)
- 🐦 **Twitter**: [@MrCl0wnLab](https://twitter.com/MrCl0wnLab)
- 📧 **Email**: mrcl0wnlab@gmail.com
**⭐ 如果这个项目对您有帮助，请考虑点个 star！**
**💡 随时欢迎提供建议和反馈！**
**💀 Hacker Hackeia!**
标签：ESC4, GitHub, OSINT, 内存取证对抗, 实时处理, 密码管理, 工具集成, 插件模块, 数字取证, 自动化脚本, 运行时操纵, 逆向工具