OpenOSINT 详细部署教程：AI 驱动的开源情报调查工具

OpenOSINT 是一个集成 AI 能力的开源情报（OSINT）调查工具，它通过自然语言交互界面，整合了 20 种专业调查工具，能够自动进行信息收集、关联分析和报告生成。本教程将介绍其安装、配置和核心使用方法。

1. 项目概述与准备

1.1 核心能力

OpenOSINT 为安全研究人员和分析师提供：

  • 20 个模块化工具：涵盖邮箱、用户名、域名、IP、电话、数据泄露、子域名、Shodan、VirusTotal、Censys、DNS 等调查维度。
  • AI 智能代理：默认使用 Anthropic Claude，也支持本地 Ollama 或任何 OpenAI 兼容接口。AI 能根据调查目标自主选择和链式调用工具。
  • 多种交互界面：提供交互式 REPL（Read-Eval-Print Loop）、命令行直接调用、Web 浏览器 UI 以及 MCP（Model Context Protocol）服务器。
  • 结构化输出：自动生成 Markdown 和 PDF 报告，支持 JSON 输出。

1.2 系统要求

  • 操作系统：Linux、macOS、Windows（通过 WSL）。
  • Python 版本：Python 3.8 或更高版本。
  • 外部依赖（部分工具需要，需在 PATH 中）：holehe, sherlock-project, sublist3r, phoneinfoga。如果缺失，对应的工具会返回错误提示，不影响其他工具使用。
  • AI API 密钥（必须）：至少需要配置一个 AI 后端。推荐使用 Anthropic API Key（默认），也可使用 OpenAI 兼容接口或本地 Ollama（无需密钥）。
  • 网络：能访问互联网以使用各 API 和工具。

⚠️ 法律与授权警告：OpenOSINT 仅限合法授权使用！ 用户必须确保其使用行为符合所在国家/地区的所有法律法规。作者不对任何滥用行为承担责任。使用前请务必阅读项目中的 DISCLAIMER.md。

2. 安装与基础配置

2.1 安装核心包

推荐从 PyPI 安装稳定版：

1
pip install openosint

从源码安装（开发版）：

1
2
3
git clone https://github.com/OpenOSINT/OpenOSINT.git
cd OpenOSINT
pip install -e .

安装可选依赖（根据需求）：

命令 用途
pip install "openosint[web]" 启用 Web UI 界面
pip install "openosint[openai]" 启用 OpenAI 兼容后端
pip install "openosint[graph]" 启用实体图谱模块（Python 3.10+）
pip install ollama 本地 Ollama 后端支持（还需安装 Ollama 运行时）
pip install shodan reportlab censys 分别安装 Shodan、PDF 报告、Censys 支持

2.2 安装外部工具（可选）

为了使用全部功能，建议安装以下工具并确保它们在系统的 PATH 环境变量中：

1
2
pip install holehe sherlock-project sublist3r
# phoneinfoga 需要从其 GitHub 仓库下载预编译二进制文件

2.3 配置 API 密钥

OpenOSINT 通过项目根目录或用户目录下的 .env 文件读取密钥。创建该文件并填入必要信息：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 至少配置一个 AI 后端
ANTHROPIC_API_KEY=sk-ant-...  # 默认 AI 后端，强烈推荐

# 以下为可选工具 API 密钥
HIBP_API_KEY=...              # HaveIBeenPwned (数据泄露查询)
SHODAN_API_KEY=...            # Shodan
VIRUSTOTAL_API_KEY=...        # VirusTotal
IP2LOCATION_API_KEY=...       # IP2Location.io
CENSYS_API_ID=...             # Censys ID
CENSYS_SECRET=...             # Censys Secret
ABUSEIPDB_API_KEY=...         # AbuseIPDB
GITHUB_TOKEN=...              # GitHub API (提升速率限制)
BRIGHTDATA_API_KEY=...        # Bright Data (用于实时搜索和网页抓取)

如果没有配置相应密钥，调用对应工具时会提示错误，但其他功能正常。

3. 核心使用方法

3.1 方式一：交互式 REPL（推荐）

在终端中直接输入 openosint 进入 AI 代理模式。你可以用自然语言描述调查目标，AI 会自动决策并执行工具链。

1
openosint

在 REPL 中，你可以：

  • 发起调查：直接输入邮箱、用户名、域名等，例如：

    1
    > investigate target@example.com

    AI 会依次调用 search_email, search_breach, 并根据结果（如发现的用户名）自动进行 search_username 等后续操作。

  • 使用命令：

    • clear：重置对话记忆
    • save：保存当前报告到 reports/ 目录
    • tools：列出所有可用工具及其状态
    • config：查看当前配置
    • history：浏览历史会话
    • exit 或 Ctrl-D：退出

3.2 方式二：直接调用工具（无 AI）

如果你想直接运行某个特定工具而不经过 AI 代理，可以使用命令行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 邮箱调查
openosint email target@example.com

# 用户名调查
openosint username johndoe99

# WHOIS 查询
openosint whois example.com

# IP 查询
openosint ip 8.8.8.8

# Shodan 查询 (需要 API 密钥)
openosint shodan 8.8.8.8

# 使用 --json 输出结构化数据
openosint email target@example.com --json

# 使用 --parallel 并发执行多个工具
openosint multi target@example.com johndoe99 example.com --parallel

3.3 方式三：启动 Web UI

Web 界面提供图形化的聊天和结果展示，支持流式输出、工具卡片，适合不熟悉命令行的用户。

1
2
3
4
# 安装 Web 依赖后启动
pip install "openosint[web]"
openosint web
# 浏览器将自动打开 http://localhost:8080

在 Web UI 的设置中，你可以选择 AI 后端（Anthropic、Ollama、OpenAI 兼容），并配置相应的 API 密钥。

4. 高级配置与集成

4.1 配置本地 Ollama（完全离线）

如果你希望完全本地运行，无需 API 密钥，可以使用 Ollama。

  1. 安装并运行 Ollama：从 ollama.com 下载并运行，拉取一个模型，如 llama3.2。

  2. 安装 Python 依赖：pip install ollama

  3. 启动 OpenOSINT 并指定使用 Ollama：

    1
    openosint --provider ollama --ollama-model llama3.2

    Web UI 中也可以在设置里选择 “Ollama (local)”。

4.2 作为 MCP 服务器运行

OpenOSINT 可以作为 MCP 服务器，将其 20 个工具暴露给任何 MCP 兼容的 AI 客户端（如 Claude Desktop、Claude Code）。

  • 在 Claude Code 中集成：

    1
    claude mcp add openosint python /绝对路径/到/OpenOSINT/openosint/mcp_server.py

  • 在 Claude Desktop 中集成：编辑配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json，添加：

    1
    2
    3
    4
    5
    6
    7
    8
    {
      "mcpServers": {
        "openosint": {
          "command": "python",
          "args": ["/绝对路径/到/OpenOSINT/openosint/mcp_server.py"]
        }
      }
    }

配置后，在 Claude 中就可以直接通过自然语言调用 OpenOSINT 的所有工具进行调查。

5. 故障排查与注意事项

  • 工具未找到：如果提示 holehe、sherlock 等未找到，请确保已通过 pip 安装，并且其可执行文件在 PATH 中。可以尝试重新打开终端或使用 python -m site --user-base 找到用户安装路径并添加到 PATH。
  • API 密钥错误：仔细检查 .env 文件中的密钥是否正确，并确保环境变量已加载（重启终端或 source .env）。
  • 网络或代理问题：部分工具需要访问外网 API。如果在中国大陆使用，可能需要配置网络代理。
  • Web UI 无法启动：确保已安装 openosint[web] 依赖，并且端口 8080 未被占用。可以使用 openosint web --port 8081 指定其他端口。
  • 关于 Web UI 的安全变更 (v2.28+)：重要！在最新版本中，为了安全考虑，当 Web UI 绑定到非 127.0.0.1 地址时（即对外提供服务），系统不会使用你的 .env 文件中的 API 密钥，而是要求每个用户自行在 Web UI 中配置密钥。这是为了防止意外泄露高权限密钥。如你确信反向代理环境安全，可设置 OPENOSINT_TRUSTED_PROXY=true 环境变量来恢复原有行为，但务必确保在前端配置了适当的认证。

6. 总结：常用命令速览

场景 命令
启动 AI 交互式调查 openosint
启动 Web UI openosint web
直接查询邮箱 openosint email 目标@邮箱.com
直接查询用户名 openosint username 目标用户名
查询域名 WHOIS openosint whois example.com
查询 IP 信息 openosint ip 8.8.8.8
使用特定 AI 提供商 openosint --provider ollama
输出 JSON 格式 在命令后加 --json
查看所有工具 openosint tools
查看历史会话 openosint history

OpenOSINT 是一个功能强大但需要谨慎使用的工具。请务必遵守法律法规，仅在授权范围内进行安全研究和调查。建议先从免费的 Prompt 入门套件开始，熟悉其工作流程和方法论。