Nesta página você pode encontrar informações para configurar o GuardianKey em seu aplicativo da web.

A interação com o GuardianKey é feita por uma API (Application Programming Interface). Nós fornecemos uma implementação de referência em PHP e Python (bibliotecas). A interação com o GuardianKey é fácil, você pode usar nossas bibliotecas ou implementar seu próprio código. Ambas as formas são documentadas aqui, em subseções distintas.

Observamos que também fornecemos plugins para softwares comumente usados que se integra com o GuardianKey de uma maneira muito simples: basta instalar e usar! Confira nossa página de plugins para ver se o software já é suportado via plugins.

Recomendamos que você faça uso de nossa implementação de referência para evitar bugs e tornar seu trabalho mais simples.

Conteúdo

Visão geral sobre o GuardianKey

O GuardianKey está focado em fornecer uma maneira moderna, inteligente e altamente segura de proteger seus sistemas na fase de autenticação.

Em suma:

1. Você registra seu sistema;
2. Seu sistema usa as informações do registro (no painel do GuardianKey) para enviar tentativas de login ao GuardianKey (na nuvem);
3. O GuardianKey processa os eventos com algoritmos de Inteligência Artificial para fornecer um risco para cada tentativa de login;
4. Com base em limites predefinidos, sua equipe de segurança e / ou o usuário podem ser notificados por e-mail;
5. Além disso, para riscos de alto nível, seu sistema pode bloquear ou exigir mais etapas para a autenticação (por exemplo, um segundo fator de autenticação); e
6. Finalmente, você pode ver tudo (eventos, gráficos, tendências, etc.) em nossa interface administrativa.

Você pode configurar os limites com base nos seus níveis de aceitação de risco, veja como usando a interface administrativa.

Interagindo com GuardianKey

Tecnicamente, a interação com o GuardianKey é feita pelas seguintes fases:

1. registrar: criar chaves criptográficas, obter um authgroupID em GuardianKey e registrar opções de notificação;
2. envio de eventos: seu sistema envia tentativas de login (eventos) para serem processadas no GuardianKey; e
3. monitoramento: você acessa a interface de administração do GuardianKey para monitorar os riscos de seus sistemas e configurar suas preferências.

Em suma:

1. o registro (cadastro) é feito pelo Painel do GuardianKey;
2. alertas são enviados através de um JSON criptografado usando UDP ou REST; e
3. o monitoramento pode ser feito através da nossa interface administrativa.

Abaixo, descrevemos as interações descritas nas fases 1 e 2.

Para as pessoas impacientes, corra rápido!

Os comandos abaixo fornecem uma maneira rápida de criar uma página de login em PHP ou Python, usando nossa implementação de API de referência.

#!/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 class of GuardianKey
$ wget https://github.com/guardiankey/guardiankey-api-php/archive/master.zip


