Security Incident Response

2025/05/23 - Security Incident Response - 5 updated api methods

Changes  Update PrincipalId pattern documentation to reflect what user should receive back from the API call

CreateCase (updated) Link ¶
Changes (request)
{'impactedAwsRegions': {'region': ['ap-southeast-7', 'mx-central-1']}}

Grants permission to create a new case.

See also: AWS API Documentation

Request Syntax

client.create_case(
    clientToken='string',
    resolverType='AWS'|'Self',
    title='string',
    description='string',
    engagementType='Security Incident'|'Investigation',
    reportedIncidentStartDate=datetime(2015, 1, 1),
    impactedAccounts=[
        'string',
    ],
    watchers=[
        {
            'email': 'string',
            'name': 'string',
            'jobTitle': 'string'
        },
    ],
    threatActorIpAddresses=[
        {
            'ipAddress': 'string',
            'userAgent': 'string'
        },
    ],
    impactedServices=[
        'string',
    ],
    impactedAwsRegions=[
        {
            'region': 'af-south-1'|'ap-east-1'|'ap-northeast-1'|'ap-northeast-2'|'ap-northeast-3'|'ap-south-1'|'ap-south-2'|'ap-southeast-1'|'ap-southeast-2'|'ap-southeast-3'|'ap-southeast-4'|'ap-southeast-5'|'ap-southeast-7'|'ca-central-1'|'ca-west-1'|'cn-north-1'|'cn-northwest-1'|'eu-central-1'|'eu-central-2'|'eu-north-1'|'eu-south-1'|'eu-south-2'|'eu-west-1'|'eu-west-2'|'eu-west-3'|'il-central-1'|'me-central-1'|'me-south-1'|'mx-central-1'|'sa-east-1'|'us-east-1'|'us-east-2'|'us-west-1'|'us-west-2'
        },
    ],
    tags={
        'string': 'string'
    }
)
type clientToken:

string

param clientToken:

Required element used in combination with CreateCase.

This field is autopopulated if not provided.

type resolverType:

string

param resolverType:

[REQUIRED]

Required element used in combination with CreateCase to identify the resolver type. Available resolvers include self-supported | aws-supported.

type title:

string

param title:

[REQUIRED]

Required element used in combination with CreateCase to provide a title for the new case.

type description:

string

param description:

[REQUIRED]

Required element used in combination with CreateCase to provide a description for the new case.

type engagementType:

string

param engagementType:

[REQUIRED]

Required element used in combination with CreateCase to provide an engagement type for the new cases. Available engagement types include Security Incident | Investigation

type reportedIncidentStartDate:

datetime

param reportedIncidentStartDate:

[REQUIRED]

Required element used in combination with CreateCase to provide an initial start date for the unauthorized activity.

type impactedAccounts:

list

param impactedAccounts:

[REQUIRED]

Required element used in combination with CreateCase to provide a list of impacted accounts.

  • (string) --

type watchers:

list

param watchers:

[REQUIRED]

Required element used in combination with CreateCase to provide a list of entities to receive notifications for case updates.

  • (dict) --

    • email (string) -- [REQUIRED]

    • name (string) --

    • jobTitle (string) --

type threatActorIpAddresses:

list

param threatActorIpAddresses:

An optional element used in combination with CreateCase to provide a list of suspicious internet protocol addresses associated with unauthorized activity.

  • (dict) --

    • ipAddress (string) -- [REQUIRED]

    • userAgent (string) --

type impactedServices:

list

param impactedServices:

An optional element used in combination with CreateCase to provide a list of services impacted.

  • (string) --

type impactedAwsRegions:

list

param impactedAwsRegions:

An optional element used in combination with CreateCase to provide a list of impacted regions.

  • (dict) --

    • region (string) -- [REQUIRED]

type tags:

dict

param tags:

An optional element used in combination with CreateCase to add customer specified tags to a case.

  • (string) --

    • (string) --

rtype:

dict

returns:

Response Syntax

{
    'caseId': 'string'
}

Response Structure

  • (dict) --

    • caseId (string) --

      A response element providing responses for requests to CreateCase. This element responds with the case ID.

