Amazon GuardDuty

Enables a custom detection rule for your account by creating an association. You specify the rule and the mode in which it operates.

See also: AWS API Documentation

Request Syntax

client.create_custom_detection_rule_association(
    RuleId='string',
    Mode='LIVE'|'DRY_RUN',
    ClientToken='string',
    Tags={
        'string': 'string'
    }
)

type RuleId:

string

param RuleId:

[REQUIRED]

The unique identifier for the custom detection rule.

type Mode:

string

param Mode:

[REQUIRED]

The rule execution mode. Valid values: LIVE | DRY_RUN.

type ClientToken:

string

param ClientToken:

A unique, case-sensitive identifier to ensure that the operation completes no more than one time. Maximum 64 characters.

This field is autopopulated if not provided.

type Tags:

dict

param Tags:

The tags to be added to the new custom detection rule association resource.

• (string) --

  • (string) --

rtype:

dict

returns:

Response Syntax

{
    'RuleAssociation': {
        'AssociationId': 'string',
        'Arn': 'string',
        'RuleId': 'string',
        'AccountId': 'string',
        'Mode': 'LIVE'|'DRY_RUN',
        'CreatedAt': datetime(2015, 1, 1),
        'UpdatedAt': datetime(2015, 1, 1),
        'ExpiresAt': datetime(2015, 1, 1)
    }
}

Response Structure

• (dict) --

  • RuleAssociation (dict) --

    The details of the newly created custom detection rule association.

    • AssociationId (string) --

      The unique identifier for the association.

    • Arn (string) --

      The Amazon Resource Name (ARN) of the association.

    • RuleId (string) --

      The unique identifier for the custom detection rule.

    • AccountId (string) --

      The Amazon Web Services account ID associated with this rule association.

    • Mode (string) --

      The rule execution mode. Valid values: LIVE | DRY_RUN.

    • CreatedAt (datetime) --

      The timestamp when the association was created.

    • UpdatedAt (datetime) --

      The timestamp when the association was last updated.

    • ExpiresAt (datetime) --

      The timestamp when the association expires.

Updates the organization-level configuration for a custom detection rule, including the mode and include/exclude account lists.

See also: AWS API Documentation

Request Syntax

client.update_custom_detection_rule_org_configuration(
    RuleId='string',
    Mode='LIVE'|'DRY_RUN',
    IncludeAccountIds=[
        'string',
    ],
    ExcludeAccountIds=[
        'string',
    ]
)

type RuleId:

string

param RuleId:

[REQUIRED]

The unique identifier for the custom detection rule.

type Mode:

string

param Mode:

[REQUIRED]

The execution mode of the organization configuration. Valid values: LIVE | DRY_RUN.

type IncludeAccountIds:

list

param IncludeAccountIds:

The account IDs to include in the organization configuration. Mutually exclusive with ExcludeAccountIds.

• (string) --

type ExcludeAccountIds:

list

param ExcludeAccountIds:

The account IDs to exclude from the organization configuration. Mutually exclusive with IncludeAccountIds.

• (string) --

rtype:

dict

returns:

Response Syntax

{}

Response Structure

• (dict) --

Creates an organization-level configuration that enables a custom detection rule across your organization. This operation is available only to the delegated administrator account.

See also: AWS API Documentation

Request Syntax

client.create_custom_detection_rule_org_configuration(
    RuleId='string',
    Mode='LIVE'|'DRY_RUN',
    IncludeAccountIds=[
        'string',
    ],
    ExcludeAccountIds=[
        'string',
    ],
    ClientToken='string'
)

type RuleId:

string

param RuleId:

[REQUIRED]

The unique identifier for the custom detection rule.

type Mode:

string

param Mode:

[REQUIRED]

The execution mode of the organization configuration. Valid values: LIVE | DRY_RUN.

type IncludeAccountIds:

list

param IncludeAccountIds:

The account IDs to include in the organization configuration. Mutually exclusive with ExcludeAccountIds.

• (string) --

type ExcludeAccountIds:

list

param ExcludeAccountIds:

The account IDs to exclude from the organization configuration. Mutually exclusive with IncludeAccountIds.

• (string) --

type ClientToken:

string

param ClientToken:

A unique, case-sensitive identifier to ensure that the operation completes no more than one time.

This field is autopopulated if not provided.

rtype:

dict

returns:

Response Syntax

{}

Response Structure

• (dict) --

Deletes the organization-level configuration for a custom detection rule. This operation is available only to the delegated administrator account.

See also: AWS API Documentation

Request Syntax

client.delete_custom_detection_rule_org_configuration(
    RuleId='string',
    Mode='LIVE'|'DRY_RUN'
)

type RuleId:

