Skip to main content

Enrollment

The Enrollment page shows every account in the Amazon Detective behavior graph, the phase Prism has it in, and the status AWS reports for it. Use it to add member accounts, correct and retry accounts whose root email failed verification, start monitoring for accounts that joined but are not ingesting, and remove accounts.

The page header reads Enrollment, subtitled "Manage which accounts are members of the Amazon Detective behavior graph".

Accessing Enrollment​

In the Security Hub sidebar, click Amazon Detective > Enrollment.

If Detective has not been set up yet, the page shows an alert reading "Amazon Detective is not set up yet for this customer. Complete the setup wizard first — it creates the behavior graph that member accounts are invited into." with a Go to setup button that opens the setup wizard.

Configuration Card​

At the top of the page, a card headed Configuration ("One account owns the behavior graph; every other account joins it by invitation") shows four values:

RowWhat it is
Administrator accountThe account that owns the behavior graph, shown as Name (123456789012) where Prism knows the account's name and as the bare ID where it does not
Home regionThe default client region
RegionsEvery region where a behavior graph exists, comma-separated
StatusThe configuration's own status, Title-Cased: Enabled, In Progress, Partial Failure, Failed

The administrator's row in the members table is labelled Administrator and carries no member-status chip. It owns the graph rather than being a member of it, so AWS reports no member status for it, and a blank chip in a column every other row fills would read as a bug. The row says so in words:

The administrator owns the behavior graph. AWS reports it as a member of its own graph, so Prism does not record a member status for it.

note

The card, the members table and the account picker are loaded independently, and each reports its own failure rather than taking the others down with it. If only the configuration read fails, the previous values stay on screen under a warning reading "The configuration below could not be refreshed and may be out of date: …" — a stale view with a visible warning is honest, where replacing a configured tenant's page with the setup prompt would not be. A failed members or accounts read shows a retry card in place of that one table, so a broken load can never render as "no accounts enrolled yet".

When Enrollment Changes Are Unavailable​

Every mutation on this page (Add, Retry, Start monitoring, Remove) is refused by the server unless the configuration is settled, so the page disables those buttons rather than dispatching a request that is certain to fail. Two states do that.

An operation is running. While the configuration is in_progress, an info alert above the account picker reads:

Enrollment changes are paused while the current operation finishes.

Setup failed. A red banner appears below the configuration card, with a Re-run setup button:

Amazon Detective setup failed*[: the reason, when the server recorded one]*. Nothing is running and nothing will resume on its own — enrollment changes stay unavailable until setup is re-run. The accounts below show how far each one got, and any account listed as a graph member is still holding one of its 1,200 slots.

note

In the failed state the "paused while the current operation finishes" alert is deliberately not shown. Nothing is running and nothing will finish, so that wording would promise a completion that never arrives. The banner above is the whole explanation.

Progress Bar​

When one or more accounts are in an active phase, or the configuration itself is mid-operation, a progress bar appears below the configuration card. The bar polls the server automatically and advances as the job progresses.

note

The bar keeps polling while the configuration itself is still working, not only while individual accounts are moving. The verification poll and the per-region loop continue after the last account cell has settled, so polling that stopped at that point would freeze the bar one tick early.

Two Columns, Two Facts​

The members table is headed Graph members ("Prism's phase and the status AWS reports, per account and region"), with a chip in its header counting the enrolled accounts, for example 3 enrolled. It has five columns:

ColumnContents
AccountName (123456789012), plus an Administrator chip on the administrator's row
Regions and AWS statusOne line per region, each carrying a pair of chips
ProgressA single chip summarising the whole account, plus any error messages
RetriesThe highest retry count across the account's regions, or —
ActionsThe buttons that apply, computed per region cell (see below)

One row is one account, because every action the API offers is account-scoped. The per-region truth is not thrown away: each region gets its own line in the Regions and AWS status column, carrying two chips, always, not only when they disagree.

ChipWhat it is
Phase chip, prefixed with the region, for example eu-west-1 · InvitingPrism's own enrollment phase for that account in that region
AWS status chip, for example Email not verifiedThe member status Amazon Detective reports for that account and region

They are separate because they answer different questions and often disagree while both are true. An account can be at phase Failed with the AWS status Accepted, not ingesting: it did join the graph, and it is not ingesting. Phase alone cannot tell that apart from a verification failure, and the remedies are different.

