Skip to Content
Cloud Engineering Academy
5. Security for Banking & Finance

Module project: a secure banking API (field encryption, roles, audit, secrets and incident runbooks) with Labs 5.4 to 5.6

Run and extend the secure edition of the Harbourline Accounts API: field-level encryption bound to the customer, a blind index for IBAN search, role-based access with segregation of duties, audit events and masked logs, Terraform for KMS, secrets and a least-privilege role, plus the CloudTrail, GuardDuty and pipeline-scanning labs and two incident runbooks.

advanced⏱ 4 h 🟡 Low costSCS-C03SAA-C03DVA-C03

Assumes: .NET 10 LTS · ASP.NET Core 10 · AWS SDK for .NET v4 (AWSSDK.KeyManagementService 4.1.1.1) · xUnit v3 4.0.3 · Terraform 1.10+ with AWS provider v6 · AWS CLI v2 · Region us-east-1. Verified against official sources on 2026-11-18.

Learning objectives

By the end of this project you can:

  • Run the secure Accounts API locally and show, with tests and curl, that stored customer records hold no plaintext identity fields, that support staff only ever see masked data, and that only a KYC officer can reveal Restricted fields.
  • Explain the design: field-level envelope encryption bound to customer_id and field, a blind index (HMAC) for IBAN search, role-based access with segregation of duties (a KYC officer cannot sign payments), idempotent payment signing, audit events for every request including denied ones, and security headers.
  • Read the Terraform that creates the KMS keys, a secret container, a Parameter Store entry and a least-privilege task role, and say what each statement is for.
  • Run Lab 5.4 (CloudTrail log file validation: tamper with a log copy and detect it) and Lab 5.5 (GuardDuty and Security Hub CSPM in one Region, sample findings, then disable) from the lab's scripts, with teardown.
  • Use the Lab 5.6 scanning pipeline definition (tests, dependency vulnerabilities, IAM policy lint, secrets scan, IaC scan) and explain why each step exists.
  • Use the two runbooks, "leaked access key" and "suspicious data download", in a tabletop exercise, and say which parts of the project's logging make each investigation possible.
  • Be explicit about what this project does not implement (private networking, WAF, automatic secret rotation, a real identity provider) and where those parts are covered.

This is the module project for Module 5 and feeds Capstone 1 and Capstone 7.

Prerequisites

Why this matters in banking

The customer table is the most valuable thing a retail bank owns. A single leaked access key, a support agent with too much visibility or a SQL injection can turn it into an incident with a regulator's name on it. A secure design does not assume any one control holds. If the database is stolen, the identity fields are ciphertext. If a support account is abused, it can only see masked data, and the log shows who asked. If a KYC officer's session is hijacked, the reveals are traceable to individual customers through KMS logs. If a key leaks, there is a runbook. The project is that design, small enough to read in an afternoon and complete enough to run.

The idea in plain language

The API has three roles and a small set of endpoints:

RoleMay do
supportView customers (masked only)
kyc-officerCreate customers, view them, reveal identity fields, search by IBAN
payments-approverSign payment instructions

A customer record has two kinds of fields. Ordinary fields (name, email, country) are stored as is. Restricted fields (date of birth, IBAN) are encrypted, and each ciphertext is bound to customer_id and the field name. The API also stores a masked IBAN (so masked reads never call KMS) and a blind index, a keyed hash of the IBAN, so an officer can search by IBAN without decrypting every row.

Analogy: a records room with a clerk window. Support staff are served photocopies with sensitive parts blacked out. A KYC officer can ask the clerk to open the sealed envelope, and the clerk writes the officer's name and the customer's file number in the register. The register is never edited. Payments staff work in a different room entirely, so no one person can both change a customer's identity and approve money leaving.

What the AWS services do here

ServiceRoleIn the project
AWS KMSWraps data keys, signs payment instructionsalias/hl-m05-data (symmetric), alias/hl-m05-payment-signing (ECC P-256), alias/hl-m05-secrets
AWS Secrets ManagerHolds the blind-index HMAC keyhl-m05/accounts-api/blind-index-key, read through a 15-minute caching reader
AWS Systems Manager Parameter StoreNon-secret configuration/hl-m05/accounts-api/config (Standard tier, no charge)
AWS IAMLeast-privilege task rolehl-m05-accounts-api with the exact calls the code makes
AWS CloudTrailManagement-event record of key and secret useLab 5.4 trail with log file validation
Amazon GuardDuty and AWS Security Hub CSPMThreat detection and postureLab 5.5, one Region, free trial
Amazon ECS on Fargate, ALB, AWS WAFWhere the API would run in productionNot built here. Design reference: Module 3, WAF and Shield and Segmentation and egress control

Microsoft / Azure comparison

