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

<– Return to plugins

No painel de administração do GuardianKey você pode configurar preferências para o mecanismo de detecção e visualize seus riscos, eventos e comportamentos de interação do usuário.

Nesta página, fornecemos uma breve documentação sobre o nosso painel.

** As imagens podem ser ampliadas clicando nelas. **

Conteúdo

Acessando pela primeira vez

Login page O painel de administração pode ser acessado via Web, no seguinte URL:

https://panel.guardiankey.io

Informamos que também temos uma versão “in company”. Nesse caso, o painel seria hospedado em seu ambiente.

Você pode usar os dados de login da sua conta se já tiver crie uma nova conta. Se você estiver usando um plug-in, ele pode ter criado uma conta para você por meio da API.

Home A interface do painel é fácil e intuitiva. O menu principal é dividido em as seguintes partes funcionais:

  • Dashboards: é possível ter uma visão geral orientada para riscos, eventos ou geográficos.
  • Explore: você pode pesquisar e explorar eventos e usuários.
  • Settings: você pode criar organizações, grupos de autenticação e políticas, para serem usados pelo mecanismo de detecção.

Clicando em usernames, é possível ver detalhes sobre isso.

Início Se você ainda não tiver eventos coletados, deverá ver algumas instruções para fazer o GuardianKey rodar na primeira página, após o login (última tela). Caso contrário, você verá alguns links para visualizar seus dados (captura de tela à direita).

Abaixo, fornecemos detalhes sobre os recursos mencionados.

Criando uma nova conta

Uma conta para você deve ser criada automaticamente por meio da API se você tiver usado um ** plugin ** fornecido por nós. Neste caso, você deve ter recebido um e-mail com os detalhes de acesso.

Se você não instalou nenhum plugin, você tem para criar uma conta e configurar seus sistemas para enviar eventos para os servidores da GuardianKey.

Registrando Nesse caso, acesse o formulário de registro em https://panel.guardiankey.io/auth/register e siga as instruções.

Recuperando a senha

Para recuperar a senha de uma conta no painel do GuardianKey, você deve acessar o link https://panel.guardiankey.io/auth/forgotpass , digite seu endereço de e-mail e siga as instruções deve ser enviado via e-mail.

NOTA: O e-mail de recuperação pode ser considerado como SPAM, portanto, dê uma olhada na sua pasta de spam. Os servidores mantidos pela Microsoft (Outlook, Hotmail, MSN, Live, etc.) geralmente abandona o e-mail sem enviá-lo para uma pasta de spam. Se for o seu caso, você deve incluir nosso e-mail “admin@guardiankey.io” na lista de remetentes seguros, no menu de configuração do seu serviço de e-mail. No URL externo abaixo, você pode encontrar as etapas para estes procedimentos.

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

Conceitos básicos

O GuardiaKey processa os eventos de autenticação enviados pelos seus sistemas para o nosso mecanismo para detectar atividades maliciosas e proteger seus sistemas contra ataques.

Uma conta em nosso painel pode administrar muitas “organizations” e muitas “policies”. Uma “organization” pode ter muitos grupos de autenticação “authgroups”.

  • Organization: pode ter muitos authgroups e políticas.
  • Authgroup: é basicamente um conjunto de usuários submetidos a uma política e uma preferência de resposta Um usuário é único em um authgroup.
  • Policy: basicamente, são os limites de risco para definir o que fazer com base nos níveis de risco.

O GuardianKey é orientado pelo risco. Esse recurso fornece uma visão realista sobre a relevância dos eventos em seus sistemas. Além disso, permite acoplar as saídas de risco e estrutura de risco da organização.

O GuardianKey calcula um risco para cada evento e recomenda seu sistema uma resposta, com base nos limiares configurados na política. Existem as seguintes respostas:

  • Accept: risco muito baixo, apenas permitir o acesso e log.
  • Notify: permitir a ação do usuário e notificar o usuário sobre o acesso (por exemplo, via e-mail).
  • Hard notify: requer uma ação extra para o usuário permitir o acesso. Por exemplo, exigindo o uso de um segundo fator de autenticação. O usuário também será notificado para esse acesso.
  • Block: bloquear a ação do usuário e não notificar o usuário. Isso deve ser usado apenas para altos riscos.

