bugwarden

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 / restrict decisions
  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 for restrict.
• 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_days makes 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.
• Two transports: streamable HTTP (per-request API key header, or a
  server-held key via --api-key-file for fleet deployments) and stdio
  (subprocess launch by a desktop MCP client).
• Single static binary, async throughout (tokio + rmcp).

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. (Server-side debug logs do record it for the
  operator.)
• 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 via
  operations is 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 = true and the individual call opts in
  with include_private = true. Either alone is not enough.
• Custom fields cannot smuggle writes. update_bug_fields.custom_fields
  accepts only keys starting with cf_; anything else (e.g. groups, cc,
  assigned_to) is rejected before Bugzilla is contacted.
• 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-only ORs 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_fields custom fields are restricted to cf_* keys as
  described above.

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.

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

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.

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.com
instead of bugzilla.suse.com) and point --bugzilla-server at that.

HTTP transport (default)

The server listens on http://<host>:<port>/mcp. 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:

bugwarden \
  --bugzilla-server https://bugzilla.opensuse.org \
  --policy /etc/bugwarden/policy.toml \
  --host 127.0.0.1 --port 8000

MCP client configuration (exact format varies by client):

{
  "mcpServers": {
    "bugzilla": {
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "ApiKey": "YOUR_BUGZILLA_API_KEY"
      }
    }
  }
}

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.

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):

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):

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

CLI reference

Command-line arguments take precedence over environment variables.

Policy file reference

The policy is strict TOML: unknown keys anywhere are a startup error, as
is a restrict rule without capabilities, an allow/deny rule with
capabilities, or default_action = "restrict". On Unix, bugwarden logs a
warning at startup if the policy file is group- or other-writable.

A complete, commented example ships in
examples/policy.toml.

Top level

[global]

[[rule]]

Rules are evaluated top to bottom; the first rule whose matcher matches the
bug wins and later rules are ignored. If no rule matches, default_action
applies. Put your most specific (usually most restrictive) rules first.

Note that a restrict rule's capabilities list is the complete grant
for every operation the rule covers, not an addition to what other rules or
default_action would have granted — that is why a rule granting only
create should carry operations = ["create"], so it decides filing without
becoming the first-match rule for reads of the bugs it matches.

match criteria

All criteria present in a matcher must hold (AND). Within a single list,
any element may match (OR). An empty matcher matches every bug — a rule
with no match is a catch-all. To express "criterion A or criterion B",
write two consecutive rules.

Unreadable metadata

Every criterion needs a field the bug object may not carry — absent, null,
of an unexpected type, or a list with an element the parser cannot read. Such
a field is unknown, and a rule that consults one is undecidable: it neither
holds nor fails. One criterion needs more than the bug object:
created_by_me also needs the caller's identity, and if either half is
missing — an unreadable creator, or a whoami lookup that failed — it is
just as undecidable and resolves the same way. A policy consulting identity
therefore denies everything its identity rules are consulted for while
whoami is failing; that is deliberate (treating unknown identity as "does
not match" would let a created_by_me deny rule be defeated by breaking
whoami). The criterion cannot widen exposure beyond the credential:
Bugzilla enforces its own permissions on every fetch, so an authorship rule
only surfaces bugs the API key could already read.

bugwarden resolves an undecidable rule by denying the bug, whatever the
rule's action. A deny rule denies because the bug may well be what it was
written to catch. An allow or restrict rule denies too — it may not grant
access on data nobody could check, and it may not simply be skipped either,
because skipping would hand the bug to a later rule or to default_action. So
unreadable metadata never buys a bug more access than readable metadata would.

Two things this deliberately does not do. A criterion that already failed
definitively wins over an unknown one, so a rule ruled out by another criterion
stays ruled out. And only the fields a rule actually consults matter — a
missing whiteboard is irrelevant to a rule that never mentions the whiteboard.
Likewise, only the rules actually consulted matter: a rule scoped away from
the operation being decided (operations) is skipped before its matcher runs,
so its criteria cannot make anything undecidable for that operation.
A field that is present but empty ("", []) is knowledge, not ignorance, and
is matched normally.

Glob syntax

Globs match the whole value, case-insensitively. * matches any (possibly
empty) substring; every other character is literal. There are no other
metacharacters. Examples: embargo*, *security*, SUSE *.

Capabilities

Thirteen capabilities exist. read implies summary; nothing else is
implied.

Upgrading from a version without create/attach: the capability set
grew from eleven to thirteen, and allow (rules and
default_action = "allow" alike) always grants the full set. A policy
written before these capabilities existed therefore starts permitting bug
filing and attachment upload the moment the server is upgraded, with no
change to the policy file. To keep the old behaviour, either add
disabled_tools = ["create_bug", "add_attachment"] under [global], or
replace allow grants with restrict rules listing exactly the
capabilities you mean. Read-only deployments are unaffected (both new
capabilities are writes).

When the server is read-only (policy or CLI), the eight write capabilities
are stripped from every grant, including from allow rules and the default
action.

Tool reference

License

Apache License 2.0. See LICENSE for details.