OXL OPNSense API Client
Project description
OPNSense API Client
This is a Python3 client for interacting with the official OPNSense API.
It enables simple management and automation of OPNSense firewalls. An interactive CLI interface might be added later on.
The base-code is a Fork of this OPNSense Ansible-Collection that was refactored for use within raw Python.
This can be useful if you want to automate your Infrastructure and do not use Ansible.
WARNING: This project is still in early development! The forked code is pretty much stable, but the refactor may not yet be.
Install
pip install oxl-opnsense-client
Get to know the available modules:
Contribute
Feel free to report issues/bugs, take part in discussions, add/extend tests and provide PRs to enhance or extend the codebase.
Note: Only the API-enabled functionalities can be implemented.
Advertisement
-
Need professional support for IT-Automation or OPNSense? Contact us:
E-Mail: contact@oxl.at
Tel: +43 3115 40 900 0
Language: German or English
Usage
See also: Ansible OPNSense-Collection Docs
from oxl_opnsense_client import Client
with Client(
firewall='192.168.10.20',
port=443, # default
credential_file='/tmp/.opnsense.txt',
# token='0pWN/C3tnXem6OoOp0zc9K5GUBoqBKCZ8jj8nc4LEjbFixjM0ELgEyXnb4BIqVgGNunuX0uLThblgp9Z',
# secret='Vod5ug1kdSu3KlrYSzIZV9Ae9YFMgugCIZdIIYpefPQVhvp6KKuT7ugUIxCeKGvN6tj9uqduOzOzUlv',
) as c:
c.test()
# True
### CREATE / REMOVE ENTRIES ###
c.run_module('syslog', params={'target': '192.168.0.1', 'port': 5303})
# {'error': None, 'result': {'changed': True, 'diff': {'after': {'uuid': None, 'rfc5424': False, 'enabled': True, 'target': '192.168.0.1', 'transport': 'udp4', 'facility': [], 'program': [], 'level': ['alert', 'crit', 'emerg', 'err', 'info', 'notice', 'warn'], 'certificate': '', 'port': 5303, 'description': ''}}}}
c.run_module('syslog', params={'target': '192.168.0.1', 'port': 5303, 'state': 'absent'})
# {'error': None, 'result': {'changed': True, 'diff': {'before': {'uuid': '2500dadc-ce43-4e23-994e-860516b0ef45', 'rfc5424': False, 'enabled': True, 'target': '192.168.0.1', 'transport': 'udp4', 'facility': [], 'program': [], 'level': ['alert', 'crit', 'emerg', 'err', 'info', 'notice', 'warn'], 'certificate': '', 'port': 5303, 'description': ''}}}}
c.run_module('syslog', params={'target': '192.168.0.1', 'port': 5303, 'state': 'absent'})
# {'error': None, 'result': {'changed': False, 'diff': {}}}
### CHECK MODE (DRY-RUN) ###
c.run_module('syslog', check_mode=True, params={'target': '192.168.0.1', 'port': 5303})
# {'error': None, 'result': {'changed': True, 'diff': {'before': {'uuid': '7f3aba31-07ca-4cb9-b93d-dc442a5291c7', 'rfc5424': False, 'enabled': True, 'target': '192.168.0.1', 'transport': 'udp4', 'facility': [], 'program': [], 'level': ['alert', 'crit', 'emerg', 'err', 'info', 'notice', 'warn'], 'certificate': '', 'port': 5303, 'description': ''}}}}
c.run_module('syslog', params={'target': '192.168.0.1', 'port': 5303, 'state': 'absent'})
# {'error': None, 'result': {'changed': False, 'diff': {}}}
Credentials
from oxl_opnsense_client import Client
# use the API credentials-file as downloaded from the WebUI
c = Client(firewall='<IP>', credential_file='/home/<YOU>/.opnsense.txt')
# use the token/key pair directly
c = Client(firewall='<IP>', token='<TOKEN>', secret='<SECRET>')
SSL Verification
from oxl_opnsense_client import Client
# provide the path to your custom CA public-key
c = Client(
firewall='<IP>',
credential_file='/home/<YOU>/.opnsense.txt',
ssl_ca_file='/home/<YOU>/ca.crt',
)
# ONLY USE FOR TESTING PURPOSES => you can disable the certificate-verification
c = Client(
firewall='<IP>',
credential_file='/home/<YOU>/.opnsense.txt',
ssl_verify=False,
)
Debug Output
This will show you the performed API calls and their JSON payload.
from oxl_opnsense_client import Client
c = Client(
firewall='<IP>',
credential_file='/home/<YOU>/.opnsense.txt',
debug=True,
)
c.run_module('syslog', params={'target': '192.168.0.1', 'port': 5303})
# INFO: REQUEST: GET | URL: https://172.17.1.52/api/syslog/settings/get
# INFO: RESPONSE: '{'status_code': 200, '_request': <Request('GET', 'https://172.17.1.52/api/syslog/settings/get')>, '_num_bytes_downloaded': 123, '_elapsed': datetime.timedelta(microseconds=194859), '_content': b'{"syslog":{"general":{"enabled":"1","loglocal":"1","maxpreserve":"31","maxfilesize":""},"destinations":{"destination":[]}}}'}'
# INFO: REQUEST: POST | URL: https://172.17.1.52/api/syslog/settings/addDestination | HEADERS: '{'Content-Type': 'application/json'}' | DATA: '{"destination": {"rfc5424": 0, "enabled": 1, "hostname": "192.168.0.1", "transport": "udp4", "facility": "", "program": "", "level": "alert,crit,emerg,err,info,notice,warn", "certificate": "", "port": 5303, "description": ""}}'
# INFO: RESPONSE: '{'status_code': 200, '_request': <Request('POST', 'https://172.17.1.52/api/syslog/settings/addDestination')>, '_num_bytes_downloaded': 64, '_elapsed': datetime.timedelta(microseconds=61852), '_content': b'{"result":"saved","uuid":"ed90d52a-63ac-4d7c-a35b-4f250350f85d"}'}'
# INFO: REQUEST: POST | URL: https://172.17.1.52/api/syslog/service/reconfigure | HEADERS: '{}'
# INFO: RESPONSE: '{'status_code': 200, '_request': <Request('POST', 'https://172.17.1.52/api/syslog/service/reconfigure')>, '_num_bytes_downloaded': 15, '_elapsed': datetime.timedelta(microseconds=657156), '_content': b'{"status":"ok"}'}'
This information is also logged to files:
ls /tmp/opnsense_client/
# api_calls.log syslog.log
The module-specific logs contain performance-profiling.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file oxl_opnsense_client-0.0.3.tar.gz
.
File metadata
- Download URL: oxl_opnsense_client-0.0.3.tar.gz
- Upload date:
- Size: 130.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | ba460d0e49d667c174e398bdcbfd44828d9e2537cb37c683580cbb3daaa40966 |
|
MD5 | 5de1bb4bcaedca81913fbc222304a2cd |
|
BLAKE2b-256 | 90ad6e2d2a4cb383d14c8782856bc842378a6036ccf921ac091ade5edae90dfc |
File details
Details for the file oxl_opnsense_client-0.0.3-py3-none-any.whl
.
File metadata
- Download URL: oxl_opnsense_client-0.0.3-py3-none-any.whl
- Upload date:
- Size: 254.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/5.1.1 CPython/3.12.7
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 732034eed7f1d0b7b1aee1dd8b27b559e09faf8f02da35440f359543d5ffb0e7 |
|
MD5 | 085ef1cc74bc6e42b36a265de041eb2a |
|
BLAKE2b-256 | d55dd5e51ce7a165b80f8fb011443981538851f2314f864813e44ac0266f144f |