# AWS - Step Functions Enum

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

## Step Functions

AWS Step Functions is 'n werksvloei-diens wat jou in staat stel om verskeie AWS-dienste in serverless werksvloeie te koördineer en te orkestreer. Deur AWS Step Functions te gebruik, kan jy werksvloeie ontwerp en uitvoer wat verskeie AWS-dienste soos AWS Lambda, Amazon S3, Amazon DynamoDB, en vele meer, in 'n volgorde van stappe verbind. Hierdie orkestrasiediens bied 'n visuele werksvloei-koppelvlak en bied **state machine** vermoëns, wat jou toelaat om elke stap van die werksvloei op 'n deklaratiewe manier te definieer met behulp van JSON-gebaseerde **Amazon States Language** (ASL).

## Sleutelkonsepte

### Standaard vs. Express Werksvloeie

AWS Step Functions bied twee tipes **state machine workflows**: Standaard en Express.

- **Standaard Werksvloei**: Hierdie standaard werksvloei tipe is ontwerp vir langlopende, duursame, en auditeerbare prosesse. Dit ondersteun **exactly-once execution**, wat verseker dat take slegs een keer uitgevoer word tensy herhalings gespesifiseer word. Dit is ideaal vir werksvloeie wat gedetailleerde uitvoeringsgeskiedenis benodig en kan tot een jaar lank loop.
- **Express Werksvloei**: Hierdie tipe is ideaal vir hoë-volume, kort duur take, wat tot vyf minute kan loop. Hulle ondersteun **at-least-once execution**, geskik vir idempotente take soos data verwerking. Hierdie werksvloeie is geoptimaliseer vir koste en prestasie, en hef fooie gebaseer op uitvoerings, duur, en geheuegebruik.

### State

State is die essensiële eenhede van state machines. Hulle definieer die individuele stappe binne 'n werksvloei, en kan 'n verskeidenheid funksies uitvoer, afhangende van sy tipe:

- **Taak:** Voer 'n werk uit, dikwels met 'n AWS-diens soos Lambda.
- **Keuse:** Neem besluite gebaseer op insette.
- **Misluk/Slaag:** Eindig die uitvoering met 'n mislukking of sukses.
- **Oorgang:** Gee insette aan uitsette of voeg data in.
- **Wag:** Vertraag uitvoering vir 'n bepaalde tyd.
- **Parallel:** Begin parallelle takke.
- **Kaart:** Dinamies herhaal stappe oor items.

### Taak

'n **Taak** state verteenwoordig 'n enkele eenheid van werk wat deur 'n state machine uitgevoer word. Take kan verskeie hulpbronne aanroep, insluitend aktiwiteite, Lambda funksies, AWS dienste, of derdeparty API's.

- **Aktiwiteite**: Pasgemaakte werkers wat jy bestuur, geskik vir langlopende prosesse.
- Hulpbron: **`arn:aws:states:region:account:activity:name`**.
- **Lambda Funksies**: Voer AWS Lambda funksies uit.
- Hulpbron: **`arn:aws:lambda:region:account:function:function-name`**.
- **AWS Dienste**: Integreer direk met ander AWS dienste, soos DynamoDB of S3.
- Hulpbron: **`arn:partition:states:region:account:servicename:APIname`**.
- **HTTP Taak**: Roep derdeparty API's aan.
- Hulpbron veld: **`arn:aws:states:::http:invoke`**. Dan moet jy die API eindpunt konfigurasie besonderhede verskaf, soos die API URL, metode, en outentikasie besonderhede.

Die volgende voorbeeld toon 'n Taak state definisie wat 'n Lambda funksie genaamd HelloWorld aanroep:
```json
"HelloWorld": {
"Type": "Task",
"Resource": "arn:aws:states:::lambda:invoke",
"Parameters": {
"Payload.$": "$",
"FunctionName": "arn:aws:lambda:<region>:<account-id>:function:HelloWorld"
},
"End": true
}
```
### Keuse