string

param RuleId:

[REQUIRED]

The unique identifier for the custom detection rule.

type Mode:

string

param Mode:

[REQUIRED]

The execution mode of the organization configuration to delete. Valid values: LIVE | DRY_RUN.

rtype:

dict

returns:

Response Syntax

{}

Response Structure

• (dict) --

Returns details for a custom detection rule association.

See also: AWS API Documentation

Request Syntax

client.get_custom_detection_rule_association(
    RuleId='string',
    AssociationId='string'
)

type RuleId:

string

param RuleId:

[REQUIRED]

The unique identifier for the custom detection rule.

type AssociationId:

string

param AssociationId:

[REQUIRED]

The unique identifier for the association.

rtype:

dict

returns:

Response Syntax

{
    'RuleAssociation': {
        'AssociationId': 'string',
        'Arn': 'string',
        'RuleId': 'string',
        'AccountId': 'string',
        'Mode': 'LIVE'|'DRY_RUN',
        'CreatedAt': datetime(2015, 1, 1),
        'UpdatedAt': datetime(2015, 1, 1),
        'ExpiresAt': datetime(2015, 1, 1)
    },
    'Tags': {
        'string': 'string'
    }
}

Response Structure

• (dict) --

  • RuleAssociation (dict) --

    The details of the custom detection rule association.

    • AssociationId (string) --

      The unique identifier for the association.

    • Arn (string) --

      The Amazon Resource Name (ARN) of the association.

    • RuleId (string) --

      The unique identifier for the custom detection rule.

    • AccountId (string) --

      The Amazon Web Services account ID associated with this rule association.

    • Mode (string) --

      The rule execution mode. Valid values: LIVE | DRY_RUN.

    • CreatedAt (datetime) --

      The timestamp when the association was created.

    • UpdatedAt (datetime) --

      The timestamp when the association was last updated.

    • ExpiresAt (datetime) --

      The timestamp when the association expires.

  • Tags (dict) --

    The tags associated with the custom detection rule association resource.

    • (string) --

      • (string) --

Disables a custom detection rule by deleting its association. This operation is idempotent.

See also: AWS API Documentation

Request Syntax

client.delete_custom_detection_rule_association(
    RuleId='string',
    AssociationId='string'
)

type RuleId:

string

param RuleId:

[REQUIRED]

The unique identifier for the custom detection rule.

type AssociationId:

string

param AssociationId:

[REQUIRED]

The unique identifier for the association to delete.

rtype:

dict

returns:

Response Syntax

{}

Response Structure

• (dict) --

Returns details for a custom detection rule in GuardDuty, including its detection logic.

See also: AWS API Documentation

Request Syntax

client.get_custom_detection_rule(
    RuleId='string'
)

type RuleId:

string

param RuleId:

[REQUIRED]

The unique identifier for the custom detection rule.

rtype:

dict

returns:

Response Syntax

{
    'Rule': {
        'RuleId': 'string',
        'Arn': 'string',
        'Name': 'string',
        'Description': 'string',
        'Severity': 'CRITICAL'|'HIGH'|'MEDIUM'|'LOW',
        'DataSource': 'CloudTrailManagementEvent',
        'Tactic': 'string',
        'Technique': 'string',
        'Service': 'string',
        'Definition': {
            'Expression': 'string'
        },
        'Language': 'SQL',
        'Schema': 'CloudTrail',
        'CreatedAt': datetime(2015, 1, 1),
        'UpdatedAt': datetime(2015, 1, 1)
    }
}

Response Structure

• (dict) --

  • Rule (dict) --

    The details of the custom detection rule.

    • RuleId (string) --

      The unique identifier for the rule.

    • Arn (string) --

      The Amazon Resource Name (ARN) of the rule.

    • Name (string) --

      The display name of the rule.

    • Description (string) --

      A description of what the rule detects.

    • Severity (string) --

      The severity level assigned to findings generated by this rule.

    • DataSource (string) --

      The data source that the rule analyzes.

    • Tactic (string) --

      The MITRE ATT&CK tactic associated with the rule.

    • Technique (string) --

      The MITRE ATT&CK technique associated with the rule.

    • Service (string) --

      The Amazon Web Services service associated with the rule.

    • Definition (dict) --

      The detection logic definition for the rule.

      • Expression (string) --

        The detection logic expression for the rule.

    • Language (string) --

      The language used for the detection logic expression.

    • Schema (string) --

      The schema version used by the rule definition.

    • CreatedAt (datetime) --

      The timestamp when the rule was created.

    • UpdatedAt (datetime) --

      The timestamp when the rule was last updated.

Returns the organization-level configuration for a custom detection rule.

See also: AWS API Documentation

