# CodeGuard

**Repository Path**: hui4412/code-guard

## Basic Information

- **Project Name**: CodeGuard
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-27
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 仓库风险扫描 Agent

专注于 Spring Boot + Vue 项目的安全风险扫描工具。

## 项目定位

Repo Risk Agent 是一个 **AI 增强的代码仓库风险扫描平台**，通过集成多种成熟扫描工具并结合 AI 复核，帮助开发者发现代码中的安全风险。

核心价值：
- **多扫描器集成** - 统一管理 Semgrep、Gitleaks、Trivy、SpotBugs、ESLint 等工具
- **AI 复核** - 使用大模型降低误报率，提供修复建议
- **结构化报告** - 输出 JSON 和 Markdown 格式，便于集成和阅读

## 扫描器验证状态

> **重要提示**: 外部扫描器需要用户本地安装。未安装时自动回退到内置扫描器。

| 扫描器 | 代码接入 | 本地验证 | Fixture 验收 | 说明 |
|--------|----------|----------|-------------|------|
| 内置扫描器 | ✅ | ✅ | ✅ | 正则表达式检测，无需安装，始终可用 |
| Semgrep | ✅ | ✅ | ✅ | 通用 SAST，需本地安装 `semgrep` |
| Gitleaks | ✅ | ✅ | ✅ | 密钥泄露检测，需本地安装 `gitleaks` |
| Trivy | ✅ | ✅ | ✅ | 依赖漏洞扫描，需本地安装 `trivy` |
| ESLint | ✅ | ✅ | ✅ | 前端代码检查，需本地安装 `eslint` |
| SpotBugs | ✅ | ❌ | ❌ | Java 字节码分析，需要 Java + SpotBugs 安装 |

**状态说明**:
- **代码接入**: Runner 代码已实现，命令构造正确
- **本地验证**: 本机 `repo-risk-agent check` 可识别，二进制可执行
- **Fixture 验收**: 在 Vue / Spring Boot fixture 上可产生有效结果

### 已知限制

1. 外部扫描器需要用户本地安装，未安装时回退到内置扫描器
2. 内置扫描器使用正则表达式，覆盖面和准确率有限
3. SpotBugs 需要先安装 Java JDK 并编译项目才能扫描
4. AI 复核需要配置 API Key，无 Key 时跳过
5. 当前主要支持 Java 和 JavaScript/TypeScript/Vue
6. 跨平台 (Linux/macOS) 兼容性尚未完整验证

## 安装

```bash
# 克隆仓库
git clone https://github.com/your-username/repo-risk-agent.git
cd repo-risk-agent

# 创建虚拟环境
python -m venv .venv

# 激活虚拟环境
# Windows
.venv\Scripts\activate
# Linux/Mac
source .venv/bin/activate

# 安装依赖
pip install -e ".[dev]"
```

### 安装外部扫描器（可选）

```bash
# Semgrep (通用 SAST) - 已验证版本: 1.163.0
pip install semgrep

# Gitleaks (密钥泄露检测) - 已验证版本: 8.30.1
# Windows: scoop install gitleaks
# 或从 https://github.com/gitleaks/gitleaks/releases 下载

# Trivy (依赖漏洞扫描) - 已验证版本: 0.70.0
# Windows: scoop install trivy
# 或从 https://trivy.dev/ 下载

# ESLint (前端代码检查) - 已验证版本: 8.x / 10.x
npm install -g eslint

# SpotBugs (Java 字节码分析) - 需要 Java JDK
# https://spotbugs.github.io/
```

安装完成后执行 `repo-risk-agent check` 验证扫描器是否可用。

详细安装说明请参考 [开源准备文档](docs/open-source-readiness.md)。

## 使用方式

### 方式一：命令行工具（推荐）

安装后可直接使用 `repo-risk-agent` 命令：

```bash
# 查看帮助
repo-risk-agent --help

# 查看版本
repo-risk-agent version

# 检查扫描器可用性
repo-risk-agent check

# 执行扫描
repo-risk-agent scan /path/to/repo

# 指定输出目录
repo-risk-agent scan /path/to/repo --output ./my-reports

# 跳过 AI 复核
repo-risk-agent scan /path/to/repo --skip-ai

# 指定扫描器
repo-risk-agent scan /path/to/repo --scanners semgrep,gitleaks
```

