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.
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_idand 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
- Lessons in this module, especially KMS and envelope encryption, Secrets Manager and Parameter Store, CloudTrail for banks, Security Hub, GuardDuty, Inspector and Detective and Incident response.
- Labs 5.3 and 5.7 (the crypto library is reused here) and Labs 5.1 and 5.2 (the policy linter is used in the pipeline).
- Docker Desktop. The .NET 10 SDK is optional.
- For the optional AWS parts: AWS CLI v2,
aws sso login --profile learn-sandbox, Terraform 1.10 or later. Use only the sandbox account.
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:
| Role | May do |
|---|---|
support | View customers (masked only) |
kyc-officer | Create customers, view them, reveal identity fields, search by IBAN |
payments-approver | Sign 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
| Service | Role | In the project |
|---|---|---|
| AWS KMS | Wraps data keys, signs payment instructions | alias/hl-m05-data (symmetric), alias/hl-m05-payment-signing (ECC P-256), alias/hl-m05-secrets |
| AWS Secrets Manager | Holds the blind-index HMAC key | hl-m05/accounts-api/blind-index-key, read through a 15-minute caching reader |
| AWS Systems Manager Parameter Store | Non-secret configuration | /hl-m05/accounts-api/config (Standard tier, no charge) |
| AWS IAM | Least-privilege task role | hl-m05-accounts-api with the exact calls the code makes |
| AWS CloudTrail | Management-event record of key and secret use | Lab 5.4 trail with log file validation |
| Amazon GuardDuty and AWS Security Hub CSPM | Threat detection and posture | Lab 5.5, one Region, free trial |
| Amazon ECS on Fargate, ALB, AWS WAF | Where the API would run in production | Not built here. Design reference: Module 3, WAF and Shield and Segmentation and egress control |
Microsoft / Azure comparison
| You know (Microsoft/Azure) | In this project | What's different |
|---|---|---|
| Azure Key Vault + Managed Identity | KMS + Secrets Manager + an IAM task role | The role gets only specific actions on specific keys, and a condition on the encryption context |
| SQL Always Encrypted with column master keys | FieldEncryptor with a KMS key | Application-level, and searchable only through an explicit blind index |
| Azure Monitor audit logs and Activity Log | AuditMiddleware events plus CloudTrail | Two layers: your application's "who did what to which resource", and AWS's "who used which key" |
| Defender for Cloud | GuardDuty + Security Hub CSPM | Two services: findings (GuardDuty) and posture checks and aggregation (Security Hub CSPM) |
| App roles from Entra ID | Cognito groups in the cognito:groups claim | Role names arrive as claims in the JWT; the app maps them to policies |
| Microsoft.Extensions.Compliance.Redaction | LogRedactor driven by [Classified] attributes | The 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 downloadPart 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
| Requirement | Test |
|---|---|
| Health is anonymous; everything else needs authentication | Health_is_anonymous, Anonymous_callers_get_401_problem_details |
| Create returns a masked view only | Create_returns_a_masked_view_only |
| Storage holds no plaintext identity fields | Stored_record_contains_no_plaintext_identity_fields |
| Support sees masked data and cannot reveal | Support_sees_masked_data_and_cannot_reveal |
| KYC officer can reveal | Kyc_officer_can_reveal_identity_fields |
| IBAN search uses the blind index | Iban_search_uses_the_blind_index |
| Validation (including the IBAN mod-97 check) | Invalid_input_returns_validation_problem, Iban_checksum_validation |
| Segregation of duties | Kyc_officer_cannot_sign_payments_segregation_of_duties |
| Idempotent signing | Signing_is_idempotent_and_rejects_key_reuse_with_a_different_body |
| Denied requests are audited | Denied_requests_are_audited_with_actor_and_correlation_id |
| Security headers | Responses_carry_security_headers |
| Classification covers every stored field | Every_stored_customer_field_is_classified (a guard that fails when someone adds a field without classifying it) |
| Log redaction follows classification | Log_redactor_follows_classification |
| Masking | Iban_masking, Pan_masking, Email_masking |
| Tokenising and pseudonymising | Tokeniser_round_trips_and_is_deterministic, Pseudonymiser_keeps_formats_and_joins |
| Blind index | Blind_index_is_deterministic_and_normalised, Blind_index_differs_per_field_and_per_key, Short_keys_are_rejected |
| Secrets caching and rotation | Cached_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:5080In 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-sandboxRun 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.SecureApiASPNETCORE_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 upMake 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 validateThe 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 downIt 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 findingsThe 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 downIt 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:
| Step | What it catches |
|---|---|
| Build and test | Regressions, 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 lint | Runs 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 key | Suspicious data download | |
|---|---|---|
| Triggers | GuardDuty credential-exfiltration findings, exposed-key notices, a secrets-scanner alert, a person reporting a paste | A spike in kms:Decrypt on the data key, a spike in reveal=true audit events from one actor, GuardDuty or Macie findings |
| First action | Deactivate the key (do not delete: you lose evidence of which key it was); revoke role sessions if it was an ASIA session key | Identify the actor from the audit event or CloudTrail; disable the user and revoke sessions; disable the data key only with incident-commander approval |
| Scope with | CloudTrail 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 |
| Never | Delete the key before capturing evidence | Schedule key deletion during an incident |
| Notify | The 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 isalias/hl-m05-secretsand that there is no rotation configured. - CloudTrail: Console → CloudTrail → Event history, filter by event source
kms.amazonaws.comor 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.jsonAKIAEXAMPLEKEYID 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:
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:
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);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());// 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
encryptor.EncryptAsync(customerId, DateOfBirthField, dob, ...)encrypts one field under a fresh data key with the context{customer_id, field}and returns anenc:v1:token. The two Restricted fields are stored only as tokens.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).BlindIndex.Compute(indexKey, IbanField, iban)stores the keyed hash that supports equality search.return Masked(stored)returns a view withDateOfBirth: nulland the masked email and IBAN, even to the officer who created the record. Revealing is a separate, audited, deliberate action.- The
revealgate 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. .SetFallbackPolicy(RequireAuthenticatedUser())means an endpoint added later without an explicit policy is protected by default./healthopts out withAllowAnonymous().- Each Terraform statement in
iam.tfmatches 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
| Symptom | Likely cause | Fix |
|---|---|---|
InvalidCiphertextException on decrypt | Wrong customer id or field, or the local KMS restarted | Use the same context; local data does not survive restarts |
AccessDeniedException from KMS | SSO role or key policy lacks the action, or the customer_id condition is not met | aws kms get-key-policy --key-id alias/hl-m05-data --policy-name default |
Crypto:Mode=Local is only allowed... | Local mode outside Development/Testing | Intended: the API fails closed |
NotFoundException: Alias ... is not found | Terraform not applied, or another Region | aws kms list-aliases --region us-east-1 |
| 401 on every call locally | Missing X-Hl-Dev-User header | Send the dev headers (Development only) |
403 on reveal=true | The role is not kyc-officer | Intended |
| 422 or 400 on create | Invalid IBAN checksum, a non-example.* email, or age outside 18 to 120 | Use a published example IBAN such as GB82WEST12345698765432 and an @example.com email |
validate-logs shows no digest files | Less than an hour since the trail started, or a wrong time window | Wait, and widen --start-time |
GuardDuty create-detector says one exists | A detector already exists in this Region | Reuse it; the script does |
| Pipeline fails on SCA | A package has a known vulnerability | Update 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=truerequests in 20 minutes from the accountkyc.jo, against 800 distinct customer ids, from an IP outside your country.kyc.jois 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
| Request | Result | Audit outcome |
|---|---|---|
GET /customers/<id> as support | 200, masked (a***@example.com, GB82**************5432, no DOB, revealed: false) | success |
GET /customers/<id>?reveal=true as support | 403 ProblemDetails | denied |
GET /customers/<id>?reveal=true as kyc-officer | 200, decrypted IBAN and DOB, revealed: true | success |
All three lines carry the actor name, the route pattern (GET /customers/{customerId}) and a correlation id, and none carries a body or a personal value. With real KMS, the third request also creates two Decrypt events in CloudTrail whose encryption context names the customer.
Example rows: Spoofing: forged JWT → signature validation, client_id check (control in Cognito setup; test in the Module 4 project's authentication tests). Spoofing: dev header handler used in production → Crypto:Mode=Local refused outside Development; extend the same fail-closed check to the dev auth scheme. Tampering: ciphertext moved between customers → encryption context binding (Ciphertext_copied_to_another_customer_does_not_decrypt). Tampering: modified payment amount → signature check (One_penny_change_breaks_the_signature). Information disclosure: support agent reads identity fields → masked views and the reveal gate (Support_sees_masked_data_and_cannot_reveal). Information disclosure: secrets in logs → classification and redaction (Log_redactor_follows_classification). Elevation of privilege: officer signs payments → segregation of duties (Kyc_officer_cannot_sign_payments_segregation_of_duties). Elevation of privilege: a new endpoint forgets authorisation → fallback policy. Uncovered example: denial of service by mass reveal calls or scraping, mitigated by per-actor rate limits in the app, API Gateway throttling and WAF rate-based rules in front, none of which this project implements.
First 15 minutes: confirm the pattern is real (audit log and CloudTrail Decrypt events), then contain: disable the user in the identity provider and revoke Identity Center or Cognito sessions; if a workload role was used, revoke its active sessions. Do not schedule key deletion; do not disable the data key unless the incident commander approves, because it takes down every legitimate reveal and decrypt. Preserve: the audit log slice, CloudTrail events grouped by encryptionContext.customer_id (the 800 affected customers), source IP and user agent, and hashes of exported evidence in the log-archive store. Hand to the DPO: the list of customer ids (not the personal data), the time window, whether the data left the environment, and the assessment of whether notification is required within the 72-hour clock (⚠ confirm with your DPO). The change that shortens detection: a metric and alarm on distinct customers revealed per actor per 10 minutes, as a user story with acceptance tests such as "25 distinct reveals in 10 minutes raises the alarm; 5 does not" and "a reveal requires a reason code of 8 to 200 characters, which is audited".
Knowledge check
Answer: So that masked reads and IBAN searches never call KMS. Support staff never trigger decrypts, which keeps KMS calls (and the CloudTrail signal) meaningful: each Decrypt represents a deliberate reveal. The blind index supports equality search on randomised ciphertext.
Answer: IBANs and similar values have low entropy and a known structure, so an attacker with the table can brute-force the hashes. An HMAC with a secret key cannot be recomputed without the key.
Answer: Three roles with separate policies. A KYC officer can create and reveal but cannot sign payments; a payments approver can sign but cannot create or reveal. The test Kyc_officer_cannot_sign_payments_segregation_of_duties proves it, and the KMS signing key's role policy is separate from the data key's.
Answer: Deleting removes the evidence of which key was involved and cannot be undone. Deactivation stops use immediately and keeps the key's record for the investigation.
Answer: Validation uses signed digest files and hashes to prove that a log was altered or deleted. It does not stop a privileged user from writing to the bucket. Prevention comes from a separate log-archive account, restrictive policies and Object Lock.
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
A bank wants support staff to look up customers by IBAN, but the IBAN column is encrypted with a random per-record data key. Which design allows equality search without decrypting every row or weakening the encryption?
A. Store a plain SHA-256 hash of the IBAN beside the ciphertext. B. Store an HMAC of the normalised IBAN with a secret key kept in Secrets Manager, and search on that value. C. Use the same nonce for every record. D. Store the IBAN in the encryption context.
Answer: B. A keyed hash cannot be recomputed without the key and supports equality search. A is brute-forceable for low-entropy values. C breaks AES-GCM. D exposes the IBAN in CloudTrail.
During an incident, an engineer proposes scheduling deletion of the KMS key used to encrypt customer data "to stop the attacker". What is the BEST guidance?
A. Do it immediately; deletion is reversible at any time. B. Disable the key only if the incident commander approves the business impact, and never schedule deletion during an incident. C. Delete the CloudTrail trail instead. D. Ignore the issue until the next business day.
Answer: B. Disabling is reversible and stops use, but it also stops legitimate use, so it is a business decision. Deletion is permanent after the waiting period and destroys access to data. C destroys evidence. D is negligent.
An application role needs to read one secret in Secrets Manager that is encrypted with a customer managed KMS key. Which policy design follows least privilege?
A. Allow kms:* on all keys.
B. Allow secretsmanager:GetSecretValue on the secret's ARN, and kms:Decrypt on that key with the condition kms:ViaService equal to the Secrets Manager endpoint for the Region.
C. Allow secretsmanager:* on all resources.
D. Attach AdministratorAccess.
Answer: B. It names the exact secret, and limits the key to use through Secrets Manager. A, C and D grant far more than needed.
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
- KMS and envelope encryption, Labs 5.3 and 5.7 and Labs 5.1 and 5.2
- Secrets Manager and Parameter Store and CloudTrail for banks
- Security Hub, GuardDuty, Inspector and Detective and Incident response
- Threat modelling with STRIDE, Pipeline security scanning and Secure code review for .NET
- UK GDPR and data residency and PCI DSS on AWS
- Module 5 overview
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.
Operational resilience and third-party risk
Understand what UK and EU regulators expect when a bank runs important business services on AWS — important business services, impact tolerances, outsourcing and third-party risk, the Critical Third Parties regime, DORA, exit plans and concentration risk — and turn those expectations into architecture, chaos experiments and evidence. Concepts only.
Module 5 cheat sheet
One-page revision summary for Security for Banking & Finance: services, Azure mapping, CLI commands, limits, decision rules, exam traps and cost traps.