Showing AWS's answer only on mismatch would hide the evidence on the one screen that could explain a stuck enrollment.

tip

Every AWS status chip carries the raw token in its tooltip. Hover it and you get AWS member status: VERIFICATION_FAILED, so the exact value AWS returned is never more than a hover away from the friendlier label.

Where AWS has not reported anything for a cell yet, a neutral No AWS status yet chip stands in its place rather than leaving the column blank.

The Progress column carries a third chip, which collapses the account's regions into one verdict: Failed wins over everything, because it is the only phase that carries an action; otherwise the first of Removing, Granting access, Inviting, Accepting invitation, Enabling or Pending that any region is in; Removed only when every region is a tombstone; Enabled otherwise. A small spinner sits beside it while that phase is active. Any per-region error messages are printed underneath, each prefixed with its region and separated by •.

Phase Reference​

PhaseColourDescription
PendingGreyEnrollment submitted, waiting to start
Granting accessBluePrism is attaching the Detective permissions policy to the account's access role and waiting for it to take effect
EnablingBlueThe behavior graph is being prepared for this account
InvitingBlueThe invitation has been created and AWS is verifying the root email address
Accepting invitationBluePrism is accepting the invitation in the account's own session
EnabledGreenFully joined to the behavior graph
FailedRedEnrollment did not complete; read the AWS status chip and the message below it
RemovingAmberRemoval is in progress
RemovedGreyThe account has been removed from the behavior graph
note

Granting access and Inviting are the two phases that legitimately take minutes. Granting waits for an IAM change to become usable; Inviting waits for AWS to verify a root email address. A row sitting in either is healthy, not stuck, and the page keeps polling throughout.

warning

"Removed" never means "present but switched off". The phase Prism stores is disabled, but the chip says Removed because the row is a tombstone: it is written after the account was taken out of the graph and Prism's CKPrism-Detective-Permissions policy was detached from its access role. See Removed accounts.

AWS Member Status Reference​

Three of these are AWS's own value Title-Cased. Two carry a Prism-authored label, because AWS's own word is actively misleading on this screen.

ChipRaw AWS statusMeaning
InvitedINVITEDThe invitation exists and AWS has finished verifying the address
Verification in progressVERIFICATION_IN_PROGRESSAWS is still matching the address to the account
Email not verifiedVERIFICATION_FAILEDAWS could not match the address to the account's root user. Reads like a Prism failure; it is AWS rejecting the address. See Verification failed
EnabledENABLEDJoined and ingesting
Accepted, not ingestingACCEPTED_BUT_DISABLEDReads like a removal; it means the account did join the graph and Detective is holding it out of ingestion. See Accepted but not ingesting

Which Actions Appear on a Row​

Actions are computed from the region cells, not from a single account-level status. The member status is per (account, region), but every API call the page can make takes only an account ID, so a row offers whichever buttons any of its regions call for.

ButtonAppears when
RetryAt least one region cell is at phase Failed and its AWS status is not ACCEPTED_BUT_DISABLED
Start monitoringAt least one region cell has the AWS status ACCEPTED_BUT_DISABLED
RemoveAlways, unless the account's summary phase is Removing
warning

An account can show both Retry and Start monitoring at once. An account that is ACCEPTED_BUT_DISABLED in us-east-1 and genuinely failed in eu-west-1 needs both remedies, and gets both buttons. There is no flat status-to-action mapping to read off: check the region lines to see which cell each button is for.

All three buttons are disabled while another action on the page is in flight, and while enrollment changes are unavailable.

The administrator's row carries no buttons at all, only the sentence:

Removing the administrator is a full disable — use Settings.

Verification Failed​

Problem: an account shows phase Failed with the AWS status chip Email not verified (VERIFICATION_FAILED), several minutes after the enrollment appeared to succeed.

Cause: Amazon Detective could not match the root email address supplied for that account against the account's actual AWS root user. The invitation call itself succeeds regardless of the address, which is why nothing was reported at the time you submitted.

Fix: the row grows an inline AWS root user email address field, pre-filled with the address that was rejected, directly above the Retry button. Correct the address, then click Retry. The field's helper text reads "Must be the account's real AWS root user address."

