CloudTrail Processing Library 사용

CloudTrail Processing Library는 AWS CloudTrail 로그를 처리하기 위한 간편한 방법을 제공하는 Java 라이브러리입니다. 개발자는 CloudTrail SQS 대기열에 관한 구성 세부 정보를 제공하고 이벤트를 처리하기 위한 코드를 작성하기만 하면 됩니다. CloudTrail Processing Library가 나머지 작업을 처리합니다. 즉, Amazon SQS 대기열을 폴링하며 대기열 메시지를 읽고 구문 분석하고 CloudTrail 로그 파일을 다운로드하며 로그 파일의 이벤트를 구문 분석하고 이벤트를 Java 객체로 코드에 전달합니다.

CloudTrail Processing Library는 확장성과 내결함성이 뛰어납니다. 로그 파일을 병렬 처리하여 로그를 필요한 만큼 처리할 수 있습니다. 또한 네트워크 시간 초과 및 액세스할 수 없는 리소스와 관련된 네트워크 장애를 처리합니다.

다음 주제에서는 CloudTrail Processing Library를 사용하여 Java 프로젝트에서 CloudTrail 로그를 처리하는 방법을 보여 줍니다.

라이브러리는 GitHub(https://github.com/aws/aws-cloudtrail-processing-library)에서 사용할 수 있는 Apache 라이선스 오픈 소스 프로젝트로 제공됩니다. 라이브러리 소스에는 자체 프로젝트를 생성할 때 토대로 사용할 수 있는 샘플 코드가 포함되어 있습니다.

최소 요구 사항

CloudTrail Processing Library를 사용하려면 다음 항목이 있어야 합니다.

• AWS SDK for Java 1.11.830

• Java 1.8(Java SE 8)

CloudTrail 로그 처리

Java 애플리케이션에서 CloudTrail 로그를 처리하려면

1. 프로젝트에 CloudTrail Processing Library 추가

2. CloudTrail Processing Library 구성

3. 이벤트 프로세서 구현

4. Processing Executor 인스턴스화 및 실행

프로젝트에 CloudTrail Processing Library 추가

CloudTrail Processing Library를 사용하려면 Java 프로젝트의 classpath에 추가합니다.

목차

• Apache Ant 프로젝트에 라이브러리 추가
• Apache Maven 프로젝트에 라이브러리 추가
• Eclipse 프로젝트에 라이브러리 추가
• IntelliJ 프로젝트에 라이브러리 추가

Apache Ant 프로젝트에 라이브러리 추가

Apache Ant 프로젝트에 CloudTrail Processing Library를 추가하려면

1. 다음 GitHub에서 CloudTrail Processing Library 소스 코드를 다운로드하거나 복제합니다.

   • https://github.com/aws/aws-cloudtrail-processing-library

2. README에 설명된 대로 다음과 같이 소스에서 .jar 파일을 구축합니다.

   mvn clean install -Dgpg.skip=true

3. 결과 .jar 파일을 프로젝트에 복사하고 프로젝트의 build.xml 파일에 추가합니다. 예제:

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

Apache Maven 프로젝트에 라이브러리 추가

CloudTrail Processing Library는 Apache Maven에서 사용할 수 있습니다. 프로젝트의 pom.xml 파일에 단일 종속성을 작성하여 프로젝트에 라이브러리를 추가할 수 있습니다.

Maven 프로젝트에 CloudTrail Processing Library를 추가하려면

• Maven 프로젝트의 pom.xml 파일을 열고 다음 종속성을 추가합니다.

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

Eclipse 프로젝트에 라이브러리 추가

Eclipse 프로젝트에 CloudTrail Processing Library를 추가하려면

1. 다음 GitHub에서 CloudTrail Processing Library 소스 코드를 다운로드하거나 복제합니다.

   • https://github.com/aws/aws-cloudtrail-processing-library

2. README에 설명된 대로 다음과 같이 소스에서 .jar 파일을 구축합니다.

   mvn clean install -Dgpg.skip=true

3. 구축한 aws-cloudtrail-processing-library-1.6.1.jar를 프로젝트의 디렉터리(일반적으로 lib)에 복사합니다.

4. Eclipse [Project Explorer]에서 프로젝트의 이름을 마우스 오른쪽 버튼으로 클릭하고 [Build Path]를 선택한 다음 [Configure]를 선택합니다.

5. [Java Build Path] 창에서 [Libraries] 탭을 선택합니다.

6. JAR 추가(Add JARs...)를 선택하고 aws-cloudtrail-processing-library-1.6.1.jar를 복사한 경로로 이동합니다.

7. [OK]를 선택하여 프로젝트에 .jar 추가를 완료합니다.

IntelliJ 프로젝트에 라이브러리 추가

IntelliJ 프로젝트에 CloudTrail Processing Library를 추가하려면

1. 다음 GitHub에서 CloudTrail Processing Library 소스 코드를 다운로드하거나 복제합니다.

   • https://github.com/aws/aws-cloudtrail-processing-library

2. README에 설명된 대로 다음과 같이 소스에서 .jar 파일을 구축합니다.

   mvn clean install -Dgpg.skip=true

3. [File]에서 [Project Structure]를 선택합니다.

4. [Modules]를 선택한 다음 [Dependencies]를 선택합니다.

5. [+ JARS or Directories]를 선택한 다음 aws-cloudtrail-processing-library-1.6.1.jar를 빌드한 경로로 이동합니다.

6. [Apply]를 선택한 다음 [OK]를 선택하여 프로젝트에 .jar 추가를 완료합니다.

CloudTrail Processing Library 구성

런타임 시 로드되는 classpath 속성 파일을 생성하거나 ClientConfiguration 객체를 생성하고 수동으로 옵션을 설정하여 CloudTrail Processing Library를 구성할 수 있습니다.

속성 파일 제공

애플리케이션에 구성 옵션을 제공하는 classpath 속성 파일을 작성할 수 있습니다. 다음 예제 파일에서는 설정할 수 있는 옵션을 보여 줍니다.

# 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

다음 파라미터는 필수 파라미터입니다.

• sqsUrl – CloudTrail 알림을 가져올 URL을 제공합니다. 이 값을 지정하지 않은 경우 AWSCloudTrailProcessingExecutor에서 IllegalStateException을 내보냅니다.

• accessKey – 계정의 고유 식별자입니다(예: AKIAIOSFODNN7EXAMPLE).

• secretKey – 계정의 고유 식별자입니다(예: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY).

accessKey 및 secretKey 파라미터는 AWS 자격 증명을 라이브러리에 제공하므로 라이브러리가 사용자를 대신하여 AWS에 액세스할 수 있습니다.

다른 파라미터의 기본값은 라이브러리에서 설정됩니다. 자세한 내용은 AWS CloudTrail Processing Library 참조 단원을 참조하세요.

ClientConfiguration 생성

classpath 속성에서 옵션을 설정하는 대신, 다음 예와 같이 ClientConfiguration 객체에서 옵션을 초기화하고 설정하여 AWSCloudTrailProcessingExecutor에 옵션을 제공할 수 있습니다.

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

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

이벤트 프로세서 구현

CloudTrail 로그를 처리하려면 CloudTrail 로그 데이터를 수신하는 EventsProcessor를 구현해야 합니다. 다음은 구현의 예입니다.

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()));
        }
    }
}

