bugwarden MCP server
Commit Nov 12, 2026Exposes a Bugzilla instance to LLM clients with a policy-driven security guard that restricts access to specific bugs and capabilities.
Also known as plusky/bugwarden
- Stars
- 7
- Tools
- 22
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 12, 2026
- License
- Apache-2.0
What is bugwarden MCP?
bugwarden exposes a Bugzilla instance to LLM clients with a policy-driven security guard that restricts access to specific bugs and capabilities. It exposes 22 tools, such as bug_info, bug_history, bug_comments.
Summary generated from the project's README
About bugwarden MCP server
Managing Bugzilla access for AI agents is what bugwarden enables through a security-first Model Context Protocol server. It allows developers to expose Bugzilla instances to LLM clients while enforcing strict, operator-defined permissions via a TOML policy file. This policy acts as a guard, ensuring that an AI agent can only interact with specific bugs or perform certain actions, such as reading summaries or leaving comments, without the model ever seeing or modifying the underlying rules.
Operators can configure fine-grained restrictions based on product, component, severity, or bug age. The server prevents information leakage by making denied bugs indistinguishable from nonexistent ones and filtering search results silently. It supports both stdio for desktop clients and streamable HTTP for fleet deployments. Users can deploy it as a single static Rust binary, via container images, or through system packages like those for openSUSE. The system includes an audit stream for tracking every tool call and decision made by the guard.
What you can do with it
- 1Restrict AI to read-only accessAn operator can disable all write tools so the LLM can only query bug details and history without making changes.
- 2Protect sensitive new bugsYou can prevent an AI from seeing recently filed bugs that might contain un-triaged sensitive information.
- 3Enforce product-specific permissionsA developer can set a policy where the agent is only allowed to read summaries and leave comments on a specific product.
- 4Audit agent interactionsSecurity teams can review a JSONL record of every tool call and the specific rule that allowed or denied the action.
Written from the project's README. Every use case is checked against a quote from it.
bugwarden MCP tools 22
Detected from the READMEbug_infobug_historybug_commentsbugs_quicksearchsummarize_buglist_attachmentsdownload_attachmentadd_commentupdate_bug_statusassign_bugupdate_bug_fieldsupdate_bug_dependencies
Show all 22 toolsShow fewer tools
add_cc_to_bugmark_as_duplicatecreate_bugadd_attachmentbug_urlbugzilla_server_infobugzilla_productsbug_fieldsquicksearch_syntaxmcp_server_info
Configuration
BUGWARDEN_HTTP_TOKENBUGZILLA_API_KEYOTEL_EXPORTER_OTLP_ENDPOINTOTEL_EXPORTER_OTLP_HEADERS
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableplusky/bugwarden is public and reachablegithub.com/plusky/bugwarden ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/plusky/bugwarden ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model22 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubbugwarden
bugwarden is a Model Context Protocol (MCP) server, written in Rust, with operator-controlled security guards. It exposes a Bugzilla instance to LLM clients — querying bugs, searching, reading comments and history, and (where permitted) updating bugs — while a policy file that the model can neither see nor change decides, per bug, what the model is allowed to do.
The Bugzilla REST API already enforces user permissions via the API key. What it cannot do is enforce a narrower set of permissions for an AI agent acting on that user's behalf. bugwarden sits in between: the operator writes a small TOML policy ("embargoed security bugs are invisible", "on the Security product the agent may only read summaries and leave comments", "nothing younger than a week exists"), and every tool call is checked against it before Bugzilla is touched or data is returned.
Features
- Complete Bugzilla tool surface: bug details, history, comments, attachment metadata and content, quicksearch, comment/status/field/ assignee/CC/dependency updates, duplicate marking, bug filing, attachment upload, server info, quicksearch syntax docs, and a bug-summarization prompt tool.
- Guard policy engine: per-bug
allow/deny/restrictdecisions matched on product, component, group, keyword, status, severity, priority, whiteboard, summary, group-restrictedness, bug age, and authorship (whether the requesting account filed the bug) — with a fine-grained 13-capability vocabulary forrestrict. - No existence oracle: a policy-denied bug is indistinguishable from a nonexistent one.
- Silent search filtering: denied bugs simply never appear in search results; summary-only bugs appear redacted.
- Minimum-age quarantine:
min_bug_age_daysmakes recently filed bugs (the ones most likely to contain not-yet-triaged sensitive data) invisible. - Read-only mode and tool disabling remove write tools from the MCP tool listing entirely — clients never see them, rather than seeing them error.
- Audit stream: an operator-only JSONL record of every tool call — the guard's verdict, the deciding rule, the bug ids it suppressed — with fail-closed modes that hold back further work while records cannot be persisted. The stream is the operator's half of the bargain the guard makes with the client, and no MCP surface can reach it.
- Two transports: streamable HTTP (per-request API key header, or a
server-held key via
--api-key-filefor fleet deployments) and stdio (subprocess launch by a desktop MCP client). - Single static binary, async throughout (tokio + rmcp), shipping with a man page and bash/zsh/fish completions.
Security model
The guard concept
The guard policy is loaded once, at startup, from a TOML file passed via
--policy (or BUGWARDEN_POLICY). It lives on the operator's filesystem. The
MCP client — i.e. the model — has no tool to read it, list its rules, or
modify it. mcp_server_info intentionally exposes only coarse facts: the rule
count, the default action, min_bug_age_days, whether the server is
read-only, and which tool names are disabled. Rule names and match criteria
are never revealed.
Every tool that takes a bug id first fetches the bug's classification metadata
(product, groups, keywords, creation time, …) and evaluates the policy
before any side effect happens or any data is returned. The only exception
is bug_url, which computes a URL string locally and contacts nothing.
Invariants
- Uniform denial. A denied bug and a nonexistent bug produce the exact
same response:
Bug {id} is not accessible through this server. No wording or detail difference can be used as an existence oracle for embargoed bugs. - Silent search filtering. Search results are post-filtered through the policy; the client is never told how many results were dropped or that filtering happened at all. The operator is: a server-side debug log records it, and an audited deployment gets the scan's counts and the withheld ids in the audit stream.
- Fail closed. If the classification fetch fails, if a bug is absent from
the response, or if a rule consulted for the operation being decided cannot
be decided because the bug object did not carry a field that rule asks
about — or, for the identity criterion
created_by_me, because the bug–caller relationship could not be established — the bug is treated as denied — never as allowed. (A rule scoped away from the operation viaoperationsis not consulted at all — scoping changes which rules run, never how a consulted rule resolves.) - Private-comment gate. Private comments are returned only when the policy
sets
allow_private_comments = trueand the individual call opts in withinclude_private = true. Either alone is not enough. - Custom fields cannot smuggle writes.
update_bug_fields.custom_fieldsandcreate_bug.custom_fieldsaccept only keys starting withcf_; anything else (e.g.groups,cc,assigned_to) is rejected before Bugzilla is contacted. - Custom fields cannot smuggle links either. A Bugzilla "Bug ID" custom
field is a link like
depends_on. A served bug body is judged by JSON type with no lookup (stock Bugzilla renders only that custom type as a number), while a history change and a write are judged by looking the field's type up by name from Bugzilla — so a hidden bug named in such a field is scrubbed frombug_info,bugs_quicksearchandbug_history, and a write naming one must pass the samesummarycheck as any other link target. Such a field takes a numeric bug id or an empty value; a value the server cannot judge (an alias, an object) is refused, and a call may set at most 50 custom fields. - The API key never leaks. The Bugzilla API key is never written to logs, error messages, or tool results; HTTP errors are sanitized so that a key passed as a URL query parameter cannot appear in error text.
- CLI can only tighten.
--read-onlyORs into the policy's read-only flag; there is no CLI switch that loosens the policy.
Deliberate omissions and strict defaults
- No header-echo tool. Incoming request headers — including the API-key header — are never exposed to the model.
- Private comments default to off. The default policy has
allow_private_comments = false, so a policy file is required to enable them. update_bug_fieldsandcreate_bugcustom fields are restricted tocf_*keys as described above.- HTTP is deny-by-default. The http transport refuses to start without a
bearer token unless
--insecure-no-authsays so explicitly; see Authentication and scopes.
Installation
openSUSE (zypper)
bugwarden is packaged in openSUSE Tumbleweed:
sudo zypper install bugwarden
For other openSUSE distributions (Leap 16.x, Slowroll), packages are built in
the devel:tools
project on the openSUSE Build Service.
The package installs worked-example configuration files —
/etc/bugwarden/policy.toml (guard policy) and /etc/bugwarden/audit.toml
(audit stream) — marked %config(noreplace), so local edits survive package
upgrades. Neither is loaded implicitly: the server reads a policy only when
one is named via --policy / BUGWARDEN_POLICY, and an audit configuration
only via --audit-config / BUGWARDEN_AUDIT_CONFIG, so installing the
package does not by itself activate anything.
.deb / .rpm from the release page
Every release carries an
x86_64 .deb and .rpm next to the tarballs, each with a .sha256:
sudo apt install ./bugwarden_<version>-1_amd64.deb # Debian, Ubuntu
sudo dnf install ./bugwarden-<version>-1.x86_64.rpm # Fedora, RHEL
apt/dnf rather than dpkg -i/rpm -i because neither of the latter
resolves dependencies. Both packages are built on current Ubuntu and link
the system glibc, so they need a comparably recent one (2.38+ as of
writing; the package's own Depends/Requires is authoritative). On an
older enterprise base such as RHEL 9 or Debian 12 the install will refuse
— use the container image or build from source there.
Same layout as the openSUSE package above, including both
/etc/bugwarden/*.toml example configs marked noreplace — so an upgrade
keeps local edits, and installing still activates nothing on its own. On
openSUSE prefer the OBS package: these two are x86_64 only and would
conflict with its completion subpackages, while OBS covers every tier-1
architecture.
Container image
podman pull ghcr.io/plusky/bugwarden
A multi-architecture (amd64/arm64) image for HTTP-transport deployments — no Rust toolchain needed. See Container for the run contract.
crates.io (cargo)
cargo install bugwarden
This installs the bugwarden binary into ~/.cargo/bin. Unlike the openSUSE
package it ships no configuration files — copy
examples/policy.toml somewhere and name it via
--policy.
From source
git clone https://github.com/plusky/bugwarden
cd bugwarden
cargo build --release
# binary at target/release/bugwarden
Release artifacts embed the crate list for cargo audit bin; a local
cargo build --release does not.
The repository pins its Rust toolchain via rust-toolchain.toml; cargo
picks it up automatically (rustup-managed installs). Any recent stable Rust
works if you build without the pin. The build compiles aws-lc-sys from
source, so it needs a C toolchain (a C compiler and cmake) as well as
Rust — this applies to cargo install bugwarden too, not only a source
build.
Man page and shell completions
Every release tarball carries the generated CLI assets next to the binary, for a distribution package or a manual install to place:
| Path in the tarball | Conventional destination |
|---|---|
man/bugwarden.1 |
/usr/share/man/man1/bugwarden.1 |
completions/bugwarden.bash |
/usr/share/bash-completion/completions/bugwarden |
completions/_bugwarden |
/usr/share/zsh/site-functions/_bugwarden |
completions/bugwarden.fish |
/usr/share/fish/vendor_completions.d/bugwarden.fish |
Man page and completions alike are derived from the clap command itself —
including the man page's ENVIRONMENT section, so every flag with an
environment variable is listed exactly once — by a second binary behind the
gen cargo feature:
cargo run --locked -p bugwarden --features gen --bin bugwarden-gen
# or, to write somewhere else:
cargo run --locked -p bugwarden --features gen --bin bugwarden-gen -- /tmp/out
Without an argument the generator rewrites the committed copies under
crates/bugwarden/; with one it writes man/ and completions/ under that
directory instead. CI regenerates and diffs them, so the committed assets
cannot drift from the CLI. The feature gates only this generator — the
server binary never links clap_complete or clap_mangen, and a plain
cargo build skips it.
TLS trust anchors and proxies
bugwarden validates the Bugzilla server's certificate against the OS
trust store, not a bundled root set. A Bugzilla instance behind a
corporate or internal CA works as soon as that CA is installed
system-wide — no bugwarden-side configuration is needed. The corollary: an
environment with no CA bundle at all — a scratch image, some minimal base
images — fails every HTTPS request to Bugzilla with a TLS handshake error.
Install ca-certificates in the image, or mount the host's bundle into it.
The published image needs neither: its
gcr.io/distroless/static-debian13 base ships the ca-certificates bundle.
HTTPS_PROXY, HTTP_PROXY and NO_PROXY from the environment are honored
for outbound Bugzilla traffic. Every request to Bugzilla — authenticated
REST calls and the unauthenticated quicksearch-syntax page alike — carries
User-Agent: bugwarden/<version> (+https://github.com/plusky/bugwarden), so
the instance's access log names this build rather than an anonymous HTTP
client. The header carries nothing else: no key material, no policy path,
no host.
Usage
Note: some Bugzilla deployments protect their interactive host with an anti-bot challenge that rejects API clients regardless of credentials. If tools fail with "response body is not valid JSON", check whether the instance offers a dedicated API host (for example
apibugzilla.suse.cominstead ofbugzilla.suse.com) and point--bugzilla-serverat that.
HTTP transport (default)
The server listens on http://<host>:<port>/mcp.
Authentication and scopes
Unlike stdio — where the client already owns the process it launched — HTTP serves anyone who can reach the port, and in server-held key mode that means serving them with the deployment's own Bugzilla credential. Authentication is therefore mandatory and deny-by-default. Two tokens define two scopes:
| Variable | Scope | Tools |
|---|---|---|
BUGWARDEN_HTTP_TOKEN |
write | every tool this deployment's policy serves |
BUGWARDEN_HTTP_READ_TOKEN |
read | the read tools only |
Either may be set alone. A caller presents its token as Authorization: Bearer <token>, which is compared in constant time; anything else — no header, the
wrong token, another scheme, an unrouted path — gets the same empty 401 with
WWW-Authenticate: Bearer, so probing tells a stranger nothing.
A read-scope caller is offered only the read tools in tools/list, and calling
a write tool anyway is answered exactly as calling a tool that does not exist,
with no Bugzilla request made. The split is the same set --read-only removes
from the tool router, so the two cannot drift. Because the advertised tool set
depends on the credential, a client that caches tools/list across tokens will
show a stale list.
Tokens are never accepted as command-line flags — argv is world-readable via
ps — so they come from the environment only. bugwarden reads no .env file:
supply them through the container runtime, or through a systemd unit's
EnvironmentFile= written with a restrictive umask.
Mint one token and keep it: the clients have to present the same value, so a
token generated inline on the command line (BUGWARDEN_HTTP_TOKEN=$(openssl rand -hex 32) bugwarden …) starts a server nobody can talk to.
umask 077
openssl rand -hex 32 > /etc/bugwarden/http-token
export BUGWARDEN_HTTP_TOKEN="$(cat /etc/bugwarden/http-token)"
bugwarden \
--bugzilla-server https://bugzilla.opensuse.org \
--policy /etc/bugwarden/policy.toml \
--host 127.0.0.1 --port 8000
Under systemd, name the file in an EnvironmentFile= instead — one
BUGWARDEN_HTTP_TOKEN=<value> line, mode 0600 — so the value never reaches a
shell history or a ps listing.
The server refuses to start — before the port is bound, exit status 1 — when:
- the http transport is in use (it is the default) with no token and no
--insecure-no-auth; --insecure-no-authis combined with either token;- a token is shorter than 32 characters, or contains anything but printable non-space ASCII;
- the read token equals the write token.
Tokens set while running over stdio are ignored, and so is --insecure-no-auth
— there is no network principal to authenticate there.
--insecure-no-auth serves the endpoint with no authentication at all: every
caller reaching the port gets the full write scope. It is a command-line flag
with no environment variable, so no ambient value can turn authentication off,
and the server says so loudly at startup.
The transport is plaintext HTTP. A bearer token sent over it is readable by anything on the path, so do not expose the port beyond a trusted network without terminating TLS in front of it (reverse proxy, service mesh, or an SSH tunnel).
A static bearer token is not MCP's OAuth 2.1 authorization flow. A client that only implements the spec's
401→ resource-metadata → OAuth dance will not authenticate; use one that lets you set a header. And the token authenticates a deployment, not a caller: audit records carry noprincipaland nowork_context. Both slots are reserved for a validator that can prove which caller made a call and what work it was authorized under, which stays issue #32's job.
Bugzilla credentials
Each client request carries the Bugzilla API key in an HTTP header (default
header name: ApiKey), so one server can serve multiple users with their own
keys. This is independent of the bearer gate above: bearer authenticates the
caller to bugwarden, the API key authenticates bugwarden's request to Bugzilla.
MCP client configuration (exact format varies by client) — both headers are required over http, one for each hop:
{
"mcpServers": {
"bugzilla": {
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer YOUR_BUGWARDEN_HTTP_TOKEN",
"ApiKey": "YOUR_BUGZILLA_API_KEY"
}
}
}
}
In server-held key mode drop the
ApiKey line: the server supplies the Bugzilla key, so Authorization is the
only credential a client holds — which is the point of that mode.
The header name is configurable with --api-key-header. For Bugzilla
instances that reject the api_key query parameter and require
Authorization: Bearer (e.g. Red Hat Bugzilla), add --use-auth-header —
this affects only server-to-Bugzilla authentication, not the client-facing
header.
Choose the placement the deployment in front of you honours: the query
parameter is what stock Bugzilla accepts, and what BMO still accepts
but documents as deprecated — BMO's supported forms are its own
X-Bugzilla-API-Key header and OAuth2 bearer tokens. The Bearer token
is the Red Hat form, and no other header form is sent. If the network
path between bugwarden and Bugzilla strips the chosen form — a proxy
dropping headers, a gateway rewriting query strings — every request
arrives anonymous: reads quietly narrow to what an anonymous caller may see,
and writes fail with "You must log in before using this part of
Bugzilla" (code 410). The key itself is fine in that state; switch the
placement to the form that survives the path. When the guard policy
consults identity, the startup preflight names this cause before the
server starts serving.
Server-held key mode (fleet deployments)
With --api-key-file the Bugzilla API key belongs to the server: every
request is served with the key read from that file, clients present no
credential at all, and the per-request header is not consulted — a request
that does carry one is served with the server's key, and the header value is
never read. There is no fallback between the two modes in either
direction (handing clients the real key would let them bypass the guard by
talking to Bugzilla directly). This fits deployments where the key is
provisioned as a container secret or a systemd credential
(LoadCredential=bugzilla-key:/etc/bugwarden/bugzilla-key plus
--api-key-file ${CREDENTIALS_DIRECTORY}/bugzilla-key):
export BUGWARDEN_HTTP_TOKEN="$(cat /etc/bugwarden/http-token)"
bugwarden \
--bugzilla-server https://bugzilla.opensuse.org \
--policy /etc/bugwarden/policy.toml \
--api-key-file /run/secrets/bugzilla-key \
--host 127.0.0.1 --port 8000
The file's content is trimmed, so a trailing newline is fine; an empty or unreadable file is a startup error naming the path (never its contents). The file is read exactly once, at startup — rotating the key requires a restart. Keep it mode 0600: bugwarden warns when group or others can access it.
One policy consequence to know: in this mode every client authenticates to
Bugzilla — and resolves identity — as the service account that owns the key,
so a policy rule matching on created_by_me describes that one account's
bug reports for all clients, not each caller's own. bugwarden warns at
startup when server-held mode meets such a policy.
stdio transport
For MCP clients that launch the server as a subprocess and speak over
stdin/stdout. There are no per-request HTTP headers here, so the API key must
be provided up front via --api-key / BUGZILLA_API_KEY or --api-key-file
(starting without one is an error). One request is one newline-delimited
line, bounded by the same cap as an HTTP POST body (see
global.max_attachment_bytes below); a line that runs past it is refused,
the transport closes and the process exits 1, since nothing can be sent
back for a request that was never parsed. That refusal is logged at WARN —
it is the cap doing its job, not something to page an operator about. Beside
it the MCP library echoes the same reason at ERROR, and before a completed
handshake the server adds one ERROR of its own, the line that reports the
session is over; after a completed handshake the library's echo is the only
ERROR there is. The first JSON-RPC message the server parses has to open a
session — initialize, or a request whose _meta declares the handshake-free
lifecycle (see MCP protocol revisions below); a ping or a server/discover
probe may come first and commits neither. A line that is no JSON-RPC message at
all does not count as that first message: an unparsable one is dropped, a
well-formed one of the wrong shape is answered -32600, and the server goes on
waiting either way. Any other opening message ends the process with exit 1,
and there the log line and the Error: line the process exits with name only
the kind of message that arrived — never its content, whose size only the
cap bounds.
BUGZILLA_API_KEY=your_api_key \
bugwarden \
--bugzilla-server https://bugzilla.opensuse.org \
--transport stdio \
--policy /etc/bugwarden/policy.toml
MCP client configuration:
{
"mcpServers": {
"bugzilla": {
"command": "/usr/local/bin/bugwarden",
"args": [
"--bugzilla-server", "https://bugzilla.opensuse.org",
"--transport", "stdio",
"--policy", "/etc/bugwarden/policy.toml"
],
"env": {
"BUGZILLA_API_KEY": "YOUR_BUGZILLA_API_KEY"
}
}
}
}
bugwarden MCP questions
What tools does bugwarden MCP provide?
It exposes 22 tools, including bug_info, bug_history, bug_comments, bugs_quicksearch, summarize_bug.
How does the security guard work?
The guard uses a TOML policy file loaded at startup to decide, per bug, what the model is allowed to do based on criteria like product, component, or severity.
Can the AI model see or change the security policy?
No, the policy file is stored on the operator's filesystem and the model has no tools to read, list, or modify it.
What happens if a bug is denied by the policy?
A denied bug is treated as if it does not exist, returning the same response as a non-existent bug to prevent existence oracles.