You know (Microsoft/Azure)In this projectWhat's different
Azure Key Vault + Managed IdentityKMS + Secrets Manager + an IAM task roleThe role gets only specific actions on specific keys, and a condition on the encryption context
SQL Always Encrypted with column master keysFieldEncryptor with a KMS keyApplication-level, and searchable only through an explicit blind index
Azure Monitor audit logs and Activity LogAuditMiddleware events plus CloudTrailTwo layers: your application's "who did what to which resource", and AWS's "who used which key"
Defender for CloudGuardDuty + Security Hub CSPMTwo services: findings (GuardDuty) and posture checks and aggregation (Security Hub CSPM)
App roles from Entra IDCognito groups in the cognito:groups claimRole names arrive as claims in the JWT; the app maps them to policies
Microsoft.Extensions.Compliance.RedactionLogRedactor driven by [Classified] attributesThe same idea, with unclassified properties failing safe

Architecture

Security-boundary view: the internet is untrusted; the API is trusted to enforce roles, encrypt fields and never log Restricted values; KMS is trusted to hold keys and enforce key policy; the database is not trusted with plaintext identity fields, because a stolen database must be useless without KMS.

Step-by-step implementation

The project folder is labs/m05-secure-banking-api.

policies/                               IAM policies and ten puzzles (Labs 5.1, 5.2)
src/Harbourline.Security.PolicyLinter   hl-policy: lint, explain and evaluate policies offline
src/Harbourline.Security.Crypto         envelope and field encryption, signing, masking, tokenising,
                                        blind index, pseudonymiser, classification, LocalDevelopmentKms
src/Harbourline.Security.Secrets        caching Secrets Manager reader, Parameter Store reader
src/Harbourline.Security.Tools          hl-crypto: Lab 5.3 and 5.7 demos
src/Harbourline.Accounts.SecureApi      the module project
tests/Harbourline.SecureBanking.Tests   72 tests (1 AWS integration test, skipped unless RUN_AWS_TESTS=1)
infra/terraform                         KMS keys, secret, parameter, least-privilege task role
scripts/                                Lab 5.4 (CloudTrail validation) and Lab 5.5 (GuardDuty + Security Hub CSPM)
pipelines/security-scan.yml             Lab 5.6 scanning pipeline
docs/runbooks/                          leaked access key, suspicious data download

Part 1: run the tests (free)

Run them in Docker

MSYS_NO_PATHCONV=1 docker run --rm --memory 3g \
  -v "$PWD/labs/m05-secure-banking-api:/src" \
  -v cea-nuget-m05:/root/.nuget/packages \
  -w /src mcr.microsoft.com/dotnet/sdk:10.0 \
  sh -c "dotnet test --solution SecureBankingApi.slnx; find . -type d \( -name bin -o -name obj \) -prune -exec rm -rf {} +"

Expected result (verified 2026-11-18 in Docker): total: 72, failed: 0, succeeded: 71, skipped: 1.

Map the API tests to the requirements

RequirementTest
Health is anonymous; everything else needs authenticationHealth_is_anonymous, Anonymous_callers_get_401_problem_details
Create returns a masked view onlyCreate_returns_a_masked_view_only
Storage holds no plaintext identity fieldsStored_record_contains_no_plaintext_identity_fields
Support sees masked data and cannot revealSupport_sees_masked_data_and_cannot_reveal
KYC officer can revealKyc_officer_can_reveal_identity_fields
IBAN search uses the blind indexIban_search_uses_the_blind_index
Validation (including the IBAN mod-97 check)Invalid_input_returns_validation_problem, Iban_checksum_validation
Segregation of dutiesKyc_officer_cannot_sign_payments_segregation_of_duties
Idempotent signingSigning_is_idempotent_and_rejects_key_reuse_with_a_different_body
Denied requests are auditedDenied_requests_are_audited_with_actor_and_correlation_id
Security headersResponses_carry_security_headers
Classification covers every stored fieldEvery_stored_customer_field_is_classified (a guard that fails when someone adds a field without classifying it)
Log redaction follows classificationLog_redactor_follows_classification
MaskingIban_masking, Pan_masking, Email_masking
Tokenising and pseudonymisingTokeniser_round_trips_and_is_deterministic, Pseudonymiser_keeps_formats_and_joins
Blind indexBlind_index_is_deterministic_and_normalised, Blind_index_differs_per_field_and_per_key, Short_keys_are_rejected
Secrets caching and rotationCached_value_is_reused_until_the_ttl_expires, Invalidate_forces_a_refresh_after_rotation, Concurrent_readers_trigger_one_remote_call, Missing_secret_surfaces_the_sdk_exception, Parameter_store_reader_asks_for_decryption, credential parsing never echoes the password

