Enabling Detective
The Detective setup wizard walks you through three steps to deploy Amazon Detective across your organization. After you submit, an asynchronous job attaches the required permissions, creates a behavior graph in each region, invites every member account, waits for AWS to verify each account's root email address, and accepts the invitations on those accounts' behalf.
Accessing the Wizard
- If no Security Hub engines are enabled yet, the Overview page is the capability selector, headed Enable Security Hub. Click Enable on the Security investigation / Amazon Detective card.
- If another engine (CSPM, GuardDuty, Macie, or Inspector) is already live, go to Configuration > Capabilities — the tab is labelled just Capabilities and is selected by default — and click Enable on the same card. The sidebar also shows a greyed Enable Amazon Detective row that opens the same wizard.
On a self-hosted deployment that is not paired with CloudKeeper SaaS, the Amazon Detective card shows an explanation instead of an Enable button and there is no sidebar entry. See Availability on self-hosted deployments.
Wizard Steps
| Step | Name | What you configure |
|---|---|---|
| 1 | Administrator account | The AWS account that will own the behavior graph |
| 2 | Members and regions | The member accounts to enrol, the home region, and the linking regions |
| 3 | Root emails | The real AWS root user email address for any member account Prism could not resolve, plus a review of the whole submission |
The three step labels appear in a stepper across the top of the wizard, and the buttons at the bottom are Back and Next, with Enable Amazon Detective replacing Next on the last step.
If a previous setup attempt failed, the wizard opens with a warning above the stepper reading "The previous setup attempt failed: <reason>. Submitting again will clear that state and retry." There is nothing to delete first.
Prerequisites
- At least one AWS account is available in Prism to serve as the administrator
- You can supply the real AWS root user email address for any member account Prism cannot resolve for you (see Step 3 below)
Step 1: Administrator Account
Select the AWS account that will act as the Amazon Detective administrator. The step opens with the sentence "Pick one linked account to own the Amazon Detective behavior graph. Every member account is invited into that account’s graph, and all investigation data is read through it."
| Field | Required | Notes |
|---|---|---|
| Administrator account | Yes | Search by account name or account ID; the selected account is not offered as a member on Step 2 |
Both of the facts below are on screen, in one warning banner above the field:
Changing the administrator account later means disabling Amazon Detective and setting it up again — the behavior graph belongs to this account and cannot be transferred. It is not pre-filled from your GuardDuty administrator: the two are independent, and Detective can be administered from a different account entirely.
The administrator account is effectively permanent. The behavior graph belongs to that account and cannot be transferred. To change it, disable Amazon Detective entirely and run the setup wizard again, which deletes the graphs and their accumulated history.
The administrator is not pre-filled from your GuardDuty administrator. Prism deliberately does not copy GuardDuty's choice, because inheriting an administrator silently is harder to notice than choosing one.
Step 2: Members and Regions
Select the member accounts to enrol and the regions to cover. The step opens with the sentence "Pick the member accounts to enroll and the regions to cover. The administrator account is always in its own graph and does not need to be selected. Amazon Detective builds one behavior graph per region, so each region you add is separate coverage."
| Field | Required | Default | Notes |
|---|---|---|---|
| Home region | Yes | none | Single-select. Choosing it adds it to Regions automatically |
| Regions | Yes | none | Multi-select; the home region is locked in and cannot be deselected |
| Member accounts | No | — | Multi-select; search by account name or account ID |
Nothing is pre-selected. Neither region field carries a default, so Next stays disabled until you have picked a home region and it is present in Regions. Selecting a home region satisfies both conditions in one action, because it is added to Regions as a locked entry the moment it is chosen.
Leaving Member accounts empty is allowed. It enrols the administrator alone, and Step 3 says so rather than silently accepting it — see the note there.
Amazon Detective builds one behavior graph per region, so each region you add is separate coverage rather than a view over one shared graph. Enabling four regions creates four graphs. There is no cross-region aggregation to configure: the home region is simply the default region Prism talks to and the one it falls back to.
The picker does not carry its own region list. It takes the supported-region list from the server and intersects it with Prism's shared AWS region list, which is why it offers 16 regions rather than the 21 in which Detective has an endpoint. See Supported regions for both lists and for the five opt-in regions.
The backend, not the picker, is the boundary. It re-checks every submitted region against the same allowlist, and — for an opt-in region — checks per account whether that account has enabled it, refusing with a message that names the account. A region picker could not name the account, because opting in is a per-account fact the wizard does not have.
A behavior graph holds at most 1,200 member accounts. If your selection would exceed that, Prism refuses the enable before any account is invited rather than partway through.
Step 3: Root Emails
The step opens with the warning it exists for:
Amazon Detective enrolls member accounts by invitation, and AWS checks the address you supply against the account’s real AWS root user. It must be that address and not the account owner’s work address: a plausible-looking substitute is accepted here, passes validation, and then fails minutes later during enrollment with nothing on screen to explain why.
Prism looks each address up automatically where it can. Enter any it could not resolve.
An account Prism resolved shows its address as green text reading "<address> (resolved automatically)" with no input at all. Only the accounts it could not resolve — plus any the server later refuses, see Submitting — get an editable field.
That field is labelled AWS root user email address, not "Email", and the account name and ID are shown beside it. Both matter:
- It must be the account's root user address, not the account owner's work address. A plausible substitute is accepted here, passes validation, and then fails minutes later during enrollment with nothing on screen to explain why.
- Without the account beside each field, you are typing addresses into an unlabelled list of identical boxes.
An empty field's helper text reads "Enter this account’s AWS root user email address."; where the lookup or the server gave a reason, that reason replaces it.
To find an account's root email, sign in to that AWS account and go to Account Settings > Account > Email address in the AWS Console.
Selecting no member accounts on Step 2 is not an error, and this step says so in place of the fields: "No member accounts selected — only the administrator account will be in the behavior graph. Go back to add members." Enable Amazon Detective stays available.
Resolution Progress
Prism resolves root emails in batches of five accounts, sequentially, and shows a progress bar labelled "Resolving root email addresses — N of N accounts" while it runs.
The batching is why the progress line exists rather than a plain spinner. A large selection produces many sequential lookups, and an indeterminate spinner over them is indistinguishable from a hang, which invites a page reload that loses the wizard state.
Resolution runs when you first reach this step and again whenever the member selection changes. Stepping back to Step 2 and forward again without changing the selection does not re-run it, and neither does being sent back here by the server.
A failed batch does not fail the step. If some lookups fail, the accounts they covered appear with an empty address and the reason beside them, and one warning banner above the fields counts the failures in batches, not accounts: "N of M lookups failed. Enter those addresses below." — where M is the number of batches, not the number of accounts. Every address that did resolve is kept. Fill in the missing ones and continue.
An email address longer than 64 characters is rejected by the field before submission, with the message "This address is N characters; Amazon Detective accepts at most 64, and a longer one rejects the whole enrollment batch." This is AWS's own limit on the invitation, and it is checked in the browser because the server-side failure rejects the entire batch, not just the offending account, so one long address would stop every other account in the same call from enrolling.
Otherwise the field's validation is deliberately loose — it requires only an @ — because the server is the real boundary and a stricter browser rule would reject an address AWS actually holds.
Review
Below the address fields, the same step carries a Review block summarising what will be submitted:
| Row | Value |
|---|---|
| Administrator account | The account chosen on Step 1, as name (id) |
| Home region | The home region chosen on Step 2 |
| Regions | Every linking region, comma-separated |
| Member accounts | The count, followed by (the administrator is in its own graph as well) |
That last row is the one to read twice. Enrolling one member account shows 1 (the administrator is in its own graph as well) — the administrator is not counted as a member, but it is in the graph, and the dashboard's Accounts covered tile will therefore read 2.
Submitting
Click Enable Amazon Detective to submit. The button reads Enabling… while the request is in flight.
Only the addresses you typed are sent. Accounts Prism resolved automatically are resolved again server-side rather than being echoed back, so an address cannot be tampered with between the lookup and the invitation.
If the server replies that some accounts still need an address, the wizard returns you to the root emails step with exactly those accounts flagged, shows the server's own sentence as an error banner among the fields, and gives each flagged account an editable field even if it had resolved cleanly a moment earlier:
Some member accounts need an AWS root user email address before enrollment
Correct the flagged accounts and resubmit. The wizard does not advance past this.
What Happens After Submission
After you click Enable Amazon Detective, the wizard hands off to an asynchronous job and replaces the steps with a status screen. It re-reads the configuration every three seconds and heads itself from the status it finds — Setting up Amazon Detective… while the job runs, then Amazon Detective is enabled, Amazon Detective enabled with partial failures, or Setup failed. Beneath the heading it repeats the administrator account and the home region, so the screen still says what is being built.
While the job runs, the screen explains it in one sentence — "Creating the behavior graph in each region, inviting every member account and waiting for AWS to verify each root user email address. This can take several minutes." — above a progress bar. The bar's own label is the job's current phase, and there are three: Preparing, Granting permissions, and Enrolling accounts.
Leaving the page does not abandon the job. Returning to Amazon Detective while it is still running shows the same progress under the heading "Enabling Amazon Detective across accounts and regions…", polling on the same three-second cadence, and it hands over to the dashboard by itself when the job settles.
The job runs once for the whole configuration, not once per region, and only steps 2 and 4 through 7 loop over regions:
- Attaches the Detective permissions policy to the administrator account's access role and waits until it is usable. This one failure is fatal: with no administrator there is no graph for anyone to join
- Creates one behavior graph per linking region. If every region fails here the job stops immediately, before a single member permission is granted
- Attaches the permissions policy to each member account's access role. A member failing here fails only that member
- Invites the granted members into each region's graph, in batches of 50
- Polls AWS until each member's invitation is verified and reaches
INVITED - Accepts each invitation in that member account's own session
- Re-reads the member list in each region to confirm the result and record each account's AWS-reported status
Steps 1 and 5 legitimately take minutes. IAM changes take time to propagate, and AWS's verification of a root email address is wall-clock work on AWS's side. The progress bar continues to advance and the page keeps polling throughout; a long pause in either phase is normal and is not a stalled job.
Step 5 is where a wrong email address surfaces. The invitation call returns success even for an account whose address does not match, and the account only flips to VERIFICATION_FAILED several minutes later. An enable that reported progress can still leave individual accounts unverified, which is what the Enrollment page is for.
Prism gives AWS eight minutes to verify, polling every 20 seconds. An account still unverified when that window closes is marked failed, with the message "operation ended before this account completed", and the job settles rather than waiting indefinitely. That is a report of where the run stopped, not a verdict on the account: AWS may well finish verifying it afterwards. Retry it from the Enrollment page — with the same address, since nothing suggests the address was wrong.
Partial Success
Accounts are invited and accepted independently, so some can succeed while others do not. If any account or region fails, the overall status becomes partial_failure:
- The wizard's own status screen heads itself Amazon Detective enabled with partial failures, and any message the job recorded appears beneath it as a warning.
- The accounts that joined are live and ingesting straight away.
- The dashboard carries a warning banner reading "Some accounts are not fully enrolled in the behavior graph." followed by the job's message, with a Review button that opens Enrollment, where each account is listed with its AWS-reported status and the action that applies to it.
Nothing is rolled back on partial failure, and retrying one account does not disturb the others.
partial_failure deliberately lands you on the dashboard rather than back in this wizard. The graph exists and most members are in it, so the per-account Retry on the Enrollment page is the repair; re-running the wizard would tear the graph down and start over.
A prior failed or disabled Detective configuration is cleared automatically when you resubmit the wizard. You do not need to manually delete the old state before running setup again.
After the Enable Completes
Detective begins ingesting immediately, but no investigations will appear on their own. Detective does not create investigation records; a report exists only once someone runs an investigation from the Amazon Detective console. See Detective does not create investigations on its own.
Related Pages
- Investigations dashboard, What you see after setup completes
- Enrollment, Add more members, retry verification failures, or remove accounts
- Settings, Change regions or permissions after setup
- Security Hub Issues, Troubleshooting setup failures and root-email problems