1. 项目概述与核心价值

如果你在网络安全领域摸爬滚打过一阵子，肯定对“撞库”这个词不陌生。简单来说，就是黑客拿着从A网站泄露的账号密码，去B网站碰运气，因为很多人习惯在不同平台用同一套密码。而 pwnedOrNot 这个工具，就是帮你快速检查自己的邮箱是否出现在已知的公开数据泄露事件中的利器。它本质上是一个命令行工具，通过调用“Have I Been Pwned”这个知名泄露数据查询服务的API，让你能批量、自动化地检查邮箱地址是否“中招”。

为什么我要专门写一篇部署指南？因为在实际工作中，我发现很多朋友，无论是安全研究员、渗透测试工程师，还是普通的隐私意识较强的用户，都希望能在自己最熟悉的环境里快速用上这个工具。有人主力用Kali Linux做测试，有人喜欢用Docker保证环境纯净和可移植性，还有人在移动设备上用Termux搭建便携式安全工具箱。网上的资料要么太零散，要么只讲一种方式，遇到依赖报错、网络问题就卡住了。所以，我打算把在Kali Linux、Docker和Termux这三个主流且差异巨大的平台上，从零开始部署pwnedOrNot的完整流程、踩过的坑以及优化技巧，一次性讲透。无论你是在虚拟机上跑Kali，在服务器上用Docker容器，还是在安卓手机上玩Termux，这篇指南都能让你少走弯路，快速搭建起属于自己的泄露查询工作站。

2. 环境准备与核心依赖解析

在开始安装之前，理解pwnedOrNot的工作原理和它的“胃口”（即依赖）至关重要。这能帮你提前避开大部分环境配置的坑。

pwnedOrNot是一个用Python编写的工具，它的核心任务就是与远程API通信、处理数据并格式化输出。因此，它的依赖主要围绕网络请求、数据解析和终端展示。最核心的Python库通常是 requests （用于HTTP请求）和 colorama （用于在终端输出彩色文字，提升可读性）。虽然项目可能会直接列出所有依赖在 requirements.txt 文件里，但不同系统环境下，安装这些Python包的前置条件天差地别。

注意 ：永远不要假设你的系统Python环境是“干净”或“完整”的。特别是在Kali Linux和Termux上，系统自带的Python可能缺少头文件、编译工具或关键的底层库（如 libffi 、 openssl 开发包），这会导致后续用 pip 安装某些依赖时编译失败。

2.1 通用前置检查清单

无论选择哪个平台，在动手安装pwnedOrNot之前，都建议先完成下面这几项检查，这能解决80%的安装失败问题：

  1. Python版本确认 ：打开终端，运行 python3 --version 。pwnedOrNot通常要求Python 3.6及以上。我强烈建议使用Python 3.7+，以获得更好的兼容性。
  2. 包管理工具更新 ：确保你的 pip 是最新的。运行 pip3 install --upgrade pip 。一个陈旧的 pip 可能无法正确解析依赖关系或从PyPI（Python包索引）下载最新的包。
  3. 系统编译工具链 ：如果你需要通过 pip 从源码编译安装任何包（比如某些时候 requests 依赖的 cryptography 库），那么 gcc 、 make 、 python3-dev （或 python3-devel ）这些包必须就位。
  4. 网络连通性测试 ：由于需要从GitHub克隆代码、从PyPI下载包、并访问“Have I Been Pwned”的API，请确保你的网络环境能够正常访问这些资源。可以简单测试一下： ping -c 3 github.com 和 curl -s https://pypi.org/simple/ 。

