SkillAgentSearch skills...

PyFRC2G

Python scripts to convert PfSense and OPNSense firewall rules into a graphical view of the flows.

GenerateConvertImprove

Install / Use

/learn @olivierb46/PyFRC2G
About this skill

Quality Score

0/100

Supported Platforms

Universal

README

PyFRC2G - Unified Firewall Rules to Graph Converter

Unified Python package to convert pfSense and OPNSense firewall rules into graphical flow diagrams.

pfSense Example OPNSense Example

Quick start: Configure pyfrc2g/config.py then run pyfrc2g or python -m pyfrc2g (API mode), or run pyfrc2g --backup config.xml to use an XML backup without API config.

👋 Overview

PyFRC2G was designed to meet two main objectives:

  • Visual Documentation: Provide a global graphical view of firewall rules (a picture is worth a thousand words)
  • Compliance Evidence: Provide evidence to meet IT security requirements defined in various compliance frameworks

⚡ Features

Core Features

  • Two Input Modes: Fetch rules via API (pfSense/OPNSense) or read from XML backup (config.xml)
  • Unified Support: Single package for both pfSense and OPNSense
  • Automatic Interface Detection: Auto-detects all available interfaces for OPNSense
  • API-Based Alias Mapping: Retrieves all aliases from firewall API or from the backup XML
  • Per-Interface Output: Generates separate CSV and PDF files for each interface
  • Smart Change Detection: Only regenerates graphs when rules have changed (MD5 comparison)
  • Configuration Check: Validates pyfrc2g/config.py before API mode (optional bypass with --skip-config-check)
  • Modular Architecture: Clean, maintainable, and extensible codebase

Technical Features

  • Graphical Flows: Generates visual flow diagrams using Graphviz
  • PDF Generation: Produces A4 PDF files with one page per interface
  • Color Coding:
    • 🟢 Green for PASS rules
    • 🔴 Red for BLOCK rules
    • 🟡 Yellow for disabled rules
  • Network Mapping: Distinguishes between VLANs/networks and destination hosts
  • Comprehensive Coverage: Handles floating rules, disabled rules, and all interface types
  • CISO Assistant Integration: Optional automatic upload of PDFs to CISO Assistant as evidence revisions

📋 Prerequisites

Python Requirements

  • Python 3.7 or higher
  • Required packages (see Installation)

System Requirements

  • Graphviz: Must be installed on your system
    • Windows: Download from Graphviz website
    • Linux: sudo apt-get install graphviz (Debian/Ubuntu) or sudo yum install graphviz (RHEL/CentOS)
    • macOS: brew install graphviz

Firewall API Setup

pfSense

  1. Install pfSense REST API Package: pfSense REST API Documentation
  2. Configure the listening interface(s) on pfSense
  3. Generate an API key for authentication

OPNSense

  1. Create API credentials in OPNSense:
    • Go to System > Access > Users
    • Create or edit a user
    • Generate API key and secret in API Keys section

💾 Installation

Option 1: Install as Package (Recommended)

# Clone the repository
git clone https://github.com/olivierb46/PyFRC2G.git
cd PyFRC2G

# Install setuptools (required by setup.py)
pip install setuptools

# Install in development mode
pip install -e .

# Or install directly
pip install .

Option 2: Direct Usage

# Install dependencies
pip install -r requirements.txt

# Use the script directly
pyfrc2g

⚙️ Configuration

Configuration is required only for API mode. When using --backup, no API config is needed.

1. Edit Configuration File

Edit pyfrc2g/config.py to configure your gateway:

For pfSense:

GATEWAY_TYPE = "pfsense"

PFS_BASE_URL = "https://pfs01.domain.lan"
PFS_TOKEN = "YOUR_API_KEY_GENERATED_WITH_PFSENSE_REST_API"

GATEWAY_NAME = "PFS01"

For OPNSense:

GATEWAY_TYPE = "opnsense"

# OPNSense Configuration
OPNS_BASE_URL = "https://opnsense.domain.lan"
OPNS_KEY = "YOUR_API_KEY"
OPNS_SECRET = "YOUR_API_SECRET"

# Option 1: Auto-detection (recommended)
INTERFACES = []  # Leave empty for automatic detection

# Option 2: Manual specification
INTERFACES = ["wan", "lan", "opt1", "opt2"]

GATEWAY_NAME = "OPNS01"  # Display name for gateway (used in labels)

2. Configuration Check (API Mode)

Before running in API mode, the tool checks that PFS_BASE_URL/PFS_TOKEN (pfSense) or OPNS_BASE_URL/OPNS_KEY/OPNS_SECRET (OPNSense) are not left as placeholders. If the config is invalid, the script exits with instructions. Use --skip-config-check to bypass (e.g. in scripts).

3. CISO Assistant Integration (Optional)

If you want to automatically upload generated PDFs to CISO Assistant as evidence revisions, configure the following in pyfrc2g/config.py:

# CISO Assistant Configuration
CISO_URL = "https://ciso-assistant.example.com"
CISO_TOKEN = "YOUR_CISO_ASSISTANT_API_TOKEN"
CISO_EVIDENCE_PATH = f"{CISO_URL}/api/evidence-revisions/"
CISO_FORLDER_ID = "<CISO_FOLDER_ID>"  # Folder ID from CISO Assistant to which the evidence is linked.
CISO_EVIDENCE_ID = "<CISO_EVIDENCE_ID>"  # Evidence ID from CISO Assistant.

