fagougou/ScanGuard

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

main

ScanGuard/README.md

feat: 添加 SONAR_HOST 作为命令行参数支持

63c63ac2

PreviewCode viewBlame

Raw

ScanGuard 🛡️

ScanGuard 是一个团队级的综合安全扫描工具集，提供容器镜像安全扫描和代码质量扫描功能，支持多语言、多团队、灵活配置。

📋 项目概述

本项目包含两个主要功能模块：

镜像扫描 (Image Scan) - 使用 Trivy 扫描 Docker 镜像的安全漏洞
代码扫描 (Code Scan) - 使用 SonarQube 进行代码质量分析和安全漏洞检测

✨ 核心特性

🌍 多语言支持：Python、Java、JavaScript/TypeScript、Go、C#、PHP 等
📊 灵活配置：严格、标准、宽松三种预设模式，支持自定义
👥 团队协作：统一的配置管理，适应不同团队需求
🔄 CI/CD 集成：无缝接入 GitLab/Jenkins/GitHub Actions/CNB 平台
💬 企微通知：扫描结果自动推送到企业微信
📈 质量门禁：可配置的质量标准和问题阈值

📁 项目结构


ScanGuard/
├── README.md                      # 项目主文档
├── docs/                          # 文档目录
│   ├── TEAM_GUIDE.md             # 团队使用指南
│   ├── CHANGELOG.md              # 更新日志
│   ├── EXAMPLES.md               # 使用示例
│   ├── QUICK_REFERENCE.md        # 快速参考
│   ├── SCAN_CAPABILITIES.md      # 扫描能力说明
│   └── ...                       # 其他文档
├── configs/                       # 配置模板目录
│   ├── README.md                 # 配置文件说明
│   ├── strict.conf               # 严格模式配置
│   ├── standard.conf             # 标准模式配置
│   ├── relaxed.conf              # 宽松模式配置
│   ├── python.conf               # Python 项目配置
│   ├── java.conf                 # Java 项目配置
│   ├── javascript.conf           # JS/TS 项目配置
│   ├── exclusions-python.txt     # Python 排除模板
│   ├── exclusions-java.txt       # Java 排除模板
│   └── exclusions-javascript.txt # JS 排除模板
├── integrations/                  # CI/CD 集成目录 ⭐
│   ├── README.md                 # 集成指南
│   ├── QUICK_START.md            # 快速开始
│   ├── image-scan/               # 镜像扫描集成配置
│   │   ├── gitlab-ci.yml        # GitLab CI 配置
│   │   ├── github-actions.yml   # GitHub Actions 配置
│   │   ├── jenkins-pipeline.groovy # Jenkins Pipeline
│   │   └── cnb.yml              # CNB 平台配置 ⭐
│   ├── code-scan/                # 代码扫描集成配置
│   │   ├── gitlab-ci.yml        # GitLab CI 配置
│   │   ├── github-actions.yml   # GitHub Actions 配置
│   │   ├── jenkins-pipeline.groovy # Jenkins Pipeline
│   │   └── cnb.yml              # CNB 平台配置 ⭐
│   ├── CNB_GUIDE.md             # CNB 平台集成指南 ⭐
│   └── scripts/                  # 可执行脚本
│       ├── image-scan.sh         # 镜像扫描一键脚本
│       └── code-scan.sh          # 代码扫描一键脚本
├── image-scan/                    # 镜像扫描模块
│   ├── scan.sh                   # 镜像扫描脚本
│   ├── generate_report.py        # 报告生成脚本
│   ├── README.md                 # 镜像扫描使用说明
│   └── tests/                    # 单元测试
│       ├── test_generate_report.py  # 报告生成测试
│       ├── test_data.py          # 测试数据
│       └── README.md             # 测试说明
└── code-scan/                     # 代码扫描模块
    ├── docker-compose.yml        # SonarQube 服务配置
    ├── scan.sh                   # 代码扫描脚本
    ├── generate_report.py        # 报告生成脚本
    ├── sonar-rules.conf          # 规则配置文件
    ├── exclusions.txt            # 扫描排除规则
    ├── README.md                 # 代码扫描使用说明
    └── CONFIG_GUIDE.md           # 配置详细指南