warning

Retrying with the same address fails identically, every time. This is not a transient error and there is nothing to wait out. The address must change before the retry can succeed. The row's message says so explicitly:

AWS could not verify the rejected address against this account’s real AWS root user. Retrying with the same address fails identically — correct it below first.

Where Prism has no address on file for the cell, the message reads "AWS could not verify the address supplied against this account’s real AWS root user…" instead.

note

The Retry button stays disabled until the field has a value. When the inline field is shown, Retry is greyed out while it is empty, and the address you type is sent verbatim rather than being re-resolved, which would return the same rejected address and loop forever.

The field is only ever rendered beside a live Retry button. A correction field with nothing to submit it is worse than no field at all, so a row that has a verification-failed cell but no retryable cell shows neither.

To find the correct address, sign in to that AWS account and open Account Settings > Account > Email address in the AWS Console. It must be the account's root user address, not an IAM user's email, a distribution list, or an alias.

Accepted but Not Ingesting​

Problem: an account shows phase Failed with the AWS status chip Accepted, not ingesting (ACCEPTED_BUT_DISABLED).

The account is a member of the behavior graph. Detective has accepted it and then held it out of ingestion, so it is joined but contributing nothing. The action is Start monitoring, and the reason AWS reports determines whether it will work. The explanation is printed on the row per region, prefixed with the region name, because one account can be held out in one region and healthy in another.

ReasonWhat the row saysAction
VOLUME_UNKNOWN"Amazon Detective accepted this account into the behavior graph but is not ingesting its data, and could not determine the account's data volume. The usual cause is that the account is not enrolled in Amazon GuardDuty. Enroll it there, then start monitoring."Enable GuardDuty for that account, then click Start monitoring
VOLUME_TOO_HIGH"Amazon Detective accepted this account into the behavior graph but is not ingesting its data: its volume is above Detective's 10 TB per day ingest limit. Start monitoring will only succeed once the volume drops below that limit — pressing it sooner is refused by AWS."Start monitoring is offered but AWS refuses it until the volume drops; remove higher-volume accounts, or request a limit increase from AWS Support
warning

There is no Retry button for an ACCEPTED_BUT_DISABLED cell. This is not operator discipline you have to remember, it is structural: the page excludes those cells when it decides whether to offer Retry. The account is already a member, CreateMembers returns it as already present and AcceptInvitation answers 409, so a Retry there would be a button that can never work. Start monitoring is the action that applies.

A row can still show Retry when a different region has genuinely failed, see Which actions appear on a row.

note

Amazon Detective does not always report a reason. When it does not, the row reads:

Amazon Detective accepted this account into the behavior graph but is not ingesting its data. AWS did not report which of its two ingest limits is holding it out.

In practice an absent reason is common, so treat the reason as extra information when it is present rather than as something that will always be there. The reason field is populated only alongside this status; it is empty on every other failing state, so nothing on the page treats it as a general "why did this fail" field.

Failed Accounts Still Occupy a Member Slot​

Any account that was invited still counts as a member of the behavior graph, whether or not the invitation was ever accepted or verified. AWS lists it as a member from the moment the invitation is created, and DeleteMembers has no member-status precondition, so an un-accepted or verification-failed account can be removed exactly like an enabled one.

warning

A behavior graph holds at most 1,200 member accounts, and a verification-failed or never-accepted account still occupies one of those slots. An abandoned partial enrollment therefore consumes quota, not merely coverage, and the quota is not returned until the account is removed.

A row carries the reminder when it has a region cell at phase Failed whose AWS status is INVITED, VERIFICATION_IN_PROGRESS, or VERIFICATION_FAILED, that is, the account is in the graph but never finished joining:

This account still occupies one of the behavior graph's 1,200 member slots. Retry it, or remove it from Detective to release the slot.

Do neither and a later enable will be refused over a limit you did not know you were spending.

This does not apply to an ACCEPTED_BUT_DISABLED account. That account is fully joined and awaiting monitoring, and the remedy there is Start monitoring, not removal.

Adding Member Accounts​

