Guia do Demoiselle Audit
Demoiselle Audit
Paulo Gladson Ximenes Pinheiro
Clóvis Lemes Ferreira Júnior
Demoiselle Audit .................................................................................................................... v
1. Auditor ............................................................................................................................ 1
1.1. Auditor de Persistência .............................................................................................. 1
1.2. Auditor de Visão ....................................................................................................... 1
1.3. Criando seu próprio Auditor ......................................................................................... 1
2. Processor ........................................................................................................................ 3
2.1. Processor REST ....................................................................................................... 3
2.2. Processor MONGO ...................................................................................................
2.3. Criando seu próprio Processor .....................................................................................
3. Configurações do Audit ......................................................................................................
3.1. Instação no Projeto ...................................................................................................
3
4
5
5
3.2. Configurações do Sistema .......................................................................................... 5
3.2.1. PersistenceAuditor .......................................................................................... 6
3.3. Dashboard .............................................................................................................. 6
3.3.1. Como instalar o Dashboard ............................................................................... 7
4. Exemplo .......................................................................................................................... 9
5. Recomendações .............................................................................................................. 11
6. Release Notes ................................................................................................................. 13
iii
iv
Demoiselle Audit
O Demoiselle Audit foi criado para suprir uma necessidade que a comunidade tinha de uma forma de historiar
os eventos das aplicações desenvolvidas com o Framework Demoiselle. Desde o inicio ainda na concepção do
componente buscamos as tecnologias, referências literárias e em padrões de mercado, as boas práticas e o que
informações seriam capazes de registrar um momento e torná-lo um insumo para uma possível auditoria.
Utilizamos duas fontes principais de referência o COBIT e o NIST. Sugerimos que essas fontes sejam usadas como
base para a implantação eficaz de um processo consistente para que em caso de auditoria a mesma seja válida.
O Demoiselle Audit é apenas uma peça no conjunto de procedimentos que garantem uma boa auditoria, apenas
o uso do componente não é suficiente em casos de ações judiciais, a confiabialidade e invioalabilidade devem ser
garantidas para que essas informações sejam consideradas relevantes.
O Demoiselle Audit é dividido em três módulos e uma implementação de um dashboard para auxilio no
desenvolvimento.
1. Core
Principal módulo do sistema funicona com um agregador para suportar a plugabilidade dos Auditores e
Processadores e tem mecanismo de tolerância a falha.
2. Auditores
O módulo responsável por observar e capturar as informações da aplicação e enviar para o Core. A
implementação de referência do Auditor fará a captura na camada de persistência da aplicação funcionando em
conjunto com o JPA coletando os dados logo após a operação de CRUD ter sido concluída.
3. Processadores
O módulo responsável pela conclusão do procedimento, ou seja ele tem a tarefa de persistir o elemento trilha. A
implementação de referência do Processador envia para um serviço REST, mas podem haver implementações
onde são enviados para um banco NoSQL, o mesmo banco da aplicação ou até mesmo um serviço de
mensageria.
4. Dashboard
Esta implementação não faz parte do mecanismo de funcionamento do Demoiselle Audit, mas serve como
ferramenta de apoio à implantação e desenvolvimento do componente, ela consiste em quatro formas de
visualizações dos dados persistidos pelo Demoiselle Audit e contém um serviço REST que recebe a trilha gerada
pela implementação de referência do Processador, servindo de apoio à implantação do componente.
NIST
v
Demoiselle Audit
Arquitetura da ferramenta Demoisele Audit.
Funcionamento da ferramenta Demoisele Audit.
vi
Auditor
O objetivo dos Auditors é estabelecer a camada que será auditada, atualmente exste dois Auditors: camada de
Persistência chamada PersistenceAuditor e para Visão chamado ViewAuditor.
Um Auditor tem como objetivo executar a coleta de dados, preenchimento do objeto Trail com dados e disparar
evento para o Processors.
Os dados coletados pelos Auditor são:
• Quem fez a operação?
• Horário da operação?
• IP de origem
• Nome do Sistema
• O que foi realizado?
• Qual objeto foi manipulado?
• Quais foram os dados atingidos pela operação?
1.1. Auditor de Persistência
Para utilizar esse Auditor é necessário adicionar no pom.xml do seu projeto o seguinte trecho:
<dependency>
<groupId>br.gov.frameworkdemoiselle.component.audit</groupId>
<artifactId>demoiselle-audit-auditors-persistence</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
1.2. Auditor de Visão
Para utilizar esse Auditor é necessário adicionar no pom.xml do seu projeto o seguinte trecho:
<dependency>
<groupId>br.gov.frameworkdemoiselle.component.audit</groupId>
<artifactId>demoiselle-audit-auditors-view</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
1.3. Criando seu próprio Auditor
Se você tiver interesse em auditar outra camada da sua aplicação você deverá:
1. Criar um projeto Maven e utilizar o parent no seu pom.xml
1
Capítulo 1. Auditor
<parent>
<groupId>br.gov.frameworkdemoiselle.component.audit</groupId>
<artifactId>demoiselle-audit-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
2. Criar
uma
classe
que
extenda
br.gov.frameworkdemoiselle.component.audit.implementation.auditors.AbstractAuditor;
de
3. Implementar os métodos que irão interceptar o ciclo de vida da camada;
4. Criar um objeto do tipo Trail e preencher seus dados básicos;
5. Chamar o método da consume([Objeto Trail]);
6. Caso seu Processor precise ser configurado, você deverá criar uma Classe que utilize a funcionalidade
@Configuration do Demoiselle Demoiselle
Configuration [http://demoiselle.sourceforge.net/docs/
framework/reference/2.4.0/html/configuracao.html], como exemplo você poderá se basear na classe impl/
processors/rest/src/main/java/br/gov/frameworkdemoiselle/component/audit/processors/rest/RESTConfig.java
Apartir desse momento o componente estará apto a repassar esse objeto para os Processors definidos no
pom.xml do seu projeto.
Na sua implementação do seu sistema você deverá informar as seguintes informações:
Tabela 1.1. Configurações
Dado
Local de Preenchimento
Profile
user.setAttribute("PROFILE", [Profile/Perfil do usuário no sistema])
Where
user.setAttribute("IP", [IP do usuário no sistema])
UserName
user.setAttribute("NAME", [Login/Nome/Identificador do usuário no sistema])
Maiores informações no link Demoiselle
Security [http://demoiselle.sourceforge.net/docs/framework/
reference/2.4.0/html/security.html]
Um exemplo de um Auditor esta na classe impl/auditors/persistence/src/main/java/br/gov/frameworkdemoiselle/
component/audit/auditors/persistence/PersistenceAuditor.java
2
Processor
Um Processor tem como finalidade dar um destino que você deseja para o objeto que representa a trilha de auditoria.
Atualmente estamos disponibilizando um Processor de REST para atender a questão de ser multi-sistema e outro
Processor para MONGO.
2.1. Processor REST
Para utilizar esse Processor é necessário adicionar no pom.xml do seu projeto o seguinte trecho:
<dependency>
<groupId>br.gov.frameworkdemoiselle.component.audit</groupId>
<artifactId>demoiselle-audit-processors-rest</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
Para o correto funcionamento é necessário adicionar no demoiselle.properties as seguintes configurações:
Tabela 2.1. Configuração demoiselle.properties
Chave
Descrição
frameworkdemoiselle.audit.processor.rest.server.url
URL do serviço REST para o envio das trilhas.
2.2. Processor MONGO
Para utilizar esse Processor é necessário adicionar no pom.xml do seu projeto o seguinte trecho:
<dependency>
<groupId>br.gov.frameworkdemoiselle.component.audit</groupId>
<artifactId>demoiselle-audit-processors-mongo</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
Para o correto funcionamento é necessário adicionar no demoiselle.properties as seguintes configurações:
Tabela 2.2. Configuração demoiselle.properties
Chave
Descrição
frameworkdemoiselle.audit.processor.mongo.server.url
URL
do
servidor
onde
se
onde
se
encontra o MongoDB
frameworkdemoiselle.audit.processor.mongo.database.name
URL
do
servidor
encontra o MongoDB
frameworkdemoiselle.audit.processor.mongo.collection.name
Nome da coleção
frameworkdemoiselle.audit.processor.mongo.database.user
Usuário (se necessário)
frameworkdemoiselle.audit.processor.mongo.database.password
Senha
3
Capítulo 2. Processor
2.3. Criando seu próprio Processor
Você poderá criar o seu próprio ponto de extensão, podendo ser um JMS, FTP, Banco de Dados NoSql, você tem a
liberdade de criar, para que isso sejá possível você deve criar um projeto Maven e utilizar o parent no seu pom.xml:
1. Criar um projeto Maven e utilizar o parent no seu pom.xml
<parent>
<groupId>br.gov.frameworkdemoiselle.component.audit</groupId>
<artifactId>demoiselle-audit-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
</parent>
2. Criar
uma
classe
que
extenda
de
br.gov.frameworkdemoiselle.component.audit.implementation.processor.AbstractProcessor e implementar o
método public void execute(@Observes @AuditProcessor Trail trail)
3. É dentro do bloco de código você implementará o destino que você deseja dar ao objeto Trail.
4. Para o bom funcionamento do seu Processor você deverá seguir as seguintes recomendações:
5. Antes de implementar seu código é necessário chamar o método super.execute(trail) para que o componente
possa saber qual é a classe do Processor que esta sendo processada, isso é necessário para a situação de falha
na execução do seu Processor e o componente possa reprocessar novamente no futuro;
Quando houver algum tratamento de exceção no seu código como blocos try e catch você deverá além de realizar
seu próprio tratamento a chamada do método fail([String com a mensagem de Erro], [Objeto Trail]); para que o
componente possa reprocessar novamente no futuro;
4
Configurações do Audit
O Demoseille Audit possui como base 3 módulos (Core, Processors e Auditors). O Core orquestra a integração
entre os Processadores e os Auditores, que são implementações de cada projeto.
3.1. Instação no Projeto
Em seu projeto que você deseja auditar, você deve adicionar no seu pom.xml no campo de dependências do
projeto as seguintes linhas:
<dependencies>
<dependency>
<groupId>br.gov.frameworkdemoiselle.component.audit</groupId>
<artifactId>demoiselle-audit-auditors-persistence</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>br.gov.frameworkdemoiselle.component.audit</groupId>
<artifactId>demoiselle-audit-auditors-view</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>br.gov.frameworkdemoiselle.component.audit</groupId>
<artifactId>demoiselle-audit-processors-rest</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
<dependency>
<groupId>br.gov.frameworkdemoiselle.component.audit</groupId>
<artifactId>demoiselle-audit-processors-mongo</artifactId>
<version>1.0.0-SNAPSHOT</version>
</dependency>
</dependencies>
No código acima estamos utilizando o Auditor para a camada de Persistência e para a camada de Visão e o
Processor para REST e o Processor para MONGO, você poderá adicionar quantos Processors e quantos Auditors
você quiser.
3.2. Configurações do Sistema
No seu arquivo demoiselle.properties você precisará adicionar as seguintes linhas:
Tabela 3.1. Configuração demoiselle.properties
Chave
Descrição
frameworkdemoiselle.audit.system
Nome do seu Sistema
frameworkdemoiselle.audit.scheduler.repeat.interval
Intervalo
de
tempo
em
milisegundos
para
o
reprocessamento das trilhas
frameworkdemoiselle.audit.scheduler.start.time
Tempo em milisegundos de quando será executado o
primeiro reprocessamento após o inicio da aplicação
5
Capítulo 3. Configurações do ...
Chave
Descrição
frameworkdemoiselle.audit.folder.fail.objects
Pasta onde a aplicação terá direito de escrita e leitura
para o armazenamento das trilhas que apresentaram
problemas no processamento
Para o Processor de REST você deverá adicionar a seguinte linha:
Tabela 3.2. Configuração demoiselle.properties
Chave
Descrição
frameworkdemoiselle.audit.processor.rest.server.url
Endereço do Serviço REST (Ex.: http://localhost:8080/
dash)
Para o Processor de MONGO você deverá adicionar a seguinte linha:
Tabela 3.3. Configuração demoiselle.properties
Chave
Descrição
frameworkdemoiselle.audit.processor.mongo.server.url
Endereço do MongoDB
frameworkdemoiselle.audit.processor.mongo.database.name
Nome do Database
frameworkdemoiselle.audit.processor.mongo.collection.name
Nome da Coleção
frameworkdemoiselle.audit.processor.mongo.database.user
Usuário (se necessário)
frameworkdemoiselle.audit.processor.mongo.database.password
Senha
3.2.1. PersistenceAuditor
Você poderá escolher quais serão suas Entidades JPA que serão auditadas na camada de persistência, para isso
adicione a anotação do JPA @EntityListeners com o valor de PersistenceAuditor.class.
Exemplo :
@Entity
@EntityListeners(value = PersistenceAuditor.class)
public class Bookmark implements Serializable {
...
}
3.3. Dashboard
Para facilitar a busca de informações do que foi feito no sistema contruímos um Dashboard que traz 4 visões
diferentes dos mesmos dados:
• Visão de Sistema que se aprofunda em Pessoa e a Funcionalidade executada;
• Visão da Pessoa que se aprofunda no Sistema e a Funcionalidade executada;
• Visão de Funcionalidade que se aprofunda no Sistema e a Pessoa que executou;
• Visão de Rastreamento que através de filtros como Sistema, Objeto e Identificador do Objeto mostrar o histórico
de operações realizadas no Objeto;
6
Como instalar o Dashboard
O Dashboard também fornece um serviço de REST para o Processor RESTProcessor, caso você utilize este
processor no seu projeto e não queira implementar seu próprio serviço de REST você poderá utilizar o Dashboard
para essa finalidade.
3.3.1. Como instalar o Dashboard
Faça um clone do projeto e acesse a pasta demoiselle-audit/impl/dashboard, você precisará alterar o arquivo
persistence.xml de acordo com as configurações do seu banco de dados onde serão armazenados as trilhas de
auditoria, após feito essa configuração abra um terminal na pasta do "dashboard" e execute o comando maven:
$mvn clean compile package
Esse comando irá gerar um arquivo chamado demoiselle-audit-dashboard.war na pasta target. Agora que você já
tem o arquivo .war você poderá fazer o deploy no seu servidor.
7
8
Exemplo
Você encontrará no link para o projeto BookmarkAudit [https://github.com/demoiselle/laboratory/tree/master/
examples/bookmark-audit] que utiliza o componente de auditoria;
9
10
Recomendações
Por se tratar de um componente de auditoria alguns pontos devem ser observados:
• O servidor onde serão armazenadas as trilhas de auditoria deverá ser blindado e com acesso restrito para que
seja garantida a confiabilidade das informações armazenadas;
• Seguir as recomendações do NIST no link [http://csrc.nist.gov/publications/nistpubs/800-92/SP800-92.pdf]
11
12
Release Notes
Dica
Para reportar problemas, abrir discussões ou perguntar algo utilize as Issues do GitHub no
endereço https://github.com/demoiselle/audit/issues .
Versão 1.0.0
•
13
14