supplyshield/supplyshield

# 🛡️ SupplyShield .. image:: https://github.com/supplyshield/supplyshield/blob/develop/docs/images/logo.png :alt: SupplyShield Logo :align: center SupplyShield 是一个开源的应用安全编排框架，旨在保护您的软件供应链免受漏洞、恶意依赖和未经批准的基础镜像的侵害。它提供了一个全面的解决方案，用于自动化检测、优先级排序和修复开源依赖和容器化应用中的安全问题。 |Python 3.10+| |stability-wip| .. |Python 3.10+| image:: https://img.shields.io/badge/python-3.10+-green.svg :target: https://www.python.org/downloads/release/python-3100/ .. |stability-wip| image:: https://img.shields.io/badge/stability-work_in_progress-lightgrey.svg .. note:: SupplyShield 处于积极开发中，相关发行版可在 GitHub 的 "releases" 部分获取。 📚 请访问 `文档 `_ 以了解更多 SupplyShield 信息。 ## 🚀 功能特性 - **自动化 SBOM 生成：** 使用 cdxgen 生成软件物料清单（SBOM），支持多种包管理器（Java、Python、Node.js、Go 等）。 - **全面的软件组成分析（SCA）：** 识别开源依赖中的漏洞。 - **基于 EPSS 的漏洞优先级排序：** 利用漏洞利用预测评分系统（EPSS）根据漏洞被利用的可能性进行优先级排序。 - **可操作的安全发现：** 自动识别安全的包版本，并为易受攻击的依赖提供升级建议。 - **GitHub 集成：** 与 GitHub 无缝集成，自动创建包含安全发现的问题。 - **CI/CD 流水线集成：** 通过消息队列处理 CI/CD 流水线中的扫描请求。 - **构建对比：** 对比不同构建之间的漏洞和包变化，以跟踪随时间的安全改进。 - **仓库管理：** 提供包含过滤、统计和跨环境漏洞跟踪的完整仓库列表。 - **多环境支持：** 跨不同部署环境（开发、预生产、生产）跟踪和管理安全发现。 - **基于 Docker 的架构：** 使用 Docker Compose 提供的完全容器化部署，便于设置和扩展。 **技术栈：** 🐍 Python | 🌶️ Flask | 🐘 PostgreSQL | 🐳 Docker ## 🚀 安装与设置 ## 先决条件 - 系统中已安装 Docker 和 Docker Compose - 用于克隆仓库的 Git - 访问所需的密钥和凭证（请参见下方的配置部分） ## 步骤 1：获取源代码 克隆包含所有子模块的项目仓库并进入项目目录： .. code-block:: bash git clone --recurse-submodules https://github.com/supplyshield/supplyshield/ cd supplyshield ## 步骤 2：配置环境变量 在根目录创建一个 `docker.env` 文件。该文件包含运行 SupplyShield 所需的所有配置变量。 ### 必需的配置变量 **数据库配置：** .. code-block:: bash # PostgreSQL 数据库用于 ScanCode.io POSTGRES_DB=scancodeio POSTGRES_USER=scancodeio POSTGRES_PASSWORD=scancodeio POSTGRES_HOST_AUTH_METHOD=trust POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=en_US.UTF-8 --lc-ctype=en_US.UTF-8 # SupplyShield 服务的数据库配置 DB_HOSTNAME=db DB_USERNAME=scancodeio DB_PASSWORD=scancodeio # ScanCode.io 数据库配置 SCANCODEIO_DB_HOST=db SCANCODEIO_DB_NAME=scancodeio SCANCODEIO_DB_USER=scancodeio SCANCODEIO_DB_PASSWORD=scancodeio # PurlDB 数据库配置（使用相同的数据库实例，不同的模式） PACKAGEDB_DB_HOST=db PACKAGEDB_DB_NAME=packagedb PACKAGEDB_DB_USER=scancodeio PACKAGEDB_DB_PASSWORD=scancodeio **AWS 配置（CI/CD 集成和 SBOM 上传必需）：** .. code-block:: bash AWS_DEFAULT_REGION=ap-south-1 AWS_ACCESS_KEY_ID=your-access-key-id AWS_SECRET_ACCESS_KEY=your-secret-access-key S3_BUCKET_NAME=your-s3-bucket-name SQS_QUEUE_NAME=your-sqs-queue-name **GitHub 应用配置（仓库克隆和问题创建必需）：** .. code-block:: bash GIT_PROVIDER=github GIT_ORG=your-organization GITHUB_APP_APP_ID=your-github-app-id GITHUB_APP_INSTALLATION_ID=your-installation-id **服务 URL：** .. code-block:: bash SCANCODEIO_URL=http://scancodeio:8000 SUPPLYSHIELD_BASE=http://web:5000 PURLDB_URL=http://purldb:8000 PURLDB_API_URL=http://purldb:8000/api VULNERABLECODE_URL=https://public.vulnerablecode.io/ **可选配置：** .. code-block:: bash # Jira 集成（可选） JIRA_URL=https://org_name.atlassian.net JIRA_USER=your-email@example.com JIRA_TOKEN=your-jira-token # 服务元数据 URL（可选） SERVICE_METADATA_URL=https://your-metapod-url # 允许的主机 ALLOWED_HOSTS=scancodeio,your-server-ip # Django 密钥 SECRET_KEY=your-secret-key-here # Go 私有模块配置（可选） GO_PRIVATE=your-go-private-config ## 步骤 3：设置 GitHub 应用私钥 SupplyShield 需要 GitHub 应用私钥来验证与 GitHub 的通信。将您的私钥文件放置在以下位置： .. code-block:: bash etc/secrets/github_app_private_key.pem 私钥文件应为 PEM 格式，并且必须与 `docker.env` 中配置的 GitHub 应用 ID 匹配。 .. note:: GitHub 应用必须具有以下权限： - **内容**：读取（用于克隆仓库） - **问题**：写入（用于创建/更新问题） - **元数据**：读取（所有 GitHub 应用必需） ## 步骤 4：使用 Docker Compose 启动服务 启动所有 SupplyShield 服务： .. code-block:: bash sudo docker compose up -d 此命令将启动以下服务： - **db**：PostgreSQL 数据库 - **scancode-migrate**：运行 ScanCode.io 的数据库迁移 - **scancodeio**：ScanCode.io 服务（端口 8002） - **daemon**：SupplyShield 守护服务（端口 8001） - **crons**：定时任务运行器 - **purldb**：PurlDB 服务（端口 8003） - **web**：SupplyShield Web 界面（端口 8000） ## 步骤 5：验证安装 检查所有服务是否正在运行： .. code-block:: bash sudo docker compose ps 所有服务应显示为“Up”或“Healthy”。您还可以访问： - Web 界面：http://localhost:8000 - ScanCode.io：http://localhost:8002 - PurlDB API：http://localhost:8003 ## 📖 使用指南 ## 扫描单个仓库 要扫描单个仓库，请使用 `process-message` 命令。这将： 1. 克隆仓库 2. 生成 SBOM（软件物料清单） 3. 扫描依赖项中的漏洞 4. 将结果存储在数据库中 **命令格式：** .. code-block:: bash sudo docker compose run --rm daemon libinv process-message '' **示例：** .. code-block:: bash sudo docker compose run --rm daemon libinv process-message '{ "repository": { "url": "https://github.com/org/repo.git", "commit": "da80e73b4376a0c8d3c6404f272b8f04e6568f40", "tag": "da80e73" }, "job_url": "https://jenkins/job/XYZ/", "aws_environment": "prod", "buildx_enabled":1", "ecr_image": [], "type": "Bridge", "timestamp": "2025-11-22-06:52:17" }' **必需的 JSON 字段：** - ``repository.url``：Git 仓库 URL（必需） - 应以 ``.git`` 结尾 - ``repository.commit``：Git 提交 SHA（必需） - ``type``：消息类型，必须为 ``"Bridge"`` 用于仓库扫描（必需） - ``timestamp``：时间戳格式为 ``"YYYY-MM-DD-HH:MM:SS"``（必需） - ``aws_environment``：环境名称（必需） - ``job_url``：CI/CD 作业 URL（必需） **可选的 JSON 字段：** - ``repository.tag``：Git 标签或分支名称（可选） - ``buildx_enabled``：是否启用 Docker buildx（可选，默认为 ``"1"``） - ``ecr_image``：ECR 镜像列表（可选，默认为 ``[]``） **带调试输出：** .. code-block:: bash sudo docker compose run --rm daemon libinv --debug process-message '' ## 查找易受攻击包的安全版本 **填充可操作的 PURL 版本：** 获取并存储可操作包的可用版本： .. code-block:: bash sudo docker compose run --rm daemon libinv populate-actionable-purl-versions **扫描正在使用的版本：** 扫描当前正在使用的所有包版本： .. code-block:: bash sudo docker compose run --rm daemon libinv --debug scan-versions-in-use **扫描最新版本：** 扫描没有已知安全版本的包的最新版本： .. code-block:: bash sudo docker compose run --rm daemon libinv --debug scan-latest-versions **填充下一个安全版本：** 为每个易受攻击的包查找并填充最接近的安全版本： .. code-block:: bash sudo docker compose run --rm daemon libinv --debug populate-next-safe-versions ## 更新 EPSS 分数 EPSS（漏洞利用预测评分系统）分数有助于根据漏洞被利用的可能性来优先处理漏洞。SupplyShield 可以更新 CVE 的 EPSS 分数。 **更新所有可操作 CVE 的 EPSS：** 此命令将更新可操作包中所有 CVE 的 EPSS 分数： .. code-block:: bash sudo docker compose run --rm daemon libinv --debug epss-update --all-actionable-cves **计算包 EPSS 分数：** 在更新 CVE 的 EPSS 分数后，计算每个包的最高 EPSS 分数： .. code-block:: bash sudo docker compose run --rm daemon libinv --debug calculate-package-epss 此命令将： 1. 获取所有成功扫描的包 2. 提取每个包的 CVE 3. 从这些 CVE 中找到最高的 EPSS 分数 4. 使用最高 EPSS 分数更新包记录 ## 将安全问题提升为 Git 问题 SupplyShield 可以自动为仓库创建或更新 GitHub 问题，其中包含可操作的安全发现。 **先决条件：** - 仓库必须已经过扫描（请先使用 `process-message`） - 仓库必须在 GitHub 上启用了 Issues - GitHub 应用必须具有 "Issues: Write" 权限 **命令格式：** .. code-block:: bash sudo docker compose run --rm daemon libinv raise-sca-as-git-issue "" **示例：** .. code-block:: bash sudo docker compose run --rm daemon libinv raise-sca-as-git-issue "https://github.com/org/repo.git" **带调试输出：** .. code-block:: bash sudo docker compose run --rm daemon libinv --debug raise-sca-as-git-issue "https://github.com/org/repo.git" **此命令的作用：** 1. 在数据库中找到仓库 2. 识别可操作的安全发现（易受攻击的包） 3. 创建或更新 GitHub 问题，内容包括： - 易受攻击的包列表 - 当前使用的版本 - 建议的安全版本 - 用于优先级的 EPSS 分数 - 包详情和升级路径 **故障排除：** - 如果出现 "Issues has been disabled in this repository"，请在仓库设置中启用 Issues - 如果出现 "Couldn't find in database"，请先使用 `process-message` 扫描仓库 - 检查 GitHub 应用权限，确保已启用 "Issues: Write" ## 定时任务 `crons` 服务会自动运行 `docker-compose.yml` 中配置的定时任务。这些任务包括： - **populate_actionable_purl_versions**：获取可操作包的可用版本（每 2 天） - **update_latest_version_tag**：为每个包标记最新版本（每 2 天） - **scan_versions_in_use**：扫描当前正在使用的所有包版本（每 2 天） - **scan_latest_versions**：扫描没有安全版本的包的最新版本（每 2 天） - **populate_next_safe_versions**：查找最近的安全版本（每 2 天） - **epss_update**：更新所有可操作 CVE 的 EPSS 分数（每天） - **calculate_package_epss**：计算包 EPSS 分数（每天） 这些任务会自动运行，无需人工干预。 ## 🏗️ 架构图 以下图表说明了 SupplyShield 的架构： .. image:: ./docs/images/architecture-simplified.png :alt: SupplyShield 架构简化图 :align: center ## 👥 贡献者 - Akhil Mahendra - Hritik Vijay - Rahul Sunder - Roshan Kumar - Yadhu Krishna M .. note:: 我们欢迎贡献！如果您想为 SupplyShield 做出贡献，请查看我们的文档，并随时提交问题或拉取请求。 ## 📄 版权声明 Copyright (c) SupplyShield 及其相关方。保留所有权利。

标签：cdxgen, CI/CD 安全, DevSecOps, EPSS, GitHub 安全集成, GPT, Python, SBOM, Web截图, XML 请求, 上游代理, 供应链攻击防护, 依赖安全, 安全优先级, 安全修复建议, 安全开发, 容器安全, 应用安全编排, 开源组件审计, 数据投毒防御, 无后门, 构建对比, 测试用例, 消息队列, 漏洞管理, 硬件无关, 自动化安全扫描, 请求拦截, 软件供应链安全, 远程方法调用, 逆向工具