# pyfortimanager
Python API client library for Fortinet's [FortiManager](https://www.fortinet.com/products/management/fortimanager).
It does not provide all endpoints or functionality available. We encourage to make a pull request with needed missing endpoints.
> **Note:** This library has been built and tested for FortiManager v7.2.x.
## Installation
To install run `pip install pyfortimanager`.
Alternatively, you can clone the repo and run `python setup.py install`.
## Quick Start
To begin, import pyfortimanager and instantiate the API.
We need to provide the IP or FQDN to the FortiManager instance and a user with access to the API.
Optionally, its possible to set `adom` which defaults to `root` and `verify` which defaults to `True`.
**Code**
```
import pyfortimanager
fortimanager = pyfortimanager.api(
host = "https://fortimanager.example.com",
token = "<api_token_from_fmg>"
)
```
> **Note:** To generate your API token, check the Fortinet docs [here](https://docs.fortinet.com/document/fortimanager/7.2.0/new-features/47777/fortimanager-supports-authentication-token-for-api-administrators-7-2-2).
## Examples
### List all FortiGates.
There is a ton of data for a single FortiGate. This code retrieves all of it, but only prints the name of the FortiGates.
**Code**
```
fmg_fortigates = fortimanager.fortigates.all()
for fmg_fortigate in fmg_fortigates['data']:
print(fmg_fortigate['name'])
```
**Output**
```
FortiGate-VM64-1
FortiGate-VM64-2
FortiGate-VM64-3
```
### Status object.
You can use the status object to check if the request is a success or not, and retrieve the error message.
**Code**
```
fmg_fortigate = fortimanager.fortigates.all(fortigate="FortiGate-VM64-4")
if fmg_fortigate['status']['code'] == 0:
print(fmg_fortigate['data']['name'])
else:
print(fmg_fortigate['status'])
```
**Output**
```
"status": {
"code": -3,
"message": "Object does not exist"
}
```
### Custom API request.
Since FortiManager consists of a ton of API endpoints, not all are supported natively in this module.
You can however use the custom_request function in order to reach any API endpoint in FortiManager.
**Code**
```
fmg_custom_request = fortimanager.system.custom_request(
params={
"url": "/dvmdb/adom/root/device",
"option": [
"get meta"
]
},
method="get"
)
print(json.dumps(fmg_custom_request, indent=4))
```
### Adding a FortiGate
This creates a model device in the Device Manager with the minimum required fields.
**Code**
```
fmg_fortigate_add = fortimanager.fortigates.add(
serial = "FGT60FTK1234ABCD",
mr = 0,
os_ver = 7
)
print(fmg_fortigate_add)
```
**Output**
```
{
"data": {
"device": {
"beta": -1,
"branch_pt": 516,
"build": 516,
"conn_mode": 1,
"dev_status": 1,
"flags": 67371040,
"hostname": "FGT60FTK1234ABCD",
"maxvdom": 10,
"mgmt_id": 999918516,
"mgmt_mode": 3,
"mr": 0,
"name": "FGT60FTK1234ABCD",
"oid": 61594,
"os_type": 0,
"os_ver": 7,
"patch": -1,
"platform_id": 19,
"platform_str": "FortiGate-60F",
"sn": "FGT60FTK1234ABCD",
"source": 1,
"tab_status": "<unknown>",
"version": 700
}
},
"status": {
"code": 0,
"message": "OK"
},
"url": "/dvm/cmd/add/device"
}
```
### Retrieve all connected Wi-Fi clients on a FortiGate
To retrieve all current active Wi-Fi clients on the FortiGate, we need to call the FortiOS API directly on the FortiGate through FortiManager's proxy API.
When making proxy calls, you'll retrieve two status objects. The first is for the FortiManager call and the the second is for the API call on the FortiGate.
> **Note:** Proxy calls only works, if the FortiGate is online.
**Code**
```
fmg_wifi_clients = fortimanager.fortiaps_proxy.clients(fortigate="FortiGate-VM64-1")
print(fmg_wifi_clients)
```
**Output**
```
{
"data": [
{
"response": {
"action": "",
"build": 523,
"http_method": "GET",
"name": "client",
"path": "wifi",
"results": [
{
"11k_capable": false,
"11r_capable": false,
"11v_capable": true,
"association_time": 1698143761,
"authentication": "pass",
"bandwidth_rx": 2493967,
"bandwidth_tx": 2564936,
"captive_portal_authenticated": 0,
"channel": 44,
"data_rate_bps": 573600000,
"data_rxrate_bps": 286800000,
"data_txrate_bps": 286800000,
"encrypt": 1,
"health": {
"band": {
"severity": "good",
"value": "5ghz"
},
"signal_strength": {
"severity": "good",
"value": -52
},
"snr": {
"severity": "good",
"value": 43
},
"transmission_discard": {
"severity": "good",
"value": 0
},
"transmission_retry": {
"severity": "good",
"value": 0
}
},
"host": "WINDOWS-PC",
"hostname": "WINDOWS-PC",
"idle_time": 1,
"ip": "10.10.10.10",
"ip6": [
"fe80::c28d:52e5:68a4:95ad"
],
"lan_authenticated": false,
"mac": "aa:bb:cc:dd:ee:ff",
"manufacturer": "Microsoft",
"mimo": "2x2",
"noise": -95,
"os": "Windows",
"radio_type": "802.11ax-5G",
"security": 12,
"security_str": "wpa2_only_enterprise",
"signal": -52,
"snr": 43,
"ssid": "SSID",
"sta_maxrate": 286800,
"sta_rxrate": 286800,
"sta_rxrate_mcs": 11,
"sta_rxrate_score": 100,
"sta_txrate": 286800,
"sta_txrate_mcs": 11,
"sta_txrate_score": 100,
"tx_discard_percentage": 0,
"tx_retry_percentage": 0,
"user": "host/WINDOWS-PC.local.net",
"vap_name": "SSID",
"vci": "MSFT 5.0",
"vlan_id": 101,
"wtp_control_ip": "10.20.30.40",
"wtp_control_local_ip": "10.20.30.40",
"wtp_id": "FP431FTF12345678",
"wtp_ip": "10.20.30.40",
"wtp_name": "FAP-431F",
"wtp_radio": 2
}
],
"serial": "FGT60FTK1234ABCD",
"status": "success",
"vdom": "root",
"version": "v7.0.12"
},
"status": {
"code": 0,
"message": "OK"
},
"target": "FortiGate-VM64-1"
}
],
"status": {
"code": 0,
"message": "OK"
},
"url": "/sys/proxy/json"
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/BESTSELLER/pyfortimanager",
"name": "pyfortimanager",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "fortinet, fortimanager",
"author": "Rasmus Thing",
"author_email": "rasmus.thing@bestseller.com",
"download_url": "https://files.pythonhosted.org/packages/73/d0/bb022501536c43dd4e52906fedb69d7715fca8caf1df0b08dea50666c565/pyfortimanager-2.2.1.tar.gz",
"platform": null,
"description": "# pyfortimanager\nPython API client library for Fortinet's [FortiManager](https://www.fortinet.com/products/management/fortimanager).\n\nIt does not provide all endpoints or functionality available. We encourage to make a pull request with needed missing endpoints.\n\n> **Note:** This library has been built and tested for FortiManager v7.2.x.\n\n## Installation\nTo install run `pip install pyfortimanager`.\n\nAlternatively, you can clone the repo and run `python setup.py install`.\n\n## Quick Start\nTo begin, import pyfortimanager and instantiate the API.\n\nWe need to provide the IP or FQDN to the FortiManager instance and a user with access to the API.\nOptionally, its possible to set `adom` which defaults to `root` and `verify` which defaults to `True`.\n\n**Code**\n```\nimport pyfortimanager\nfortimanager = pyfortimanager.api(\n host = \"https://fortimanager.example.com\",\n token = \"<api_token_from_fmg>\"\n)\n```\n\n> **Note:** To generate your API token, check the Fortinet docs [here](https://docs.fortinet.com/document/fortimanager/7.2.0/new-features/47777/fortimanager-supports-authentication-token-for-api-administrators-7-2-2).\n\n## Examples\n### List all FortiGates.\nThere is a ton of data for a single FortiGate. This code retrieves all of it, but only prints the name of the FortiGates.\n\n**Code**\n```\nfmg_fortigates = fortimanager.fortigates.all()\nfor fmg_fortigate in fmg_fortigates['data']:\n print(fmg_fortigate['name'])\n```\n\n**Output**\n```\nFortiGate-VM64-1\nFortiGate-VM64-2\nFortiGate-VM64-3\n```\n\n### Status object.\nYou can use the status object to check if the request is a success or not, and retrieve the error message.\n\n**Code**\n```\nfmg_fortigate = fortimanager.fortigates.all(fortigate=\"FortiGate-VM64-4\")\nif fmg_fortigate['status']['code'] == 0:\n print(fmg_fortigate['data']['name'])\nelse:\n print(fmg_fortigate['status'])\n```\n\n**Output**\n```\n\"status\": {\n \"code\": -3,\n \"message\": \"Object does not exist\"\n}\n```\n\n### Custom API request.\nSince FortiManager consists of a ton of API endpoints, not all are supported natively in this module.\n\nYou can however use the custom_request function in order to reach any API endpoint in FortiManager.\n\n**Code**\n```\nfmg_custom_request = fortimanager.system.custom_request(\n params={\n \"url\": \"/dvmdb/adom/root/device\",\n \"option\": [\n \"get meta\"\n ]\n },\n method=\"get\"\n)\nprint(json.dumps(fmg_custom_request, indent=4))\n```\n\n### Adding a FortiGate\nThis creates a model device in the Device Manager with the minimum required fields.\n\n**Code**\n```\nfmg_fortigate_add = fortimanager.fortigates.add(\n serial = \"FGT60FTK1234ABCD\",\n mr = 0,\n os_ver = 7\n)\nprint(fmg_fortigate_add)\n```\n\n**Output**\n```\n{\n \"data\": {\n \"device\": {\n \"beta\": -1,\n \"branch_pt\": 516,\n \"build\": 516,\n \"conn_mode\": 1,\n \"dev_status\": 1,\n \"flags\": 67371040,\n \"hostname\": \"FGT60FTK1234ABCD\",\n \"maxvdom\": 10,\n \"mgmt_id\": 999918516,\n \"mgmt_mode\": 3,\n \"mr\": 0,\n \"name\": \"FGT60FTK1234ABCD\",\n \"oid\": 61594,\n \"os_type\": 0,\n \"os_ver\": 7,\n \"patch\": -1,\n \"platform_id\": 19,\n \"platform_str\": \"FortiGate-60F\",\n \"sn\": \"FGT60FTK1234ABCD\",\n \"source\": 1,\n \"tab_status\": \"<unknown>\",\n \"version\": 700\n }\n },\n \"status\": {\n \"code\": 0,\n \"message\": \"OK\"\n },\n \"url\": \"/dvm/cmd/add/device\"\n}\n```\n\n### Retrieve all connected Wi-Fi clients on a FortiGate\nTo retrieve all current active Wi-Fi clients on the FortiGate, we need to call the FortiOS API directly on the FortiGate through FortiManager's proxy API.\n\nWhen making proxy calls, you'll retrieve two status objects. The first is for the FortiManager call and the the second is for the API call on the FortiGate.\n\n> **Note:** Proxy calls only works, if the FortiGate is online.\n\n**Code**\n```\nfmg_wifi_clients = fortimanager.fortiaps_proxy.clients(fortigate=\"FortiGate-VM64-1\")\nprint(fmg_wifi_clients)\n```\n\n**Output**\n```\n{\n \"data\": [\n {\n \"response\": {\n \"action\": \"\",\n \"build\": 523,\n \"http_method\": \"GET\",\n \"name\": \"client\",\n \"path\": \"wifi\",\n \"results\": [\n {\n \"11k_capable\": false,\n \"11r_capable\": false,\n \"11v_capable\": true,\n \"association_time\": 1698143761,\n \"authentication\": \"pass\",\n \"bandwidth_rx\": 2493967,\n \"bandwidth_tx\": 2564936,\n \"captive_portal_authenticated\": 0,\n \"channel\": 44,\n \"data_rate_bps\": 573600000,\n \"data_rxrate_bps\": 286800000,\n \"data_txrate_bps\": 286800000,\n \"encrypt\": 1,\n \"health\": {\n \"band\": {\n \"severity\": \"good\",\n \"value\": \"5ghz\"\n },\n \"signal_strength\": {\n \"severity\": \"good\",\n \"value\": -52\n },\n \"snr\": {\n \"severity\": \"good\",\n \"value\": 43\n },\n \"transmission_discard\": {\n \"severity\": \"good\",\n \"value\": 0\n },\n \"transmission_retry\": {\n \"severity\": \"good\",\n \"value\": 0\n }\n },\n \"host\": \"WINDOWS-PC\",\n \"hostname\": \"WINDOWS-PC\",\n \"idle_time\": 1,\n \"ip\": \"10.10.10.10\",\n \"ip6\": [\n \"fe80::c28d:52e5:68a4:95ad\"\n ],\n \"lan_authenticated\": false,\n \"mac\": \"aa:bb:cc:dd:ee:ff\",\n \"manufacturer\": \"Microsoft\",\n \"mimo\": \"2x2\",\n \"noise\": -95,\n \"os\": \"Windows\",\n \"radio_type\": \"802.11ax-5G\",\n \"security\": 12,\n \"security_str\": \"wpa2_only_enterprise\",\n \"signal\": -52,\n \"snr\": 43,\n \"ssid\": \"SSID\",\n \"sta_maxrate\": 286800,\n \"sta_rxrate\": 286800,\n \"sta_rxrate_mcs\": 11,\n \"sta_rxrate_score\": 100,\n \"sta_txrate\": 286800,\n \"sta_txrate_mcs\": 11,\n \"sta_txrate_score\": 100,\n \"tx_discard_percentage\": 0,\n \"tx_retry_percentage\": 0,\n \"user\": \"host/WINDOWS-PC.local.net\",\n \"vap_name\": \"SSID\",\n \"vci\": \"MSFT 5.0\",\n \"vlan_id\": 101,\n \"wtp_control_ip\": \"10.20.30.40\",\n \"wtp_control_local_ip\": \"10.20.30.40\",\n \"wtp_id\": \"FP431FTF12345678\",\n \"wtp_ip\": \"10.20.30.40\",\n \"wtp_name\": \"FAP-431F\",\n \"wtp_radio\": 2\n }\n ],\n \"serial\": \"FGT60FTK1234ABCD\",\n \"status\": \"success\",\n \"vdom\": \"root\",\n \"version\": \"v7.0.12\"\n },\n \"status\": {\n \"code\": 0,\n \"message\": \"OK\"\n },\n \"target\": \"FortiGate-VM64-1\"\n }\n ],\n \"status\": {\n \"code\": 0,\n \"message\": \"OK\"\n },\n \"url\": \"/sys/proxy/json\"\n}\n```\n",
"bugtrack_url": null,
"license": "Apache2",
"summary": "Python API client library for Fortinet's FortiManager.",
"version": "2.2.1",
"project_urls": {
"Homepage": "https://github.com/BESTSELLER/pyfortimanager"
},
"split_keywords": [
"fortinet",
" fortimanager"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "34897355f82d5283b19ad06d404b4867da1fbc906e5e3e12637ed0f4a7298d5c",
"md5": "e2b107fb29d8a289ea4288c6797f2b63",
"sha256": "466e2b64cc298b0052d0dea92b78ce4322f25428556b9e35b94dce99255c18a1"
},
"downloads": -1,
"filename": "pyfortimanager-2.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2b107fb29d8a289ea4288c6797f2b63",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 29144,
"upload_time": "2024-03-27T09:55:35",
"upload_time_iso_8601": "2024-03-27T09:55:35.120250Z",
"url": "https://files.pythonhosted.org/packages/34/89/7355f82d5283b19ad06d404b4867da1fbc906e5e3e12637ed0f4a7298d5c/pyfortimanager-2.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "73d0bb022501536c43dd4e52906fedb69d7715fca8caf1df0b08dea50666c565",
"md5": "c5ab7d05ce204b8762ed3da10319ec08",
"sha256": "5a4e034ca871214a330613d24584208ead2c5b7fa9775309ff7d5a795ceb67c2"
},
"downloads": -1,
"filename": "pyfortimanager-2.2.1.tar.gz",
"has_sig": false,
"md5_digest": "c5ab7d05ce204b8762ed3da10319ec08",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 20866,
"upload_time": "2024-03-27T09:55:38",
"upload_time_iso_8601": "2024-03-27T09:55:38.130283Z",
"url": "https://files.pythonhosted.org/packages/73/d0/bb022501536c43dd4e52906fedb69d7715fca8caf1df0b08dea50666c565/pyfortimanager-2.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-27 09:55:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BESTSELLER",
"github_project": "pyfortimanager",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.20.0"
],
[
"<",
"3.0"
]
]
}
],
"lcname": "pyfortimanager"
}
JSON
