oauthlint

npx oauthlint scan ./src

Self-contained: nothing to install and no config. The CLI bundles the rule pack and, on first run, downloads and checksum-verifies a small pinned scan engine (~41 MB, one time, cached). It reuses an installed opengrep or semgrep if one is on your PATH; override it with OAUTHLINT_ENGINE or --engine.

📖 Full documentation & rule catalogue: oauthlint.dev · 🔬 the empirical case for it: oauthlint.dev/research

What it is

AI coding assistants (tools like GitHub Copilot, Cursor, and Claude Code, and others) ship the same OAuth/JWT bugs across every project they touch:

• JWT verified with alg: none accepted
• client_secret hard-coded in source
• redirect_uri whitelisted with * wildcards
• token written to localStorage (XSS-readable)
• OAuth flow without state / without PKCE
• /login POST without rate limiting
• password persisted in plaintext
• Math.random() used for CSRF tokens
• untrusted input flowing into a redirect or an outbound request (open-redirect / SSRF), caught by dataflow (taint) analysis rather than plain pattern-matching
• MCP server auth: token pass-through (confused deputy), missing RFC 8707 audience/resource binding, unauthenticated MCP transports, and SSRF from tool-handler arguments, for the official TypeScript and Python MCP SDKs
• …and many more: 270+ rules across eleven languages (JavaScript, TypeScript, Python, Go, C#, and more), including mobile auth (Swift/iOS, Android) and framework-aware coverage (ASP.NET Core, Gin/Echo/Fiber, Hono + better-auth, FastAPI, Django/Flask, Ktor, Spring Security, Laravel/Socialite, Rails/Devise/OmniAuth/Doorkeeper, NextAuth/Passport, Express/Fastify/NestJS, MCP, and more)

oauthlint sits between generic SAST (Snyk, Semgrep) and enterprise IAM ($50K+/year): free, focused, and built for the developer who has to fix the finding. Every finding links to a page explaining why it matters and how to fix it.

Why OAuthLint?

Honest answer: nothing stops you from writing these rules yourself. Semgrep is open source, it's the engine we run, and a capable engineer could reproduce a lot of this. We don't have a technical moat, and we won't pretend otherwise.

What we have is the work most people never do:

• Low false positives, validated against real auth libraries. We run the rules against jose, NextAuth, PyJWT, Authlib, golang/oauth2, oauth2-rs, Spring and more. Anything that fires on mature library source goes to a triage queue, not to you. Tuning a rule so it doesn't trip on jose's internals is the tedious, invisible work the generic Semgrep registry skips. (See the validation report: thousands of files of real auth-library source, zero false positives on the clean libraries.)
• One coherent product across every language it covers. Same concept, same ID scheme, same docs. AUTH-JWT-001 in JS maps to AUTH-GO-JWT-001 in Go, instead of a patchwork of community rules with mismatched styles.
• Every finding teaches. Every rule links to a fix page with CWE and OWASP mappings, so a finding is a lesson rather than a grep hit.
• Dataflow, not only patterns. Taint-mode rules trace untrusted input through to dangerous sinks (open-redirect, SSRF), catching bugs a single-line pattern would miss.
• The angle the registry doesn't have. OAuthLint targets the OAuth/JWT bugs AI coding tools ship on repeat. Each rule encodes that in its llm-prevalence metadata, and the empirical /research report measures it.

Use OAuthLint when you'd rather not write and maintain an auth rule pack yourself. That's the whole pitch.

What it looks like

Every finding names the rule, the exact file and line, why it is dangerous, and
a link to the fix.

Quick start

CLI

# one-shot scan, no install
npx oauthlint scan ./src

# fail CI on HIGH severity and above
npx oauthlint scan ./src --fail-on HIGH

# machine-readable output
npx oauthlint scan ./src --json

# GitHub Code Scanning
npx oauthlint scan ./src --format sarif > oauthlint.sarif

# a shareable, self-contained HTML audit report
npx oauthlint scan ./src --format html > report.html

# auto-apply safe fixes (e.g. cookie flags); preview them first with --fix-dry-run
npx oauthlint scan ./src --fix-dry-run
npx oauthlint scan ./src --fix

# incremental: scan only what changed (fast; great for pre-commit hooks)
npx oauthlint scan --diff       # vs the default branch
npx oauthlint scan --staged     # only git-staged files

# adopt on an existing codebase: snapshot today's findings, then alert on NEW ones only
npx oauthlint baseline ./src
npx oauthlint scan ./src --baseline --fail-on HIGH

Other commands: oauthlint list (browse rules), oauthlint explain <rule-id> (read a rule's why and fix in your terminal), oauthlint init (write a config), oauthlint doctor (check your setup).

GitHub Action

- uses: Auspeo/oauthlint@v1
  with:
    severity: HIGH
    fail-on: HIGH

The Action is Docker-based, so it runs in any repository's CI regardless of the project's language. Auspeo/oauthlint@v1 is the GitHub Marketplace entrypoint; the original Auspeo/oauthlint/action@v1 subpath still works and behaves identically. The SARIF output (--format sarif) uploads to GitHub Code Scanning, and there's a recipe for GitLab CI too.

VS Code, Cursor, Windsurf, and other VS Code forks

Install oauthlint from the VS Code Marketplace (or OpenVSX for Cursor, Windsurf, and other VS Code forks and agentic editors) for inline diagnostics on save, a status-bar finding count, an "Apply fix" Quick Fix where a rule ships a safe autofix, and Quick Fix suppressions. The extension is self-contained: the rule pack and scan engine come with it, so there is no CLI or Semgrep to install.

MCP server (scan AI-generated code in-loop)

oauthlint-mcp is an MCP server that hands the rule pack to AI coding tools (Claude Code, Cursor, Windsurf, and others) so they can scan the OAuth code they just wrote, in the same loop that produced it. The bug gets caught before it reaches your diff.

// add to your tool's MCP config
{
  "mcpServers": {
    "oauthlint": { "command": "npx", "args": ["oauthlint-mcp"] }
  }
}

The oauthlint-mcp package is on npm, so npx oauthlint-mcp runs it with no install. Setup for each tool is at oauthlint.dev/docs/mcp.

Use directly with Semgrep

Already have Semgrep? Run the full pack with one command, no install and no config file:

semgrep --config https://oauthlint.dev/r/oauthlint.yaml ./src

Per-language bundles are available too (e.g. oauthlint-python.yaml, oauthlint-go.yaml). The hosted config is always the latest pack; for a pinned ruleset, use the oauthlint CLI / oauthlint-rules on npm. See the Semgrep docs.

Inline suppression

// oauthlint-disable-next-line auth.jwt.alg-none -- legacy code, replaced in Q2
return jwt.verify(token, key, { algorithms: ['RS256', 'none'] });

Wholesale silencing (oauthlint-disable-file *) is intentionally unsupported. The next reviewer needs to see exactly which lines opted out.

Rules

270+ rules across OAuth 2.0, OIDC, JWT, cookies, CORS, secrets, session hygiene and MCP server auth, spanning eleven languages from JavaScript and Python to Go, C#, and Kotlin, plus mobile auth (Swift/iOS, Android), with framework-aware coverage (ASP.NET Core, Laravel, Rails, Ktor, and more). Each is mapped to CWE and OWASP and has a documentation page. Some are taint-mode dataflow rules that follow untrusted input to its sink rather than matching a single line: an OAuth credential reaching a log sink, request input reaching a JWT verification key, or a value flowing into a redirect or outbound request (open-redirect, SSRF). SSRF coverage now spans JS/TS, Python, Go, Java (Spring) and Rust (reqwest), and a dedicated rule catches Authorization: Basic credentials written to logs. A dedicated MCP rule pack catches the OAuth 2.1 resource-server mistakes MCP servers ship (token pass-through, missing RFC 8707 audience binding, unauthenticated transports, tool-handler SSRF) for the official TypeScript (@modelcontextprotocol/sdk) and Python (mcp / FastMCP) SDKs. The catalogue grows with every release.

👉 Browse the full catalogue at oauthlint.dev/rules.

Language support

oauthlint is built on Semgrep, whose engine is language-agnostic. The rules are plain YAML data, so adding a language means writing rule packs, not re-architecting anything.

Why JS/TS first? That's where AI coding tools generate the most code, and so the most OAuth/JWT bugs. It's the densest place to start, not the ceiling. Want your stack covered? Open an issue.

What's in this repo

Develop

pnpm install
pnpm test:run     # full suite: rule pack + CLI + Action + VS Code + scripts
pnpm lint
pnpm build
pnpm typecheck
pnpm --filter oauthlint-site dev     # preview the docs site locally

Adding a rule: drop a YAML file in rules/rules/<category>/, add vulnerable.ts + safe.ts fixtures, and the schema-driven tests pick it up automatically. The docs site (site/) generates its rule pages straight from the rule pack, so no separate docs-refresh step is needed.

Commits & releases

• Conventional Commits are enforced (feat:, fix:, docs:, chore:, …) via a commit-msg hook.
• Git hooks (husky): pre-commit runs Biome on staged files; pre-push runs typecheck + the full test suite.
• Releases use Changesets; see RELEASE.md.

Roadmap

Where OAuthLint stands, and where it is going. Want to help with any of it? See
Contributing below; false-positive reports and new rules are
especially welcome.

Shipped

• 270+ rules across eleven languages (JavaScript, TypeScript, Python, Go, C#, and more), including mobile auth (Swift/iOS, Android), a dedicated MCP server-auth pack, and framework-aware packs (ASP.NET Core, Gin/Echo/Fiber, Hono + better-auth, FastAPI, Django/Flask, Ktor, Spring Security, Laravel/Socialite, Rails/Devise/OmniAuth/Doorkeeper, NextAuth/Passport, Express/Fastify/NestJS)
• Autofix with a dry-run preview, plus dataflow (taint) analysis
• SARIF output and GitHub code scanning, a GitHub Action, and GitLab CI
• VS Code extension, also on Open VSX for Cursor, Windsurf, and similar editors
• JetBrains IDE plugin (IntelliJ, WebStorm, PyCharm, GoLand, and more) on the JetBrains Marketplace
• MCP server, so AI coding tools scan the auth code they generate, in-loop
• oauthlint probe, a live OAuth 2.1 conformance check for running MCP servers
• Shareable HTML reports
• A guide for writing your own low-false-positive rules (docs)

Now

• Deeper framework-aware coverage across the stacks already supported,
  tuned for high signal and low false positives
• Closing rule-parity gaps across the eleven supported languages

Next

• A reproducible "auth and AI" benchmark: which OAuth/JWT anti-patterns each AI
  coding tool actually produces
• More integrations: Azure and Bitbucket pipelines
• Wider autofix coverage, so more findings ship a safe one-click rewrite

Exploring

• Interprocedural dataflow for deeper taint tracking
• A hosted MCP endpoint for cloud-based agents

Contributing

The most useful contribution is telling us when a rule is wrong: open a
false-positive issue.
Want a new anti-pattern caught, or want to write the rule yourself? See
CONTRIBUTING.md. A rule is one YAML file plus a
vulnerable.ts / safe.ts fixture pair. By participating you agree to the
Code of Conduct.

License

MIT. See LICENSE. Built and maintained by Auspeo.