Skip to main content

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.

warning

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.

Here is a video on Zenarmor RESTful API:

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 (Zenarmor 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 Zenconsole and enable API.

Authorization API Key​

KeyValue
apikeyapi_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​

ParameterValuePossible Values
userusera
service_nameeastpecteastpect/elasticsearch/mongod
actionstopstart/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​

ParameterValuePossible Values
userusera
statustruetrue/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​

ParameterValuePossible Values
userusera

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​

ParameterValuePossible Values
userusera

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​

ParameterValuePossible Values
userusera

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​

ParameterValuePossible Values
userusera

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​

ParameterValuePossible Values
userusera

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​

ParameterValuePossible Values
userusera

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​

ParameterValuePossible Values
userusera

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​

ParameterValue
userusera
policy_id1641142628
policy_namemy_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​

ParameterValuePossible Values
userusera
policy_id1641142628
policy_namemy_example_pol
actionaddadd/remove
item_typeipmac/ip
value192.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 Zenarmor Instance.

/usr/local/zenarmor/zenarmor-agent/scripts/zenapi.py

Endpoints​

POST https://<ip>:<port>/ipssignature

Example Query​

https://localhost:8090/ipssignature?user=usera

Request Params​

ParameterValuePossible Values
userusera
actionlistlist / add / del / apply
typeipip / filemd5
data192.168.122.1192.168.122.1 / d8e8fca2dc0f896fd7cb4cb0031ba249
categoryMalware+Malware+ / Virus ….
messageMalware+ detectionCustom 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"
}
]
}

Update Policy Exclusion​

Update Policy Exclusion is an object where you can update policy exclusion lists. It supports POST method.

Endpoints​

POST https://<ip>:<port>/updateexclusion

Example Query​

https://localhost:8090/updateexclusion?
user=usera&policy_id=0&item_type=domain&value=yahoo.com&list_type=blacklist&send_fe
edback=false&action=add&is_global=true

Request Params​

ParameterValuePossible Values
userusera
policy_id0
actionaddadd/remove
item_typedomaindomain/ipv4/ipv6
valueyahoo.com
list_typeblacklistblacklist/whitelist
send_feedbackfalsefalse/true
is_globaltruefalse/true

Response​

{
"Body": "[{\"advanced_security\":[],\"app\":false,\"app_controls\":
[],\"cloud_id\":\"GPDDnqKKS4\",\"decision_is_block\":0,\"delete_status\":0,\"direct
ions\":{\"inbound\":false,\"outbound\":false},\"essential_security\":
[],\"exclusion_blacklist\":[],\"exclusion_blacklist_global\":
[{\"is_global\":true,\"type\":null,\"value\":\"yahoo.com\"}],\"exclusion_whitelist\
":[],\"exclusion_whitelist_global\":[],\"groups\":
[\"system\"],\"id\":0,\"interfaces\":
[],\"is_centralized\":0,\"is_cloud\":0,\"is_sync\":0,\"mac_addresses\":
[],\"name\":\"Default\",\"networks\":[],\"schedules\":
[],\"security\":false,\"sort_number\":0,\"status\":1,\"tls\":false,\"usernames\":
[\"system\"],\"uuid\":\"0\",\"vlans\":[],\"web\":true,\"web_controls\":
[],\"webcategory_type\":\"permissive\"}]",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}

Add/Update A Whole Policy​

Add/Update A Whole Policy is an object where you can update a whole policy at once. It supports POST method.

Endpoints​

POST https://<ip>:<port>/setwholepolicy

Example Query​

https://localhost:8090/setwholepolicy?user=usera

Request Params​

ParameterValuePossible Values
userusera

Raw Data​

--header 'Content-Type: application/json' \
--data-raw
'{"id":null,"checksum":"27d6f73bb1a7de518c5888dfcbf30c9d","local_id":null,"is_active":true,"is_centralized":false,
"is_default":false,"name":"rax15y","decision_is_block":false,"groups":["ahmet","mehmet","nurullah","gencturk"],"usernames":
[],"interfaces":[],"vlans":[],"mac_addresses":[{ "value": "aa:bb:cc:dd:ee:ff" }, { "value": "11:22:33:44:55:66" } ],
"networks": [ { "value": "192.168.1.0/24" }],"directions":
{"inbound":true,"outbound":true},"webcategory_type":"permissive","sort_number":99,"
security":true,"app":true,"web":true,"tls":false,"advanced_security":
[124],"essential_security":[],"app_controls":[],"web_controls":[],"schedules":
[],"exclusion_blacklist":[],"exclusion_whitelist":[],"exclusion_blacklist_global":
[],"exclusion_whitelist_global":[]}'
note

To add a new policy, id field must be null.

To update an existing policy, id field must be equal to the policy id, such as "1578999954".

Response​

{
"Body": "[{\"advanced_security\":[124],\"app\":false,\"app_controls\":
[],\"cloud_id\":\"\",\"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\":
[\"ahmet\",\"mehmet\",\"nurullah\",\"gencturk\"],\"id\":1926640613,\"interfaces\":
[],\"is_centralized\":0,\"is_cloud\":1,\"is_sync\":0,\"mac_addresses\":
[],\"name\":\"rax15y\",\"networks\":[],\"schedules\":
[],\"security\":true,\"sort_number\":-133,\"status\":1,\"tls\":false,\"usernames\":
[],\"uuid\":\"8fe3ca29-c455-4e1f-aa06-1de6938f7797\",\"vlans\":
[],\"web\":true,\"web_controls\":[],\"webcategory_type\":\"permissive\"}]",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}

Remove Policy​

Remove Policy is an object where you can remove a whole policy at once. It supports POST method.

Endpoints​

POST https://<ip>:<port>/removepolicy

Example Query​

https://localhost:8090/removepolicy?user=usera&policy_id=1578999954

Request Params​

ParameterValuePossible Values
userusera
policy_id1578999954

Response​

{
"Body": "{\"error\":false,\"message\":\"\"}",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}

Update Policy Status​

Update Policy Status is an object where you can activate / inactivate a policy. It supports POST method.

Endpoints​

POST https://<ip>:<port>/setpolicystatus

Example Query​

https://localhost:8090/setpolicystatus?user=usera&policy_id=1979666332&status=true

Request Params​

ParameterValuePossible Values
userusera
policy_id1979666332
statustruetrue/false

Response​

{
"Body": "[{\"advanced_security\":[124],\"app\":false,\"app_controls\":
[],\"cloud_id\":\"aXFR4OkxsM\",\"decision_is_block\":0,\"delete_status\":0,\"direct
ions\":{\"inbound\":true,\"outbound\":true},\"essential_security\":
[],\"exclusion_blacklist\":[],\"exclusion_blacklist_global\":
[],\"exclusion_whitelist\":[],\"exclusion_whitelist_global\":[],\"groups\":
[\"ahmet\",\"mehmet\",\"nurullah\",\"gencturk\"],\"id\":1979666332,\"interfaces\":
[],\"is_centralized\":0,\"is_cloud\":1,\"is_sync\":0,\"mac_addresses\":
[],\"name\":\"rax15y\",\"networks\":[],\"schedules\":
[],\"security\":true,\"sort_number\":-133,\"status\":1,\"tls\":false,\"usernames\":
[],\"uuid\":\"8fe3ca29-c455-4e1f-aa06-1de6938f7797\",\"vlans\":
[],\"web\":true,\"web_controls\":[],\"webcategory_type\":\"permissive\"}]",
"Status": 200,
"Message": "OK",
"Headers": [
{
"content-type": "application/json; charset=utf-8"
}
]
}

Map Directory User​

Map Directory User is an object that you can call to notify the firewall that a specific user is logged into a specific IP. It supports the POST method.

Endpoints​

POST https://<ip>:<port>/mapdirectoryuser

Example Query​

https://localhost:8090/mapdirectoryuser?user=usera

Request Params​

ParameterValuePossible Values
userusera

Request​

--header 'Content-Type: application/json' \
--data-raw '{
"action": "Login",
"username": "alex",
"ip": "192.168.55.41",
"groups": [
"grp1",
"grp2"
],
"hostname": "myhost"
}'

JSON Body Fields​

ParameterValuePossible ValuesDescription
actionLoginLogin/LogoutLogin with associate the username and hostname of the specified client IP. Logout will unset the client IP's associated username.
usernamealexThe username to associate with the client's IP.
ip192.168.55.41The client IP address of the host in question.
hostnamemyhostThe hostname to associate with the client's IP.
groups[“grp1”,”grp2”]Allow Firewall to know which groups a user belongs to

Response​

{
"status": false,
"error_code": 400,
"message": "Invalid Api Key or User"
}
{
"status": true,
"error_code": 0,
"message": ""
}