Part 2: run the API locally and play the roles (free)

Start it

dotnet run --project src/Harbourline.Accounts.SecureApi --environment Development --urls http://localhost:5080

In Development the API uses LocalDevelopmentKms and accepts two dev-only headers, X-Hl-Dev-User and X-Hl-Dev-Roles (roles support, kyc-officer, payments-approver). The console shows one audit {...} JSON line per request. Data is in memory and disappears when the process stops.

Create a customer as a KYC officer

curl -s -X POST http://localhost:5080/customers \
  -H "X-Hl-Dev-User: kyc.jo" -H "X-Hl-Dev-Roles: kyc-officer" -H "Content-Type: application/json" \
  -d '{"firstName":"Alex","lastName":"Taylor","dateOfBirth":"1984-03-09","email":"alex.taylor@example.com","country":"GB","iban":"GB82WEST12345698765432"}'

The response is a masked view: the email as a***@example.com, the IBAN as GB82**************5432, no date of birth, revealed: false. Note the customerId (CUS- plus eight digits).

Read it as support, then as the officer

curl -s http://localhost:5080/customers/<id> -H "X-Hl-Dev-User: support.sam" -H "X-Hl-Dev-Roles: support"
curl -s "http://localhost:5080/customers/<id>?reveal=true" -H "X-Hl-Dev-User: support.sam" -H "X-Hl-Dev-Roles: support"
curl -s "http://localhost:5080/customers/<id>?reveal=true" -H "X-Hl-Dev-User: kyc.jo" -H "X-Hl-Dev-Roles: kyc-officer"

The first returns masked data. The second returns 403 with a ProblemDetails: revealing identity fields requires the kyc-officer role. The third returns the decrypted IBAN and date of birth with revealed: true. Watch the console: all three requests produced audit lines with the actor, the action and the outcome (success or denied), and none contains the body.

Search by IBAN, then try to sign a payment as the wrong role

curl -s -X POST http://localhost:5080/customers/search \
  -H "X-Hl-Dev-User: kyc.jo" -H "X-Hl-Dev-Roles: kyc-officer" -H "Content-Type: application/json" \
  -d '{"iban":"GB82 WEST 1234 5698 7654 32"}'

curl -i -X POST http://localhost:5080/payments/sign \
  -H "X-Hl-Dev-User: kyc.jo" -H "X-Hl-Dev-Roles: kyc-officer" -H "Idempotency-Key: 11111111-2222-3333-4444-555555555555" \
  -H "Content-Type: application/json" -d '{}'

Search normalises the IBAN (spaces and case are ignored), computes the HMAC and finds the row without decrypting anything. Signing as a KYC officer returns 403: segregation of duties. Repeat as payments-approver with a valid payment body to see a signed instruction, and repeat the same request to see the stored response replayed.

Part 3: read the design decisions (free)

Field encryption and reveal (Customers.cs)

CustomerService.CreateAsync encrypts the date of birth and the IBAN as enc:v1: tokens, each with the context {customer_id, field}. GetAsync decrypts only when reveal is true, and the endpoint checks the kyc-officer role before calling it. Every decrypt is one KMS call with the customer id in the context, so CloudTrail shows exactly whose fields were revealed. The masked IBAN and the blind index are computed at write time, so masked reads and searches never call KMS.

Blind index (BlindIndex.cs)

Encrypted values are randomised: the same IBAN encrypts differently twice, so it cannot be searched. The blind index is HMAC-SHA256(key, field + U+001F + normalised value). Without the HMAC key, an attacker with the table cannot recompute it, unlike a plain SHA-256 hash, which is trivial to brute-force for low-entropy values. The trade-offs are written in the source: equality search only, equal values are visibly equal, and the key is as sensitive as the data key. The key lives in Secrets Manager. It is not rotated automatically because rotating it means rebuilding the index; a runbook step covers manual rotation (see Secrets Manager and Parameter Store).

Roles and segregation of duties (ServiceSetup.cs)

Three roles, four policies: CanViewCustomers (support or KYC officer), CanManageCustomers (KYC officer), CanSignPayments (payments approver), and a fallback policy that requires an authenticated user for anything not otherwise marked. In production the roles come from the cognito:groups claim of a validated JWT (MapInboundClaims = false, NameClaimType = "username", RoleClaimType = "cognito:groups"). The source notes that Cognito access tokens carry client_id and not aud, so if you accept access tokens you must validate client_id in a policy.

Audit and headers (Security.cs)

AuditMiddleware runs after authentication (so the actor is known) and wraps authorisation (so 401s and 403s are recorded). It writes one JSON line per request: event id, time, actor, action (the route pattern, not the raw URL), resource, outcome (success, rejected, denied, unauthenticated, error), source IP and correlation id. It never logs bodies, and it accepts a caller's correlation id only if it is 8 to 64 safe characters, to prevent log injection. SecurityHeadersMiddleware sets nosniff, Cache-Control: no-store, a restrictive CSP and Referrer-Policy: no-referrer, and Kestrel's Server header is disabled.