Eventos podem ter os seguintes estados:

  • Pending: foi notificado ao usuário e é necessária uma ação do usuário para marcá-lo como resolvido.
  • Resolved: o evento foi aceito, bloqueado ou resolvido pelo usuário (via e-mail) ou pelo administrador (via painel).

Dashboards

O painel de administração do GuardianKey, atualmente, fornece os seguintes painéis de controle:

Risk dashboard
  • Risk: fornece informações sobre o risco aceito, mitigado e pendente. O risco aceito é a soma de todos os eventos abaixo do “aceitar” limite. Risco mitigado é o risco relacionado aos eventos bloqueados e eventos ameaçados. O risco pendente é a soma dos riscos do evento dos eventos notificados.

Geographic dashboard - Event: fornece informações sobre o número de eventos, com base em cada tipo de resposta.
- Geographic: fornece os eventos traçados no mapa do mundo.

Em todos os painéis, você pode escolher o período de tempo para criar os gráficos e tabelas.

Atualmente, não é possível criar painéis personalizados. No entanto, você pode enviar os eventos processados para seu aplicativo de análise (por exemplo, um SIEM) e visualize os dados integrados a outros registros de sua organização. Isso pode ser feito criação de ganchos da Web.

Explorando eventos e usuários

Explorando eventos No menu “Explorar” é possível pesquisar e explorar usuários e eventos. Basta definir as opções de pesquisa no formulário de pesquisa e clique no botão “Filtrar”.

Explorando detalhes do usuário Em qualquer lugar do painel, você pode clicar no nome de usuário para abrir detalhes sobre o usuário específico. Nesta página, há os eventos e comportamentos personalizados do usuário relacionado.


Alterar as configurações de senha e perfil

Mudando o perfil Para alterar as configurações da conta no painel de administração, basta clicar sobre o nome de usuário no canto superior direito e, em seguida, perfil.

Configurações do mecanismo

No painel, você também pode alterar as preferências de detecção. Abaixo, apresentamos como.

Organizações

Organizações Você pode visualizar, editar, excluir, criar novos e reivindicar autoridade sobre as organizações.

“Reivindicar uma organização” é usado para fornecer ao usuário a administração acesso sobre uma organização, incluindo suas políticas e grupos de autoria.

Isso pode ser necessário se você já tiver uma organização criada e deseja ter acesso a ele usando outra conta. Não vai revogar o acesso do último usuário, basta incluir o acesso para o novo.

Políticas

Atualizando uma política Ao definir uma política, você deve definir três limites:

  • “Notify threshold”: os eventos serão aceitos abaixo e serão notificados acima.
  • “Hard notify threshold”: Para eventos com risco acima desse valor, será sugerido ao sistema que exija mais ações do usuário (por exemplo, um fator de autenticação extra).
  • “Block threshold”: acima desse limite, a ação do usuário será bloqueada. Usuário não será notificado sobre isso via e-mail.

Authgroups

Verificando as informações de implantação de um authgroup Um authgroup é, talvez, a entidade mais importante na sua configuração. Os eventos devem ser enviados para um authgroup. Algumas informações são necessárias para configurar seus sistemas para enviar eventos para GuardianKey, basicamente: KEY, IV, organizationID e o authgroupID. Essas informações podem ser encontradas na guia “Implantar informações”.

Informações sobre um authgroup Usuários são únicos em um authgroup. Além disso, aqui, você deve configurar a política e as opções de notificação. O nome e a descrição de um authgroup são usados ​​apenas para sua referência.