2.2 各平台特殊依赖考量

  • Kali Linux ：作为渗透测试发行版，Kali预装了海量工具，Python环境也比较“重”。好处是很多底层依赖可能已经有了。但潜在问题是，不同版本Kali的Python环境可能被其他工具修改过，存在包冲突。我们的策略是优先使用系统包管理器 apt 安装基础依赖，再为pwnedOrNot项目创建独立的虚拟环境。
  • Docker ：这是最“纯净”的方式。你不需要关心宿主机的环境，所有依赖都被封装在镜像里。核心工作是编写或使用一个正确的 Dockerfile ，定义好从哪个基础镜像开始、安装哪些包、如何设置工作目录和启动命令。
  • Termux ：这是在Android上模拟的Linux环境，运行在ARM架构上。它的软件源独立，包名和常规Linux发行版不同（比如没有 apt-get ，而是 pkg ）。最大的挑战在于ARM架构下某些Python二进制扩展包的可用性，以及Termux独特的文件路径结构（ $PREFIX 代替了传统的 /usr ）。

理清了这些底层逻辑，我们就可以针对每个平台，开始具体的部署实战了。

3. Kali Linux 部署实战与深度优化

Kali是很多安全从业者的主力系统，在这里部署工具讲究一个“稳”字，既要能用，又不能搞乱系统本身为其他工具准备的环境。

3.1 系统级依赖安装

首先，更新软件源并安装编译环境和必要的Python开发包。打开终端，执行以下命令： 

sudo apt update
sudo apt upgrade -y
sudo apt install -y python3-pip python3-venv git build-essential libssl-dev libffi-dev python3-dev
  • sudo apt update ：刷新软件包列表，确保获取到最新的版本信息。
  • sudo apt upgrade -y ：升级所有已安装的包（ -y 表示自动确认）。这一步不是必须，但能减少因旧包引起的兼容性问题。
  • python3-pip ：安装Python3的包管理工具pip。
  • python3-venv ：这是关键！用于创建Python虚拟环境，我们将在这个独立环境中安装pwnedOrNot，与系统Python完全隔离。
  • build-essential , libssl-dev , libffi-dev , python3-dev ：这些是编译Python包（特别是涉及加密、哈希的包）所必需的头文件和库。缺少它们，后续 pip install 可能会报错，提示找不到 openssl/opensslv.h 或 ffi.h 。

3.2 创建虚拟环境并部署工具

我习惯在用户主目录下创建一个专门的目录来管理这些自部署的工具。 

cd ~
mkdir -p my-security-tools
cd my-security-tools

接下来，创建Python虚拟环境并激活它。虚拟环境就像一个“沙箱”，所有针对pwnedOrNot的包安装都只在这个沙箱内生效。 

python3 -m venv pwnedornot-env
source pwnedornot-env/bin/activate

执行 source 命令后，你的命令行提示符前面通常会显示 (pwnedornot-env) ，这表明你已经进入了虚拟环境。现在，使用虚拟环境内的 pip 来操作。

从GitHub克隆pwnedOrNot的仓库： 

git clone https://github.com/thewhiteh4t/pwnedOrNot.git
cd pwnedOrNot

安装项目依赖。通常项目根目录下会有 requirements.txt 文件： 

pip3 install -r requirements.txt

如果项目没有明确的 requirements.txt ，或者安装后运行仍报错，可以尝试手动安装核心依赖： 

pip3 install requests colorama

3.3 验证安装与基本使用

安装完成后，先验证工具是否能正常运行： 

python3 pwnedornot.py -h

你应该能看到帮助信息，列出了可用的参数，比如 -e 用于指定单个邮箱， -l 用于指定一个包含邮箱列表的文件。

现在，尝试查询一个测试邮箱（你可以用自己的邮箱）： 

python3 pwnedornot.py -e example@example.com

首次运行，工具可能会提示你需要API密钥。“Have I Been Pwned”的API v3需要密钥才能使用。你需要去官网（https://haveibeenpwned.com/API/Key）注册一个免费账户并获取API密钥。获取后，通常可以通过设置环境变量 HIBP_API_KEY 来使用： 

export HIBP_API_KEY='你的实际API密钥'
python3 pwnedornot.py -e your_email@domain.com

实操心得 ：在Kali中，建议将API密钥写入你的shell配置文件（如 ~/.bashrc 或 ~/.zshrc ）中，但要注意安全，避免泄露。可以这样添加： export HIBP_API_KEY='你的密钥' 。然后执行 source ~/.bashrc 使其生效。这样以后每次打开终端都可以直接使用，无需重复输入。

