20行代码为MailAccess写一个OSINT模块：模块契约与自动发现机制开发者教程

【免费下载链接】MailAccessFree email OSINT tool, 5000 platforms, identity clustering, breach detection. No API keys required. pip install mailaccess项目地址https://gitcode.com/gh_mirrors/mai/MailAccess点击查看免费下载MailAccess 是一个开源免费的邮件 OSINT 工具pip install mailaccess即可运行内置 82 个 OSINT 模块可跨 5,300 平台完成身份聚类、数据泄露检测等调查绝大多数模块无需 API Key。本文面向开发者带你拆解它的模块契约与自动发现机制只需一个约 20 行的 Python 文件就能把你的数据源接入整条调查流水线重启服务即被自动注册全程零手动接线。一、为什么 MailAccess 的模块设计值得学MailAccess 的架构哲学是数据源即插件。一次investigate命令触发时引擎会把所有已注册模块并发调度执行各自产出标准化证据finding最终聚合成一份带置信度和溯源的报告。对贡献者来说这意味着你不需要理解整个引擎只需遵守一份极简契约。契约定义在 backend/modules/base.py全文不到 100 行是所有 OSINT 模块必须满足的接口协议。二、模块契约BaseModule 的四个类属性 一个方法类属性模块的身份证继承BaseModule后你要在类级别不是__init__里声明属性作用默认值name唯一 slug用于 API 响应和数据库记录必填description一行说明会展示在GET /api/modules/列表里必填requires_key为True时缺少 API Key 会自动跳过Falseemail_linked查找键就是邮箱本身时为True会盖印到每条 finding 上Falsepriority调度优先级100唯一方法async run(email)abstractmethod async def run(self, email: str) - ModuleResult: Run the module against *email* and return a ModuleResult.返回值是ModuleResult数据类包含四个字段status状态、findings发现列表、metadata模块级补充信息、errors人类可读错误。状态枚举ModuleStatus有五种SUCCESS— 正常完成可能有无发现SUCCESS_EMPTY— 正常完成且无发现PARTIAL— 部分成功例如部分请求被限流FAILED— 模块内部失败SKIPPED— 因缺 Key 或配置关闭而主动跳过 一个细节BaseModule.__init_subclass__会在类创建时自动给你的run包一层校验——如果你返回了None或不是ModuleResult的对象会直接抛AssertionError。这层守门人保证流水线里的脏数据无处可藏源码见 backend/modules/base.py。三、20行代码写一个完整模块按 CONTRIBUTING.md 的契约一个最小可用的 OSINT 模块长这样from __future__ import annotations from ..core.http_client import build_client from .base import BaseModule, ModuleResult, ModuleStatus class ExampleModule(BaseModule): name example_check # 1. 唯一 slug description Check Example service. # 2. 一行用途说明 requires_key False # 3. 是否需要 API Key async def run(self, email: str) - ModuleResult: # 4. 异步入口 findings: list[dict] [] async with build_client(timeout10.0) as client: try: resp await client.get( fhttps://example.com/api/check/{email} ) if resp.status_code 200 and resp.json().get(found): findings.append({ platform: example_service, profile_url: fhttps://example.com/{email}, confidence: high, metadata: {note: direct email match}, }) except Exception as exc: # 5. 永不抛出转成 errors return ModuleResult( statusModuleStatus.FAILED, errors[str(exc)] ) return ModuleResult(statusModuleStatus.SUCCESS, findingsfindings)五条铁律摘自 CONTRIBUTING.mdrun()永不抛异常——捕获一切用FAILEDerrors返回缺 Key 尽早返回SKIPPED而不是FAILED出站 HTTP 一律走build_client()backend/core/http_client.py它统一管理代理与限流每个模块有超时上限——默认 30 秒MODULE_TIMEOUT_SECONDS见 backend/config.py引擎用asyncio.wait_for强制执行阻塞库要用asyncio.to_thread()包装别卡死事件循环。真实示例可参考 backend/modules/hackernews.py错误收集、限流设置rate_limiter.set_delay、finding 去重一应俱全是很好的范本源码。四、自动发现机制文件放对位置重启即注册这是 MailAccess 最优雅的设计。backend/modules/init.py 里的注册器在首次访问时扫描backend/modules/目录def _discover() - None: package_dir Path(__file__).parent for _finder, module_name, _ispkg in pkgutil.iter_modules([str(package_dir)]): if module_name in _SKIP: continue mod importlib.import_module(f.{module_name}, package__name__) for attr_name in dir(mod): obj getattr(mod, attr_name) if (isinstance(obj, type) and issubclass(obj, BaseModule) and obj is not BaseModule and hasattr(obj, name)): _registry[obj.name] obj翻译成白话任何.py文件只要定义了继承BaseModule且带name属性的类就会被pkgutil.iter_modules扫出来、导入、注册进全局_registry——没有导入列表要维护没有工厂方法要改。三个细节值得注意懒加载发现逻辑被延迟到第一次需要模块列表时才执行约 1 秒 的导入成本避免拖慢服务冷启动和/health探活name 必须全局唯一重复会静默覆盖先到者验证很简单重启服务后跑mailaccess modules或用 APIGET /api/modules/backend/api/routes/modules.py——你的模块名出现了就说明契约通过。五、模块如何被引擎调度执行注册只是入场券。真正执行发生在 backend/core/engine.py 的InvestigationEngine里引擎按阶段 DAG 组织执行backend/core/phases.py主阶段一次性拿到get_all_modules()的全部类用asyncio.Semaphore(max_concurrency)控制并发默认10 个模块同时跑MAX_CONCURRENT_MODULES全局出站请求还有 40 的总闸门单模块超时默认 30 秒超时会以FAILED记录但不影响整次调查你的 finding 会经过证据标注trace/label、跨模块去重、身份图聚合最终进入报告、导出文件和数据库。也就是说一个写对契约的模块天然获得了并发调度、超时保护、错误隔离、证据链标注和持久化——这些你一行代码都不用写。六、开发自查清单提交前对照 CONTRIBUTING.md 的 PR Checklistname唯一description一目了然缺 Key 时返回SKIPPED不返回FAILED无阻塞 I/O 直跑事件循环HTTP 走build_client()无硬编码凭据不新增第三方依赖pytest通过测试随 PR 提交更新了 docs/modules.md 的模块表与 finding schema落地路径只有一条把文件放到backend/modules/my_module.py下次服务启动自动注册。更多模块的 finding schema 细节如gravatar、hibp、xposedornot等 82 个模块的完整字段定义可查阅官方文档docs/modules.md 的 Adding a Module 章节。从 20 行代码到一条完整证据链这就是 MailAccess 模块体系的开发体验契约极小、发现自动、调度托管。赞分享【免费下载链接】MailAccessFree email OSINT tool, 5000 platforms, identity clustering, breach detection. No API keys required. pip install mailaccess项目地址https://gitcode.com/gh_mirrors/mai/MailAccess点击查看免费下载相关推荐The Big Brother开发者指南/api/dispatch统一调度机制与自定义OSINT模块二次开发教程The Big Brother开发者指南/api/dispatch统一调度机制与自定义OSINT模块二次开发教程 The Big Brother 是一个开源的OpenConstructionERP模块开发教程10分钟写出第一个模块并自动挂载OpenConstructionERP模块开发教程10分钟写出第一个模块并自动挂载 OpenConstructionERP 是一款开源建筑 ERP 系统支持后端前端桌面应用ERP企业应用Bookshelf微模块开发契约如何编写你自己的Micro-moduleBookshelf微模块开发契约如何编写你自己的Micro module 如果你想在 KOReader 阅读器的 Bookshelf 书架插件里加一块时钟、天创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考