OAuth Guardian 🛡️

A CLI tool and npm package that audits OAuth 2.0 implementations against OWASP, NIST, and RFC specifications to identify security vulnerabilities and compliance gaps.

⚠️ Development Status

This project is in active development (Phase 2 Complete ✅).

Currently implemented:

✅ Phase 1 Complete: Full OAuth 2.0 audit system
- ✅ Project foundation and TypeScript setup
- ✅ CLI framework with commander
- ✅ Type definitions for checks, config, and reports
- ✅ HTTP client with OAuth metadata discovery
- ✅ Base check class for security audits
- ✅ 4 OAuth 2.0 security checks (PKCE, state, redirect URI, token storage)
- ✅ Audit engine with category filtering
- ✅ 3 report formats (JSON, HTML, Terminal)
- ✅ YAML configuration system with validation
✅ Phase 2 Complete: NIST 800-63B Compliance + Enhanced Reporting
- ✅ AAL1, AAL2, AAL3 compliance checks
- ✅ AAL detection and analysis
- ✅ Session management validation
- ✅ Authenticator lifecycle management
- ✅ Enhanced HTML reports with visual charts (Chart.js)
- ✅ NIST AAL compliance dashboard with metrics

Test Coverage: 349 tests (320 passing), ~77% coverage

Next: Phase 2.5 (Local Scanning Mode) or Phase 3 (OWASP Checks)

See docs/phase-1.md and docs/phase-2.md for detailed development progress.

The Problem

OAuth 2.0 implementations are frequently misconfigured, leading to critical security vulnerabilities:

Missing PKCE implementation (leaving mobile/SPA apps vulnerable)
Insecure token storage (localStorage instead of HttpOnly cookies)
Weak redirect URI validation (enabling open redirect attacks)
CSRF vulnerabilities (missing state parameter)
Non-compliant NIST authentication assurance levels
OWASP Top 10 authentication failures

Manual security audits are time-consuming, error-prone, and don't scale across teams.

The Solution

OAuth Guardian provides automated security auditing for OAuth 2.0 implementations:

🔍 Automated Testing - Test OAuth flows against industry standards
📋 Compliance Validation - Verify NIST 800-63B and OWASP compliance
📊 Actionable Reports - Generate detailed reports with remediation guidance
🔄 CI/CD Integration - Fail builds on critical security issues
🎯 Developer-Friendly - Clear error messages and fix suggestions

Features

Planned Security Checks

OAuth 2.0 / RFC Compliance

✅ PKCE (Proof Key for Code Exchange) implementation
✅ State parameter usage (CSRF protection)
✅ Redirect URI validation
✅ Secure token storage
✅ Token lifecycle management
✅ Scope validation
✅ Client authentication

NIST 800-63B Compliance

✅ Authentication Assurance Levels (AAL1/AAL2/AAL3)
✅ Session management validation
✅ Authenticator lifecycle checks

OWASP Top 10

✅ Broken access control
✅ Cryptographic failures
✅ Injection vulnerabilities
✅ Security misconfiguration
✅ Authentication failures

Report Formats

📄 JSON - Machine-readable for CI/CD, includes NIST AAL metrics
🌐 HTML - Visual reports with interactive Chart.js charts:
- Doughnut chart for check status distribution
- Bar chart for findings by severity
- NIST AAL compliance dashboard with per-level metrics
- Collapsible remediation guidance
- Print-friendly styles
📝 Markdown - Documentation-friendly (planned)
📊 CSV - Spreadsheet analysis (planned)
🔍 SARIF - IDE integration (VS Code, etc.) (planned)
💻 Terminal - Colorized CLI output with category grouping

Installation

Requirements:

Node.js >= 18.0.0
npm or yarn

Global Installation (Coming Soon)

npm install -g oauth-guardian

Development Installation

# Clone the repository
git clone https://github.com/asg5704/oauth-guardian.git
cd oauth-guardian

# Install dependencies
npm install

# Build the project
npm run build

# Run the CLI
node dist/cli.js https://auth.example.com

Usage

CLI Usage

OAuth Guardian supports two modes of operation:

Mode 1: Remote Discovery (Current)

Audits a live OAuth provider by discovering its metadata endpoints:

Basic syntax:

oauth-guardian <target-url> [options]

Mode 2: Local Repository Scan (Planned - Post-Phase 2)

Scans local code repositories for OAuth security issues without requiring a running server:

# Coming soon!
oauth-guardian scan [path] [options]

See ROADMAP.md for details on the local scanning feature.

Remote Discovery Mode

Available options:

Arguments:
  target                  Target URL to audit (e.g., https://auth.example.com)

Options:
  -V, --version           output the version number
  -c, --config <path>     Path to configuration file
  -f, --format <format>   Report format (json, html, markdown, csv, sarif)
                          (default: "terminal")
  -o, --output <path>     Output file path (stdout if not specified)
  --fail-on <severity>    Fail with exit code 1 on this severity level
                          (default: "critical")
  --checks <checks>       Comma-separated list of checks to run
  --skip-checks <checks>  Comma-separated list of checks to skip
  --nist-level <level>    Target NIST assurance level (AAL1, AAL2, AAL3)
  -v, --verbose           Enable verbose logging (default: false)
  --no-color              Disable colored output
  -h, --help              display help for command

Examples:

# Audit an OAuth server
oauth-guardian https://auth.example.com

# Generate JSON report
oauth-guardian https://auth.example.com --format json --output report.json

# Test with specific NIST level
oauth-guardian https://auth.example.com --nist-level AAL2

# Fail on high severity issues
oauth-guardian https://auth.example.com --fail-on high

# Run specific checks only
oauth-guardian https://auth.example.com --checks pkce,state,redirect-uri

# Verbose mode
oauth-guardian https://auth.example.com --verbose

Programmatic Usage

import { OAuthAuditor, ReportFormat } from "oauth-guardian";

const auditor = new OAuthAuditor({
  target: "https://auth.example.com",
  oauth: {
    pkce: true,
    state: true,
    redirectUri: true,
  },
  reporting: {
    format: ReportFormat.JSON,
    includeRemediation: true,
  },
});

const results = await auditor.run();

if (results.hasFailures("critical")) {
  console.error("Critical security issues found!");
  process.exit(1);
}

Project Status

Current Phase: Phase 1 - MVP (Week 1 Complete)

Completed:

✅ Project setup and TypeScript configuration
✅ Type definitions for checks, config, and reports
✅ HTTP client with OAuth metadata discovery
✅ Base check class with helper methods
✅ CLI framework with commander

Next Steps (Week 2):

⏳ Implement first OAuth checks (PKCE, state, redirect URI)
⏳ Create audit engine
⏳ JSON and terminal reporters

See docs/phase-1.md for detailed progress tracking.

Development

Prerequisites

Node.js >= 18.0.0
TypeScript 5.9+
npm or yarn

Setup

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode (auto-rebuild on changes)
npm run dev

# Clean build artifacts
npm run clean

Project Structure

oauth-guardian/
├── src/
│   ├── types/           # TypeScript type definitions
│   │   ├── check.ts     # Check result types
│   │   ├── config.ts    # Configuration types
│   │   └── report.ts    # Report types
│   ├── auditor/         # Main audit engine
│   │   └── http-client.ts  # HTTP client wrapper
│   ├── checks/          # Security checks
│   │   ├── base-check.ts   # Abstract base class
│   │   ├── oauth/       # OAuth 2.0 checks
│   │   ├── nist/        # NIST 800-63B checks
│   │   └── owasp/       # OWASP checks
│   ├── reporters/       # Report generators
│   ├── config/          # Configuration system
│   ├── rules/           # Custom rules engine
│   ├── cli.ts           # CLI entry point
│   └── index.ts         # Programmatic API
├── tests/
│   ├── unit/
│   ├── integration/
│   ├── fixtures/
│   └── __mocks__/
├── templates/           # Report templates
├── docs/                # Documentation
│   ├── README.md        # Main project docs
│   └── phase-1.md       # Development progress
└── examples/            # Usage examples

Scripts

npm run build     # Compile TypeScript to dist/
npm run dev       # Watch mode compilation
npm run start     # Run the CLI
npm run clean     # Remove build artifacts
npm test          # Run tests (not yet implemented)

Architecture

Type System

OAuth Guardian is built with a strict TypeScript type system:

CheckResult: Represents the outcome of a security check
CheckContext: Provides runtime context to checks
AuditorConfig: Configuration for the audit engine
Report: Structured audit report with findings

Check System

All security checks extend BaseCheck:

abstract class BaseCheck {
  abstract readonly id: string;
  abstract readonly name: string;
  abstract readonly category: CheckCategory;
  abstract execute(context: CheckContext): Promise<CheckResult>;
}

Checks have access to helper methods:

pass() - Create passing result
fail() - Create failing result with severity
warning() - Create warning result
skip() - Skip check with reason
error() - Handle check errors

HTTP Client

The HttpClient class provides:

OAuth metadata discovery (.well-known endpoints)
Request/response logging
Timeout handling
Safe JSON parsing
URL accessibility checking

Contributing

Contributions are welcome! This project is in active development.

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/amazing-check)
Make your changes
Test your changes (npm run build && node dist/cli.js <url>)
Commit your changes (git commit -m 'Add amazing security check')
Push to the branch (git push origin feature/amazing-check)
Open a Pull Request

