Oauth Auditor

@guardbee/mcp-oauth-auditor

🇬🇧 English | 🇹🇷 Türkçe | 🇨🇳 中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇧🇷 Português | 🇪🇸 Español | 🇩🇪 Deutsch

[npm version] [npm downloads] [License: MIT]

An MCP (Model Context Protocol) server that scans an MCP server's own authorization code for OAuth 2.1 anti-patterns named in the MCP specification's own Security Considerations section.

The MCP spec doesn't leave this to guesswork — it explicitly calls out token passthrough (forwarding a client's token to a downstream API unchanged, instead of exchanging/re-scoping it) and missing audience validation (accepting a token whose aud claim was never issued for this server) as the central authorization failure modes for a server acting as an OAuth resource server. This package checks for exactly those two, plus three related anti-patterns in the same family.

Telemetry is off by default. With GUARDBEE_TELEMETRY=1 it sends the server, tool, success, duration and short parameter values such as a file path; longer strings and fields like content, token or password are replaced with a placeholder. See @guardbee/mcp-telemetry.

Claude ──► oauth-auditor ──► Your MCP server's auth code              │              ├─ token-passthrough    (client's token forwarded unchanged downstream)              ├─ token-validation     (jwt.verify() with no audience check)              ├─ discovery-ssrf       (OAuth/OIDC discovery URL built from client input)              ├─ pkce                 (authorization request missing code_challenge)              ├─ redirect-validation  (redirect_uri checked with startsWith/includes, not exact match)              └─ secrets-exposure     (hardcoded client_secret)

Why these two specifically

Token passthrough matters because a token a client presented to this server was scoped and audienced for this server — not whatever downstream API the server's own tool handlers call next. Forwarding it unchanged means the downstream service is trusting a credential it never issued, on the basis of a server-side decision the original token issuer never approved.

Missing audience validation is the same failure from the other direction: jwt.verify(token, key) confirms a token's signature is valid, but says nothing about who it was issued for. Without an explicit audience check, a token minted for a completely unrelated resource server — one that happens to share the same issuer/signing key — will verify successfully here too. This is the textbook confused-deputy substitution the MCP spec is warning about.

The other three patterns are adjacent, concrete instances of the same "an MCP server's auth code trusts something it shouldn't" theme: an OAuth/OIDC discovery URL built from client-supplied input (the shape behind a real disclosed CVE), a redirect_uri validated with a prefix/substring check instead of an exact match (open-redirect bypass), and PKCE silently missing from an authorization request (required by OAuth 2.1 unconditionally, not just for public clients).

Features

• 6 categories: token-passthrough, token-validation, discovery-ssrf, pkce, redirect-validation, secrets-exposure
• Two of the checks (missing audience validation, missing PKCE) look for an absence near a call site rather than a fixed regex — they extract the full jwt.verify(...) call (or the authorization-request URL construction) and confirm audience: / code_challenge is genuinely nowhere nearby, not just matched by a lucky string position
• SARIF 2.1.0 output — CI/CD integration (GitHub Code Scanning, etc.)
• Config file support via guardbee.yml
• 18 unit tests — a positive and a negative (false-positive) scenario for every pattern, plus one fully-correct OAuth flow that produces zero findings. Found and fixed a real regex bug during development (a trailing \b after a ] character that can never match, since ] isn't a word character — silently missed the bracket-notation form of header access). End-to-end verified against a fixture with all 6 anti-patterns deliberately planted (caught all 6), and against the entire guardbee-mcp monorepo (401 files — zero findings in any real third-party code; the only non-test matches were the scanner's own pattern-definition source textually containing the string jwt.verify( inside a regex literal and a doc comment, not actual vulnerable usage)

Quick Start

Claude Desktop / MCP Client

{  "mcpServers": {    "guardbee-oauth-auditor": {      "command": "npx",      "args": ["-y", "@guardbee/mcp-oauth-auditor"]    }  }}

CLI (CI/CD)

npx @guardbee/mcp-oauth-auditor scan ./src --fail-on=high --format=sarif > results.sarif

MCP Tools

Detected Patterns

Python and Go

The language comes from the file extension, and Python- and Go-specific rules run only on their own files.

• Python (FastAPI / Starlette / Flask, PyJWT, python-jose, authlib): python_missing_audience_validation (jwt.decode with no audience= and no authlib claims_options aud), python_audience_verification_disabled ("verify_aud": False), python_token_passthrough_to_downstream (the Authorization header or all of request.headers on a requests / httpx / client call), missing_pkce_on_auth_request on authlib create_authorization_url / authorize_redirect with no code_challenge, and the discovery SSRF, redirect, state and 0.0.0.0 rules.
• Go (golang-jwt / jwx, go-oidc, golang.org/x/oauth2, go-sdk and mcp-go HTTP transports): go_missing_audience_validation (jwt.Parse with no jwt.WithAudience), go_oidc_client_id_check_skipped, go_token_passthrough_to_downstream (out.Header.Set("Authorization", r.Header.Get("Authorization"))), go_hardcoded_oauth_client_secret, go_loose_redirect_uri_validation (strings.HasPrefix), go_predictable_state_handle (math/rand, time), go_oauth_discovery_ssrf, go_auth_url_opened_via_shell, missing_pkce_on_auth_request on AuthCodeURL with no S256ChallengeOption, and ListenAndServe(":8080") as listen_all_interfaces.
• Both: token_passthrough_via_variable — the incoming Authorization header read into a variable that is then put on an outgoing request.

Every finding links its section of the MCP spec Security Best Practices (SARIF helpUri) and carries its OWASP MCP Top 10 id as a SARIF tag. The newer rules are heuristics over one file at a time: a check done in another module (an auth middleware, an iss comparison in a helper) is not seen.

Live probe

npx @guardbee/mcp-oauth-auditor probe http://127.0.0.1:3000/mcp

Read-only checks of a running HTTP MCP endpoint: does it answer an initialize without credentials (probe_unauthenticated_access), and does it accept a foreign Host (probe_dns_rebinding_host_accepted) or Origin (probe_foreign_origin_accepted)? It sends no credentials, calls nothing beyond initialize, closes any session it opened, and refuses a host that resolves to a public address unless --allow-public. CLI only: an agent cannot start it through the MCP tools.

Configuration (guardbee.yml)

oauth-auditor:  fail-on: high       # any | critical | high | medium | none  max-files: 5000  exclude:    - ".test.ts"

Limitations (by design)

• TypeScript/JavaScript, Python and Go. Each has rules for its common libraries (above). Other languages (Rust, Java, C#, …) and other libraries are only matched where they happen to share a shape with these, e.g. a literal client_secret or response_type=code.
• Heuristic, not a full OAuth conformance test. This finds specific anti-patterns in source, not a live protocol conformance check against a running authorization server. It won't catch every way an OAuth flow can be misimplemented — only the handful the MCP spec calls out as the highest-stakes ones.
• The absence-based checks (audience, PKCE) use a bounded text window, not a real parser — a jwt.verify() call whose options object happens to be built far away from the call site (a variable passed in, rather than an inline object) won't be checked for audience correctly.

Development

npm run buildnpm test

License

MIT — GuardBee

Feedback

Questions, ideas, or a false positive? Start a thread in GitHub Discussions or open an issue. If GuardBee is useful to you, a ⭐ on the repository helps others find it.