'n **Keuse** toestand voeg voorwaardelike logika by 'n werksvloei, wat besluite op grond van invoerdata moontlik maak. Dit evalueer die gespesifiseerde voorwaardes en oorweeg na die ooreenstemmende toestand op grond van die resultate.

- **Vergelyking**: Elke keuse-reël sluit 'n vergelykingsoperateur in (bv. **`NumericEquals`**, **`StringEquals`**) wat 'n invoervariabele met 'n gespesifiseerde waarde of 'n ander variabele vergelyk.
- **Volgende Veld**: Keuse toestande ondersteun nie die **`End`** veld nie, eerder, hulle definieer die **`Next`** toestand om na oor te skakel as die vergelyking waar is.

Voorbeeld van **Keuse** toestand:
```json
{
"Variable": "$.timeStamp",
"TimestampEquals": "2000-01-01T00:00:00Z",
"Next": "TimeState"
}
```
### Misluk/Sukses

'n **`Misluk`** toestand stop die uitvoering van 'n toestandmasjien en merk dit as 'n mislukking. Dit word gebruik om 'n foutnaam en 'n oorsaak te spesifiseer, wat besonderhede oor die mislukking verskaf. Hierdie toestand is terminal, wat beteken dit beëindig die uitvoeringsvloei.

'n **`Sukses`** toestand stop die uitvoering suksesvol. Dit word tipies gebruik om die werksvloei te beëindig wanneer dit suksesvol voltooi is. Hierdie toestand vereis nie 'n **`Next`** veld nie.

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