### 方式二：直接运行 main.py

```bash
python main.py scan /path/to/repo
python main.py check
```

### 方式三：Python 模块运行

```bash
python -m repo_risk_agent.cli scan /path/to/repo
```

## 快速体验

项目提供了验收样例，可快速体验扫描效果：

```bash
# 扫描 Vue 风险样例
repo-risk-agent scan ./fixtures/vue-risk-sample --skip-ai

# 扫描 Spring Boot 风险样例
repo-risk-agent scan ./fixtures/springboot-risk-sample --skip-ai
```

样例包含故意引入的安全风险，用于验证扫描器能力。详见：
- [Vue 风险样例说明](fixtures/vue-risk-sample/README.md)
- [Spring Boot 风险样例说明](fixtures/springboot-risk-sample/README.md)

## 参数说明

### scan 命令

| 参数 | 简写 | 说明 | 示例 |
|------|------|------|------|
| `repo_path` | - | 待扫描的仓库路径（必填） | `./my-project` |
| `--config` | `-c` | 配置文件路径 | `--config config.yaml` |
| `--output` | `-o` | 报告输出目录 | `--output ./reports` |
| `--scanners` | `-s` | 指定扫描器（逗号分隔） | `--scanners semgrep,gitleaks` |
| `--skip-ai` | - | 跳过 AI 复核 | `--skip-ai` |

### check 命令

检查系统中可用的扫描器。

### version 命令

显示版本信息。

## 输出报告

扫描完成后，报告默认保存在 `./reports/` 目录：

- `report.json` - 结构化 JSON 报告
- `report.md` - 可读的 Markdown 报告

报告包含：
- 扫描器状态和可用性
- 问题来源分布（外部 vs 内置）
- 按严重程度分类的问题列表
- AI 复核结果和修复建议

## 配置文件

默认配置文件位于 `src/repo_risk_agent/config/config.yaml`。

可通过 `--config` 参数指定自定义配置文件。

### 配置示例

```yaml
# 扫描器配置
scanners:
  semgrep:
    enabled: true
    rules:
      - "p/security-audit"
      - "p/java"
  eslint:
    enabled: true

# AI 配置
ai:
  api_key: "your-api-key"
  model: "gpt-4"
  base_url: "https://api.openai.com/v1"

# 扫描配置
scan:
  exclude_dirs:
    - "node_modules"
    - "dist"
    - "target"
  exclude_patterns:
    - "*.min.js"
    - "*.umd.js"
```

## 环境变量

| 变量名 | 说明 |
|--------|------|
| `REPO_RISK_AGENT_AI_API_KEY` | AI API Key（优先级高于配置文件） |

## 项目结构

```
repo-risk-agent/
├── src/
│   └── repo_risk_agent/
│       ├── ai/           # AI 复核和建议生成
│       ├── config/       # 配置加载
│       ├── context/      # 上下文构建
│       ├── normalizer/   # 结果归一化
│       ├── report/       # 报告生成
│       └── scanner/      # 扫描器集成
├── tests/                # 测试用例
├── fixtures/             # 验收样例
│   ├── vue-risk-sample/
│   └── springboot-risk-sample/
├── docs/                 # 文档
├── reports/              # 扫描报告（运行产物，不纳入版本控制）
├── main.py               # 直接运行入口
├── pyproject.toml        # 项目配置
├── README.md             # 本文件
├── LICENSE               # MIT 许可证
├── CONTRIBUTING.md       # 贡献指南
└── CHANGELOG.md          # 更新日志
```

## 贡献

欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE)。

## 相关文档

- [1.0 发布门槛](docs/release/v1.0-release-gate.md) - 发布条件和验证状态
- [开源准备状态](docs/open-source-readiness.md) - 详细的能力边界和已知限制
- [架构文档](docs/architecture/) - 系统架构说明
- [整改记录](docs/rectifications/) - 项目整改历史