GetCase (updated) Link ¶
Changes (response)
{'impactedAwsRegions': {'region': ['ap-southeast-7', 'mx-central-1']}}

Grant permission to view a designated case.

See also: AWS API Documentation

Request Syntax

client.get_case(
    caseId='string'
)
type caseId:

string

param caseId:

[REQUIRED]

Required element for GetCase to identify the requested case ID.

rtype:

dict

returns:

Response Syntax

{
    'title': 'string',
    'caseArn': 'string',
    'description': 'string',
    'caseStatus': 'Submitted'|'Acknowledged'|'Detection and Analysis'|'Containment, Eradication and Recovery'|'Post-incident Activities'|'Ready to Close'|'Closed',
    'engagementType': 'Security Incident'|'Investigation',
    'reportedIncidentStartDate': datetime(2015, 1, 1),
    'actualIncidentStartDate': datetime(2015, 1, 1),
    'impactedAwsRegions': [
        {
            'region': 'af-south-1'|'ap-east-1'|'ap-northeast-1'|'ap-northeast-2'|'ap-northeast-3'|'ap-south-1'|'ap-south-2'|'ap-southeast-1'|'ap-southeast-2'|'ap-southeast-3'|'ap-southeast-4'|'ap-southeast-5'|'ap-southeast-7'|'ca-central-1'|'ca-west-1'|'cn-north-1'|'cn-northwest-1'|'eu-central-1'|'eu-central-2'|'eu-north-1'|'eu-south-1'|'eu-south-2'|'eu-west-1'|'eu-west-2'|'eu-west-3'|'il-central-1'|'me-central-1'|'me-south-1'|'mx-central-1'|'sa-east-1'|'us-east-1'|'us-east-2'|'us-west-1'|'us-west-2'
        },
    ],
    'threatActorIpAddresses': [
        {
            'ipAddress': 'string',
            'userAgent': 'string'
        },
    ],
    'pendingAction': 'Customer'|'None',
    'impactedAccounts': [
        'string',
    ],
    'watchers': [
        {
            'email': 'string',
            'name': 'string',
            'jobTitle': 'string'
        },
    ],
    'createdDate': datetime(2015, 1, 1),
    'lastUpdatedDate': datetime(2015, 1, 1),
    'closureCode': 'Investigation Completed'|'Not Resolved'|'False Positive'|'Duplicate',
    'resolverType': 'AWS'|'Self',
    'impactedServices': [
        'string',
    ],
    'caseAttachments': [
        {
            'attachmentId': 'string',
            'fileName': 'string',
            'attachmentStatus': 'Verified'|'Failed'|'Pending',
            'creator': 'string',
            'createdDate': datetime(2015, 1, 1)
        },
    ],
    'closedDate': datetime(2015, 1, 1)
}

Response Structure

  • (dict) --

    • title (string) --

      Response element for GetCase that provides the case title.

    • caseArn (string) --

      Response element for GetCase that provides the case ARN

    • description (string) --

      Response element for GetCase that provides contents of the case description.

    • caseStatus (string) --

      Response element for GetCase that provides the case status. Options for statuses include Submitted | Detection and Analysis | Eradication, Containment and Recovery | Post-Incident Activities | Closed

    • engagementType (string) --

      Response element for GetCase that provides the engagement type. Options for engagement type include Active Security Event | Investigations

    • reportedIncidentStartDate (datetime) --

      Response element for GetCase that provides the customer provided incident start date.

    • actualIncidentStartDate (datetime) --

      Response element for GetCase that provides the actual incident start date as identified by data analysis during the investigation.

    • impactedAwsRegions (list) --

      Response element for GetCase that provides the impacted regions.

      • (dict) --

        • region (string) --

    • threatActorIpAddresses (list) --

      Response element for GetCase that provides a list of suspicious IP addresses associated with unauthorized activity.

      • (dict) --

        • ipAddress (string) --

        • userAgent (string) --

    • pendingAction (string) --

      Response element for GetCase that provides identifies the case is waiting on customer input.

    • impactedAccounts (list) --

      Response element for GetCase that provides a list of impacted accounts.

      • (string) --

    • watchers (list) --

      Response element for GetCase that provides a list of Watchers added to the case.

      • (dict) --

        • email (string) --

        • name (string) --

        • jobTitle (string) --

    • createdDate (datetime) --

      Response element for GetCase that provides the date the case was created.

    • lastUpdatedDate (datetime) --

      Response element for GetCase that provides the date a case was last modified.

    • closureCode (string) --

      Response element for GetCase that provides the summary code for why a case was closed.

    • resolverType (string) --

      Response element for GetCase that provides the current resolver types. Options include self-supported | AWS-supported.

    • impactedServices (list) --

      Response element for GetCase that provides a list of impacted services.

      • (string) --

    • caseAttachments (list) --

      Response element for GetCase that provides a list of current case attachments.

      • (dict) --

        • attachmentId (string) --

        • fileName (string) --

        • attachmentStatus (string) --

        • creator (string) --

        • createdDate (datetime) --

    • closedDate (datetime) --

      Response element for GetCase that provides the date a specified case was closed.