3.4 常见问题排查（Kali篇）

  1. pip install 报错： Failed building wheel for cryptography 或类似编译错误

    • 原因 ：缺少编译所需的开发库。
    • 解决 ：确保你已经执行了上面 3.1 步骤，安装了 build-essential libssl-dev libffi-dev python3-dev 。如果仍失败，尝试升级 pip 和 setuptools ： pip3 install --upgrade pip setuptools wheel 。

  2. 运行脚本时报错： ModuleNotFoundError: No module named '...'

    • 原因 ：没有在正确的虚拟环境中运行，或者依赖没有安装成功。
    • 解决 ：首先确认命令行提示符前有 (pwnedornot-env) 。如果没有，回到工具目录，执行 source ../pwnedornot-env/bin/activate 。然后重新安装依赖 pip3 install -r requirements.txt 。

  3. API请求失败，提示超时或SSL错误

    • 原因 ：网络问题，或者系统时间不正确导致SSL证书验证失败。
    • 解决 ：检查网络连接。使用 date 命令查看系统时间是否正确。如果不正确，可以尝试安装 ntpdate 进行同步： sudo apt install ntpdate && sudo ntpdate pool.ntp.org 。对于网络问题，可以考虑配置代理（需根据你的实际情况设置，此处不展开）。

4. Docker 容器化部署：打造可移植环境

Docker部署的核心思想是“一次构建，处处运行”。它完美解决了环境依赖和污染的问题。我们将通过编写一个 Dockerfile 来定义构建镜像的每一步。

4.1 编写 Dockerfile

在你的工作目录（例如 ~/my-security-tools ）下，创建一个名为 Dockerfile 的文件（没有后缀名），内容如下： 

# 使用官方Python 3.9 slim镜像作为基础，体积较小
FROM python:3.9-slim

# 设置维护者信息（可选）
LABEL maintainer="your-email@example.com"

# 安装系统依赖：git用于克隆代码，gcc等用于编译Python包
RUN apt-get update && apt-get install -y \
    git \
    gcc \
    g++ \
    make \
    libssl-dev \
    libffi-dev \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /app

# 克隆pwnedOrNot仓库
RUN git clone https://github.com/thewhiteh4t/pwnedOrNot.git .

# 安装Python依赖
RUN pip3 install --no-cache-dir -r requirements.txt

# 设置容器启动时默认执行的命令（查看帮助）
ENTRYPOINT ["python3", "pwnedornot.py"]
CMD ["-h"]

