SGBox Docs

SGBox - IM data extractor API

4 min read

With the SGBox IM Data Extractor API, you can extract information from the Alarm & Incident management system for further use. Currently the following extraction are available

  • Generated alarms and their details.

1 Required parameters

1.1 Header Section

The header section contains the authorization parameters, all parameters are mandatory.

Parameter NameParameter Value
Content-Typeapplication/json
api_keythe API Key
tenant_idThe reference Tenant ID or sgbox for single tenant instances
user-nameThe user name
user_passThe user password
requestThe action required, can be one of the following:
check - To check the connection
alarms - To extract the alarms
The authorization parameters will always be validated.

1.2 POST Section

The POST section contains the Alarms selection criteria.

Parameter NameParameter Value
start_dateThe start date/time of the alarms extraction window in the format “YYYY-MM-DD HH:mm:ss.”
end_dateThe end date/time of the alarms extraction window in the format “YYYY-MM-DD HH:mm:ss.”
alarms_statusThe status of the alarms to be extracted, can be one of the following:
0 - Open Alarms
1 - Assigned to triage
2 - Assigned to Incident
8 - Closed as Incident
9 - Closed as False Positive
all - All alarms
alarms_detailsEnables/disables the alarm details extraction, can be one of the following:
on - To extract the details
off - To NOT extract the details

1.3 Call example

Below is a PHP example showing how to call the AM Alarms Extractor API.

Please note

This API can be called once per minute at most. Calls with frequencies lower than one minute will be ignored.

 
# --- Set the URL to be called.
$url = 'https://<your server ip address>/sgbox/API/common/im_data_extractor.php';
 
# --- Set the payload  
$payload = [
	"start_date"    => '2025-12-16 13:59:00',
	"end_date"      => '2025-12-16 14:10:00',
	"alarm_status"  => '0',
	"alarm_details" => 'on'
];
$payload = json_encode($payload);
 
# --- cURL init
$ch = curl_init($url);
 
# --- Set headers
curl_setopt($ch, CURLOPT_HTTPHEADER, [
	"Content-Type: application/json",
	"api_key: 16f2d62d4fc4ed143efd91e1fe59367e",
	"tenant_id: your_tenant",
	"user_name: your_user",
	"user_pass: your_user_password",
	"request: alarms'
]);
 
# --- Set cURL options
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 10);
curl_setopt($ch, CURLOPT_TIMEOUT, 300);
 
# 
# --- Do not verify SSL (only for Test environments 
#     or when SGBox is using a self-signed certificate)
#
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
# ---
  
# --- Execute the call   
$response   = curl_exec($ch);
$http_code  = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curl_error = curl_error($ch) ?? '';
 
curl_close($ch);
 
# --- Get the result  
if ($http_code >= 200 && $http_code < 300) {
	echo $response;
} else {
	$response = json_decode($response, true);
	$curl_error = ($curl_error == '') ? '' : 'Error: '.$curl_error;
	echo json_encode([
		'success' => false,
		'message' => "HTTP Code: $http_code, $curl_error, Message: ".$response['message']
	]);
 
}

1.4 API Output

The API will return a JSON structured as follows:

{
    "success": true,                                         # --- True or false 
    "message": "1 alarm(s) where successfully extracted.",   # --- The success or the error message
	"result": [                                            
		{},                                                  # --- An entry for each alarm extracted
        [...],
        {}
    ]
}

When the alarms_datails option is set to on, at the end of each alarm node, the node additional_details will contain the alarm’s additional information. For example:

			"additional_details": {
                "host_data": [
                    [
                        {
                            "host_ip": "YODADC01",
                            "host_name": "YODADC01",
                            "network": "10.250.2.0",
                            "network_mask": 24,
                            "network_name": "Test 01"
                        }
                    ]
                ],
                "raw_log": [
                    [
                        {
                            "raw_log": "202512170800084230925 Dec 17 08:00:08 YODADC01 Provider-Name=\"Microsoft-Windows-Security-Auditing\" [...]"
                        }
                    ]
                ],
                "pattern": [
                    [
                        {
                            "pattern_regex": "EventID=\"(4732)\" MemberName=\"(.*?)\" MemberSid=\"(.*?)\" [...]" ,
                            "pattern_name": "[SGA][4732] Member Added to Local Group"
                        }
                    ]
                ],
                "extracted_parameters": [
                    [
                        {
                            "EventID": "4732",
                            "SubjectLogonId": "0x11095b9",
                            "SubjectDomainName": "YODA",
                            "SubjectUserName": "mrossi_da",
							[...]
                        }
                    ]
                ]
            }

1.5 API Messages

1.5.1 Success messages

  • n alarm(s) where successfully extracted
  • No alarm(s) found for the specified criteria

1.5.2 Error messages

Header and POST errors

  • Server error 000
    • Invalid request method. It must be POST.
  • Server error 001
    • POST data is not a valid JSON
  • Server error 002
    • Invalid HEADER parameter
  • Server error 003
    • Invalid POST parameter

Authentication errors

  • Server error 021
    • Invalid API Key
  • Server error 022
    • Invalid user or password
  • Server error 023
    • Requested Tenant_ID does not exists

Generic errors

  • Server error 097
    • Internal API Error.
  • Server error 098
    • This API is not supposed to run on a manager instance
  • Server error 099
    • Too many calls in a short time

Custom errors

  • Custom error 001
    • The AM module is not active on the specified tenant. There is nothing to extract.

Backlinks