EventsProcessor를 구현할 경우 AWSCloudTrailProcessingExecutor가 CloudTrail 이벤트를 전송하는 데 사용하는 process() 콜백을 구현합니다. 이벤트는 CloudTrailClientEvent 객체 목록에 제공됩니다.

CloudTrailClientEvent 객체는 CloudTrail 이벤트 및 전달 정보를 읽는 데 사용할 수 있는 CloudTrailEvent 및 CloudTrailEventMetadata를 제공합니다.

이 간단한 예에서는 SampleEventsProcessor에 전달된 각 이벤트에 대한 이벤트 정보를 인쇄합니다. 자체 구현에서는 적절한 방식으로 로그를 처리할 수 있습니다. AWSCloudTrailProcessingExecutor에 전송할 이벤트가 있고 실행되는 동안에는 계속해서 EventsProcessor로 이벤트를 전송합니다.

Processing Executor 인스턴스화 및 실행

EventsProcessor를 작성하고 CloudTrail Processing Library에 대한 구성 값을 설정(속성 파일에서 설정 또는 ClientConfiguration 클래스를 사용하여 설정)한 후 이러한 요소를 사용하여 AWSCloudTrailProcessingExecutor를 초기화하고 사용할 수 있습니다.

AWSCloudTrailProcessingExecutor를 사용하여 CloudTrail 이벤트를 처리하려면

