CloudTrail Processing Library 사용 - AWS CloudTrail

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 로그를 처리하는 방법을 보여 줍니다.

라이브러리는 Apache 라이선스가 부여된 오픈 소스 프로젝트이며 GitHub에서 제공됩니다.

라이브러리 소스에는 자체 프로젝트를 생성할 때 토대로 사용할 수 있는 샘플 코드가 포함되어 있습니다.

최소 요구 사항

CloudTrail Processing Library를 사용하려면 다음이 필요합니다.

CloudTrail 로그 처리

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

프로젝트에 CloudTrail Processing Library 추가

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

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

Apache Ant 프로젝트에 라이브러리를 추가하려면

  1. Download or clone the CloudTrail Processing Library source code from GitHub:

  2. Build the .jar file from source as described in the README:

    mvn clean install -Dgpg.skip=true
  3. 결과 .jar 파일을 프로젝트에 복사하고 프로젝트의 build.xml 파일에 추가합니다. 예:

    <classpath> <pathelement path="${classpath}"/> <pathelement location="lib/aws-cloudtrail-processing-library-1.2.0.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.2.0</version> </dependency>

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

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

  1. Download or clone the CloudTrail Processing Library source code from GitHub:

  2. Build the .jar file from source as described in the README:

    mvn clean install -Dgpg.skip=true
  3. 빌드된 aws-cloudtrail-processing-library-1.2.0.jar를 프로젝트의 디렉터리에 복사합니다(일반적으로 lib).

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

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

  6. Add JARs...를 선택하고 aws-cloudtrail-processing-library-1.2.0.jar를 복사한 경로로 이동합니다.

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

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

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

  1. Download or clone the CloudTrail Processing Library source code from GitHub:

  2. Build the .jar file from source as described in the README:

    mvn clean install -Dgpg.skip=true
  3. [File]에서 [Project Structure]를 선택합니다.

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

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

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

CloudTrail Processing Library 구성

실행시간에 로드되는 classpath 속성 파일을 생성하거나 객체를 생성한 후 수동으로 옵션을 설정하여 를 구성할 수 있습니다.

속성 파일 제공

애플리케이션에 구성 옵션을 제공하는 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).

accessKeysecretKey 파라미터는 라이브러리가 사용자 대신 에 액세스할 수 있도록 라이브러리에 자격 증명을 제공합니다.

다른 파라미터의 기본값은 라이브러리에서 설정됩니다. 자세한 내용은 AWS CloudTrail Processing Library Reference를 참조하십시오.

ClientConfiguration 생성

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

ClientConfiguration basicConfig = new ClientConfiguration( "http://sqs.us-east-1.amazonaws.com/123456789012/queue2", new DefaultAWSCredentialsProviderChain()); basicConfig.setEnableRawEventInfo(true); basicConfig.setThreadCount(4); basicConfig.setnEventsPerEmit(20);

Events Processor 구현

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

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를 구현할 때 가 이벤트를 전송하기 위해 사용하는 콜백을 구현합니다. 이벤트는 CloudTrailClientEvent 객체 목록에 제공됩니다.

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

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

Processing Executor 인스턴스화 및 실행

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

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

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

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

  3. AWSCloudTrailProcessingExecutorstart()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는 객체를 수신하는 단일 콜백 메서드 를 선언합니다. 소스에서 수신된 이벤트가 처리되지 않도록 하려면 에서 를 반환합니다.

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

다음은 구현의 예입니다.

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는 객체를 수신하는 단일 콜백 메서드 를 선언합니다. 이벤트가 처리되지 않도록 하려면 에서 를 반환합니다.

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

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

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를 반환함).

진행률 보고

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

  • Amazon SQS에서 메시지 폴링

  • 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 객체를 수신합니다.

전달된 ProcessingLibraryExceptiongetStatus() 메서드를 사용하여 예외 발생 시 실행된 작업을 확인하고 작업 상태에 대한 추가 정보를 구할 수 있습니다. 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에 대한 자세한 내용은 다음을 참조하십시오.