The Not in the graph table ("Linked accounts Amazon Detective is not investigating") lists the accounts in your organization that are not currently in the behavior graph, including any previously removed ones, which carry a previously removed chip. When there is nothing left to add it reads "Every linked account is in the graph".

  1. Select the accounts you want to enrol. Use the header checkbox to select all at once, or check individual rows.

  2. Click Add N to Detective (where N is the number of selected accounts). With nothing selected the button reads Add to Detective and is disabled.

  3. Prism resolves the AWS root user email address for each selected account automatically, as the page explains above the table:

    Detective enrolls by invitation, and AWS checks each account’s AWS root user email address before it joins. Prism looks the addresses up automatically; if any cannot be resolved, or AWS refuses one, you will be asked for exactly those before the invitation is sent.

    • If every address resolves, the accounts are added and enter the enrollment phases.
    • If any cannot be resolved, or was resolved and refused, the add stops and the email dialog below opens with exactly those accounts.

The Root Email Dialog​

The server answers a partial add with the list of accounts it still needs an address for, and the page reopens as a step rather than reporting a failure: a generic "request failed" naming no accounts would be a dead end.

The dialog is titled AWS root user email addresses and shows the server's own sentence in a warning banner, falling back to "Some member accounts need an AWS root user email address before enrollment". Under it:

AWS checks each address 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 as Email not verified with nothing on screen to explain why.

Each flagged account gets its own AWS root user email address field, labelled with the account, pre-filled with whatever address was resolved and refused, and carrying the server's reason for that account as helper text (or "Enter this account’s AWS root user email address." where there is none). Fill them in and click Invite accounts; the button stays disabled until every field has a value.

note

A second refusal does not wipe what you typed. If the corrected addresses are still wrong, the dialog reopens with the accounts that failed again and keeps the values already in the fields rather than resetting them to the server's, so a correction that is still wrong is edited rather than retyped.

tip

Add member accounts in batches of 5 or fewer to avoid root-email resolution timeouts. Root-email resolution runs synchronously for the whole selection and is not cached, so a large selection can exceed the request timeout. After each batch reaches Enabled, add the next.

This matters more for Detective than for GuardDuty or Macie: a Detective behavior graph permits up to 1,200 members, so the selections people attempt here are far larger.

warning

Each member account must use its real AWS root user email address. A wrong or placeholder address does not fail at submit; it fails several minutes later as VERIFICATION_FAILED. See Verification failed.

Removing an Account​

  1. In the Graph members table, click Remove on the account's row.

  2. A confirmation dialog headed Remove account from Detective appears, naming the account:

    Remove 123456789012? It is deleted from the behavior graph in every region, which releases the member slot it holds, its cached investigations are deleted here, and Prism detaches the IAM policy it added to the account’s access role. The row stays on this page as a record of that. Adding the account back later re-invites it, and AWS verifies its root user email address again.

  3. Confirm with Remove. The account enters the Removing phase, and its Remove button disappears while that runs. When removal completes it is marked Removed, moves to the Removed accounts table, and reappears in Not in the graph so it can be re-enrolled later.

The administrator account cannot be removed from this page. To stop Detective entirely, use the Danger zone tab in Settings.

Removed Accounts​

Removed accounts are not dropped from the page. Once at least one account has been removed, a Removed accounts section appears ("Tombstoned rows — the record that Prism removed each account and detached its scoped IAM policy") with its own count chip, for example 2 removed, and three columns: Account, Regions and last AWS status, and Last error.

These rows are kept, never deleted. Each one is the only record that Prism attached its CKPrism-Detective-Permissions policy to that account’s access role and then detached it — an account that disappeared from this page instead would be one nobody could check. Add an account back from the picker below to re-invite it.

Each row keeps its per-region chips, so the last state each region reached is still readable, and the Last error column shows the final message per region, or —.

An account only lands here when every one of its region cells is a tombstone. An account removed from one region but live in another stays in Graph members.

Live Auto-Polling​

While any account is in an active phase (Pending, Granting access, Enabling, Inviting, Accepting invitation, or Removing), or the configuration itself is still working, the page polls the server automatically and updates the chips and progress bar without a manual refresh.

note

An account that finishes enrolling while it is still ticked in the Not in the graph picker is un-ticked automatically. Re-sending an already-enrolled account is skipped server-side, and if every ticked account is already enrolled the whole request is refused, which would read as the failure of an add that in fact succeeded.