Request Syntax

client.get_custom_detection_rule_org_configuration(
    RuleId='string',
    Mode='LIVE'|'DRY_RUN'
)

type RuleId:

string

param RuleId:

[REQUIRED]

The unique identifier for the custom detection rule.

type Mode:

string

param Mode:

[REQUIRED]

The execution mode of the organization configuration to retrieve. Valid values: LIVE | DRY_RUN.

rtype:

dict

returns:

Response Syntax

{
    'Configuration': {
        'RuleId': 'string',
        'Mode': 'LIVE'|'DRY_RUN',
        'Status': 'ACTIVE'|'PROCESSING'|'FAILED',
        'StatusReason': 'string',
        'IncludeAccountIds': [
            'string',
        ],
        'ExcludeAccountIds': [
            'string',
        ],
        'CreatedAt': datetime(2015, 1, 1),
        'UpdatedAt': datetime(2015, 1, 1),
        'ExpiresAt': datetime(2015, 1, 1)
    }
}

Response Structure

• (dict) --

  • Configuration (dict) --

    The details of the organization configuration.

    • RuleId (string) --

      The unique identifier for the custom detection rule.

    • Mode (string) --

      The execution mode of the organization configuration. Valid values: LIVE | DRY_RUN.

    • Status (string) --

      The configuration status. Valid values: ACTIVE | PROCESSING | FAILED.

    • StatusReason (string) --

      The reason for the current configuration status.

    • IncludeAccountIds (list) --

      A list of member account IDs included in the organization configuration. Mutually exclusive with ExcludeAccountIds.

      • (string) --

    • ExcludeAccountIds (list) --

      A list of member account IDs excluded from the organization configuration. Mutually exclusive with IncludeAccountIds.

      • (string) --

    • CreatedAt (datetime) --

      The timestamp when the organization configuration was created.

    • UpdatedAt (datetime) --

      The timestamp when the organization configuration was last updated.

    • ExpiresAt (datetime) --

      The timestamp when the organization configuration expires.

Returns all available custom detection rules in GuardDuty. You can filter the results by data source, severity, tactic, technique, and service.

See also: AWS API Documentation

Request Syntax

client.list_custom_detection_rules(
    MaxResults=123,
    NextToken='string',
    Filters=[
        {
            'Name': 'name'|'description'|'dataSource'|'severity'|'tactic'|'technique'|'service',
            'Values': [
                'string',
            ],
            'Condition': 'EQUALS'|'CONTAINS'
        },
    ]
)

type MaxResults:

integer

param MaxResults:

The maximum number of results to return in a single page. Minimum value of 1, maximum value of 100.

type NextToken:

string

param NextToken:

A pagination token from a previous response. Use this token to retrieve the next page of results.

type Filters:

list

param Filters:

A list of filter criteria to apply when listing custom detection rules.

• (dict) --

  Contains filter criteria for listing custom detection rules or associations.

  • Name (string) -- [REQUIRED]

    The name of the field to filter by.

  • Values (list) -- [REQUIRED]

    The values to match against the specified filter name.

    • (string) --

  • Condition (string) --

    The condition to apply to the filter. For example, EQUALS or CONTAINS.

rtype:

dict

returns:

Response Syntax

