# AWS - Step Functions Enum

{{#include ../../../banners/hacktricks-training.md}}

## Step Functions

AWS Step Functionsは、複数のAWSサービスをサーバーレスワークフローに調整および編成するためのワークフローサービスです。AWS Step Functionsを使用することで、AWS Lambda、Amazon S3、Amazon DynamoDBなどのさまざまなAWSサービスをステップのシーケンスで接続するワークフローを設計および実行できます。このオーケストレーションサービスは、視覚的なワークフローインターフェースを提供し、**状態マシン**機能を提供し、JSONベースの**Amazon States Language**（ASL）を使用してワークフローの各ステップを宣言的に定義できます。

## Key concepts

### Standard vs. Express Workflows

AWS Step Functionsは、2種類の**状態マシンワークフロー**を提供します：StandardとExpress。

- **Standard Workflow**：このデフォルトのワークフロータイプは、長時間実行される耐久性のある監査可能なプロセス向けに設計されています。**正確に1回の実行**をサポートし、リトライが指定されない限り、タスクは1回だけ実行されます。詳細な実行履歴が必要なワークフローに最適で、最大1年間実行できます。
- **Express Workflow**：このタイプは、高ボリュームの短期間のタスクに最適で、最大5分間実行されます。**少なくとも1回の実行**をサポートし、データ処理のような冪等タスクに適しています。これらのワークフローは、コストとパフォーマンスの最適化が行われており、実行、期間、メモリ使用量に基づいて課金されます。

### States

Statesは状態マシンの基本単位です。ワークフロー内の個々のステップを定義し、そのタイプに応じてさまざまな機能を実行できます：

- **Task:** ジョブを実行し、通常はLambdaのようなAWSサービスを使用します。
- **Choice:** 入力に基づいて決定を下します。
- **Fail/Succeed:** 失敗または成功で実行を終了します。
- **Pass:** 入力を出力に渡すか、データを注入します。
- **Wait:** 設定された時間だけ実行を遅延させます。
- **Parallel:** 並列ブランチを開始します。
- **Map:** アイテムに対してステップを動的に反復します。

### Task

**Task**状態は、状態マシンによって実行される単一の作業単位を表します。タスクは、アクティビティ、Lambda関数、AWSサービス、またはサードパーティAPIなど、さまざまなリソースを呼び出すことができます。

- **Activities**: あなたが管理するカスタムワーカーで、長時間実行されるプロセスに適しています。
- Resource: **`arn:aws:states:region:account:activity:name`**.
- **Lambda Functions**: AWS Lambda関数を実行します。
- Resource: **`arn:aws:lambda:region:account:function:function-name`**.
- **AWS Services**: DynamoDBやS3など、他のAWSサービスと直接統合します。
- Resource: **`arn:partition:states:region:account:servicename:APIname`**.
- **HTTP Task**: サードパーティAPIを呼び出します。
- Resource field: **`arn:aws:states:::http:invoke`**. 次に、API URL、メソッド、認証の詳細など、APIエンドポイントの構成詳細を提供する必要があります。

以下の例は、HelloWorldというLambda関数を呼び出すTask状態の定義を示しています：
```json
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:<region>:<account-id>:function:HelloWorld"
},
"End": true
}
```
### Choice

A **Choice** state adds conditional logic to a workflow, enabling decisions based on input data. It evaluates the specified conditions and transitions to the corresponding state based on the results.

- **Comparison**: 各選択ルールには、入力変数を指定された値または別の変数と比較する比較演算子（例：**`NumericEquals`**、**`StringEquals`**）が含まれています。
- **Next Field**: Choice states do not support don't support the **`End`** field, instead, they define the **`Next`** state to transition to if the comparison is true.

Example of **Choice** state:
```json
{
"Variable": "$.timeStamp",
"TimestampEquals": "2000-01-01T00:00:00Z",
"Next": "TimeState"
}
```
### 失敗/成功

**`Fail`** ステートは、ステートマシンの実行を停止し、それを失敗としてマークします。エラー名と原因を指定し、失敗に関する詳細を提供するために使用されます。このステートは終端であり、実行フローを終了します。

**`Succeed`** ステートは、実行を成功裏に停止します。通常、ワークフローが成功裏に完了したときに終了するために使用されます。このステートは **`Next`** フィールドを必要としません。

{{#tabs }}
{{#tab name="Fail example" }}
```json
"FailState": {
"Type": "Fail",
"Error": "ErrorName",
"Cause": "Error details"
}
```
{{#endtab }}

{{#tab name="成功例" }}
```json
"SuccessState": {
"Type": "Succeed"
}
```
{{#endtab }}
{{#endtabs }}

### Pass

**Pass** ステートは、作業を行うことなく、またはフィルターを使用してJSONステート入力を変換し、その変換されたデータを次のステートに渡すことによって、入力を出力に渡します。これは、静的データを注入したり変換したりすることを可能にし、ステートマシンのテストや構築に役立ちます。
```json
"PassState": {
"Type": "Pass",
"Result": {"key": "value"},
"ResultPath": "$.newField",
"Next": "NextState"
}
```
### Wait

**Wait**ステートは、指定された期間だけステートマシンの実行を遅延させます。待機時間を設定するための主な方法は3つあります。

- **X Seconds**: 待機する固定の秒数。

```json
"WaitState": {
"Type": "Wait",
"Seconds": 10,
"Next": "NextState"
}
```

- **Absolute Timestamp**: 待機する正確な時間。

```json
"WaitState": {
"Type": "Wait",
"Timestamp": "2024-03-14T01:59:00Z",
"Next": "NextState"
}
```

- **Dynamic Wait**: **`SecondsPath`**または**`TimestampPath`**を使用して入力に基づく。

```json
jsonCopiar código
"WaitState": {
"Type": "Wait",
"TimestampPath": "$.expirydate",
"Next": "NextState"
}
```

### Parallel

**Parallel**ステートは、ワークフロー内で複数のタスクのブランチを同時に実行することを可能にします。各ブランチは独立して実行され、それぞれのステートのシーケンスを処理します。実行は、すべてのブランチが完了するまで待機し、その後次のステートに進みます。主なフィールドは次のとおりです。

- **Branches**: 並行実行パスを定義する配列。各ブランチは別々のステートマシンです。
- **ResultPath**: ブランチの結合出力をどこに（入力内で）配置するかを定義します。
- **Retry and Catch**: 並行ステートのエラーハンドリング設定。
```json
"ParallelState": {
"Type": "Parallel",
"Branches": [
{
"StartAt": "Task1",
"States": { ... }
},
{
"StartAt": "Task2",
"States": { ... }
}
],
"Next": "NextState"
}
```
### マップ

**Map** ステートは、データセット内の各アイテムに対して一連のステップを実行することを可能にします。データの並列処理に使用されます。データセットのアイテムをどのように処理したいかに応じて、Step Functions は以下のモードを提供します。

- **インラインモード**: 各 JSON 配列アイテムに対してステートのサブセットを実行します。40 未満の並列反復を持つ小規模なタスクに適しており、**`Map`** ステートを含むワークフローのコンテキスト内でそれぞれを実行します。

```json
"MapState": {
"Type": "Map",
"ItemsPath": "$.arrayItems",
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "INLINE"
},
"StartAt": "AddState",
"States": {
"AddState": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"OutputPath": "$.Payload",
"Parameters": {
"FunctionName": "arn:aws:lambda:<region>:<account-id>:function:add-function"
},
"End": true
}
}
},
"End": true
"ResultPath": "$.detail.added",
"ItemsPath": "$.added"
}
```

- **分散モード**: 高い同時実行性を持つ大規模な並列処理のために設計されています。Amazon S3 に保存されているような大規模データセットの処理をサポートし、最大 10,000 の並列子ワークフロー実行を高い同時実行性で実行します。これらの子は別の子実行として実行されます。

```json
"DistributedMapState": {
"Type": "Map",
"ItemReader": {
"Resource": "arn:aws:states:::s3:getObject",
"Parameters": {
"Bucket": "my-bucket",
"Key": "data.csv"
}
},
"ItemProcessor": {
"ProcessorConfig": {
"Mode": "DISTRIBUTED",
"ExecutionType": "EXPRESS"
},
"StartAt": "ProcessItem",
"States": {
"ProcessItem": {
"Type": "Task",
"Resource": "arn:aws:lambda:region:account-id:function:my-function",
"End": true
}
}
},
"End": true
"ResultWriter": {
"Resource": "arn:aws:states:::s3:putObject",
"Parameters": {
"Bucket": "myOutputBucket",
"Prefix": "csvProcessJobs"
}
}
}
```

### バージョンとエイリアス

Step Functions は、ステートマシンの**バージョン**と**エイリアス**を通じてワークフローデプロイメントを管理することもできます。バージョンは、実行可能なステートマシンのスナップショットを表します。エイリアスは、ステートマシンの最大 2 つのバージョンへのポインタとして機能します。

- **バージョン**: これらの不変のステートマシンのスナップショットは、そのステートマシンの最新のリビジョンから作成されます。各バージョンは、ステートマシン ARN とバージョン番号をコロンで区切って組み合わせた一意の ARN によって識別されます (**`arn:aws:states:region:account-id:stateMachine:StateMachineName:version-number`**)。バージョンは編集できませんが、ステートマシンを更新して新しいバージョンを公開するか、希望するステートマシンバージョンを使用できます。
- **エイリアス**: これらのポインタは、同じステートマシンの最大 2 つのバージョンを参照できます。単一のステートマシンに対して複数のエイリアスを作成でき、それぞれはエイリアス名をコロンで区切ってステートマシン ARN と組み合わせた一意の ARN によって識別されます (**`arn:aws:states:region:account-id:stateMachine:StateMachineName:aliasName`**)。エイリアスは、ステートマシンの 2 つのバージョンのいずれかの間でトラフィックをルーティングすることを可能にします。あるいは、エイリアスはステートマシンの特定のバージョンを指すことができますが、他のエイリアスには指しません。必要に応じて、異なるバージョンのステートマシンにリダイレクトするように更新でき、制御されたデプロイメントとワークフロー管理を促進します。

**ASL** に関する詳細情報については、次を確認してください: [**Amazon States Language**](https://states-language.net/spec.html)。

## ステートマシンのための IAM ロール

AWS Step Functions は、AWS Identity and Access Management (IAM) ロールを利用して、ステートマシン内のリソースとアクションへのアクセスを制御します。AWS Step Functions におけるセキュリティと IAM ロールに関連する主な側面は以下の通りです。

- **実行ロール**: AWS Step Functions の各ステートマシンは IAM 実行ロールに関連付けられています。このロールは、ステートマシンがあなたの代わりに実行できるアクションを定義します。ステートマシンが AWS サービスと相互作用するステート間を遷移する際（Lambda 関数の呼び出し、DynamoDB へのアクセスなど）、この実行ロールを引き受けてそれらのアクションを実行します。
- **権限**: IAM 実行ロールは、他の AWS サービスに対する必要なアクションを許可する権限で構成する必要があります。たとえば、ステートマシンが AWS Lambda 関数を呼び出す必要がある場合、IAM ロールには **`lambda:InvokeFunction`** 権限が必要です。同様に、DynamoDB に書き込む必要がある場合、適切な権限 (**`dynamodb:PutItem`**, **`dynamodb:UpdateItem`** など) を付与する必要があります。

## 列挙

ReadOnlyAccess ポリシーは、以下のすべての列挙アクションに対して十分です。
```bash
# State machines #

## List state machines
aws stepfunctions list-state-machines
## Retrieve informatio about the specified state machine
aws stepfunctions describe-state-machine --state-machine-arn <value>

## List versions for the specified state machine
aws stepfunctions list-state-machine-versions --state-machine-arn <value>
## List aliases for the specified state machine
aws stepfunctions list-state-machine-aliases --state-machine-arn <value>
## Retrieve information about the specified state machine alias
aws stepfunctions describe-state-machine-alias --state-machine-alias-arn <value>

## List executions of a state machine
aws stepfunctions list-executions --state-machine-arn <value> [--status-filter <RUNNING | SUCCEEDED | FAILED | TIMED_OUT | ABORTED | PENDING_REDRIVE>] [--redrive-filter <REDRIVEN | NOT_REDRIVEN>]
## Retrieve information and relevant metadata about a state machine execution (output included)
aws stepfunctions describe-execution --execution-arn <value>
## Retrieve information about the state machine associated to the specified execution
aws stepfunctions describe-state-machine-for-execution --execution-arn <value>
## Retrieve the history of the specified execution as a list of events
aws stepfunctions get-execution-history --execution-arn <value> [--reverse-order | --no-reverse-order] [--include-execution-data | --no-include-execution-data]

## List tags for the specified step Functions resource
aws stepfunctions list-tags-for-resource --resource-arn <value>

## Validate the definition of a state machine without creating the resource
aws stepfunctions validate-state-machine-definition --definition <value> [--type <STANDARD | EXPRESS>]

# Activities #

## List existing activities
aws stepfunctions list-activities
## Retrieve information about the specified activity
aws stepfunctions describe-activity --activity-arn <value>

# Map Runs #

## List map runs of an execution
aws stepfunctions list-map-runs --execution-arn <value>
## Provide information about the configuration, progress and results of a Map Run
aws stepfunctions describe-map-run --map-run-arn <value>
## Lists executions of a Map Run
aws stepfunctions list-executions --map-run-arn <value> [--status-filter <RUNNING | SUCCEEDED | FAILED | TIMED_OUT | ABORTED | PENDING_REDRIVE>] [--redrive-filter <REDRIVEN | NOT_REDRIVEN>]
```
## プライバシー昇格

次のページでは、**Step Functionsの権限を悪用して特権を昇格させる方法**を確認できます：

{{#ref}}
../aws-privilege-escalation/aws-stepfunctions-privesc/README.md
{{#endref}}

## ポストエクスプロイテーション

{{#ref}}
../aws-post-exploitation/aws-stepfunctions-post-exploitation/README.md
{{#endref}}

## 永続性

{{#ref}}
../aws-persistence/aws-step-functions-persistence/README.md
{{#endref}}

## 参考文献

- [https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsstepfunctions.html](https://docs.aws.amazon.com/service-authorization/latest/reference/list_awsstepfunctions.html)
- [https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html](https://docs.aws.amazon.com/step-functions/latest/dg/welcome.html)
- [https://states-language.net/spec.html](https://states-language.net/spec.html)

{{#include ../../../banners/hacktricks-training.md}}