repoward

repoward

A GitHub MCP server that stops AI agents acting on what an attacker's issue told them to do.

Status: alpha. It has not had an independent security review. Read

the threat model, especially the part about where it runs.

The problem

An agent with GitHub access can read a malicious public issue, read a private repository, and post the contents in a public pull request. Each call looks allowed on its own, so per-tool permissions do not stop the sequence. This is the attack Invariant Labs published against agents using GitHub's MCP server, and repoward's test suite replays it against real repositories.

Flow guard

Before every write, repoward checks what this agent has already read, using facts from GitHub:

This does not depend on the model noticing an attack or on scanning text, so rewording or encoding the data does not get around it. The state survives restarts, and no tool can clear it. A person can:

uvx repoward flow status

uvx repoward flow reset

What it does not do:

• It only sees this server's tools. A shell, a browser or another MCP server is still a way out, so it protects agents whose GitHub access and outbound routes are limited to this server.
• Data can stay in an agent's context after the window (60 minutes by default) ends. Restart a long-running agent to clear its context.
• Reading one private repository and writing to another private repository is allowed, unless you set single_repo: true.
• Repository files and code search results do not count as untrusted input, because they were merged by someone with write access.
• author_association is a coarse signal, and a compromised trusted account counts as trusted.
• Maintainers of public repositories will see more approval requests. That is the cost of the default, and trusted_associations is configurable.

Features

• Policy: default-deny YAML with roles, repository allowlists and path denylists. See policy.example.yaml.
• Single guarded path: every tool attempt, including unknown tools and invalid arguments, passes through one pipeline and is logged.
• Audit log: a hash-chained record of every decision, with optional HMAC and checkpoints.
• Rate limits: per principal and per tool.
• Read tools: github_list_issues, github_get_issue, github_search_code, github_get_file, ci_get_status and ci_get_job_logs.
• Write tools: github_create_branch, github_commit_files, github_create_pull_request and github_comment. Writes only reach branches with the configured prefix (agent/ by default), pull requests are draft only by default, commit sizes are limited, nothing is forced or retried, and text holding a recognizable credential is refused.
• Dangerous tools: github_merge_pull_request and github_delete_branch need human approval. An approval covers one exact call at one exact commit, works once and expires. Merging is off until a policy turns it on.
• GitHub App tokens (optional): each call gets a short-lived token limited to one repository and only the permissions that tool needs, and GitHub enforces those limits itself.
• Pull request review as approval (optional): a merge can be approved by a real GitHub review of the exact commit.
• Pull request receipts (optional): a commit status summarizing how the agent's run has gone.
• HTTP mode (optional): serve several users from one server, each logging in with a JWT from your identity provider.
• Policy replay: see which past decisions a policy edit would change before you deploy it.
• Untrusted content handling: text from GitHub users comes back wrapped in a tag with a random id per response, after invisible characters, hidden HTML comments and images are removed and secrets are redacted. This is a mitigation, not a guarantee: a model can still be fooled, which is why the rules above are enforced outside the model.

How it works

Every tool call takes the same path, including calls to unknown tools and calls with invalid arguments, so each attempt is logged. Tool code is only ever run from this one place.

MCP client

| stdio, or HTTP with a JWT checked on every request v repoward

1. Find the tool and validate its arguments fail: refused and logged
2. Check the policy default deny
3. Check the flow guard for writes
4. Check the rate limit
5. Check for human approval if policy or the flow guard asks for it
6. Log the decision if this fails, a write does not happen
7. Run the tool
8. Clean, redact, limit and label the output
9. Log the outcome | v

GitHub API

Who it is for

Agents whose only route to GitHub is this server, such as CI bots and hosted agents. What repoward can enforce depends on where it runs relative to the agent:

With a shell on the same OS user, repoward only helps an agent that is misled and not trying to get around it. Running repoward as its own user sets up the separated case on Linux, and is tested automatically. GitHub-side controls, such as a ruleset protecting your default branch, are the backstop in every case.