{
    'Rules': [
        {
            'RuleId': 'string',
            'Arn': 'string',
            'Name': 'string',
            'Description': 'string',
            'Severity': 'CRITICAL'|'HIGH'|'MEDIUM'|'LOW',
            'DataSource': 'CloudTrailManagementEvent',
            'Tactic': 'string',
            'Technique': 'string',
            'Service': 'string',
            'Language': 'SQL',
            'Schema': 'CloudTrail',
            'CreatedAt': datetime(2015, 1, 1),
            'UpdatedAt': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string'
}

Response Structure

• (dict) --

  • Rules (list) --

    A list of custom detection rule summaries.

    • (dict) --

      Contains summary information about a custom detection rule.

      • RuleId (string) --

        The unique identifier for the rule.

      • Arn (string) --

        The Amazon Resource Name (ARN) of the rule.

      • Name (string) --

        The display name of the rule.

      • Description (string) --

        A description of what the rule detects.

      • Severity (string) --

        The severity level assigned to findings generated by this rule.

      • DataSource (string) --

        The data source that the rule analyzes.

      • Tactic (string) --

        The MITRE ATT&CK tactic associated with the rule.

      • Technique (string) --

        The MITRE ATT&CK technique associated with the rule.

      • Service (string) --

        The Amazon Web Services service associated with the rule.

      • Language (string) --

        The language used for the detection logic expression.

      • Schema (string) --

        The schema version used by the rule definition.

      • CreatedAt (datetime) --

        The timestamp when the rule was created.

      • UpdatedAt (datetime) --

        The timestamp when the rule was last updated.

  • NextToken (string) --

    A pagination token to retrieve the next page of results. If this field is empty, there are no additional results.

Returns all custom detection rule associations for your account. You can filter by rule ID and mode.

See also: AWS API Documentation

Request Syntax

client.list_custom_detection_rule_associations(
    MaxResults=123,
    NextToken='string',
    RuleId='string',
    Mode='LIVE'|'DRY_RUN'
)

type MaxResults:

integer

param MaxResults:

The maximum number of results to return in a single page. Minimum value of 1, maximum value of 100.

type NextToken:

string

param NextToken:

A pagination token from a previous response. Use this token to retrieve the next page of results.

type RuleId:

string

param RuleId:

The unique identifier for the custom detection rule to filter associations by.

type Mode:

string

param Mode:

The rule execution mode to filter associations by.

rtype:

dict

returns:

Response Syntax

{
    'RuleAssociations': [
        {
            'AssociationId': 'string',
            'Arn': 'string',
            'RuleId': 'string',
            'Mode': 'LIVE'|'DRY_RUN',
            'CreatedAt': datetime(2015, 1, 1),
            'UpdatedAt': datetime(2015, 1, 1),
            'ExpiresAt': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string'
}

Response Structure

• (dict) --

  • RuleAssociations (list) --

    A list of custom detection rule association summaries.

    • (dict) --

      Contains summary information about a custom detection rule association.

      • AssociationId (string) --

        The unique identifier for the association.

      • Arn (string) --

        The Amazon Resource Name (ARN) of the association.

      • RuleId (string) --

        The unique identifier for the custom detection rule.

      • Mode (string) --

        The rule execution mode. Valid values: LIVE | DRY_RUN.

      • CreatedAt (datetime) --

        The timestamp when the association was created.

      • UpdatedAt (datetime) --

        The timestamp when the association was last updated.

      • ExpiresAt (datetime) --

        The timestamp when the association expires.

  • NextToken (string) --

    A pagination token to retrieve the next page of results. If this field is empty, there are no additional results.

Updates the mode of an existing custom detection rule association.

See also: AWS API Documentation

Request Syntax

client.update_custom_detection_rule_association(
    RuleId='string',
    AssociationId='string',
    Mode='LIVE'|'DRY_RUN'
)

type RuleId:

string

param RuleId:

[REQUIRED]

The unique identifier for the custom detection rule.

type AssociationId:

string

param AssociationId:

[REQUIRED]

The unique identifier for the association to update.

type Mode:

string

param Mode:

[REQUIRED]

The rule execution mode. Valid values: LIVE | DRY_RUN.

rtype:

dict

returns:

Response Syntax

{}

Response Structure

• (dict) --

Returns all organization-level configurations for custom detection rules. You can filter the results by status.

See also: AWS API Documentation

Request Syntax

client.list_custom_detection_rule_org_configurations(
    MaxResults=123,
    NextToken='string',
    Status='ACTIVE'|'PROCESSING'|'FAILED'
)

type MaxResults:

integer

param MaxResults:

The maximum number of results to return in a single page. Minimum value of 1, maximum value of 100.

type NextToken:

string

param NextToken:

A pagination token from a previous response. Use this token to retrieve the next page of results.

type Status:

string

param Status:

The configuration status to filter by.

rtype:

dict

returns:

Response Syntax

{
    'Configurations': [
        {
            'RuleId': 'string',
            'Mode': 'LIVE'|'DRY_RUN',
            'Status': 'ACTIVE'|'PROCESSING'|'FAILED',
            'StatusReason': 'string',
            'CreatedAt': datetime(2015, 1, 1),
            'UpdatedAt': datetime(2015, 1, 1),
            'ExpiresAt': datetime(2015, 1, 1)
        },
    ],
    'NextToken': 'string'
}

Response Structure

• (dict) --

  • Configurations (list) --

    A list of organization configurations for custom detection rules.

    • (dict) --

      Contains summary information about an organization-level configuration for a custom detection rule.

      • RuleId (string) --

        The unique identifier for the custom detection rule.

      • Mode (string) --

        The rule execution mode.

      • Status (string) --

        The configuration status.

      • StatusReason (string) --

        The reason for the current configuration status.

      • CreatedAt (datetime) --

        The timestamp when the organization configuration was created.

      • UpdatedAt (datetime) --

        The timestamp when the organization configuration was last updated.

      • ExpiresAt (datetime) --

        The timestamp when the organization configuration expires.

  • NextToken (string) --

    A pagination token to retrieve the next page of results. If this field is empty, there are no additional results.