1. AWSCloudTrailProcessingExecutor.Builder 객체를 인스턴스화합니다. Builder의 생성자는 EventsProcessor 객체와 classpath 속성 파일 이름을 사용합니다.

2. Builder의 build() 팩토리 메서드를 호출하여 AWSCloudTrailProcessingExecutor 객체를 구성하고 가져옵니다.

3. AWSCloudTrailProcessingExecutor의 start() 및 stop() 메서드를 사용하여 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
  }
}

고급 주제

주제

• 처리할 이벤트 필터링
• 데이터 이벤트 처리
• 진행률 보고
• 오류 처리

처리할 이벤트 필터링

기본적으로 Amazon SQS 대기열의 S3 버킷에 있는 모든 로그 및 로그에 포함된 모든 이벤트는 ​EventsProcessor에 전송됩니다. CloudTrail Processing Library는 CloudTrail 로그를 가져오는 데 사용되는 소스를 필터링하고 처리할 이벤트를 필터링하기 위해 구현할 수 있는 선택적 인터페이스를 제공합니다.

SourceFilter

SourceFilter 인터페이스를 구현하여 제공된 소스의 로그를 처리할지 여부를 선택할 수 있습니다. SourceFilter는 CloudTrailSource 객체를 수신하는 단일 콜백 메서드인 filterSource()를 선언합니다. 소스의 이벤트가 처리되지 않도록 하려면 filterSource()에서 false를 반환합니다.

CloudTrail Processing Library는 라이브러리가 Amazon SQS 대기열의 로그를 폴링한 후 filterSource() 메서드를 호출합니다. 이는 라이브러리가 로그에 대해 이벤트 필터링 또는 처리를 시작하기 전에 발생합니다.

다음은 구현의 예입니다.

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);
  }
}

자체 SourceFilter를 제공하지 않을 경우 DefaultSourceFilter가 사용되며 이 경우 모든 소스가 처리됩니다(항상 true를 반환함).

EventFilter

EventFilter 인터페이스를 구현하여 CloudTrail 이벤트를 EventsProcessor에 전송할지 여부를 선택할 수 있습니다. EventFilter는 CloudTrailEvent 객체를 수신하는 단일 콜백 메서드인 filterEvent()를 선언합니다. 이벤트가 처리되지 않도록 하려면 filterEvent()에서 false를 반환합니다.

CloudTrail Processing Library는 라이브러리가 Amazon SQS 대기열의 로그를 폴링한 후와 소스 필터링 후에 filterEvent() 메서드를 호출합니다. 이는 라이브러리가 로그에 대해 이벤트 처리를 시작하기 전에 발생합니다.

다음 구현 예제를 참조하십시오.

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");
  }
}

자체 EventFilter를 제공하지 않을 경우 DefaultEventFilter가 사용되며 이 경우 모든 이벤트가 처리됩니다(항상 true를 반환함).

데이터 이벤트 처리

CloudTrail은 데이터 이벤트를 처리할 때 정수(int)이든 float(소수를 포함하는 숫자)이든 상관없이 숫자를 원래 형식으로 유지합니다. 데이터 이벤트의 필드에 정수가 있는 이벤트의 경우 CloudTrail은 이전에 이러한 숫자를 부동 소수점으로 처리했습니다. 현재 CloudTrail은 이러한 필드의 숫자를 처리할 때 원래 형식을 유지합니다.

모범 사례로, 자동화 중단을 방지하려면 CloudTrail 데이터 이벤트를 처리하거나 필터링하는 데 사용하는 코드 또는 자동화에서 유연성을 유지하고 int 및 float 형식의 숫자를 모두 허용해야 합니다. 최상의 결과를 얻으려면 CloudTrail Processing Library 버전 1.4.0 이상을 사용하세요.

다음 코드 조각 예에서는 데이터 이벤트의 ResponseParameters 블록에 있는 desiredCount 파라미터의 float 형식 숫자인 2.0을 보여 줍니다.

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