Note: Leave these as default values (<CISO_ASSISTANT_ADDRESS>, etc.) to disable CISO Assistant integration.

4. Aliases (API Mode)

In API mode, the package automatically retrieves all aliases from the firewall API:

  • Interface names and descriptions
  • Network aliases
  • Address aliases
  • Port aliases

No manual alias mapping is required. In backup mode, aliases are read from the XML file.

🚀 Usage

Command-Line Options (argparse)

| Option | Short | Description | |--------|-------|-------------| | --api | -a | Fetch rules from firewall API (default if no mode) | | --backup FILE | -b | Read rules from XML backup (pfSense or OPNSense config.xml) | | --gateway-name NAME | -g | Gateway display name (for backup or when not using API) | | --skip-config-check | | Skip configuration check before API mode | | --debug | -d | Enable debug logging | | --verbose | -v | Verbose output (same as --debug) |

Basic Usage

Mode API (default)

Configure pyfrc2g/config.py, then run:

pyfrc2g
# or explicitly
pyfrc2g --api

Before running, a configuration check ensures that API URL and credentials are set. If the config is still using placeholders, the tool exits with a clear message. Use --backup to work without API config, or --skip-config-check to bypass (not recommended).

Mode XML Backup

Use a pfSense or OPNSense backup file (e.g. from Diagnostics > Backup & Restore). No API config needed.

pyfrc2g --backup config-backup.xml

# Optional: set gateway name (otherwise derived from filename)
pyfrc2g --backup config-backup.xml --gateway-name my-firewall

The tool detects automatically whether the backup is pfSense or OPNSense and parses rules and aliases from the XML. PDFs are generated the same way as in API mode.

Other Examples

# Debug / verbose
pyfrc2g --api --debug
pyfrc2g --backup config.xml --verbose

# Bypass config check (e.g. in scripts)
pyfrc2g --api --skip-config-check

As an Installed Package:

pyfrc2g
pyfrc2g --backup config.xml

As a Python Module:

from pyfrc2g import Config, APIClient, GraphGenerator
from pyfrc2g.main import main

# Option 1: Use the main function
main()

# Option 2: Use components directly
config = Config()
api_client = APIClient(config)
graph_generator = GraphGenerator(config)

# Fetch aliases
api_client.fetch_aliases()

# Fetch rules
rules = api_client.fetch_rules()

# Generate graphs
graph_generator.generate_graphs(csv_path, output_dir)

What the Script Does

Mode API

  1. Runs a configuration check (unless --skip-config-check or --backup is used)
  2. Connects to your gateway (pfSense or OPNSense)
  3. Fetches all aliases and firewall rules from the API
  4. Auto-detects interfaces (for OPNSense, if not specified)

Mode Backup

  1. Parses the XML backup (pfSense or OPNSense), extracts rules and aliases
  2. No API call; gateway type and name come from the file or --gateway-name

Common steps 5. Generates a temporary CSV file with all rules 6. Compares with previous version (MD5 checksum) 7. If changes detected, generates graphs and PDFs (Graphviz + ReportLab) 8. Uploads PDFs to CISO Assistant (if configured)

Generated Files

The script generates files in results/<GATEWAY_NAME>/:

Global Files:

  • <GATEWAY_NAME>_FLOW_MATRIX.pdf - PDF with all interfaces (one page per interface)

Per-Interface Files:

  • <GATEWAY_NAME>_<interface>_flows.csv - CSV file with rules for specific interface
  • <GATEWAY_NAME>_<interface>_FLOW_MATRIX.pdf - PDF with graphs for specific interface

Tracking:

  • md5sum.txt - MD5 hash of last generated CSV (for change detection)

Example Output Structure

results/PFS01/
├── PFS01_FLOW_MATRIX.pdf              # Global PDF (all interfaces)
├── PFS01_wan_FLOW_MATRIX.pdf          # WAN interface PDF
├── PFS01_wan_flows.csv                # WAN interface CSV
├── PFS01_lan_FLOW_MATRIX.pdf          # LAN interface PDF
├── PFS01_lan_flows.csv                # LAN interface CSV
└── PFS01_opt1_FLOW_MATRIX.pdf         # OPT1 interface PDF

📊 Output Format

CSV Columns

The temporary and per-interface CSV files use the same columns for both pfSense and OPNsense:

| Column | Description | |------------|-------------| | SOURCE | Source network or address (mapped from API aliases when available) | | GATEWAY | Gateway name and interface(s), e.g. OPNS01/wan,lan or OPNS01/Floating-rules | | ACTION | Pass, block, reject (mapped to display value) | | PROTOCOL | IP layer and protocol: IPv4 tcp, IPv6 udp, IPv4+IPv6 Any, etc. Empty protocol is shown as Any. | | PORT | Destination port or range | | DESTINATION| Destination network or address | | COMMENT | Rule description | | DISABLED | True / False | | FLOATING | True for floating rules | | RULE

olivierb46

View profile

View on GitHub
GitHub Stars427
CategoryDevelopment
Updated2d ago
Forks30
olivierb46/PyFRC2G

Languages

Python

Security Score

100/100

Audited on Mar 24, 2026

No findings