GetMembership (updated) Link ¶
Changes (response)
{'region': ['ap-southeast-7', 'mx-central-1']}

Grants permission to get details of a designated service membership.

See also: AWS API Documentation

Request Syntax

client.get_membership(
    membershipId='string'
)
type membershipId:

string

param membershipId:

[REQUIRED]

Required element for GetMembership to identify the membership ID to query.

rtype:

dict

returns:

Response Syntax

{
    'membershipId': 'string',
    'accountId': 'string',
    'region': 'af-south-1'|'ap-east-1'|'ap-northeast-1'|'ap-northeast-2'|'ap-northeast-3'|'ap-south-1'|'ap-south-2'|'ap-southeast-1'|'ap-southeast-2'|'ap-southeast-3'|'ap-southeast-4'|'ap-southeast-5'|'ap-southeast-7'|'ca-central-1'|'ca-west-1'|'cn-north-1'|'cn-northwest-1'|'eu-central-1'|'eu-central-2'|'eu-north-1'|'eu-south-1'|'eu-south-2'|'eu-west-1'|'eu-west-2'|'eu-west-3'|'il-central-1'|'me-central-1'|'me-south-1'|'mx-central-1'|'sa-east-1'|'us-east-1'|'us-east-2'|'us-west-1'|'us-west-2',
    'membershipName': 'string',
    'membershipArn': 'string',
    'membershipStatus': 'Active'|'Cancelled'|'Terminated',
    'membershipActivationTimestamp': datetime(2015, 1, 1),
    'membershipDeactivationTimestamp': datetime(2015, 1, 1),
    'customerType': 'Standalone'|'Organization',
    'numberOfAccountsCovered': 123,
    'incidentResponseTeam': [
        {
            'name': 'string',
            'jobTitle': 'string',
            'email': 'string'
        },
    ],
    'optInFeatures': [
        {
            'featureName': 'Triage',
            'isEnabled': True|False
        },
    ]
}

Response Structure

  • (dict) --

    • membershipId (string) --

      Response element for GetMembership that provides the queried membership ID.

    • accountId (string) --

      Response element for GetMembership that provides the configured account for managing the membership.

    • region (string) --

      Response element for GetMembership that provides the configured region for managing the membership.

    • membershipName (string) --

      Response element for GetMembership that provides the configured membership name.

    • membershipArn (string) --

      Response element for GetMembership that provides the membership ARN.

    • membershipStatus (string) --

      Response element for GetMembership that provides the current membership status.

    • membershipActivationTimestamp (datetime) --

      Response element for GetMembership that provides the configured membership activation timestamp.

    • membershipDeactivationTimestamp (datetime) --

      Response element for GetMembership that provides the configured membership name deactivation timestamp.

    • customerType (string) --

      Response element for GetMembership that provides the configured membership type. Options include Standalone | Organizations.

    • numberOfAccountsCovered (integer) --

      Response element for GetMembership that provides the number of accounts in the membership.

    • incidentResponseTeam (list) --

      Response element for GetMembership that provides the configured membership incident response team members.

      • (dict) --

        • name (string) --

        • jobTitle (string) --

        • email (string) --

    • optInFeatures (list) --

      Response element for GetMembership that provides the if opt-in features have been enabled.

      • (dict) --

        • featureName (string) --

        • isEnabled (boolean) --

