Firewall Testing-Framework

A framework for testing and troubleshooting firewall rulesets.

Module on pypi.org

Documentation

You can find the documentation at: ftf.oxl.app

CLI Example

For more see: ftf.oxl.app - Usage - Run

ftf-cli --firewall-system 'linux_netfilter' \
        --file-interfaces 'testdata/plugin_translate_linux_interfaces.json' \
        --file-routes 'testdata/plugin_translate_linux_routes.json' \
        --file-route-rules 'testdata/plugin_translate_linux_route-rules.json' \
        --file-ruleset 'testdata/plugin_translate_netfilter_ruleset.json' \
        --src-ip 172.17.11.5 \
        --dst-ip 2.2.2.2

> 🛈 SYSTEM: Processing packet: [172.17.11.5]:50000 =tcp=> [2.2.2.2]:443
> 🛈 ROUTER: Packet inbound-interface: docker0
> 🛈 ROUTER: Packet inbound-route: 172.17.0.0/16, scope link
> 🛈 FIREWALL: Processing Chain: Table "nat" ip4 | Chain "PREROUTING" ip4 nat (1 rules)
> 🛈 FIREWALL: > Chain PREROUTING | Rule 0 | Match => jump
> 🛈 FIREWALL: > Chain PREROUTING | Sub-Chain: DOCKER (2 rules)
> 🛈 FIREWALL: > Chain DOCKER | Rule 0 | Match => return
> 🛈 ROUTER: Packet outbound-interface: wan
> 🛈 ROUTER: Packet outbound-route: 0.0.0.0/0, gw 10.255.255.254, metric 600, scope global
> 🛈 FIREWALL: Processing Chain: Table "filter" ip4 | Chain "FORWARD" ip4 filter (5 rules)
> 🛈 FIREWALL: > Chain FORWARD | Rule 0 | Match => jump
> 🛈 FIREWALL: > Chain FORWARD | Sub-Chain: DOCKER-USER (1 rules)
> 🛈 FIREWALL: > Chain DOCKER-USER | Rule 0 | Match => return
> 🛈 FIREWALL: > Chain FORWARD | Rule 1 | Match => drop
> ✖ FIREWALL: Packet blocked by rule: Seq 1, Action: drop, Rule: #101 "TEST IP4-DADDR DROP"
>              > Matches: {'proto_l3': {'==': 'ip4'}, 'ip_daddr': {'==': ['2.2.2.2/32']}}

Roadmap

2025

Core Simulator:

• Fundamental Features
  • Routing
  • Network Interfaces
  • Firewall Tables
  • Firewall Chains
    • Sub-Chains (Jump, Goto)
  • Firewall Rules
  • System-Specific Translate-Plugins
  • System-Specific Rule-Matching
  • Destination-NAT
  • Source-NAT
• Run modes:
  • One-Shot CLI
  • Basic interactive shell
  • Automated/CI mode
    • Run multiple Test-cases from config
• Defining basic config-schema (Topology, Rulesets, Tests)
• Option to Output results to JSON
• Supporting multiple Firewalls
  • Generating Layer 3 Topology
  • Detect Firewall-chaining (one firewall routes to another one - p.e. over VPN)

Development:

• Create Plugin Templates
• Create Guide on how to develop Plugins

Firewall Support:

• Netfilter (NFTables/IPTables)
• OPNsense (Information from Config-Backup-File and runtime-infos like routes from API)

Contribute

See: CONTRIBUTING

Credits

• Thanks to the go-ftw (Web Application Firewall Testing Framework) project that inspired us to create this project

• Thanks go to @MikPisula for some inspiration on how to simulate network-traffic over a firewall (MikPisula/packet-simulator)