You can retrieve data from our servers using two types of requests: check or update requests. Check requests are used to check information on a selected IPs, while Update requests retrieve threat level information on multiple IPs.
To request a check on one or more IPs, you must POST a JSON string to /api/public/v1/check/ with the following format:
{
"access_id": YOUR_ACCESS_ID,
"access_code": YOUR_ACCESS_CODE,
"ip": [ list_of_ips_to_check ]
}
where YOUR_ACCESS_ID and YOUR_ACCESS_CODE are your API credentials, while list_of_ips_to_check is a comma separated list of quoted IPs. For example:
{
"access_id": ws_access_0000000000000000,
"access_code": ws_code_1111111111111111,
"ip": [ "1.1.1.1", "2.2.2.2", "3.3.3.3" ]
}
A well formed request with correct API credentials returns information on the listed IPs according to the following format.
{
"count": number_of_returned_entries,
"error": error_occurred,
"response": [ list_of_returned_entries ]
}
where number_of_returned_entries corresponds to the number of entries that were returned by the server, and should match the number of requested IPs, unless you exceeded
your allowances.
The value of error_occurred is null unless the number of requested IPs exceeded your allowance, in which case an error "Allowance exceeded" is returned.
Finally, list_of_returned_entries details information on each IP. The format of each entry in this list is as follows:
{ "ip": ip_requested, "status": ip_status, "threats": [ list_of_threats ] }
where ip_requested identifies the IP corresponding to this specific entry, status returns the threat status of the IP according to our records
and may be one of Monitored, Suspicious, Serious,
Critical, or null if the IP was not identified as a threat.
If the IP requested cannot be processed because of exceeding allowances, then the IP will not be listed in the `response`.
For IPs where the status returned is a threat level, a list of threats observed and their approximate frequency is also returned.
Update requests permit to update your block lists with information from our servers. To request new data, send a POST request to /api/public/v1/update/ with the following format:
{
"access_id": YOUR_ACCESS_ID,
"access_code": YOUR_ACCESS_CODE,
"updates": requested_updates
}
where YOUR_ACCESS_ID and YOUR_ACCESS_CODE are your API credentials, while requested_updates is the number of IPs you want to request. There is a hard limit of 50 IPs per request: if you request more, the response will be limited to a maximum of 50, or the number permitted by your allowances, whichever is lower. For example:
{
"access_id": ws_access_0000000000000000,
"access_code": ws_code_1111111111111111,
"updates": 30
}
A well formed request with correct API credentials returns information on the listed IPs according to the following format.
{
"count": number_of_returned_entries,
"error": error_occurred,
"response": [ list_of_returned_entries ]
}
where number_of_returned_entries corresponds to the number of entries that were returned by the server: it might not match the requested number if you exceeded your allowances.
error_occurred isnull unless the number of requested IPs exceeded your allowance, in which case an error "Allowance exceeded" is returned.
list_of_returned_entries details information on each IP. The format of each entry in this list is as follows:
{ "ip": ip_requested, "status": ip_status }
where ip_requested identifies the IP corresponding to this specific entry, status returns the threat status of the IP according to our records
and may be one of Monitored, Suspicious, Serious,
Critical, or null if the IP was not identified as a threat.
There are two type of errors that may be encountered when sending a request to ServerSnug. The first occurs
when ServerSnug cannot understand your request. The server will return an HTML error code. The second type of error
occurs when the server receives the request and can recognize the credentials, but your request contains an error.
In this case the return HTML code is 200, to indicate correct reception of your request, but the error
field of the Json response is set to detail the issue encountered.
The following table lists the possible responses returned in case of error.
| HTML code | Json `error` field | Description |
|---|---|---|
| 403 | — | Your API credentials were not recognized. You might have provided the wrong credentials. |
| 500 | — | The ServerSnug server is experiencing some issues. Retry later. |
| 200 | Malformed request | Your JSON contains some error that prevented its correct parsing. |
| 200 | Missing `ip` | You sent a check request, but your JSON needs an `ip` field specifying the list of IPs for which you wish to retrieve information. |
| 200 | Missing `updates` | You sent an update request, but your JSON needs an `updates` field specifying the number of entries the server should return. |
Send a request to check three IPs.
curl --data '{"access_id": "ws_access_0000000000000000", "access_code": "ws_code_1111111111111111", "ip": [ "1.1.1.1", "2.2.2.2", "3.3.3.3" ]"}' https://www.serversnug.com/api/public/v1/check/
The first and second IPs have associated information on threats; the third response has no associated information.
{"count": 3, "error": null, "response": [{"ip": "1.1.1.1", "status": "Serious", "threats": [[54.55, "Folder scan"], [27.27, "Intelligence gathering scan"], [9.09, "Port scan"], [9.09, "Code injection"]]}, {"ip": "2.2.2.2", "status": "Monitored", "threats": [[100, "Basic vulnerability scan"]]}, {"ip": "3.3.3.3", "status": "Monitored", "threats": []}]}
The first IP has associated information on threats; the second and third are not returned as the account had one remaining check available.
{"count": 1, "error": "Allowance exceeded", "response": [{"ip": "1.1.1.1", "status": "Serious", "threats": [[54.55, "Folder scan"], [27.27, "Intelligence gathering scan"], [9.09, "Port scan"], [9.09, "Code injection"]]}]}
Send an update request.
curl --data '{"access_id": "ws_access_0000000000000000", "access_code": "ws_code_1111111111111111", "updates": 3}' https://www.serversnug.com/api/public/v1/updates/
Three IPs were requested and returned. Each has its associated status.
{"count": 3, "error": null, "response": [{"ip": "1.1.1.1", "status": "Serious"}, {"ip": "2.2.2.2", "status": "Monitored"}, {"ip": "3.3.3.3", "status": "Monitored"}]}
Three IPs were requested but one is returned: the allowance was exceeded.
{"count": 1, "error": "Allowance exceeded", "response": [{"ip": "1.1.1.1", "status": "Serious"}]}