ListMemberships (updated) Link ¶
Changes (response)
{'items': {'region': ['ap-southeast-7', 'mx-central-1']}}

Grants permission to query the memberships a principal has access to.

See also: AWS API Documentation

Request Syntax

client.list_memberships(
    nextToken='string',
    maxResults=123
)
type nextToken:

string

param nextToken:

Optional element.

type maxResults:

integer

param maxResults:

Request element for ListMemberships to limit the number of responses.

rtype:

dict

returns:

Response Syntax

{
    'nextToken': 'string',
    'items': [
        {
            'membershipId': 'string',
            'accountId': 'string',
            'region': 'af-south-1'|'ap-east-1'|'ap-northeast-1'|'ap-northeast-2'|'ap-northeast-3'|'ap-south-1'|'ap-south-2'|'ap-southeast-1'|'ap-southeast-2'|'ap-southeast-3'|'ap-southeast-4'|'ap-southeast-5'|'ap-southeast-7'|'ca-central-1'|'ca-west-1'|'cn-north-1'|'cn-northwest-1'|'eu-central-1'|'eu-central-2'|'eu-north-1'|'eu-south-1'|'eu-south-2'|'eu-west-1'|'eu-west-2'|'eu-west-3'|'il-central-1'|'me-central-1'|'me-south-1'|'mx-central-1'|'sa-east-1'|'us-east-1'|'us-east-2'|'us-west-1'|'us-west-2',
            'membershipArn': 'string',
            'membershipStatus': 'Active'|'Cancelled'|'Terminated'
        },
    ]
}

Response Structure

  • (dict) --

    • nextToken (string) --

      Optional element.

    • items (list) --

      Request element for ListMemberships including the accountID, membershipARN, membershipID, membershipStatus, and region for each response.

      • (dict) --

        • membershipId (string) --

        • accountId (string) --

        • region (string) --

        • membershipArn (string) --

        • membershipStatus (string) --

UpdateCase (updated) Link ¶
Changes (request)
{'impactedAwsRegionsToAdd': {'region': ['ap-southeast-7', 'mx-central-1']},
 'impactedAwsRegionsToDelete': {'region': ['ap-southeast-7', 'mx-central-1']}}

Grants permission to update an existing case.

See also: AWS API Documentation

Request Syntax

client.update_case(
    caseId='string',
    title='string',
    description='string',
    reportedIncidentStartDate=datetime(2015, 1, 1),
    actualIncidentStartDate=datetime(2015, 1, 1),
    engagementType='Security Incident'|'Investigation',
    watchersToAdd=[
        {
            'email': 'string',
            'name': 'string',
            'jobTitle': 'string'
        },
    ],
    watchersToDelete=[
        {
            'email': 'string',
            'name': 'string',
            'jobTitle': 'string'
        },
    ],
    threatActorIpAddressesToAdd=[
        {
            'ipAddress': 'string',
            'userAgent': 'string'
        },
    ],
    threatActorIpAddressesToDelete=[
        {
            'ipAddress': 'string',
            'userAgent': 'string'
        },
    ],
    impactedServicesToAdd=[
        'string',
    ],
    impactedServicesToDelete=[
        'string',
    ],
    impactedAwsRegionsToAdd=[
        {
            'region': 'af-south-1'|'ap-east-1'|'ap-northeast-1'|'ap-northeast-2'|'ap-northeast-3'|'ap-south-1'|'ap-south-2'|'ap-southeast-1'|'ap-southeast-2'|'ap-southeast-3'|'ap-southeast-4'|'ap-southeast-5'|'ap-southeast-7'|'ca-central-1'|'ca-west-1'|'cn-north-1'|'cn-northwest-1'|'eu-central-1'|'eu-central-2'|'eu-north-1'|'eu-south-1'|'eu-south-2'|'eu-west-1'|'eu-west-2'|'eu-west-3'|'il-central-1'|'me-central-1'|'me-south-1'|'mx-central-1'|'sa-east-1'|'us-east-1'|'us-east-2'|'us-west-1'|'us-west-2'
        },
    ],
    impactedAwsRegionsToDelete=[
        {
            'region': 'af-south-1'|'ap-east-1'|'ap-northeast-1'|'ap-northeast-2'|'ap-northeast-3'|'ap-south-1'|'ap-south-2'|'ap-southeast-1'|'ap-southeast-2'|'ap-southeast-3'|'ap-southeast-4'|'ap-southeast-5'|'ap-southeast-7'|'ca-central-1'|'ca-west-1'|'cn-north-1'|'cn-northwest-1'|'eu-central-1'|'eu-central-2'|'eu-north-1'|'eu-south-1'|'eu-south-2'|'eu-west-1'|'eu-west-2'|'eu-west-3'|'il-central-1'|'me-central-1'|'me-south-1'|'mx-central-1'|'sa-east-1'|'us-east-1'|'us-east-2'|'us-west-1'|'us-west-2'
        },
    ],
    impactedAccountsToAdd=[
        'string',
    ],
    impactedAccountsToDelete=[
        'string',
    ]
)
type caseId:

string

param caseId:

[REQUIRED]

Required element for UpdateCase to identify the case ID for updates.

type title:

string

param title:

Optional element for UpdateCase to provide content for the title field.

type description:

string

param description:

Optional element for UpdateCase to provide content for the description field.

type reportedIncidentStartDate:

datetime

param reportedIncidentStartDate:

Optional element for UpdateCase to provide content for the customer reported incident start date field.

type actualIncidentStartDate:

datetime

param actualIncidentStartDate:

Optional element for UpdateCase to provide content for the incident start date field.

type engagementType:

string

param engagementType:

Optional element for UpdateCase to provide content for the engagement type field. Available engagement types include Security Incident | Investigation.

type watchersToAdd:

list

param watchersToAdd:

Optional element for UpdateCase to provide content to add additional watchers to a case.

  • (dict) --

    • email (string) -- [REQUIRED]

    • name (string) --

    • jobTitle (string) --

type watchersToDelete:

list

param watchersToDelete:

Optional element for UpdateCase to provide content to remove existing watchers from a case.

  • (dict) --

    • email (string) -- [REQUIRED]

    • name (string) --

    • jobTitle (string) --

type threatActorIpAddressesToAdd:

list

param threatActorIpAddressesToAdd:

Optional element for UpdateCase to provide content to add additional suspicious IP addresses related to a case.

  • (dict) --

    • ipAddress (string) -- [REQUIRED]

    • userAgent (string) --

type threatActorIpAddressesToDelete:

list

param threatActorIpAddressesToDelete:

Optional element for UpdateCase to provide content to remove suspicious IP addresses from a case.

  • (dict) --

    • ipAddress (string) -- [REQUIRED]

    • userAgent (string) --

type impactedServicesToAdd:

list

param impactedServicesToAdd:

Optional element for UpdateCase to provide content to add services impacted.

  • (string) --

type impactedServicesToDelete:

list

param impactedServicesToDelete:

Optional element for UpdateCase to provide content to remove services impacted.

  • (string) --

type impactedAwsRegionsToAdd:

list

param impactedAwsRegionsToAdd:

Optional element for UpdateCase to provide content to add regions impacted.

  • (dict) --

    • region (string) -- [REQUIRED]

type impactedAwsRegionsToDelete:

list

param impactedAwsRegionsToDelete:

Optional element for UpdateCase to provide content to remove regions impacted.

  • (dict) --

    • region (string) -- [REQUIRED]

type impactedAccountsToAdd:

list

param impactedAccountsToAdd:

Optional element for UpdateCase to provide content to add accounts impacted.

  • (string) --

type impactedAccountsToDelete:

list

param impactedAccountsToDelete:

Optional element for UpdateCase to provide content to add accounts impacted.

  • (string) --

rtype:

dict

returns:

Response Syntax

{}

Response Structure

  • (dict) --