awslabs/automated-security-helper
GitHub: awslabs/automated-security-helper
由 AWS 开源的安全扫描编排引擎，整合多种 SAST、SCA 与 IaC 扫描工具，支持多种运行模式与报告格式，并通过 MCP 协议与 AI 助手集成，便于在开发流程中尽早识别代码和基础设施中的安全问题。
Stars: 617 | Forks: 79
# ASH - Automated Security Helper
[](https://github.com/awslabs/automated-security-helper/actions/workflows/ash-build-and-scan.yml)
[](https://github.com/awslabs/automated-security-helper/actions/workflows/unit-tests.yml)
## 目录
- [目录](#table-of-contents)
- [概述](#overview)
- [ASH v3 主要功能](#key-features-in-ash-v3)
- [内置扫描器](#built-in-scanners)
- [前置条件](#prerequisites)
- [运行环境要求](#runtime-requirements)
- [安装选项](#installation-options)
- [快速安装（推荐）](#quick-install-recommended)
- [其他安装方式](#other-installation-methods)
- [使用 `uvx`](#using-uvx)
- [使用 `pip`](#using-pip)
- [克隆仓库](#clone-the-repository)
- [基本用法](#basic-usage)
- [输出示例](#sample-output)
- [通过 MCP 集成 AI](#ai-integration-with-mcp)
- [MCP 服务器功能](#mcp-server-features)
- [安装与设置](#installation-and-setup)
- [前置条件](#prerequisites-1)
- [客户端配置](#client-configuration)
- [可用的 MCP 工具](#available-mcp-tools)
- [使用示例](#usage-examples)
- [配置支持](#configuration-support)
- [配置](#configuration)
- [配合 pre-commit 使用 ASH](#using-ash-with-pre-commit)
- [输出文件](#output-files)
- [常见问题](#faq)
- [文档](#documentation)
- [反馈与贡献](#feedback-and-contributing)
- [安全性](#security)
- [许可证](#license)
- [Star History](#star-history)
## 概述
ASH (Automated Security Helper) 是一款安全扫描工具，旨在帮助您在开发流程中尽早识别代码、基础设施和 IAM 配置中的潜在安全问题。
- ASH 不能替代人工审查或团队/客户的安全标准
- 它利用轻量级开源工具，确保灵活性和可移植性
- ASH v3 已完全使用 Python 重写，在可用性和功能性方面有显著改进
## ASH v3 主要功能
- **基于 Python 的 CLI**：ASH 现在有了基于 Python 的 CLI 入口，同时保持与 shell 脚本入口的向后兼容性
- **多种执行模式**：根据需要以 `local`、`container` 或 `precommit` 模式运行 ASH
- **增强的配置**：支持 YAML/JSON 配置文件，并可通过 CLI 参数进行覆盖
- **改进的报告**：支持 JSON、Markdown、HTML 和 CSV 等多种报告格式
- **扫描器验证系统**：全面的验证确保所有预期的扫描器都已注册、启用、排队、执行并包含在结果中
- **可插拔架构**：通过自定义插件、扫描器和报告器扩展 ASH
- **统一的输出格式**：标准化的输出格式，可导出为多种格式（SARIF、JSON、HTML、Markdown、CSV）
- **UV 包管理**：ASH 现在使用 UV 进行更快的依赖解析和工具隔离
- **全面的测试**：广泛的集成测试套件验证了跨平台的 UV 迁移功能
## 内置扫描器
ASH v3 集成了多个开源安全工具作为扫描器。Bandit、Checkov 和 Semgrep 等工具通过 UV 的工具隔离系统进行管理，该系统会自动在隔离环境中安装和运行它们，而不会影响您的项目依赖：
| Scanner | Type | Languages/Frameworks | Installation (Local Mode) |
|---------------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| [Bandit](https://github.com/PyCQA/bandit) | SAST | Python | 通过 UV 工具隔离管理（自动安装：`bandit>=1.7.0`） |
| [Semgrep](https://github.com/semgrep/semgrep) | SAST | Python, JavaScript, TypeScript, Java, Go, C#, Ruby, PHP, Kotlin, Swift, Bash, 及更多 | 通过 UV 工具隔离管理（自动安装：`semgrep>=1.125.0`） |
| [detect-secrets](https://github.com/Yelp/detect-secrets) | Secrets | 所有文本文件 | 随 ASH 附带 |
| [Checkov](https://github.com/bridgecrewio/checkov) | IaC, SAST | Terraform, CloudFormation, Kubernetes, Dockerfile, ARM Templates, Serverless, Helm, 及更多 | 通过 UV 工具隔离管理（自动安装：`checkov>=3.2.0,<4.0.0`） |
| [cfn_nag](https://github.com/stelligent/cfn_nag) | IaC | CloudFormation | `gem install cfn-nag` |
| [cdk-nag](https://github.com/cdklabs/cdk-nag) | IaC | CloudFormation | 随 ASH 附带 |
| [npm-audit](https://docs.npmjs.com/cli/v8/commands/npm-audit) | SCA | JavaScript/Node.js | 安装 Node.js/npm |
| [Grype](https://github.com/anchore/grype) | SCA | Python, JavaScript/Node.js, Java, Go, Ruby, 及更多 | 参见 [Grype 安装](https://github.com/anchore/grype#installation) |
| [Syft](https://github.com/anchore/syft) | SBOM | Python, JavaScript/Node.js, Java, Go, Ruby, 及更多 | 参见 [Syft 安装](https://github.com/anchore/syft#installation) |
## 前置条件
### 运行环境要求
| Mode | Requirements | Notes |
|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------|
| Local | Python 3.10+, UV 包管理器 | 部分扫描器需要额外工具（见上表） |
| Container | 任何兼容 OCI 的容器运行时（[Finch](https://github.com/runfinch/finch)、[Docker](https://docs.docker.com/get-docker/)、[Podman](https://podman.io/) 等） | Windows 上：通常需要 WSL2 |
| Precommit | Python 3.10+, UV 包管理器 | 扫描器子集，针对速度优化 |
## 安装选项
### 快速安装（推荐）
```
# 在 Linux/macOS 上安装 uv（如果尚未安装）
curl -sSfL https://astral.sh/uv/install.sh | sh
# 为 ASH 创建别名
alias ash="uvx git+https://github.com/awslabs/automated-security-helper.git@v3.2.3"
```
```
# 在 Windows 上使用 PowerShell 安装 uv（如果尚未安装）
irm https://astral.sh/uv/install.ps1 | iex
# 为 ASH 创建函数
function ash { uvx git+https://github.com/awslabs/automated-security-helper.git@v3.2.3 $args }
```
### 其他安装方式
## 基本用法
```
# 在 local 模式下运行扫描（仅 Python）
ash --mode local
# 在 container 模式下运行扫描（所有工具）
ash --mode container
# 在 precommit 模式下运行扫描（快速工具子集）
ash --mode precommit
```
### 输出示例
```
ASH Scan Results Summary
┏━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━┳━━━━━━━━┳━━━━━┳━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ Scanner ┃ Suppressed ┃ Critical ┃ High ┃ Medium ┃ Low ┃ Info ┃ Duration ┃ Actionable ┃ Result ┃ Threshold ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━╇━━━━━━━━╇━━━━━╇━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ bandit │ 7 │ 0 │ 1 │ 0 │ 56 │ 0 │ 19.9s │ 1 │ FAILED │ MEDIUM (global) │
│ cdk-nag │ 0 │ 0 │ 30 │ 0 │ 0 │ 5 │ 48.7s │ 30 │ FAILED │ MEDIUM (global) │
│ cfn-nag │ 0 │ 0 │ 0 │ 15 │ 0 │ 0 │ 45.1s │ 15 │ FAILED │ MEDIUM (global) │
│ checkov │ 10 │ 0 │ 25 │ 0 │ 0 │ 0 │ 38.9s │ 25 │ FAILED │ MEDIUM (global) │
│ detect-secrets │ 0 │ 0 │ 48 │ 0 │ 0 │ 0 │ 18.9s │ 48 │ FAILED │ MEDIUM (global) │
│ grype │ 0 │ 0 │ 2 │ 1 │ 0 │ 0 │ 40.3s │ 3 │ FAILED │ MEDIUM (global) │
└────────────────┴────────────┴──────────┴──────┴────────┴─────┴──────┴──────────┴────────────┴────────┴─────────────────┘
source-dir: '.'
output-dir: '.ash/ash_output'
=== ASH Scan Completed in 1m 6s: Next Steps ===
View detailed findings...
- SARIF: '.ash/ash_output/reports/ash.sarif'
- JUnit: '.ash/ash_output/reports/ash.junit.xml'
- ASH aggregated results JSON available at: '.ash/ash_output/ash_aggregated_results.json'
=== Actionable findings detected! ===
To investigate...
1. Open one of the summary reports for a user-friendly table of the findings:
- HTML report of all findings: '.ash/ash_output/reports/ash.html'
- Markdown summary: '.ash/ash_output/reports/ash.summary.md'
- Text summary: '.ash/ash_output/reports/ash.summary.txt'
2. Use ash report to view a short text summary of the scan in your terminal
3. Use ash inspect findings to explore the findings interactively
4. Review scanner-specific reports and outputs in the '.ash/ash_output/scanners' directory
=== ASH Exit Codes ===
0: Success - No actionable findings or not configured to fail on findings
1: Error during execution
2: Actionable findings detected when configured with `fail_on_findings: true`. Default is True. Current value: True
ERROR (2) Exiting due to 122 actionable findings found in ASH scan
```
## 通过 MCP 集成 AI
ASH 包含一个 Model Context Protocol (MCP) 服务器，使 AI 助手能够通过标准化接口执行安全扫描并分析结果。这允许您将 ASH 与 Amazon Q CLI、Claude Desktop 和 Cline (VS Code) 等 AI 开发工具集成。
### MCP 服务器功能
ASH MCP 服务器提供：
- **实时进度跟踪**：通过流式更新监控扫描进度
- **后台扫描**：启动扫描并在运行时继续其他工作
- **多扫描管理**：使用唯一标识符处理并发扫描
- **全面的错误处理**：详细的错误消息和恢复建议
- **配置支持**：完全支持 ASH 配置文件和环境变量
### 安装与设置
#### 前置条件
1. **安装 UV**：从 [Astral](https://docs.astral.sh/uv/getting-started/installation/) 或 [GitHub README](https://github.com/astral-sh/uv#installation) 安装 `uv`
2. **安装 Python 3.10+**：使用 `uv python install 3.10`（或更新版本）
#### 客户端配置
**Amazon Q Developer CLI** - 添加到 `~/.aws/amazonq/mcp.json`：
```
{
"mcpServers": {
"ash": {
"command": "uvx",
"args": [
"--from=git+https://github.com/awslabs/automated-security-helper@v3.0.0",
"ash",
"mcp"
],
"disabled": false,
"autoApprove": []
}
}
}
```
**Claude Desktop** - 添加到 `claude_desktop_config.json`：
```
{
"mcpServers": {
"ash-security": {
"command": "uvx",
"args": [
"--from=git+https://github.com/awslabs/automated-security-helper@v3.0.0",
"ash",
"mcp"
]
}
}
}
```
**Cline (VS Code)**:
```
{
"mcpServers": {
"ash": {
"command": "uvx",
"args": [
"--from=git+https://github.com/awslabs/automated-security-helper@v3.0.0",
"ash",
"mcp"
],
"disabled": false,
"autoApprove": [
"get_scan_progress",
"list_active_scans",
"get_scan_results"
]
}
}
}
```
### 可用的 MCP 工具
ASH MCP 服务器提供以下工具：
| Tool | Description | Use Case |
|------|-------------|----------|
| `scan_directory` | 执行完整的安全扫描 | 获取完整结果的一次性扫描 |
| `scan_directory_with_progress` | 启动带实时进度跟踪的扫描 | 需要进度监控的长时间扫描 |
| `get_scan_progress` | 获取正在运行的扫描的当前进度 | 监控扫描状态和部分结果 |
| `get_scan_results` | 获取已完成扫描的最终结果 | 检索完整的扫描结果 |
| `list_active_scans` | 列出所有活动和最近的扫描 | 管理多个并发扫描 |
| `cancel_scan` | 取消正在运行的扫描 | 停止不必要或有问题的扫描 |
| `check_installation` | 验证 ASH 安装和依赖项 | 排查设置问题 |
### 使用示例
配置完成后，您可以通过自然语言与 ASH 交互。以下每个句子都代表可在各种编码 CLI（Q CLI、Cline 等）中使用的提示词，用于指示 CLI 识别 ASH MCP 工具并根据提示中提供的说明使用它。
**基本安全扫描：**
```
"Can you scan this project directory for security vulnerabilities?"
"Please run ASH on the ./src folder and analyze the results"
"Check this code for security issues with HIGH severity threshold"
```
**进度监控：**
```
"Start a security scan on this directory and show me the progress"
"Monitor the current scan and let me know when it's done"
"What's the status of my running security scans?"
```
**分析与报告：**
```
"Perform a comprehensive security audit and create a prioritized action plan"
"Scan this code and help me fix any critical security issues"
"Generate a security report with remediation recommendations"
```
### 配置支持
MCP 服务器支持所有 ASH 配置方式：
- **配置文件**：`.ash/ash.yaml` 或自定义配置路径
- **环境变量**：`ASH_DEFAULT_SEVERITY_LEVEL`、`ASH_OFFLINE` 等
- **CLI 参数**：严重性阈值、自定义输出目录
有关流式功能和高级用法的详细信息，请参阅 [MCP Streaming Guide](docs/content/tutorials/mcp-streaming-guide.md)。
## 配置
ASH v3 使用 YAML 配置文件（`.ash/ash.yaml`）并支持 JSON Schema 验证：
```
# yaml-language-server: $schema=https://raw.githubusercontent.com/awslabs/automated-security-helper/refs/heads/main/automated_security_helper/schemas/AshConfig.json
project_name: my-project
global_settings:
severity_threshold: MEDIUM
ignore_paths:
- path: 'tests/test_data'
reason: 'Test data only'
scanners:
bandit:
enabled: true
options:
confidence_level: high
reporters:
markdown:
enabled: true
options:
include_detailed_findings: true
```
## 配合 pre-commit 使用 ASH
将以下内容添加到您的 `.pre-commit-config.yaml`：
```
repos:
- repo: https://github.com/awslabs/automated-security-helper
rev: v3.0.0
hooks:
- id: ash-simple-scan
```
运行：
```
pre-commit run ash-simple-scan --all-files
```
## 输出文件
ASH v3 在 `.ash/ash_output/` 目录中生成多个输出文件：
- `ash_aggregated_results.json`：包含验证检查点的完整机器可读结果
- `reports/ash.summary.txt`：人类可读的文本摘要
- `reports/ash.summary.md`：用于 GitHub PR 和其他平台的 Markdown 摘要
- `reports/ash.html`：交互式 HTML 报告
- `reports/ash.csv`：用于筛选和排序发现的 CSV 报告
`ash_aggregated_results.json` 文件包含全面的验证信息，用于跟踪整个扫描过程中的扫描器注册、启用、执行和结果包含情况。扫描器验证系统还可以生成详细的验证报告，提供对扫描器状态、验证检查点、依赖项问题的全面分析，以及用于排查扫描问题的可操作建议。
## 常见问题
` 或您偏好的方法手动安装工具
2. **离线模式**：设置 `ASH_OFFLINE=true` 以跳过自动安装并使用系统安装的工具
3. **回退行为**：如果 UV 工具安装失败，ASH 会自动回退到系统安装的工具
自动安装使用合理的默认版本约束以确保兼容性：
- **Bandit**：`>=1.7.0`（增强的 SARIF 支持和安全修复）
- **Checkov**：`>=3.2.0,<4.0.0`（改进的稳定性，避免 4.x 中潜在的破坏性更改）
- **Semgrep**：`>=1.125.0`（全面的规则支持和性能改进）
这些约束可以在需要时通过扫描器配置覆盖。
## 文档
完整文档请访问 [ASH Documentation](https://awslabs.github.io/automated-security-helper/)。
## 反馈与贡献
- 在[此处](https://github.com/awslabs/automated-security-helper/issues)创建 issue
- 贡献指南请参见 [CONTRIBUTING](CONTRIBUTING.md)
## 安全性
安全问题报告信息请参见 [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications)。
## 许可证
本库根据 Apache 2.0 许可证授权。详见 [LICENSE](LICENSE) 文件。
## Star History
[](https://www.star-history.com/#awslabs/automated-security-helper&Date)
点击展开其他安装选项
#### 使用 `pipx` ``` # 使用 pipx 安装（隔离环境） pipx install git+https://github.com/awslabs/automated-security-helper.git@v3.0,1 # 正常使用 ash --help ``` #### 使用 `pip` ``` pip install git+https://github.com/awslabs/automated-security-helper.git@v3.2.3 ``` #### 克隆仓库 ``` git clone https://github.com/awslabs/automated-security-helper.git --branch v3.2.3 cd automated-security-helper pip install . ```如何在 Windows 上运行 ASH？
ASH v3 可以通过 Python 3.10+ 在 Windows 上直接以 local 模式运行。只需使用 pip、pipx 或 uvx 安装 ASH 并使用 `--mode local` 运行。对于 container 模式，您需要 WSL2 和 Docker Desktop、Rancher Desktop 或 Podman Desktop 等容器运行时。如何在 CI/CD 管道中运行 ASH？
ASH 可以在任何支持容器的 CI/CD 环境中以 container 模式运行。示例请参见 [tutorials](docs/content/tutorials/running-ash-in-ci.md)。如何从扫描中排除文件？
ASH 遵循 `.gitignore` 文件。您也可以在 `.ash/ash.yaml` 配置文件中配置忽略路径。如何在离线/物理隔离环境中运行 ASH？
使用 `ash --mode container --offline --offline-semgrep-rulesets p/ci --no-run` 构建离线镜像，推送到您的私有仓库，然后在物理隔离环境中使用 `ash --mode container --offline --no-build`。我正在尝试扫描 CDK 应用程序，但 ASH 没有显示 CDK Nag 扫描结果 —— 为什么？
ASH 在底层使用 CDK Nag，通过 `CfnInclude` CDK 构造将 NagPack 规则应用于 *CloudFormation 模板*。这纯粹是一种引入原始 CloudFormation 模板并对其应用 CDK NagPacks 的机制；对由另一个 CDK 应用程序发出的模板执行此操作时，由于 CDK 添加到模板上的 `BootstrapVersion` 参数的存在，会导致 `CfnInclude` 构造发生冲突。对于 CDK 应用程序，我们建议直接在您的 CDK 代码中集成 CDK Nag。ASH 仍将对通过 CDK 合成的模板应用其他 CloudFormation 扫描器（cfn-nag、checkov），但 CDK Nag 扫描器不会扫描这些模板。为什么 ASH 试图自动安装工具？我可以使用我自己安装的工具？
ASH v3 使用 UV 的工具隔离系统自动管理扫描器依赖项，如 Bandit、Checkov 和 Semgrep。这确保了工具版本的一致性并避免了依赖冲突。如果您希望使用自己安装的工具： 1. **预安装工具**：使用 `uv tool installASH 失败并显示 UV 工具安装错误。如何修复？
如果您遇到 UV 工具安装问题： 1. **检查 UV 安装**：确保 UV 已安装并可用：`uv --version` 2. **网络连接**：UV 工具安装需要互联网访问 3. **使用离线模式**：设置 `ASH_OFFLINE=true` 以跳过下载并使用预安装的工具 4. **手动安装**：手动预安装工具： uv tool install bandit>=1.7.0 uv tool install checkov>=3.2.0,<4.0.0 uv tool install semgrep>=1.125.0 5. **检查日志**：使用 `--verbose` 运行 ASH 以查看详细的错误消息，包括： - UV 可用性状态 - 工具安装尝试和重试逻辑 - 版本检测信息 - 回退机制激活 6. **回退到系统工具**：如果 UV 安装失败，ASH 将自动尝试使用系统安装的工具 7. **安装超时**：如有必要，在扫描器配置中增加超时时间： scanners: checkov: options: install_timeout: 600 # 10 minutes标签：AI 辅助, AST 引擎, AWS, CI/CD 安全, DevSecOps, DPI, FTP漏洞扫描, Homebrew安装, IaC 安全, IAM 配置检查, MCP, Pre-commit, Python, SAST, 上游代理, 云安全监控, 基础设施安全, 安全助手, 安全编排, 数据投毒防御, 文档安全, 无后门, 模型上下文协议, 盲注攻击, 结构化查询, 自动化安全, 请求拦截, 软件开发工具包, 逆向工具, 静态分析