Amazon Web Services, Inc.

Amazon Detective

Detective uses machine learning and purpose-built visualizations to help you to analyze and investigate security issues across your Amazon Web Services…

Identity & security#openapi#cloud

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Detective uses machine learning and purpose-built visualizations to help you to
analyze and investigate security issues across your Amazon Web Services (Amazon Web Services) workloads. Detective automatically extracts time-based events such
as login attempts, API calls, and network traffic from CloudTrail and Amazon Virtual Private Cloud (Amazon VPC) flow logs. It also extracts findings detected by
Amazon GuardDuty.
The Detective API primarily supports the creation and management of behavior
graphs. A behavior graph contains the extracted data from a set of member accounts, and is
created and managed by an administrator account.
To add a member account to the behavior graph, the administrator account sends an
invitation to the account. When the account accepts the invitation, it becomes a member
account in the behavior graph.
Detective is also integrated with Organizations. The organization
management account designates the Detective administrator account for the
organization. That account becomes the administrator account for the organization behavior
graph. The Detective administrator account is also the delegated administrator
account for Detective in Organizations.
The Detective administrator account can enable any organization account as a
member account in the organization behavior graph. The organization accounts do not receive
invitations. The Detective administrator account can also invite other accounts to
the organization behavior graph.
Every behavior graph is specific to a Region. You can only use the API to manage
behavior graphs that belong to the Region that is associated with the currently selected
endpoint.
The administrator account for a behavior graph can use the Detective API to do
the following:

Enable and disable Detective. Enabling Detective creates a new
behavior graph.

View the list of member accounts in a behavior graph.

Add member accounts to a behavior graph.

Remove member accounts from a behavior graph.

Apply tags to a behavior graph.

The organization management account can use the Detective API to select the
delegated administrator for Detective.
The Detective administrator account for an organization can use the Detective API to do the following:

Perform all of the functions of an administrator account.

Determine whether to automatically enable new organization accounts as member
accounts in the organization behavior graph.

An invited member account can use the Detective API to do the following:

View the list of behavior graphs that they are invited to.

Accept an invitation to contribute to a behavior graph.

Decline an invitation to contribute to a behavior graph.

Remove their account from a behavior graph.

All API actions are logged as CloudTrail events. See Logging Detective API Calls with CloudTrail .

We replaced the term "master account" with the term "administrator account". An
administrator account is used to centrally manage multiple accounts. In the case of
Detective, the administrator account manages the accounts in their behavior
graph.

