Detective examples using Amazon CLI - Amazon Command Line Interface
Actions
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Detective examples using Amazon CLI

The following code examples show you how to perform actions and implement common scenarios by using the Amazon Command Line Interface with Detective.

Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios and cross-service examples.

Scenarios are code examples that show you how to accomplish a specific task by calling multiple functions within the same service.

Each example includes a link to GitHub, where you can find instructions on how to set up and run the code in context.

Topics

Actions

The following code example shows how to use accept-invitation.

Amazon CLI

To accept an invitation to become a member account in a behavior graph

The following accept-invitation example accepts an invitation to become a member account in behavior graph arn:aws:detective:us-east-1:111122223333:graph:123412341234.

aws detective accept-invitation \
    --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

This command produces no output.

For more information, see Responding to a behavior graph invitation in the Amazon Detective Administration Guide.

The following code example shows how to use create-graph.

Amazon CLI

To enable Amazon Detective and create a new behavior graph

The following create-graph example enables Detective for the Amazon account that runs the command in the Region where the command is run. A new behavior graph is created that has that account as its administrator account. The command also assigns the value Finance to the Department tag.

aws detective create-graph \
    --tags '{"Department": "Finance"}'

Output:

{
    "GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:027c7c4610ea4aacaf0b883093cab899"
}

For more information, see Enabling Amazon Detective in the Amazon Detective Administration Guide.

  • For API details, see CreateGraph in Amazon CLI Command Reference.

The following code example shows how to use create-members.

Amazon CLI

To invite member accounts to a behavior graph

The following create-members example invites two Amazon accounts to become member accounts in the behavior graph arn:aws:detective:us-east-1:111122223333:graph:123412341234. For each account, the request provides the Amazon account ID and the account root user email address. The request includes a custom message to insert into the invitation email.

aws detective create-members \
    --accounts AccountId=444455556666,EmailAddress=mmajor@example.com AccountId=123456789012,EmailAddress=jstiles@example.com \
    --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234 \
    --message "This is Paul Santos. I need to add your account to the data we use for security investigation in Amazon Detective. If you have any questions, contact me at psantos@example.com."

Output:

{
    "Members": [
    {
        "AccountId": "444455556666",
        "AdministratorId": "111122223333",
        "EmailAddress": "mmajor@example.com",
        "GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:123412341234",
        "InvitedTime": 1579826107000,
        "MasterId": "111122223333",
        "Status": "INVITED",
        "UpdatedTime": 1579826107000
   },
   {
        "AccountId": "123456789012",
        "AdministratorId": "111122223333",
        "EmailAddress": "jstiles@example.com",
        "GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:123412341234",
        "InvitedTime": 1579826107000,
        "MasterId": "111122223333",
        "Status": "VERIFICATION_IN_PROGRESS",
        "UpdatedTime": 1579826107000
     }
    ],
    "UnprocessedAccounts": [ ]
}

For more information, see Inviting member accounts to a behavior graph<https://docs.aws.amazon.com/detective/latest/adminguide/graph-admin-add-member-accounts.html> in the Amazon Detective Administration Guide.

To invite member accounts without sending invitation emails

The following create-members example invites two Amazon accounts to become member accounts in the behavior graph arn:aws:detective:us-east-1:111122223333:graph:123412341234. For each account, the request provides the Amazon account ID and the account root user email address. The member accounts do not receive invitation emails.

aws detective create-members \
    --accounts AccountId=444455556666,EmailAddress=mmajor@example.com AccountId=123456789012,EmailAddress=jstiles@example.com \
    --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234 \
    --disable-email-notification

Output:

{
    "Members": [
    {
        "AccountId": "444455556666",
        "AdministratorId": "111122223333",
        "EmailAddress": "mmajor@example.com",
        "GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:123412341234",
        "InvitedTime": 1579826107000,
        "MasterId": "111122223333",
        "Status": "INVITED",
        "UpdatedTime": 1579826107000
   },
   {
        "AccountId": "123456789012",
        "AdministratorId": "111122223333",
        "EmailAddress": "jstiles@example.com",
        "GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:123412341234",
        "InvitedTime": 1579826107000,
        "MasterId": "111122223333",
        "Status": "VERIFICATION_IN_PROGRESS",
        "UpdatedTime": 1579826107000
     }
    ],
    "UnprocessedAccounts": [ ]
}

