最小要件 CloudTrail ログを処理しています高度なトピックその他のリソース

CloudTrail Processing Library の使用

この CloudTrail Processing Library は Java ライブラリで、AWS CloudTrail ログを処理する簡単な方法が用意されています。ユーザーは、CloudTrail の SQS キューに関する設定の詳細を提供し、イベントを処理するコードを記述します。CloudTrail Processing Library が残りを処理します。これにより Amazon SQS キューをポーリングし、キューメッセージの読み取りと解析、CloudTrail ログファイルのダウンロード、ログファイル内のイベントの解析を行い、イベントを Java オブジェクトとしてコードに渡します。

CloudTrail Processing Library は耐障害性が高く、スケーラブルです。ログファイルの並列処理を行うため、必要な数だけのログを処理することができます。ネットワークタイムアウトや、アクセスできないリソースに関するネットワーク障害に対応します。

次のトピックでは、CloudTrail Processing Library を使用して Java プロジェクトの CloudTrail ログを処理する方法を示します。

ライブラリは、Apache ライセンスの付いたオープンソースプロジェクトとして提供され、GitHub で入手できます。https://github.com/aws/aws-cloudtrail-processing-library。ライブラリソースには、独自のプロジェクトのベースとして使用できるサンプルコードが含まれます。

最小要件

CloudTrail Processing Library を使用するには、以下のものが必要です。

CloudTrail ログを処理しています

Java アプリケーションで CloudTrail ログを処理するには:

CloudTrail Processing Library をプロジェクトに追加する
CloudTrail Processing Library の設定
イベントプロセッサを実装する
処理エグゼキューターをインスタンス化して実行する

CloudTrail Processing Library をプロジェクトに追加する

CloudTrail Processing Library を使用するには、Java プロジェクトのクラスパスに追加します。

Apache Ant プロジェクトにライブラリを追加する

Apache Ant プロジェクトに CloudTrail Processing Library を追加するには

GitHub から CloudTrail Processing Library のソースコードをダウンロードまたはクローンします。
- https://github.com/aws/aws-cloudtrail-processing-library
「README」で説明されているように、ソースから .jar ファイルを構築します。
```
mvn clean install -Dgpg.skip=true
```
作成された .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 ファイルに依存関係を 1 つ書くことで、プロジェクトに追加できます。

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 を追加するには

GitHub から CloudTrail Processing Library のソースコードをダウンロードまたはクローンします。
- https://github.com/aws/aws-cloudtrail-processing-library
「README」で説明されているように、ソースから .jar ファイルを構築します。
```
mvn clean install -Dgpg.skip=true
```
構築した aws-cloudtrail-processing-library-1.6.1.jar をプロジェクトのディレクトリ (通常は lib) にコピーします。
Eclipse の [Project Explorer] でプロジェクト名を右クリックし、[Build Path]、[Configure] の順に選択します。
[Java Build Path] ウィンドウで、[Libraries] タブを選択します。
[Add JARs...] (JAR を追加...) をクリックして、aws-cloudtrail-processing-library-1.6.1.jar をコピーしたパスに移動します。
[OK] を選択すると、プロジェクトに .jar が追加されます。

IntelliJ プロジェクトにライブラリを追加する

IntelliJ プロジェクトに CloudTrail Processing Library を追加するには

GitHub から CloudTrail Processing Library のソースコードをダウンロードまたはクローンします。
- https://github.com/aws/aws-cloudtrail-processing-library
「README」で説明されているように、ソースから .jar ファイルを構築します。
```
mvn clean install -Dgpg.skip=true
```
[File] で、[Project Structure] を選択します。
[Modules]、[Dependencies] の順に選択します。
[+ JARS or Directories] を選択し、構築した aws-cloudtrail-processing-library-1.6.1.jar のパスに移動します。
[Apply]、[OK] の順に選択すると、プロジェクトに .jar が追加されます。

CloudTrail Processing Library の設定

実行時にロードされるクラスパスプロパティファイルを作成することにより、または ClientConfiguration オブジェクトを作成してオプションを手動で設定することにより、CloudTrail Processing Library を設定できます。

プロパティファイルを提供する

