ez-appsec/ez-appsec

# ez-appsec **AI 驱动的应用程序安全扫描** — 一款免费、开源的 AI 优先安全套件，适用于 GitLab 和 GitHub。 ## 概述 `ez-appsec` 利用人工智能分析您的代码库中的安全漏洞，并提供 AI 驱动的修复指导。它将多种检测机制与 OpenAI 的语言模型相结合，提供快速、准确且可操作的安全见解。 ### 主要功能 - **🚀 外部扫描器集成**：利用 gitleaks、semgrep、kics 和 grype - **🤖 AI 驱动的修复**：基于 LLM 的修复安全问题指导 - **🎯 多语言支持**：支持外部扫描器涵盖的所有语言 - **📊 多种输出格式**：JSON、SARIF（兼容 GitHub/GitLab）、**GitLab 漏洞格式** - **⚡ 零配置**：开箱即用，与外部工具配合工作 - **🆓 免费且开源**：无云依赖，本地运行 ## 工作原理 ez-appsec 是一个轻量级的编排层，运行一流的开源扫描器，将其输出规范化为单一架构，可选择性地通过 AI 指导丰富发现结果，并将结果推送到托管的安全仪表板。 ``` ┌─────────────────────────────────────────────────────────────────┐ │ Your codebase │ └───────────────────────────┬─────────────────────────────────────┘ │ ez-appsec scan / github-scan / gitlab-scan ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Scanner orchestration │ │ │ │ gitleaks semgrep kics grype │ │ (secrets) (SAST) (IaC) (dependencies) │ └───────────────────────────┬─────────────────────────────────────┘ │ raw JSON from each tool ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Normalization layer │ │ Unified schema: type · severity · file · line · scanner · CVE │ └───────────────────────────┬─────────────────────────────────────┘ │ ┌─────────────┼─────────────┐ │ (optional) │ │ ▼ ▼ ▼ AI enrichment Filter by Sort by severity (OpenAI API) severity │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Output formats │ │ │ │ CLI summary JSON SARIF (GitHub) GitLab vuln format │ └───────────────────────────┬─────────────────────────────────────┘ │ push via CI/CD ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Security Dashboard (GitHub / GitLab Pages) │ │ Multi-project · severity filters · finding detail · AI fix │ └─────────────────────────────────────────────────────────────────┘ ``` ### 扫描流程 | 步骤 | 发生内容 | |------|-------------| | **1. 运行扫描器** | ez-appsec 针对目标路径调用每个已安装的扫描器（gitleaks、semgrep、kics、grype）并捕获其原始 JSON 输出 | | **2. 规范化** | 将每个扫描器的输出转换为统一的漏洞架构，具有一致的严重性级别、文件路径和行号 | | **3. AI 丰富** | 当设置了 `OPENAI_API_KEY` 时，每个发现都会获得 AI 生成的风险解释和分步修复指南 —— 此步骤是可选的，否则跳过 | | **4. 筛选和排序** | 根据请求的严重性阈值筛选发现，并按 严重 → 高 → 中 → 低 排序 | | **5. 报告** | 结果作为 CLI 输出、JSON、SARIF（用于 GitHub Security 标签页）或 GitLab 漏洞格式写入 | | **6. 仪表板推送** | 在 CI/CD 模式下，`vulnerabilities.json` 被提交到仪表板仓库；Pages 站点会自动重建 | ## 安装 ### 从源代码 ``` git clone https://github.com/ez-appsec/ez-appsec.git cd ez-appsec pip install -e . ``` ### Docker 包含所有扫描器的预构建镜像（发布到 GitHub Container Registry）： ``` # 从 GHCR 拉取 docker pull ghcr.io/ez-appsec/ez-appsec:latest # 或在本地构建 docker build -t ez-appsec:latest . # 运行扫描 docker run --rm -v $(pwd):/scan ghcr.io/ez-appsec/ez-appsec:latest scan . ``` 轻量级变体（约 300MB）： ``` docker pull ghcr.io/ez-appsec/ez-appsec:slim docker run --rm -v $(pwd):/scan ghcr.io/ez-appsec/ez-appsec:slim scan . ``` ### 从 PyPI（即将推出） ``` pip install ez-appsec ``` ### 要求 - Python 3.9+ - OpenAI API key（用于 AI 驱动的分析，可选） ## 快速开始 ### 安装 Claude Code 技能 将 `/ez-appsec-install` 和 `/ez-appsec-scan` 斜杠命令添加到您的项目： ``` curl -fsSL https://raw.githubusercontent.com/ez-appsec/ez-appsec/main/skills/install.sh | bash -s -- --project ``` 然后使用 `/ez-appsec-install` 通过 `scan.yml` 包含和合并请求将 ez-appsec 扫描添加到任何 GitLab 项目。 对于 GitHub 项目，使用 `/ez-appsec-install-github` 添加 GitHub Actions 工作流集成： ``` curl -fsSL https://raw.githubusercontent.com/ez-appsec/ez-appsec/main/skills/install.sh | bash -s --github ``` 这将： - 将 `.github/workflows/github-scan.yml` 添加到您的仓库 - 设置版本控制变量 - 配置 GitHub Pages 仪表板集成（可选） - 创建用于审查的拉取请求 ### 检查扫描器安装 ``` # 查看已安装的扫描器 ez-appsec status # 安装推荐的扫描器 brew install gitleaks semgrep kics grype ``` ### 基本安全扫描 ``` # 扫描当前目录 ez-appsec scan # 扫描指定路径 ez-appsec scan /path/to/project # 将结果保存为 JSON ez-appsec scan . --output results.json ``` ### GitLab 漏洞格式 生成与 GitLab 安全仪表板兼容的报告： ``` # 扫描并以 GitLab 漏洞格式输出 ez-appsec gitlab-scan . --output gitlab-report.json # 启用 AI 分析和自定义提示 ez-appsec gitlab-scan . --ai-prompt "Focus on critical issues" --output report.json ``` GitLab 格式包括： - 标准化的漏洞架构 - 严重性级别（critical、high、medium、low、info） - 位置信息（文件、行号） - 修复建议 - 扫描器标识 - CVE 引用（如果可用） ### GitHub SARIF 格式 生成与 GitHub Advanced Security 兼容的报告： ``` # 扫描并以 SARIF 格式输出 ez-appsec github-scan . --output ez-appsec.sarif # 启用 AI 分析和自定义提示 ez-appsec github-scan . --ai-prompt "Focus on critical issues" --output report.sarif ``` SARIF 格式包括： - 标准化的 SARIF 2.1.0 架构 - 映射到 SARIF 级别的严重性级别（error、warning、note） - 位置信息（文件、行号、区域） - 带有帮助 URI 的规则定义 - 扫描器标识 - CVE 引用（如果可用） **注意**：要在 GitHub Security 标签页中查看 SARIF 结果，请使用包含 SARIF 上传的 GitHub Actions 工作流。Security 标签页显示需要 GitHub Advanced Security 许可证。 ### 初始化配置 ``` # 创建默认的 .ez-appsec.yaml ez-appsec init ``` ### 快速检查（无 AI） ``` # 快速检测秘密，不进行 AI 分析 ez-appsec check ``` ### 使用 AI 分析 ``` # 启用 AI 修复指导 (需要 OPENAI_API_KEY) export OPENAI_API_KEY=sk-... ez-appsec scan . --ai-prompt "Focus on SQL injection and authentication issues" ``` ## 配置 在项目根目录中创建一个 `.ez-appsec.yaml` 文件： ``` # 要扫描的编程语言 languages: - python - javascript - go - java # 要报告的最低严重级别 severity: medium # AI 模型配置 ai: model: gpt-4 temperature: 0.5 # 自定义检测规则 custom_rules: [] # 排除模式 exclude: - .git - node_modules - __pycache__ - .venv ``` ## 检测机制 ez-appsec 完全依赖于行业领先的开源安全扫描器： ### 外部扫描器（主要） - **[gitleaks](https://github.com/gitleaks/gitleaks)** - 具有 140+ 种模式的密钥检测 - **[semgrep](https://semgrep.dev/)** - 跨语言具有 1000+ 条规则的 SAST - **[kics](https://www.kics.io/)** - 基础设施即代码安全扫描 - **[grype](https://github.com/anchore/grype)** - 漏洞和 SBOM 分析 ### AI 增强 当提供 OPENAI_API_KEY 时，外部扫描器的所有发现都会通过 AI 驱动的分析进行增强，提供： - 详细的风险解释 - 分步修复指导 - 修复代码示例 ### AI 驱动的分析 当设置了 OPENAI_API_KEY 时，每个发现都会收到： - 详细的风险解释 - 分步修复指导 - 修复代码示例 ## 输出示例 ``` ✓ Security scan completed Total issues found: 5 Top Issues: [critical] Potential hardcoded secrets Found suspicious pattern in config.py [high] Potential SQL injection Found suspicious pattern in database.py [medium] Potential unsafe eval Found suspicious pattern in utils.py ``` ## 与 CI/CD 集成 ### GitHub Actions 通过创建 `.github/workflows/ez-appsec-scan.yml` 将 ez-appsec 扫描添加到任何 GitHub 仓库： ``` name: ez-appsec Security Scan on: pull_request: push: branches: [main] workflow_dispatch: permissions: contents: read security-events: write pull-requests: write jobs: scan: runs-on: ubuntu-latest container: image: ghcr.io/ez-appsec/ez-appsec:latest options: --entrypoint "" steps: - uses: actions/checkout@v4 - name: Run ez-appsec scan run: ez-appsec github-scan . --output scan-results/ez-appsec.sarif - name: Upload SARIF to GitHub Security if: always() uses: github/codeql-action/upload-sarif@v3 with: sarif_file: scan-results/ez-appsec.sarif continue-on-error: true ``` 请参阅 [`.github/workflows/github-scan.yml`](.github/workflows/github-scan.yml) 了解带有 PR 评论和仪表板集成的完整工作流。 ### Docker Compose ``` services: security-scan: image: ghcr.io/ez-appsec/ez-appsec:latest volumes: - .:/scan environment: - OPENAI_API_KEY=${OPENAI_API_KEY} command: scan . --output results.json ``` ### GitHub Pages 仪表板 有关完整功能文档和屏幕截图，请参阅下面的[仪表板](#dashboard)部分。 ``` # 将 dashboard 模板 Fork 到你的组织或用户账户 gh repo fork ez-appsec/ez-appsec-dashboard --org YOUR_ORG --clone # 启用 GitHub Pages (从 main 分支的 /public 提供服务) gh api --method PUT repos/YOUR_ORG/ez-appsec-dashboard/pages \ -f '{"source":{"branch":"main","path":"/public"}}' ``` 每个被扫描的仓库使用由 ez-appsec GitHub App 创建的短期令牌将结果推送到仪表板 —— 无需存储 PAT。 ## API 使用 ### 基本扫描 ``` from ez_appsec.scanner import SecurityScanner from ez_appsec.config import Config config = Config(severity="medium", ai_model="gpt-4") scanner = SecurityScanner(config) results = scanner.scan("/path/to/code") print(f"Found {results['total']} issues") ``` ### GitLab 漏洞格式 ``` from ez_appsec.scanner import SecurityScanner from ez_appsec.config import Config config = Config(severity="high") scanner = SecurityScanner(config) # 生成与 GitLab 兼容的漏洞报告 gitlab_report = scanner.scan_to_gitlab_format("/path/to/code", "report.json") print(f"Generated report with {len(gitlab_report['vulnerabilities'])} vulnerabilities") ``` ### GitHub SARIF 格式 生成与 GitHub Advanced Security 兼容的报告： ``` from ez_appsec.scanner import SecurityScanner from ez_appsec.config import Config config = Config(severity="high") scanner = SecurityScanner(config) # 生成 SARIF 报告 github_report = scanner.scan_to_github_format("/path/to/code", "report.json") print(f"Generated SARIF report with {len(github_report['runs'][0]['results'])} findings") ``` SARIF 格式与 GitHub 的安全功能兼容，可以通过 GitHub Actions 工作流上传。 ### 单个扫描器输出转换 ``` from ez_appsec.converters import VulnerabilityConverters # 将 gitleaks 输出转换为 GitLab 格式 report = VulnerabilityConverters.convert_scanner_output( "gitleaks", "gitleaks-output.json", "gitlab-report.json" ) # 支持的扫描器：gitleaks、semgrep、kics、grype ``` ## 仪表板 ez-appsec 安全仪表板是一个托管在 GitHub Pages（或 GitLab Pages）上的静态 Web 应用程序。它将来自一个或多个仓库的漏洞扫描结果聚合到单个视图中，具有筛选、向下钻取和 AI 驱动的修复指导功能。 ### 设置 ``` # 1. 将 dashboard 仓库 Fork 到你的 GitHub 组织 gh repo fork ez-appsec/ez-appsec-dashboard --org YOUR_ORG --clone # 2. 启用 GitHub Pages gh api --method PUT repos/YOUR_ORG/ez-appsec-dashboard/pages \ -f '{"source":{"branch":"main","path":"/public"}}' # 3. 在每个要扫描的仓库上安装 ez-appsec GitHub App # (自动配置扫描工作流和 secrets) # https://github.com/apps/ez-appsec/installations/new ``` 对于 GitLab，在 Claude Code 中运行 `/ez-appsec-install-dashboard ` 以自动创建和配置仪表板项目。 ### 概述 — 漏洞摘要 仪表板标题显示按严重性细分的总漏洞计数、平均发现时间指标和视觉严重性分布图表。**运行扫描**按钮直接链接到最新的 CI/CD 工作流运行。  ### 多项目侧边栏 当推送了来自多个仓库的扫描结果时，左侧会出现项目侧边栏。单击任何项目以将主视图筛选为仅该仓库的发现，或选择 **所有项目** 以查看聚合结果。  ### 漏洞列表 发现显示为按严重性排序（严重优先）的卡片。每张卡片显示： - 严重性徽章（颜色编码） - 发现标题和扫描器来源 - 受影响的文件和行号 - 简短描述 列表已分页（每页 100 个），并在筛选器更改时实时更新。  ### 筛选器 三个筛选器控件可在不重新加载页面的情况下缩小漏洞列表范围： | 筛选器 | 选项 | |--------|---------| | **严重性** | 全部 · 严重 · 高 · 中 · 低 · 信息 | | **扫描器** | 全部 · Gitleaks · Semgrep · Grype · KICS | | **搜索** | 跨标题、描述、文件路径的全文搜索 |  ### 发现详情 单击任何漏洞卡片以打开包含完整发现的详细信息模态框： - 规则 ID 和扫描器名称 - 严重性级别 - 受影响的文件路径和行号 - 完整描述 - CVE 引用（如果可用） - 指向源提交的链接  ### AI 修复指导 每个发现都包含一个 **AI 修复**按钮，可打开一个修复面板，其中包含： - 风险的通俗语言解释 - 分步修复说明 - 代码示例（如适用） 需要在扫描环境中设置 `OPENAI_API_KEY`。  ### GitHub Security 标签页 (SARIF) 当 `github-scan` 工作流运行时，发现结果通过 SARIF 上传到 GitHub Security 标签页。这不需要任何额外配置 —— 工作流会自动处理上传。  ### PR 评论 在拉取请求上，工作流会发布摘要评论，其中包含发现计数和完整运行产物链接。  ## 贡献 欢迎贡献！可改进的领域： - [ ] 额外的语言支持（Rust、C/C++、C#） - [ ] 自定义规则定义 - [ ] 与更多 AI 提供商集成 - [ ] 大型代码库的性能优化 - [ ] 用于减少误报的机器学习模型 ## 路线图 - **v0.2.0**：支持 Rust 和 C/C++ - **v0.3.0**：自定义规则引擎和策略执行 - **v0.4.0**：与 Claude、Gemini 和本地 LLM 集成 - **v1.0.0**：生产就绪版本发布 ## 许可证 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件 ## 支持 - 📖 [文档](./docs) - 🐛 [问题跟踪器](https://github.com/ez-appsec/ez-appsec/issues) - 💬 [讨论](https://github.com/ez-appsec/ez-appsec/discussions) - 🔒 [安全策略](./SECURITY.md) ## 作者 由 [John Felten](https://www.linkedin.com/in/john-felten/) 创建 —— 拥有 25 年以上经验的 DevSecOps 工程师 ## 免责声明 虽然 ez-appsec 旨在全面，但没有任何安全工具能捕获所有漏洞。在部署到生产环境之前，请始终进行全面的安全审查和渗透测试。

标签：AI安全, Angular, Chat Copilot, DevSecOps, FTP漏洞扫描, GitLab, Gitleaks, Grype, Kics, LLM, OpenAI, Petitpotam, SARIF, SAST, Semgrep, Unmanaged PE, WordPress安全扫描, 上游代理, 云安全监控, 人工智能, 内存规避, 多语言支持, 安全测试框架, 安全编排, 本地化部署, 漏洞修复, 用户模式Hook绕过, 盲注攻击, 网络安全培训, 请求拦截, 逆向工具, 零配置, 静态分析