🚀 快速开始

方式一：团队首次使用（推荐）

如果你是第一次使用 ScanGuard，或者需要为团队配置扫描工具，请查看：

📖 团队使用指南 - 详细的团队使用和配置说明

方式三：镜像扫描

扫描 Docker 镜像的安全漏洞：


cd image-scan
./scan.sh <镜像名称> [阻断级别] [企业微信Webhook Key]

示例：


# 基本扫描（使用默认 HIGH 级别）
./scan.sh nginx:latest

# 指定阻断级别
./scan.sh nginx:latest CRITICAL

# 扫描并发送企业微信通知（使用 webhook key）
./scan.sh nginx:latest HIGH "your-webhook-key-here"

# 或使用环境变量（推荐）
export WECHAT_KEY="your-webhook-key-here"
./scan.sh nginx:latest HIGH

更多详情请查看 image-scan/README.md

方式四：代码扫描

步骤 1：选择配置模板

根据项目类型选择合适的配置：


# Python 项目
cp configs/python.conf <项目目录>/sonar-rules.conf
cp configs/exclusions-python.txt <项目目录>/exclusions.txt

# Java 项目
cp configs/java.conf <项目目录>/sonar-rules.conf
cp configs/exclusions-java.txt <项目目录>/exclusions.txt

# JavaScript/TypeScript 项目
cp configs/javascript.conf <项目目录>/sonar-rules.conf
cp configs/exclusions-javascript.txt <项目目录>/exclusions.txt

# 或者按严格程度选择
cp configs/standard.conf <项目目录>/sonar-rules.conf  # 标准模式（推荐）
cp configs/strict.conf <项目目录>/sonar-rules.conf    # 严格模式
cp configs/relaxed.conf <项目目录>/sonar-rules.conf   # 宽松模式

步骤 2：启动 SonarQube 服务（首次使用）


cd code-scan
docker-compose up -d

等待服务启动后，访问 http://localhost:9000 进行初始配置。

步骤 3：执行代码扫描


cd code-scan
./scan.sh <SonarQube_Token> [项目Key] [输出文件] [企业微信Key]

示例：


export SONAR_TOKEN=sqa_xxxxx
export SONAR_PROJECT=my-project
cd code-scan
./scan.sh

更多详情请查看：

🔧 环境要求

镜像扫描

Docker（推荐）或 Trivy 二进制文件
可选：Python 3（用于企业微信通知）

代码扫描

Docker 和 Docker Compose
SonarQube 服务器（可通过 docker-compose 启动）
Python 3（用于报告生成）

📝 功能特性

镜像扫描

✅ 使用 Trivy 进行容器镜像安全扫描
✅ 支持 Docker 和本地二进制两种模式
✅ 可配置阻断级别（CRITICAL, HIGH, MEDIUM, LOW, NONE）
✅ 企业微信 Markdown 格式告警通知和报告文件上传
✅ 自动生成详细的 Markdown 格式报告
✅ 环境自适应（自动检测 Docker 或本地 Trivy）
✅ 安全的 webhook key 传递方式（支持环境变量和命令行参数）
✅ 包含完整的单元测试

代码扫描

✅ 使用 SonarQube 进行代码质量分析
✅ 支持多种编程语言（Python, Java, JavaScript/TypeScript, Go, C#, PHP 等）
✅ 自动检测项目类型和编译目录
✅ 生成详细的 Markdown 格式报告
✅ 支持企业微信报告上传和通知
✅ 历史报告索引和管理
✅ 灵活的扫描排除规则配置

配置系统（新）

✅ 多严格程度：严格、标准、宽松三种预设模式
✅ 语言专用配置：Python、Java、JavaScript 等专用模板
✅ 自定义规则：支持 Cognitive Complexity、函数参数、行数等规则配置
✅ 质量门禁：可配置代码覆盖率、重复率、技术债务等指标
✅ 团队协作：配置文件可纳入版本控制，统一团队标准
✅ 自动应用：扫描时自动读取配置并尝试应用到 SonarQube 服务器

