# ApeGuard
**一键安全态势评估** — 层次化扫描、[统一零信任框架](https://github.com/pirateape/unified-zero-trust-framework)映射、多受众报告。
[](https://github.com/pirateape/ape-guard/actions/workflows/ci.yml)
[](https://github.com/pirateape/ape-guard/releases)
[](LICENSE)
```
# 单命令 — 全面评估
apeguard scan
# 三份报告，一次扫描：
# 📋 technical.md → 供工程师使用
# 📊 executive.md → 供领导使用
# 🗺️ roadmap.md → 供工程经理使用
```
## 功能
- **7层扫描管道** — 密钥 → SAST → SCA → 容器 → DAST → IaC → SBOM，一键完成
- **统一零信任框架映射** — 每个发现都与8个支柱的[UZTF](https://github.com/pirateape/unified-zero-trust-framework)映射，并具有成熟度评分（基线 → 高级 → 自适应）。以CISA零信任成熟度模型为基础。
- **多受众报告** — 技术（工程师）、执行（领导）、路线图（EMs）
- **多格式输出** — Markdown、JSON、SARIF、HTML
- **攻击链分析** — 在扫描器之间交叉引用发现以检测多阶段利用路径
- **架构风险图** — 自动生成的Mermaid组件风险图
- **缓存** — SQLite支持的扫描缓存，基于TTL修剪以避免重新扫描未更改的目标
- **LLM修复** — Ollama驱动的修复建议（本地，无数据泄露）
- **MCP服务器** — 模型上下文协议（MCP）服务器用于AI代理集成
- **100%本地** — 无SaaS、无遥测、无数据离开您的机器
- **零成本工具链** — Gitleaks（MIT）+ Semgrep CE（LGPL-2.1）+ Trivy（Apache 2.0）+ Nuclei（MIT）
## 安装
### 前置条件
安装至少一个扫描工具。ApeGuard在运行时自动检测它们：
```
# 秘密扫描（第1层）
brew install gitleaks
# 或：https://github.com/gitleaks/gitleaks/releases
# SAST / 静态分析（第2层）
pip install semgrep
# 或：brew install semgrep
# SCA / 漏洞扫描（第3层 + 第4层）
brew install trivy
# 或：https://github.com/aquasecurity/trivy/releases
# DAST / 动态扫描（第5层 — 可选）
brew install nuclei
# 或：https://github.com/projectdiscovery/nuclei/releases
# IaC 配置错误扫描（第6层 — 可选）
pip install checkov
# 或：brew install checkov
# SBOM 库存（第7层 — 可选）
brew install syft
# 或：https://github.com/anchore/syft/releases
```
### 从源码（Rust）
```
cargo install apeguard
```
### 从GitHub发布版
从[发布页面](https://github.com/pirateape/ape-guard/releases）下载您平台上的预构建二进制文件。
```
# 示例：Linux x86_64
curl -LO https://github.com/pirateape/ape-guard/releases/latest/download/apeguard-x86_64-unknown-linux-gnu
chmod +x apeguard-x86_64-unknown-linux-gnu
sudo mv apeguard-x86_64-unknown-linux-gnu /usr/local/bin/apeguard
```
### Docker
```
docker pull ghcr.io/pirateape/ape-guard:latest
docker run --rm -v "$PWD:/target" ghcr.io/pirateape/ape-guard scan /target
```
## 快速入门
```
# 初始化配置
apeguard init
# 运行全面安全扫描（所有可用层）
apeguard scan
# 仅运行特定层
apeguard scan --layers 1,2,3
# 扫描容器镜像
apeguard scan --container nginx:latest
# 扫描网络目标（启用 Nuclei 的 DAST）
apeguard scan --web https://example.com
# 生成 HTML 报告而不是 Markdown
apeguard scan --format md,html
# 如果发现高严重性发现则失败 CI
apeguard scan --fail-on high
# 查看缓存结果
apeguard cache stats
# 从缓存重新生成报告
apeguard report
```
Demo GIF generated with VHS. Regenerate via vhs demo.tape.
## 命令
| 命令 | 描述 |
|---------|-------------|
| `scan` | 在目标目录、容器或Web端点上运行全面的安全评估 |
| `report` | 从缓存的扫描中重新生成报告 |
| `compare` | 两个扫描快照之间的差异 |
| `init` | 创建`.apeguard.yaml`配置文件 |
| `config` | 显示或验证当前配置 |
| `version` | 显示版本和扫描器可用状态 |
| `completions` | 生成shell完成脚本 |
| `serve` | 启动MCP服务器以进行AI代理集成 |
| `cache` | 管理扫描缓存（统计信息、修剪） |
### 扫描选项
| 选项 | 描述 |
|--------|-------------|
| `--layers` | 要运行的扫描器层：`1`（密钥）、`2`（SAST）、`3`（SCA）、`4`（容器）、`5`（DAST）、`6`（IaC）、`7`（SBOM） |
| `--web` | Web目标URL — 通过Nuclei启用DAST扫描 |
| `--container` | 要扫描的容器镜像（可重复） |
| `--severity` | 最小发现严重性阈值 |
| `--format` | 输出格式：`md`、`json`、`sarif`、`html`、`pdf`（占位符） |
| `--reports` | 报告类型：`tech`、`exec`、`roadmap` |
| `--fail-on` | 退出代码行为：`never`、`high`、`critical` |
| `--output-dir` | 报告输出目录（默认：`.apeguard/reports`） |
| `--no-cache` | 强制全面重新扫描，忽略缓存 |
## 架构
### 层模型
```
Layer 1 ─ Secrets ───── Gitleaks ──── regex & entropy detection
Layer 2 ─ SAST ──────── Semgrep ───── static analysis (40+ languages)
Layer 3 ─ SCA vulns ─── Trivy fs ──── filesystem dependency scanning
Layer 4 ─ Container ─── Trivy image ─ container image vulnerability scanning
Layer 5 ─ DAST ──────── Nuclei ────── dynamic web/template scanning
Layer 6 ─ IaC ───────── Checkov ───── infrastructure-as-code misconfiguration scanning
Layer 7 ─ SBOM ──────── Syft ──────── software bill of materials inventory
```
### 管道
```
Target
│
├─ gitleaks ──┐
├─ semgrep ───┤
├─ trivy fs ──┤
├─ trivy image┤
├─ nuclei ────┤
├─ checkov ───┤
├─ syft ──────┘
│
▼
Deduplication ─── (file, line, rule_id) composite key
│
├─ Cross-reference ──── Attack chain builder
├─ ZT mapping ───────── 8-pillar maturity scorecard
├─ Severity filter
├─ LLM remediation ──── Ollama local model (optional)
│
▼
Reports ─── technical.md executive.md roadmap.md + JSON / SARIF / HTML
```
### 发现ID格式
每个发现都收到一个唯一的标识符：`AG-{SCANNER}-{DATE}-{NONCE8}-{SEQ}`
示例：`AG-GL-20260531-a1b2c3d4-001`
## 零信任框架映射
ApeGuard实现了[统一零信任框架（UZTF）](https://github.com/pirateape/unified-zero-trust-framework) — 一个基于[CISA零信任成熟度模型](https://www.cisa.gov/zero-trust-maturity-model)的8个支柱成熟度模型，作为其基础。
每个发现都映射到一个或多个UZTF支柱：
| 柱 | 描述 | 示例发现 | CISA来源 |
|--------|-------------|-----------------|-------------|
| **身份** | 认证与授权 | 硬编码API密钥 | 直接：CISA身份 |
| **设备** | 端点健康与合规性 | 过时的依赖项 | 直接：CISA设备 |
| **网络** | 分隔与流量安全 | 开放端口 / SSRF | 直接：CISA网络 |
| **应用** | 应用安全与输入验证 | SQL注入 / XSS | 直接：CISA应用 |
| **数据** | 加密与分类 | 源中的密钥 | 直接：CISA数据 |
| **可见性** | 监控与分析 | 缺失审计日志 | CISA跨切扩展 |
| **自动化** | 自动响应与编排 | CI/CD配置错误 | CISA跨切扩展 |
| **基础设施** | 云/主机配置 | IAM配置错误 | CISA跨切扩展 |
### 成熟度评分（UZTF）
- **基线**（0–50）：存在基础控制，存在重大差距
- **高级**（51–80）：实施主动安全措施
- **自适应**（81–100）：实时、自动化、自我修复的态势
评分卡显示了按支柱的成熟度，并具有可操作的差距分析。有关完整的框架规范，请参阅[UZTF存储库](https://github.com/pirateape/unified-zero-trust-framework)。
## 报告
ApeGuard从每次扫描生成三种报告类型，存储在`.apeguard/reports/`：
### 技术报告（`technical.md`）
为**工程师**。列出每个发现，包括文件位置、严重性、CWE/CVSS引用、ZT支柱、MITRE ATT&CK战术、攻击链交叉引用和修复步骤。
### 执行报告（`executive.md`）
为**领导**。风险态势摘要、严重性分解、零信任评分卡、主要风险和趋势指标。
### 路线图报告（`roadmap.md`）
为**工程经理**。按时间范围（立即 / 短期 / 长期）优先排序的修复计划，按ZT支柱和严重性组织。
### 其他格式
- **JSON** — 适用于CI/CD管道和工具集成的机器可读输出
- **SARIF 2.1** — 标准化格式，用于GitHub安全选项卡和SARIF兼容工具
- **HTML** — 自包含的深色主题报告，具有严重性徽章、ZT评分卡卡和架构图
## 配置
ApeGuard从目标目录中的`.apeguard.yaml`读取（通过`apeguard init`生成）：
```
layers:
- 1
- 2
- 3
severity: all
binaries:
gitleaks: null # custom path, null = auto-detect in PATH
semgrep: null
trivy: null
cache:
enabled: true
path: .apeguard/cache
ttl_hours: 24
report:
formats:
- md
types:
- tech
- exec
- roadmap
output_dir: .apeguard/reports
```
## MCP服务器（AI代理集成）
ApeGuard实现了[模型上下文协议（MCP）](https://modelcontextprotocol.io/)以与AI驱动的开发工具集成。
```
# 启动 MCP 服务器
apeguard serve
```
### MCP工具
| 工具 | 描述 |
|------|-------------|
| `scan` | 运行安全评估（层1-5），可选严重性过滤器 |
| `list_tools` | 列出可用的MCP工具 |
| `resources/read` | 访问扫描报告、评分卡和架构分析 |
### MCP资源
| URI | 描述 |
|-----|-------------|
| `apeguard://reports/{scan_id}` | 完整扫描报告 |
| `apeguard://scorecard/{scan_id}` | 零信任评分卡 |
| `apeguard://latest` | 最新扫描摘要 |
| `apeguard://arch_analysis` | 基于Mermaid的架构组件风险评估图 |
## 开发
```
# 克隆并构建
git clone https://github.com/pirateape/ape-guard
cd apeguard
cargo build
# 运行测试
cargo test
# 运行特定模块测试
cargo test report::tests
# 与 clippy 进行检查
cargo clippy
# 格式化代码
cargo fmt
```
### 项目结构
```
src/
├── main.rs # Entry point, CLI dispatch
├── cli.rs # CLI argument parsing (clap)
├── config.rs # YAML configuration loader
├── mcp.rs # MCP server implementation
├── scanner/
│ ├── mod.rs # Scanner trait + shared timeout helper
│ ├── gitleaks.rs # Layer 1: Secrets scanning
│ ├── semgrep.rs # Layer 2: SAST
│ ├── trivy.rs # Layer 3: Filesystem SCA
│ ├── container.rs # Layer 4: Container image scanning
│ └── dast.rs # Layer 5: DAST (Nuclei)
├── find/
│ └── mod.rs # Canonical finding, severity, scorecard types
├── normalize.rs # ZT pillar mapping + MITRE ATT&CK
├── chain.rs # Attack chain builder
├── arch.rs # Architecture discovery + risk assessment
├── report/
│ └── mod.rs # Report generator (markdown, JSON, SARIF, HTML)
├── dedup.rs # Finding deduplication
├── cache.rs # SQLite-backed scan cache
└── llm.rs # Ollama remediation
```
## CI/CD集成
```
# .github/workflows/security-scan.yml
name: Security Scan
on: [push, pull_request]
jobs:
apeguard:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # required for Gitleaks PR scanning
- name: Install scanners
run: |
brew install gitleaks semgrep trivy
- name: Install ApeGuard
run: cargo install apeguard
- name: Run security scan
run: apeguard scan --fail-on high --format sarif
- name: Upload SARIF to GitHub
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: .apeguard/reports/*.sarif
```
## 许可证
根据**弹性许可证2.0**（EL-2.0）许可。
您可以在任何项目中使用、复制、修改和重新分发此软件，包括商业项目，只要您不将其作为付费SaaS产品提供。有关详细信息，请参阅[LICENSE](LICENSE)文件。
### 扫描工具许可证
| 工具 | 许可证 | 层 |
|------|---------|-------|
| Gitleaks | MIT | 1 — 密钥 |
| Semgrep CE | LGPL-2.1 | 2 — SAST |
| Trivy | Apache 2.0 | 3 + 4 — SCA / 容器 |
| Nuclei | MIT | 5 — DAST |
| Checkov | Apache 2.0 | 6 — IaC |
| Syft | Apache 2.0 | 7 — SBOM |
## 相关
- [统一零信任框架（UZTF）](https://github.com/pirateape/unified-zero-trust-framework) — 8个支柱成熟度模型，具有定量评分（此工具实现的内容）
- [ApeGuard GitHub Action](https://github.com/pirateape/apeguard-action) — 在CI/CD管道中运行分层扫描
- [Azure安全审计框架](https://github.com/pirateape/Azure-Security) — 148+ Azure防御深度资源（KQL、PowerShell、策略、工作簿）
- [CISA零信任成熟度模型](https://www.cisa.gov/zero-trust-maturity-model) — 美国联邦政府的基础ZT框架（UZTF基于此）
- [MITRE ATT&CK](https://attack.mitre.org/) — 对抗战术与技术
- [模型上下文协议](https://modelcontextprotocol.io/) — AI代理集成标准