For more information, see Inviting member accounts to a behavior graph<https://docs.aws.amazon.com/detective/latest/adminguide/graph-admin-add-member-accounts.html> in the Amazon Detective Administration Guide.

  • For API details, see CreateMembers in Amazon CLI Command Reference.

The following code example shows how to use delete-graph.

Amazon CLI

To disable Detective and delete the behavior graph

The following delete-graph example disables Detective and deletes the specified behavior graph.

aws detective delete-graph \
    --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

This command produces no output.

For more information, see Disabling Amazon Detective in the Amazon Detective Administration Guide.

  • For API details, see DeleteGraph in Amazon CLI Command Reference.

The following code example shows how to use delete-members.

Amazon CLI

To remove member accounts from a behavior graph

The following delete-members example removes two member accounts from the behavior graph arn:aws:detective:us-east-1:111122223333:graph:123412341234. To identify the accounts, the request provides the Amazon account IDs.

aws detective delete-members \
    --account-ids 444455556666 123456789012 \
    --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

Output:

 {
    "AccountIds": [ "444455556666", "123456789012" ],
    "UnprocessedAccounts": [ ]
}

For more information, see Removing member accounts from a behavior graph<https://docs.aws.amazon.com/detective/latest/adminguide/graph-admin-remove-member-accounts.html> in the Amazon Detective Administration Guide.

  • For API details, see DeleteMembers in Amazon CLI Command Reference.

The following code example shows how to use disassociate-membership.

Amazon CLI

To resign membership from a behavior graph

The following disassociate-membership example removes the Amazon account that runs the command from the behavior graph arn:aws:detective:us-east-1:111122223333:graph:123412341234.

aws detective disassociate-membership \
     --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

For more information, see Removing your account from a behavior graph<https://docs.aws.amazon.com/detective/latest/adminguide/member-remove-self-from-graph.html> in the Amazon Detective Administration Guide.

The following code example shows how to use get-members.

Amazon CLI

To retrieve information about selected behavior graph member accounts

The following get-members example retrieves information about two member accounts in the behavior graph arn:aws:detective:us-east-1:111122223333:graph:123412341234. For the two accounts, the request provides the Amazon account IDs.

aws detective get-members \
    --account-ids 444455556666 123456789012 \
    --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

Output:

{
    "MemberDetails": [
    {
        "AccountId": "444455556666",
        "AdministratorId": "111122223333",
        "EmailAddress": "mmajor@example.com",
        "GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:123412341234",
        "InvitedTime": 1579826107000,
        "MasterId": "111122223333",
        "Status": "INVITED",
        "UpdatedTime": 1579826107000
    }
    {
        "AccountId": "123456789012",
        "AdministratorId": "111122223333",
        "EmailAddress": "jstiles@example.com",
        "GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:123412341234",
        "InvitedTime": 1579826107000,
        "MasterId": "111122223333",
        "Status": "INVITED",
        "UpdatedTime": 1579826107000
    }
],
    "UnprocessedAccounts": [ ]
}

For more information, see Viewing the list of accounts in a behavior graph<https://docs.aws.amazon.com/detective/latest/adminguide/graph-admin-view-accounts.html> in the Amazon Detective Administration Guide.

  • For API details, see GetMembers in Amazon CLI Command Reference.

The following code example shows how to use list-graphs.

Amazon CLI

To view a list of behavior graphs that your account is the administrator for

The following list-graphs example retrieves the behavior graphs that the calling account is the administrator for within the current Region.

aws detective list-graphs

Output:

{
    "GraphList": [
        {
            "Arn": "arn:aws:detective:us-east-1:111122223333:graph:123412341234",
            "CreatedTime": 1579736111000
        }
    ]
}

  • For API details, see ListGraphs in Amazon CLI Command Reference.

The following code example shows how to use list-invitations.

Amazon CLI

