ZENARMOR RESTFUL API
The Zenarmor API is structured in a RESTful method. Our API supports standard HTTP response codes, authentication, and verbs, takes form-encoded request bodies, produces JSON-encoded replies, and uses predictable resource-oriented URLs.
The Zenarmor API uses API keys to authenticate requests. You can view and manage your API keys in the Zenarmor Dashboard.
caution
Keep in mind that your API keys have a lot of power, so keep them safe! Do not post your private API keys on GitHub, in client-side code, or anywhere else that is publicly available.
Authentication
HTTP Basic Auth is used to authenticate users to the API. As the basic auth username value, provide your API key. There is no need to enter a password. API user and key should be sent as parameter and API Key should be sent in the authorization header.
You must enable API for your firewall and generate authentication API key on your Zenconsole by connecting to Zenportal (SVN Centralized Cloud Management Portal).
info
If you are using Zenarmor on an OPNsense firewall, to get benefit of API feature you must register your node to Zenportal and enable API on your Zenconsole.
AuthorizationAPI Key
Key | Value |
---|---|
apikey | api_key_value |
API Objects
Available API Objects are explained below.
Exceptions
HTTPS is required for all API queries. Plain HTTP calls will be rejected. Requests to the API that aren't authenticated will also fail.
Zenarmor employs standard HTTP response codes to indicate if an API request was successful or not. Codes in the 2xx range, on the whole, suggest success. Codes in the 4xx range indicate that an error occurred based on the data provided (e.g., a required parameter was omitted, a charge failed, etc.). Server errors are indicated by codes in the 5xx range (these are rare).
Some 4xx faults that could be handled programmatically (for example, a user authentication will be rejected) include an error code that summarizes the error quickly.
Enable / Disable / Start / Stop Service
Service is an object that you can Enable, Disable, Start or Stop the Zenarmor Engine Service
Endpoints
POST https://<ip>:<port>/service?user=username&service_name=service&action=action_name
Example Query
https://localhost:8090/service?user=usera&service_name=eastpect&action=stop
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera | |
service_name | eastpect | eastpect/elasticsearch/mongod |
action | stop | start/stop/restart/enable/disable |
Response
{
"Body": "{\"Status\":0,\"Message\":\"Success\"}",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Bypass Engine
Bypass Engine is an object that you can Bypass the Zenarmor agent. Bypass Engine only supports POST Method.
Endpoints
POST https://<ip>:<port>/bypassengine?user=username&status=true/false
Example Query
https://localhost:8090/bypassengine?user=usera&status=false
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera | |
status | true | true/false |
Response
{
"Body": "{\"Status\":0,\"Message\":\"Success\"}",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Top Applications
Top Applications is an object that you can get top applications list from Zenarmor Engine. It supports GET Method.
Endpoints
GET https://<ip>:<port>/topapplications/?user=<user>
Example Query
https://localhost:8090/topapplications?user=usera
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera |
Response
{
"Body": "{\"datasets\":[{\"data\":[4352283,895430,696506,407678,140741],\"backgroundColor\":[\"#109618\",\"#66aa00\",\"#990099\",\"#66aa00\",\"#109618\"]}],\"labels\":[\"Online Utility\",\"Web Browsing\",\"Business Tools\",\"Software Updates\",\"Infrastructure Services\"],\"labels2\":[\"\",\"\",\"\",\"\",\"\"],\"labelsId\":[],\"field\":\"\",\"sumByte\":true}",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Top Hosts
Top Host is an object that you can get the top hosts list
Endpoints
GET https://<ip>:<port>/tophosts
Example Query
https://localhost:8090/tophosts?user=usera
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera |
Response
{
"Body": "{\"datasets\":[{\"data\":[37913240,894361,35184,1988],\"backgroundColor\":[\"#3366cc\",\"#dd4477\",\"#0099c6\",\"#3366cc\"]}],\"labels\":[\"192.168.1.46\",\"10.255.255.182\",\"192.168.1.52\",\"192.168.1.1\"],\"labels2\":[\"\",\"\",\"\",\"\"],\"labelsId\":[],\"field\":\"\",\"sumByte\":true}",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Top Detected Hosts
Top Detected Hosts is an object that you can get the Top Detected Hosts List. It supports GET method.
Endpoints
GET https://<ip>:<port>/topdetectedthreathosts
Example Query
https://localhost:8090/topdetectedthreathosts?user=usera
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera |
Response
{
"Body": "{\"datasets\":[{\"data\":[1],\"backgroundColor\":
[\"#0099c6\"]}],\"labels\":[\"mvdesktop.local\"],\"labels2\":[\"\"],\"labelsId\":
[],\"field\":\"\",\"sumByte\":true}",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Top Threats
Top Threats is an object that you can get the list of the top threats
Endpoints
GET https://<ip>:<port>/topthreats
Example Query
https://localhost:8090/topthreats?user=usera
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera |
Response
{
"Body": "{\"datasets\":[{\"data\":[19],\"backgroundColor\":[\"#990099\"]}],\"labels\":[\"Potentially Dangerous\"],\"labels2\":[\"\"],\"labelsId\":[],\"field\":\"\",\"sumByte\":true}",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Top Blocked Threats
Top Blocked Threats is an object where you can get the top blocked threats. It supports GET method.
Endpoints
GET https://<ip>:<port>/topblockedthreats
Example Query
https://localhost:8090/topblockedthreats?user=usera
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera |
Response
{
"Body": "{\"datasets\":[{\"data\":[13],\"backgroundColor\":[\"#109618\"]}],\"labels\":[\"Potentially Dangerous\"],\"labels2\":[\"\"],\"labelsId\":[],\"field\":\"\",\"sumByte\":true}",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Top Policy Blocks
Top Policy Blocks is an object that you can get the connection details of Policy Based Blocks. It supports GET method.
Endpoints
GET https://<ip>:<port>/toppolicyblocks
Example Query
https://localhost:8090/toppolicyblocks
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera |
Response
{
"Body": "{\"datasets\":[{\"data\":[13],\"backgroundColor\":[\"#109618\"]}],\"labels\":[\"Potentially Dangerous\"],\"labels2\":[\"\"],\"labelsId\":[],\"field\":\"\",\"sumByte\":true}",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
All Policies
All Policies is an object where you can get the list of all policies. It supports GET method.
Endpoints
GET https://<ip>:<port>/policies
Example Query
https://localhost:8090/policies?user=usera
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera |
Response
{
"Body": "[{\"advanced_security\":[],\"app\":false,\"app_controls\":[],\"cloud_id\":\"kugK4XUPIw\",\"decision_is_block\":0,\"delete_status\":0,\"directions\":{\"inbound\":true,\"outbound\":true},\"essential_security\":[],\"exclusion_blacklist\":[],\"exclusion_blacklist_global\":[],\"exclusion_whitelist\":[],\"exclusion_whitelist_global\":[],\"groups\":[],\"id\":1641142628,\"interfaces\":[],\"is_centralized\":0,\"is_cloud\":1,\"is_sync\":0,\"mac_addresses\":[],\"macaddresses\":\"\",\"name\":\"my_example_pol\",\"networks\":[],\"schedules\":[],\"security\":false,\"sort_number\":-76,\"status\":1,\"tls\":false,\"usernames\":[],\"uuid\":\"ceaea***-e0**-4699-abcb-**********\",\"vlans\":[],\"web\":true,\"web_controls\":[],\"webcategory_type\":\"permissive\"},{\"advanced_security\":[],\"app\":true,\"app_controls\":[1,2,10013,,18280],\"cloud_id\":\"FwlOvn9eOC\",\"decision_is_block\":0,\"delete_status\":0,\"directions\":{\"inbound\":false,\"outbound\":false},\"essential_security\":[],\"exclusion_blacklist\":[],\"exclusion_blacklist_global\":[],\"exclusion_whitelist\":[],\"exclusion_whitelist_global\":[],\"groups\":[\"system\"],\"id\":0,\"interfaces\":[],\"is_centralized\":0,\"is_cloud\":0,\"is_sync\":0,\"mac_addresses\":[],\"macaddresses\":\"\",\"name\":\"Default\",\"networks\":[],\"schedules\":[],\"security\":false,\"sort_number\":0,\"status\":1,\"tls\":false,\"usernames\":[\"system\"],\"uuid\":\"0\",\"vlans\":[],\"web\":true,\"web_controls\":[103],\"webcategory_type\":\"permissive\"}]",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Policy
Policy is an object where you can get details of specific policy. It supports GET method.
Endpoints
GET https://<ip>:<port>/policy
Example Query
https://localhost:8090/policy?user=usera&policy_id=1641142628&policy_name=my_example_pol
Request Params
Parameter | Value |
---|---|
user | usera |
policy_id | 1641142628 |
policy_name | my_example_pol |
Response
{
"Body": "[{\"advanced_security\":[],\"app\":false,\"app_controls\":[],\"cloud_id\":\"kugK4XUPIw\",\"decision_is_block\":0,\"delete_status\":0,\"directions\":{\"inbound\":true,\"outbound\":true},\"essential_security\":[],\"exclusion_blacklist\":[],\"exclusion_blacklist_global\":[],\"exclusion_whitelist\":[],\"exclusion_whitelist_global\":[],\"groups\":[],\"id\":1641142628,\"interfaces\":[],\"is_centralized\":0,\"is_cloud\":1,\"is_sync\":0,\"mac_addresses\":[],\"macaddresses\":\"\",\"name\":\"my_example_pol\",\"networks\":[],\"schedules\":[],\"security\":false,\"sort_number\":-76,\"status\":1,\"tls\":false,\"usernames\":[],\"uuid\":\"ceaea***-e0**-4699-abcb-**********\",\"vlans\":[],\"web\":true,\"web_controls\":[],\"webcategory_type\":\"permissive\"}]",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Update Policy
Update Policy is an object where you can update a policy. It supports POST method
Endpoints
POST https://<ip>:<port>/updatepolicy
Example Query
https://localhost:8090/updatepolicy?user=usera&policy_id=641142628&policy_name=my_example_pol&aciton=add&item_type=ip&value=192.168.1.89
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera | |
policy_id | 1641142628 | |
policy_name | my_example_pol | |
action | add | add/remove |
item_type | ip | mac/ip |
value | 192.168.1.89 |
Response
{
"Body": "[{\"advanced_security\":[],\"app\":false,\"app_controls\":[],\"cloud_id\":\"kugK4XUPIw\",\"decision_is_block\":0,\"delete_status\":0,\"directions\":{\"inbound\":true,\"outbound\":true},\"essential_security\":[],\"exclusion_blacklist\":[],\"exclusion_blacklist_global\":[],\"exclusion_whitelist\":[],\"exclusion_whitelist_global\":[],\"groups\":[],\"id\":1641142628,\"interfaces\":[],\"is_centralized\":0,\"is_cloud\":1,\"is_sync\":0,\"mac_addresses\":[],\"macaddresses\":\"\",\"name\":\"my_example_pol\",\"networks\":[\"192.168.1.89\"],\"schedules\":[],\"security\":false,\"sort_number\":-76,\"status\":1,\"tls\":false,\"usernames\":[],\"uuid\":\"ceaea***-e0**-4699-abcb-**********\",\"vlans\":[],\"web\":true,\"web_controls\":[],\"webcategory_type\":\"permissive\"}]",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
IPS Signature
IPS Signature is an object where you can create new rule or delete rule. It supports POST method.
You can find sample Python code for using rest api on below provided path in your OPNsense Zenarmor Instance.
/usr/local/sensei/zenarmor-agent/scripts/zenapi.py
note
On Linux distributions, this sample Python code is located in the next path:
/usr/local/zenarmor/zenarmor-agent/scripts/zenapi.py
Endpoints
POST https://<ip>:<port>/ipssignature
Example Query
https://localhost:8090/ipssignature?user=usera
Request Params
Parameter | Value | Possible Values |
---|---|---|
user | usera | |
action | list | list / add / del / apply |
type | ip | ip / filemd5 |
data | 192.168.122.1 | 192.168.122.1 / d8e8fca2dc0f896fd7cb4cb0031ba249 |
category | Malware+ | Malware+ / Virus …. |
message | Malware+ detection | Custom message |
Response For Add / del / apply action parameters
{
"Body": "",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Response for Wrong type
{
"Body": "{\"title\":\"Invalid type of Signature\",\"message\":\"Invalid type of Signature\"}",
"Status": 400,
"Message": "Bad Request",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Response for Invalid hash
{
"Body": "{\"title\":\"Invalid hash data\",\"message\":\"Invalid hash data\"}",
"Status": 400,
"Message": "Error",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}
Response for Action parameter is list
{
"Body": "[{\"Index\":0,\"Type\":\"ip\",\"Data\":\"192.168.122.138\",\"Category\":\"Malware+\",\"Message\":\"message\",\"Detail\":\"detail\"},{\"Index\":1,\"Type\":\"filemd5\",\"Data\":\"d8e8fca2dc0f896fd7cb4cb0031ba249\",\"Category\":\"Malware+\",\"Message\":\"message\",\"Detail\":\"detail\"}]",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}