bugwarden(1)

🦋 bugwarden(1) 🦋

okay bestie, welcome to the General Commands Manual page for bugwarden(1) — manual name folded right in here so we can get to the good stuff. 🫶

---

✨ NAME ✨

bugwarden — MCP server for Bugzilla with operator-controlled security guards. that's the whole name, and honestly it's giving secure little gateway energy. 💅

---

📜 SYNOPSIS 📜

here's the whole invocation shape, bestie — keep it exact, no cap:

bugwarden --bugzilla-server <BUGZILLA_SERVER> [--transport <TRANSPORT>]
       [--host <HOST>] [--port <PORT>] [--allowed-hosts <HOST>]
       [--api-key-header <API_KEY_HEADER>] [--api-key <API_KEY>]
       [--api-key-file <API_KEY_FILE>] [--use-auth-header] [--read-only]
       [--policy <POLICY>] [--audit-config <AUDIT_CONFIG>] [--insecure-no-auth]
       [-h|--help] [-V|--version]

---

💖 DESCRIPTION 💖

MCP server for Bugzilla with operator-controlled security guards. that's it, that's the description — but like, say it with your chest: operator-controlled security guards are the moment. ✨

---

🎀 OPTIONS 🎀

okay, option time. one bullet per flag, no skips, no cap. 💖

• --bugzilla-server <BUGZILLA_SERVER> — Base URL of the Bugzilla server, like https://bugzilla.example.com. If you don't pass it, the environment variable BUGZILLA_SERVER is used instead.
• --transport <TRANSPORT> [default: http] — Transport for the MCP server: 'http' (default) or 'stdio'. Environment variable MCP_TRANSPORT can also be used.

Possible values:

• http: Streamable HTTP transport (default). Clients send the Bugzilla API key per-request via the API key header, unless --api-key-file selects server-held key mode — then the header is not consulted at all.
• stdio: Stdio transport. The API key comes from --api-key / BUGZILLA_API_KEY or --api-key-file at startup.

• --host <HOST> [default: 127.0.0.1] — Host address for the MCP server to listen on (http transport only). Defaults to 127.0.0.1 or the MCP_HOST environment variable.
• --port <PORT> [default: 8000] — Port for the MCP server to listen on (http transport only). Defaults to 8000 or the MCP_PORT environment variable.
• --allowed-hosts <HOST> — Hostname or 'host:port' authority accepted in an inbound Host header (http transport only). Repeat the flag, or separate entries with commas; environment variable MCP_ALLOWED_HOSTS can also be used. Empty entries are dropped, so MCP_ALLOWED_HOSTS= is an unset (like BUGZILLA_API_KEY_FILE=); without a host, Host validation stays off and any Host header is served. An entry that is not a hostname or host:port — for example '*', a URL, or a space-containing typo — is a startup error.
• --api-key-header <API_KEY_HEADER> [default: ApiKey] — HTTP header for clients to send the Bugzilla API key. Defaults to 'ApiKey' or the MCP_API_KEY_HEADER environment variable. Not consulted in server-held key mode (--api-key-file over http).
• --api-key <API_KEY> — Bugzilla API key. Required for --transport stdio (no HTTP headers exist there) unless --api-key-file provides it. Environment variable BUGZILLA_API_KEY can also be used. Ignored for --transport http — clients send the key per-request via the API key header; use --api-key-file for a server-held key.
• --api-key-file <API_KEY_FILE> — Path to a file holding the Bugzilla API key, e.g. a container secret or systemd LoadCredential path. Mutually exclusive with --api-key. Over http this selects server-held key mode: every request is served with this key and the per-request API key header is not consulted. An empty value counts as absent, like --api-key — so BUGZILLA_API_KEY_FILE= is an unset, not an error.
• --use-auth-header — Use 'Authorization: Bearer' header instead of the api_key query parameter (required for some Bugzilla instances). Environment variable BUGZILLA_USE_AUTH_HEADER=true can also be used.
• --read-only — Disables all tools which modify the state of a bug. Environment variable MCP_READ_ONLY=true can also be used. Can only tighten the guard policy, never loosen it.
• --policy <POLICY> — Path to the guard policy TOML file. Environment variable BUGWARDEN_POLICY can also be used. Without it, an allow-all default policy is used.
• --audit-config <AUDIT_CONFIG> — Path to the audit configuration TOML file (see examples/audit.toml). Environment variable BUGWARDEN_AUDIT_CONFIG can also be used. The exact value none disables the audit file (OTLP-only when an endpoint is set). Without it, and with no OTLP endpoint, no audit stream is written. An endpoint with no file decision, or none with no endpoint, is a startup error.
• --insecure-no-auth — Serve the http transport without bearer authentication. Only for a trusted, isolated network: every caller that reaches the port gets the full write scope. Command line only, with no environment variable, so no ambient value can turn authentication off. Tokens are never taken from the command line either (argv is world-readable): set BUGWARDEN_HTTP_TOKEN / BUGWARDEN_HTTP_READ_TOKEN in the environment.
• -h, --help — Print help (see a summary with '-h').
• -V, --version — Print version.

---

🚪 EXIT STATUS 🚪

