panther-labs/panther-analysis

内置 Panther 检测规则

Panther 部署 | CLI 文档

Panther 是一款专为大规模安全操作构建的现代 SIEM。 借助 Panther，团队可以将检测规则定义为代码，并通过编程方式将其上传到您的 Panther 部署中。该仓库包含了由 Panther 团队和社区开发的所有检测规则。 我们欢迎所有贡献！请在提交 Pull Request 之前阅读[贡献指南](https://github.com/panther-labs/panther-analysis/blob/main/CONTRIBUTING.md)。 # 快速开始 ## 克隆仓库 ``` git clone git@github.com:panther-labs/panther-analysis.git cd panther-analysis ``` ### 仓库结构 包含检测规则的文件夹按照日志类型以 `_` 的格式进行组织： - **Rules** 分析[日志](https://docs.panther.com/data-onboarding/supported-logs)以检测恶意活动 - **Policies** 表示[资源](https://docs.panther.com/cloud-scanning)的期望安全状态，以检测安全配置错误 - **Scheduled rules** 分析定期执行的 [SQL 查询](https://docs.panther.com/data-analytics/example-queries)的输出 ## 配置 Python 环境 ``` python3 -m pip install pipenv echo "PYTHON_BIN_PATH=\"$(python3 -m site --user-base)/bin\"" >> ~/.zprofile echo "export PATH=\"$PATH:$PYTHON_BIN_PATH\"" >> ~/.zprofile . ~/.zprofile make install pipenv shell # Optional, this will spawn a subshell containing pipenv environment variables. Running pipenv run before commands becomes optional after this step ``` ## 代码格式化和 Linting (Pre-commit Hooks) 该仓库使用 pre-commit hooks 在代码提交前自动进行格式化和 linting。这确保了代码的一致性，并有助于尽早发现潜在错误。 ### 设置 运行 `make install`（如“配置 Python 环境”部分所述）会安装所有必要的依赖项，包括 `pre-commit`。 初始设置完成后，您需要通过运行以下命令来一次性安装 Git hooks： ``` make install-pre-commit-hooks ``` ### 用法 安装完成后，每次运行 `git commit` 时，pre-commit hooks 都会自动运行。 - 如果进行了任何格式化更改或发现 linting 错误，提交将被中止。 - 查看格式化工具（例如 `black`、`isort`）所做的更改。 - 修复任何报告的 linting 错误（例如由 `flake8`、`pylint` 报告的）。 - 暂存更改（`git add .`）并再次运行 `git commit`。 您也可以使用 Make 命令在所有文件上手动运行 hooks： ``` make run-pre-commit-hooks ``` 这对于检查整个代码库或在更改 pre-commit 配置后非常有用。 ### 安装依赖并运行您的第一个测试 ``` make install pipenv run panther_analysis_tool test --path rules/aws_cloudtrail_rules/ ``` ### 运行检测测试 ``` pipenv run panther_analysis_tool test [-h] [--path PATH] [--filter KEY=VALUE [KEY=VALUE ...] [--debug] ``` ### 使用特定路径进行测试 ``` pipenv run panther_analysis_tool test --path rules/cisco_umbrella_dns_rules ``` ### 按严重程度测试 ``` pipenv run panther_analysis_tool test --filter Severity=Critical ``` ### 按日志类型测试 ``` pipenv run panther_analysis_tool test --filter LogTypes=AWS.GuardDuty ``` ### 创建检测规则的 zip 文件 ``` pipenv run panther_analysis_tool zip [-h] [--path PATH] [--out OUT] [--filter KEY=VALUE [KEY=VALUE ...]] [--debug] ``` ### 打包所有严重级别为 Critical 的检测规则 ``` pipenv run panther_analysis_tool zip --filter Severity=Critical ``` ### 上传检测规则到您的 Panther 实例 ``` # 注意：API token 和 host 也可以设置为环境变量： # - PANTHER_API_TOKEN # - PANTHER_API_HOST pipenv run panther_analysis_tool upload [-h] [--path PATH] [--out OUT] [--filter KEY=VALUE [KEY=VALUE ...]] [--debug] --api-key YOUR_PANTHER_API_KEY --api-token YOUR_PANTHER_API_HOST ``` 全局辅助函数定义在 `global_helpers` 文件夹中。这是一个硬编码的位置，不能更改。但是，您可以在此路径下创建任意数量的文件。只需通过指定的 `GlobalID` 将它们导入到您的检测规则中即可。 此外，检测规则组可以链接到多个“Reports”，这是一个用于跟踪 CIS、PCI、MITRE ATT&CK 等框架的系统。 ## 使用 [Visual Studio Code](https://code.visualstudio.com/) 如果您习惯使用 Visual Studio Code IDE，`make vscode-config` 命令可以配置 VSCode 以配合此仓库工作。 除了此命令外，您还需要安装以下 vscode 插件： 1. [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) 2. [Black Formatter](https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter) 3. [Pylint](https://marketplace.visualstudio.com/items?itemName=ms-python.pylint) 4. [Bandit](https://marketplace.visualstudio.com/items?itemName=nwgh.bandit) 5. [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml) 您还需要配置 Visual Studio 的 [code](https://code.visualstudio.com/docs/setup/mac#_launching-from-the-command-line) 命令，以便能够从 CLI 打开 Visual Studio。 `make vscode-config` 将配置以下内容： 1. 配置 VSCode 使用此仓库的 Python 虚拟环境。 2. 解析像 global_helpers 这样的本地导入，从而允许通过 Intellisense/Pylance 进行代码补全。 3. 创建两个调试目标，这将为您提供一键支持，以便通过调试器运行 `panther_analysis_tool test`。 4. 为 `schemas/` 目录中的自定义 panther-analysis schemas 安装 JSONSchema 支持。这带来了关于 schemas/custom-schema.yml 文件中哪些字段是必需的 IDE 提示。 5. 为 `rules/` 目录中的 panther-analysis 规则安装 JSONSchema 支持。这带来了关于 rules/my-rule.yml 文件中哪些字段是必需的 IDE 提示。 6. 配置 `Black` 和 `isort` 设置以在保存时自动格式化（从而减少对所有文件运行 `make fmt` 的需要）。 7. 配置 `pylint` 设置以便在更改时进行 linting - 确保用户级 VSCode 设置中存在 `"pylint.lintOnChange": true`（`Cmd+Shift+P` -> `Preferences: Open Settings (JSON)`）。 8. 配置 `Bandit` 设置以便在打开文件时进行 linting ``` user@computer:panther-analysis: make vscode-config ``` ## 使用 Docker 要使用 Docker，您可以运行提供的一些 `make` 命令来执行常见的 panther-analysis 工作流。首先构建容器，然后您可以从创建的镜像中运行任何您想要的命令。如果您想运行不同的命令，请遵循 Makefile 中的模式。 ``` make docker-build make docker-test make docker-lint ``` 请注意，只有在更新 `Pipfile.lock` 更改时才需要重新构建容器，因为依赖项是在构建镜像时安装的。后续的测试和 lint 命令通过挂载当前文件系统目录在镜像中运行，因此它使用的是您的本地文件系统。 ## 使用 Windows 如果您使用的是 Windows 机器，可以使用以下说明执行标准的 panther-analysis 工作流。 1. 为 Windows 安装 [docker desktop](https://docs.docker.com/desktop/install/windows-install/)。 2. 建议使用 `make`。如果您想使用 `make`，首先安装 [chocolately](https://chocolatey.org/install)，这是一个标准的 Windows 包管理器。 3. 使用 chocolately 安装 make 命令： choco install make 4. `make` 现在应该已安装并添加到您的 PATH 中。尝试运行 `make docker-build` 来开始。 # 编写检测规则 _有关编写检测规则的完整参考，请阅读我们的[指南](https://docs.panther.com/writing-detections)！_ 每个检测规则都有一个 Python 文件（`.py`）和一个同名的元数据文件（`.yml`）（位于同一位置），例如： 示例检测规则：`okta_brute_force_logins.py` ``` def rule(event): return (event.get('outcome', {}).get('result', '') == 'FAILURE' and event.get('eventType') == 'user.session.start') def title(event): return 'Suspected brute force Okta logins to account {} due to [{}]'.format( event.get('actor', {}).get('alternateId', 'ID_NOT_PRESENT'), event.get('outcome', {}).get('reason', 'REASON_NOT_PRESENT') ) ``` 示例检测元数据：`okta_brute_force_logins.yml` ``` AnalysisType: rule Filename: okta_brute_force_logins.py RuleID: "Okta.BruteForceLogins" DisplayName: "Okta Brute Force Logins" Enabled: true LogTypes: - Okta.SystemLog Tags: - Identity & Access Management Severity: Medium --- Threshold: 5 DedupPeriodMinutes: 15 SummaryAttributes: - eventType - severity - displayMessage - p_any_ip_addresses Tests: - Name: Failed login ExpectedResult: true Log: { "eventType": "user.session.start", "actor": { "id": "00uu1uuuuIlllaaaa356", "type": "User", "alternateId": "panther_labs@acme.io", "displayName": "Run Panther", }, "request": {}, "outcome": { "result": "FAILURE", "reason": "VERIFICATION_ERROR" }, } ``` # 自定义检测规则 自定义 detections-as-code 是 Panther 提供的最强大的功能之一。要管理自定义检测规则，您可以创建此仓库的私有 Fork。 在[带标签的发布](https://github.com/panther-labs/panther-analysis/releases)之后，您可以从此公共仓库拉取上游更改。 按照[此处](https://docs.panther.com/panther-developer-workflows/ci-cd/detections-repo)的说明，使用公共 Fork 或私有克隆仓库来托管您的自定义检测内容。 # 获取更新 当您想从此仓库拉取最新更改时，我们建议利用[包含的 GitHub Action](https://docs.panther.com/panther-developer-workflows/detections-repo/public-fork#keeping-in-sync-with-upstream)。 如果您希望手动同步，可以在终端中运行以下过程。 ``` # 将公共 repository 添加为 remote git remote add panther-upstream git@github.com:panther-labs/panther-analysis.git # 拉取最新更改 # 注意：如果您最初没有保留历史记录，可能需要使用 `--allow-unrelated-histories` # flag git pull panther-upstream main # 将最新更改推送到您的 forked repo 并合并它们 git push ``` # 移除已弃用的格式化工具 以前，Node、NPM 和 Prettier 用于格式化 Markdown 和 YAML 文件；这些已不再使用。 根据 Node 的管理方式，如果在其他地方不再需要它，则需要将其卸载或删除。请参阅您的系统/包管理器文档以获取有关删除 Node 的说明。 否则，运行 `npm uninstall prettier` 将移除 Prettier。 # 许可证 该仓库根据 [Apache License, Version 2.0](https://github.com/panther-labs/panther-analysis/blob/main/LICENSE.txt) 获得许可。

标签：AMSI绕过, EC2, IaC, Panther, Python, 多线程, 威胁检测, 安全信息与事件管理, 安全策略, 安全运营, 开源规则库, 扫描框架, 提示词设计, 搜索引擎爬取, 数据监控, 无后门, 检测即代码, 网络安全, 请求拦截, 逆向工具, 隐私保护