pfsense-api 0.1.1
Python API for monitoring PfSense firewalls.
Requires Python: >=3.10
Keywords: queue, thread, async

# PFSENSE-API
This may seem like yet another attempt to provide API like access to PfSense, a platform that has failed to provide even rudimentary API access.  The current iteration is a READ-ONLY API.  This is intended to provide running statistics and health information, not configuration updates.  At a future date I may provide some write access functionality.

## Usage Examples

    from pfsense_api import PfsenseApi
  
    \# connect and login
    pfsense = PfsenseApi(host='192.168.1.1', port=8443, username='admin', password='admin', verify_ssl=True, ca_cert_path='ca_file.pem')

    \# get all system info
    system_stats = pfsense.system_stats()

    \# get specific API data
    general = pfsense.call_api('general')
    software_system = pfsense.call_api('software_system')
    thermal = pfsense.call_api('thermal')
    disks = pfsense.call_api('disks')
    interface_stats = pfsense.call_api('interface_stats')
    openvpn_connections = pfsense.call_api('openvpn_connections')
    dhcp_leases = pfsense.call_api('dhcp_leases')
    gateways = pfsense.call_api('gateways')
    routes_v4 = pfsense.call_api('routes_v4')
    routes_v6 = pfsense.call_api('routes_v6')
    carp = pfsense.call_api('carp')
    arp = pfsense.call_api('arp')
    ndp = pfsense.call_api('ndp')
    states = pfsense.call_api('states')
    haproxy = pfsense.call_api('haproxy')

## Supported API's

Since PfSense does not provide any API interfaces, these API's are based on parsing HTML tables, JSON (in a couple of instance) or text strings.

All data returned (except for those that are already in JSON format) are returned as named tuples to make accessing the data easier.  For example:

    general = pfsense.call_api('general')
    print(eneral.memory_used_percent)
    print(uptime_days)

### General

Most values are self explanitory.  The uptime values are collective.  i.e. x days + x hours + x minutes + x seconds (this is a straight string parse).  MBUF is memory buffers used for packet routing.  CPU tick information is used to generate the % CPU usage information.

- cpu_tick_total
- cpu_tick_used
- memory_used_percent
- uptime_days
- uptime_hours
- uptime_minutes
- uptime_seconds
- state_used
- state_max
- temp_c
- datetime
- cpu_freq_current
- cpu_freq_max
- sys_load_1
- sys_load_5
- sys_load_15
- mbuf_current
- mbuf_max
- mbuf_percent
- state_percent

### Software_system

Software system returns the currently installed version, the latest available version, and a 'comparison' of the two.

- installed_version
- version
- pkg_version_compare

### Thermal

This API will return the output of any available thermal sensors on the system.

### Disks

This API will return a list of the local disks on the system with the following:

- mount
- size (in bytes)
- used (in bytes)
- usage
  - fs_type (i.e. ufs / tmpfs)
  - usage_percent

### Interface_stats

The interface stats will return a list of the interfaces with the interface level counters:

- bytes_in
- bytes_out
- collisions
- errors_in
- errors_out
- packets_in
- packets_out

### OpenVPN Connections

This API will return a list of OpenVPN servers and their associated active connections.  This also includes OpenVPN sessions initiated from the PfSense firewall to another server.

- bytes_received
- bytes_sent
- last_change
- local_address
- name
- remote_host
- service
- status
- virtual_address

### dhcp_leases

This API returns 3 tables from the DHCP status page

#### Pool Status

- failover_group
- my_state
- peer_state
- since (for my state)
- since_1 (for peer state)

#### Leases

- description
- end
- hostname
- ip_address
- mac_address

#### Lease Utilization

- capacity
- interface
- pool_end
- pool_start
- used
- utilization

### gateways

This will return a list of the gateways on the system as well as the monitoring status of the gateway.

- description
- gateway
- loss
- monitor
- name
- trr
- trrsd
- status

### routes_v4 / routes_v6

This will return the IPv4 / IPv6 routes active on the system.

- net
- gw
- flags
- uses
- mtu
- interface

### carp

This will pull the status of CARP virtual addresses on the system.

- description
- interface_and_vhid
- status
- virtual_ip_address

### arp

This will pull a list of all ARP entries on the system.

- hostname
- interface
- ip_address
- link_type
- mac_address
- status

### ndp

This will pull a list of the IPv6 neighbor discovery table on the system.

- expiration
- hostname
- interface
- ipv6_address
- mac_address

### states

This will return a list of all the states present on the system.

NOTE:  This is subject to change.  Currently it is only parsing the text on the table and may be updated to parse the fields further.

### haproxy

This will return the data pulled from the HA proxy service.

NOTE:  This works, however the returend data is difficult to interpret.  I do not have a description for each of the fields at this time.

## Class

Class: PfsenseApi

    A class designed to handle login and data querying from a PfSense firewall.

    Attributes:

        host: PfSense host address.
        port: PfSense port (default is 443).
        supported_read_apis: List of READ API's supported by this release
        verify_ssl: Boolean flag to verify SSL certificates (default is True).
        log_level: Logging level (default is INFO).
        ca_cert_path: Path to CA certificate file (default is None).

    Methods:

    __init__(self, host, username, password, port=443, log_level=INFO, verify_ssl=True, ca_cert_path=None)
        Initializes a PfsenseApi instance, establishes a session, and logs in.
    
    login(self, username, password) -> bool
        Logs into the PfSense firewall using the provided username and password.

    system_stats(self) -> dict
        Collects system stats and general info from the firewall using supported APIs and returns the data as a dictionary.

    def call_api(self, api_name:str) -> list|dict
        Call a specific API and return the data

    get_response(self, method='get', path='/index.php', data=None, headers=None, parameters=None, retry=RETRY, timeout=TIMEOUT) -> requests.Response
        Executes an HTTP request with optional parameters, data, and headers.