By default it runs over stdio as one identity. To serve several people from one server, see Serving over HTTP.

Install

Requires uv. Create a starter policy, which also prints a client config to paste:

uvx repoward init --repo your-org/your-repo

The starter policy gives the server read-only tools. Add --role contributor for write tools. Files live in ~/.repoward, or wherever REPOWARD_HOME points. An existing policy is never overwritten.

Run this first, because the server will not start without a policy. Then add it to your MCP client, and use a token set up as described in GitHub token. Avoid committing a config that holds a real token.

Claude Code

claude mcp add --env GITHUB_TOKEN=<your-token> --transport stdio repoward -- uvx repoward serve

Claude Desktop

In claude_desktop_config.json, under Settings > Developer > Edit Config:

{

"mcpServers": { "repoward": { "command": "uvx", "args": ["repoward", "serve"], "env": { "GITHUB_TOKEN": " " } } } }

Cursor

In ~/.cursor/mcp.json, reading the token from your environment:

{

"mcpServers": { "repoward": { "command": "uvx", "args": ["repoward", "serve"], "env": { "GITHUB_TOKEN": "${env:GITHUB_TOKEN}" } } } }

VS Code

In .vscode/mcp.json or your user profile's mcp.json, which prompts for the token once:

{

"inputs": [ { "type": "promptString", "id": "github-token", "description": "GitHub token", "password": true } ], "servers": { "repoward": { "type": "stdio", "command": "uvx", "args": ["repoward", "serve"], "env": { "GITHUB_TOKEN": "${input:github-token}" } } } }

Codex

In ~/.codex/config.toml, forwarding the token from your environment:

[mcp_servers.repoward]

command = "uvx" args = ["repoward", "serve"] env_vars = ["GITHUB_TOKEN"]

Gemini CLI

In ~/.gemini/settings.json, reading the token from your environment:

{

"mcpServers": { "repoward": { "command": "uvx", "args": ["repoward", "serve"], "env": { "GITHUB_TOKEN": "$GITHUB_TOKEN" } } } }

OpenCode

In opencode.json in your project, or ~/.config/opencode/opencode.json, reading the token from your environment:

{

"mcp": { "repoward": { "type": "local", "command": ["uvx", "repoward", "serve"], "environment": { "GITHUB_TOKEN": "{env:GITHUB_TOKEN}" } } } }

Any other client that can launch a stdio MCP server runs the same command: uvx repoward serve.

If your client reports that the server failed to connect, run uvx repoward serve in a terminal to see why. The usual cause is that repoward init has not been run yet, so there is no policy.

Useful commands:

uvx repoward validate-policy

uvx repoward audit verify

Approving risky actions

A call that needs approval does not run. It returns an approval_id, and a person decides from a terminal:

uvx repoward approvals list

uvx repoward approvals show uvx repoward approvals approve

The agent then repeats the same call. Pushing new commits changes the commit the call names, so the old approval no longer applies, and GitHub refuses a merge whose head has moved.

Approving with a pull request review

A merge can also be approved by a normal GitHub review, so the approver needs their own GitHub identity and not just access to this machine. Turn it on in your policy:

approvals:

github_review: { enabled: true, min_permission: write }

A review counts only if it approves the exact commit being merged, comes from a user other than the pull request's author and this server's own identity, and that user has the required access. Any reviewer's outstanding request for changes blocks it. Each check is made again at merge time.

This needs the server to act as a GitHub App or a separate bot account. With your own token, your own reviews are refused. If an agent can reach the reviewer's GitHub credentials, such as a logged-in gh on the same machine, this protection is lost.

Limits of approvals

If the agent runs as the same OS user as this server and has a shell, it could run these commands or edit the database itself. Run the server and its files under a separate user or in a container for approvals to mean anything.

GitHub token

Use a fine-grained personal access token limited to the repositories you allow, with short expiry. Choose Only select repositories so that repository permissions appear. The read tools need these, all read-only:

To use the write tools, also give it read and write acce