Skip to content

CHANGELOG.md

Latest commit

 

History

History
258 lines (213 loc) · 9.98 KB

CHANGELOG.md

File metadata and controls

258 lines (213 loc) · 9.98 KB
Raw

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Fixed - Code Quality

  • Code Quality Improvements: Cleaned up unused imports and variables
    • Removed unused STATUS imports from reporter.py and cross_origin_validator.py
    • Moved sys import to top of analyzer.py (Python best practice)
    • Removed unused local variables in set_cookie.py and permissions_policy.py
    • Added nosec comment for false positive bandit warning in config.py
    • Zero pyflakes warnings, zero bandit issues
    • All 582 tests passing, 97% coverage maintained

Added - Analyzer Enhancements

  • Cache-Control Analyzer: Enhanced validation with 3 new security features (Sprint 3)

    • Directive conflict detection
      • Detects public + private (mutually exclusive)
      • Detects no-store + max-age (max-age redundant)
      • Detects no-store + no-cache (no-cache redundant)
      • Detects private + s-maxage (s-maxage inapplicable)
      • MEDIUM severity conflicts trigger BAD status
    • must-revalidate validation
      • Warns when max-age > 1 day without must-revalidate or immutable
      • Prevents serving very stale content when origin is unreachable
      • LOW severity recommendations for long cache durations
    • stale-while-revalidate and stale-if-error support
      • Parses and validates modern caching directives
      • Enables graceful degradation and performance optimization
    • 19 comprehensive tests covering all new features
    • Smart severity handling: MEDIUM → BAD status, LOW → recommendations only
    • 100% backward compatibility maintained (all 43 existing tests pass)

  • Set-Cookie Analyzer: Enhanced validation with 4 new security features (Sprint 2)

    • Cookie prefix validation (__Secure-, __Host-) per RFC 6265bis
      • __Secure- prefix requires Secure attribute
      • __Host- prefix requires Secure attribute, no Domain, Path=/
    • Domain/Path scope analysis
      • Detects overly broad domains (e.g., "com", "co.uk")
      • Warns about Domain with leading dot (applies to subdomains)
      • Flags Path=/ on sensitive cookies (exposed to entire site)
    • Sensitive cookie pattern detection
      • Detects session/auth/CSRF cookies by name pattern (14 patterns)
      • Flags sensitive cookies missing BOTH Secure AND HttpOnly
      • Patterns: session, auth, token, jwt, csrf, phpsessid, etc.
    • SameSite=None frequency warnings
      • Warns when ≥50% cookies use SameSite=None (third-party tracking risk)
      • Privacy-focused recommendation for cross-site cookie usage
    • 23 comprehensive tests covering all new features
    • Smart severity handling: HIGH → BAD status, LOW → recommendations only
    • 100% backward compatibility maintained (all 517 existing tests pass)

  • CSP Analyzer: Advanced bypass detection system with 12 common attack patterns

    • JSONP endpoint detection (Google APIs, AngularJS CDN, AWS S3, Cloudflare, etc.)
    • Angular/AngularJS template injection vulnerability detection
    • Data URI bypass detection in script-src
    • User-uploaded content domain detection (AWS S3 buckets)
    • Missing base-uri validation (prevents base tag injection)
    • Missing object-src validation (prevents Flash/plugin bypass)
    • script-src 'self' with file upload capability warnings
    • unsafe-hashes context validation
    • script-src-elem without script-src detection
    • Dangling markup injection detection
    • Smart severity handling: HIGH severity bypasses trigger BAD status, LOW/MEDIUM provide recommendations
    • 23 comprehensive tests for bypass detection
    • Enhanced documentation with detailed attack scenarios for all 10+ bypass patterns

Added

  • Automatic retry logic with exponential backoff for transient failures (429, 503, timeouts)
  • Verbose and quiet modes (-v/--verbose, -q/--quiet) for better output control
  • JSON schema versioning for backwards compatibility tracking
  • Enhanced SSRF protection with intermediate redirect validation (not just final destination)
  • Robust analyzer validation - runtime validation of all analyzer return values
  • Maximum timeout validation - prevents extremely long hangs (300s max)
  • CSP DoS protection - 10KB size limit to prevent memory exhaustion attacks
  • GitHub Actions CI/CD pipeline for automated testing across Python 3.8-3.12
  • Pre-commit hooks configuration with black, isort, flake8, mypy, and bandit
  • Comprehensive security policy (SECURITY.md) with vulnerability disclosure process
  • Contributing guidelines (CONTRIBUTING.md) for external contributors
  • Development tool configurations in pyproject.toml (black, isort, mypy, bandit, coverage)
  • 18 new edge case tests (IPv6 URLs, malformed CSP, timeout boundaries, schema version)

Changed

  • CSP parser hardening - gracefully handles empty directives, duplicates, and malformed input
  • Exception handling improvements - specific exception types instead of broad catches
  • HTTP error handling - preserves exit code 3 even when analysis fails during error
  • Enhanced pyproject.toml with dev dependencies and tool configurations
  • Updated test suite from 478 to 494 tests (97% coverage)
  • fetch_headers_with_retry() now used by default instead of fetch_headers()