Classification and masking (DataClassification.cs, DataMasking.cs)

Every stored field carries a [Classified] level: Public, Internal, Confidential (masked in logs) or Restricted (encrypted at field level and never logged). LogRedactor turns an object into a log-safe dictionary and marks any unlabelled property [UNCLASSIFIED], so a new field cannot leak by default. The test Every_stored_customer_field_is_classified makes forgetting a label a build failure.

Fail closed (ServiceSetup.cs)

Crypto:Mode=Local is refused outside Development and Testing with an exception. Local KMS, the dev header handler and the in-memory tokeniser are learning shortcuts that must not run in production, and the code enforces that rather than trusting configuration discipline.

Part 4: deploy the supporting infrastructure (optional, credits)

Cost and scope

Three KMS keys (about 1 USD per key-month, prorated hourly) and one secret (about 0.40 USD per month, prorated) cost a few cents if destroyed the same day (⚠ VERIFY current prices). Use only the sandbox account.

Apply the Terraform

aws sso login --profile learn-sandbox
cd labs/m05-secure-banking-api/infra/terraform
cp backend.hcl.example backend.hcl        # edit the bucket name, or: terraform init -backend=false
terraform init -backend-config=backend.hcl
terraform apply -var owner=<your-name>

The configuration validated in this build (Terraform 1.14 image, init -backend=false then validate: "The configuration is valid"). It was not applied here. It creates the three keys and aliases, the role hl-m05-accounts-api (assumable only by ECS tasks in your account, with an aws:SourceAccount condition against the confused-deputy problem), a secret container and a Parameter Store entry.

Put a random blind-index key in the secret

Terraform creates only the container, so the value never enters Terraform state:

aws secretsmanager put-secret-value --secret-id hl-m05/accounts-api/blind-index-key \
  --secret-string "$(openssl rand -base64 32)" --profile learn-sandbox

Run the API against real KMS and Secrets Manager

ASPNETCORE_ENVIRONMENT=Development Crypto__Mode=Kms AWS_PROFILE=learn-sandbox AWS_REGION=us-east-1 \
  dotnet run --project src/Harbourline.Accounts.SecureApi

ASPNETCORE_ENVIRONMENT=Development keeps the dev header authentication; Crypto__Mode=Kms switches to real KMS and Secrets Manager with your SSO credentials. Repeat the Part 2 calls, then open CloudTrail and find the GenerateDataKey and Decrypt events with customer_id in the encryption context. Deploying to ECS Fargate behind an ALB with WAF follows Module 3; use the Terraform role as the task role. This part was not run in the build environment (no AWS account), so confirm the behaviour yourself (⚠ VERIFY).

Part 5: Lab 5.4, CloudTrail log file validation (free to cents)

The script scripts/lab-5-4-cloudtrail-validation.sh creates a private bucket, a bucket policy restricted to one trail (with aws:SourceArn) and a TLS-only deny, and a trail with --enable-log-file-validation. Digest files appear roughly hourly, so this lab spans a couple of hours of waiting.

Bring it up

OWNER=<your-name> ./scripts/lab-5-4-cloudtrail-validation.sh up

Make a few API calls (for example aws sts get-caller-identity, aws kms list-aliases). Wait one to two hours for the first digest file.

Validate, tamper, validate again

OWNER=<your-name> ./scripts/lab-5-4-cloudtrail-validation.sh validate

The script first validates untouched logs (aws cloudtrail validate-logs --verbose), then downloads one log file, changes one string (eventName to eventNAME), uploads it back under the same key, and validates again. Expect the second validation to report that the log file is INVALID with a hash mismatch (⚠ VERIFY the exact wording on your CLI version). The point: you can prove a log was altered even if you cannot prevent a privileged user from altering it, which is why production trails go to a separate log-archive account with Object Lock.

Tear down

OWNER=<your-name> ./scripts/lab-5-4-cloudtrail-validation.sh down

It stops and deletes the trail, empties and deletes the bucket. Check that nothing tagged Project=cea-lab remains. The script writes a policy file to /tmp, which works in Git Bash; on other shells adjust the path.

Part 6: Lab 5.5, GuardDuty and Security Hub CSPM (free during trial, then disable)

Enable, generate sample findings, then look

./scripts/lab-5-5-guardduty-securityhub.sh up
./scripts/lab-5-5-guardduty-securityhub.sh findings

