This document describes the security architecture of mcp-github-crunchtools.
| Asset | Sensitivity | Impact if Compromised |
|---|---|---|
| GitHub Personal Access Token | Critical | Full account access, code access, CI/CD manipulation |
| Repository Source Code | High | Intellectual property theft, supply chain attacks |
| Default Branch and Releases | High | A merge or a published release ships code to users |
| Pull Requests / Issues | Medium | Information disclosure, workflow manipulation |
| CI Check Results and Job Logs | Medium | Infrastructure details; a log can echo a secret a job printed |
| Actor | Capability | Motivation |
|---|---|---|
| Malicious AI Agent | Can craft tool inputs | Data exfiltration, privilege escalation |
| Local Attacker | Access to filesystem | Token theft, configuration tampering |
| Network Attacker | Man-in-the-middle | Token interception (mitigated by TLS) |
| Vector | Description | Mitigation |
|---|---|---|
| Token Leakage | Token exposed in logs, errors, or outputs | Never log tokens; scrub the env and request tokens from errors |
| Token Mix-up | One HTTP caller's token used for another's request | Per-call header and a request-scoped context variable; nothing on the shared client (2.2) |
| Check Bypass | A token allowed to bypass rulesets merges a PR with failing checks | The merge tool enforces required checks itself (2.7) |
| Input Injection | Malicious owner/repo or path | Strict input validation |
| Path Traversal | Manipulated file paths | Allowlist validation, reject .. |
| SSRF | Redirect API calls to internal services | HTTPS enforcement, URL validation |
| Token Forwarding | A redirect carries the token to another host | The API client follows no redirects; the job-log redirect is fetched by a client with no token (2.6) |
| Untrusted Text | Comments, reviews and job logs are written by other people and by the code under test | Returned as data with bounded size; the caller (or a gateway in front of it) must not treat them as instructions |
| Unintended Merge | The PR head moves between the check and the merge | merge_pull_request_tool always pins the merge to the head it checked; GitHub refuses (409) if it moved |
| Denial of Service | Exhaust GitHub rate limits | Rate-limit awareness |
| Privilege Escalation | Access beyond token scope | Server relies on token scope |
| Supply Chain | Compromised dependencies | Automated CVE scanning |
┌─────────────────────────────────────────────────────────────┐
│ Layer 1: Input Validation │
│ - Allowlist for owner/repo characters │
│ - Positive-integer validation for issue/PR numbers │
│ - Path traversal rejection for file reads │
├─────────────────────────────────────────────────────────────┤
│ Layer 2: Token Handling │
│ - Environment variable only (never file, never arg) │
│ - Never log, never include in errors │
│ - Use Authorization: Bearer header (not in URL) │
├─────────────────────────────────────────────────────────────┤
│ Layer 3: API Client Hardening │
│ - Configurable base URL with HTTPS enforcement (GHES) │
│ - Pinned X-GitHub-Api-Version │
│ - TLS certificate validation (default in httpx) │
│ - Request timeout enforcement (30s) │
│ - Response size limits (10MB) │
├─────────────────────────────────────────────────────────────┤
│ Layer 4: Output Sanitization │
│ - Redact tokens from any error messages │
│ - Limit response sizes to prevent memory exhaustion │
│ - Structured errors without internal details │
├─────────────────────────────────────────────────────────────┤
│ Layer 5: Runtime Protection │
│ - No filesystem writes │
│ - No shell execution (subprocess) │
│ - No dynamic code evaluation (eval/exec) │
├─────────────────────────────────────────────────────────────┤
│ Layer 6: Supply Chain Security │
│ - Automated CVE scanning via GitHub Actions │
│ - Dependabot alerts enabled │
│ - Container built on Hummingbird for minimal CVEs │
└─────────────────────────────────────────────────────────────┘
GITHUB_TOKEN is read from the environment only and held as a pydantic
SecretStr; Config.__repr__() and __str__() print token=***. It is
required unless GITHUB_ACCEPT_REQUEST_TOKEN is on.
With GITHUB_ACCEPT_REQUEST_TOKEN set to true, 1 or yes, the server
takes the caller's token from each HTTP request's Authorization header, as
GitHub's own hosted MCP server does. Off (the default), the header is
ignored and nothing changes.
- The token is chosen per API call. An incoming
Authorization: Bearer <token>is sent as that call's own header, overriding the shared client's default; without one,GITHUB_TOKENis used; with neither, the call fails before any request is made. The shared httpx client carries anAuthorizationdefault only whenGITHUB_TOKENis set, and never a request's token, so concurrent requests with different tokens each send their own. A test runs five requests in flight at once to show it. - The header must match
Bearer <token>exactly: the scheme in any case, a single space, then 1 to 1024 printable non-space ASCII characters. Anything else (another scheme, spaces, control characters, an empty value) is refused with an error that does not echo it, and is never forwarded. A malformed header does not fall back toGITHUB_TOKEN. - FastMCP strips
Authorizationfrom the headers it exposes; the client asks for it explicitly, and only when the option is on. stdio has no request headers and always usesGITHUB_TOKEN. - The request token is kept in a context variable for the duration of the request so that error messages scrub it (2.5).
Turning the option on makes the server act as whoever presents a token. That grants no access the caller did not already have, but the HTTP port should still be reachable only by intended callers, over TLS, since the token crosses it.
The API base URL is validated to prevent SSRF:
- Must be a valid URL with scheme and netloc
- Must use HTTPS unless connecting to localhost
- Trailing slashes are stripped
- Defaults to
https://api.github.com; override withGITHUB_API_URLfor GHES
All inputs are validated:
- Owner / repo names: letters, digits, dots, hyphens, underscores only
- Issue / PR / page numbers: must be positive integers
- File paths: rejected if they contain
.. - States: allowlist of "open", "closed", "all"
- Merge methods: allowlist of "merge", "squash", "rebase"
- Git refs (PR base, release tag and target): git check-ref-format rules;
a PR head may also be
owner:branchfor a fork - Expected head SHA: a full 40 or 64 character hex commit SHA
- Comment bodies: 1-65536 characters, extra fields rejected (extra="forbid")
- Titles and bodies (issues, PRs, releases): at most 256 and 65536 characters
Errors are sanitized before being returned:
def scrub_tokens(message: str) -> str:
for token in (os.environ.get("GITHUB_TOKEN", ""), request_token.get()):
if token:
message = message.replace(token, "***")
return messageGitHubApiError passes every message through scrub_tokens, which removes
both GITHUB_TOKEN and the token of the current request.
GitHub signals primary rate limiting with HTTP 403 plus
x-ratelimit-remaining: 0; the client maps this (and HTTP 429) to a
RateLimitError that surfaces the retry window.
get_failed_job_logs_tool is the only tool whose data comes from a host other
than the API. GitHub answers GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs
with a 302 to a short-lived, pre-signed URL on a storage host.
- The API client is built with
follow_redirects=False, so the client that holds the token never follows a redirect on its own. - The redirect target is fetched by a separate client created with no default
headers. No
Authorizationheader reaches the storage host; a test asserts this on the request as sent. - The target must be
https, name a host rather than an IP address (in any spelling, including2130706433and0x7f.0.0.1), and carry no embedded credentials. It is not redirected further, and anything but a 200 is an error. - The target host is not checked against a list of names. GitHub documents no
stable set of log-storage hosts and a GitHub Enterprise Server uses its
operator's storage, so a list would break the tool. The
Locationcomes from the configured API over verified TLS and no tool argument reaches it; whoever could forge it already receives the token on every API request. - The signed URL is never logged and never placed in an error message, and a storage error body is not echoed.
- The download is streamed. Only the last 256 KiB are held in memory and the download is abandoned past 20 MB.
Log text is then reduced before it is returned: ANSI escapes and per-line
timestamps are removed, each job is cut to its last tail_lines lines (at
most 1000), logs are returned for at most 5 failed jobs, and all log text in
one result stays within 256 KiB. The result says when any of these cut
something.
merge_pull_request_tool enforces the base branch's required status checks
itself. GitHub lets an organization owner, or an actor on a ruleset's bypass
list, merge past failing required checks, so a token with that standing
would otherwise merge a red pull request.
- The PR's head SHA and base are read first; a caller's
shathat is not the head is refused. - Required checks come from the branch's active rulesets
(
GET /repos/{owner}/{repo}/rules/branches/{branch}) and its classic protection, as shown on the branch (GET .../branches/{branch}), which needs no Administration permission. An error reading either, or a protected branch whose protection is not shown, refuses the merge: the gate cannot tell that from there being no checks. - No required checks at all refuses the merge unless the caller passes
allow_no_required_checks=True. - Each required check needs, on the head commit, a completed check run of
that name concluding
success,skippedorneutral(the most recent run of the name, by id, decides) or a commit status ofsuccess. A rule that names an app (integration_id, orapp_idin classic protection) is satisfied only by that app's check runs, never by a commit status, which anyone with Commit statuses: write could post. - Every list is read in full, up to 10 pages of 100; a longer list refuses the merge rather than be judged in part.
- Just before merging the PR is read again, and a changed head or base
refuses the merge: the merge call pins the head but not the base, so a
retarget during the gate would otherwise land on a branch whose checks
were not judged. The merge request pins
shato the checked head, so a push after that re-read makes GitHub answer 409. A retarget in the milliseconds between the re-read and the merge call remains possible; GitHub offers no way to pin the base. - Other branch rules, such as required reviews, are not re-enforced; a token that may bypass them still does.
Permissions below are the repository permissions of a fine-grained personal access token. Metadata: read comes with any of them.
Grant read on Contents, Issues, Pull requests and Actions
(plus Commit statuses for get_pull_request_checks_tool),
or repo:status + public_repo for classic tokens limited to public
repositories.
Capabilities: list/read issues, PRs, diffs, checks, PR comments and reviews, workflow runs, failed-job logs, files; search Risk: Information disclosure only. Job logs can contain whatever a job printed.
Add write on Issues and Pull requests.
Capabilities: the above plus opening and updating issues and pull requests, commenting, and replying to review comments Risk: Can open, close and comment if the token is compromised. Cannot change code.
Add write on Contents, and on Actions if runs are to be triggered or re-run.
Capabilities: the above plus merge_pull_request_tool,
create_release_tool, trigger_workflow_tool and the rerun_* tools
Risk: Contents: write is also the permission to push commits and tags;
GitHub offers nothing narrower for merging. A compromised token can change the
default branch wherever branch rules allow it, and a published release fires
the repository's on: release workflows. Protect the default branch with
required checks: merge_pull_request_tool refuses to merge unless they are
green (2.7), and without any it refuses unless told otherwise.
A release whose target commit changes a file under .github/workflows/,
relative to the default branch, additionally needs Workflows: write;
without it GitHub answers 404. Expect the same of a merge that brings workflow
changes in.
| Tool | Fine-grained permission |
|---|---|
list_issues_tool, get_issue_tool |
Issues: read |
create_issue_tool, update_issue_tool |
Issues: write |
create_issue_comment_tool |
Issues: write, or Pull requests: write on a PR |
list_pull_requests_tool, get_pull_request_tool, get_pull_request_diff_tool, list_pull_request_comments_tool |
Pull requests: read |
get_pull_request_checks_tool |
Pull requests: read, Commit statuses: read (see below) |
create_pull_request_tool, update_pull_request_tool, reply_to_review_comment_tool |
Pull requests: write |
merge_pull_request_tool |
Contents: write; Pull requests and Commit statuses: read (see 2.7) |
create_release_tool |
Contents: write |
list_workflow_runs_tool, get_workflow_run_tool, get_failed_job_logs_tool |
Actions: read |
trigger_workflow_tool, rerun_workflow_run_tool, rerun_failed_jobs_tool |
Actions: write |
get_file_content_tool, list_repo_tree_tool |
Contents: read |
search_code_tool, search_issues_tool |
None of their own (see below) |
get_pull_request_checks_tool and merge_pull_request_tool read check-runs, and GitHub's permission table
for fine-grained tokens lists no permission for that endpoint. It is readable
on public repositories; on a private repository use a classic token or a
GitHub App token. The search tools likewise have no permission of their own:
they return what the token can already read.
For minimum privilege, grant only:
- Read on Contents, Issues, Pull requests and Actions — if you only need to read
- Add write on Issues and Pull requests — to comment, open and update
- Add write on Contents — only where the agent is meant to merge or release (merging needs no Administration permission: the gate reads branch protection from the branch itself)
This project uses GitHub Actions to automatically scan for CVEs:
- Scheduled Scans: dependency audits on a regular cadence
- PR Checks: every pull request is scanned before merge
- Dependabot: enabled for automatic security updates
The container image is built on Hummingbird Python from Project Hummingbird:
| Advantage | Description |
|---|---|
| Minimal CVE Count | Dramatically reduced attack surface |
| Rapid Security Updates | Security patches applied promptly |
| Python Optimized | Pre-configured Python environment |
| Non-Root Default | Runs as non-root user |
| Production Ready | Proper signal handling, minimal footprint |
| Event | Level | Fields |
|---|---|---|
| Server startup | INFO | version, GitHub API URL |
| GitHub API call | DEBUG | method, path (no auth headers) |
| Permission denied | WARN | required_scope |
| Rate limited | WARN | retry_after |
| Error | ERROR | error_type (no internals) |
- API tokens (any form)
- Full request/response bodies
- Issue/PR descriptions (may contain secrets)
- File content
- Job logs and the signed URLs they are downloaded from
Before each release:
- All inputs validated
- No token exposure in logs or errors
- No filesystem writes
- No shell execution
- No eval/exec
- Rate limiting considered
- Error messages don't leak internals
- Dependencies scanned for CVEs
- Container rebuilt with latest Hummingbird base
Report security vulnerabilities using GitHub's private security advisory. This creates a private channel visible only to maintainers.
Do NOT open public issues for security vulnerabilities.