Skip to content

THREAT_MODEL.md

Latest commit

 

History

History
94 lines (77 loc) · 3.5 KB

THREAT_MODEL.md

File metadata and controls

94 lines (77 loc) · 3.5 KB
Raw

Threat Model Outline for oauth2 Ruby Gem

1. Overview

This document outlines the threat model for the oauth2 Ruby gem, which implements OAuth 2.0, 2.1, and OIDC Core protocols. The gem is used to facilitate secure authorization and authentication in Ruby applications.

2. Assets to Protect

  • OAuth access tokens, refresh tokens, and ID tokens
  • User credentials (if handled)
  • Client secrets and application credentials
  • Sensitive user data accessed via OAuth
  • Private keys and certificates (for signing/verifying tokens)

3. Potential Threat Actors

  • External attackers (internet-based)
  • Malicious OAuth clients or resource servers
  • Insiders (developers, maintainers)
  • Compromised dependencies

4. Attack Surfaces

  • OAuth endpoints (authorization, token, revocation, introspection)
  • HTTP request/response handling
  • Token storage and management
  • Configuration files and environment variables
  • Dependency supply chain

5. Threats and Mitigations

5.1 Token Leakage

  • Threat: Tokens exposed via logs, URLs, or insecure storage
  • Mitigations:
    • Avoid logging sensitive tokens
    • Use secure storage mechanisms
    • Never expose tokens in URLs

5.2 Token Replay and Forgery

  • Threat: Attackers reuse or forge tokens
  • Mitigations:
    • Validate token signatures and claims
    • Use short-lived tokens and refresh tokens
    • Implement token revocation

5.3 Insecure Communication

  • Threat: Data intercepted via MITM attacks
  • Mitigations:
    • Enforce HTTPS for all communications
    • Validate SSL/TLS certificates

5.4 Client Secret Exposure

  • Threat: Client secrets leaked in code or version control
  • Mitigations:
    • Store secrets in environment variables or secure vaults
    • Never commit secrets to source control

5.5 Dependency Vulnerabilities

  • Threat: Vulnerabilities in third-party libraries
  • Mitigations:
    • Regularly update dependencies
    • Use tools like bundler-audit for vulnerability scanning

5.6 Improper Input Validation

  • Threat: Injection attacks via untrusted input
  • Mitigations:
    • Validate and sanitize all inputs
    • Use parameterized queries and safe APIs

5.7 Request-Target Trust Boundary Expansion

  • Threat: Applications may pass untrusted or insufficiently validated absolute URLs into request paths that can carry OAuth credentials or authenticated state.
  • Risk: This can expand trust boundaries, contributing to token leakage, authenticated requests to unintended hosts, or SSRF-like pivoting in the surrounding application.
  • Mitigations:
    • Prefer relative paths where practical
    • Do not pass untrusted absolute URLs into token-bearing clients
    • Validate or allowlist outbound request targets at the application layer
    • Treat request-target validation as a separate concern from log redaction and token storage

5.8 Insufficient Logging and Monitoring

  • Threat: Attacks go undetected
  • Mitigations:
    • Log security-relevant events (without sensitive data)
    • Monitor for suspicious activity

6. Assumptions

  • The gem is used in a secure environment with up-to-date Ruby and dependencies
  • End-users are responsible for secure configuration and deployment

7. Out of Scope

  • Security of external OAuth providers
  • Application-level business logic

8. References

This outline should be reviewed and updated regularly as the project evolves.