praetorian-inc/pius

# Pius - 攻击面发现与 OSINT 侦察工具 [](https://github.com/praetorian-inc/pius/actions/workflows/ci.yaml) [](go.mod) [](LICENSE) [](https://goreportcard.com/report/github.com/praetorian-inc/pius) [](https://github.com/praetorian-inc/pius/releases) **Pius** 是一个用 Go 编写的开源攻击面发现工具。给定公司名称，它可以映射完整的外部攻击面：域名、子域名和 IP 范围（CIDR）。Pius 通过 23 个发现插件，查询证书透明度日志、所有五个区域互联网注册管理机构（ARIN, RIPE, APNIC, AFRINIC, LACNIC）、被动 DNS 数据库、WHOIS/RDAP、BGP 表等。 专为需要可靠、可重复资产发现的渗透测试人员、Bug 赏金猎人和安全团队构建。与临时的侦察脚本不同，Pius 是生产级的：并发插件执行、三阶段发现流水线、多层缓存、针对模糊结果的置信度评分、优雅降级以及被动优先的 OSINT 默认设置。 ## 目录 - [为什么选择 Pius：与 Amass 和 Subfinder 的对比](#why-pius-how-it-compares-to-amass-and-subfinder) - [功能特性](#features) - [快速入门](#quick-start) - [插件](#plugins) - [域名插件](#domain-plugins) - [CIDR 插件](#cidr-plugins) - [工作原理：三阶段发现流水线](#how-it-works-three-phase-discovery-pipeline) - [架构](#architecture) - [用法](#usage) - [基础发现](#basic-discovery) - [CIDR 发现](#cidr-discovery) - [输出格式](#output-formats) - [插件选择](#plugin-selection) - [配置](#configuration) - [常见问题](#faq) - [故障排除](#troubleshooting) - [贡献](#contributing) - [安全](#security) - [许可证](#license) ## 为什么选择 Pius：与 Amass 和 Subfinder 的对比 Pius 填补了子域名枚举工具（如 subfinder）和完整攻击面管理平台之间的空白。如果您需要从单个工具中获得**域名和 CIDR 发现**，并具备置信度评分和分阶段流水线，Pius 就是为此工作流程量身定制的。 | 特性 | Pius | amass | subfinder | |---------|------|-------|-----------| | 语言 | Go | Go | Go | | 单一二进制文件 | 是 | 是 | 是 | | RIR CIDR 发现 | 是（全部 5 个 RIR） | 部分 | 否 | | 分阶段流水线 | 是（handle → CIDR） | 否 | 否 | | 置信度评分 | 是 | 否 | 否 | | 默认被动模式 | 是 | 是 | 是 | | 缓存层 | 是（24小时） | 否 | 否 | ## 功能特性 ### 用例 - **渗透测试。** 在进行测试之前，映射组织的外部攻击面。 - **Bug 赏金侦察。** 从组织名称中发现范围内的域名和 IP 范围。 - **攻击面管理。** 利用被动优先的默认设置持续监控新资产。 - **红队行动。** 通过企业注册表（GLEIF, SEC EDGAR, Wikidata）识别子公司和关联基础设施。 ### 能力 | 特性 | 描述 | |---------|-------------| | **23 个发现插件** | 14 个域名插件 + 9 个 CIDR 插件，覆盖证书透明度、被动 DNS、WHOIS、RDAP、RPSL、BGP 表、favicon 哈希和子域名排列 | | **全部 5 个 RIR** | ARIN（北美）、RIPE（欧洲/中东）、APNIC（亚太）、AFRINIC（非洲）、LACNIC（拉丁美洲） | | **三阶段流水线** | 阶段 0 独立运行，阶段 1 发现 RIR 组织句柄，阶段 2 将句柄解析为 CIDR；后期插件利用已发现的资产丰富结果 | | **置信度评分** | 模糊的名称到资产映射会被评分并标记为待审查，而不是被静默丢弃 | | **多层缓存** | API 响应缓存 24 小时（JSON 格式）；RPSL 数据库缓存 24 小时（解压后的本地文件） | | **默认被动模式** | 默认仅查询 OSINT 来源；主动插件（DNS 暴力破解、区域传送）需自行选择启用 | | **灵活输出** | 终端表格、JSON 数组和 NDJSON（换行符分隔）格式 | | **单一二进制** | 基于 Go 的工具编译为一个可移植的可执行文件，无运行时依赖 | ## 快速入门 ### 安装 需要 Go 1.25.0 或更高版本。 ``` go install github.com/praetorian-inc/pius/cmd/pius@latest ``` 或从源代码构建： ``` git clone https://github.com/praetorian-inc/pius.git cd pius go build -o pius ./cmd/pius ``` ### 基础用法 ``` # 为组织发现域名和 CIDR（被动模式） pius run --org "Acme Corp" # 添加 domain hint 以解锁更多插件 pius run --org "Acme Corp" --domain acme.com # 包含主动插件（DNS brute-force, zone transfer） pius run --org "Acme Corp" --domain acme.com --mode all ``` ### 输出示例 ``` [domain] acme.com (crt-sh) [domain] api.acme.com (crt-sh) [domain] staging.acme.com (passive-dns) [domain] acme.com (reverse-whois) ⚠ needs-review [confidence:0.42] [cidr] 203.0.113.0/24 (arin) [cidr] 198.51.100.0/22 (ripe) ``` ### 列出可用插件 ``` pius list ``` ## 插件 ### 域名插件 所有域名插件在阶段 0（独立、并发）运行。它们输出发现的域名。 | 插件 | 数据源 | 需要认证 | 模式 | 备注 | |--------|-------------|---------------|------|-------| | `crt-sh` | 证书透明度日志 | 无 | 被动 | 对通配符条目进行去重 | | `apollo` | Apollo.io 丰富 API | `APOLLO_API_KEY` | 被动 | 缓存结果 24 小时；域名查询置信度为 0.85 | | `github-org` | GitHub 组织搜索 | `GITHUB_TOKEN`（可选） | 被动 | 置信度评分；发出阈值为 0.65 | | `gleif` | GLEIF LEI 企业注册表 | 无 | 被动 | 发现父/子公司域名 | | `passive-dns` | SecurityTrails 被动 DNS | `SECURITYTRAILS_API_KEY` | 被动 | 历史子域名记录 | | `reverse-whois` | ViewDNS 反向 WHOIS | `VIEWDNS_API_KEY` | 被动 | 置信度 0.75；注册人邮箱匹配 | | `dns-brute` | 本地 DNS 解析器 | 无 | **主动** | 50 个并发 goroutine；嵌入式字典 | | `dns-zone-transfer` | DNS AXFR | 无 | **主动** | 提取 A, AAAA, CNAME, MX, SRV 记录 | | `doh-enum` | DNS-over-HTTPS 解析器 | AWS 凭证（可选） | **主动** | 50 个并发 worker；轮询端点旋转；可选 API Gateway 部署以实现 IP 多样性 | | `favicon-hash` | Shodan + FOFA favicon 搜索 | `SHODAN_API_KEY`, `FOFA_API_KEY`（可选） | **主动** | favicon 的 MurmurHash3；发现 CDN 后的源 IP | | `dns-permutation` | 发现的子域名（阶段 0） | 无 | **主动** | 阶段 3；altdns 风格的排列；通配符过滤 | | `google-dorks` | Google Knowledge Graph | 无 | 被动 | 抓取子公司轮播 | | `reverse-ip` | PTR 记录, HackerTarget, ViewDNS | `VIEWDNS_API_KEY`（可选） | 被动 | 阶段 3；使用阶段 2 的 CIDR | | `wikidata` | Wikidata SPARQL | 无 | 被动 | P749/P355/P127 企业关系；24 小时缓存 | ### CIDR 插件 CIDR 发现使用多阶段流水线：阶段 0 直接发现 CIDR，阶段 1 发现 RIR 组织句柄，阶段 2 将句柄解析为 CIDR 块。 | 插件 | 阶段 | 数据源 | 协议 | RIR 覆盖范围 | |--------|-------|-------------|----------|--------------| | `asn-bgp` | 0（独立） | RIPE RIS BGP 表 | HTTP REST | 全球（已公告的前缀） | | `shodan` | 0（独立） | Shodan net: 搜索 | HTTP REST | 全球（需要 `SHODAN_API_KEY`） | | `whois` | 1（句柄发现） | 全部 5 个 RIR | HTTP REST | ARIN, RIPE, APNIC, AFRINIC, LACNIC | | `edgar` | 1（句柄发现） | SEC EDGAR 文件 | HTTP REST | 全球上市公司 | | `arin` | 2（解析） | ARIN RDAP | RDAP (RFC 7483) | 北美 | | `ripe` | 2（解析） | RIPE RDAP | RDAP (RFC 7483) | 欧洲、中东、中亚 | | `lacnic` | 2（解析） | LACNIC RDAP | RDAP (RFC 7483) | 拉丁美洲和加勒比地区 | | `apnic` | 2（解析） | APNIC RPSL 数据库 | 缓存的 gzip 文件 | 亚太地区 | | `afrinic` | 2（解析） | AFRINIC RPSL 数据库 | 缓存的 gzip 文件 | 非洲 | ## 工作原理：三阶段发现流水线 Pius 使用三阶段并发流水线来发现组织资产： ``` pius run --org "Acme Corp" --domain acme.com │ ▼ Plugin Registry (init() auto-registration) │ ┌──────────┴─────────────────────────────┐ │ Phase 0 (concurrent, independent) │ │ crt-sh apollo github-org gleif │ │ passive-dns reverse-whois │ │ dns-brute* dns-zone-transfer* │ │ doh-enum* favicon-hash* │ │ asn-bgp │ └──────────┬─────────────────────────────┘ │ Emits domains + CIDRs directly ┌──────────┴─────────────────────────────┐ │ Phase 1 (concurrent) │ │ whois edgar │ └──────────┬─────────────────────────────┘ │ Emits RIR org handles ▼ enrichWithHandles() Input.Meta["arin_handles"] = "ACME-1" Input.Meta["ripe_handles"] = "ORG-ACME-RIPE" │ ┌──────────┴─────────────────────────────┐ │ Phase 2 (concurrent) │ │ arin ripe apnic afrinic lacnic │ └──────────┬─────────────────────────────┘ │ Emits CIDR blocks ▼ enrichWithAssets() Input.Meta["cidrs"] = [...] Input.Meta["discovered_domains"] = [...] │ ┌──────────┴─────────────────────────────┐ │ Late-stage (concurrent, asset consumers)│ │ dns-permutation* reverse-ip │ └──────────┬─────────────────────────────┘ │ Emits additional domains ▼ filterOutput() (strips internal handle findings) │ ▼ Domains + CIDRs * active mode only ``` ### 发现流水线 1. **阶段 0（独立）**：无跨插件依赖的域名和 CIDR 插件从一开始就并发运行 2. **阶段 1（句柄发现）**：`whois` 查询所有 5 个 RIR 以获取组织句柄。`edgar` 模式匹配 SEC 文件 3. **句柄丰富**：发现的句柄按注册表分组并注入到流水线输入中 4. **阶段 2（句柄解析）**：RDAP 插件（ARIN, RIPE, LACNIC）获取每个句柄的 CIDR 块。RPSL 插件（APNIC, AFRINIC）解析本地缓存的注册表数据库 5. **资产丰富**：发现的 CIDR 和域名被注入到流水线输入中供后期消费者使用 6. **后期丰富**：`dns-permutation` 从发现的域名生成 altdns 风格的子域名变体。`reverse-ip` 对发现的 CIDR 执行 PTR 查找 7. **输出过滤**：内部 `cidr-handle` 发现被移除。只有域名和 CIDR 到达用户 ## 架构 ``` cmd/pius/ CLI entrypoint (Cobra-based) pkg/ cache/ Two-tier caching: API responses (JSON) + RPSL databases (gzip) cidr/ IP range → CIDR conversion and /24 subnet splitting client/ Shared HTTP client with retries and 10 MB response limit plugins/ Plugin interface, registry, confidence scoring all/ Blank imports to trigger all plugin init() registrations cidrs/ CIDR discovery plugin implementations domains/ Domain discovery plugin implementations runner/ Pipeline orchestration, mode filtering, output formatting ``` ### 关键设计决策 - **三阶段流水线**将 RIR 句柄发现（阶段 1）与 CIDR 解析（阶段 2）分离，从而实现准确的多 RIR 查找 - **插件式注册**使用 Go `init()` 函数。新插件无需更改 runner - **置信度评分**用于名称匹配模糊的插件（GitHub org 搜索、反向 WHOIS、Apollo），区分高置信度结果和需要人工审查的结果 - **两层缓存**针对不同的数据配置文件进行优化：小型 API 响应为 JSON（apollo, github-org），大型 RPSL 注册表转储为解压后的本地文件（APNIC, AFRINIC） - **全程优雅降级**。插件错误会被记录，但永远不会导致流水线失败；始终返回部分结果 ## 用法 ### 基础发现 ``` # 被动发现（默认）适用于持续监控，安全可靠 pius run --org "Acme Corp" # 添加 domain hint 以解锁 crt-sh, dns-brute, passive-dns, zone-transfer pius run --org "Acme Corp" --domain acme.com # 添加 ASN hint 以直接查询 BGP 表 pius run --org "Acme Corp" --asn AS12345 # 组合所有 hints pius run --org "Acme Corp" --domain acme.com --asn AS12345 ``` ### CIDR 发现 ``` # 通过全部 5 个 RIR 进行被动 CIDR 发现 pius run --org "Acme Corp" --mode passive --plugins whois,arin,ripe,apnic,afrinic,lacnic # 从 ASN 直接进行 BGP 查询（无需 handle 解析） pius run --org "Acme Corp" --asn AS12345 --plugins asn-bgp ``` ### DoH 子域名枚举 ``` # 使用嵌入式词表进行基础 DoH 枚举（Cloudflare, Google, AdGuard resolvers） pius run --domain acme.com --mode active --plugins doh-enum # 使用自定义词表 pius run --domain acme.com --mode active --plugins doh-enum --doh-wordlist /path/to/wordlist.txt # 使用自定义 DoH 服务器 pius run --domain acme.com --mode active --plugins doh-enum \ --doh-servers "https://dns.google.com/dns-query,https://cloudflare-dns.com/dns-query" # 跨 8 个 AWS 区域部署 API Gateways 以实现 IP 轮换（需要 AWS 凭证） pius run --domain acme.com --mode active --plugins doh-enum \ --doh-servers "https://dns.google.com/dns-query,https://cloudflare-dns.com/dns-query" \ --doh-deploy-gateways # 使用预先存在的 API Gateway URL pius run --domain acme.com --mode active --plugins doh-enum \ --doh-gateways "https://abc123.execute-api.us-east-1.amazonaws.com/pius" ``` ### 输出格式 ``` # 终端表格（默认）- 人类可读 pius run --org "Acme Corp" # JSON array - 结构化输出，便于解析 pius run --org "Acme Corp" --output json # NDJSON - 每行一个对象，适合流式传输/管道操作 pius run --org "Acme Corp" --output ndjson # 通过管道将 NDJSON 传递给 jq 进行过滤 pius run --org "Acme Corp" --output ndjson | jq 'select(.type == "cidr")' ``` ### 插件选择 ``` # 仅运行特定插件 pius run --org "Acme Corp" --plugins crt-sh,apollo,arin # 禁用特定插件（运行所有其他插件） pius run --org "Acme Corp" --disable edgar,dns-brute # 主动模式 - 包含 DNS brute-force 和 zone transfer pius run --org "Acme Corp" --domain acme.com --mode active # 所有模式 - 被动 + 主动结合 pius run --org "Acme Corp" --domain acme.com --mode all # 调整并发数（默认：5） pius run --org "Acme Corp" --concurrency 10 ``` ## 配置 ### 环境变量 需要 API 密钥的插件在运行前会在 `Accepts()` 中检查它们。如果缺少环境变量，插件将被静默跳过。 | 变量 | 插件 | 必需 | 备注 | |----------|--------|----------|-------| | `APOLLO_API_KEY` | `apollo` | 是 | Apollo.io API 密钥 | | `GITHUB_TOKEN` | `github-org` | 否 | 将速率限制从 60 提高到 5000 请求/小时 | | `SECURITYTRAILS_API_KEY` | `passive-dns` | 是 | SecurityTrails API 密钥 | | `VIEWDNS_API_KEY` | `reverse-whois` | 是 | ViewDNS.info API 密钥 | | `SHODAN_API_KEY` | `favicon-hash` | 是 | Shodan API 密钥 | | `FOFA_API_KEY` | `favicon-hash` | 否 | FOFA API 密钥；启用额外的扫描器 | | `VIEW_API_KEY` | `reverse-ip` | 否 | ViewDNS.info API 密钥；启用额外的反向 IP 源 | | AWS 凭证 | `doh-enum` | 否 | 仅在使用 `--doh-deploy-gateways` 时需要 | ### 缓存 Pius 自动在 `~/.pius/cache/` 下缓存数据。无需配置。 | 缓存类型 | 使用者 | TTL | 格式 | |-----------|---------|-----|--------| | API 响应缓存 | `apollo`, `github-org` | 24 小时 | 每个键一个 JSON | | RPSL 注册表数据库 | `apnic`, `afrinic` | 24 小时 | 解压后的 gzip | 清除缓存： ``` rm -rf ~/.pius/cache/ ``` ### CLI 参考 ``` Usage: pius run [flags] pius list run flags: -o, --org string Organization name to search (required) -d, --domain string Known domain hint (optional) --asn string Known ASN hint, e.g. AS12345 (optional) --plugins string Comma-separated plugin whitelist (default: all) --disable string Comma-separated plugin blacklist --concurrency int Max concurrent plugins (default: 5) -f, --output string Output format: terminal, json, ndjson (default: terminal) --mode string Plugin mode: passive, active, all (default: passive) --doh-wordlist string Path to subdomain wordlist for DoH enumeration --doh-servers string Comma-separated DoH server URLs --doh-gateways string Comma-separated AWS API Gateway URLs for DoH --doh-deploy-gateways Auto-deploy AWS API Gateways for IP rotation ``` **退出码：** | 代码 | 含义 | |------|---------| | 0 | 成功，发现完成 | | 1 | 运行时错误 | ## 常见问题 ### 哪些 Pius 插件在默认没有 API 密钥的情况下运行？ 所有接受所提供输入的被动插件默认都会运行。如果有 API 密钥要求的被动插件（apollo, passive-dns, reverse-whois）的环境变量未设置，则会被静默跳过。主动插件（dns-brute, dns-zone-transfer, doh-enum, favicon-hash）仅在 `--mode active` 或 `--mode all` 时运行。 ### Pius 如何发现 IP 范围和 CIDR？ 阶段 0 插件（域名插件 + asn-bgp）立即并发运行。阶段 1 插件（whois, edgar）从公司名称发现 RIR 组织句柄。然后 runner 将这些句柄作为元数据注入输入中，阶段 2 插件（arin, ripe, apnic, afrinic, lacnic）将每个句柄解析为 CIDR 块。这种分离实现了准确的多 RIR 覆盖，同时保持插件松散耦合。 ### `needs-review` 置信度标志意味着什么？ 某些插件使用置信度评分对模糊匹配进行排名。例如，`github-org` 根据名称相似度和域名匹配对组织候选者进行评分。置信度在 0.35 到 0.65 之间的发现会带有 `needs-review` 标志发出，而不是被静默丢弃。低于 0.35 的发现作为噪声被丢弃。 ### 如何编写自定义 Pius 插件？ 1. 在 `pkg/plugins/domains/` 或 `pkg/plugins/cidrs/` 中创建一个 Go 文件 2. 实现 `plugins.Plugin` 接口（7 个方法：`Name`, `Description`, `Category`, `Phase`, `Mode`, `Accepts`, `Run`） 3. 在 `init()` 函数中注册： func init() { plugins.Register("my-plugin", func() plugins.Plugin { return &MyPlugin{client: client.New()} }) } 4. 在 `pkg/plugins/all/all.go` 中导入该包 请参阅现有插件（如 `crt_sh.go` 或 `arin.go`）以获取参考实现。 ### Pius 可以在没有任何 API 密钥的情况下运行吗？ 可以。以下插件不需要认证，仅需 `--org` 即可运行： - `crt-sh`（需要 `--domain`） - `gleif` - `whois` - `edgar` - `arin`, `ripe`, `apnic`, `afrinic`, `lacnic` - `asn-bgp`（需要 `--asn`） - `github-org`（可选 `GITHUB_TOKEN`） - `wikidata` - `google-dorks` 主动插件（`dns-brute`, `dns-zone-transfer`, `doh-enum`）也不需要认证，但必须使用 `--mode active` 启用。注意：`doh-enum` 默认使用嵌入式字典；仅在 `--doh-deploy-gateways` 时才需要 AWS 凭证。`favicon-hash` 插件需要 `SHODAN_API_KEY`。 ### RDAP 和 RPSL 在 IP 范围发现方面有什么区别？ RDAP 插件（arin, ripe, lacnic）向每个注册表的 RDAP API 发出实时 HTTP 查询。每个句柄发出一个请求。RPSL 插件（apnic, afrinic）每天一次将完整的注册表数据库作为 gzip 文件下载并在本地解析。RPSL 在初始下载后提供更低的延迟；RDAP 提供更新的数据。 ## 故障排除 ### 无 CIDR 结果 **原因**：阶段 1 插件未找到 RIR 句柄，或句柄未返回 CIDR。 **解决方案**： 1. 尝试组织名称的替代拼写：`--org "Acme Corporation"` vs `--org "Acme Corp"` 2. 检查 `whois` 或 `edgar` 是否运行：使用 `--plugins whois` 进行隔离 3. 验证组织是否拥有 RIR 分配（某些组织使用云提供商空间） ### 无域名结果 **原因**：缺少域名提示，或未设置 API 密钥。 **解决方案**： 1. 添加 `--domain` 以解锁 crt-sh 和 DNS 插件 2. 为这些插件设置 `APOLLO_API_KEY`, `SECURITYTRAILS_API_KEY` 或 `VIEWDNS_API_KEY` 3. 运行 `pius list` 以确认注册了哪些插件 ### APNIC/AFRINIC 结果过时 **原因**：RPSL 数据库缓存在其 24 小时 TTL 内。 **解决方案**： ``` rm ~/.pius/cache/*.rpsl pius run --org "Acme Corp" ``` ### 来自 GitHub 的速率限制 **原因**：未设置 `GITHUB_TOKEN`；未认证请求限制为 60 次/小时。 **解决方案**： ``` export GITHUB_TOKEN="ghp_..." pius run --org "Acme Corp" ``` ### CIDR 发现速度慢 **原因**：跨多个注册表每个句柄有多个 RDAP 请求。 **解决方案**：降低并发性或限制为特定注册表： ``` # 仅查询 ARIN（如果组织位于美国则更快） pius run --org "Acme Corp" --plugins whois,arin ``` ## 贡献 我们欢迎贡献。要添加新插件： 1. 在适当的包（`domains/` 或 `cidrs/`）中创建插件文件 2. 实现 `Plugin` 接口 - 需要 7 个方法 3. 通过 `init()` 注册并在 `pkg/plugins/all/all.go` 中添加空白导入 4. 编写涵盖 `Accepts()`, `Run()`, 错误路径和缓存（如适用）的单元测试 5. 遵循现有的错误处理约定： - 瞬态故障 → 返回 `(nil, nil)`（优雅降级） - 解析错误 → 返回带有上下文的包装错误 - 使用 `slog.Warn()` 记录部分失败 ### 开发 ``` # 运行所有测试 go test ./... # 运行特定包测试 go test ./pkg/plugins/domains/... -v # 构建二进制文件 go build -o pius ./cmd/pius # 安装到 $GOPATH/bin go install ./cmd/pius ``` ## 安全 Pius 专为**授权的安全测试和资产发现**而设计。 - Pius 为您指定的组织发送 DNS 查询和 API 请求。您必须始终确保拥有授权 - 主动插件（`dns-brute`, `dns-zone-transfer`）生成发往目标名称服务器的网络流量 - 切勿针对您不拥有或未获得明确评估许可的组织运行 通过 [GitHub Issues](https://github.com/praetorian-inc/pius/issues) 报告安全问题。 ## 许可证 [Apache 2.0](LICENSE) - Praetorian Security, Inc. **由 [Praetorian](https://www.praetorian.com/) 构建。** 专注于攻击面管理、渗透测试和安全工程方面的进攻性安全专家。

标签：ASN, CIDR, ESC4, GitHub, Golang, IP地址扫描, OSINT, WHOIS查询, 互联网资产测绘, 侦察工具, 动态调用, 协议探测, 域名枚举, 子域名挖掘, 安全编程, 实时处理, 数据展示, 日志审计, 红队, 网络安全, 被动DNS, 证书透明度, 进程管理, 隐私保护