Contribution Ideas

🔍 Implement security checks (see docs/README.md for planned checks)
📊 Add report formats (PDF, email, Slack notifications)
🧪 Write tests (unit tests, integration tests)
📝 Improve documentation
🐛 Fix bugs (check GitHub issues)
🎨 Enhance CLI UX (better output, progress indicators)

Code Style

Use TypeScript strict mode
Follow existing code patterns
Add JSDoc comments for public APIs
Include tests for new features
Update documentation

Questions?

Open an issue on GitHub
Check the project documentation

Roadmap

Phase 1: MVP (Weeks 1-3) - ✅ Complete

Week 1: Foundation & Project Setup
Week 2: Core OAuth Checks & Basic Reporting
Week 3: Configuration System & HTML Reports

Delivered: 4 OAuth checks, 3 report formats, YAML config, 118 tests

Phase 2: NIST Compliance (Weeks 4-5) - ✅ Complete

Week 4: Authentication Assurance Level checks (AAL1, AAL2, AAL3)
Week 4: Session management & authenticator lifecycle validation
Week 5: Enhanced reporting with compliance scorecards & charts

Delivered: 6 NIST checks, AAL detection, visual analytics, NIST dashboard, 349 tests total

Phase 2.5: Local Scanning Mode (Post-Phase 2, Pre-Phase 3)

New capability: Scan local code repositories without running server

Dual-mode architecture - Support both remote and local auditing
Metadata file support - Use local .well-known files
Auto-detection - Parse Node.js/TypeScript OAuth config
Multi-language parsers - Python, Java, Go support
CI/CD integration - Pre-deployment security scanning

See ROADMAP.md for detailed implementation plan.

Phase 3: OWASP & Advanced Features (Weeks 6-8)

OWASP Top 10 authentication checks
Token lifecycle validation
Custom rules engine
Additional report formats (CSV, Markdown, SARIF)

Phase 4: Testing & Polish (Weeks 9-10)

85%+ test coverage
Comprehensive documentation
CI/CD pipeline
Performance optimization

Phase 5: Launch (Weeks 11-12)

npm package publishing
GitHub repository public release
Community announcement
Documentation site

See ROADMAP.md for the complete implementation roadmap with timelines.

Real-World Expertise

This project is built by Alexander Garcia, who:

Implemented OAuth 2.0 at massive scale (200M+ authentications at VA.gov)
Hand-wrote custom OAuth 2.0 SDK with PKCE support
Built authentication infrastructure serving millions of Veterans
Deep understanding of security constraints in government systems

Resources

OAuth 2.0 Specifications

NIST Guidelines

NIST 800-63B - Digital Identity Guidelines (Authentication)

OWASP Resources

License

MIT License - See LICENSE file for details.

Contact

Maintainer: Alexander Garcia

GitHub: @asg5704

Repository: https://github.com/asg5704/oauth-guardian

Issues: https://github.com/asg5704/oauth-guardian/issues

Built with ❤️ for the security community

Report Bug · Request Feature · Documentation

Name		Name	Last commit message	Last commit date
Latest commit History 17 Commits
docs		docs
src		src
templates		templates
tests		tests
.gitignore		.gitignore
README.md		README.md
ROADMAP.md		ROADMAP.md
oauth-guardian.config.example.yml		oauth-guardian.config.example.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

asg5704/oauth-guardian

Folders and files

Latest commit

History

Repository files navigation

OAuth Guardian 🛡️

⚠️ Development Status

Table of Contents

The Problem

The Solution

Features

Planned Security Checks

Report Formats

Installation

Global Installation (Coming Soon)

Development Installation

Usage

CLI Usage

Mode 1: Remote Discovery (Current)

Mode 2: Local Repository Scan (Planned - Post-Phase 2)

Remote Discovery Mode

Programmatic Usage

Project Status

Current Phase: Phase 1 - MVP (Week 1 Complete)

Development

Prerequisites

Setup

Project Structure

Scripts

Architecture

Type System

Check System

HTTP Client

Contributing

How to Contribute

Contribution Ideas

Code Style

Questions?

Roadmap

Phase 1: MVP (Weeks 1-3) - ✅ Complete

Phase 2: NIST Compliance (Weeks 4-5) - ✅ Complete

Phase 2.5: Local Scanning Mode (Post-Phase 2, Pre-Phase 3)

Phase 3: OWASP & Advanced Features (Weeks 6-8)

Phase 4: Testing & Polish (Weeks 9-10)

Phase 5: Launch (Weeks 11-12)

Real-World Expertise

Resources

OAuth 2.0 Specifications

NIST Guidelines

OWASP Resources

License

Contact

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 2

Uh oh!

Languages

Packages