解密Horus源码架构:OSINT取证工具的argparse命令分发与模块化设计原理
解密Horus源码架构:OSINT取证工具的argparse命令分发与模块化设计原理
Horus 是一款用 Python 编写的 OSINT(开源情报)与数字取证工具,内置 Shodan 查询、IP 追踪、EXIF 解析、Loki 加密等 20 余个子命令。本文带你逐层解密它的源码架构:如何用 argparse 实现一条参数对应一个子命令的命令分发,以及通过模块化设计让每个功能独立成文件、统一接入的扩展机制,非常适合想学习 CLI 工具架构的初学者。
Horus 是什么:一个"全家桶"式取证工具箱
可以把 Horus 理解为一个"瑞士军刀":你只需要记住一个入口 horus.py,然后根据不同调查需求调用不同子命令,例如:
| 子命令 | 所属领域 | 功能 |
|---|---|---|
-shodan |
OSINT | 查询 IP 的 ISP、组织、位置、开放端口 |
-geolock |
OSINT | 基于 Shodan 的 IP 追踪与定位 |
-numlook |
OSINT | 全球手机号归属地与运营商查询 |
-mactrace |
OSINT | 通过 MAC 地址反查设备厂商 |
-exif |
取证 | 读取或清除图片 EXIF 元数据 |
-lokiencrypt |
Loki 加密 | 使用 Fernet 密钥加密目录 |
-apicon |
配置 | 交互式录入各 API Key |
所有依赖声明见 requirements.txt,项目元数据见 pyproject.toml。
整体目录结构一览
Horus 的目录划分非常克制,职责清晰:
horus/
├── horus.py # 程序入口:argparse 参数注册与分发
├── etc/
│ ├── init/banner.py # 启动横幅与版本号
│ └── skeleton/config/ # API 配置骨架文件
├── src/
│ ├── main.py # 交互式菜单入口(无参数时的第二条路径)
│ ├── apicon.py # API 配置子模块
│ ├── utils.py # 统一的彩色输出样式与提示函数
│ └── modules/ # 所有功能模块(每个文件 = 一个子命令)
│ ├── var/pipes/ # 运行时数据:API 配置、Loki 密钥、日志
│ ├── shodan.py
│ ├── geolock.py
│ └── template.py # 新模块的官方模板
└── tests/test_horus.py # 冒烟测试
关键设计思想:src/modules/ 目录里一个文件就是一个功能,入口文件只负责"路由",不写任何业务逻辑。
argparse 命令分发:一个互斥参数组搞定 20 个子命令
入口文件 horus.py 的三段式结构
打开 horus.py,整个命令分发的核心只有三步:
parser = argparse.ArgumentParser()
ap = parser.add_mutually_exclusive_group()
ap.add_argument('-apicon', help='Configure the API settings for Horus', action="store_true")
ap.add_argument('-shodan', help='...', action="store_true")
# ... 其余子命令
三个要点值得初学者注意:
store_true动作:每个参数不带值,出现即为True。这让"子命令"的语义非常干净——-shodan表示"运行 shodan 模块",而不是传一个参数给主程序。add_mutually_exclusive_group()互斥参数组:保证用户一次只能指定一个子命令。输入python3 horus.py -shodan -exif会被argparse直接拒绝,天然实现了"一次执行一个工具"的行为约束,无需手写校验逻辑。- 注释即文档:源码中用
# SECURITY.、# OSINT.等分组注释把参数分成安全、枚举、OSINT、Loki 四大类,与启动菜单的分类一一对应。
用 if 链完成分发
参数解析后(见 horus.py),Horus 用最直白的方式完成路由:
args = vars(parser.parse_args())
if args['shodan']:
shodan.run_shodan()
sys.exit(0)
每一个分支都遵循同一套"三段式"模式:
if args['pvpn']:
while True:
try:
pvpn.pvpn() # 1. 调用模块函数
sys.exit(0) # 2. 成功后立即退出
except Exception as error:
print(f">_ FAILURE: {error}") # 3. 异常统一转成友好提示
sys.exit(0)
这里有一个很实用的技巧:把整个模块调用包在 while True + try/except 里。因为子模块内部(如 Loki 加密)会 sys.exit() 结束流程,这个结构能兜住 SystemExit 之外的所有异常,保证任何子命令崩溃都不会抛出原始 traceback,而是统一打印红字 FAILURE 后干净退出。对新手工具来说,这种"错误不外泄"的体验设计非常值得借鉴。
为什么不用子解析器(subparsers)?
熟悉 argparse 的人可能会问:为何不用 parser.add_subparsers()?原因很实际——Horus 的子命令不需要额外参数(所有输入都在运行时通过 input() 交互完成),所以"布尔开关 + if 链"比"子命令 + 各自参数"更简单、更易读。这是一种"按复杂度选型"的务实架构决策:当每个子功能只是一个独立小程序时,开关式分发足矣。
第二条路径:交互式菜单分发
如果用户不带任何参数运行 python3 horus.py,程序会走进 src/main.py 的 main_script():
print_hero()
option = input(f"{PROMPT} ")
if option.lower() == "shodan":
shodan.run_shodan()
sys.exit(0)
这里出现了一个 input() 驱动的 if 链,逻辑与 argparse 分发几乎完全同构——都是"选项字符串 → 模块函数"的映射,只是输入来源从命令行变成了键盘。print_hero() 来自 src/utils.py,它会按 SECURITY / ENUMERATION / OSINT / LOKI / FORENSICS 五大分区打印命令清单,并用红黄绿三色标注每个功能的完成度(绿色=已实现、黄色=开发中、红色=待实现)。
这种"双入口"设计(命令行参数 + 交互菜单)是 CLI 工具的常见套路:参数化入口方便脚本化和快捷调用,交互菜单降低新手的学习门槛。
模块化设计:template.py 揭示的扩展机制
新模块只需"三步走"
项目自带了一份官方模块模板 src/modules/template.py,它定义了每个模块的标准骨架:
from ..utils import * # 1. 从公共层导入输出样式
def module_name(): # 2. 定义与模块同名的主函数
# CODE HERE.
return
if __name__ == '__main__': # 3. 支持独立运行调试
module_name()
要把一个新工具接入 Horus,开发者只需:
- 复制模板,重命名文件与函数;
- 在 horus.py 的互斥参数组里注册一行参数;
- 在分发区加一个
if args['xxx']分支。
以真实模块 src/modules/exif.py 为例,它的 exif() 函数内部独立完成"提示输入 → 读取文件 → 解析 EXIF → 打印结果"全流程,对外只暴露一个函数名——模块间零耦合,任何一个模块被删除都不影响其他模块运行。
API 配置的集中管理
需要第三方 API 的模块共享同一份配置文件 src/modules/var/pipes/api_config.json。查看 src/modules/shodan.py:
with open('./src/modules/var/pipes/api_config.json') as f:
data = json.load(f)
key = data["shodan"]
而配置文件由 src/apicon.py 生成的 apicon 子命令交互式写入:逐项询问 Shodan、Numlookup、VirusTotal 等 API Key,组装成字典后落盘到 var/pipes/ 目录。这个"配置与代码分离 + 集中式录入"的模式,使得新增 API 依赖时只需改两处:apicon 的提问项和 api_config.json 的键名。仓库还备有一份骨架 etc/skeleton/config/api_config_skeleton.json 供初始化参考。
统一视觉语言:utils.py 的作用
所有模块的输出风格都来自 src/utils.py 定义的常量与函数:SUCCESS、QUESTION、NOTICE 等彩色前缀,以及 print_response()、print_notice() 等封装函数。这意味着无论调用哪个子命令,用户看到的交互提示风格都完全一致。公共展示层 + 独立业务模块,是 Horus 模块化设计最重要的"胶水"。
快速上手:运行与验证
pip install -r requirements.txt
python3 horus.py -shodan # 命令行参数方式
python3 horus.py # 无参数进入交互菜单
python3 horus.py -apicon # 先配置各 API Key
首次使用建议先跑 -apicon 录入密钥(Shodan、VirusTotal 等为付费 API,部分功能无 Key 不可用)。测试入口在 tests/test_horus.py,目前仅做启动冒烟测试;启动横幅与版本号定义在 etc/init/banner.py(当前版本 1.2.7)。
总结:三个值得抄进自己项目的架构点
- 互斥参数组 + if 链分发:子功能无需独立参数时,比 subparsers 更简单的命令路由方案;
- 一文件一模块 + 同名主函数:
template.py让"新增功能"变成固定三步操作,模块间零耦合; - 公共展示层统一风格:所有子命令共享
utils.py的输出前缀与错误提示,保证多工具集成后的体验一致性。
这套"轻入口、重模块"的架构,正是中小型 Python CLI 工具最实用的组织范式——Horus 用它把 20 多个独立调查工具装进了一个 python3 horus.py 的世界里。