The script enables GuardDuty (one detector in one Region) and Security Hub CSPM without enabling every standard (each control evaluation is billed after the trial, ⚠ VERIFY terms and trial availability in your account). It then creates sample findings such as UnauthorizedAccess:IAMUser/InstanceCredentialExfiltration.OutsideAWS and Recon:IAMUser/MaliciousIPCaller, which are marked as samples and reflect no real activity, and lists them. Compare the first finding type with the "leaked access key" runbook's trigger list.

Disable

./scripts/lab-5-5-guardduty-securityhub.sh down

It deletes the GuardDuty detector and disables Security Hub CSPM in that Region. Check both consoles afterwards.

Part 7: Lab 5.6, the scanning pipeline (free)

Copy pipelines/security-scan.yml to .github/workflows/security-scan.yml in your own repository. It runs on every pull request and every push to main, with permissions: contents: read:

StepWhat it catches
Build and testRegressions, including the "every stored field is classified" guard
Dependency vulnerabilities (SCA)Known-vulnerable NuGet packages, direct and transitive (dotnet list package --vulnerable --include-transitive, fails the job if any are reported)
IAM policy lintRuns hl-policy lint on the service's identity policy, using the lab's own tool
Secrets scan (gitleaks)Secrets in the full git history (fetch-depth: 0)
IaC scan (Checkov)Terraform misconfigurations; starts with soft_fail: true so you can triage first, then switch to false so new findings block merges

The pipeline calls nothing in AWS. Check the action versions and the soft_fail guidance against the current tool documentation before relying on it (⚠ VERIFY). See Pipeline security scanning.

Part 8: the runbooks and a tabletop exercise (free)

Read docs/runbooks/leaked-access-key.md and docs/runbooks/suspicious-data-download.md. They follow a shared structure: triggers, contain (a 15-minute target), scope, eradicate and recover, evidence and notification. The key facts:

Leaked access keySuspicious data download
TriggersGuardDuty credential-exfiltration findings, exposed-key notices, a secrets-scanner alert, a person reporting a pasteA spike in kms:Decrypt on the data key, a spike in reveal=true audit events from one actor, GuardDuty or Macie findings
First actionDeactivate the key (do not delete: you lose evidence of which key it was); revoke role sessions if it was an ASIA session keyIdentify the actor from the audit event or CloudTrail; disable the user and revoke sessions; disable the data key only with incident-commander approval
Scope withCloudTrail by access key: persistence (CreateUser, CreateAccessKey, AttachRolePolicy...) and data access (GetSecretValue, kms:Decrypt, S3 reads)CloudTrail Decrypt events grouped by encryptionContext.customer_id: the list of customers whose fields were revealed
NeverDelete the key before capturing evidenceSchedule key deletion during an incident
NotifyThe DPO decides on notification; UK GDPR has a 72-hour clock from awareness for a reportable breach (⚠ confirm with your DPO and legal team)The same, and never copy revealed personal data into the ticket: reference customer IDs only

Run a tabletop: a colleague reads the trigger, you walk through the steps aloud and name the exact command or console location for each. Time yourself against the 15-minute containment target.

AWS Console instructions

  • KMS: Console → Key Management Service → Customer managed keys: check each key's policy, rotation and aliases.
  • Secrets Manager: Console → Secrets Manager → hl-m05/accounts-api/blind-index-key: confirm the encryption key is alias/hl-m05-secrets and that there is no rotation configured.
  • CloudTrail: Console → CloudTrail → Event history, filter by event source kms.amazonaws.com or by access key for the runbook exercise; Trails → your Lab 5.4 trail for log file validation settings.
  • GuardDuty and Security Hub: Console → GuardDuty → Findings; Console → Security Hub → Findings.

Console wording changes over time (⚠ VERIFY).

AWS CLI

# Who used the data key recently, and for which customer? (Event history covers 90 days of management events)
aws cloudtrail lookup-events --lookup-attributes AttributeKey=EventSource,AttributeValue=kms.amazonaws.com \
  --max-results 20 --profile learn-sandbox --region us-east-1

# Runbook step: last use of a suspect access key
aws iam get-access-key-last-used --access-key-id AKIAEXAMPLEKEYID --profile learn-sandbox

# Runbook step: deactivate, do not delete
aws iam update-access-key --user-name <user> --access-key-id AKIAEXAMPLEKEYID --status Inactive --profile learn-sandbox

# Policy gate used in the pipeline, run locally
dotnet run --project src/Harbourline.Security.PolicyLinter -- lint policies/good-accounts-api-read.json

AKIAEXAMPLEKEYID is a placeholder. Never paste real keys into commands saved in history, tickets or chat.

Infrastructure as Code

The project ships Terraform. The task role's policy is the part worth reading closely, because it is the "exactly the calls the code makes" statement of least privilege:

infra/terraform/iam.tf (task role policy)
resource "aws_iam_role_policy" "api" {
  name = "hl-m05-accounts-api"
  role = aws_iam_role.api.id

  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [
      {
        Sid      = "FieldEncryption"
        Effect   = "Allow"
        Action   = ["kms:GenerateDataKey", "kms:Decrypt"]
        Resource = aws_kms_key.data.arn
        Condition = {
          "ForAnyValue:StringEquals" = { "kms:EncryptionContextKeys" = ["customer_id"] }
        }
      },
      {
        Sid      = "PaymentSigning"
        Effect   = "Allow"
        Action   = ["kms:Sign", "kms:Verify", "kms:GetPublicKey"]
        Resource = aws_kms_key.signing.arn
      },
      {
        Sid      = "ReadBlindIndexKey"
        Effect   = "Allow"
        Action   = "secretsmanager:GetSecretValue"
        Resource = aws_secretsmanager_secret.blind_index_key.arn
      },
      {
        Sid      = "DecryptSecretViaSecretsManagerOnly"
        Effect   = "Allow"
        Action   = "kms:Decrypt"
        Resource = aws_kms_key.secrets.arn
        Condition = {
          StringEquals = { "kms:ViaService" = "secretsmanager.${var.region}.amazonaws.com" }
        }
      },
      {
        Sid      = "ReadConfig"
        Effect   = "Allow"
        Action   = "ssm:GetParameter"
        Resource = aws_ssm_parameter.config.arn
      }
    ]
  })
}

Notice that the secret's own KMS key is usable only via Secrets Manager (kms:ViaService), so the application role cannot use that key to decrypt arbitrary data. A CDK equivalent is straightforward; if you write one, remember Amazon.CDK.Tags.Of(this) inside a Stack, and that cdk-nag 3.x registers as Validations.Of(app).AddPlugins(new AwsSolutionsChecks(app, ...)) and takes acknowledgments through Validations.Of(stack).Acknowledge(...) with exact finding IDs (for example AwsSolutions-IAM5[Resource::*]). This project's infrastructure is Terraform only, so no cdk-nag gotchas apply to its code.

Complete code

The complete project is in labs/m05-secure-banking-api/. The two pieces that carry the security argument:

src/Harbourline.Accounts.SecureApi/Customers.cs (create, reveal, search)
var stored = new StoredCustomer(
    customerId,
    request.FirstName.Trim(),
    request.LastName.Trim(),
    request.Email.Trim(),
    request.Country,
    await encryptor.EncryptAsync(customerId, DateOfBirthField, dob, cancellationToken),
    await encryptor.EncryptAsync(customerId, IbanField, iban, cancellationToken),
    DataMasking.MaskIban(iban),
    BlindIndex.Compute(indexKey, IbanField, iban),
    "pending",
    clock.GetUtcNow());
store.Add(stored);
return Masked(stored);

// Each decrypt is a KMS call with the customer_id in the encryption context, so CloudTrail
// records exactly whose identity data was revealed.
var iban = await encryptor.DecryptAsync(customerId, IbanField, stored.IbanCiphertext, cancellationToken);
var dob = await encryptor.DecryptAsync(customerId, DateOfBirthField, stored.DateOfBirthCiphertext, cancellationToken);
src/Harbourline.Accounts.SecureApi/ServiceSetup.cs (roles and fallback policy)
services.AddAuthorizationBuilder()
    .AddPolicy("CanViewCustomers", p => p.RequireRole(Roles.Support, Roles.KycOfficer))
    .AddPolicy("CanManageCustomers", p => p.RequireRole(Roles.KycOfficer))
    .AddPolicy("CanSignPayments", p => p.RequireRole(Roles.PaymentsApprover))
    .SetFallbackPolicy(new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build());
src/Harbourline.Accounts.SecureApi/Customers.cs (the reveal gate)
// Least privilege inside the API: only KYC officers may reveal Restricted fields, and only when they ask.
var wantsReveal = reveal == true;
if (wantsReveal && !http.User.IsInRole(Roles.KycOfficer))
{
    return Results.Problem(statusCode: StatusCodes.Status403Forbidden, title: "Revealing identity fields requires the kyc-officer role.");
}

