内容
# GitHub 安全检查工具
> ⚠️ **免责声明**: 这是一个非官方的、社区建设的工具，与 GitHub, Inc. 无关，不受其支持或认可。
用于扫描 GitHub 仓库的安全配置问题和最佳实践的综合工具。提供可行的建议和 SOC 2 合规报告。
## 功能
- **安全扫描**: 对分支保护、安全功能、访问控制和仓库设置进行 40 多项检查
- **建议**: 为每个发现提供具体的缓解步骤和文档链接
- **SOC 2 报告**: 生成符合 SOC 2 信托服务标准的合规报告
- **多个接口**: CLI、MCP 服务器（用于 AI 助手）和 Web 仪表盘
## 安全检查（40 多项）
### 分支保护（12 项检查）
| 检查 | 严重程度 | 描述 |
|-------|----------|-------------|
| 启用分支保护 | 关键 | 验证默认分支上存在保护规则 |
| 需要拉取请求审查 | 高 | 在合并前需要拉取请求审查 |
| 解除过时审查 | 中 | 当推送新提交时解除审批 |
| 代码所有者审查 | 中 | 需要代码所有者审查 |
| 需要审查者数量 | 中 | 强制执行最低审查者数量（推荐：2） |
| 管理员绕过限制 | 高 | 防止管理员绕过规则 |
| 需要状态检查 | 高 | 在合并前需要 CI/CD 检查通过 |
| 强制推送限制 | 高 | 防止重写历史的强制推送 |
| 分支删除限制 | 中 | 防止删除受保护的分支 |
| 会话解决 | 低 | 需要解决所有审查评论 |
| 需要签名提交 | 中 | 需要 GPG/SSH 签名提交 |
| 需要线性历史 | 低 | 强制执行压缩或变基合并 |
### 安全功能（9 项检查）
| 检查 | 严重程度 | 描述 |
|-------|----------|-------------|
| 安全策略（SECURITY.md） | 中 | 漏洞报告说明 |
| Dependabot 警报 | 高 | 依赖项漏洞警报 |
| Dependabot 配置 | 中 | 自动依赖项版本更新 |
| 代码扫描（CodeQL） | 高 | 安全漏洞的静态分析 |
| 机密扫描 | 高 | 检测意外提交的机密 |
| 推送保护 | 信息 | 阻止包含机密的提交 |
| 关键漏洞警报 | 关键 | 未解决的关键 Dependabot 警报 |
| 高漏洞警报 | 高 | 未解决的高严重性警报 |
| 私有漏洞报告 | 信息 | GitHub 安全顾问已启用 |
### 访问控制（8 项检查）
| 检查 | 严重程度 | 描述 |
|-------|----------|-------------|
| 公共仓库警告 | 信息 | 仓库公开可访问时的提醒 |
| 管理员数量 | 中 | 标志过多管理员访问（> 5 用户） |
| 外部协作者 | 信息 | 跟踪具有写入权限的非组织成员 |
| 部署密钥具有写入权限 | 中 | 确定可以推送的部署密钥 |
| 旧部署密钥 | 低 | 标志使用超过 1 年的部署密钥 |
| 不安全 Webhook URL | 高 | 使用 HTTP 而不是 HTTPS 的 Webhook |
| Webhook 没有秘密 | 中 | Webhook 缺乏有效载荷验证 |
| Webhook 配置审计 | 信息 | 审查所有 Webhook 配置 |
### 仓库设置（14 项检查）
| 检查 | 严重程度 | 描述 |
|-------|----------|-------------|
| 公共仓库的 Wiki | 信息 | Wiki 已启用且公开可访问 |
| 问题已禁用 | 低 | GitHub 问题已禁用 |
| 旧分支名称 | 信息 | 使用“master”而不是“main” |
| README 文件 | 低 | 仓库文档 |
| LICENSE 文件 | 低 | 项目许可条款 |
| CODEOWNERS 文件 | 中 | 自动审查分配 |
| GitHub Actions 权限 | 中 | 允许不受限制的操作 |
| .gitignore 文件 | 低 | 防止意外提交敏感文件 |
| GITHUB_TOKEN 权限 | 高 | 默认令牌具有写入权限 |
| Actions 可以批准 PR | 中 | 工作流可以批准拉取请求 |
| 私有仓库分叉 | 中 | 允许私有仓库分叉 |
| 合并策略 | 信息 | 允许所有合并类型 |
| 自动删除分支 | 低 | 合并的分支未自动删除 |
| 未受保护的环境 | 中 | 部署环境没有保护规则 |
## 安装
```bash
# 克隆仓库
git clone https://github.com/vdanniel/github-security-checker.git
cd github-security-checker
# 安装依赖项
npm install
# 构建所有软件包
npm run build
```
## 使用
### CLI
```bash
# 设置 GitHub 令牌
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
# 交互式扫描（选择仓库）
npx @ghsec/cli scan
# 扫描特定仓库
npx @ghsec/cli scan -r owner/repo1 owner/repo2
# 扫描组织中的所有仓库
npx @ghsec/cli scan -o my-organization
# 生成 SOC 2 报告
npx @ghsec/cli report -r owner/repo1 owner/repo2 --output soc2-report.md
# 输出为 JSON
npx @ghsec/cli scan -r owner/repo --json --output results.json
```
### MCP 服务器（用于 Kiro/AI 助手）
将以下内容添加到您的 `.kiro/settings/mcp.json` 中：
```json
{
"mcpServers": {
"github-security": {
"command": "node",
"args": ["path/to/github-security-checker/packages/mcp/dist/index.js"],
"env": {
"GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
}
}
}
}
```
可用 MCP 工具：
- `list_repos` - 列出可用仓库
- `scan_repo` - 扫描单个仓库
- `scan_multiple_repos` - 扫描多个仓库
- `generate_soc2_report` - 生成 SOC 2 合规报告
- `get_recommendations` - 获取详细的修复说明
### Web 仪表盘
```bash
# 启动开发服务器
cd packages/web
npm run dev
# 打开 http://localhost:3000
```
功能：
- 输入 GitHub 令牌和仓库列表
- 带有严重性指标的视觉扫描结果
- 可扩展的发现结果和建议
- 摘要统计和分数
## SOC 2 控制映射
| 控制 | 描述 | 检查 |
|---------|-------------|--------|
| CC6.1 | 逻辑访问控制 | 分支保护、管理员访问、部署密钥、GITHUB_TOKEN 权限 |
| CC6.2 | 用户访问管理 | 协作者权限、外部协作者 |
| CC6.7 | 数据传输保护 | Webhook HTTPS、机密扫描、推送保护 |
| CC7.1 | 漏洞管理 | Dependabot、代码扫描、依赖项警报 |
| CC7.4 | 安全事件响应 | 安全策略、漏洞报告 |
| CC8.1 | 变更管理 | 拉取请求审查、状态检查、代码所有者、签名提交 |
## 安全分数
每个仓库根据发现结果获得 0-100 的分数：
| 严重程度 | 分数扣除 |
|----------|-----------------|
| 关键 | -25 分 |
| 高 | -15 分 |
| 中 | -8 分 |
| 低 | -3 分 |
| 信息 | 0 分 |
**分数解释：**
- 90-100：优秀的安全态势
- 70-89：良好，需要进行小改进
- 50-69：一般，需要解决几个问题
- 低于 50：较差，需要立即关注
## GitHub 令牌权限
您的个人访问令牌所需的范围：
**经典令牌：**
- `repo` - 私有仓库的完全控制权
- `read:org` - 读取组织成员资格（用于组织扫描）
- `security_events` - 读取安全事件
**细粒度令牌：**
- 仓库访问：所有仓库（或选择特定仓库）
- 权限：
- Actions: 读取
- Administration: 读取
- Contents: 读取
- Dependabot alerts: 读取
- Environments: 读取
- Metadata: 读取
- Secret scanning alerts: 读取
- Security events: 读取
- Webhooks: 读取
## 项目结构
```
github-security-checker/
├── .github/
│ └── workflows/
│ ├── vscode-extension.yml # 构建并发布 VS Code 扩展
│ └── packages.yml # 构建、检查和测试核心软件包
├── packages/
│ ├── core/ # 核心扫描逻辑和类型
│ ├── cli/ # 命令行界面
│ ├── mcp/ # 用于 AI 助手的 MCP 服务器
│ ├── vscode/ # VS Code 扩展
│ └── web/ # Next.js Web 仪表盘
├── package.json # 工作区配置
└── README.md
```
## VS Code 扩展
从 [VS Code 市场](https://marketplace.visualstudio.com/items?itemName=DanielSurendran.github-security-checker) 或 [Open VSX](https://open-vsx.org/) 安装。
命令：
- `GitHub Security: Connect to GitHub` - 与 GitHub 认证
- `GitHub Security: Scan Repositories` - 运行安全扫描
- `GitHub Security: Show Results` - 查看扫描结果
- `GitHub Security: Generate SOC 2 Report` - 生成合规报告
- `GitHub Security: Fix Finding` - 应用推荐的修复
## CI/CD
该项目使用 GitHub Actions 进行持续集成：
- **vscode-extension.yml** - 构建并发布 VS Code 扩展到 VS Code 市场和 Open VSX
- **packages.yml** - 构建、检查和测试核心软件包
### 所需机密
| 机密 | 描述 |
|--------|-------------|
| `VSCE_PAT` | VS Code 市场的个人访问令牌 |
| `OVSX_PAT` | Open VSX 注册表的个人访问令牌 |
## 开发
```bash
# 构建核心软件包
npm run build -w @ghsec/core
# 在开发环境中运行 Web 应用程序
npm run dev -w @ghsec/web
# 在开发环境中运行 MCP 服务器
npm run dev -w @ghsec/mcp
```
## 路线图
- [ ] 常见问题的自动修复功能
- [ ] GitHub 应用程序集成（无需个人访问令牌）
- [ ] 组织范围的扫描仪表盘
- [ ] 带有通知的定时扫描
- [ ] 自定义规则定义
- [ ] GitHub 规则集支持（新的分支保护）
- [ ] 导出到 CSV/PDF 格式
## 贡献
欢迎贡献！请阅读我们的贡献指南并提交拉取请求。
## 许可证
MIT
