oxl-opnsense-client


Nameoxl-opnsense-client JSON
Version 0.0.3 PyPI version JSON
download
home_pageNone
SummaryOXL OPNSense API Client
upload_time2024-11-10 13:44:51
maintainerNone
docs_urlNone
authorNone
requires_python>=3.10
licenseNone
keywords api client opnsense firewall network network-as-code nac infrastructure-as-code iac
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls. 
            # OPNSense API Client

[![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)
[![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)

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](https://github.com/ansibleguy/collection_opnsense) that was refactored for use within raw Python.

This can be useful if you want to automate your Infrastructure and do not use [Ansible](https://www.ansible.com/how-ansible-works/).

**WARNING**: This project is still in early development! The forked code is pretty much stable, but the refactor may not yet be.

----

## Install

```bash
pip install oxl-opnsense-client
```

Get to know the available modules:

* [Module list](https://github.com/O-X-L/opnsense-api-client/tree/main/src/oxl_opnsense_client/plugins/modules)
* [Ansible Docs](https://opnsense.ansibleguy.net)

----

## Contribute

Feel 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).

Note: Only the [API-enabled](https://docs.opnsense.org/development/api.html) functionalities can be implemented.

----

## Advertisement

* Need **professional support** for IT-Automation or OPNSense? Contact us:

  E-Mail: [contact@oxl.at](mailto:contact@oxl.at)

  Tel: [+43 3115 40 900 0](tel:+433115409000)

  Web: [EN](https://www.o-x-l.com) | [DE](https://www.oxl.at)

  Language: German or English

----

## Usage

See also: [Ansible OPNSense-Collection Docs](https://opnsense.ansibleguy.net/en/latest/usage/2_basic.html)

```python3
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

```python3
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

```python3
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.

```python3
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:

```bash
ls /tmp/opnsense_client/
# api_calls.log  syslog.log
```

The module-specific logs contain performance-profiling.

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "oxl-opnsense-client",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.10",
    "maintainer_email": null,
    "keywords": "api, client, opnsense, firewall, network, network-as-code, nac, infrastructure-as-code, iac",
    "author": null,
    "author_email": "Rath Pascal <contact@oxl.at>",
    "download_url": "https://files.pythonhosted.org/packages/90/ad/6e2d2a4cb383d14c8782856bc842378a6036ccf921ac091ade5edae90dfc/oxl_opnsense_client-0.0.3.tar.gz",
    "platform": null,
    "description": "# 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\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='<IP>', credential_file='/home/<YOU>/.opnsense.txt')\n\n# use the token/key pair directly\nc = Client(firewall='<IP>', token='<TOKEN>', secret='<SECRET>')\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='<IP>',\n    credential_file='/home/<YOU>/.opnsense.txt',\n    ssl_ca_file='/home/<YOU>/ca.crt',\n)\n\n# ONLY USE FOR TESTING PURPOSES => you can disable the certificate-verification\nc = Client(\n    firewall='<IP>',\n    credential_file='/home/<YOU>/.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='<IP>',\n    credential_file='/home/<YOU>/.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': <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\":[]}}}'}'\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': <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\"}'}'\n# INFO: REQUEST: POST | URL: https://172.17.1.52/api/syslog/service/reconfigure | HEADERS: '{}'\n# 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\"}'}'\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",
    "bugtrack_url": null,
    "license": null,
    "summary": "OXL OPNSense API Client",
    "version": "0.0.3",
    "project_urls": {
        "Documentation": "https://github.com/O-X-L/opnsense-api-client",
        "Homepage": "https://www.oxl.at",
        "Issues": "https://github.com/O-X-L/opnsense-api-client/issues",
        "Repository": "https://github.com/O-X-L/opnsense-api-client.git"
    },
    "split_keywords": [
        "api",
        " client",
        " opnsense",
        " firewall",
        " network",
        " network-as-code",
        " nac",
        " infrastructure-as-code",
        " iac"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "d55dd5e51ce7a165b80f8fb011443981538851f2314f864813e44ac0266f144f",
                "md5": "085ef1cc74bc6e42b36a265de041eb2a",
                "sha256": "732034eed7f1d0b7b1aee1dd8b27b559e09faf8f02da35440f359543d5ffb0e7"
            },
            "downloads": -1,
            "filename": "oxl_opnsense_client-0.0.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "085ef1cc74bc6e42b36a265de041eb2a",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.10",
            "size": 254608,
            "upload_time": "2024-11-10T13:44:49",
            "upload_time_iso_8601": "2024-11-10T13:44:49.821837Z",
            "url": "https://files.pythonhosted.org/packages/d5/5d/d5e51ce7a165b80f8fb011443981538851f2314f864813e44ac0266f144f/oxl_opnsense_client-0.0.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "90ad6e2d2a4cb383d14c8782856bc842378a6036ccf921ac091ade5edae90dfc",
                "md5": "5de1bb4bcaedca81913fbc222304a2cd",
                "sha256": "ba460d0e49d667c174e398bdcbfd44828d9e2537cb37c683580cbb3daaa40966"
            },
            "downloads": -1,
            "filename": "oxl_opnsense_client-0.0.3.tar.gz",
            "has_sig": false,
            "md5_digest": "5de1bb4bcaedca81913fbc222304a2cd",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.10",
            "size": 130541,
            "upload_time": "2024-11-10T13:44:51",
            "upload_time_iso_8601": "2024-11-10T13:44:51.593657Z",
            "url": "https://files.pythonhosted.org/packages/90/ad/6e2d2a4cb383d14c8782856bc842378a6036ccf921ac091ade5edae90dfc/oxl_opnsense_client-0.0.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2024-11-10 13:44:51",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "O-X-L",
    "github_project": "opnsense-api-client",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [],
    "lcname": "oxl-opnsense-client"
}
None
Elapsed time: 0.41496s