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"
        }
                    ]
}

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

Parameter	Value	Possible Values
user	usera
policy_id	0
action	add	add/remove
item_type	domain	domain/ip
value	yahoo.com
list_type	blacklist	blacklist/whitelist
send_feedback	false	false/true
is_global	true	false/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

Parameter	Value	Possible Values
user	usera

Raw Data

--header 'Content-Type: application/json' \ --data-raw '{"id":null,"checksum":"27d6f73bb1a7de518c5888dfcbf30c9d","local_id":null,"is_activ e":true,"is_centralized":false,"is_default":false,"name":"rax15y","decision_is_bloc k":false,"groups":["ahmet","mehmet","nurullah","gencturk"],"usernames": [],"interfaces":[],"vlans":[],"mac_addresses":[],"networks":[],"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

Parameter	Value	Possible Values
user	usera
policy_id	1578999954

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

Parameter	Value	Possible Values
user	usera
policy_id	1979666332
status	true	true/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"
}
]
}