# copy the Keys of GuardiaKey Panel to the top of the file guardiankey-class.php, example:
$GKconfig = array(  
			'email' => '[email protected]',
			'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 class
$ wget https://github.com/guardiankey/guardiankey-api-python/archive/master.zip

# copy the Keys of GuardiaKey Panel to the top of the file guardiankey.py, example:
GKconfig = {}
GKconfig['email'] = '[email protected]'
GKconfig['agentid'] = 'xxxxxxxxxxx'
GKconfig['key'] = 'xxxxxxxxxxx'
GKconfig['iv'] = 'xxxxxxxxxxx'
GKconfig['service'] = 'Myservice'
GKconfig['orgid'] = ''
GKconfig['groupid'] = ''
GKconfig['reverse'] = '1'

• Exemplo de código para o seu sistema enviar eventos para GuardianKey
• Solução de problemas

Realizando o registro

Um registro (cadastro) prévio é necessário para enviar eventos ao GuardianKey. Isso deve ser feito utilizando o Painel do GuardianKey.

Enviando eventos

O envio de um evento pode ser feito basicamente seguindo as etapas:

• Etapa 1: crie um JSON contendo as informações sobre o evento (veja a [estrutura] (# detalhes-sobre-o-json-data-estrutura) abaixo);
• Etapa 2: criptografar o JSON usando o KEY / IV gerado na fase de registro;
• Etapa 3: envie a string “authgroupID | cipher” para GuardianKey via UDP ou REST;
• Etapa 4: se você usar o modo de sincronização (usando apenas REST), você deve receber “ALLOW”,“NOTIFY”,“HARD NOTIFY” ou “BLOCK”, que pode ser usado para bloquear o usuário ou exigir um fator extra para o usuário para autenticar.

A API do GuardianKey suporta o recebimento de eventos via UDP ou REST. O UDP é mais rápido, mas é usado exclusivamente para registrar eventos para notificação, ou seja, o seu sistema não receberá um feedback a tempo de bloquear a tentativa de login, mas o seu CSIRT e os usuários podem receber os alertas.

A interface REST é síncrona, a escolha entre eles depende de o suporte dado pela linguagem de programação usada para essas tecnologias e aos requisitos de segurança.

Enviando eventos usando a implementação da API de referência

Certifique-se de ter baixado a implementação de referência:

• PHP – https://github.com/guardiankey/guardiankey-api-php/
• Python – https://github.com/guardiankey/guardiankey-api-python/

Você precisará incluir sua KEY / IV, AgentID e outras informações na parte superior do arquivo, como no código de exemplo abaixo. Em sua implementação, você pode salvar essas informações em um banco de dados e recuperá-las quando necessário.

 <?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'] = ''

Depois de salvar esses parâmetros no arquivo guardiankey.class.php ou guardiankey.py, você pode fazer uso dele, como nos seguintes códigos:

 <?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."

Nota: Seu sistema deve enviar até mesmo as tentativas de login não autorizadas (login / pass não correspondem). GuardianKey será executado se você não enviar tal evento, no entanto, esta informação é útil para o nosso Aprendizado de Máquina procedimentos e proporcionar uma melhor experiência de visualização.

Criando seu próprio código para enviar eventos

O GuardianKey basicamente requer as informações sobre o endereço IP do cliente, o User-Agent enviado pelo navegador do usuário e se o login falhou no sistema. Essas informações estão disponíveis na solicitação do usuário e na rotina de verificação do sistema.

Abaixo apresentamos um exemplo usando a linguagem PHP.

 <?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;
*/

Evitando inundação de eventos

Quando um sistema recebe um ataque de força bruta, é comum que o mesmo envie para o GuardianKey muitos eventos. O GuardianKey conta com um avançado sistema de detecção de força bruta. Quando um ataque desse é detectado, o GuardianKey retorna “1” no campo “response_cache” do json de resposta do evento. Com isso, você pode por exemplo colocar o IP do atacante em uma “blacklist”, descartando e/ou bloqueando os acessos vindos desse IP.

Detalhes sobre a estrutura de dados JSON

A tabela abaixo descreve os campos JSON usados para enviar eventos para GuardianKey.

Recebendo notificações

  Você tem dois modos para receber notificações: via e-mail ou Webhook.

Recebendo via e-mail

  Se você deseja receber notificações por e-mail, basta configurar as informações do SMTP em sua conta no painel GuardianKey (https://panel.guardiankey.io).

Recebendo via webhook

  Você pode receber notificações via webhook. Esse método permite que você personalize o tratamento da notificação: Envie para um banco de dados, notifique os usuários por outros métodos, etc.

  Para isso, você precisa hospedar a página que recebe um json do GuardianKey e indicar no painel GuardianKey (ou no registrador) a URL do seu webhook.     Por favor, veja a implementação de referência do webhook (em PHP):

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

A tabela abaixo descreve os campos JSON enviados de GuardianKey para webhook:

Você pode também usar uma chave de criptografia simétrica para receber os eventos em seu webhook de forma criptogradfada. Para usar dessa forma crie o endpoint do seu webhook contendo a rota “/crypt”, e utilize as chaves “KEY e IV” do seu Authgroup como chave.

Criando sua própria tela de confirmação

Por padrão, o GuardianKey envia um link para a tela de confirmação (para o usuário ver se reconhece o acesso ou não) usando o domínio “guardiankey.io”. Você pode querer hospedagem desta tela em seu domínio (o que dá ao usuário mais credibilidade). Para isso você tem que seguir os seguintes passos:

• Você precisará de um servidor web (executando PHP, por exemplo) e, nesse servidor web, você configurará o webhook e a tela de confirmação. No endereço abaixo você encontrará os arquivos de referência (webhook.php e viewresolveevent.php). https://github.com/guardiankey/guardiankey-api-php
• Nas opções de arquivo “guardiankey.class.php”, você define a opção “resolveEventURL” como URL da sua tela para resolver eventos.
• Você configura sua ação do webhook para enviar ao usuário o link da sua tela de confirmação e no link a ser enviado ao usuário que você adicionar como parâmetros: eventId e event_token. Ex: https: //xxxxxxxxxx.com/viewresolveevent.php?e=<<\eventId>&t=<event_token>
• Finalmente, na tela de confirmação, você recuperará as informações do evento e enviará a resposta do usuário via API para GuardianKey, como no arquivo viewresolveevent.php.

Detalhes da criptografia

Utilizamos um algoritmo de criptografia simétrica para assinatura, autenticação e confidencialidade protegida dos eventos. Os sistemas devem enviar o authgroupID e o JSON criptografados no envio de eventos, como no exemplo abaixo (no caso do UDP):

authgroupID|cipher text (JSON) 

Se usar a interface REST, o evento será enviado como JSON:

id: authgroupID
data: cipher text (JSON)

A tabela abaixo apresenta detalhes sobre a criptografia usada.

Referências úteis

• PHP API implementação de referência – https://github.com/guardiankey/guardiankey-api-php/
• Python API implementação de referência – https://github.com/guardiankey/guardiankey-api-python/
• Obtendo ajuda no grupo de discussão – https://groups.google.com/forum/#!forum/guardiankey
• Plugins já implementados
• Entre em contato com os desenvolvedores