Tutorials: security-batch-11 (5 tutorials)

tuts/092-aws-kms-gs/README.md

@@ -0,0 +1,52 @@
+# KMS: Create a key and encrypt data
+
+Create a customer managed KMS key, encrypt and decrypt data, and generate a data key using the AWS CLI.
+
+## Source
+
+https://docs.aws.amazon.com/kms/latest/developerguide/getting-started.html
+
+## Use case
+
+- ID: kms/getting-started
+- Phase: create
+- Complexity: beginner
+- Core actions: kms:CreateKey, kms:Encrypt, kms:Decrypt
+
+## What it does
+
+1. Creates a customer managed KMS key
+2. Creates an alias for the key
+3. Describes the key metadata
+4. Encrypts data using fileb://
+5. Decrypts the ciphertext
+6. Generates a data key for client-side encryption
+7. Lists KMS keys and aliases
+
+## Running
+
+```bash
+bash aws-kms-gs.sh
+```
+
+## Resources created
+
+- KMS customer managed key (with alias)
+
+The key costs $1/month until deleted. The script prompts you to clean up when it finishes. Cleanup schedules the key for deletion with a 7-day waiting period.
+
+## Estimated time
+
+- Run: ~7 seconds
+
+## Cost
+
+$1/month for the customer managed key. Delete the key promptly to avoid charges.
+
+## Related docs
+
+- [Getting started with AWS KMS](https://docs.aws.amazon.com/kms/latest/developerguide/getting-started.html)
+- [Creating keys](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html)
+- [Encrypting and decrypting data](https://docs.aws.amazon.com/kms/latest/developerguide/programming-encryption.html)
+- [Data keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#data-keys)
+- [Deleting KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/deleting-keys.html)

tuts/092-aws-kms-gs/REVISION-HISTORY.md

@@ -0,0 +1,8 @@
+# Revision History: 092-aws-kms-gs
+
+## Shell (CLI script)
+
+### 2026-04-14 v1 published
+- Type: functional
+- Initial version
+

tuts/092-aws-kms-gs/aws-kms-gs.md

@@ -0,0 +1,91 @@
+# Create a key and encrypt data with AWS KMS
+
+This tutorial shows you how to create a customer managed KMS key, assign it an alias, encrypt and decrypt data, and generate a data key for client-side encryption.
+
+## Prerequisites
+
+- AWS CLI configured with credentials and a default region
+- Permissions for `kms:CreateKey`, `kms:CreateAlias`, `kms:DescribeKey`, `kms:Encrypt`, `kms:Decrypt`, `kms:GenerateDataKey`, `kms:ListAliases`, `kms:ScheduleKeyDeletion`, `kms:DeleteAlias`
+
+## Step 1: Create a customer managed key
+
+```bash
+KEY_ID=$(aws kms create-key --description "Tutorial key" \
+    --query 'KeyMetadata.KeyId' --output text)
+echo "Key ID: $KEY_ID"
+```
+
+KMS returns the key metadata including the key ID, ARN, and state. The key is enabled immediately.
+
+## Step 2: Create an alias
+
+An alias is a friendly name for your key. Alias names must start with `alias/`.
+
+```bash
+aws kms create-alias --alias-name "alias/tutorial-key" --target-key-id "$KEY_ID"
+```
+
+## Step 3: Describe the key
+
+```bash
+aws kms describe-key --key-id "$KEY_ID" \
+    --query 'KeyMetadata.{KeyId:KeyId,State:KeyState,Created:CreationDate,Description:Description}' \
+    --output table
+```
+
+## Step 4: Encrypt data
+
+Write plaintext to a file and encrypt it using `fileb://` to pass raw bytes:
+
+```bash
+echo "Hello from the KMS tutorial" > plaintext.txt
+aws kms encrypt --key-id "$KEY_ID" \
+    --plaintext "fileb://plaintext.txt" \
+    --output text --query 'CiphertextBlob' > ciphertext.b64
+```
+
+The `fileb://` prefix tells the CLI to read the file as raw binary. The output is base64-encoded ciphertext.
+
+## Step 5: Decrypt data
+
+Decode the base64 ciphertext to binary, then decrypt:
+
+```bash
+base64 --decode ciphertext.b64 > ciphertext.bin
+aws kms decrypt --ciphertext-blob "fileb://ciphertext.bin" \
+    --output text --query 'Plaintext' | base64 --decode
+```
+
+KMS identifies the correct key from metadata embedded in the ciphertext.
+
+## Step 6: Generate a data key
+
+A data key lets you encrypt data locally. KMS returns both a plaintext key (for immediate use) and an encrypted copy (to store alongside your data).
+
+```bash
+aws kms generate-data-key --key-id "$KEY_ID" --key-spec AES_256 \
+    --query '{KeyId:KeyId}' --output table
+```
+
+## Step 7: List keys
+
+```bash
+aws kms list-aliases \
+    --query 'Aliases[?starts_with(AliasName, `alias/tutorial`)].{Alias:AliasName,KeyId:TargetKeyId}' \
+    --output table
+```
+
+## Cleanup
+
+Schedule the key for deletion (minimum 7-day waiting period) and delete the alias:
+
+```bash
+aws kms schedule-key-deletion --key-id "$KEY_ID" --pending-window-in-days 7
+aws kms delete-alias --alias-name "alias/tutorial-key"
+```
+
+The key incurs $1/month until the scheduled deletion completes. The script automates all steps including cleanup:
+
+```bash
+bash aws-kms-gs.sh
+```

tuts/092-aws-kms-gs/aws-kms-gs.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# Tutorial: Create a KMS key and encrypt data
+# Source: https://docs.aws.amazon.com/kms/latest/developerguide/getting-started.html
+
+WORK_DIR=$(mktemp -d)
+LOG_FILE="$WORK_DIR/kms-$(date +%Y%m%d-%H%M%S).log"
+exec > >(tee -a "$LOG_FILE") 2>&1
+
+REGION=${AWS_DEFAULT_REGION:-${AWS_REGION:-$(aws configure get region 2>/dev/null)}}
+if [ -z "$REGION" ]; then
+    echo "ERROR: No AWS region configured. Set one with: export AWS_DEFAULT_REGION=us-east-1"
+    exit 1
+fi
+export AWS_DEFAULT_REGION="$REGION"
+echo "Region: $REGION"
+
+RANDOM_ID=$(cat /dev/urandom | tr -dc 'a-z0-9' | fold -w 8 | head -n 1)
+ALIAS_NAME="alias/tutorial-key-${RANDOM_ID}"
+
+handle_error() { echo "ERROR on line $1"; trap - ERR; cleanup; exit 1; }
+trap 'handle_error $LINENO' ERR
+
+cleanup() {
+    echo ""
+    echo "Cleaning up resources..."
+    if [ -n "$KEY_ID" ]; then
+        aws kms schedule-key-deletion --key-id "$KEY_ID" --pending-window-in-days 7 > /dev/null 2>&1 && \
+            echo "  Scheduled key $KEY_ID for deletion in 7 days"
+    fi
+    aws kms delete-alias --alias-name "$ALIAS_NAME" 2>/dev/null && echo "  Deleted alias $ALIAS_NAME"
+    rm -rf "$WORK_DIR"
+    echo "Cleanup complete."
+}
+
+# Step 1: Create a customer managed key
+echo "Step 1: Creating a customer managed KMS key"
+KEY_ID=$(aws kms create-key --description "Tutorial key ${RANDOM_ID}" \
+    --query 'KeyMetadata.KeyId' --output text)
+echo "  Key ID: $KEY_ID"
+
+# Step 2: Create an alias
+echo "Step 2: Creating alias: $ALIAS_NAME"
+aws kms create-alias --alias-name "$ALIAS_NAME" --target-key-id "$KEY_ID"
+echo "  Alias created"
+
+# Step 3: Describe the key
+echo "Step 3: Describing the key"
+aws kms describe-key --key-id "$KEY_ID" \
+    --query 'KeyMetadata.{KeyId:KeyId,State:KeyState,Created:CreationDate,Description:Description}' --output table
+
+# Step 4: Encrypt data
+echo "Step 4: Encrypting data"
+echo "Hello from the KMS tutorial" > "$WORK_DIR/plaintext.txt"
+aws kms encrypt --key-id "$KEY_ID" \
+    --plaintext "fileb://$WORK_DIR/plaintext.txt" \
+    --output text --query 'CiphertextBlob' > "$WORK_DIR/ciphertext.b64"
+echo "  Plaintext: $(cat "$WORK_DIR/plaintext.txt")"
+echo "  Ciphertext (base64, first 40 chars): $(head -c 40 "$WORK_DIR/ciphertext.b64")..."
+
+# Step 5: Decrypt data
+echo "Step 5: Decrypting data"
+cat "$WORK_DIR/ciphertext.b64" | base64 --decode > "$WORK_DIR/ciphertext.bin"
+aws kms decrypt --ciphertext-blob "fileb://$WORK_DIR/ciphertext.bin" \
+    --output text --query 'Plaintext' | base64 --decode > "$WORK_DIR/decrypted.txt"
+echo "  Decrypted: $(cat "$WORK_DIR/decrypted.txt")"
+
+# Step 6: Generate a data key
+echo "Step 6: Generating a data key"
+aws kms generate-data-key --key-id "$KEY_ID" --key-spec AES_256 \
+    --query '{KeyId:KeyId}' --output table
+echo "  Data key generated (plaintext + encrypted copy returned)"
+
+# Step 7: List keys
+echo "Step 7: Listing KMS keys (first 5)"
+aws kms list-aliases --query 'Aliases[?starts_with(AliasName, `alias/tutorial`)].{Alias:AliasName,KeyId:TargetKeyId}' --output table
+
+echo ""
+echo "Tutorial complete."
+echo "Do you want to clean up all resources? (y/n): "
+read -r CHOICE
+if [[ "$CHOICE" =~ ^[Yy]$ ]]; then
+    cleanup
+else
+    echo "Resources left running. The key will incur $1/month until deleted."
+    echo "Manual cleanup:"
+    echo "  aws kms schedule-key-deletion --key-id $KEY_ID --pending-window-in-days 7"
+    echo "  aws kms delete-alias --alias-name $ALIAS_NAME"
+fi

tuts/102-amazon-guardduty-gs/README.md

@@ -0,0 +1,55 @@
+# GuardDuty: Enable threat detection and review findings
+
+## Source
+
+https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_settingup.html
+
+## Use case
+
+- **ID**: guardduty/getting-started
+- **Level**: beginner
+- **Core actions**: `guardduty:CreateDetector`, `guardduty:ListFindings`, `guardduty:GetFindings`, `guardduty:CreateSampleFindings`
+
+## Steps
+
+1. Enable GuardDuty (handle pre-existing detector)
+2. Get detector details
+3. List findings
+4. Generate sample findings
+5. List findings again
+6. Get finding statistics
+
+## Resources created
+
+| Resource | Type |
+|----------|------|
+| GuardDuty detector | `AWS::GuardDuty::Detector` |
+
+## Duration
+
+~13 seconds
+
+## Cost
+
+GuardDuty offers a free 30-day trial for new accounts. After the trial, pricing is based on the volume of data analyzed (VPC flow logs, DNS logs, CloudTrail events). The detector is deleted during cleanup.
+
+## Related docs
+
+- [Setting up GuardDuty](https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_settingup.html)
+- [Understanding GuardDuty findings](https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_findings.html)
+- [Managing GuardDuty detectors](https://docs.aws.amazon.com/guardduty/latest/ug/guardduty_managing.html)
+- [Sample findings](https://docs.aws.amazon.com/guardduty/latest/ug/sample_findings.html)
+
+---
+
+## Appendix
+
+| Field | Value |
+|-------|-------|
+| Date | 2026-04-14 |
+| Script lines | 97 |
+| Exit code | 0 |
+| Runtime | 13s |
+| Steps | 6 |
+| Issues | Handled pre-existing detector |
+| Version | v1 |

tuts/102-amazon-guardduty-gs/REVISION-HISTORY.md

@@ -0,0 +1,8 @@
+# Revision History: 102-amazon-guardduty-gs
+
+## Shell (CLI script)
+
+### 2026-04-14 v1 published
+- Type: functional
+- Initial version
+