| Name | pfsense-api JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | |
| Summary | Python API for monitoring PfSense firewalls. |
| upload_time | 2024-02-04 03:17:04 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.7 |
| license | |
| keywords |
queue
thread
async
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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.
Raw data
{
"_id": null,
"home_page": "",
"name": "pfsense-api",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "queue,thread,async",
"author": "",
"author_email": "Thomas Dunteman <git@learningtopi.com>",
"download_url": "https://files.pythonhosted.org/packages/fb/c8/de11c0de1c61afb69502ea7f36e2bfbb39cd169a8bc8bf685ef97c43aca3/pfsense_api-0.1.0.tar.gz",
"platform": null,
"description": "# PFSENSE-API\nThis 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.\n\n## Usage Examples\n\n from pfsense_api import PfsenseApi\n \n \\# connect and login\n pfsense = PfsenseApi(host='192.168.1.1', port=8443, username='admin', password='admin', verify_ssl=True, ca_cert_path='ca_file.pem')\n\n \\# get all system info\n system_stats = pfsense.system_stats()\n\n \\# get specific API data\n general = pfsense.call_api('general')\n software_system = pfsense.call_api('software_system')\n thermal = pfsense.call_api('thermal')\n disks = pfsense.call_api('disks')\n interface_stats = pfsense.call_api('interface_stats')\n openvpn_connections = pfsense.call_api('openvpn_connections')\n dhcp_leases = pfsense.call_api('dhcp_leases')\n gateways = pfsense.call_api('gateways')\n routes_v4 = pfsense.call_api('routes_v4')\n routes_v6 = pfsense.call_api('routes_v6')\n carp = pfsense.call_api('carp')\n arp = pfsense.call_api('arp')\n ndp = pfsense.call_api('ndp')\n states = pfsense.call_api('states')\n haproxy = pfsense.call_api('haproxy')\n\n## Supported API's\n\nSince 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.\n\nAll data returned (except for those that are already in JSON format) are returned as named tuples to make accessing the data easier. For example:\n\n general = pfsense.call_api('general')\n print(eneral.memory_used_percent)\n print(uptime_days)\n\n### General\n\nMost 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.\n\n- cpu_tick_total\n- cpu_tick_used\n- memory_used_percent\n- uptime_days\n- uptime_hours\n- uptime_minutes\n- uptime_seconds\n- state_used\n- state_max\n- temp_c\n- datetime\n- cpu_freq_current\n- cpu_freq_max\n- sys_load_1\n- sys_load_5\n- sys_load_15\n- mbuf_current\n- mbuf_max\n- mbuf_percent\n- state_percent\n\n### Software_system\n\nSoftware system returns the currently installed version, the latest available version, and a 'comparison' of the two.\n\n- installed_version\n- version\n- pkg_version_compare\n\n### Thermal\n\nThis API will return the output of any available thermal sensors on the system.\n\n### Disks\n\nThis API will return a list of the local disks on the system with the following:\n\n- mount\n- size (in bytes)\n- used (in bytes)\n- usage\n - fs_type (i.e. ufs / tmpfs)\n - usage_percent\n\n### Interface_stats\n\nThe interface stats will return a list of the interfaces with the interface level counters:\n\n- bytes_in\n- bytes_out\n- collisions\n- errors_in\n- errors_out\n- packets_in\n- packets_out\n\n### OpenVPN Connections\n\nThis 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.\n\n- bytes_received\n- bytes_sent\n- last_change\n- local_address\n- name\n- remote_host\n- service\n- status\n- virtual_address\n\n### dhcp_leases\n\nThis API returns 3 tables from the DHCP status page\n\n#### Pool Status\n\n- failover_group\n- my_state\n- peer_state\n- since (for my state)\n- since_1 (for peer state)\n\n#### Leases\n\n- description\n- end\n- hostname\n- ip_address\n- mac_address\n\n#### Lease Utilization\n\n- capacity\n- interface\n- pool_end\n- pool_start\n- used\n- utilization\n\n### gateways\n\nThis will return a list of the gateways on the system as well as the monitoring status of the gateway.\n\n- description\n- gateway\n- loss\n- monitor\n- name\n- trr\n- trrsd\n- status\n\n### routes_v4 / routes_v6\n\nThis will return the IPv4 / IPv6 routes active on the system.\n\n- net\n- gw\n- flags\n- uses\n- mtu\n- interface\n\n### carp\n\nThis will pull the status of CARP virtual addresses on the system.\n\n- description\n- interface_and_vhid\n- status\n- virtual_ip_address\n\n### arp\n\nThis will pull a list of all ARP entries on the system.\n\n- hostname\n- interface\n- ip_address\n- link_type\n- mac_address\n- status\n\n### ndp\n\nThis will pull a list of the IPv6 neighbor discovery table on the system.\n\n- expiration\n- hostname\n- interface\n- ipv6_address\n- mac_address\n\n### states\n\nThis will return a list of all the states present on the system.\n\nNOTE: This is subject to change. Currently it is only parsing the text on the table and may be updated to parse the fields further.\n\n### haproxy\n\nThis will return the data pulled from the HA proxy service.\n\nNOTE: This works, however the returend data is difficult to interpret. I do not have a description for each of the fields at this time.\n\n## Class\n\nClass: PfsenseApi\n\n A class designed to handle login and data querying from a PfSense firewall.\n\n Attributes:\n\n host: PfSense host address.\n port: PfSense port (default is 443).\n supported_read_apis: List of READ API's supported by this release\n verify_ssl: Boolean flag to verify SSL certificates (default is True).\n log_level: Logging level (default is INFO).\n ca_cert_path: Path to CA certificate file (default is None).\n\n Methods:\n\n __init__(self, host, username, password, port=443, log_level=INFO, verify_ssl=True, ca_cert_path=None)\n Initializes a PfsenseApi instance, establishes a session, and logs in.\n \n login(self, username, password) -> bool\n Logs into the PfSense firewall using the provided username and password.\n\n system_stats(self) -> dict\n Collects system stats and general info from the firewall using supported APIs and returns the data as a dictionary.\n\n def call_api(self, api_name:str) -> list|dict\n Call a specific API and return the data\n\n get_response(self, method='get', path='/index.php', data=None, headers=None, parameters=None, retry=RETRY, timeout=TIMEOUT) -> requests.Response\n Executes an HTTP request with optional parameters, data, and headers.\n",
"bugtrack_url": null,
"license": "",
"summary": "Python API for monitoring PfSense firewalls.",
"version": "0.1.0",
"project_urls": {
"bug tracker": "https://github.com/LearningToPi/pfsense_api/issues",
"source code": "https://github.com/LearningToPi/pfsense_api"
},
"split_keywords": [
"queue",
"thread",
"async"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9b73432f4849e1b161141e2008eba18f1023bbb27d465242ae80b7fd109be7f3",
"md5": "fe1038b492b1fee0ac0a176c37002edf",
"sha256": "f331ddae2fe6bdef458a8a15ef13b090fc7241e8e0b495706dd148ad5f0e3005"
},
"downloads": -1,
"filename": "pfsense_api-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fe1038b492b1fee0ac0a176c37002edf",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 16451,
"upload_time": "2024-02-04T03:17:02",
"upload_time_iso_8601": "2024-02-04T03:17:02.075087Z",
"url": "https://files.pythonhosted.org/packages/9b/73/432f4849e1b161141e2008eba18f1023bbb27d465242ae80b7fd109be7f3/pfsense_api-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fbc8de11c0de1c61afb69502ea7f36e2bfbb39cd169a8bc8bf685ef97c43aca3",
"md5": "1f37dfee1af8e073ce7bdb1f757cf954",
"sha256": "2535c9efe9dd904395c37142ef0a092645686acf40a650d215c2aff8862315fc"
},
"downloads": -1,
"filename": "pfsense_api-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "1f37dfee1af8e073ce7bdb1f757cf954",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 16643,
"upload_time": "2024-02-04T03:17:04",
"upload_time_iso_8601": "2024-02-04T03:17:04.055098Z",
"url": "https://files.pythonhosted.org/packages/fb/c8/de11c0de1c61afb69502ea7f36e2bfbb39cd169a8bc8bf685ef97c43aca3/pfsense_api-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-04 03:17:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "LearningToPi",
"github_project": "pfsense_api",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "pfsense-api"
}
