Como usar a biblioteca de processamento do CloudTrail - AWS CloudTrail
Requisitos mínimosProcessamento de logs do CloudTrailTópicos avançadosRecursos adicionais

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Como usar a biblioteca de processamento do CloudTrail

A Biblioteca de processamento do CloudTrail é uma biblioteca Java que fornece uma maneira simples de processar logs do AWS CloudTrail. Forneça detalhes de configuração sobre a sua fila do SQS do CloudTrail e escreva o código para processar eventos. A Biblioteca de Processamento do CloudTrail cuida do resto. Ela consulta a sua fila do Amazon SQS, lê e analisa as mensagens da fila, faz downloads de arquivos de log do CloudTrail, analisa eventos nos arquivos de log e passa os eventos para o seu código como objetos Java.

A Biblioteca de Processamento do CloudTrail é altamente escalável e tolerante a falhas. Ela lida com processamento paralelo de arquivos de log para que você possa processar quantos logs precisar. Ela lida com falhas de rede relacionadas a limites de tempo da rede e recursos inacessíveis.

O tópico a seguir mostra como usar a Biblioteca de Processamento do CloudTrail para processar logs do CloudTrail em seus projetos Java.

A biblioteca é fornecida como um projeto de código aberto licenciado para Apache, disponível no GitHub: https://github.com/aws/aws-cloudtrail-processing-library. O código-fonte da biblioteca inclui código de exemplo que você pode usar como base para os seus próprios projetos.

Requisitos mínimos

Para usar a Biblioteca de Processamento do CloudTrail, é necessário ter o seguinte:

Processamento de logs do CloudTrail

Para processar logs do CloudTrail na sua aplicação Java:

  1. Adicionar a Biblioteca de Processamento do CloudTrail ao seu projeto

  2. Configurar a Biblioteca de Processamento do CloudTrail

  3. Implementar o processador de eventos

  4. Instalar e executar o executor de processamento

Adicionar a Biblioteca de Processamento do CloudTrail ao seu projeto

Para usar a Biblioteca de Processamento do CloudTrail, adicione-a ao classpath do seu projeto Java.

Adicionar a biblioteca a um projeto Apache Ant

Para adicionar a Biblioteca de Processamento do CloudTrail a um projeto Apache Ant

  1. Baixe ou clone o código-fonte da Biblioteca de Processamento do CloudTrail do GitHub:

  2. Crie o arquivo .jar a partir do código-fonte, conforme descrito na seção README (LEIA-ME):

    mvn clean install -Dgpg.skip=true

  3. Copie o arquivo .jar resultante para o seu projeto e adicione-o ao arquivo build.xml do projeto. Por exemplo:

    
<classpath>
  <pathelement path="${classpath}"/>
  <pathelement location="lib/aws-cloudtrail-processing-library-1.6.1.jar"/>
</classpath>

Adicionar a biblioteca a um projeto Apache Maven

A Biblioteca de Processamento do CloudTrail está disponível para o Apache Maven. Você pode adicioná-la ao seu projeto escrevendo uma única dependência no arquivo pom.xml do seu projeto.

Para adicionar a Biblioteca de Processamento do CloudTrail a um projeto Maven

  • Abra o arquivo pom.xml do seu projeto Maven e adicione a seguinte dependência:

    
<dependency>
    <groupId>com.amazonaws</groupId>
    <artifactId>aws-cloudtrail-processing-library</artifactId>
    <version>1.6.1</version>
</dependency>

Adicionar a biblioteca a um projeto Eclipse

Para adicionar a Biblioteca de Processamento do CloudTrail a um projeto Eclipse

  1. Baixe ou clone o código-fonte da Biblioteca de Processamento do CloudTrail do GitHub:

  2. Crie o arquivo .jar a partir do código-fonte, conforme descrito na seção README (LEIA-ME):

    mvn clean install -Dgpg.skip=true

  3. Copie o aws-cloudtrail-processing-library-1.6.1.jar compilado para um diretório do seu projeto (normalmente, lib).

  4. Clique com o botão direito do mouse no nome do projeto no Project Explorer (Explorador de projetos) do Eclipse, escolha Build Path (Caminho do build) e escolha Configure (Configurar)

  5. Na janela Java Build Path (Caminho de build Java), escolha a guia Libraries (Bibliotecas).

  6. Selecione Adicionar JARs... e navegue até o caminho em que aws-cloudtrail-processing-library-1.6.1.jar foi copiado.

  7. Escolha OK para concluir a adição do .jar ao seu projeto.

Adicionar a biblioteca a um projeto IntelliJ

Para adicionar a Biblioteca de Processamento do CloudTrail a um projeto IntelliJ

  1. Baixe ou clone o código-fonte da Biblioteca de Processamento do CloudTrail do GitHub:

  2. Crie o arquivo .jar a partir do código-fonte, conforme descrito na seção README (LEIAME):

    mvn clean install -Dgpg.skip=true

  3. Em File, escolha Project Structure.

  4. Escolha Modules (Módulos) e escolha Dependencies (Dependências).

  5. Escolha + JARS or Directories (+ JARS ou diretórios) e acesse o caminho em que você criou o aws-cloudtrail-processing-library-1.6.1.jar.

  6. Escolha Apply (Aplicar) e escolha OK para concluir a adição do .jar ao seu projeto.

Configurar a Biblioteca de Processamento do CloudTrail

É possível configurar a Biblioteca de Processamento do CloudTrail ao criar um arquivo de propriedades de caminho de classe que é carregado no tempo de execução ou ao criar um objeto ClientConfiguration e definir as opções manualmente.

Fornecer um arquivo de propriedades

Você pode criar um arquivo de propriedades classpath que fornece opções de configuração ao seu aplicativo. O seguinte exemplo de arquivo mostra as opções que você pode definir:

# AWS access key. (Required)
accessKey = your_access_key

# AWS secret key. (Required)
secretKey = your_secret_key

# The SQS URL used to pull CloudTrail notification from. (Required)
sqsUrl = your_sqs_queue_url

# The SQS end point specific to a region.
sqsRegion = us-east-1

# A period of time during which Amazon SQS prevents other consuming components
# from receiving and processing that message.
visibilityTimeout = 60

# The S3 region to use.
s3Region = us-east-1

# Number of threads used to download S3 files in parallel. Callbacks can be
# invoked from any thread.
threadCount = 1

# The time allowed, in seconds, for threads to shut down after
# AWSCloudTrailEventProcessingExecutor.stop() is called. If they are still
# running beyond this time, they will be forcibly terminated.
threadTerminationDelaySeconds = 60

# The maximum number of AWSCloudTrailClientEvents sent to a single invocation
# of processEvents().
maxEventsPerEmit = 10

# Whether to include raw event information in CloudTrailDeliveryInfo.
enableRawEventInfo = false

# Whether to delete SQS message when the CloudTrail Processing Library is unable to process the notification.
deleteMessageUponFailure = false

Os seguintes parâmetros são obrigatórios:

  • sqsUrl - Fornece o URL para obter as suas notificações do CloudTrail. Se você não especificar esse valor, o AWSCloudTrailProcessingExecutor lança uma IllegalStateException.

  • accessKey - Um identificador exclusivo para a sua conta, como AKIAIOSFODNN7EXAMPLE.

  • secretKey - Um identificador exclusivo para a sua conta, como wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY.

Os parâmetros accessKey e secretKey fornecem as suas credenciais AWS para a biblioteca, permitindo que ela acesse AWS em seu nome.

O padrão para os outros parâmetros são definidos pela biblioteca. Para obter mais informações, consulte a Referência da Biblioteca de Processamento do AWS CloudTrail.

Criar uma ClientConfiguration

Em vez de definir opções nas propriedades do classpath, você pode fornecer opções ao AWSCloudTrailProcessingExecutor inicializando e definindo opções em um objeto ClientConfiguration, como mostra este exemplo:

ClientConfiguration basicConfig = new ClientConfiguration(
    "http://sqs.us-east-1.amazonaws.com/123456789012/queue2",
    new DefaultAWSCredentialsProviderChain());

basicConfig.setEnableRawEventInfo(true);
basicConfig.setThreadCount(4);
basicConfig.setnEventsPerEmit(20);

Implementar o processador de eventos

Para processar logs do CloudTrail, é necessário implementar um EventsProcessor que recebe os dados de log do CloudTrail. Este é um exemplo de nome de implementação: 

public class SampleEventsProcessor implements EventsProcessor {

    public void process(List<CloudTrailEvent> events) {
        int i = 0;
        for (CloudTrailEvent event : events) {
            System.out.println(String.format("Process event %d : %s", i++, event.getEventData()));
        }
    }
}

Ao implementar um EventsProcessor, você implementa o retorno de chamada process() que AWSCloudTrailProcessingExecutor usa para enviar eventos do CloudTrail para você. Os eventos são fornecidos em uma lista de objetos CloudTrailClientEvent.

O objeto CloudTrailClientEvent fornece CloudTrailEvent e CloudTrailEventMetadata que você pode usar para ler o evento do CloudTrail e as informações de fornecimento.

Esse exemplo simples imprime as informações de cada evento transmitido ao SampleEventsProcessor. Em sua própria implementação, você pode processar logs de acordo com a sua necessidade. O AWSCloudTrailProcessingExecutor continua enviando eventos ao seu EventsProcessor, desde que tenha eventos para enviar e ainda esteja em execução.

Instalar e executar o executor de processamento

Depois de criar um EventsProcessor e definir os valores de configuração para a Biblioteca de Processamento do CloudTrail (em um arquivo de propriedades ou usando a classe ClientConfiguration), você poderá usar esses elementos para inicializar e usar um AWSCloudTrailProcessingExecutor.

Para usar o AWSCloudTrailProcessingExecutor para processar eventos do CloudTrail

  1. Instanciar um objeto AWSCloudTrailProcessingExecutor.Builder. O construtor do Builder usa um objeto EventsProcessor e o nome de um arquivo de propriedades do caminho de classe.

  2. Chame o método de fábrica build() do Builder para configurar e obter um objeto AWSCloudTrailProcessingExecutor.

  3. Use os métodos do AWSCloudTrailProcessingExecutor start() e stop() para iniciar e encerrar o processamento de eventos CloudTrail.

public class SampleApp {
  public static void main(String[] args) throws InterruptedException {
    AWSCloudTrailProcessingExecutor executor = new
      AWSCloudTrailProcessingExecutor.Builder(new SampleEventsProcessor(),
        "/myproject/cloudtrailprocessing.properties").build();

    executor.start();
    Thread.sleep(24 * 60 * 60 * 1000); // let it run for a while (optional)
    executor.stop(); // optional
  }
}

Tópicos avançados

Filtrar os eventos a serem processados

Por padrão, todos os logs no bucket do S3 da sua fila do Amazon SQS e todos os eventos que eles contêm são enviados para o EventsProcessor. A Biblioteca de Processamento do CloudTrail fornece interfaces opcionais que você pode implementar para filtrar as origens usadas para obter os logs do CloudTrail e para filtrar os eventos que você tem interesse em processar.

SourceFilter

Você pode implementar a interface SourceFilter para escolher se deseja processar os logs de uma origem fornecida. SourceFilter declara um único método de retorno de chamada, filterSource(), que recebe um objeto CloudTrailSource. Para impedir que os eventos de uma origem sejam processados, retorne false de filterSource().

A Biblioteca de Processamento do CloudTrail chama o método filterSource() após a biblioteca consultar logs na fila do Amazon SQS. Isso ocorre antes de a biblioteca começar a filtragem de eventos ou o processamento de logs.

Este é um exemplo de nome de implementação:

public class SampleSourceFilter implements SourceFilter{
  private static final int MAX_RECEIVED_COUNT = 3;

  private static List<String> accountIDs ;
  static {
    accountIDs = new ArrayList<>();
    accountIDs.add("123456789012");
    accountIDs.add("234567890123");
  }

  @Override
  public boolean filterSource(CloudTrailSource source) throws CallbackException {
    source = (SQSBasedSource) source;
    Map<String, String> sourceAttributes = source.getSourceAttributes();

    String accountId = sourceAttributes.get(
      SourceAttributeKeys.ACCOUNT_ID.getAttributeKey());

    String receivedCount = sourceAttributes.get(
      SourceAttributeKeys.APPROXIMATE_RECEIVE_COUNT.getAttributeKey());

    int approximateReceivedCount = Integer.parseInt(receivedCount);

    return approximateReceivedCount <= MAX_RECEIVED_COUNT && accountIDs.contains(accountId);
  }
}

Se você não fornecer seu próprio SourceFilter, DefaultSourceFilter será usado, o que permite que todas as origens sejam processadas (o valor retornado é sempre true).

EventFilter

É possível implementar a interface EventFilter para escolher se um evento do CloudTrail é enviado para o seu EventsProcessor. O EventFilter declara um único método de retorno de chamada, filterEvent(), que recebe um objeto CloudTrailEvent. Para impedir que o evento seja processado, retorne false de filterEvent().

A Biblioteca de Processamento do CloudTrail chama o método filterEvent() após a biblioteca consultar logs na fila do Amazon SQS. e após a filtragem da fonte. Isso ocorre antes de a biblioteca começar o processamento de eventos para os logs.

Veja este exemplo de implementação:

public class SampleEventFilter implements EventFilter{

  private static final String EC2_EVENTS = "ec2.amazonaws.com";

  @Override
  public boolean filterEvent(CloudTrailClientEvent clientEvent) throws CallbackException {
    CloudTrailEvent event = clientEvent.getEvent();

    String eventSource = event.getEventSource();
    String eventName = event.getEventName();

    return eventSource.equals(EC2_EVENTS) && eventName.startsWith("Delete");
  }
}

Se você não fornecer seu próprio EventFilter, DefaultEventFilter será usado, o que permite que todos os eventos sejam processados (o valor retornado é sempre true).

Processar eventos de dados

Quando o CloudTrail processa eventos de dados, ele preserva os números em seu formato original, seja ele um inteiro (int) ou um float (um número que contém um decimal). Em eventos que têm inteiros nos campos de um evento de dados, o CloudTrail processou historicamente esses números como floats. Atualmente, o CloudTrail processa números nesses campos mantendo seu formato original.

Como prática recomendada, para evitar quebrar suas automações, seja flexível em qualquer código ou automação que você esteja usando para processar ou filtrar eventos de dados do CloudTrail e permita os números int e float formatados. Para obter melhores resultados, use a versão 1.4.0 ou superior da Biblioteca de Processamento do CloudTrail.

O snippet de exemplo a seguir mostra um número formatado float (2.0) para o parâmetro desiredCount no bloco de evento de dados ResponseParameters.

