Faqs

Frequently Asked Questions

Security and Encryption

What is the recommended IAM guard-rail and how does it prevent the “Confused Deputy” attack?

(Recommended) Customer IAM guard-rail

You can enforce that no one later edits the trust policy to remove this check:

aws iam put-role-permissions-boundary \
  --role-name TracepromptViewer \
  --permissions-boundary arn:aws:iam::aws:policy/AWSTrustedAccessExternalIdBoundary

This boundary policy (a few lines) denies any future UpdateAssumeRolePolicy that omits the ExternalId condition. It keeps well-meaning admins from accidentally weakening the guard.

Why this closes the “Confused Deputy” gap

• Suppose an attacker learns the role ARN.
• They try sts:AssumeRole ⇒ AWS checks the trust policy.
• Because their call lacks the secret ExternalId, the request fails with AccessDenied.
• Only Traceprompt—who knows the UUID for that org—can obtain credentials.

How do tight-lifetime credentials (≤ 1 hour) improve security?

Short STS sessions mean the keys Traceprompt obtains are useless to an attacker after an hour (or whatever limit you pick). Below are the changes you need to make to honour the cap.

In your AWS account – cap the role at 1 hour

1. IAM console → Roles → TracepromptViewer
2. Edit → Maximum session duration
3. Set 1 hour (3,600 seconds) → Save

Or CLI:

aws iam update-role \
  --role-name TracepromptViewer \
  --max-session-duration 3600

The minimum AWS allows is 900s; 3,600s is a good balance between security and latency.

Traceprompt backend – request the shortest session you need

We set DurationSeconds as the value so we have transparency:

await sts.send(
  new AssumeRoleCommand({
    RoleArn: viewerRoleArn,
    RoleSessionName: `viewer-${userId}`,
    ExternalId: orgId,
    DurationSeconds: 900, // ask for only 15 min
  })
);

• If Traceprompt requests a longer duration than the role’s cap, AWS truncates it to the cap.
• Requesting a shorter duration still works, so pick the minimum that won’t cause mid-request expiry (15-30 min is typical).

(Optional) Automatic drift-detection

Customers who run AWS Config can enable rule iam-role-max-session-duration and set the desired value (≤ 3,600). If someone later raises the limit, they’ll get an alert.

Why this matters

• Reduced blast-radius – even if the viewer credentials leak, they expire quickly.
• Zero impact on throughput – when Traceprompt needs fresh credentials it simply re-assumes the role; this is invisible to the user.
• Compliance tick-box – many frameworks (HIPAA, SOC 2, ISO 27001) require short-lived, automatically-rotated credentials for cross-account access.

Result: The Viewer role now issues credentials that live for at most one hour, limiting any misuse window to a tight time-box.

How do I perform zero-downtime CMK rotation?

Rotating your customer-managed KMS key (CMK) is fully supported by Traceprompt and can be done without interrupting ingest or decryption.

Prerequisites

• New CMK in the same AWS Region as the old one
• The same resource-based key policy statements you used before:
  • TracepromptIngestRole – Encrypt / GenerateDataKey
  • TracepromptViewer – Decrypt (conditioned on tenant_id)
  • (optional) TracepromptViewerCallerRole – DescribeKey
• Console or API access to Traceprompt → Org → Encryption Settings

Step-by-Step

1. Create & tag the new CMK

Using the AWS CLI, create a new CMK with the same policy statements as the old one (or use the AWS console):

aws kms create-key --description "Traceprompt CMK – rotated $(date +%Y-%m-%d)"

Copy the returned KeyId / ARN.

2. Copy policies from the old CMK

1. In the KMS console open OldKey → Key policy → Switch to policy view → Copy JSON.
2. Replace the old ARN(s) with the new key ARN inside any “Resource”: ”*” shortcuts if you previously used explicit ARNs.
3. Attach that policy to the new key (PutKeyPolicy).

Tip: Keep the root-admin stanza in both keys until rotation is finished.

3. Add the new key to Traceprompt

1. In the Traceprompt dashboard open Settings → Encryption.
2. Paste the new CMK ARN into “Additional CMK” and Save & Test.
   • You should see “Key verified”.
3. Do not delete the old ARN yet.

At this point:

• Encrypt → New data is wrapped with the new CMK.
• Decrypt → Traceprompt tries keys in the order listed; both still work.

4. Verify backlog is clear

Navigate to Settings → Encryption → Key Usage (added in v0.11.0):

CMK ARN	New entries since rotation	Old-key decrypts in last 30 min
…093f7 (new)	✓ increasing	—
…353df (old)	0	0

When both counters for the old key stay at 0 for at least one flush interval (default = 5 min) you’re safe to remove it.

5. Remove (and optionally delete) the old CMK

1. In Traceprompt → Encryption click 🗑 Remove next to the old ARN and confirm.
2. Wait ~60 s; ingest/decrypt health checks should stay green.
3. In AWS KMS you may now Disable or ScheduleKeyDeletion for the retired key in accordance with your retention policy.

Common Questions

Question	Answer
Does rotation cause double KMS cost?	Only during the overlap window when both keys are active — minimal.
What if I forget to copy the key policy?	Traceprompt will return 403 on encryption test and refuse to save the ARN.
Multiple orgs share one key — can I rotate just one tenant?	Yes. Policies reference tenant_id so each org can move to its own new CMK independently.