📊 报告格式

镜像扫描报告

JSON 格式的详细扫描结果
企业微信 Markdown 格式摘要（包含漏洞统计和详情）

代码扫描报告

Markdown 格式的详细报告
包含问题统计、按文件分组的问题列表
支持企业微信文件上传

🔐 安全注意事项

Token 安全：请妥善保管 SonarQube Token，不要提交到代码仓库
Webhook Key 安全：
- ⚠️ 不要硬编码 webhook key 到脚本中
- ✅ 推荐使用环境变量：export WECHAT_KEY="your-key"
- ✅ 或通过命令行参数传入：./scan.sh <image> [level] [key]
- ✅ 在 CI/CD 中使用密钥管理工具（如 GitLab CI Variables、GitHub Secrets）
报告文件：扫描报告可能包含敏感信息，请妥善保管

🎯 团队使用场景

场景 1：后端团队（Python/Django）


cp configs/python.conf sonar-rules.conf
cp configs/exclusions-python.txt exclusions.txt
# 根据需要调整配置

场景 2：前端团队（React/Vue）


cp configs/javascript.conf sonar-rules.conf
cp configs/exclusions-javascript.txt exclusions.txt

场景 3：Java 团队（Spring Boot）


cp configs/java.conf sonar-rules.conf
cp configs/exclusions-java.txt exclusions.txt

场景 4：遗留代码项目


# 使用宽松模式，逐步改进
cp configs/relaxed.conf sonar-rules.conf

更多使用场景请查看 TEAM_GUIDE.md

📚 配置选择指南

项目类型	推荐配置	说明
新项目	`strict.conf` 或 `standard.conf`	从高标准开始
成熟项目	`standard.conf` ⭐	平衡质量和效率
遗留代码	`relaxed.conf`	逐步改进
Python 项目	`python.conf`	语言特定优化
Java 项目	`java.conf`	企业级 Java
前端项目	`javascript.conf`	现代前端框架

详细配置说明请查看：

🧪 测试

镜像扫描模块测试

镜像扫描模块包含完整的单元测试：


cd image-scan/tests
python3 -m unittest discover -s . -p "test_*.py" -v

测试覆盖：

✅ 报告加载和解析
✅ 漏洞分析和统计
✅ Markdown 报告生成
✅ 企业微信上传（使用 Mock）
✅ 边界情况和错误处理

更多详情请查看 image-scan/tests/README.md

📖 文档导航

文档	说明
README.md	项目主文档（当前）
integrations/README.md	CI/CD 集成指南 ⭐
integrations/QUICK_START.md	快速集成指南 ⚡
integrations/CNB_GUIDE.md	CNB 平台集成指南 ⭐
docs/TEAM_GUIDE.md	团队使用指南
docs/CHANGELOG.md	更新日志
docs/EXAMPLES.md	使用示例
docs/QUICK_REFERENCE.md	快速参考
docs/SCAN_CAPABILITIES.md	扫描能力说明
configs/README.md	配置模板说明
code-scan/README.md	代码扫描使用说明
code-scan/CONFIG_GUIDE.md	配置详细指南
image-scan/README.md	镜像扫描使用说明
image-scan/tests/README.md	测试说明

🔧 CI/CD 集成

⚡ 快速集成（推荐）

无需下载项目，直接使用远程脚本：


# 镜像扫描
curl -sL https://cnb.cool/fagougou/ScanGuard/-/git/raw/main/integrations/scripts/image-scan.sh | \
bash -s -- <镜像名称> [阻断级别] [webhook_key]

# 代码扫描
curl -sL https://cnb.cool/fagougou/ScanGuard/-/git/raw/main/integrations/scripts/code-scan.sh | \
bash -s -- <token> <project> [output] [wechat_key] [scan_dir] [sonar_host]