Security overview

This document is for security reviewers. It covers what Cloud Certainty StateCraft protects against, how users are identified, how access is limited, where data and audio go and how they are encrypted. Everything described here runs in your own AWS account.

#Threat model

StateCraft lets many people see, run and change AWS Step Functions workflows, by mouse, keyboard or voice. What it must prevent:

Out of scope: a malicious administrator of the AWS account (they can change any IAM policy), and the security of the identity provider, of users' devices and browsers, and of the browser vendor's speech service when an administrator chooses it.

#Controls

#Identity and authorization

The API trusts the Cognito ID token's signature, issuer and audience (checked by API Gateway), and then decides who the caller is from its claims. Roles, grants, drafts and the bootstrap admin are keyed on the email claim, so a user who could pick their own email could take over someone else's access. The API therefore accepts the email only when it is one the user can't choose; otherwise it refuses the caller with 403 forbidden on every route.

The provider is read from the signed token, never from anything the client sends.

Bootstrap admin. BootstrapAdminEmail is always an admin, so it is bound to an immutable identity: the first trusted sign-in with that email records the caller's Cognito user ID, and from then on only that user is the bootstrap admin. Sign in as the bootstrap admin straight after deployment. Resetting the binding is described in the admin guide.

#Permissions, grants and session policies

What a user can do is the intersection of two independent layers.

1. The connection's IAM role sets the ceiling for everyone: the local role is limited by the stack parameters LocalAccessLevel (Read, Operate or Full), PassRoleArns and StateMachineKmsKeyArns; a spoke role by the same parameters of its own stack. StateCraft can never do more in an account than its role allows, and the account owner controls that role.
2. StateCraft grants decide what each user may do within that ceiling: a subject (user or group), a connection, Regions, state machine name patterns and permissions (view, data, run, deploy). See the admin guide.

Grants are not only checked in code. For every request, the API calls sts:AssumeRole on the connection's role with:

• SourceIdentity = the user's email. It can't be changed for the rest of the session, also in role chains, and it appears in CloudTrail for every Step Functions, CloudWatch, CloudWatch Logs and KMS call in the target account;
• a role session name sc-<email>, also visible in CloudTrail;
• a session policy (for non-admins) that allows Step Functions actions only on the ARNs of the state machines matching the user's patterns (the machines, their versions and aliases, their Standard and Express executions, their Distributed Map children and Map Runs), and only the actions of the user's permission: reads for view; reads with kms:Decrypt for data; plus start, stop, redrive, TestState, Map Run updates, iam:PassRole to Step Functions and kms:GenerateDataKey for run; plus create, update, delete, versions, aliases, tags and log delivery for deploy. If a user's grants are too many to fit the session policy size limit, the request is refused rather than widened.

Listing state machines and reading CloudWatch metrics have no resource-level permissions in AWS, so those reads use a separate, read-only session, and StateCraft filters the results by the caller's grants: a user never sees a state machine they have no grant on.

Data without data. IAM can't separate an execution's metadata from its data. For people without data, StateCraft asks Step Functions for metadata only (includedData = METADATA_ONLY, includeExecutionData = false) and removes inputs, outputs, causes and parameters from what it returns. For state machines encrypted with a customer managed key, AWS enforces it as well.

Your SCPs, permission boundaries and key policies still apply on top: StateCraft adds restrictions and never removes yours.

#Voice and assist

#IAM summary

* resources appear only where AWS has no resource-level permissions (states:ListStateMachines, ListActivities, ValidateStateMachineDefinition, TestState, cloudwatch:GetMetricData, log delivery actions, License Manager), for PassRoleArns when you keep its default * (still only to Step Functions, and never StateCraft's own roles), and for KMS keys when StateMachineKmsKeyArns is empty (still only through Step Functions).

#Data flows

#What stays in your account

Everything: identities, connections and external IDs, grants, drafts (workflow definitions), saved inputs (which may contain business data), execution records, bulk jobs, usage figures and the audit log, as well as your state machines, their executions and their data. Cloud Certainty operates no service in the data path, and the stack never contacts the vendor at runtime. The AWS Marketplace container registry and the vendor's public bucket in us-east-1 (templates and the release manifest) are read-only distribution points used at install and upgrade, and, with UpdateChecks = Enabled, for a daily read of the public release manifest that sends nothing about you. Links to cloudcertainty.com in the portal are plain links, followed only when someone clicks them. The one path out of your AWS account is voice with the browser's speech service, and only when an administrator chooses it.

#Encryption

• In transit. TLS for every AWS API, Amazon Transcribe streaming and the portal (HTTPS only, with HSTS). The artifacts bucket denies non-TLS requests.
• At rest. With KmsKeyArn, your customer managed key encrypts the DynamoDB tables, CloudWatch Logs, the update topic, the artifacts bucket and the bulk jobs workflow. Without it, AWS owned keys and SSE-S3 are used. Your state machines keep their own encryption; StateCraft uses their keys only through Step Functions, only within a person's data or run permission, and only the keys in StateMachineKmsKeyArns when you list them.

#Portal hardening

Amplify Hosting serves the portal with these headers:

• A strict Content-Security-Policy: no inline or third-party script, no eval, frame-ancestors 'none', and AWS endpoints allowed only for sign-in, the API and, for voice, the Amazon Transcribe streaming endpoint of the stack's Region.
• Strict-Transport-Security, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, X-Frame-Options: DENY, and a Permissions-Policy that allows only the microphone and clipboard writing, for the portal itself, and turns off camera, geolocation, payment and USB. Browsers ask each person before the portal can use the microphone.

Graphs, timelines and charts are drawn in the browser; nothing is loaded from third parties. Tokens are kept in session storage, never in cookies; refresh tokens last 8 hours and can be revoked.

#Audit

Every administrative change (roles, connections, grants, settings), every deploy, version and alias change, every execution started, stopped or redriven, every Map Run change, TestState run, bulk job, draft change and assist request is written to the audit log with the actor, source IP and target. Admins read it in Administration › Audit log. Events are kept for the plan's audit days: 30 on Starter, 90 on Team, 365 on Business and 3,650 on Enterprise. Execution records keep who started, stopped and redrove each execution for 30 to 730 days by plan. For each AWS call, CloudTrail in the target account shows the assumed-role session with sourceIdentity set to the user's email. Forward CloudTrail and the log groups to your SIEM.

#Licensing

StateCraft reads its AWS Marketplace licence from AWS License Manager in your account: at install and in the API. Nothing about your usage or data is sent anywhere. Without a valid licence the installer stops and the API answers 402 licence_required. If License Manager is unreachable, or a licence that was active disappears (which bridges a move between plans), StateCraft keeps working for up to 72 hours from the last successful check. Your data and your workflows stay in place either way.

#Shared responsibility

• Keep BootstrapAdminEmail on a protected identity and enforce MFA at your IdP. Grant Admin to a second person or group.
• Keep connection roles at Read unless people need to operate executions there, and at Operate unless teams deploy through StateCraft. Narrow PassRoleArns to your workflows' execution roles.
• Grant groups rather than single users, with name prefixes per team (orders-*), and give data only to people who need to see execution data.
• Keep voice on Amazon Transcribe, set an AI services opt-out policy if your organisation requires it, and choose the browser's speech service only if sending audio to the browser vendor is acceptable.
• Review assist proposals like any code change before deploying them.
• On Business and above, set the IP allowlist to your corporate egress ranges if users should only connect from managed networks.
• Forward CloudTrail and StateCraft's log groups to your SIEM.