2018/05/04 - Amazon GuardDuty - 5 new 1 updated api methods
Changes Amazon GuardDuty is adding five new API operations for creating and managing filters. For each filter, you can specify a criteria and an action. The action you specify is applied to findings that match the specified criteria.
Returns a paginated list of the current filters.
See also: AWS API Documentation
Request Syntax
client.list_filters(
DetectorId='string',
MaxResults=123,
NextToken='string'
)
string
[REQUIRED] The ID of the detector that specifies the GuardDuty service where you want to list filters.
integer
Indicates the maximum number of items that you want in the response. The maximum value is 50.
string
Paginates results. Set the value of this parameter to NULL on your first call to the ListFilters operation.For subsequent calls to the operation, fill nextToken in the request with the value of nextToken from the previous response to continue listing data.
dict
Response Syntax
{
'FilterNames': [
'string',
],
'NextToken': 'string'
}
Response Structure
(dict) -- 200 response
FilterNames (list) -- A list of filter names
(string) -- The unique identifier for a filter
NextToken (string) -- You can use this parameter when paginating results. Set the value of this parameter to null on your first call to the list action. For subsequent calls to the action fill nextToken in the request with the value of NextToken from the previous response to continue listing data.
Returns the details of the filter specified by the filter name.
See also: AWS API Documentation
Request Syntax
client.get_filter(
DetectorId='string',
FilterName='string'
)
string
[REQUIRED] The detector ID that specifies the GuardDuty service where you want to list the details of the specified filter.
string
[REQUIRED] The name of the filter whose details you want to get.
dict
Response Syntax
{
'Action': 'NOOP'|'ARCHIVE',
'Description': 'string',
'FindingCriteria': {
'Criterion': {
'string': {
'Eq': [
'string',
],
'Gt': 123,
'Gte': 123,
'Lt': 123,
'Lte': 123,
'Neq': [
'string',
]
}
}
},
'Name': 'string',
'Rank': 123
}
Response Structure
(dict) -- 200 response
Action (string) -- Specifies the action that is to be applied to the findings that match the filter.
Description (string) -- The description of the filter.
FindingCriteria (dict) -- Represents the criteria to be used in the filter for querying findings.
Criterion (dict) -- Represents a map of finding properties that match specified conditions and values when querying findings.
(string) --
(dict) -- Finding attribute (for example, accountId) for which conditions and values must be specified when querying findings.
Eq (list) -- Represents the equal condition to be applied to a single field when querying for findings.
(string) --
Gt (integer) -- Represents the greater than condition to be applied to a single field when querying for findings.
Gte (integer) -- Represents the greater than equal condition to be applied to a single field when querying for findings.
Lt (integer) -- Represents the less than condition to be applied to a single field when querying for findings.
Lte (integer) -- Represents the less than equal condition to be applied to a single field when querying for findings.
Neq (list) -- Represents the not equal condition to be applied to a single field when querying for findings.
(string) --
Name (string) -- The name of the filter.
Rank (integer) -- Specifies the position of the filter in the list of current filters. Also specifies the order in which this filter is applied to the findings.
Updates the filter specified by the filter name.
See also: AWS API Documentation
Request Syntax
client.update_filter(
Action='NOOP'|'ARCHIVE',
Description='string',
DetectorId='string',
FilterName='string',
FindingCriteria={
'Criterion': {
'string': {
'Eq': [
'string',
],
'Gt': 123,
'Gte': 123,
'Lt': 123,
'Lte': 123,
'Neq': [
'string',
]
}
}
},
Rank=123
)
string
Specifies the action that is to be applied to the findings that match the filter.
string
The description of the filter.
string
[REQUIRED] The unique ID of the detector that specifies the GuardDuty service where you want to update a filter.
string
[REQUIRED] The name of the filter.
dict
Represents the criteria to be used in the filter for querying findings.
Criterion (dict) -- Represents a map of finding properties that match specified conditions and values when querying findings.
(string) --
(dict) -- Finding attribute (for example, accountId) for which conditions and values must be specified when querying findings.
Eq (list) -- Represents the equal condition to be applied to a single field when querying for findings.
(string) --
Gt (integer) -- Represents the greater than condition to be applied to a single field when querying for findings.
Gte (integer) -- Represents the greater than equal condition to be applied to a single field when querying for findings.
Lt (integer) -- Represents the less than condition to be applied to a single field when querying for findings.
Lte (integer) -- Represents the less than equal condition to be applied to a single field when querying for findings.
Neq (list) -- Represents the not equal condition to be applied to a single field when querying for findings.
(string) --
integer
Specifies the position of the filter in the list of current filters. Also specifies the order in which this filter is applied to the findings.
dict
Response Syntax
{
'Name': 'string'
}
Response Structure
(dict) -- 200 response
Name (string) -- The name of the filter.
Deletes the filter specified by the filter name.
See also: AWS API Documentation
Request Syntax
client.delete_filter(
DetectorId='string',
FilterName='string'
)
string
[REQUIRED] The unique ID that specifies the detector where you want to delete a filter.
string
[REQUIRED] The name of the filter.
dict
Response Syntax
{}
Response Structure
(dict) -- 200 response
Creates a filter using the specified finding criteria.
See also: AWS API Documentation
Request Syntax
client.create_filter(
Action='NOOP'|'ARCHIVE',
ClientToken='string',
Description='string',
DetectorId='string',
FindingCriteria={
'Criterion': {
'string': {
'Eq': [
'string',
],
'Gt': 123,
'Gte': 123,
'Lt': 123,
'Lte': 123,
'Neq': [
'string',
]
}
}
},
Name='string',
Rank=123
)
string
Specifies the action that is to be applied to the findings that match the filter.
string
The idempotency token for the create request.This field is autopopulated if not provided.
string
The description of the filter.
string
[REQUIRED] The unique ID of the detector that you want to update.
dict
Represents the criteria to be used in the filter for querying findings.
Criterion (dict) -- Represents a map of finding properties that match specified conditions and values when querying findings.
(string) --
(dict) -- Finding attribute (for example, accountId) for which conditions and values must be specified when querying findings.
Eq (list) -- Represents the equal condition to be applied to a single field when querying for findings.
(string) --
Gt (integer) -- Represents the greater than condition to be applied to a single field when querying for findings.
Gte (integer) -- Represents the greater than equal condition to be applied to a single field when querying for findings.
Lt (integer) -- Represents the less than condition to be applied to a single field when querying for findings.
Lte (integer) -- Represents the less than equal condition to be applied to a single field when querying for findings.
Neq (list) -- Represents the not equal condition to be applied to a single field when querying for findings.
(string) --
string
The name of the filter.
integer
Specifies the position of the filter in the list of current filters. Also specifies the order in which this filter is applied to the findings.
dict
Response Syntax
{
'Name': 'string'
}
Response Structure
(dict) -- 200 response
Name (string) -- The name of the successfully created filter.
{'Findings': {'Resource': {'InstanceDetails': {'ImageDescription': 'string',
'NetworkInterfaces': {'NetworkInterfaceId': 'string'}}}}}
Describes Amazon GuardDuty findings specified by finding IDs.
See also: AWS API Documentation
Request Syntax
client.get_findings(
DetectorId='string',
FindingIds=[
'string',
],
SortCriteria={
'AttributeName': 'string',
'OrderBy': 'ASC'|'DESC'
}
)
string
[REQUIRED] The ID of the detector that specifies the GuardDuty service whose findings you want to retrieve.
list
IDs of the findings that you want to retrieve.
(string) -- The unique identifier for the Finding
dict
Represents the criteria used for sorting findings.
AttributeName (string) -- Represents the finding attribute (for example, accountId) by which to sort findings.
OrderBy (string) -- Order by which the sorted findings are to be displayed.
dict
Response Syntax
{
'Findings': [
{
'AccountId': 'string',
'Arn': 'string',
'Confidence': 123.0,
'CreatedAt': 'string',
'Description': 'string',
'Id': 'string',
'Partition': 'string',
'Region': 'string',
'Resource': {
'AccessKeyDetails': {
'AccessKeyId': 'string',
'PrincipalId': 'string',
'UserName': 'string',
'UserType': 'string'
},
'InstanceDetails': {
'AvailabilityZone': 'string',
'IamInstanceProfile': {
'Arn': 'string',
'Id': 'string'
},
'ImageDescription': 'string',
'ImageId': 'string',
'InstanceId': 'string',
'InstanceState': 'string',
'InstanceType': 'string',
'LaunchTime': 'string',
'NetworkInterfaces': [
{
'Ipv6Addresses': [
'string',
],
'NetworkInterfaceId': 'string',
'PrivateDnsName': 'string',
'PrivateIpAddress': 'string',
'PrivateIpAddresses': [
{
'PrivateDnsName': 'string',
'PrivateIpAddress': 'string'
},
],
'PublicDnsName': 'string',
'PublicIp': 'string',
'SecurityGroups': [
{
'GroupId': 'string',
'GroupName': 'string'
},
],
'SubnetId': 'string',
'VpcId': 'string'
},
],
'Platform': 'string',
'ProductCodes': [
{
'Code': 'string',
'ProductType': 'string'
},
],
'Tags': [
{
'Key': 'string',
'Value': 'string'
},
]
},
'ResourceType': 'string'
},
'SchemaVersion': 'string',
'Service': {
'Action': {
'ActionType': 'string',
'AwsApiCallAction': {
'Api': 'string',
'CallerType': 'string',
'DomainDetails': {},
'RemoteIpDetails': {
'City': {
'CityName': 'string'
},
'Country': {
'CountryCode': 'string',
'CountryName': 'string'
},
'GeoLocation': {
'Lat': 123.0,
'Lon': 123.0
},
'IpAddressV4': 'string',
'Organization': {
'Asn': 'string',
'AsnOrg': 'string',
'Isp': 'string',
'Org': 'string'
}
},
'ServiceName': 'string'
},
'DnsRequestAction': {
'Domain': 'string'
},
'NetworkConnectionAction': {
'Blocked': True|False,
'ConnectionDirection': 'string',
'LocalPortDetails': {
'Port': 123,
'PortName': 'string'
},
'Protocol': 'string',
'RemoteIpDetails': {
'City': {
'CityName': 'string'
},
'Country': {
'CountryCode': 'string',
'CountryName': 'string'
},
'GeoLocation': {
'Lat': 123.0,
'Lon': 123.0
},
'IpAddressV4': 'string',
'Organization': {
'Asn': 'string',
'AsnOrg': 'string',
'Isp': 'string',
'Org': 'string'
}
},
'RemotePortDetails': {
'Port': 123,
'PortName': 'string'
}
},
'PortProbeAction': {
'Blocked': True|False,
'PortProbeDetails': [
{
'LocalPortDetails': {
'Port': 123,
'PortName': 'string'
},
'RemoteIpDetails': {
'City': {
'CityName': 'string'
},
'Country': {
'CountryCode': 'string',
'CountryName': 'string'
},
'GeoLocation': {
'Lat': 123.0,
'Lon': 123.0
},
'IpAddressV4': 'string',
'Organization': {
'Asn': 'string',
'AsnOrg': 'string',
'Isp': 'string',
'Org': 'string'
}
}
},
]
}
},
'Archived': True|False,
'Count': 123,
'DetectorId': 'string',
'EventFirstSeen': 'string',
'EventLastSeen': 'string',
'ResourceRole': 'string',
'ServiceName': 'string',
'UserFeedback': 'string'
},
'Severity': 123.0,
'Title': 'string',
'Type': 'string',
'UpdatedAt': 'string'
},
]
}
Response Structure
(dict) -- 200 response
Findings (list) -- A list of findings.
(dict) -- Representation of a abnormal or suspicious activity.
AccountId (string) -- AWS account ID where the activity occurred that prompted GuardDuty to generate a finding.
Arn (string) -- The ARN of a finding described by the action.
Confidence (float) -- The confidence level of a finding.
CreatedAt (string) -- The time stamp at which a finding was generated.
Description (string) -- The description of a finding.
Id (string) -- The identifier that corresponds to a finding described by the action.
Partition (string) -- The AWS resource partition.
Region (string) -- The AWS region where the activity occurred that prompted GuardDuty to generate a finding.
Resource (dict) -- The AWS resource associated with the activity that prompted GuardDuty to generate a finding.
AccessKeyDetails (dict) -- The IAM access key details (IAM user information) of a user that engaged in the activity that prompted GuardDuty to generate a finding.
AccessKeyId (string) -- Access key ID of the user.
PrincipalId (string) -- The principal ID of the user.
UserName (string) -- The name of the user.
UserType (string) -- The type of the user.
InstanceDetails (dict) -- The information about the EC2 instance associated with the activity that prompted GuardDuty to generate a finding.
AvailabilityZone (string) -- The availability zone of the EC2 instance.
IamInstanceProfile (dict) -- The profile information of the EC2 instance.
Arn (string) -- AWS EC2 instance profile ARN.
Id (string) -- AWS EC2 instance profile ID.
ImageDescription (string) -- The image description of the EC2 instance.
ImageId (string) -- The image ID of the EC2 instance.
InstanceId (string) -- The ID of the EC2 instance.
InstanceState (string) -- The state of the EC2 instance.
InstanceType (string) -- The type of the EC2 instance.
LaunchTime (string) -- The launch time of the EC2 instance.
NetworkInterfaces (list) -- The network interface information of the EC2 instance.
(dict) -- The network interface information of the EC2 instance.
Ipv6Addresses (list) -- A list of EC2 instance IPv6 address information.
(string) -- IpV6 address of the EC2 instance.
NetworkInterfaceId (string) -- The ID of the network interface
PrivateDnsName (string) -- Private DNS name of the EC2 instance.
PrivateIpAddress (string) -- Private IP address of the EC2 instance.
PrivateIpAddresses (list) -- Other private IP address information of the EC2 instance.
(dict) -- Other private IP address information of the EC2 instance.
PrivateDnsName (string) -- Private DNS name of the EC2 instance.
PrivateIpAddress (string) -- Private IP address of the EC2 instance.
PublicDnsName (string) -- Public DNS name of the EC2 instance.
PublicIp (string) -- Public IP address of the EC2 instance.
SecurityGroups (list) -- Security groups associated with the EC2 instance.
(dict) -- Security groups associated with the EC2 instance.
GroupId (string) -- EC2 instance's security group ID.
GroupName (string) -- EC2 instance's security group name.
SubnetId (string) -- The subnet ID of the EC2 instance.
VpcId (string) -- The VPC ID of the EC2 instance.
Platform (string) -- The platform of the EC2 instance.
ProductCodes (list) -- The product code of the EC2 instance.
(dict) -- The product code of the EC2 instance.
Code (string) -- Product code information.
ProductType (string) -- Product code type.
Tags (list) -- The tags of the EC2 instance.
(dict) -- A tag of the EC2 instance.
Key (string) -- EC2 instance tag key.
Value (string) -- EC2 instance tag value.
ResourceType (string) -- The type of the AWS resource.
SchemaVersion (string) -- Findings' schema version.
Service (dict) -- Additional information assigned to the generated finding by GuardDuty.
Action (dict) -- Information about the activity described in a finding.
ActionType (string) -- GuardDuty Finding activity type.
AwsApiCallAction (dict) -- Information about the AWS_API_CALL action described in this finding.
Api (string) -- AWS API name.
CallerType (string) -- AWS API caller type.
DomainDetails (dict) -- Domain information for the AWS API call.
RemoteIpDetails (dict) -- Remote IP information of the connection.
City (dict) -- City information of the remote IP address.
CityName (string) -- City name of the remote IP address.
Country (dict) -- Country code of the remote IP address.
CountryCode (string) -- Country code of the remote IP address.
CountryName (string) -- Country name of the remote IP address.
GeoLocation (dict) -- Location information of the remote IP address.
Lat (float) -- Latitude information of remote IP address.
Lon (float) -- Longitude information of remote IP address.
IpAddressV4 (string) -- IPV4 remote address of the connection.
Organization (dict) -- ISP Organization information of the remote IP address.
Asn (string) -- Autonomous system number of the internet provider of the remote IP address.
AsnOrg (string) -- Organization that registered this ASN.
Isp (string) -- ISP information for the internet provider.
Org (string) -- Name of the internet provider.
ServiceName (string) -- AWS service name whose API was invoked.
DnsRequestAction (dict) -- Information about the DNS_REQUEST action described in this finding.
Domain (string) -- Domain information for the DNS request.
NetworkConnectionAction (dict) -- Information about the NETWORK_CONNECTION action described in this finding.
Blocked (boolean) -- Network connection blocked information.
ConnectionDirection (string) -- Network connection direction.
LocalPortDetails (dict) -- Local port information of the connection.
Port (integer) -- Port number of the local connection.
PortName (string) -- Port name of the local connection.
Protocol (string) -- Network connection protocol.
RemoteIpDetails (dict) -- Remote IP information of the connection.
City (dict) -- City information of the remote IP address.
CityName (string) -- City name of the remote IP address.
Country (dict) -- Country code of the remote IP address.
CountryCode (string) -- Country code of the remote IP address.
CountryName (string) -- Country name of the remote IP address.
GeoLocation (dict) -- Location information of the remote IP address.
Lat (float) -- Latitude information of remote IP address.
Lon (float) -- Longitude information of remote IP address.
IpAddressV4 (string) -- IPV4 remote address of the connection.
Organization (dict) -- ISP Organization information of the remote IP address.
Asn (string) -- Autonomous system number of the internet provider of the remote IP address.
AsnOrg (string) -- Organization that registered this ASN.
Isp (string) -- ISP information for the internet provider.
Org (string) -- Name of the internet provider.
RemotePortDetails (dict) -- Remote port information of the connection.
Port (integer) -- Port number of the remote connection.
PortName (string) -- Port name of the remote connection.
PortProbeAction (dict) -- Information about the PORT_PROBE action described in this finding.
Blocked (boolean) -- Port probe blocked information.
PortProbeDetails (list) -- A list of port probe details objects.
(dict) -- Details about the port probe finding.
LocalPortDetails (dict) -- Local port information of the connection.
Port (integer) -- Port number of the local connection.
PortName (string) -- Port name of the local connection.
RemoteIpDetails (dict) -- Remote IP information of the connection.
City (dict) -- City information of the remote IP address.
CityName (string) -- City name of the remote IP address.
Country (dict) -- Country code of the remote IP address.
CountryCode (string) -- Country code of the remote IP address.
CountryName (string) -- Country name of the remote IP address.
GeoLocation (dict) -- Location information of the remote IP address.
Lat (float) -- Latitude information of remote IP address.
Lon (float) -- Longitude information of remote IP address.
IpAddressV4 (string) -- IPV4 remote address of the connection.
Organization (dict) -- ISP Organization information of the remote IP address.
Asn (string) -- Autonomous system number of the internet provider of the remote IP address.
AsnOrg (string) -- Organization that registered this ASN.
Isp (string) -- ISP information for the internet provider.
Org (string) -- Name of the internet provider.
Archived (boolean) -- Indicates whether this finding is archived.
Count (integer) -- Total count of the occurrences of this finding type.
DetectorId (string) -- Detector ID for the GuardDuty service.
EventFirstSeen (string) -- First seen timestamp of the activity that prompted GuardDuty to generate this finding.
EventLastSeen (string) -- Last seen timestamp of the activity that prompted GuardDuty to generate this finding.
ResourceRole (string) -- Resource role information for this finding.
ServiceName (string) -- The name of the AWS service (GuardDuty) that generated a finding.
UserFeedback (string) -- Feedback left about the finding.
Severity (float) -- The severity of a finding.
Title (string) -- The title of a finding.
Type (string) -- The type of a finding described by the action.
UpdatedAt (string) -- The time stamp at which a finding was last updated.