アプリケーションに設定オプションを提供するクラスパスプロパティファイルを作成できます。次のサンプルファイルでは、設定できるオプションを示します。


# 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 を作成する

クラスパスプロパティでオプションを設定する代わりに、次の例のように、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 オブジェクトによって提供される CloudTrailEvent と CloudTrailEventMetadata を使用して、CloudTrail イベントと配信情報を読み取ることができます。

この簡単な例では、SampleEventsProcessor に渡された各イベントのイベント情報が表示されます。実際の実装では、必要に応じてログを処理できます。AWSCloudTrailProcessingExecutor は、送信するイベントがあり、実行している限りは、EventsProcessor へのイベントの送信を続けます。

処理エグゼキューターをインスタンス化して実行する

EventsProcessor を作成し、CloudTrail の設定値を (プロパティファイルまたは ClientConfiguration クラスを使用して) 設定した後は、これらの要素を使用することで、AWSCloudTrailProcessingExecutor を初期化して使用できます。

`AWSCloudTrailProcessingExecutor` を使用して CloudTrail イベントを処理するには

AWSCloudTrailProcessingExecutor.Builder オブジェクトをインスタンス化します。Builder のコンストラクタは、EventsProcessor オブジェクトとクラスパスのプロパティファイル名を受け取ります。
Builder の build() ファクトリメソッドを呼び出し、AWSCloudTrailProcessingExecutor オブジェクトを設定して取得します。
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 で 1 つだけ宣言されているコールバックメソッド filterSource() は、CloudTrailSource オブジェクトを受け取ります。ソースからのイベントが処理されないようにするには、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 で 1 つだけ宣言されているコールバックメソッド、filterEvent() は、CloudTrailEvent オブジェクトを受け取ります。イベントが処理されないようにするには、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で宣言されている 2 つのメソッド 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 で 1 つだけ宣言されている 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 は一般的な例外処理と処理エラーとを区別せず、キューメッセージが削除される場合があります。

例えば、SourceFilter を使用して、タイムスタンプでメッセージをフィルタリングします。
ただし、CloudTrail ログファイルを受け取る S3 バケットにアクセスするために必要なアクセス権限がありません。必要なアクセス権限がないため、AmazonServiceException がスローされます。CloudTrail Processing Library は、これを CallBackException で折り返します。
DefaultExceptionHandler はこれをログとして記録しますが、必要なアクセス権限がないという根本原因を特定することはありません。メッセージに有効な CloudTrail ログファイルが含まれている場合でも、CloudTrail Processing Library はこれを処理エラーとみなし、メッセージを削除します。

メッセージを SourceFilter でフィルタリングするには、ExceptionHandler がサービスの例外を処理エラーから区別できることを確認します。

その他のリソース

CloudTrail Processing Library の詳細については、以下を参照してください。

CloudTrail Processing Library の GitHub プロジェクトには、CloudTrail Processing Library アプリケーションの実装方法を示すサンプルコードが含まれます。
CloudTrail Processing Library Java パッケージドキュメント。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

CloudTrail ログファイルの整合性検証のカスタム実装

設定

CloudTrail Processing Library の使用

トピック

最小要件

CloudTrail ログを処理しています

CloudTrail Processing Library をプロジェクトに追加する

目次

Apache Ant プロジェクトにライブラリを追加する

Apache Ant プロジェクトに CloudTrail Processing Library を追加するには

Apache Maven プロジェクトにライブラリを追加する

Maven プロジェクトに CloudTrail Processing Library を追加するには

Eclipse プロジェクトにライブラリを追加する

Eclipse プロジェクトに CloudTrail Processing Library を追加するには

IntelliJ プロジェクトにライブラリを追加する

IntelliJ プロジェクトに CloudTrail Processing Library を追加するには

CloudTrail Processing Library の設定

プロパティファイルを提供する

ClientConfiguration を作成する

イベントプロセッサを実装する

処理エグゼキューターをインスタンス化して実行する

AWSCloudTrailProcessingExecutor を使用して CloudTrail イベントを処理するには

高度なトピック

トピック

処理するイベントのフィルタリング

データイベントの処理

進行状況のレポート

エラー処理

注記

その他のリソース

`AWSCloudTrailProcessingExecutor` を使用して CloudTrail イベントを処理するには