解密Horus源码架构:OSINT取证工具的argparse命令分发与模块化设计原理

原创2026-10-15 11:00:211,950 阅读

解密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")
# ... 其余子命令

三个要点值得初学者注意:

  1. store_true 动作:每个参数不带值,出现即为 True。这让"子命令"的语义非常干净——-shodan 表示"运行 shodan 模块",而不是传一个参数给主程序。
  2. add_mutually_exclusive_group() 互斥参数组:保证用户一次只能指定一个子命令。输入 python3 horus.py -shodan -exif 会被 argparse 直接拒绝,天然实现了"一次执行一个工具"的行为约束,无需手写校验逻辑。
  3. 注释即文档:源码中用 # 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,开发者只需:

  1. 复制模板,重命名文件与函数;
  2. 在 horus.py 的互斥参数组里注册一行参数;
  3. 在分发区加一个 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)。

总结:三个值得抄进自己项目的架构点

  1. 互斥参数组 + if 链分发:子功能无需独立参数时,比 subparsers 更简单的命令路由方案;
  2. 一文件一模块 + 同名主函数:template.py 让"新增功能"变成固定三步操作,模块间零耦合;
  3. 公共展示层统一风格:所有子命令共享 utils.py 的输出前缀与错误提示,保证多工具集成后的体验一致性。

这套"轻入口、重模块"的架构,正是中小型 Python CLI 工具最实用的组织范式——Horus 用它把 20 多个独立调查工具装进了一个 python3 horus.py 的世界里。

登录后查看全文