Guia Alerta, em um authgroup Na aba “Alertas”, você deve configurar como seus usuários devem ser notificados se o nível de risco do evento estiver em um nível de risco notificável. O GuardianKey suporta as seguintes opções:

  • E-mail via seu SMTP: usado para enviar notificações de eventos para seus usuários por meio de um servidor de correspondência fornecido por você. Você pode usar uma conta do Gmail, por exemplo.
  • Web hook: neste caso, o GuardianKey processará os eventos para calcular seu risco e enviá-los via REST usando o “Web hook URL”, inserido por você no formulário. Isso é particularmente útil para coletar os eventos em seu sistema de registro. A resposta deve ser feita ao seu lado. Existem exemplos em nosso GitHub para implementar o serviço webhook em seu servidor de aplicativos da web. Alguns plugins já implementam um web hook para receber e lidar com os eventos processados.

Abaixo, fornecemos mais detalhes sobre cada caso de notificação.

Configurar para enviar e-mails para meus usuários

Com base nas suas configurações, o GuardianKey pode notificar seus usuários via e-mail sobre acesso arriscado em suas contas em seus sistemas.

Nesse caso, você deve fornecer um servidor SMTP para esses e-mails. Para evitar problemas com filtros de spam, não enviamos e-mails diretamente.

Existem muitas opções para resolver isso, como:

  1. Você pode permitir que o IP do nosso servidor faça retransmissões em seu servidor SMTP e insira o endereço IP do seu servidor de retransmissão SMTP;
  2. Se todos os e-mails dos usuários tiverem o mesmo nome de domínio, basta informar o MX desse domínio.
  3. Você pode criar uma conta em um serviço de envio gratuito, como o GMail, e inserir os dados da conta no GuardianKey;

Se você escolher as opções 1 ou 2, deverá inserir a edição do seu grupo de permissões:

  • Método de notificação: E-mail
  • Host SMTP: seu IP do servidor de retransmissão SMT ou o IP do MX
  • Porto: 25
  • Método SMTP: clear

Se você escolher 3, poderá criar uma conta no GMmail (por exemplo), ** exclusiva ** para essa finalidade e definir:

  • Notify method: E-mail
  • SMTP sender: O endereço do GMail
  • SMTP host: smtp.gmail.com
  • SMTP user: O endereço do GMail
  • SMTP pass: a senha
  • SMTP port: 465
  • SMTP method: SSL

NOTA: Você pode precisar manter uma senha de uma conta de e-mail em nossos sistemas, assim, não use sua conta pessoal! Crie uma conta exclusiva para este fim, sem qualquer outro uso. Em qualquer caso, você pode personalizar o e-mail a ser enviado aos usuários no formulário de edição do authgroup.

Configurar para enviar eventos processados para mim, via Web hook

Com base nas suas configurações, o GuardianKey pode enviar os eventos processados aos seus sistemas via REST (webhook). Em seus sistemas, você pode notificar seus usuários, criar logs e realizar algumas análises de dados sobre os eventos.

Nesse caso, você deve implementar e hospedar um serviço Web (REST) e insira o URL no formulário do authgroup.

Alguns plugins fornecidos por nós já implementam um webservice. Você também pode dar uma olhada no nosso GitHub para ver um código de exemplo, em https://github.com/pauloangelo/guardiankey-api-php .

  • Método de notificação: gancho da Web
  • URL do Web hook: o URL

Em qualquer caso, você pode personalizar o e-mail a ser enviado aos usuários no formulário de edição do authgroup.

Obtenha ajuda ou tire suas dúvidas sobre o GuardianKey na nossa lista:

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

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 usando a API;
  2. Seu sistema usa as informações recebidas na etapa de registro para enviar tentativas de login ao GuardianKey (na nuvem);
  3. O GuardianKey processa os eventos com algoritmos de Machine Learning 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 é feito através de um servidor web, que suporta REST e XML-RPC;   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 registering code and the class
$ wget https://github.com/pauloangelo/guardiankey-api-php/archive/master.zip

$ unzip master.zip
# run the code for registering
$ 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'




Links Úteis:

Acessando a API para registrar