逐行解读 ：

  • FROM python:3.9-slim ：选择了一个轻量级的Python 3.9镜像。 slim 版本比完整版小很多，足够我们使用。
  • RUN apt-get update && ... ：这是Dockerfile的最佳实践之一。将 update 和 install 放在同一个 RUN 指令中，并且最后清理apt缓存（ rm -rf /var/lib/apt/lists/* ），可以显著减少镜像层大小。
  • WORKDIR /app ：设置容器内的工作目录为 /app ，后续命令都在此目录下执行。
  • RUN git clone ... ：克隆项目代码到当前工作目录（ /app ）。
  • RUN pip3 install ... ：安装依赖。 --no-cache-dir 选项告诉pip不要缓存下载的包，进一步减小镜像大小。
  • ENTRYPOINT 和 CMD ：定义了容器的默认行为。 ENTRYPOINT 指定了固定命令（ python3 pwnedornot.py ）， CMD 指定了默认参数（ -h ）。这意味着当你不带参数运行容器时，它会显示帮助信息。你也可以在运行时覆盖 CMD 部分。

4.2 构建镜像并运行容器

在包含 Dockerfile 的目录下，打开终端，执行构建命令： 

docker build -t pwnedornot:latest .

-t 参数给镜像打标签，这里命名为 pwnedornot ，标签为 latest 。末尾的 . 表示Dockerfile在当前目录。

构建完成后，你可以看到新的镜像出现在列表中： docker images 。

现在，运行一个容器来测试。为了传递API密钥，我们使用 -e 参数设置环境变量： 

docker run --rm -e HIBP_API_KEY='你的实际API密钥' pwnedornot:latest -e test@example.com
  • --rm ：容器停止运行后自动删除，避免留下无用的容器。
  • -e HIBP_API_KEY=... ：将宿主机的环境变量传入容器内部，供pwnedOrNot脚本读取。
  • 最后的 -e test@example.com 覆盖了Dockerfile中 CMD 定义的 -h ，成为传递给 pwnedornot.py 的参数。

4.3 高级用法与数据持久化

批量查询本地文件 ：如果你想查询一个存放在宿主机上的邮箱列表文件（如 emails.txt ），需要将宿主机目录挂载到容器内。

假设你的邮箱列表文件在宿主机的 /home/user/data/emails.txt ，你可以这样运行： 

docker run --rm -v /home/user/data:/data -e HIBP_API_KEY='你的密钥' pwnedornot:latest -l /data/emails.txt -o /data/results.txt
  • -v /home/user/data:/data ：将宿主机的 /home/user/data 目录挂载到容器内的 /data 目录。
  • -l /data/emails.txt ：告诉容器内的pwnedOrNot读取挂载进去的列表文件。
  • -o /data/results.txt ：将结果输出到同样挂载的目录中，这样在宿主机上就能直接看到 results.txt 文件了。

创建别名简化命令 ：每次输入长长的 docker run 命令很麻烦。可以在你的shell配置文件中添加别名。编辑 ~/.bashrc ，加入： 

alias pwnedornot='docker run --rm -v $(pwd):/data -e HIBP_API_KEY=\"你的密钥\" pwnedornot:latest'

保存后执行 source ~/.bashrc 。之后，在任意目录下，你只需要将邮箱列表文件放在当前目录，然后运行： 

pwnedornot -l ./emails.txt -o ./results.txt

因为别名里定义了 -v $(pwd):/data ，所以当前目录（ $(pwd) ）被挂载到了容器的 /data ，非常方便。

注意事项 ：将API密钥硬编码在别名或脚本中存在安全风险。对于生产环境或敏感用途，考虑使用Docker Secrets（在Swarm模式下）或通过外部文件传入环境变量。对于个人使用，确保你的宿主机安全。

5. Termux (Android) 部署：移动端安全利器

在Android手机上通过Termux部署pwnedOrNot，可以让你随时随地快速检查泄露情况，或者集成到移动端的自动化工作流中。Termux是一个强大的终端模拟器和Linux环境，但它的文件系统和包管理与标准Linux有所不同。

5.1 Termux 基础环境配置

首先，从Google Play或F-Droid安装Termux。启动后，第一步是更新软件源和升级已有包： 

pkg update
pkg upgrade -y

接着，安装必要的底层工具和Python环境： 

pkg install -y python git clang make libffi openssl-tool python-dev libcrypt-dev
  • clang ：Termux上常用的C/C++编译器，替代 gcc 。
  • libffi , openssl-tool , python-dev , libcrypt-dev ：这些是编译Python加密相关库所必需的开发包。在Termux中，包名可能与Debian/Ubuntu略有差异。

安装Python的包管理工具 pip ： 

pip install --upgrade pip

5.2 获取源码与安装依赖

和之前类似，我们创建一个工作目录并克隆代码： 

cd ~
mkdir -p my-tools
cd my-tools
git clone https://github.com/thewhiteh4t/pwnedOrNot.git
cd pwnedOrNot

在Termux中，通常不建议使用虚拟环境（因为环境本身相对独立），直接使用 pip 安装到用户空间即可。安装项目依赖： 

pip install -r requirements.txt

如果遇到编译错误，可能是因为某些包的二进制轮子（wheel）不适用于Termux的ARM架构，需要从源码编译。确保你已经安装了 clang 和那些 -dev 包。有时需要指定 pip 使用 --no-binary 选项强制编译： 

pip install --no-binary :all: cryptography
# 然后再尝试安装 requirements.txt

5.3 在Termux中运行与配置

安装完成后，运行方式与Kali中一致： 

python pwnedornot.py -h

设置API密钥。在Termux中，你可以将其添加到Termux的启动脚本中。编辑 ~/.bashrc 文件： 

nano ~/.bashrc

在文件末尾添加： 

export HIBP_API_KEY='你的实际API密钥'

按 Ctrl+X ，然后按 Y ，再按回车保存。退出Termux并重新打开，或者执行 source ~/.bashrc 使环境变量生效。

现在可以正常查询了： 

python pwnedornot.py -e your_email@gmail.com

5.4 Termux专属问题与优化

  1. 存储权限 ：默认情况下，Termux只能访问自己的私有目录（ ~/ ）。如果你想读取手机存储上的文件（如 /sdcard/Download/emails.txt ），需要授予存储权限并建立符号链接。

    • 运行 termux-setup-storage 。这会提示你允许存储权限，并在 ~/ 目录下创建一个 storage 文件夹，链接到你的手机存储。
    • 之后，你可以通过 ~/storage/shared/Download/emails.txt 这样的路径来访问文件。

  2. 后台运行与省电 ：Android系统可能会在屏幕关闭后休眠Termux进程。如果你需要长时间运行批量查询，可以考虑：

    • 使用 termux-wake-lock 命令阻止CPU休眠。
    • 使用 nohup 或 tmux （需安装 pkg install tmux ）在后台运行任务。
    • 安装Termux:Widget，创建快捷脚本一键运行任务。

  3. 性能考量 ：手机CPU和内存资源有限。批量查询大量邮箱时，建议使用 -t 参数（如果工具支持）调整线程数，设置为较低的值（如2或3），避免过度消耗资源导致Termux被系统杀死。同时，使用 -o 参数将结果输出到文件，防止终端输出过多内容造成卡顿。

6. 工具使用技巧与脚本化实战

部署好了，我们来聊聊怎么用得更好。pwnedOrNot的基础用法是查询单个邮箱，但它的威力在于批量处理和自动化。

6.1 批量查询与报告生成

假设你有一个每行一个邮箱地址的文件 email_list.txt ，使用 -l 参数进行批量查询，并用 -o 输出结果： 

python3 pwnedornot.py -l /path/to/email_list.txt -o ./breach_report.txt

生成的 breach_report.txt 会包含每个邮箱的查询结果。但原始输出可能比较冗长。我们可以结合其他命令行工具（如 grep , awk ）进行初步过滤。例如，只提取出被泄露过的邮箱和对应的泄露事件： 

python3 pwnedornot.py -l email_list.txt | grep -A2 "\[+\]" > breached_emails.txt

这个命令会匹配到包含 [+] 的行（通常表示发现泄露），并打印该行及后面两行（通常包含泄露详情），然后保存到新文件。

6.2 集成到自动化工作流

真正的效率提升来自于自动化。这里分享一个我常用的简单脚本，它读取邮箱列表，查询泄露信息，并生成一个更结构化的CSV报告。

创建一个名为 pwned_checker.sh 的脚本： 

#!/bin/bash

# 检查是否提供了输入文件
if [ -z "$1" ]; then
    echo "Usage: $0 <email_list_file>"
    exit 1
fi

INPUT_FILE="$1"
OUTPUT_CSV="pwned_report_$(date +%Y%m%d_%H%M%S).csv"

# 写入CSV表头
echo "Email,Breach Count,Breach Names" > "$OUTPUT_CSV"

# 逐行读取邮箱文件
while IFS= read -r email; do
    # 去除行首尾空白字符
    email_clean=$(echo "$email" | xargs)
    # 跳过空行
    if [ -z "$email_clean" ]; then
        continue
    fi

    echo "Checking: $email_clean"
    # 运行pwnedOrNot，并将结果捕获。这里假设工具的输出格式。
    # 注意：实际解析需要根据pwnedOrNot的具体输出格式调整grep和awk命令。
    # 以下是一个示例解析逻辑，可能需要你自行调整。
    RESULT=$(python3 /path/to/pwnedornot.py -e "$email_clean" 2>/dev/null)

    # 示例：提取泄露数量（假设输出中有类似“[+] Breaches found: 3”的行）
    BREACH_COUNT=$(echo "$RESULT" | grep "Breaches found:" | awk '{print $NF}')
    # 如果没有找到泄露，设为0
    BREACH_COUNT=${BREACH_COUNT:-0}

    # 示例：提取泄露名称（假设在“Breaches:”行之后列出）
    BREACH_NAMES=$(echo "$RESULT" | awk '/Breaches:/{flag=1; next} /^$/ || /\[-]/{flag=0} flag' | tr '\n' ';' | sed 's/;*$//')

    # 写入CSV行
    echo "\"$email_clean\",\"$BREACH_COUNT\",\"$BREACH_NAMES\"" >> "$OUTPUT_CSV"

    # 礼貌性延迟，避免请求过快被API限制
    sleep 1.5
done < "$INPUT_FILE"

echo "检查完成。报告已生成: $OUTPUT_CSV"

脚本说明 ：

  1. 这是一个Bash脚本，需要传入一个邮箱列表文件作为参数。
  2. 它创建一个带有时间戳的CSV输出文件。
  3. 逐行读取邮箱，调用pwnedOrNot进行查询。
  4. 关键点 ： RESULT 的解析部分（ grep 和 awk 命令） 强烈依赖于pwnedOrNot工具的实际输出格式 。上面的命令是示例，你需要根据你使用的pwnedOrNot版本的真实输出，调整这些命令来准确提取“泄露数量”和“泄露名称”。
  5. 每次查询后暂停1.5秒，遵守API的使用礼仪，避免触发速率限制。
  6. 最终生成一个CSV文件，可以用Excel或LibreCalc打开，方便排序和筛选。

给脚本执行权限并运行： 

chmod +x pwned_checker.sh
./pwned_checker.sh email_list.txt

6.3 API密钥管理与安全建议

API密钥是访问服务的凭证，必须妥善保管。

  • 不要硬编码在脚本或命令行历史中 ：如上所述，使用环境变量是更安全的方式。
  • 为密钥设置使用范围 ：如果API服务支持（如Have I Been Pwned的付费API），在创建密钥时，只授予其最小的必要权限（例如，只允许查询，不允许执行其他操作）。
  • 定期轮换密钥 ：定期在服务端生成新的API密钥，并替换旧密钥。
  • 使用密钥管理工具 ：对于更复杂的生产环境，可以考虑使用像 pass 、 gopass 或云服务商提供的密钥管理服务来存储和调用密钥。

最后，无论用哪种方式部署，都请务必遵守“Have I Been Pwned”服务的使用条款，不要进行高频、自动化的恶意查询。将这些工具和技术用于保护你自己和你拥有合法权限测试的系统的安全，这才是它们的价值所在。

Logo
亚马逊云科技技术品牌专区

更多推荐

cover

基于STM32的全屋环境智能监测与预警终端设计

avatar 亚马逊云科技技术品牌专区

Keras：面向人类的深度学习库

Keras3支持多后端（TensorFlow、PyTorch、JAX），通过设置环境变量切换，兼容指定版本。pip安装后可用Sequential API快速构建CNN模型，如MNIST分类示例，实

avatar 亚马逊云科技技术品牌专区

AI行业日报｜2026-09-25：5个热点事件

本期行业动态聚焦于端侧算力重构、自主智能体工作流、开发工具经济模型、网络隔离架构设计与公共部门合规审查。以下结合一线技术场景进行结构化梳理，供 AI 研究员与软件工程团队参考。 PrismML 正将其轻量级语言模型适配至搭载高通处理器的智能眼镜终端 1 。该平台的核心战略指向开源权重模型的本地化运行，旨在最大化挖掘穿戴设备现有算力的利用效率 1 。对于嵌入式与边缘计算开发者而言，此类微型模型向低功

avatar 亚马逊云科技技术品牌专区