Fixed

  • Set-Cookie exception handling now catches specific exceptions only
  • CSP parser no longer crashes on extremely long policies (raises ValueError instead)
  • Timeout parameter now properly validated with upper bound
  • Mock objects in tests properly handled by redirect validation code

[1.0.0] - 2024-12-04

Added

  • Initial release of Security Header Analyzer
  • Core CLI tool for analyzing HTTP security headers
  • Support for 9 security headers:
    • Strict-Transport-Security (HSTS)
    • X-Frame-Options
    • X-Content-Type-Options
    • Content-Security-Policy (CSP)
    • Referrer-Policy
    • Permissions-Policy
    • Cross-Origin-Embedder-Policy (COEP)
    • Cross-Origin-Opener-Policy (COOP)
    • Cross-Origin-Resource-Policy (CORP)

Security Features

  • SSRF (Server-Side Request Forgery) protection
    • Private IP address blocking (RFC 1918, localhost)
    • IPv6 private range blocking
    • Redirect destination validation
    • DNS rebinding attack mitigation
  • SSL/TLS certificate validation
  • Configurable timeouts and redirect limits

Header Analysis Features

  • HSTS Analysis:

    • max-age validation (minimum 10886400 seconds / 126 days)
    • includeSubDomains directive checking
    • preload directive detection

  • X-Frame-Options Analysis:

    • DENY/SAMEORIGIN validation
    • Deprecated ALLOW-FROM detection

  • Content-Security-Policy Analysis:

    • unsafe-inline/unsafe-eval detection
    • Wildcard source detection
    • Nonce and hash support validation
    • strict-dynamic support detection

  • Referrer-Policy Analysis:

    • Policy strictness evaluation
    • Best practice recommendations

  • Permissions-Policy Analysis:

    • Feature directive parsing
    • Allowlist validation

  • Cross-Origin Headers:

    • COEP: require-corp validation
    • COOP: isolation level checking
    • CORP: resource sharing policy validation

CLI Features

  • Text and JSON output formats
  • Configurable timeout (default: 10 seconds)
  • Redirect control (default: follow up to 5)
  • Custom User-Agent support
  • Debug mode with detailed error information
  • Color-coded severity levels in text output

Testing

  • 291 comprehensive unit and integration tests
  • 96% code coverage
  • Mock-based testing (no external network calls)
  • Edge case coverage for all analyzers
  • Test fixtures for reusable test data

Documentation

  • Comprehensive README with installation and usage instructions
  • Security considerations and SSRF limitations documented
  • Responsible use guidelines
  • Example outputs for both text and JSON formats
  • Best practices documentation for each security header
  • Project structure documentation

Architecture

  • Modular design with clear separation of concerns:
    • fetcher.py: HTTP header fetching with SSRF protection
    • analyzer.py: Analysis orchestration
    • reporter.py: Report generation (text/JSON)
    • config.py: Shared configuration and exceptions
    • analyzers/: Individual header analyzer modules
  • Registry pattern for extensible analyzer system
  • Custom exception hierarchy for error handling
  • Type hints throughout codebase

Dependencies

  • Python 3.8+ required
  • Single production dependency: requests>=2.28.0

Development History (Pre-1.0.0)

  • Initial project structure and analyzer framework
  • Implemented core analyzers (HSTS, X-Frame-Options, X-Content-Type-Options, CSP, Referrer-Policy)
  • Added advanced CSP analysis (nonces, hashes, strict-dynamic)
  • Implemented cross-origin header analyzers (COEP, COOP, CORP, Permissions-Policy)
  • Enhanced fetcher with DNS rebinding protection
  • Comprehensive test suite development
  • Edge case testing for all security headers
  • CLI workflow and integration tests
  • Configuration refactoring for better maintainability

Version History Summary

Security Updates

No security vulnerabilities fixed in this release.

Breaking Changes

None - Initial release.

Deprecations

None - Initial release.

Known Issues

  • TOCTOU vulnerability in SSRF protection (DNS can change between validation and request)
  • DNS resolution timeout is OS-controlled (~30 seconds)
  • No explicit timeout for socket.getaddrinfo()

See SECURITY.md for mitigation strategies.

Release Notes Format

For future releases, we follow this format:

[Version] - YYYY-MM-DD

Added

  • New features

Changed

  • Changes to existing functionality

Deprecated

  • Features marked for removal

Removed

  • Removed features

Fixed

  • Bug fixes

Security

  • Security fixes (disclosed responsibly)

Maintainers: When releasing a new version:

  1. Update version in sha/__init__.py
  2. Update version in pyproject.toml
  3. Move unreleased changes to new version section
  4. Add release date
  5. Create git tag: git tag -a v1.0.0 -m "Release version 1.0.0"
  6. Push tag: git push origin v1.0.0