O registro é realizado nas seguintes etapas:

  • ** Passo 1 **: cliente (você ou seu sistema) cria uma CHAVE e IV (Vetor de Inicialização). Além disso, você pode registrar os métodos de notificação;
  • ** Etapa 2 **: o cliente invoca a função de registro do servidor da GuardianKey com os parâmetros KEY / IV e um e-mail administrativo; e
  • ** Etapa 3 **: o servidor salva as informações enviadas e retorna um authgroupID, que deve ser usado para enviar eventos.

Nossa implementação de API de referência já fornece essas etapas implementadas. Em tais casos, o processo de interação é muito simples.

Para criar um authgroupID, você também pode executar nosso código disponível no GitHub e descrito na seção para as pessoas impacientes.

Observamos que, após o registro, você precisa enviar eventos. Os procedimentos também são descritos abaixo.

Implementando seu próprio código para registrar

Se você quiser usar GuardianKey usando outra linguagem de programação ou quer criar seu próprio código, você pode interagir diretamente com a API do GuardianKey para registrar via REST.

Os códigos abaixo fornecem exemplos para o registro 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)



** Nota: ** Convidamos você a compartilhar seu código para outros idiomas ou plugins de sistemas. Basta publicar no GitHub e nos avisar enviando um e-mail (veja a página de contato).

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 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”, “EXTRAREQUIREMENT” 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.

Modo Vantagens
UDP (async) rápido
REST (sync) Habilita bloqueio de acesso

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

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

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

Detalhes sobre a estrutura de dados JSON

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

Field Description
generatedTime geração de evento em unix timestamp (ex. 1527075751)
agentId agentid para identificar exclusivamente o agente. Se você tiver apenas um agente, use o authGroupID
organizationId na maioria dos casos, use o mesmo authGroupId(ex. 7d97e98f8af…9e0ee507c4)
authGroupId string retornada pela função de registro (ex. 7d97e98f8af…9e0ee507c4)
service referência de texto para o seu sistema web, a sua escolha (ex. NextCloud)
eventType Tipo de evento (autenticação ou acesso incorreto (futuro))
clientIP o IP (v4 ou v6) usado pelo usuário que está tentando acessar (por exemplo, 123.123.123.123)
clientReverse dns reverso do clientIP(ex. 123.123.123.123.ispdomain.com)
userName o nome de login do usuário usado no sistema (ex. john)
userEmail o e-mail do usuário (ex. john@company.com), necessário apenas se seus usuários devem ser notificados por acessos suspeitos
loginFailed 0 se usuário/senha corresponder e 1 caso contrário(ex. 0)
userAgent o cabeçalho completo do User-agent enviado pelo navegador do usuário (ex. “Mozilla/5.0 (Windows NT 6.1) … Safari/537.”)
sequential número seqüencial para evitar ataques de replay
authMethod usado para alguns serviços que permite que esses recursos, na maioria dos casos, deixem em branco
psychometricTyped em desenvolvimento, deixe em branco
psychometricImage em desenvolvimento, deixe em branco

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/pauloangelo/guardiankey-api-php/blob/master/webhook.php

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

Campo Descrição
generatedTime Data e hora em unixtime da geração do eventos (ex. 1527075751)
message_contextual Mensagem amigável sobre a notificação
userName Nome de usuário usado
agentId AgentID de serviço
eventId ID do evento
risk_level Nível de risco
serviço Nome do serviço
clienteIP IP utilizado no acesso
asn Sistema Autônomo Número de acessos
clientReverse DNS reverso do IP o acesso
client_ua Useragent de acesso
client_device Dispositivo do cliente
client_os Os usados ​​
país País de acesso
região Região de acesso
cidade Cidade de acesso
country_code Código do país
latitude Posição de latitude do acesso
longitude Posição de longitude do acesso
risk_value Risco de Valor
authMethod Implementação futura
event_response Resposta de GuardianKey
message_intel Informação de inteligência de ameaça
authGroupId AuthgroupID do agente
organizationId ID da organização
message_psychometric Informação Psicométrica (futuro)

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.

Parameter Value
algoritmo de criptografia AES
comprimento da chave 256
modo de cifra de bloco CFB
tamanho do segmento 8

Referências úteis