panther-labs/panther_analysis_tool

# Panther Analysis 工具 [Panther Analysis Tool](https://github.com/panther-labs/panther_analysis_tool) 是一个 Python 应用程序，用于测试、打包和部署 Panther Detections。 了解更多详情，请参阅[快速开始](https://docs.panther.com/quick-start)和 [Panther 文档](https://docs.panther.com/)。 ## 安装说明 ### 前置条件 - **Python 3.11**：通过以下任意一种方法安装 Python： - [官方发布页面](https://www.python.org/downloads/release/python-3119/)上的下载链接 - 使用 [Homebrew](https://brew.sh/)，运行 `brew install python@3.11` - 使用 [pyenv](https://github.com/pyenv/pyenv) 管理 Python 版本 - 使用 [uv](https://docs.astral.sh/uv/) 管理 Python 版本：`uv python install 3.11` - **Pipenv**：要安装 [Pipenv](https://pipenv.pypa.io/en/latest/)，请运行 `pip install --user pipenv` ### 从 PyPi 安装 使用 pip 从 PyPi 安装 [panther_analysis_tool package](https://pypi.org/project/panther-analysis-tool/)： ``` pip3 install panther_analysis_tool ``` 或者使用 `uv`： ``` uv add panther_analysis_tool ``` 或者不使用虚拟环境： ``` make deps pip3 install -e . ``` ### 从源码安装 ``` make install pipenv run -- pip3 install -e . ``` ## 用法 ### 帮助 显示可用的命令及其选项： ``` $ panther_analysis_tool -h usage: panther_analysis_tool [-h] [--version] [--debug] [--skip-version-check] {release,test,publish,upload,delete,update-custom-schemas,test-lookup-table,validate,zip,check-connection,benchmark,enrich-test-data} ... Panther Analysis Tool: A command line tool for managing Panther policies and rules. positional arguments: {release,test,publish,upload,delete,update-custom-schemas,test-lookup-table,validate,zip,check-connection,benchmark,enrich-test-data} release Create release assets for repository containing panther detections. Generates a file called panther-analysis-all.zip and optionally generates panther-analysis-all.sig test Validate analysis specifications and run policy and rule tests. debug Run a single rule test in a debug environment, which allows you to see print statements and use breakpoints. publish Publishes a new release, generates the release assets, and uploads them. Generates a file called panther-analysis-all.zip and optionally generates panther-analysis-all.sig upload Upload specified policies and rules to a Panther deployment. delete Delete policies, rules, or saved queries from a Panther deployment update-custom-schemas Update or create custom schemas on a Panther deployment. test-lookup-table Validate a Lookup Table spec file. validate Validate your bulk uploads against your panther instance zip Create an archive of local policies and rules for uploading to Panther. check-connection Check your Panther API connection benchmark Performance test one rule against one of its log types. The rule must be the only item in the working directory or specified by --path, --ignore-files, and --filter. This feature is an extension of Data Replay and is subject to the same limitations. enrich-test-data Enrich test data with additional enrichments from the Panther API. optional arguments: -h, --help show this help message and exit --version show program's version number and exit --debug --skip-version-check ``` ### 测试 为指定路径运行测试： ``` $ panther_analysis_tool test --path tests/fixtures/valid_policies/ [INFO]: Testing analysis packs in tests/fixtures/valid_policies/ AWS.IAM.MFAEnabled [PASS] Root MFA not enabled fails compliance [PASS] User MFA not enabled fails compliance ``` 运行规则的特定单元测试： ``` $ panther_analysis_tool test --filter RuleID=AWS.IAM.AccessKeyCompromised --test-names "An AWS Access Key was Uploaded to Github" [INFO]: Testing analysis items in . AWS.IAM.AccessKeyCompromised [PASS] An AWS Access Key was Uploaded to Github ``` 运行规则的多个特定单元测试： ``` $ panther_analysis_tool test --filter RuleID=AWS.CloudTrail.Stopped --test-names "CloudTrail Was Stopped" "Error Stopping CloudTrail" [INFO]: Testing analysis items in . [PASS] CloudTrail Was Stopped ... [PASS] Error Stopping CloudTrail [PASS] [rule] false ``` ### 调试 在调试模式下运行特定的单元测试： ``` panther_analysis_tool debug My.RuleID "My unit test name" ``` 查看类似以下 print 语句的输出： ``` INFO: Testing analysis items in /panther-analysis/rules/debug Debug.RuleThatPrints Hello world! ``` 或者查看带有 traceback 信息的错误： ``` INFO: Testing analysis items in /panther-analysis/rules/debug Debug.RuleWithError ERROR: Test exception for debug tracing File "/panther-analysis/rules/debug/rule_with_error.py", line 4, in rule sub_func() File "/panther-analysis/rules/debug/rule_with_error.py", line 7, in sub_func raise ValueError('Test exception for debug tracing') ``` ### 上传 创建可通过 Panther UI 上传的包： ``` $ panther_analysis_tool zip --path tests/fixtures/valid_policies/ --out tmp [INFO]: Testing analysis packs in tests/fixtures/valid_policies/ AWS.IAM.MFAEnabled [PASS] Root MFA not enabled fails compliance [PASS] User MFA not enabled fails compliance [INFO]: Zipping analysis packs in tests/fixtures/valid_policies/ to tmp [INFO]: /tmp/panther-analysis-2020-03-23T12-48-18.zip ``` 或者直接将包上传到 Panther： ``` $ panther_analysis_tool upload --path tests/fixtures/valid_policies/ --out tmp [INFO]: Testing analysis packs in tests/fixtures/valid_policies/ AWS.IAM.MFAEnabled [PASS] Root MFA not enabled fails compliance [PASS] User MFA not enabled fails compliance AWS.IAM.BetaTest [PASS] Root MFA not enabled fails compliance [PASS] User MFA not enabled fails compliance AWS.CloudTrail.MFAEnabled [PASS] Root MFA not enabled fails compliance [PASS] User MFA not enabled fails compliance [INFO]: Zipping analysis packs in tests/fixtures/valid_policies/ to tmp [INFO]: Found credentials in environment variables. [INFO]: Uploading pack to Panther [INFO]: Upload success. [INFO]: API Response: { "modifiedPolicies": 0, "modifiedRules": 0, "newPolicies": 2, "newRules": 1, "totalPolicies": 2, "totalRules": 1 } ``` ### 过滤 `test`、`zip` 和 `upload` 命令均支持过滤。过滤的工作原理是传入 `--filter` 参数，并附带一个以 `KEY=VALUE1,VALUE2` 格式指定的过滤器列表。其中的键（KEY）可以是策略或规则中的任意有效字段。使用过滤器时，只有匹配每个指定过滤条件的分析项才会被纳入考虑。例如，以下命令将仅测试 AnalysisType 为 `policy` 且 severity 为 `High` 的项目： ``` $ panther_analysis_tool test --path tests/fixtures/valid_policies --filter AnalysisType=policy Severity=High [INFO]: Testing analysis packs in tests/fixtures/valid_policies AWS.IAM.BetaTest [PASS] Root MFA not enabled fails compliance [PASS] User MFA not enabled fails compliance ``` 或者，以下命令将测试 AnalysisType 为 `policy` 或 `rule`，并且 severity 为 `High` 的项目： ``` $ panther_analysis_tool test --path tests/fixtures/valid_policies --filter AnalysisType=policy,rule Severity=High [INFO]: Testing analysis packs in tests/fixtures/valid_policies AWS.IAM.BetaTest [PASS] Root MFA not enabled fails compliance [PASS] User MFA not enabled fails compliance AWS.CloudTrail.MFAEnabled [PASS] Root MFA not enabled fails compliance [PASS] User MFA not enabled fails compliance ``` 在编写引用全局分析类型的策略或规则时，请将它们包含在过滤器中。过滤值为空字符串意味着仅在字段存在时才应用该过滤器。以下命令会返回错误：该策略导入了一个全局变量，但该全局变量缺少 severity，因此被过滤器排除了。 ``` $ panther_analysis_tool test --path tests/fixtures/valid_policies --filter AnalysisType=policy,global Severity=Critical [INFO]: Testing analysis packs in tests/fixtures/valid_policies AWS.IAM.MFAEnabled [ERROR] Error loading module, skipping Invalid: tests/fixtures/valid_policies/example_policy.yml No module named 'panther' [ERROR]: [('tests/fixtures/valid_policies/example_policy.yml', ModuleNotFoundError("No module named 'panther'"))] ``` 要使此查询生效，请允许 severity 字段不存在： ``` $ panther_analysis_tool test --path tests/fixtures/valid_policies --filter AnalysisType=policy,global Severity=Critical,"" [INFO]: Testing analysis packs in tests/fixtures/valid_policies AWS.IAM.MFAEnabled [PASS] Root MFA not enabled fails compliance [PASS] User MFA not enabled fails compliance ``` 过滤器在 `zip` 和 `upload` 命令中的工作方式与在 `test` 命令中完全相同。 除了过滤外，还可以使用 --minimum-tests 标志设置最少的单元测试数量。未达到最少测试数量的 Detections 将被视为未通过。如果 `--minimum-tests` 设置为 2 或更高，则要求至少有一个测试返回 `True`，另一个测试返回 `False`。 ``` $ panther_analysis_tool test --path tests/fixtures/valid_policies --minimum-tests 2 % panther_analysis_tool test --path okta_rules --minimum-tests 2 [INFO]: Testing analysis packs in okta_rules Okta.AdminRoleAssigned [PASS] Admin Access Assigned Okta.BruteForceLogins [PASS] Failed login Okta.GeographicallyImprobableAccess [PASS] Non Login [PASS] Failed Login -------------------------- Panther CLI Test Summary Path: okta_rules Passed: 0 Failed: 3 Invalid: 0 -------------------------- Failed Tests Summary Okta.AdminRoleAssigned ['Insufficient test coverage, 2 tests required but only 1 found.', 'Insufficient test coverage: expected at least one passing and one failing test.'] Okta.BruteForceLogins ['Insufficient test coverage, 2 tests required but only 1 found.', 'Insufficient test coverage: expected at least one passing and one failing test] Okta.GeographicallyImprobableAccess ['Insufficient test coverage: expected at least one passing and one failing test.'] ``` 在这种情况下，即使规则通过了所有测试，它们仍然会被视为未通过，因为它们没有达到正确的测试覆盖率。 ### 删除规则、策略或保存的查询 ``` $ panther_analysis_tool delete usage: panther_analysis_tool delete [-h] [--no-confirm] [--athena-datalake] [--api-token API_TOKEN] [--api-host API_HOST] [--aws-profile AWS_PROFILE] [--analysis-id ANALYSIS_ID [ANALYSIS_ID ...]] [--query-id QUERY_ID [QUERY_ID ...]] Delete policies, rules, or saved queries from a Panther deployment optional arguments: -h, --help show this help message and exit --no-confirm Skip manual confirmation of deletion (default: False) --athena-datalake Instance DataLake is backed by Athena (default: False) --api-token API_TOKEN The Panther API token to use. See: https://docs.panther.com/api-beta (default: None) --api-host API_HOST The Panther API host to use. See: https://docs.panther.com/api-beta (default: None) --aws-profile AWS_PROFILE The AWS profile to use when updating the AWS Panther deployment. (default: None) --analysis-id ANALYSIS_ID [ANALYSIS_ID ...] Space separated list of Detection IDs (default: []) --query-id QUERY_ID [QUERY_ID ...] Space separated list of Saved Queries (default: []) ``` 传入以空格分隔的 Analysis ID（RuleID 或 PolicyID）或 QueryID 列表。使用 --no-confirm 标志可跳过确认提示。规则及其关联的已保存查询将被匹配并删除。默认配置针对 Snowflake 数据湖；对于 Athena 数据湖，请使用 --athena-datalake 标志。 ## 配置文件 Panther Analysis Tool 还会读取当前工作目录下的配置文件 `.panther_settings.yml` 中的选项。本仓库中包含了一个示例配置文件 [example_panther_config.yml](example_panther_config.yml)，其中包含受支持选项的示例语法。 配置文件中的选项优先于命令行选项。例如，如果配置文件中设置了 minimum_tests: 2，而命令行中指定了 --minimum-tests 1，则最少的测试数量将为 2。 ### 本地开发 要在本地使用 panther_analysis_tool 进行开发，请准备两个仓库：一个是本仓库，另一个是包含用于 PAT 测试的 panther 分析内容的仓库。 在你的 [panther_analysis](https://github.com/panther-labs/panther-analysis) 内容仓库中，以可编辑模式安装（例如并进行测试）： ``` pipenv install --editable ../relative/path/to/panther_analysis_tool pipenv run panther_analysis_tool test ``` ## 许可证 本仓库采用 AGPL-3.0 [许可证](https://github.com/panther-labs/panther-analysis/blob/master/LICENSE)授权。

标签：DevSecOps, Python, 上游代理, 安全检测规则, 安全运营, 扫描框架, 文档结构分析, 无后门, 逆向工具