{{#tab name="Sukses voorbeeld" }}
```json
"SuccessState": {
"Type": "Succeed"
}
```
{{#endtab }}
{{#endtabs }}

### Pass

'n **Pass** toestand stuur sy invoer na sy uitvoer, hetsy sonder om enige werk te verrig of JSON toestand invoer te transformeer met behulp van filters, en dan die getransformeerde data na die volgende toestand te stuur. Dit is nuttig vir toetsing en die konstruksie van toestandmasjiene, wat jou toelaat om statiese data in te voeg of dit te transformeer.
```json
"PassState": {
"Type": "Pass",
"Result": {"key": "value"},
"ResultPath": "$.newField",
"Next": "NextState"
}
```
### Wag

'n **Wag** toestand vertraag die uitvoering van die toestandmasjien vir 'n spesifieke duur. Daar is drie primêre metodes om die wagtyd te konfigureer:

- **X Sekondes**: 'n Vasgestelde aantal sekondes om te wag.

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

- **Absoluut Tydstempel**: 'n Presiese tyd om te wag tot.

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

- **Dinamiese Wag**: Gebaseer op invoer met behulp van **`SecondsPath`** of **`TimestampPath`**.

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

### Parallel

'n **Parallel** toestand laat jou toe om verskeie takke van take gelyktydig binne jou werksvloei uit te voer. Elke tak loop onafhanklik en verwerk sy eie volgorde van toestande. Die uitvoering wag totdat al die takke voltooi is voordat dit na die volgende toestand voortgaan. Sy sleutelvelde is:

- **Takke**: 'n Array wat die parallelle uitvoeringspaaie definieer. Elke tak is 'n aparte toestandmasjien.
- **ResultPath**: Definieer waar (in die invoer) om die saamgevoegde uitvoer van die takke te plaas.
- **Hernu en Vang**: Fouthanteringskonfigurasies vir die parallelle toestand.
```json
"ParallelState": {
"Type": "Parallel",
"Branches": [
{
"StartAt": "Task1",
"States": { ... }
},
{
"StartAt": "Task2",
"States": { ... }
}
],
"Next": "NextState"
}
```
### Map

'n **Map** toestand stel die uitvoering van 'n stel stappe vir elke item in 'n dataset in staat. Dit word gebruik vir parallelle verwerking van data. Afhangende van hoe jy die items van die dataset wil verwerk, bied Step Functions die volgende modi aan:

- **Inline Mode**: Voer 'n substel van toestande uit vir elke JSON-array item. Geschik vir klein skaal take met minder as 40 parallelle iterasies, wat elkeen in die konteks van die werksvloei wat die **`Map`** toestand bevat, loop.

```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"
}
```

- **Distributed Mode**: Ontwerp vir groot skaal parallelle verwerking met hoë mededinging. Ondersteun die verwerking van groot datasets, soos dié wat in Amazon S3 gestoor is, wat 'n hoë mededinging van tot 10,000 parallelle kind werksvloei-uitvoerings moontlik maak, wat hierdie kinders as 'n aparte kind uitvoering loop.

```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"
}
}
}
```

### Versions and aliases

Step Functions laat jou ook toe om werksvloei-implementasies te bestuur deur middel van **versies** en **aliases** van toestandmasjiene. 'n weergawe verteenwoordig 'n snapshot van 'n toestandmasjien wat uitgevoer kan word. Aliases dien as wysers na tot twee weergawes van 'n toestandmasjien.

- **Versies**: Hierdie onveranderlike snapshots van 'n toestandmasjien word geskep vanaf die mees onlangse hersiening van daardie toestandmasjien. Elke weergawe word geïdentifiseer deur 'n unieke ARN wat die toestandmasjien ARN met die weergawe nommer kombineer, geskei deur 'n dubbelepunt (**`arn:aws:states:region:account-id:stateMachine:StateMachineName:version-number`**). Weergawes kan nie gewysig word nie, maar jy kan die toestandmasjien opdateer en 'n nuwe weergawe publiseer, of die gewenste toestandmasjien weergawe gebruik.
- **Aliases**: Hierdie wysers kan na tot twee weergawes van dieselfde toestandmasjien verwys. Meervoudige aliases kan geskep word vir 'n enkele toestandmasjien, elkeen geïdentifiseer deur 'n unieke ARN wat die toestandmasjien ARN met die alias naam kombineer, geskei deur 'n dubbelepunt (**`arn:aws:states:region:account-id:stateMachine:StateMachineName:aliasName`**). Aliases stel die roetering van verkeer tussen een van die twee weergawes van 'n toestandmasjien in staat. Alternatiewelik kan 'n alias na 'n enkele spesifieke weergawe van die toestandmasjien wys, maar nie na ander aliases nie. Hulle kan opgedateer word om na 'n ander weergawe van die toestandmasjien te herlei soos nodig, wat beheerde implementasies en werksvloei-bestuur fasiliteer.

Vir meer gedetailleerde inligting oor **ASL**, kyk: [**Amazon States Language**](https://states-language.net/spec.html).

## IAM Roles for State machines

AWS Step Functions gebruik AWS Identity and Access Management (IAM) rolle om toegang tot hulpbronne en aksies binne toestandmasjiene te beheer. Hier is die sleutel aspekte wat verband hou met sekuriteit en IAM rolle in AWS Step Functions:

- **Execution Role**: Elke toestandmasjien in AWS Step Functions is geassosieer met 'n IAM uitvoering rol. Hierdie rol definieer watter aksies die toestandmasjien namens jou kan uitvoer. Wanneer 'n toestandmasjien tussen toestande oorgaan wat met AWS dienste interaksie het (soos die aanroep van Lambda funksies, toegang tot DynamoDB, ens.), neem dit hierdie uitvoering rol aan om daardie aksies uit te voer.
- **Permissions**: Die IAM uitvoering rol moet geconfigureer word met toestemmings wat die nodige aksies op ander AWS dienste toelaat. Byvoorbeeld, as jou toestandmasjien AWS Lambda funksies moet aanroep, moet die IAM rol **`lambda:InvokeFunction`** toestemmings hê. Net so, as dit na DynamoDB moet skryf, moet toepaslike toestemmings (**`dynamodb:PutItem`**, **`dynamodb:UpdateItem`**, ens.) toegestaan word.

## Enumeration

ReadOnlyAccess beleid is genoeg vir al die volgende enumerasie aksies.
```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>]
```
## Privesc

In die volgende bladsy kan jy kyk hoe om **Step Functions toestemming te misbruik om voorregte te verhoog**:

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

## Post Exploitation

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

## Persistence

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

## References

- [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}}