Skip to content

feat(pfsense_rule): add state tracking options#253

Open
adriangalilea wants to merge 1 commit intopfsensible:masterfrom
adriangalilea:feat/rule-rate-limit-options
Open

feat(pfsense_rule): add state tracking options#253
adriangalilea wants to merge 1 commit intopfsensible:masterfrom
adriangalilea:feat/rule-rate-limit-options

Conversation

@adriangalilea
Copy link
Copy Markdown

Summary

Adds support for PF state tracking advanced options to the pfsense_rule module. These fields were previously listed in RULE_UNMANAGED_ELEMENTS (preserved but not configurable). This PR promotes them to fully managed parameters.

New parameters

Parameter XML element Description
max_src_conn max-src-conn Max established connections per source host
max_src_states max-src-states Max state entries per source host
max_src_nodes max-src-nodes Max unique source hosts
max_src_conn_rate max-src-conn-rate Max new connections per time interval
max_src_conn_rates max-src-conn-rates Time interval (seconds) for max_src_conn_rate
statetimeout statetimeout State timeout in seconds

Example usage

- name: Rate-limit inbound connections
  pfsense_rule:
    name: 'Rate-limited inbound'
    action: pass
    interface: wan
    floating: true
    direction: in
    quick: true
    protocol: tcp
    source: any
    destination: my_servers
    destination_port: 21841
    max_src_conn: 3
    max_src_states: 3
    max_src_conn_rate: 3
    max_src_conn_rates: 60
    state: present

Validation

  • State tracking options only work on pass rules (pfSense requirement)
  • max_src_conn and max_src_conn_rate require TCP protocol
  • max_src_conn_rate and max_src_conn_rates must be set together

Motivation

The pfSense REST API package (pfSense-pkg-RESTAPI) does not expose these fields either, making Ansible via pfsensible the only programmatic way to manage PF rate-limiting rules. These options are critical for protecting services from connection floods (SYN floods, DDoS) without manual Web UI configuration.

Changes

  • plugins/module_utils/rule.py: Added 6 params to RULE_ARGUMENT_SPEC, XML mapping in _params_to_obj, validation in _validate_params, removal handling, and logging
  • plugins/modules/pfsense_rule.py: Added documentation and example for new params
  • tests/unit/plugins/modules/test_pfsense_rule_create.py: Added 8 tests covering creation, validation, and error cases

…_states, etc.)

Add support for PF state tracking advanced options to the pfsense_rule
module. These were previously listed in RULE_UNMANAGED_ELEMENTS and
are now fully managed parameters:

- max_src_conn: max established connections per source host
- max_src_states: max state entries per source host
- max_src_nodes: max unique source hosts
- max_src_conn_rate: max new connections per time interval
- max_src_conn_rates: time interval (seconds) for max_src_conn_rate
- statetimeout: state timeout in seconds

These map to the pfSense XML config elements max-src-conn,
max-src-states, max-src-nodes, max-src-conn-rate, max-src-conn-rates,
and statetimeout respectively.

Validation ensures:
- State tracking options only apply to pass rules
- max_src_conn/max_src_conn_rate require TCP protocol
- max_src_conn_rate and max_src_conn_rates must be set together
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant