github-security-mcp

GitHub security posture analysis for AI agents.

GitHub Enterprise security features cost $21/user/month.
This gives your AI agent the same visibility for free — org, repos, Actions, secrets, supply chain.

The Problem • How It's Different • Quick Start • What The AI Can Do • Tools • Checks • Architecture

The Problem

GitHub security is fragmented. You need separate tools for org settings, repo configurations, Actions workflow analysis, secret scanning, supply chain, and access control. No single tool covers it all, and none work with AI agents.

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 gives your AI agent 39 tools and 45 security checks via the Model Context Protocol. The agent calls GitHub APIs directly, understands what it finds, and tells you exactly what to fix.

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"

How It's Different

Existing tools focus on one slice of GitHub security. github-security-mcp covers the full stack and works with any AI agent.

Quick Start

Install

git clone https://github.com/badchars/github-security-mcp.git
cd github-security-mcp
bun install

Set up authentication

# Classic PAT (requires: repo, admin:org, admin:org_hook, admin:repo_hook)
export GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Fine-grained PAT (preferred — least privilege)
# Organization: Members (read), Administration (read)
# Repository: Administration, Code scanning, Dependabot, Secret scanning,
#             Actions, Environments, Webhooks (all read-only)

Connect to your AI agent

claude mcp add github-security -- bun run /path/to/github-security-mcp/src/index.ts

{
  "mcpServers": {
    "github-security": {
      "command": "bun",
      "args": ["run", "/path/to/github-security-mcp/src/index.ts"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Start auditing

You: "Audit my GitHub org for security misconfigurations"

That's it. The agent handles the rest.

What The AI Can Do

Full Organization Audit

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 Workflow Security

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."

Access Control Review

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 Exposure Detection

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."

Tools Reference (39 tools)

Check Registry (45 checks)

Architecture

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

Design decisions:

• Single Octokit instance — GitHub API is global (no regions). Lazy initialization on first API call.
• Uniform CheckResult — Every check returns the same structure: checkId, severity, status, details, remediation. Same pattern as cloud-audit-mcp.
• Static workflow analysis — Actions checks fetch YAML via Contents API and use regex analysis. GitHub has no parsed workflow API.
• Enterprise graceful degradation — Enterprise-only features (audit log, credential authorizations, SSO) return NOT_APPLICABLE instead of errors.
• In-memory findings — Session-scoped findings array. No database, no persistence. Run github_audit_summary or github_audit_report to aggregate.
• 4 dependencies — @modelcontextprotocol/sdk, @octokit/rest, @octokit/graphql, zod. Nothing else.

Authentication

The token is read from the GITHUB_TOKEN environment variable.

Part of the MCP Security Suite

Limitations

• Requires a GitHub PAT or GitHub App token with appropriate scopes
• Some checks require GitHub Enterprise Cloud (audit log, credential authorizations, SSO) — these gracefully return NOT_APPLICABLE on free/Team plans
• Actions workflow analysis is regex-based (no AST parsing) — may miss complex injection patterns
• Rate limiting: GitHub API allows 5,000 requests/hour for authenticated users. A full org audit with many repos may approach this limit
• macOS / Linux (Windows not tested)

For authorized security testing and assessment only.
Always ensure you have proper authorization before auditing any organization.

MIT License • Built with Bun + TypeScript