LPO26/FalconHostSearch
GitHub: LPO26/FalconHostSearch
一款只读命令行工具，整合 CrowdStrike Falcon 端点数据与 Tenable 漏洞数据，支持按多种维度搜索主机并关联展示漏洞、端口、应用、检测结果和威胁情报。
Stars: 0 | Forks: 0
# FalconHostSearch.py
一款命令行工具，可通过 IP、主机名、操作系统/类型或登录用户在 **CrowdStrike Falcon** 中搜索主机，并可选择性地从 Tenable 提取每台主机的 **漏洞和开放端口**、获取其 **已安装的应用程序**（CrowdStrike Discover）以及其 **最近的检测结果**（CrowdStrike Alerts API）。它还可以独立查询 **CrowdStrike 威胁情报**（参与者和报告），而完全不需要进行主机搜索。
该工具是 **只读** 的。它只负责搜索和显示信息，绝不会对主机执行任何操作。
## 环境要求
- Python 3.8+
- 两个依赖包：
```
pip install crowdstrike-falconpy requests
```
`requests` 仅用于 Tenable 查询 (`--vulns`)；该工具的其余功能在没有它的情况下也能正常运行。
## 设置
凭据将从环境变量中读取——脚本中不会存储任何信息。
**CrowdStrike（始终需要）：**
| 变量 | 说明 |
| --- | --- |
| `FALCON_CLIENT_ID` | API client ID |
| `FALCON_CLIENT_SECRET` | API client secret |
| `FALCON_CLOUD` | 可选。`us1`（默认）、`us2`、`eu1` 或 `usgov1` |
**Tenable（仅在指定 `--vulns` 或 `--ports` 时需要）：**
| 变量 | 说明 |
| --- | --- |
| `TIO_ACCESS_KEY` | Tenable access key |
| `TIO_SECRET_KEY` | Tenable secret key |
设置方法：
```
# Windows PowerShell
$env:FALCON_CLIENT_ID="your-client-id"
$env:FALCON_CLIENT_SECRET="your-client-secret"
$env:TIO_ACCESS_KEY="your-access-key"
$env:TIO_SECRET_KEY="your-secret-key"
```
```
# macOS / Linux
export FALCON_CLIENT_ID="your-client-id"
export FALCON_CLIENT_SECRET="your-client-secret"
export TIO_ACCESS_KEY="your-access-key"
export TIO_SECRET_KEY="your-secret-key"
```
### 必需的 API 权限范围（保持只读）
- **Falcon：** `Hosts: READ`（登录用户列还会使用主机登录历史记录，这也包含在 Hosts: READ 权限中）。对于 `--apps`，还需要 `Discover: READ`。对于 `--detections`，还需要 `Alerts: READ`。对于情报相关的参数，还需要 `Actors (Falcon Intelligence): READ` / `Reports (Falcon Intelligence): READ`。
- **Tenable：** 拥有 Basic / **Can View** 权限的用户即可满足要求。
## 用法
```
python FalconHostSearch.py [TERM ...] [--user NAME] [--vulns] [--min-severity LEVEL] [--ports] [--apps]
[--detections] [--intel-actors [QUERY]] [--intel-reports [QUERY]]
[--report ID] [--report-pdf ID]
[--days N] [--no-login] [--aid] [--md]
```
你必须提供一个搜索词（IP / 主机名 / 操作系统）、`--user NAME`，**或者**其中一个威胁情报参数——情报参数可以独立运行，无需搜索主机。
## 四种搜索方式
### 1. 通过 IP
类似于 IPv4 地址的值将匹配本地或外部 IP。
```
python FalconHostSearch.py 10.50.10.24
```
### 2. 通过主机名
任何自由文本搜索词都会与主机名进行不区分大小写的 *包含* 匹配。
```
python FalconHostSearch.py web01
```
### 3. 通过操作系统 / 类型
- 平台关键字——`Windows`、`Linux`、`Mac`——将返回该平台上的所有主机。
- 添加类型关键字会根据设备类型缩小范围：`Server`、`Workstation` 或 `Domain Controller`。
- 特定的操作系统字符串将与操作系统版本进行匹配。
```
python FalconHostSearch.py Windows # all Windows hosts
python FalconHostSearch.py "Windows Server" # only Windows servers
python FalconHostSearch.py "Windows Workstation" # only Windows workstations
python FalconHostSearch.py server # all servers, any platform
python FalconHostSearch.py Ubuntu # OS version contains "Ubuntu"
```
### 4. 通过登录用户（`--user`）
返回指定用户最近登录过的主机。这会读取 **与 `LAST LOGIN USER` 列中显示的相同数据**，因此您在主机搜索中看到的内容就是 `--user` 会查找的内容。
```
python FalconHostSearch.py --user john # any host john logged into
python FalconHostSearch.py --user john "Windows" # scoped to Windows hosts (faster)
```
- 匹配的是 **片段**（例如 `john`），而不是完整的 `DOMAIN\user` 字符串。
- `--user` 之后的可选搜索词会将搜索 **限定** 在这些主机范围内，从而保持查询速度（参见性能说明）。
## 选项
| 参数 | 说明 |
| --- | --- |
| `--user NAME` | 查找该用户最近登录过的主机。匹配 `LAST LOGIN USER` 列。 |
| `--vulns` | 同时从 Tenable 提取每台匹配主机的漏洞。 |
| `--min-severity LEVELS` | 选择要显示的 Tenable 严重级别。指定单个级别 = 该级别 **及以上** (`--min-severity medium`)。以逗号分隔的列表 = **仅这些级别** (`--min-severity critical,high`)。可用级别：`critical`、`high`、`medium`、`low`、`info`；默认显示全部。影响表格和严重程度统计。 |
| `--ports` | 同时显示 Tenable 中每台匹配主机的开放端口。 |
| `--apps` | 同时显示来自 CrowdStrike Discover 的每台匹配主机的已安装应用程序。 |
| `--detections` | 同时显示每台匹配主机在 `--days` 时间窗口内的最近检测结果（CrowdStrike Alerts API）。 |
| `--intel-actors [QUERY]` | 威胁情报：列出参与者，或通过关键字搜索。独立运行——无需搜索主机。 |
| `--intel-reports [QUERY]` | 威胁情报：列出报告，或通过关键字搜索。独立运行——无需搜索主机。列表会显示每个报告的 ID。 |
| `--report ID` | 在终端中阅读一份情报报告：元数据、相关的参与者/行业以及完整报告文本。 |
| `--report-pdf ID` | 将一份情报报告作为 `intel-report-ID.pdf` 保存在当前目录中。 |
| `--days N` | Tenable 的回溯时间窗口，单位为天（默认 `90`）。仅与 `--vulns` 一起使用。 |
| `--no-login` | 跳过 Falcon 登录用户查询，以更快地获取主机列表。（在 `--user` 模式下会被忽略，因为该模式下的登录数据本身就是搜索目标。） |
| `--aid` | 同时显示 Falcon Agent ID（设备 ID）列。 |
| `--md`, `--markdown` | 输出 Markdown 格式而不是彩色表格——非常适合保存到文件中。 |
## 示例
```
# Host 列表
python FalconHostSearch.py "Windows Server"
python FalconHostSearch.py 10.50.10.0 # partial IP / hostname fragment
python FalconHostSearch.py linux server
# 用户查找
python FalconHostSearch.py --user maria
python FalconHostSearch.py --user svc-backup --aid
# 带有 Tenable 漏洞和/或开放端口
python FalconHostSearch.py web01 --vulns
python FalconHostSearch.py web01 --ports
python FalconHostSearch.py web01 --apps
python FalconHostSearch.py web01 --detections
python FalconHostSearch.py 10.50.10.24 --detections --days 30
python FalconHostSearch.py web01 --ports --vulns --apps --detections
# Threat intel（独立运行；无需主机搜索）
python FalconHostSearch.py --intel-actors
python FalconHostSearch.py --intel-actors "bear"
python FalconHostSearch.py --intel-reports "ransomware"
python FalconHostSearch.py --report 41712 # read a report in the terminal
python FalconHostSearch.py --report 41712 --md > report.md
python FalconHostSearch.py --report-pdf 41712 # save the official PDF
python FalconHostSearch.py web01 --detections --intel-reports # can combine
python FalconHostSearch.py 10.50.10.24 --vulns --days 180
python FalconHostSearch.py web01 --vulns --min-severity medium # medium and above
python FalconHostSearch.py web01 --vulns --min-severity critical,high --ports # only those levels
python FalconHostSearch.py --user john --vulns
# Markdown 输出（保存到文件）
python FalconHostSearch.py "Windows Server" --md > servers.md
python FalconHostSearch.py --user john --vulns --md > john_report.md
```
## 理解输出内容
### 主机表格
列：`HOSTNAME`、`LOCAL IP`、`OS VERSION`、`TYPE`（Server / Workstation / Domain Controller）、`MANUFACTURER`、`LAST LOGIN USER`、`LAST SEEN` 和 `AID`（仅在指定 `--aid` 时显示）。
### 漏洞（`--vulns`）
在主机表格下方，每台主机都会有一个显示以下内容的段落：
- 其 **Tenable 标签**（例如 `Owner:InfraSec`），
- 一个 **严重程度统计**（Critical / High / Medium / Low / Info 以及总数），
- 一个结果表格：严重程度、plugin ID、漏洞名称和 plugin family。使用 `--min-severity` 控制要显示的严重级别：单个级别表示该级别及以上（`medium`），以逗号分隔的列表表示仅显示这些级别（`critical,high`——任何组合都可以，甚至是非连续的如 `critical,low`）；统计和标题注释会提示有多少结果被隐藏了。
每个 Falcon 主机在 Tenable 中的匹配方式是 **先匹配主机名，再匹配 IP**。如果一台主机存在于 Falcon 但不存在于 Tenable，会打印出 *"Not found in Tenable"*，然后程序会继续运行。
### 开放端口（`--ports`）
对于每台匹配的主机，显示 Tenable 检测到的开放端口，格式为 `端口/协议`，并在已知情况下在括号内显示服务名称（例如 `443/tcp (www)`）。端口数据来源于 Tenable 的端口扫描器和服务检测结果，因此它们反映的是最近的一次扫描——未被扫描（或没有网络扫描数据）的主机不会显示任何内容。`--ports` 和 `--vulns` 可以一起使用或单独使用；两者都需要提供 Tenable 密钥。
### 已安装的应用程序（`--apps`）
对于每台匹配的主机，以 `名称 版本 (供应商)` 的格式列出已安装的应用程序，数据来源于 **CrowdStrike Discover**（权限范围 `Discover: READ`，使用相同的 Falcon 密钥），并限定在该主机范围内。如果 Discover 不可用（未授权 / 没有权限范围）或该主机没有应用程序，则会输出相应提示。此功能需要 Falcon Discover；它不使用 Tenable。
### 检测结果（`--detections`）
对于每台匹配的主机，显示其来自 **CrowdStrike Alerts API** 的最近检测结果（旧版 Detects API 已于 2025 年 9 月停用，因此需要 `Alerts: READ` 权限范围）：严重程度、日期、检测名称、战术/技术以及状态，按时间倒序排列，限定在 `--days` 时间窗口内。每台主机最多显示最新的 20 条记录，如果还有更多，则会显示总数。
### 威胁情报（`--intel-actors`, `--intel-reports`）
针对 **Falcon Intelligence** 的独立查询——无需进行主机搜索。如果不指定值，它们会列出最近的条目；如果指定关键字，它们会执行搜索（`--intel-actors "bear"`）。参与者会显示来源、目标行业和最后活动日期；报告会显示 **ID**、类型和发布日期。这些功能需要 Intel 订阅和相应的 `READ` 权限范围，否则会清晰地打印出“无访问权限”的提示。
**阅读报告：** 从列表中获取一个 ID，并使用 `--report ID` 在终端中阅读它——类型、发布日期、相关的参与者、目标行业/国家、动机、Falcon 控制台中报告的链接，以及完整的报告文本（API 的富文本 HTML 会被转换为纯文本）。`--report-pdf ID` 会将官方 PDF 下载为 `intel-report-ID.pdf`。某些报告类型没有内嵌文本；输出时会提示这一点，而 PDF 包含了完整的文档。两者使用的都是与列表相同的 `Reports (Falcon Intelligence): READ` 权限范围——依然是只读的。
### Markdown 模式（`--md`）
生成整洁的 Markdown——一个主机表格以及针对每台主机的漏洞表格——不包含任何颜色代码。它可以在 GitHub、Obsidian 或任何 Markdown 查看器中渲染为真实的表格。使用 `>` 可将其重定向到文件中。
## 性能说明
- **缩小范围搜索非常快；全网搜索负担较重。** 特定的主机名、IP 或 `"Windows Server"` 会迅速返回结果。匹配数千台主机的广泛搜索词会为所有这些主机提取详细信息（和登录历史记录）。
- **用户搜索存在取舍。** Falcon 没有针对登录用户的服务端过滤功能，因此 `--user` 会提取候选主机并在本地进行匹配。使用搜索词（例如 `--user john "Windows"`、子网等）限定范围可以保持查询速度；单独使用 `--user john` 会扫描整个集群并打印出提示。当您的设备记录中已经包含了最后登录的用户时，它会跳过针对每台主机的登录历史记录调用。
- **`--vulns` 会为每台匹配的主机调用一次 Tenable。** 请将其与范围较窄的搜索配合使用，而不是全网搜索。
- **`--ports` 会为每台主机增加几次 Tenable 调用**（它会读取端口扫描结果的输出），因此也最好与范围较窄的搜索配合使用。
- **`--apps` 和 `--detections` 也会针对每台主机进行查询**（Discover / Alerts 限定在每台主机上），因此也应与范围较窄的搜索配合使用。情报相关的参数无论涉及多少主机，都只进行一次查询。
- **`--no-login`** 会跳过登录用户查询，以尽可能快地获取主机列表。
## 故障排除
| 症状 | 可能的原因 / 解决方法 |
| --- | --- |
| `Set FALCON_CLIENT_ID and FALCON_CLIENT_SECRET...` | Falcon 环境变量未在此 shell 中设置。 |
| `--vulns needs Tenable keys...` | 未设置 `TIO_ACCESS_KEY` / `TIO_SECRET_KEY`。 |
| `Falcon API error` / 认证失败 | 检查 client ID/secret、`FALCON_CLOUD` 区域，并确保该客户端拥有 `Hosts: READ` 权限。 |
| `Tenable auth failed (HTTP 401/403)` | 检查 Tenable 密钥并确保用户具有查看权限。 |
| `"Windows Server"` 未返回任何结果 | 您的租户可能对该类型的标记方式不同——运行普通的 `Windows` 搜索并查看 `TYPE` 列，以了解正在使用的确切值。 |
| 某台主机的 `LAST LOGIN USER` 为空 | 该主机在 Falcon 的保留时间窗口内没有最近的交互式登录（例如，仅作为服务运行的服务器）。 |
| `--ports` 在某台主机上未显示任何内容 | 该主机在时间窗口内未进行过网络/端口扫描，或者 Tenable 中没有该主机的端口扫描记录。 |
| `--apps` 提示“Discover not available” | 您的 API client 缺少 `Discover: READ` 权限范围，或者该租户未获得 Discover 授权。 |
| `--apps` 在某台主机上未显示应用程序 | Discover 中没有该主机的应用程序记录。 |
|--detections` 提示“no access” | 请将 `Alerts: READ` 权限范围添加到您的 API client 中（检测结果已移至 Alerts API）。 |
| 情报参数提示“no access” | 您的客户端缺少 Falcon Intelligence `READ` 权限范围，或者该租户没有 Intel 订阅。 |
| `--report` 未显示文本 | 该报告类型没有内嵌正文；使用 `--report-pdf ID` 可获取完整文档。 |
| `--user NAME` 未找到您期望的结果 | 尝试搜索更短的片段；存储的值通常包含域名前缀或采用了不同的账户名格式。 |
| 主机在 Falcon 中显示，但提示 `Not found in Tenable` | 该主机的名称/IP 在这两个系统中不一致，或者它不在 Tenable 中。 |
## 备注
- **只读：** 该工具不会执行任何容器隔离、扫描或其他任何操作——它只负责搜索和显示。
- 终端中的输出带有颜色；使用 `--md` 可输出纯 Markdown。
标签：GPT, Python, 威胁情报, 字符串匹配, 开发者工具, 插件系统, 数据泄露, 无后门, 漏洞管理, 终端安全管理, 资产盘点, 逆向工具