Endpoints 29

  • PUTAccept invitation/invitationAccepts an invitation for the member account to contribute data to a behavior graph. This operation can only be called by an invited member account. The…
  • POSTBatch get graph member datasources/graph/datasources/getGets data source package information for the behavior graph.
  • POSTBatch get membership datasources/membership/datasources/getGets information on the data source package history for an account.
  • POSTCreate graph/graphCreates a new behavior graph for the calling account, and sets that account as the administrator account. This operation is called by the account that is…
  • POSTCreate members/graph/membersCreateMembers is used to send invitations to accounts. For the organization behavior graph, the Detective administrator account uses CreateMembers to enable…
  • POSTDelete graph/graph/removalDisables the specified behavior graph and queues it to be deleted. This operation removes the behavior graph from each member account's list of behavior…
  • POSTDelete members/graph/members/removalRemoves the specified member accounts from the behavior graph. The removed accounts no longer contribute data to the behavior graph. This operation can only…
  • POSTDescribe organization configuration/orgs/describeOrganizationConfigurationReturns information about the configuration for the organization behavior graph. Currently indicates whether to automatically enable new organization accounts…
  • POSTDisable organization admin account/orgs/disableAdminAccountRemoves the Detective administrator account in the current Region. Deletes the organization behavior graph. Can only be called by the organization management…
  • POSTDisassociate membership/membership/removalRemoves the member account from the specified behavior graph. This operation can only be called by an invited member account that has the ENABLED status.…
  • POSTEnable organization admin account/orgs/enableAdminAccountDesignates the Detective administrator account for the organization in the current Region. If the account does not have Detective enabled, then enables…
  • POSTGet investigation/investigations/getInvestigationDetective investigations lets you investigate IAM users and IAM roles using indicators of compromise. An indicator of compromise (IOC) is an artifact observed…
  • POSTGet members/graph/members/getReturns the membership details for specified member accounts for a behavior graph.
  • POSTList datasource packages/graph/datasources/listLists data source packages in the behavior graph.
  • POSTList graphs/graphs/listReturns the list of behavior graphs that the calling account is an administrator account of. This operation can only be called by an administrator account.…
  • POSTList indicators/investigations/listIndicatorsGets the indicators from an investigation. You can use the information from the indicators to determine if an IAM user and/or IAM role is involved in an…
  • POSTList investigations/investigations/listInvestigationsDetective investigations lets you investigate IAM users and IAM roles using indicators of compromise. An indicator of compromise (IOC) is an artifact observed…
  • POSTList invitations/invitations/listRetrieves the list of open and accepted behavior graph invitations for the member account. This operation can only be called by an invited member account.…
  • POSTList members/graph/members/listRetrieves the list of member accounts for a behavior graph. For invited accounts, the results do not include member accounts that were removed from the…
  • POSTList organization admin accounts/orgs/adminAccountslistReturns information about the Detective administrator account for an organization. Can only be called by the organization management account.
  • GETList tags for resource/tags/:ResourceArnReturns the tag values that are assigned to a behavior graph.
  • POSTTag resource/tags/:ResourceArnApplies tag values to a behavior graph.
  • DELETEUntag resource/tags/:ResourceArn?tagKeys=Removes tags from a behavior graph.
  • POSTReject invitation/invitation/removalRejects an invitation to contribute the account data to a behavior graph. This operation must be called by an invited member account that has the INVITED…
  • POSTStart investigation/investigations/startInvestigationDetective investigations lets you investigate IAM users and IAM roles using indicators of compromise. An indicator of compromise (IOC) is an artifact observed…
  • POSTStart monitoring member/graph/member/monitoringstateSends a request to enable data ingest for a member account that has a status of ACCEPTED_BUT_DISABLED . For valid member accounts, the status is updated as…
  • POSTUpdate datasource packages/graph/datasources/updateStarts a data source package for the Detective behavior graph.
  • POSTUpdate investigation state/investigations/updateInvestigationStateUpdates the state of an investigation.
  • POSTUpdate organization configuration/orgs/updateOrganizationConfigurationUpdates the configuration for the Organizations integration in the current Region. Can only be called by the Detective administrator account for the…

API details

Base URL
https://api.detective.{region}.amazonaws.com
Authentication
AWS Signature Version 4 (requests signed with your AWS access key)
Operations
29 operations on 27 pathsPOST 26GET 1PUT 1DELETE 1
Description format
AWS Smithy model, API version 2018-10-26

How to test the Amazon Detective in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Amazon Detective collection, without the publisher's secrets.
  3. Add your credentialsThis API uses AWS Signature Version 4 (requests signed with your AWS access key). Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Accept invitation” (PUT /invitation), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Amazon Detective?

Detective uses machine learning and purpose-built visualizations to help you to analyze and investigate security issues across your Amazon Web Services… It is listed under Identity & security and has 29 endpoints.

Who publishes the Amazon Detective?

It is listed from Amazon Web Services, Inc.'s public API description (an OpenAPI document), not published by Amazon Web Services, Inc. on Swastik Codes. Anyone who controls amazonaws.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Amazon Detective?

Requests go to https://api.detective.{region}.amazonaws.com. Endpoint paths are added to this base URL.

How do I authenticate with the Amazon Detective?

With AWS Signature Version 4 (requests signed with your AWS access key).

How many endpoints does the Amazon Detective have?

29 operations on 27 paths (26 POST, 1 GET, 1 PUT, 1 DELETE).

Is forking the Amazon Detective free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.