To view a list of behavior graphs that an account is a member of or is invited to

The following list-invitations example retrieves the behavior graphs that the calling account has been invited to. The results include only open and accepted invitations. They do not include rejected invitations or removed memberships.

aws detective list-invitations

Output:

{
    "Invitations": [
    {
        "AccountId": "444455556666",
        "AdministratorId": "111122223333",
        "EmailAddress": "mmajor@example.com",
        "GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:123412341234",
        "InvitedTime": 1579826107000,
        "MasterId": "111122223333",
        "Status": "INVITED",
        "UpdatedTime": 1579826107000
    }
]
}

For more information, see Viewing your list of behavior graph invitations<https://docs.aws.amazon.com/detective/latest/adminguide/member-view-graph-invitations.html> in the Amazon Detective Administration Guide.

The following code example shows how to use list-members.

Amazon CLI

To list the member accounts in a behavior graph

The following list-members example retrieves the invited and enabled member accounts for the behavior graph arn:aws:detective:us-east-1:111122223333:graph:123412341234. The results do not include member accounts that were removed.

aws detective list-members \
    --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

Output:

{
    "MemberDetails": [
        {
            "AccountId": "444455556666",
            "AdministratorId": "111122223333",
            "EmailAddress": "mmajor@example.com",
            "GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:123412341234",
            "InvitedTime": 1579826107000,
            "MasterId": "111122223333",
            "Status": "INVITED",
            "UpdatedTime": 1579826107000
        },
        {
            "AccountId": "123456789012",
            "AdministratorId": "111122223333",
            "EmailAddress": "jstiles@example.com",
            "GraphArn": "arn:aws:detective:us-east-1:111122223333:graph:123412341234",
            "InvitedTime": 1579826107000,
            "MasterId": "111122223333",
            "PercentOfGraphUtilization": 2,
            "PercentOfGraphUtilizationUpdatedTime": 1586287843,
            "Status": "ENABLED",
            "UpdatedTime": 1579973711000,
            "VolumeUsageInBytes": 200,
            "VolumeUsageUpdatedTime": 1586287843
        }
    ]
}

For more information, see Viewing the list of accounts in a behavior graph in the Amazon Detective Administration Guide.

  • For API details, see ListMembers in Amazon CLI Command Reference.

The following code example shows how to use list-tags-for-resource.

Amazon CLI

To retrieve the tags assigned to a behavior graph

The following list-tags-for-resource example returns the tags assigned to the specified behavior graph.

aws detective list-tags-for-resource \
    --resource-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

Output:

{
    "Tags": {
        "Department" : "Finance"
    }
}

For more information, see Managing tags for a behavior graph in the Amazon Detective Administration Guide.

The following code example shows how to use reject-invitation.

Amazon CLI

To reject an invitation to become a member account in a behavior graph

The following reject-invitation example rejects an invitation to become a member account in the behavior graph arn:aws:detective:us-east-1:111122223333:graph:123412341234.

aws detective reject-invitation \
    --graph-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234

This command produces no output.

For more information, see Responding to a behavior graph invitation<https://docs.aws.amazon.com/detective/latest/adminguide/member-invitation-response.html> in the Amazon Detective Administration Guide.

The following code example shows how to use tag-resource.

Amazon CLI

To assign a tag to a resource

The following tag-resource example assigns a value for the Department tag to the specified behavior graph.

aws detective tag-resource \
    --resource-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234 \
    --tags '{"Department":"Finance"}'

This command produces no output.

For more information, see Managing tags for a behavior graph in the Amazon Detective Administration Guide.

  • For API details, see TagResource in Amazon CLI Command Reference.

The following code example shows how to use untag-resource.

Amazon CLI

To remove a tag value from a resource

The following untag-resource example removes the Department tag from the specified behavior graph.

aws detective untag-resource \
    --resource-arn arn:aws:detective:us-east-1:111122223333:graph:123412341234 \
    --tag-keys "Department"

This command produces no output.

For more information, see Managing tags for a behavior graph in the Amazon Detective Administration Guide.

  • For API details, see UntagResource in Amazon CLI Command Reference.