面向 AI 代理的 GitHub 安全态势分析工具，通过 MCP 协议提供 39 个工具和 45 项检查，覆盖组织、仓库、Actions、secrets、供应链和访问控制六大领域的安全审计。
面向 AI 代理的 GitHub 安全态势分析。
GitHub Enterprise 安全功能的费用为 $21/用户/月。免费的同等可见性 —— 包括组织、仓库、Actions、secrets、供应链。
问题背景 •
独特之处 •
快速开始 •
AI 能力 •
工具 •
检查项 •
架构
## 问题背景
GitHub 安全功能是碎片化的。针对组织设置、仓库配置、Actions 工作流分析、secret 扫描、供应链和访问控制，您需要使用各自独立的工具。没有单一工具能涵盖所有内容，而且没有一种工具能与 AI 代理协同工作。
```
Traditional workflow:
manually check org settings → click through 15 pages
run github-advisory-db for each repo → one at a time
grep workflows for script injection → miss half the patterns
review collaborator access → spreadsheet hell
check secret scanning alerts → another dashboard
──────────────────────────────────────────
Total: hours of manual work per org
```
**github-security-mcp** 通过 [Model Context Protocol](https://modelcontextprotocol.io) 为您的 AI 代理提供 39 个工具和 45 项安全检查。代理直接调用 GitHub API，理解其发现的内容，并准确告诉您需要修复什么。
```
With github-security-mcp:
You: "Audit my GitHub org for security issues and prioritize the fixes"
Agent: → checks org settings (2FA, SSO, member privileges)
→ scans repos (branch protection, secret scanning, Dependabot)
→ analyzes workflows (script injection, unpinned actions, OIDC)
→ reviews access (teams, collaborators, PATs, GitHub Apps)
→ "12 critical, 8 high — here are the top 5 to fix now"
```
## 独特之处
现有工具仅关注 GitHub 安全的某一个切片。github-security-mcp 覆盖完整的技术栈，并可与任何 AI 代理配合使用。
现有工具
github-security-mcp
接口 CLI / GitHub UI / 仪表盘
MCP — AI 代理实时调用工具
范围 单一领域 (Actions, 或 secrets, 或仓库)
全栈: 组织 + 仓库 + Actions + secrets + 供应链 + 访问控制
关联分析 无 — 孤立的发现结果
代理链式推理: "此未固定的 action + 写入权限 + 无环境保护 = 供应链风险"
修复建议 通用文档链接
代理针对您的具体配置生成特定的修复指南
Actions 分析 大多数工具跳过工作流
8 项检查: 脚本注入、PR target、OIDC、版本固定、secrets、runners、环境、权限
Enterprise 功能 需要 GitHub Enterprise ($21/用户/月)
免费 — 使用公开 API，并对 Enterprise 专属功能进行优雅降级
与热门工具的具体对比
## 快速开始
### 安装
```
git clone https://github.com/badchars/github-security-mcp.git
cd github-security-mcp
bun install
```
### 设置认证
```
# Classic PAT (需要: repo, admin:org, admin:org_hook, admin:repo_hook)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
# Fine-grained PAT (首选 — 最小权限)
# Organization: Members (读取), Administration (读取)
# Repository: Administration, Code scanning, Dependabot, Secret scanning,
# Actions, Environments, Webhooks (均为只读)
```
### 连接到您的 AI 代理
Claude Code
Claude Desktop
Cursor / Windsurf / 其他 MCP 客户端
### 开始审计
```
You: "Audit my GitHub org for security misconfigurations"
```
就是这样。代理会处理剩下的工作。
## AI 能力展示
### 完整组织审计
```
You: "Run a complete security audit on our GitHub org"
Agent: → github_run_all {org: "myorg", repo: "main-app"}
→ 45 checks across 6 categories
→ github_audit_report
→ "34 findings: 4 critical, 7 high, 12 medium.
Critical #1: No branch protection on main (REPO-001)
Critical #2: Script injection in deploy.yml (ACT-001)
Critical #3: 3 critical Dependabot alerts unfixed 90+ days (REPO-007)
Critical #4: Unresolved secret scanning alerts (SEC-002)
Here are the exact fixes for each..."
```
### Actions 工作流安全
```
You: "Check our CI/CD workflows for supply chain risks"
Agent: → github_check_workflow_injection
Found ${{ github.event.issue.title }} in run: block (deploy.yml:47)
→ github_check_workflow_pinning
12 actions use tags instead of SHA pins
→ github_check_workflow_pr_target
build.yml uses pull_request_target with checkout — critical risk
→ github_check_workflow_permissions
Default GITHUB_TOKEN has write-all permissions
→ "4 supply chain risks found. The PR target + checkout pattern
allows any fork to execute arbitrary code with write access
to your repo. Fix this first."
```
### 访问控制审查
```
You: "Who has too much access to our repositories?"
Agent: → github_check_team_permissions
"platform" team has admin on 47 repos, only 3 members
→ github_check_collaborators
8 outside collaborators with write access
→ github_check_app_permissions
"old-ci-bot" GitHub App has admin + all repos
→ github_check_pat_usage
14 classic PATs with repo scope (should be fine-grained)
→ "Reduce blast radius: restrict platform team to maintain,
remove 3 stale outside collaborators, limit old-ci-bot
to specific repos, migrate classic PATs to fine-grained."
```
### Secret 泄露检测
```
You: "Are we properly protecting secrets across our repos?"
Agent: → github_check_secret_scanning
Secret scanning disabled on 5 private repos
→ github_check_push_protection
3 push protection bypasses in the last month
→ github_check_secret_patterns
No custom secret patterns defined
→ github_check_secret_scoping
2 org secrets available to all repos (should be scoped)
→ "Enable secret scanning on all repos, review the 3 bypasses,
add custom patterns for internal API keys, and scope
org secrets to only the repos that need them."
```
## 工具参考 (39 个工具)
组织 (7)
仓库 (8)
Actions (8)
Secrets (4)
供应链 (4)
访问控制 (4)
元数据 (4)
## 检查注册表 (45 项检查)
组织 (ORG-001 至 ORG-010)
仓库 (REPO-001 至 REPO-013)
Actions (ACT-001 至 ACT-008)
Secrets (SEC-001 至 SEC-005)
供应链 (SUP-001 至 SUP-005)
访问控制 (ACC-001 至 ACC-004)
## 架构
```
src/
├── index.ts Entry point + MCP stdio
├── types/
│ └── index.ts CheckResult, ToolDef, ToolContext, ToolResult
├── github/
│ └── client.ts GitHubClientFactory (lazy Octokit + GraphQL)
├── protocol/
│ ├── tools.ts 39 tool definitions (Zod schemas)
│ └── mcp-server.ts MCP server + stdio transport
├── org/ Organization checks (ORG-001..010)
│ ├── security.ts 2FA, visibility, member privileges
│ ├── sso.ts SSO/SAML via GraphQL
│ ├── members.ts Outside collaborators, stale members
│ ├── apps.ts OAuth apps, GitHub App installations
│ ├── webhooks.ts Insecure webhook URLs
│ └── audit-log.ts Suspicious audit log patterns
├── repo/ Repository checks (REPO-001..013)
│ ├── branch-protection.ts Branch protection rules
│ ├── secret-scanning.ts Secret scanning + push protection
│ ├── code-scanning.ts CodeQL enabled, open alerts
│ ├── dependabot.ts Dependabot enabled, critical alerts
│ ├── settings.ts SECURITY.md, vuln reporting, forks
│ ├── webhooks.ts Insecure repo webhooks
│ ├── deploy-keys.ts Deploy key permissions
│ └── codeowners.ts CODEOWNERS file
├── actions/ GitHub Actions checks (ACT-001..008)
│ ├── injection.ts Script injection via untrusted inputs
│ ├── pr-target.ts pull_request_target + checkout
│ ├── permissions.ts GITHUB_TOKEN default permissions
│ ├── pinning.ts Unpinned third-party actions
│ ├── runners.ts Self-hosted runner exposure
│ ├── environments.ts Environment protection rules
│ ├── secrets.ts Secret exfiltration patterns
│ └── oidc.ts OIDC configuration
├── secrets/ Secret management checks (SEC-001..005)
│ ├── scanning.ts Coverage + alert triage
│ ├── push-protection.ts Push protection bypasses
│ ├── patterns.ts Custom secret patterns
│ └── scoping.ts Env/repo/org secret scoping
├── supply-chain/ Supply chain checks (SUP-001..005)
│ ├── dependency-graph.ts Dependency graph enabled
│ ├── dependabot-updates.ts Security updates config
│ ├── sbom.ts SBOM generation
│ └── vulnerabilities.ts Known vulns, stale unfixed
├── access/ Access control checks (ACC-001..004)
│ ├── teams.ts Team permission audit
│ ├── collaborators.ts External collaborators
│ ├── github-apps.ts GitHub App permissions
│ └── tokens.ts Classic vs fine-grained PATs
└── meta/ Aggregation + reporting
├── list-checks.ts CHECK_REGISTRY (45 checks)
├── summary.ts Findings aggregation
├── report.ts Markdown/JSON report
└── run-all.ts Execute all checks
```
**设计决策:**
- **单一 Octokit 实例** — GitHub API 是全局的 (无区域概念)。在首次 API 调用时延迟初始化。
- **统一的 CheckResult** — 每个检查返回相同的结构: checkId, severity, status, details, remediation。与 [cloud-audit-mcp](https://github.com/badchars/cloud-audit-mcp) 模式相同。
- **静态工作流分析** — Actions 检查通过 Contents API 获取 YAML 并使用正则分析。GitHub 没有解析后的工作流 API。
- **Enterprise 优雅降级** — Enterprise 专属功能 (审计日志、凭证授权、SSO) 返回 `NOT_APPLICABLE` 而非错误。
- **内存 findings** — 会话范围的 findings 数组。无数据库，无持久化。运行 `github_audit_summary` 或 `github_audit_report` 进行聚合。
- **4 个依赖项** — `@modelcontextprotocol/sdk`, `@octokit/rest`, `@octokit/graphql`, `zod`。除此之外别无其他。
## 认证
| 令牌类型 | 所需权限范围 |
|---|---|
| **Classic PAT** | `repo`, `admin:org`, `admin:org_hook`, `admin:repo_hook` |
| **Fine-grained PAT** (推荐) | 组织: 成员 + 管理 (读取)。仓库: 管理、代码扫描、Dependabot、Secret 扫描、Actions、环境、Webhook (读取) |
| **GitHub App** | 与 Fine-grained PAT 相同的仓库/组织权限 |
令牌从 `GITHUB_TOKEN` 环境变量中读取。
## MCP 安全套件的一部分
| 项目 | 领域 | 工具 |
|---|---|---|
| [hackbrowser-mcp](https://github.com/badchars/hackbrowser-mcp) | 浏览器安全测试 | 39 个工具, Firefox, 注入测试 |
| [cloud-audit-mcp](https://github.com/badchars/cloud-audit-mcp) | 云安全 (AWS/Azure/GCP) | 38 个工具, 60+ 检查 |
| **github-security-mcp** | GitHub 安全态势 | 39 个工具, 45 项检查 |
## 限制
- 需要具有适当权限范围的 GitHub PAT 或 GitHub App 令牌
- 某些检查需要 GitHub Enterprise Cloud (审计日志、凭证授权、SSO) — 这些在免费/Team 计划上会优雅地返回 NOT_APPLICABLE
- Actions 工作流分析基于正则 (无 AST 解析) — 可能会遗漏复杂的注入模式
- 速率限制: GitHub API 允许认证用户每小时 5,000 次请求。包含许多仓库的完整组织审计可能会接近此限制
- macOS / Linux (Windows 尚未测试)
仅用于授权的安全测试和评估。
MIT License • 使用 Bun + TypeScript 构建
