Telas com o processo de instalação, simples e rápido.

<– Return to plugins

In the GuardianKey’s administration panel you can set-up preferences for the detection engine and visualize your risks, events, and user’s interaction behaviours.

In this page we provide a brief documentation about our panel.

Images can be enlarged by clicking on them.

Contents

Accessing for the first time

Login page The administration panel can be accessed via Web, at the following URL:

https://panel.guardiankey.io

We note that we also have an in company version. In this case, the panel would be hosted in your environment.

You can use your account login data if you already have, or create a new account. If you are using a plugin, it may have created an account for you via API.

Home The panel’s interface is easy and intuitive. The main menu is divided into the following functional parts:

  • Dashboards: it is possible to have an overview oriented to risks, events or geographic.
  • Explore: you can search and explore events and users.
  • Settings: you can create organizations, authentication groups and policies, to be used by the detection engine.

Clicking on usernames, it is possible to view details about it.

Home If you still don’t have events collected, you should see some instructions to make GuardianKey run in the first page, after login (last screenshot). Otherwise, you will see some links to view your data (screenshot at right).

Below we provide details about the mentioned features.

Creating a new account

An account for you should be automatically created via API if you have used a plugin provided by us. In this case, you should have received an e-mail with the access details.

If you have not installed any plugin, you have to create an account and then configure your systems to send events to the GuardianKey’s servers.

Registering In this case, access the registering form at https://panel.guardiankey.io/auth/register and follow the instructions.

Recovering the password

To recover the password of an account at the GuardianKey’s panel, you should access the link https://panel.guardiankey.io/auth/forgotpass , type your e-mail address and follow the instructions that should be sent via e-mail.

NOTE: The recovery e-mail can be considered as SPAM, thus, have a look at your spam folder. The servers maintained by Microsoft (Outlook, Hotmail, MSN, Live, etc.) usually drops the e-mail without sending it to a spam folder. If it is your case, you have to include our e-mail “admin@guardiankey.io” in the safe sender list, at the configuration menu of your e-mail service. In the external URL below, you can find the steps for these procedures.

https://knowledgebase.constantcontact.com/articles/KnowledgeBase/5873-adding-email-addresses-to-a-safe-sender-list?lang=en_US

Basic concepts

GuardiaKey processes the authentication events sent by your systems to our engine to detect malicious activities and protect your systems against attacks.

One account at our panel can administrate many “organizations” and many “policies”. An “organization” can have many authentication groups “authgroups”.

  • Organization: may have many authgroups and policies.
  • Authgroup: is, basically, a set of users submitted to a policy and a response preference. One user is unique in an authgroup.
  • Policy: basically, is risk thresholds to define what to do based on the risk levels.

GuardianKey is risk-oriented. This feature provides a realistic view about the relevance of events in your systems. Also, it enables you to couple the risk outputs in the organization’s risk framework.

GuardianKey computes a risk for each event and recommends to your system a response, based on the thresholds set-up in the policy. There are the following responses:

  • Accept: risk too low, just allow the access and log.
  • Notify: allow the user action and notify the user about the access (e.g., via e-mail).
  • Hard notify: requires an extra action for the user to allow the access. For example, requiring the use of a second authentication factor. The user will also be notified for this access.
  • Block: block the user action and do not notify the user. This should be use only for high risks.

Events may have the following states:

  • Pending: it was notified to the user and it is needed an action from the user to mark it as resolved.
  • Resolved: the event was accepted, blocked or resolved by the user (via e-mail) or administrator (via panel).

Dashboards

The GuardianKey’s administration panel, currently, provides the following dashboards:

Risk dashboard
  • Risk: provides information about the accepted, mitigated, and pending risk. The accept risk is the sum of all events below the “accept” threshold. Mitigated risk is the risk related to the blocked events and threated events. The pending risk is the sum of event risks of the notified events. Geographic dashboard
  • Event: provides information about the number of events, based on each response type.
  • Geographic: provides the events ploted in the world map.

On all dashboards, you can choose the time period to create the graphs and tables.

Currently, it is not possible to create customized dashboards. However, you can send the processed events to your analytics application (e.g., a SIEM), and visualize the data integrated to other logs of your organization. This can be done by setting-up Web hooks.

Exploring events and users

