Skip to content

v2.7.0

Choose a tag to compare

View all tags
@sean-e-dietrich sean-e-dietrich released this 25 Jan 22:16
v2.7.0
219cd3a
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

Added

New Plugin Configuration Format (#48)

Introduced a new canonical plugins: array format as the preferred way to configure firewall plugins. This format provides explicit control over plugin behavior and supports multiple instances of the same plugin class.

New Format:

plugins:
  - plugin: "Kanopi\\Firewall\\Plugins\\IpAddress"
    response: allow      # 'allow' (bypass) or 'block'
    weight: -200         # Execution order (lower runs first)
    enable: true
    config:
      - 127.0.0.1

  - plugin: "Kanopi\\Firewall\\Plugins\\IpAddress"
    response: block
    weight: -100
    enable: true
    config:
      - 192.168.1.100

Key Features:

  • Same plugin class can be used multiple times with different configurations
  • Explicit response field (allow or block) indicates plugin behavior
  • weight field controls execution order (replaces priority in legacy format)
  • plugins: arrays from multiple config files are appended (not replaced) during merging
  • Full backward compatibility with legacy bypass:/block: format

New Components:

  • PluginConfigNormalizer - Converts legacy format to canonical format
  • PluginManager::createFromPluginsArray() - Factory method for new format

Field Mapping (Legacy → New):

Legacy New Format
bypass: section response: allow
block: section response: block
priority weight

Firewall Mode Configuration (#43)

Added a new mode setting in global configuration to control firewall behavior:

global:
  mode: block  # Options: block, log, exception, disabled
Mode Evaluates? Writes Storage? Terminates?
block Yes Yes Yes (sends HTTP response)
log Yes No No (logs warning only)
exception Yes Yes No (throws FirewallBlockedException)
disabled No No No (skips all evaluation)
  • block - Default production behavior
  • log - Dry-run/audit mode for testing rules without blocking
  • exception - Throws catchable exception for framework integration
  • disabled - Completely bypasses firewall evaluation

Extended Logging (#42)

Enhanced logging throughout the firewall with more detailed context:

  • Plugin evaluation results with timing information
  • Storage operations (block, unblock, offense tracking)
  • Configuration loading and merging details
  • Request evaluation flow with decision points
  • Debug-level logs for troubleshooting

PHP 8.5 Testing Support (#47)

Added PHP 8.5 to the CI test matrix to ensure forward compatibility.

Changed

Exception Handling Updates (#46)

Updated exception handling to work with new GeoIP2 library exceptions:

  • Properly catches and handles AddressNotFoundException
  • Improved error messages for GeoIP lookup failures
  • Better fallback behavior when IP cannot be geolocated

Fixed

  • Fixed exception types for GeoIP2 library compatibility
  • Improved error handling in GeoLocation and ASN plugins

Documentation

  • Comprehensive README updates documenting new plugins: format
  • Updated CLAUDE.md with new architecture details
  • New examples in example/config.yml showing both formats
  • Updated example/README.md with new format examples

[2.6.0] - 2024-12-XX

Added

  • New {presets_dir} token for referencing built-in preset configurations
  • Path::getPresetsDirectory() method for centralized preset path access
  • Centralized token normalization in TokenSubstitute::normalizeInclude()

Changed

  • Consolidated token substitution logic for better maintainability
  • Removed duplicate normalization code from ConfigLoader

[2.5.0] - 2024-XX-XX

Added

  • Remote configuration file support with local caching
  • KANOPI_FIREWALL_CACHE_DIR, KANOPI_FIREWALL_CACHE_TTL, KANOPI_FIREWALL_CACHE_TIMEOUT constants
  • $_SERVER fallback for environment variable resolution

Changed

  • Environment variables now check both getenv() and $_SERVER

Upgrade Guide: 2.6.x → 2.7.0

Plugin Configuration

The new plugins: array format is optional but recommended. Your existing bypass: and block: configurations will continue to work without modification.

To migrate to the new format:

  1. Replace bypass: section entries with response: allow plugins
  2. Replace block: section entries with response: block plugins
  3. Rename priority to weight
  4. Add explicit plugin: key with the class name

Before (Legacy):

bypass:
  "Kanopi\\Firewall\\Plugins\\IpAddress":
    priority: -200
    enable: true
    config:
      - 127.0.0.1

block:
  "Kanopi\\Firewall\\Plugins\\IpAddress":
    priority: -100
    enable: true
    config:
      - 192.168.1.100

After (New):

plugins:
  - plugin: "Kanopi\\Firewall\\Plugins\\IpAddress"
    response: allow
    weight: -200
    enable: true
    config:
      - 127.0.0.1

  - plugin: "Kanopi\\Firewall\\Plugins\\IpAddress"
    response: block
    weight: -100
    enable: true
    config:
      - 192.168.1.100

Firewall Mode

If you were using custom logic to control firewall behavior, consider using the new mode setting:

global:
  mode: log  # For dry-run testing

Breaking Changes

None. This release maintains full backward compatibility.

Full Changelog: v2.6.0...v2.7.0

Assets 7
Loading