"eventName": "CreateService",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "000.00.00.00",
    "userAgent": "console.amazonaws.com",
    "requestParameters": {
        "clientToken": "EXAMPLE",
        "cluster": "default",
        "desiredCount": 2.0
...

O snippet de exemplo a seguir mostra um número formatado int (2) para o parâmetro desiredCount no bloco de evento de dados ResponseParameters.

"eventName": "CreateService",
    "awsRegion": "us-east-1",
    "sourceIPAddress": "000.00.00.00",
    "userAgent": "console.amazonaws.com",
    "requestParameters": {
        "clientToken": "EXAMPLE",
        "cluster": "default",
        "desiredCount": 2
...

Informar o progresso

Implemente a interface ProgressReporter para personalizar os relatórios de progresso da Biblioteca de Processamento do CloudTrail. O ProgressReporter declara dois métodos: reportStart() e reportEnd(), que são chamados no início e no fim das seguintes operações:

  • Consultar mensagens do Amazon SQS

  • Analisar mensagens do Amazon SQS

  • Processar uma fonte do Amazon SQS para logs do CloudTrail

  • Excluir mensagens do Amazon SQS

  • Baixar um arquivo de log do CloudTrail

  • Processar um arquivo de log do CloudTrail

Os dois métodos recebem um objeto ProgressStatus que contém informações sobre a operação executada. O membro progressState contém um membro da enumeração ProgressState que identifica a operação atual. Esse membro pode conter informações adicionais no membro progressInfo. Além disso, qualquer objeto que você retornar de reportStart() será transmitido para reportEnd(), a fim de que você possa fornecer informações contextuais, como o horário em que o evento começou a ser processado.

Veja a seguir um exemplo de implementação que fornece informações sobre quanto tempo uma operação levou para ser concluída:

public class SampleProgressReporter implements ProgressReporter {
  private static final Log logger =
    LogFactory.getLog(DefaultProgressReporter.class);

  @Override
  public Object reportStart(ProgressStatus status) {
    return new Date();
  }

  @Override
  public void reportEnd(ProgressStatus status, Object startDate) {
    System.out.println(status.getProgressState().toString() + " is " +
      status.getProgressInfo().isSuccess() + " , and latency is " +
      Math.abs(((Date) startDate).getTime()-new Date().getTime()) + "
      milliseconds.");
  }
}

Se você não implementar seu próprio ProgressReporter, DefaultExceptionHandler, que imprime o nome do estado que está em execução, será usado.

Tratamento de erros

A interface ExceptionHandler permite que você dê um tratamento especial quando ocorre uma exceção durante o processamento de log. ExceptionHandler declara um único método de retorno de chamada, handleException(), que recebe um objeto ProcessingLibraryException com contexto sobre a exceção que ocorreu.

Você pode usar o método de ProcessingLibraryException, getStatus(), transferido para descobrir qual operação foi executada quando a exceção ocorreu e obter informações adicionais sobre o status da operação. ProcessingLibraryException deriva-se da classe padrão Exception de Java, portanto, você também pode recuperar informações sobre a exceção chamando qualquer um dos métodos de exceção.

Veja este exemplo de implementação:

public class SampleExceptionHandler implements ExceptionHandler{
  private static final Log logger =
    LogFactory.getLog(DefaultProgressReporter.class);

  @Override
  public void handleException(ProcessingLibraryException exception) {
    ProgressStatus status = exception.getStatus();
    ProgressState state = status.getProgressState();
    ProgressInfo info = status.getProgressInfo();

    System.err.println(String.format(
      "Exception. Progress State: %s. Progress Information: %s.", state, info));
  }
}

Se você não fornecer seu próprio ExceptionHandler, DefaultExceptionHandler, que imprime uma mensagem de erro padrão, será usado.

nota

Se o parâmetro deleteMessageUponFailure for true, a Biblioteca de Processamento do CloudTrail não distinguirá exceções gerais de erros de processamento, e poderá excluir as mensagens da fila.

  1. Por exemplo, você usa o SourceFilter para filtrar mensagens por data e hora.

  2. No entanto, você não tem as permissões necessárias para acessar o bucket do S3 que recebe os arquivos de log do CloudTrail. Como você não tem as permissões necessárias, uma AmazonServiceException é lançada. A Biblioteca de Processamento do CloudTrail encapsula isso em CallBackException.

  3. O DefaultExceptionHandler registra isso como um erro, mas não identifica a causa-raiz, que é o fato de você não ter as permissões necessárias. A Biblioteca de Processamento do CloudTrail considera isso um erro de processamento e exclui a mensagem, mesmo que ela inclua um arquivo de log do CloudTrail válido.

Se você quiser filtrar mensagens com SourceFilter, verifique se o seu ExceptionHandler pode diferenciar exceções de serviço de erros de processamento.

Recursos adicionais

Para obter mais informações sobre a Biblioteca de Processamento do CloudTrail, consulte: