{"id":25883094,"url":"https://github.com/o-x-l/opnsense-api-client","last_synced_at":"2025-03-02T16:31:14.579Z","repository":{"id":262001163,"uuid":"885793100","full_name":"O-X-L/opnsense-api-client","owner":"O-X-L","description":"Client for interacting with the OPNSense API","archived":false,"fork":false,"pushed_at":"2024-11-10T14:13:09.000Z","size":367,"stargazers_count":2,"open_issues_count":1,"forks_count":1,"subscribers_count":3,"default_branch":"latest","last_synced_at":"2025-02-11T19:19:37.874Z","etag":null,"topics":["api-client","automation","firewall","iac","infrastructure-as-code","library","nac","network-administration","network-as-code","network-automation","network-management","opnsense","security"],"latest_commit_sha":null,"homepage":"https://opnsense.ansibleguy.net/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/O-X-L.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-09T12:14:32.000Z","updated_at":"2024-11-18T21:06:04.000Z","dependencies_parsed_at":"2024-11-09T20:57:46.287Z","dependency_job_id":"1ed07144-fb23-41db-a130-de1f6cdee538","html_url":"https://github.com/O-X-L/opnsense-api-client","commit_stats":null,"previous_names":["o-x-l/opnsense-api-client"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/O-X-L%2Fopnsense-api-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/O-X-L%2Fopnsense-api-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/O-X-L%2Fopnsense-api-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/O-X-L%2Fopnsense-api-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/O-X-L","download_url":"https://codeload.github.com/O-X-L/opnsense-api-client/tar.gz/refs/heads/latest","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241537061,"owners_count":19978456,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","automation","firewall","iac","infrastructure-as-code","library","nac","network-administration","network-as-code","network-automation","network-management","opnsense","security"],"created_at":"2025-03-02T16:31:13.695Z","updated_at":"2025-03-02T16:31:14.542Z","avatar_url":"https://github.com/O-X-L.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OPNSense API Client\n\n[![Lint](https://github.com/O-X-L/opnsense-api-client/actions/workflows/lint.yml/badge.svg)](https://github.com/O-X-L/opnsense-api-client/actions/workflows/lint.yml)\n[![Test](https://github.com/O-X-L/opnsense-api-client/actions/workflows/unittest.yml/badge.svg)](https://github.com/O-X-L/opnsense-api-client/actions/workflows/unittest.yml)\n[![PyPI - Version](https://img.shields.io/pypi/v/oxl-opnsense-client?color=green)](https://pypi.org/project/oxl-opnsense-client/)\n\nThis is a Python3 client for interacting with the official OPNSense API.\n\nIt enables simple management and automation of OPNSense firewalls. An interactive CLI interface might be added later on.\n\nThe base-code is a Fork of this [OPNSense Ansible-Collection](https://github.com/ansibleguy/collection_opnsense) that was refactored for use within raw Python.\n\nThis can be useful if you want to automate your Infrastructure and do not use [Ansible](https://www.ansible.com/how-ansible-works/).\n\n**WARNING**: This project is still in early development! The forked code is pretty much stable, but the refactor may not yet be.\n\n----\n\n## Install\n\n```bash\npip install oxl-opnsense-client\n```\n\nGet to know the available modules:\n\n* [Module list](https://github.com/O-X-L/opnsense-api-client/tree/main/src/oxl_opnsense_client/plugins/modules)\n* [Ansible Docs](https://opnsense.ansibleguy.net)\n\n----\n\n## Contribute\n\nFeel free to [report issues/bugs](https://github.com/O-X-L/opnsense-api-client/issues), [take part in discussions](https://github.com/O-X-L/opnsense-api-client/discussions), [add/extend tests](https://github.com/O-X-L/opnsense-api-client/tree/latest/src/tests) and [provide PRs to enhance or extend the codebase](https://github.com/O-X-L/opnsense-api-client/pulls).\n\nNote: Only the [API-enabled](https://docs.opnsense.org/development/api.html) functionalities can be implemented.\n\n----\n\n## Advertisement\n\n* Need **professional support** for IT-Automation or OPNSense? Contact us:\n\n  E-Mail: [contact@oxl.at](mailto:contact@oxl.at)\n\n  Tel: [+43 3115 40 900 0](tel:+433115409000)\n\n  Web: [EN](https://www.o-x-l.com) | [DE](https://www.oxl.at)\n\n  Language: German or English\n\n----\n\n## Usage\n\nSee also: [Ansible OPNSense-Collection Docs](https://opnsense.ansibleguy.net/en/latest/usage/2_basic.html)\n\n```python3\nfrom oxl_opnsense_client import Client\n\nwith Client(\n    firewall='192.168.10.20',\n    port=443,  # default\n    credential_file='/tmp/.opnsense.txt',\n    # token='0pWN/C3tnXem6OoOp0zc9K5GUBoqBKCZ8jj8nc4LEjbFixjM0ELgEyXnb4BIqVgGNunuX0uLThblgp9Z',\n    # secret='Vod5ug1kdSu3KlrYSzIZV9Ae9YFMgugCIZdIIYpefPQVhvp6KKuT7ugUIxCeKGvN6tj9uqduOzOzUlv',\n) as c:\n    c.test()\n    # True\n\n    ### CREATE / REMOVE ENTRIES ###\n    \n    c.run_module('syslog', params={'target': '192.168.0.1', 'port': 5303})\n    # {'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': ''}}}}\n    c.run_module('syslog', params={'target': '192.168.0.1', 'port': 5303, 'state': 'absent'})\n    # {'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': ''}}}}\n    c.run_module('syslog', params={'target': '192.168.0.1', 'port': 5303, 'state': 'absent'})\n    # {'error': None, 'result': {'changed': False, 'diff': {}}}\n\n    ### CHECK MODE (DRY-RUN) ###\n    \n    c.run_module('syslog', check_mode=True, params={'target': '192.168.0.1', 'port': 5303})\n    # {'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': ''}}}}\n    c.run_module('syslog', params={'target': '192.168.0.1', 'port': 5303, 'state': 'absent'})\n    # {'error': None, 'result': {'changed': False, 'diff': {}}}\n```\n\n\n### Credentials\n\n```python3\nfrom oxl_opnsense_client import Client\n\n# use the API credentials-file as downloaded from the WebUI\nc = Client(firewall='\u003cIP\u003e', credential_file='/home/\u003cYOU\u003e/.opnsense.txt')\n\n# use the token/key pair directly\nc = Client(firewall='\u003cIP\u003e', token='\u003cTOKEN\u003e', secret='\u003cSECRET\u003e')\n```\n\n----\n\n### SSL Verification\n\n```python3\nfrom oxl_opnsense_client import Client\n\n# provide the path to your custom CA public-key\nc = Client(\n    firewall='\u003cIP\u003e',\n    credential_file='/home/\u003cYOU\u003e/.opnsense.txt',\n    ssl_ca_file='/home/\u003cYOU\u003e/ca.crt',\n)\n\n# ONLY USE FOR TESTING PURPOSES =\u003e you can disable the certificate-verification\nc = Client(\n    firewall='\u003cIP\u003e',\n    credential_file='/home/\u003cYOU\u003e/.opnsense.txt',\n    ssl_verify=False,\n)\n```\n\n----\n\n### Debug Output\n\nThis will show you the performed API calls and their JSON payload.\n\n```python3\nfrom oxl_opnsense_client import Client\nc = Client(\n    firewall='\u003cIP\u003e',\n    credential_file='/home/\u003cYOU\u003e/.opnsense.txt',\n    debug=True,\n)\n\nc.run_module('syslog', params={'target': '192.168.0.1', 'port': 5303})\n# INFO: REQUEST: GET | URL: https://172.17.1.52/api/syslog/settings/get\n# INFO: RESPONSE: '{'status_code': 200, '_request': \u003cRequest('GET', 'https://172.17.1.52/api/syslog/settings/get')\u003e, '_num_bytes_downloaded': 123, '_elapsed': datetime.timedelta(microseconds=194859), '_content': b'{\"syslog\":{\"general\":{\"enabled\":\"1\",\"loglocal\":\"1\",\"maxpreserve\":\"31\",\"maxfilesize\":\"\"},\"destinations\":{\"destination\":[]}}}'}'\n# 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\": \"\"}}'\n# INFO: RESPONSE: '{'status_code': 200, '_request': \u003cRequest('POST', 'https://172.17.1.52/api/syslog/settings/addDestination')\u003e, '_num_bytes_downloaded': 64, '_elapsed': datetime.timedelta(microseconds=61852), '_content': b'{\"result\":\"saved\",\"uuid\":\"ed90d52a-63ac-4d7c-a35b-4f250350f85d\"}'}'\n# INFO: REQUEST: POST | URL: https://172.17.1.52/api/syslog/service/reconfigure | HEADERS: '{}'\n# INFO: RESPONSE: '{'status_code': 200, '_request': \u003cRequest('POST', 'https://172.17.1.52/api/syslog/service/reconfigure')\u003e, '_num_bytes_downloaded': 15, '_elapsed': datetime.timedelta(microseconds=657156), '_content': b'{\"status\":\"ok\"}'}'\n```\n\nThis information is also logged to files:\n\n```bash\nls /tmp/opnsense_client/\n# api_calls.log  syslog.log\n```\n\nThe module-specific logs contain performance-profiling.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fo-x-l%2Fopnsense-api-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fo-x-l%2Fopnsense-api-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fo-x-l%2Fopnsense-api-client/lists"}