AWS GuardDuty is a cloud-based threat detection service that monitors your AWS accounts and workloads for malicious or unauthorized activity. You can use AWS GuardDuty to detect and respond to threats such as compromised instances, reconnaissance, port scanning, denial of service attacks, and more. AWS GuardDuty can also integrate with other AWS services and third-party tools to automate your response actions.

To use the Python API, you must install the AWS SDK for Python (Boto3) and configure your credentials and region. You can find the installation and configuration instructions here. To use the CLI, you must install the AWS CLI version 2 and configure your credentials and region. You can find the installation and configuration instructions here.

To enable AWS GuardDuty, you can use the create_detector method in the Python API or the create-detector command in the CLI. For example:

Python

import boto3
client = boto3.client('guardduty')
response = client.create_detector(
Enable=True,
FindingPublishingFrequency='SIX_HOURS'
)
detector_id = response['DetectorId']
print(detector_id)

CLI

aws guardduty create-detector --enable --finding-publishing-frequency SIX_HOURS

This will create a detector with the default settings and return the detector ID. You can also specify other parameters such as tags, data sources, and delegated administrator. You can find the complete list of parameters here.

To list all the detectors in your account, you can use the list_detectors method in the Python API or the list-detectors command in the CLI. For example:

Python

import boto3
client = boto3.client('guardduty')
response = client.list_detectors()
detector_ids = response['DetectorIds']
print(detector_ids)

CLI

aws guardduty list-detectors

This will return a list of detector IDs. You can also use pagination tokens to retrieve more results if needed.

To get the details of a specific detector, you can use the get_detector method in the Python API or the get-detector command in the CLI. For example:

Python

import boto3
client = boto3.client('guardduty')
detector_id = '1234567890abcdef'
response = client.get_detector(
DetectorId=detector_id
)
print(response)

CLI

aws guardduty get-detector --detector-id 1234567890abcdef

This will return a dictionary or a JSON object with information such as status, creation time, tags, data sources, and finding publishing frequency.

To disable or delete a detector, you can use the update_detector method in the Python API or the update-detector command in the CLI to change its status to DISABLED and then use the delete_detector method or the delete-detector command to remove it. For example:

Python

import boto3
client = boto3.client('guardduty')
detector_id = '1234567890abcdef'
client.update_detector(
DetectorId=detector_id,
Enable=False
)
client.delete_detector(
DetectorId=detector_id
)

CLI

aws guardduty update-detector --detector-id 1234567890abcdef --no-enable
aws guardduty delete-detector --detector-id 1234567890abcdef

This will disable and delete the detector with the given ID. You can also specify other parameters, such as tags or data sources when updating a detector.

To view the findings generated by AWS GuardDuty, you can use the list_findings method in the Python API or the list-findings command in the CLI. For example:

Python

import boto3
client = boto3.client('guardduty')
detector_id = '1234567890abcdef'
response = client.list_findings(
DetectorId=detector_id
)
finding_ids = response['FindingIds']
print(finding_ids)

CLI

aws guardduty list-findings --detector-id 1234567890abcdef

This will return a list of finding IDs for the given detector. You can also use filters, sorting, and pagination to narrow your results.

You can use the get_findings method in the Python API or the get-findings command in the CLI to get the details of a specific finding. For example:

Python

import boto3
client = boto3.client('guardduty')
detector_id = '1234567890abcdef'
finding_ids = ['abcd1234efgh5678']
response = client.get_findings(
DetectorId=detector_id,
FindingIds=finding_ids
)
findings = response['Findings']
print(findings)

CLI

aws guardduty get-findings --detector-id 1234567890abcdef --finding-ids abcd1234efgh5678

This will return a list of dictionaries or JSON objects with information such as severity, type, description, resource, action, evidence, and recommendation.

To archive or unarchive a finding, you can use the update_findings_feedback method in the Python API or the update-findings-feedback command in the CLI. For example:

Python

import boto3
client = boto3.client('guardduty')
detector_id = '1234567890abcdef'
finding_ids = ['abcd1234efgh5678']
client.update_findings_feedback(
DetectorId=detector_id,
FindingIds=finding_ids,
Feedback='ARCHIVE'
)

CLI

aws guardduty update-findings-feedback --detector-id 1234567890abcdef --finding-ids abcd1234efgh5678 --feedback ARCHIVE

This will archive the finding with the given ID. You can also use the feedback value of ‘UNARCHIVE’ to unarchive a finding.

To create or update a filter for your findings, you can use the create_filter or update_filter methods in the Python API or the create-filter or update-filter commands in the CLI. For example:

Python

import boto3
client = boto3.client('guardduty')
detector_id = '1234567890abcdef'
filter_name = 'high-severity'
client.create_filter(
DetectorId=detector_id,
Name=filter_name,
Description='Filter for high severity findings',
Action='NOOP',
Rank=1,
FindingCriteria={
'Criterion': {
'severity': {
'Gte': 7
}
}
}
)

CLI

aws guardduty create-filter --detector-id 1234567890abcdef --name high-severity --description "Filter for high severity findings" --action NOOP --rank 1 --finding-criteria '{"Criterion": {"severity": {"Gte": 7}}}'

This will create a filter with the given name and criteria for the given detector. You can also specify other parameters, such as tags or client tokens. You can use the update_filter method or command to change the properties of an existing filter.

To list all the filters for your detector, you can use the list_filters method in the Python API or the list-filters command in the CLI. For example:

Python

import boto3
client = boto3.client('guardduty')
detector_id = '1234567890abcdef'
response = client.list_filters(
DetectorId=detector_id
)
filter_names = response['FilterNames']
print(filter_names)

CLI

aws guardduty list-filters --detector-id 1234567890abcdef

This will return a list of filter names for the given detector. You can also use pagination tokens to retrieve more results if needed.

To get the details of a specific filter, you can use the get_filter method in the Python API or the get-filter command in the CLI. For example:

Python

import boto3
client = boto3.client('guardduty')
detector_id = '1234567890abcdef'
filter_name = 'high-severity'
response = client.get_filter(
DetectorId=detector_id,
FilterName=filter_name
)
print(response)

CLI

aws guardduty get-filter --detector-id 1234567890abcdef --name high-severity

This will return a dictionary or a JSON object with information such as description, action, rank, and finding criteria.

You can use the delete_filter method in the Python API or the delete-filter command in the CLI to delete a filter. For example:

Python

import boto3
client = boto3.client('guardduty')
detector_id = '1234567890abcdef'
filter_name = 'high-severity'
client.delete_filter(
DetectorId=detector_id,
FilterName=filter_name
)

CLI

aws guardduty delete-filter --detector-id 1234567890abcdef --name high-severity

This will delete the filter with the given name from the given detector.

To create or update an IP set or a threat intel set for your detector, you can use the create_ip_set or create_threat_intel_set methods in the Python API or the create-ip-set or create-threat-intel-set commands in the CLI. For example:

Python

import boto3
client = boto3.client('guardduty')
detector_id = '1234567890abcdef'
ip_set_name = 'trusted-ips'
ip_set_location = 's3://my-bucket/trusted-ips.txt'
client.create_ip_set(
DetectorId=detector_id,
Name=ip_set_name,
Location=ip_set_location,
Activate=True,
Format='TXT'
)

CLI

aws guardduty create-ip-set --detector-id 1234567890abcdef --name trusted-ips --location s3://my-b

Exploring the Full Spectrum of AWS Services