다음 코드 조각 예에서는 데이터 이벤트의 ResponseParameters 블록에 있는 desiredCount 파라미터의 int 형식 숫자인 2를 보여 줍니다.

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

진행률 보고

ProgressReporter 인터페이스를 구현하여 CloudTrail Processing Library 진행률 보고를 사용자 지정합니다. ProgressReporter는 다음 작업이 시작될 때와 끝날 때 호출되는 reportStart() 및 reportEnd()라는 두 개의 메서드를 선언합니다.

• Amazon SQS에서 메시지 폴링

• Amazon SQS의 메시지 구문 분석

• CloudTrail 로그의 Amazon SQS 소스 처리

• Amazon SQS의 메시지 삭제

• CloudTrail 로그 파일 다운로드

• CloudTrail 로그 파일 처리

두 메서드는 수행된 작업에 대한 정보를 포함하는 ProgressStatus 객체를 수신합니다. progressState 멤버는 현재 작업을 식별하는 ProgressState 열거형의 멤버를 보유합니다. 이 멤버는 progressInfo 멤버에 추가 정보를 포함할 수 있습니다. 또한 reportStart()에서 반환할 수 있는 모든 객체는 reportEnd()에 전달되므로 이벤트 처리가 시작된 시간 등의 컨텍스트 정보를 제공할 수 있습니다.

다음은 작업이 완료될 때까지 걸리는 시간에 대한 정보를 제공하는 구현 예제입니다.

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.");
  }
}

자체 ProgressReporter를 구현하지 않을 경우 실행 중인 상태의 이름을 인쇄하는 DefaultExceptionHandler가 대신 사용됩니다.

오류 처리

ExceptionHandler 인터페이스를 사용하면 로그 처리 중 예외가 발생할 경우 특수 처리를 제공할 수 있습니다. ExceptionHandler는 객체를 수신하는 단일 콜백 메서드 handleException()를 선언하고 이 콜백 메서드는 발생한 예외에 대한 컨텍스트가 포함된 ProcessingLibraryException 객체를 수신합니다.

전달된 ProcessingLibraryException의 getStatus() 메서드를 사용하여 예외 발생 시 실행된 작업을 확인하고 작업 상태에 대한 추가 정보를 구할 수 있습니다. ProcessingLibraryException은 Java의 표준 Exception 클래스에서 파생되므로 Exception 메서드 중 하나를 사용하여 예외에 대한 정보를 검색할 수도 있습니다.

다음 구현 예제를 참조하십시오.

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));
  }
}

자체 ExceptionHandler를 제공하지 않을 경우 표준 오류 메시지를 인쇄하는 DefaultExceptionHandler가 대신 사용됩니다.

참고

deleteMessageUponFailure 파라미터가 true인 경우 CloudTrail Processing Library는 일반 예외를 처리 오류와 구별하지 않고 대기열 메시지를 삭제할 수 있습니다.

1. 예를 들어 SourceFilter를 사용하여 타임스탬프를 기준으로 메시지를 필터링합니다.

2. 그러나 CloudTrail 로그 파일을 수신하는 S3 버킷에 액세스하는 데 필요한 권한이 없습니다. 필요한 권한이 없으므로 AmazonServiceException이 발생합니다. CloudTrail Processing Library는 이를 CallBackException으로 래핑합니다.

3. DefaultExceptionHandler는 이를 오류로 로깅하지만 필요한 권한이 없는 근본 원인을 식별하지 않습니다. CloudTrail Processing Library는 이를 처리 오류로 간주하고 메시지에 유효한 CloudTrail 로그 파일이 포함되어 있는 경우에도 메시지를 삭제합니다.

SourceFilter를 사용하여 메시지를 필터링하려면 ExceptionHandler가 서비스 예외를 처리 오류와 구별할 수 있는지 확인합니다.

추가 리소스

CloudTrail Processing Library에 대한 자세한 내용은 다음을 참조하세요.

• CloudTrail Processing Library 애플리케이션을 구현하는 방법을 보여 주는 샘플 코드가 포함된 CloudTrail Processing Library GitHub 프로젝트

• CloudTrail Processing Library Java 패키지 설명서