Exploring events In the menu “Explore” it is possible to search and explore users and events. Just set the search options in the search form and click on the “Filter” button.

Exploring user details In any place of the panel, you can click in the username to open details about the specific user. In this page, there are the events and custom behaviors of the related user.


Changing password and profile settings

Changing profile To change the settings for the account in the administration panel, you just have to click over the username at the top-right and, then, profile.

Engine settings

In the panel you can also change detection preferences. Below, we present how.

Organizations

Organizations You can view, edit, delete, create new, and claim authority over organizations.

“Claim an organization” is used to give to your user the administration access over an organization, including its policies and authgroups.

This may be needed if you already have an organization created and want to have access over it using another account. It will not revoke the access of the last user, just include access for the new one.

Policies

Updating a policy On defining a policy, you should set three thresholds:

  • “Notify threshold”: events will be accepted below it and notified above it.
  • “Hard notify threshold”: for events with risk above this value, it will be suggested to the system to require more actions from the user (e.g., an extra authentication factor).
  • “Block threshold”: over this threshold, the user action will be blocked. User will not be notified about this via e-mail.

Authgroups

Checking deployment information for an authgroup An authgroup is, maybe, the most important entity in your configuration. The events should be sent to an authgroup. Some information is required to configure your systems to send events to GuardianKey, basically: KEY, IV, organizationID, and the authgroupID. These information can be found in the “Deploy information” tab.

Information about an authgroup Users are unique in an authgroup. Also, here, you should set-up the policy and the notification options. The name and description of an authgroup is used just for your reference.

Alert tab, in an authgroup In the tab “Alerts”, you must set-up how your users should be notified if the event risk level is in a notifiable risk level. GuardianKey supports the following options:

  • E-mail via your SMTP: used to send event notifications to your users via a mailing server provided by you. You can use a GMail account, for example.
  • Web hook: in this case, GuardianKey will process the events to compute its risk and submit them via REST using the “Web hook URL”, inputed by you in the form. This is particular useful to collect the events in your log system. The response should be made in your side. There is examples in our GitHub to implement webhook service in your web application server. Some plugins already implements a Web hook to receive and deal with the processed events.

Below we provide more details about each notification case.

Set-up to send e-mails to my users

Based on your settings, GuardianKey can notify your users via e-mail about risky access on their accounts at your systems.

In this case, you must provide a SMTP server for such e-mails. To avoid troubles with spam filters, we do not send e-mails directly.

There are many options to solve this, such as:

  1. You can allow our server’s IP to make relays in your SMTP server and input the IP address of your SMTP relay server;
  2. If all users’ e-mails have the same domain name, you can just inform the MX of this domain.
  3. You can create an account at a free mailing service, such as GMail, and input the account data in GuardianKey;

If you choose options 1 or 2, you should input on editing your authgroup:

  • Notify method: E-mail
  • SMTP Host: your SMT relay server IP or the MX’s IP
  • Port: 25
  • SMTP method: clear

If you choose 3, you can create an account in GMmail (for example), exclusive for this purpose, and set:

  • Notify method: E-mail
  • SMTP sender: the GMail address
  • SMTP host: smtp.gmail.com
  • SMTP user: the GMail address
  • SMTP pass: the password
  • SMTP port: 465
  • SMTP method: SSL

NOTE: You may need to keep a password of an e-mail account in our systems, thus, do not use your personal account! Create an account exclusive for this purpose, without any other use.

In any case, you can customize the e-mail to be sent to your users in the authgroup’s edition form.

Set-up to send processed events to me, via Web hook

Based on your settings, GuardianKey can send the processed events to your systems via REST (webhook). In your systems, you can notify your users, make logs, and perform some data analytics on the events.

In this case, you must implement and host a webservice (REST) and input the URL in the authgroup’s form.

Some plugins provided by us already implement a webservice. You can also have a look at our GitHub to see an example code, at https://github.com/pauloangelo/guardiankey-api-php .

  • Notify method: Web hook
  • Web hook URL: the URL

In any case, you can customize the e-mail to be sent to your users in the authgroup’s edition form.

Get help or ask your questions about the GuardianKey on our list:

https://groups.google.com/d/forum/guardiankey

In this page you can find information to configure the GuardianKey in your web application.

The interaction with GuardianKey is done by an API (Application Programming Interface). We provide a reference implementation in PHP and Python (libraries). The interaction with GuardianKey is easy, you can use our libs or you can implement your own code. Both ways are documented here, in distinct subsections.

We note that we also provide plugins for commonly used software that integrates with GuardianKey in a very simple way: just install and use! Check our plugins’ page to see if you software is already supported via plugins.

We recommend you to make use of our reference implementation to avoid bugs and make your work more simple.

Contents

Overview about the GuardianKey

GuardianKey is focused on providing a modern, intelligent and high-secure way to protect your systems in the authentication phase.

In summary:

  1. You register your system using the API;
  2. Your system use the information received in the registration step to send login attempts to GuardianKey (in cloud);
  3. The GuardianKey process the events with Artificial Intelligence algorithms to provide a risk for each login attempt;
  4. Based on predefined thresholds, your security staff and/or the user can be notified by e-mail;
  5. Also, for high level risks, your system can block or require more steps for the authentication (e.g., a second auth factor); and
  6. Finally, you can see everything (events, graphs, trends, etc.) in our admin interface.

You can configure the thresholds based on your risk acceptance levels, see how in using the admin interface.

Interacting with GuardianKey

Technically, the interaction with GuardianKey is done by the following phases:

  1. registering: create cryptographic keys, get an authgroupID in GuardianKey and register notification options;
  2. sending events: your system send login attempts (events) to be processed in GuardianKey; and
  3. monitoring: you access the GuardianKey admin interface to monitor your systems’ risks and setup your preferences.

In summary:

  1. the registration is done via a webserver, which supports REST and XML-RPC;
  2. alerts are sent via an encrypted JSON using UDP or REST; and
  3. the monitoring can be done via our admin interface.

Below, we describe the interactions described in phases 1 and 2.

For the impatient people, running it fast!

The commands below provide a fast way to create a login page in PHP or Python, using our reference API implementation.

#!/bin/sh
# Install PHP with extensions curl and ...
$ sudo apt-get install php php-json php-curl
 OR
$ sudo yum install php php-json php-curl
# Download the registering code and the class
$ wget https://github.com/pauloangelo/guardiankey-api-php/archive/master.zip

$ unzip master.zip
# run the code for registering
$ cd guardiankey-api-php-master
$ php register.php

# copy the output to the top of the file guardiankey-class.php, example:
$GKconfig = array(  
			'email' => 'xxxxx@xxxx.com',
			'agentid' => 'xxxxxxxxxxx',
			'key' => 'xxxxxxxxxxx',
			'iv' => 'xxxxxxxxxxx',
			'orgid' => 'xxxxxxxxxxx',
			'groupid' => 'xxxxxxxxxxx',
			'reverse' => '1',
			);

# Now, you should make a call for this function in the login processing code of your system
# Link to the code above, as in the example below.
<?php 
// This is my system's login page
require_once("guardiankey.class.php");
$GK = new guardiankey();
if ($_POST) {
...
$GK->send_event($username);
echo "<h2>Any data</h2>";
} 
#!/bin/sh
# Install Python dependencies using pip:
$ pip install requests json hashlib time 

# Download the registering code and the class
$ wget https://github.com/pauloangelo/guardiankey-api-python/archive/master.zip

$ unzip master.zip
# run the code for registering
$ python register.py

# copy the output to the top of the file guardiankey.py, example:
GKconfig = {}
GKconfig['email'] = 'xxxx@xxxxxx.com'
GKconfig['agentid'] = 'xxxxxxxxxxx'
GKconfig['key'] = 'xxxxxxxxxxx'
GKconfig['iv'] = 'xxxxxxxxxxx'
GKconfig['service'] = 'Myservice'
GKconfig['orgid'] = ''
GKconfig['groupid'] = ''
GKconfig['reverse'] = '1'




Useful links:

Accessing the API for registering

The registration is performed in the following steps:

  • Step 1: client (you or your system) creates a KEY and IV (Initialization Vector). Additionally, you can register the notification methods;
  • Step 2: client invokes the GuardianKey’s webserver register function with parameters KEY/IV and an admin e-mail; and
  • Step 3: the webserver saves the sent information and returns an authgroupID, which must be used to send events.

Our reference API implementation already provides these steps implemented. In such cases, the interaction process is very simple.

To create an authgroupID, you can also run our code available in GitHub and described in section for the impatient people.

We note that, after registering, you have to send events. The procedures are also described below.

Implementing your own code to register

If you want to use GuardianKey using other programming language or want to create your own code, you can interact directly with the GuardianKey’s API for registering via REST.

The codes below provide examples for registering via REST.

 <?php
/* Dependencies: php-curl */
define('AES_256_CBC', 'aes-256-cbc');
function register($email) {
			$guardianKeyWS='https://api.guardiankey.io/register';
            // Create new Key
            $key = openssl_random_pseudo_bytes(32);
            $iv = openssl_random_pseudo_bytes(openssl_cipher_iv_length('aes-256-cfb'));
            $keyb64 = base64_encode($key);
            $ivb64 =  base64_encode($iv);
            $agentid = base64_encode(openssl_random_pseudo_bytes(20));
	
            /* Optionally, you can set the notification parameters, such as:
              - notify_method: email or webhook
			  - notify_data: A base64-encoded json containing URL (if method is webhook), server and SMTP port, user, and email password.
		Example for e-mail:
			$notify_method = 'email';
			$notify_data = base64_encode('{"smtp_method":"TLS","smtp_host":"smtp.example.foo","smtp_port":"587","smtp_user":"myuser","smtp_pass":"mypass"}');
		Example for webhook:
		    $notify_method = 'webhook';
			$notify_data = base64_encode('{"webhook_url":"https://myorganization.com/guardiankey.php"}');
			*/
			$data = array(
					'email' => $email,
					'keyb64' => $keyb64,
					'ivb64' => $ivb64,
					/*Uncoment if you defined notify options
					'notify_method' => $notify_method,
					'notify_data' => $notify_data*/
					);
			$ch = curl_init();
			curl_setopt($ch,CURLOPT_URL, $guardianKeyWS);
			curl_setopt($ch,CURLOPT_POST, true);
			curl_setopt($ch,CURLOPT_POSTFIELDS, $data);
			curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
			$returned = curl_exec($ch);
			curl_close($ch);
			$returns = @json_decode($returned);
			if ($returns === null) {
				echo  'An error ocurred: '.$returned;
			} else {

				if ($_SERVER['SERVER_NAME']) {
						echo "<pre>";
				}
            echo  'Please add in your GuardianKey configuration: 
					$GKconfig = array(
					\'email\' => "'.$email.'",
					\'agentid\' => "'.$agentid.'",
					\'key\' => "'.$keyb64.'",
					\'iv\' => "'.$ivb64.'",
					\'orgid\' => "'.$returns->organizationId.'",
					\'groupid\' => "'.$returns->authGroupId.'",
					\'reverse\' => "1",
					);';
}
if ($_SERVER['SERVER_NAME']) {
	if ($_POST) {
		$email = $_POST['email'];
	} else {
	echo "<form action=# method=post>
		<p>Please enter admin email:</p>
		<input type=email name=email><br>
		<input type=submit value=submit>
	</form>";
	die;
	}
} else {
		echo "Please enter admin email:";
		$handle = fopen ("php://stdin","r");
		$email = trim(fgets($handle));	
	}
register($email);

// to send events, you need to save the $agentid, $key and $iv

import base64
import os
import requests
from Crypto.Cipher import AES

def register(email):
	guardianKeyWS='https://api.guardiankey.io/register'
	data = {}
	data['keyb64'] = base64.b64encode(os.urandom(32))
	data['ivb64']  = base64.b64encode(os.urandom(16))
	data['email'] = email
#Optionally, you can set the notification parameters, such as:
#notify_method: email or webhook
#notify_data: A base64-encoded json containing URL (if method is webhook), server and SMTP port, user, and email password.
#Example for e-mail:
	#data['notify_method'] = 'email'
	#data['notify_data'] = base64.b64encode('{"smtp_method":"TLS","smtp_host":"smtp.example.foo","smtp_port":"587","smtp_user":"myuser","smtp_pass":"mypass"}')
#Example for webhook:
    #data['notify_method'] = 'webhook';
	#data['notify_data'] = base64.b64encode('{"webhook_url":"https://myorganization.com/guardiankey.php"}')
	url = 'https://api.guardiankey.io/register'
	headers = {'Content-type': 'application/x-www-form-urlencoded', 'Accept': 'text/plain'}
	query = requests.post(url, data=data, headers=headers)
	return query.text,data['keyb64'],data['ivb64']


email = raw_input( "Enter the administrator e-mail:")
agentid,key,iv = register(email)

message = 'Put in your configuration this values:\n\
		   email: {}\n\
		   agentid: {}\n\
		   key: {}\n\
		   iv: {}\n'

print message.format(email,agentid,key,iv)



Note: We invite you to share your code for other languages or plugins of systems. Just publish it in GitHub and let us know by sending an e-mail (see the contact page).

Sending events

Sending an event can be done basically following the steps:

  • Step 1: create a JSON containing the information about the event (see the structure below);
  • Step 2: encrypt the JSON using the KEY/IV generated in the register phase;
  • Step 3: send the string “authgroupID|cipher” to GuardianKey via UDP or REST;
  • Step 4: if you use the sync mode (only using REST), you should receive “ALLOW”, “NOTIFY”,“HARD NOTIFY” or “BLOCK”, which can be used to block the user or require an extra factor for the user to authenticate.

The GuardianKey’s API supports receiving events via UDP or REST. UDP is more fast, but it is used uniquely to log events for notification, i.e., your system will not receive a feedback in time to block the login attempt, but your CSIRT and users can receive the alerts.

The REST interface is synchronous, the choice between them depends on the support given by the used programming language to these technologies and to the security requirements.

Mode Advantages
UDP (async) fast
REST (sync) enable blocking the access

Sending events using the reference API implementation

Make sure you have downloaded the reference implementation:

You will need to include your KEY/IV, AgentID and other information in the top of the file, like in the example code below. In your implementation, you can save this information in a database and retrieve when required.

 <?php
$GKconfig = array(
	'email' => "",  // Your admin e-mail
	'agentid' => "", // the hash returned in the register phase
	'key' => "",    // the Key generated in the register phase
	'iv' => "",     // the IV generated in the registrer phase
	'orgid' => "",     // use the same value as agentid in first use
	'groupid' => "",   // use the same value as agentid in first use
	'reverse' => "1",  // 1 or 0, to make reverse DNS 
                       // querying for sending
);

# Please run register.py for generate your configuration
GKconfig = {}
GKconfig['email'] = ''
GKconfig['agentid'] = ''
GKconfig['key'] = ''
GKconfig['iv'] = ''
GKconfig['service'] = ''
GKconfig['orgid'] = ''
GKconfig['groupid'] = ''
GKconfig['reverse'] = ''

After saving these parameters in the guardiankey.class.php or guardiankey.py file, you can just make use of it, like in the following codes:

 <?php
echo "<h2>My Login Page</h2>
<p>Please login</p>
<form action=# method=post>
<p>Username:<input type=text name=user></p>
<p>Password:<input type=password name=password></p>
<input type=submit value=submit>
</form>";
if ($_POST) {
   // $systemBlockedAccess is true if your system denied the access,
   // for example, if $username or $password are is valid.
   // Possible values:  0 - username and password is valid, 
   //			1 - username and password NOT is valid
   $systemBlockedAccess= yourLoginFunction($username,$password);

   require_once("guardiankey.class.php");
   $GK = new guardiankey();
   $GK->sendevent($username,$systemBlockedAccess);

}

 <?php
echo "<h2>My Login Page</h2>
<p>Please login</p>
<form action=# method=post>
<p>Username:<input type=text name=user></p>
<p>Password:<input type=password name=password></p>
<input type=submit value=submit>
</form>";
if ($_POST) {
   // $systemBlockedAccess is true if your system denied the access,
   // for example, if $username or $password are is valid.
   // Possible values:  0 - username and password is valid, 
   //			1 - username and password NOT is valid
   $systemBlockedAccess= yourLoginFunction($username,$password);

   require_once("guardiankey.class.php");
   $GK = new guardiankey();


   $GKReturn = json_decode($GK->checkaccess($username,$systemBlockedAccess));

   if($GKReturn['response'] === "ALLOW") {
     echo "<h2>Allowed!</h2>";
   }else if($$GKReturn['action']  === "EXTRAREQUIREMENT") {
     echo "<h2>Require OTP or something else. If not supported, ";
     echo "    you can just allow or deny the access, depending the security policy.</h2>";
   }else{
     echo "<h2>Your access was blocked! Contact the admin!</h2>";
   }
}


println "This is tab 2."

Note: Your system should send even the unauthorized login attempts (login/pass don’t match). GuardianKey will run if you do not send such event, however, this information is useful for our Machine Learning procedures and to provide a better visualization experience.

Creating your own code to send events

GuardianKey basically requires the information about the client’s IP address, the User-Agent submitted by the user’s browser, and if the login failed in the system. This information is available in the user’s request and in the system’s verification routine.

Below we present an example using the PHP language.

 <?php
// The KEY and IV can be saved in Base64 to simplify the manipulation
// But it must be decoded to be used.
$key=base64_decode($keyb64);
$iv=base64_decode($ivb64);

// This is an PHP object, that can be easily converted to JSON 
$json = new stdClass();
$json->generatedTime=$timestamp;
$json->agentId=$agentid;
$json->organizationId=$agentid;
$json->authGroupId=$agentid;
// identification of your system, useful for monitoring
$json->service="MySystem";
// The client's IP
$json->clientIP=$_SERVER['REMOTE_ADDR'];
// reverse lookups are used for some Machine Learning detection algorithms
// however, it can take some time. We recommend to send this information!
$json->clientReverse = ($reverse==1)?  gethostbyaddr($json->clientIP) : "";
// This is the login name
$json->userName=$username;
// Used in some specific cases
$json->authMethod="";
// Put 0 if login was validated in the system and 1 if it failed
$json->loginFailed="0";
// This is the UserAgent provided by the browser
$json->userAgent=substr($_SERVER['HTTP_USER_AGENT'],0,500);
$json->psychometricTyped="";
$json->psychometricImage="";

// Create the JSON
$message = json_encode($json,JSON_UNESCAPED_SLASHES);
// PAD the message
$blocksize=16;
$padsize = $blocksize - (strlen($message) % $blocksize);
$message=str_pad($message,$padsize," ");
// Encrypt using the KEY/IV
$cipher = openssl_encrypt($message, 'aes-256-cfb8', $key, 0, $iv);
// Create the payload and send via UDP
$payload=$agentid."|".$cipher;
$socket = socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
socket_sendto($socket, $payload, strlen($payload), 0, "collector.guardiankey.net", "8888");

// OR create the payload and send via REST, using curl:
/* $tmpdata->id = $agentid;
   $tmpdata->message = $cipher;
   $data = json_encode($tmpdata)
   $ch = curl_init();
   	curl_setopt($ch,CURLOPT_URL, 'https://api.guardiankey.io/checkaccess');
	curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");                                                                     
	curl_setopt($ch, CURLOPT_HTTPHEADER, array(
		'Content-Type: application/json',                                                                                
                'Content-Length: ' . strlen($data)));  
	curl_setopt($ch,CURLOPT_POSTFIELDS, $data);
	curl_setopt($ch, CURLOPT_REETURNTRANSFER, 1);
   $return = curl_exec($ch);
   curl_close($ch);
   return $return;
*/

Avoiding Event Flooding

When a system receives a brute force attack, it often sends GuardianKey many events. GuardianKey has an advanced brute force detection system. When such an attack is detected, GuardianKey returns “1” in the “response_cache” field of the event response json. With this, you can for example put the attacker’s IP in a “blacklist”, discarding and / or blocking access from that IP.

Details about the JSON data structure

Table below describes the JSON fields used for sending events to GuardianKey.

Field Description
generatedTime event generation unix timestamp (ex. 1527075751)
agentId agentid to identify uniquely the agent. If you have just one agent, use the authGroupID
organizationId in most cases, use the same authGroupId (ex. 7d97e98f8af…9e0ee507c4)
authGroupId string returned by the register function (ex. 7d97e98f8af…9e0ee507c4)
service text reference for your web system, your choice (ex. NextCloud)
eventType Type of event (Authentication or badaccess(future))
clientIP the IP (v4 or v6) used for user trying to have access (ex. 123.123.123.123)
clientReverse dns reverse of the clientIP (ex. 123.123.123.123.ispdomain.com)
userName the user login name used in the system (ex. john)
userEmail the user e-mail (ex. john@company.com), required only if your users should be notified by suspicious accesses
loginFailed 0 if user/pass matches and 1 otherwise (ex. 0)
userAgent the complete user-agent header sent by the user’s browser (ex. “Mozilla/5.0 (Windows NT 6.1) … Safari/537.”)
sequential sequential number to avoid replay attacks
authMethod used for some services that allows this features, most cases, leave it blank
psychometricTyped under development, leave it blank
psychometricImage under development, leave it blank

Receiving notifications

You have two modes for receive notifications: Via e-mail or Webhook.

Receiving via e-mail

If you want receive notifications via e-mail, just you configure SMTP information in your account on the GuardianKey panel (https://panel.guardiankey.io).

Receiving via webhook

You can receive notifications via webhook. This method enables that you personalize the treatment of notification: Send to a your DB, notificate users via other methods, etc.

For it, you need host the page that receive a json from GuardianKey and indicate in GuardianKey panel (or in the register) the URL of you webhook.

Please view the reference implementation of webhook (in PHP):

https://github.com/pauloangelo/guardiankey-api-php/blob/master/webhook.php

Table below describes the JSON fields sent from GuardianKey to webhook:

Field Description
generatedTime Event generation unix timestamp (ex. 1527075751)
message_contextual Frienldy message about the notification
userName Username used
agentId AgentID of service
eventId ID of event
risk_level Level of Risk
service Service name
clientIP IP used in the access
asn Autonomous System Number of access
clientReverse DNS reverse of IP the access
client_ua Useragent of access
client_device Device of client
client_os Os used
country Country of access
region Region of access
city City of access
country_code Code of country
latitude Latitude position of the access
longitude Longitude position of the access
risk_value Value Risk
authMethod Future implementation
event_response Response of GuardianKey
message_intel Information of threat intelligence
authGroupId AuthgroupID of agent
organizationId Organization ID
message_psychometric Psycometric info (future)

Creating Your Own Confirmation Screen

By default, GuardianKey sends a link to the confirmation screen (for the user to see if they recognize access or not) using the “guardiankey.io” domain. You may want to host this screen on your domain (which gives the user more credibility). For this you have to follow the following steps:

  • You will need a web server (running PHP, for example) and on that web server you will configure webhook and the confirmation screen. At the address below you will find the reference files (webhook.php and viewresolveevent.php). https://github.com/pauloangelo/guardiankey-api-php
  • In the “guardiankey.class.php” file options, you set the “resolveEventURL” option to your screen URL for resolving events.
  • You configure your webhook action to send the user the link from your confirmation screen and the link to be sent to the user you add as parameters: eventId and event_token. Ex: https: //xxxxxxxxxx.com/viewresolveevent.php?e=<eventId>&t=<event_token>
  • Finally, on the confirmation screen, you will retrieve event information and send the user response via API to GuardianKey, as in the viewresolveevent.php file.

Encryption details

We use a symmetric cryptography algorithm for signature, authentication and protected confidentiality of the events. The systems must send the authgroupID and the JSON encrypted on sending events, as in the example below (in UDP case):

authgroupID|cipher text (JSON) 

If use REST interface, event is sent as JSON:

id: authgroupID
data: cipher text (JSON)

The table below presents details about the used cryptography.

Parameter Value
crypt algorithm AES
key length 256
block cipher mode CFB
segment size 8

Useful references

The App is used to receive instant notifications regarding access to accounts in systems protected by GuardianKey. To use it, follow the steps below.

  1. Install the app from the Play Store: GuardianKey Security
  2. Click on authorize device and read the QR Code for your authgroup/user
  3. Done! When an event should be notified, GuardianKey will send a push notification.

About the QR Code

The QR Code must contain a text in the following format:

v2/authorize_device/AUTHGROUPID/USERNAME/TOKEN

where AUTHGROUPID can be found in the deployment information tab at the Administration Panel, USERNAME is the login used for the user, and TOKEN is as follows:

TOKEN = sha256("AUTHGROUPID-USERNAME-KEY")

KEY is your authgroup’s respective key, found in the panel. We have a page to generate the QR Code for you, the URL is below.

https://panel.guardiankey.io/authgroups/authqrcode/AUTHGROUPID/USERNAME/TOKEN

Authgroupid and key can be found in the panel, you may use this information to generate the token, for example, in the the following site: Generate SHA256 sum online .