Code explained line by line

  1. encryptor.EncryptAsync(customerId, DateOfBirthField, dob, ...) encrypts one field under a fresh data key with the context {customer_id, field} and returns an enc:v1: token. The two Restricted fields are stored only as tokens.
  2. DataMasking.MaskIban(iban) computes the masked IBAN once, at write time, so masked reads do not need KMS (and support staff never cause a decrypt).
  3. BlindIndex.Compute(indexKey, IbanField, iban) stores the keyed hash that supports equality search.
  4. return Masked(stored) returns a view with DateOfBirth: null and the masked email and IBAN, even to the officer who created the record. Revealing is a separate, audited, deliberate action.
  5. The reveal gate runs before the service call, so a support user's request never reaches KMS. A denied request is still audited by the middleware that wraps authorisation.
  6. .SetFallbackPolicy(RequireAuthenticatedUser()) means an endpoint added later without an explicit policy is protected by default. /health opts out with AllowAnonymous().
  7. Each Terraform statement in iam.tf matches a call in the code: field encryption, signing, reading the one secret, decrypting that secret through Secrets Manager only, and reading one parameter. If the code starts calling something else, the role must change, which is a reviewable event.

Security considerations

⚠ Learning shortcut — not for production

The customer store is in memory. Authentication in Development uses trusted headers. KMS is faked locally. The secret has recovery_window_in_days = 0. The blind-index key is not rotated. There is no network isolation, no WAF and no real identity provider in the code. The tokeniser is in-memory and deterministic for demonstration. Production needs a managed database (DynamoDB or Aurora, encrypted at rest as well), Cognito or another OIDC provider with MFA and client_id validation, a private network with VPC endpoints, WAF, a rotation plan for every secret, AWS Encryption SDK for envelope format, and a reviewed incident-response process.

  • Threat model first. Do a STRIDE threat model for this API before you add features (Exercise 🟡).
  • Never log Restricted values, tokens, secrets or request bodies. The redactor fails safe, and the audit middleware logs only metadata.
  • Reveal is a privileged operation. Consider requiring a reason code or a second approver, and an alarm on reveal volume per actor (the suspicious-download runbook's first trigger).
  • Segregate duties in identity too: the people who can administer KMS keys should not be the ones who can reveal data.
  • GDPR. Encryption, masking and minimisation are technical measures, not compliance. Retention, lawful basis, subject access requests, erasure and breach notification need legal and data-protection review. For erasure with envelope encryption, per-customer keys or per-customer data keys are a design option to discuss (⚠ legal review).
  • PCI DSS. This project does not store card numbers. If yours does, scoping, key management and logging requirements change; see PCI DSS on AWS. The lab only demonstrates masking helpers with public test card numbers.
  • Nothing here makes a system compliant with PCI DSS or UK GDPR.

Banking use case

An onboarding team creates customers with a KYC officer role. A contact-centre team, using the same API with the support role, sees masked data and handles most calls without any decrypt. When a customer disputes a transaction, a fraud analyst with the KYC role reveals the IBAN, and the reveal is a Decrypt event naming the customer. A payments service, running as a different role, signs approved payment instructions with a key that the KYC role has no permission to use. When a GuardDuty finding says credentials were used from an unexpected network, the on-call engineer opens the runbook and has a deactivate command, a scoping query and an evidence checklist ready.

Common mistakes

  • Storing plaintext "just for now" in a column that later gets copied to analytics.
  • Decrypting to mask. Compute the masked value at write time instead.
  • Logging the request body "for debugging", which puts Restricted data into logs and then into the log-archive account.
  • Searching by decrypting every row, or by a plain SHA-256 hash of the IBAN.
  • One role that does everything, defeating segregation of duties.
  • Deleting an access key first, losing the evidence of which key it was.
  • Disabling a key without approval during an incident, and taking down the whole product.
  • Forgetting the teardown: keys pending deletion, a trail still logging, GuardDuty and Security Hub still enabled.
  • Treating the runbook as finished without a tabletop and timings.

Troubleshooting

SymptomLikely causeFix
InvalidCiphertextException on decryptWrong customer id or field, or the local KMS restartedUse the same context; local data does not survive restarts
AccessDeniedException from KMSSSO role or key policy lacks the action, or the customer_id condition is not metaws kms get-key-policy --key-id alias/hl-m05-data --policy-name default
Crypto:Mode=Local is only allowed...Local mode outside Development/TestingIntended: the API fails closed
NotFoundException: Alias ... is not foundTerraform not applied, or another Regionaws kms list-aliases --region us-east-1
401 on every call locallyMissing X-Hl-Dev-User headerSend the dev headers (Development only)
403 on reveal=trueThe role is not kyc-officerIntended
422 or 400 on createInvalid IBAN checksum, a non-example.* email, or age outside 18 to 120Use a published example IBAN such as GB82WEST12345698765432 and an @example.com email
validate-logs shows no digest filesLess than an hour since the trail started, or a wrong time windowWait, and widen --start-time
GuardDuty create-detector says one existsA detector already exists in this RegionReuse it; the script does
Pipeline fails on SCAA package has a known vulnerabilityUpdate the package, or document an accepted risk

Cost and cleanup

Local parts: free. AWS parts: credits (KMS keys and one secret for a few hours; CloudTrail first management trail is free, with storage cents; GuardDuty and Security Hub CSPM free during trial in an account that has never enabled them, ⚠ VERIFY).

# Part 4 (Terraform)
cd labs/m05-secure-banking-api/infra/terraform && terraform destroy -var owner=<your-name>

# Part 5 and 6
OWNER=<your-name> ./scripts/lab-5-4-cloudtrail-validation.sh down
./scripts/lab-5-5-guardduty-securityhub.sh down

# Nothing tagged for the lab should remain (keys show as pending deletion for 7 days)
aws resourcegroupstaggingapi get-resources --tag-filters Key=Project,Values=cea-lab --region us-east-1 --profile learn-sandbox

# Local build output
find labs/m05-secure-banking-api -type d \( -name bin -o -name obj -o -name TestResults \) -prune -exec rm -rf {} +

Exercises

  • 🟢 Guided: run the tests, run the API, and complete the three role walks in Part 2 (support masked, support denied reveal, officer reveal), then find the three audit lines and write down actor, action and outcome for each.
  • 🟡 Challenge: write a STRIDE table for the API with at least eight threats (two each for spoofing, tampering, information disclosure and elevation of privilege). For each, name the control in the project and the test that proves it. Add a ninth threat the project does not cover, and propose the control and where it would live (WAF, network, rotation, step-up authentication).
  • 🔴 Live problem: at 02:10 an alarm fires: 4,000 reveal=true requests in 20 minutes from the account kyc.jo, against 800 distinct customer ids, from an IP outside your country. kyc.jo is on leave. Use the suspicious-download runbook to decide, in order, what you do in the first 15 minutes, what you must not do, which evidence you preserve, and which questions you hand to the data protection officer. Then say which single change in the project (a rate limit on reveals, a reason code, an alarm on distinct customers per actor) would have shortened detection, and write it as a user story with acceptance tests.

Assignment

Deliver for your portfolio repository: (1) a README with the architecture diagram and the requirements-to-tests table from this page, (2) your STRIDE table from the challenge, (3) your copy of the scanning pipeline running on your repository (a screenshot or log excerpt of one passing run, with no secrets in it), (4) the two runbooks adapted to your own organisation's names with measured timings from a tabletop, and (5) a one-page "what must change before production" note that references each learning shortcut in the callout above and the lesson that covers the fix. This is the seed of Capstone 1 and of the evidence in Capstone 7.

Solutions

Knowledge check

Interview questions

  • "How would you protect customer identity data in a database?" Field-level envelope encryption with KMS, bound to customer and field; masked views by default; reveal as a privileged, audited action; a blind index for search; least privilege on keys; and CloudTrail alarms on decrypt volume.
  • "How do you let support staff help customers without exposing everything?" Masked views computed at write time, role-based access, a separate role to reveal, and audit events for each access.
  • "What logs do you keep and what do you never log?" Who, what, which resource, outcome, source IP and correlation id; never bodies, Restricted values, tokens or secrets.
  • "Walk me through a leaked access key response." Identify and deactivate, revoke sessions, scope with CloudTrail by access key, remove persistence, rotate exposed secrets, capture evidence, involve the DPO, post-incident review.
  • "What would you add before production?" Real identity provider with MFA, private networking and VPC endpoints, WAF, secret rotation, AWS Encryption SDK, managed encrypted database, alarms, a rehearsed runbook.

Certification practice

Completion checklist

  • I ran the tests and saw total: 72, succeeded: 71, skipped: 1
  • I walked the three roles locally and found the matching audit lines
  • I can explain the blind index, the reveal gate and segregation of duties
  • I ran or read Labs 5.4 and 5.5 and their teardown commands
  • I copied the scanning pipeline into my own repository
  • I did a timed tabletop with each runbook
  • If I deployed: Terraform destroyed, trail deleted, GuardDuty and Security Hub disabled, and the tag query returned nothing except keys pending deletion
  • I wrote the STRIDE table and the production-readiness note

Key takeaways

  • Protect the data itself: field-level encryption bound to the customer, with KMS as the only way to read it.
  • Make the safe path the default: masked views, a fallback authorisation policy, a redactor that fails safe, and a local KMS that refuses to run in production.
  • Separate duties by role and by key, and log every access, including denials, without logging the data.
  • Search encrypted data with a keyed blind index, and keep that key in Secrets Manager.
  • Rehearse the runbooks. A runbook that has never been timed is a hope, not a control.

Further reading

Independent learning resource — not affiliated with, endorsed or sponsored by Amazon Web Services. AWS and related marks are trademarks of Amazon.com, Inc. or its affiliates. All banking data in examples is fictional. Sample architectures are for learning and are not automatically compliant with GDPR, PCI DSS or any banking regulation.

On this page