• 0 — Clean shutdown.
• 1 — Startup or runtime failure: a missing or malformed http bearer token, an unreadable policy or audit configuration, a key misconfiguration, an unparsable --allowed-hosts list, an OTLP collector that will not take records, a Bugzilla client or transport error.
• 2 — Command-line usage error.

---

🌈 ENVIRONMENT 🌈

Most variables are the fallback for one option; a command-line argument always wins over the environment, and the built-in default applies when neither is given. The two bearer tokens are the exception: they have no option at all and are read from the environment only, because argv is world-readable. 💅

• BUGZILLA_SERVER — Fallback for --bugzilla-server.
• MCP_TRANSPORT — Fallback for --transport.
• MCP_HOST — Fallback for --host.
• MCP_PORT — Fallback for --port.
• MCP_ALLOWED_HOSTS — Fallback for --allowed-hosts.
• MCP_API_KEY_HEADER — Fallback for --api-key-header.
• BUGZILLA_API_KEY — Fallback for --api-key.
• BUGZILLA_API_KEY_FILE — Fallback for --api-key-file.
• BUGZILLA_USE_AUTH_HEADER — Fallback for --use-auth-header.
• MCP_READ_ONLY — Fallback for --read-only.
• BUGWARDEN_POLICY — Fallback for --policy.
• BUGWARDEN_AUDIT_CONFIG — Fallback for --audit-config.
• BUGWARDEN_HTTP_TOKEN — Bearer token granting the write scope over the http transport: every tool the guard policy serves. Environment only — there is no command-line flag, because argv is world-readable. At least 32 printable non-space ASCII characters.
• BUGWARDEN_HTTP_READ_TOKEN — Bearer token granting the read scope over the http transport: the read tools only. Same rules, and it must differ from BUGWARDEN_HTTP_TOKEN. Either token may be set alone; over http, setting neither is a startup error unless --insecure-no-auth is given.
• OTEL_EXPORTER_OTLP_ENDPOINT — Base URL of an OpenTelemetry collector (bugwarden appends /v1/logs). Environment only. Unset or empty turns export off. Must be paired with --audit-config / BUGWARDEN_AUDIT_CONFIG (a file, or the exact value none). An endpoint with no file decision is a startup error.
• OTEL_EXPORTER_OTLP_HEADERS — Headers added to every export request, key=value separated by commas. Credential material (I12): environment only, never logged.
• OTEL_EXPORTER_OTLP_PROTOCOL — The one accepted value is http/protobuf; anything else is a startup error. Not consulted while export is off.
• OTEL_SERVICE_NAME — service.name on exported records. Defaults to bugwarden.
• OTEL_EXPORTER_OTLP_LOGS_ENDPOINT — Logs-specific endpoint; overrides OTEL_EXPORTER_OTLP_ENDPOINT and is used as given (write the whole URL including /v1/logs).
• OTEL_EXPORTER_OTLP_LOGS_HEADERS — Logs-specific headers; overrides OTEL_EXPORTER_OTLP_HEADERS. Same secrecy.
• OTEL_EXPORTER_OTLP_LOGS_PROTOCOL — Logs-specific protocol; overrides OTEL_EXPORTER_OTLP_PROTOCOL.

---

📁 FILES 📁

• /etc/bugwarden/policy.toml — Worked example guard policy as installed by distribution packages; the source tree and release archives ship it as examples/policy.toml. The server reads a policy only when one is named with --policy or BUGWARDEN_POLICY; without one, the built-in allow-all default policy applies.
• /etc/bugwarden/audit.toml — Worked example audit configuration; the source tree ships it as examples/audit.toml. Without --audit-config or BUGWARDEN_AUDIT_CONFIG and with no OTLP endpoint, no audit stream is written. The exact value none disables the file so a collector can be the only sink.

---

🧚 EXAMPLES 🧚

Serve a local MCP client over stdio, with the server reading the Bugzilla API key from a file. bestie, note the --transport stdio and --api-key-file combo:

           bugwarden --transport stdio \
               --bugzilla-server https://bugzilla.example.com \
               --api-key-file ~/.config/bugwarden/api-key \
               --policy /etc/bugwarden/policy.toml

Listen on HTTP — that's the default transport, 127.0.0.1:8000 — where each client presents a bearer token to this server and its own key in the API key header. The token is minted once and kept; a value generated inline would start a server no client could present a credential to. yes, that's the whole warning — read it twice 🫶

           export BUGWARDEN_HTTP_TOKEN="$(cat /etc/bugwarden/http-token)"
           bugwarden --bugzilla-server https://bugzilla.example.com \
               --policy /etc/bugwarden/policy.toml

Listen on HTTP with a server-held key (container secret, systemd LoadCredential): every request is served with this key and the per-request key header is not consulted, so the bearer token is the only thing a client presents. 💅

           export BUGWARDEN_HTTP_TOKEN="$(cat /etc/bugwarden/http-token)"
           bugwarden --bugzilla-server https://bugzilla.example.com \
               --api-key-file /run/secrets/bugzilla-api-key \
               --policy /etc/bugwarden/policy.toml

---

💖 okay that's the whole bugwarden(1) page, bestie — source/version sign-off: bugwarden 0.6.0, manual handle bugwarden(1). mwah 💋✨