guardduty_list_findings
List AWS GuardDuty security findings by detector, with optional filtering by severity or specific IDs. Retrieve finding IDs to analyze security threats in your AWS environment.
Instructions
List GuardDuty finding IDs for a given detector.
Optionally, you can supply a list of finding IDs to retrieve specific findings or a minimum severity threshold to filter findings.
Parameters:
aws_region (str): The AWS region - use 'us-east-1' if not specified.
detector_id (str): The GuardDuty detector ID.
finding_ids (list, optional): Specific finding IDs to query.
severity_threshold (float, optional): If provided, returns only findings with severity greater than this value.
<IMPORTANT>
After calling this tool, you should call guardduty_get_findings multiple times with the finding_ids returned by this tool.
</IMPORTANT>
Returns:
str: JSON-formatted list of finding IDs.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| aws_region | Yes | ||
| detector_id | Yes | ||
| finding_ids | No | ||
| severity_threshold | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- server.py:568-614 (handler)The handler function for the 'guardduty_list_findings' tool. It is registered via the @mcp.tool() decorator and implements the core logic to list GuardDuty findings for a specified detector using the AWS boto3 SDK. The function signature and docstring define the input schema and output format.
@mcp.tool() async def guardduty_list_findings( aws_region: str, detector_id: str, finding_ids: list = None, severity_threshold: float = None ) -> str: """ List GuardDuty finding IDs for a given detector. Optionally, you can supply a list of finding IDs to retrieve specific findings or a minimum severity threshold to filter findings. Parameters: aws_region (str): The AWS region - use 'us-east-1' if not specified. detector_id (str): The GuardDuty detector ID. finding_ids (list, optional): Specific finding IDs to query. severity_threshold (float, optional): If provided, returns only findings with severity greater than this value. <IMPORTANT> After calling this tool, you should call guardduty_get_findings multiple times with the finding_ids returned by this tool. </IMPORTANT> Returns: str: JSON-formatted list of finding IDs. """ try: client = boto3.client('guardduty', region_name=aws_region) params = {} if finding_ids: params["FindingIds"] = finding_ids if severity_threshold is not None: # Apply a filter criterion for severity greater than the threshold. params["FindingCriteria"] = { "Criterion": { "severity": { "Gt": int(severity_threshold) } } } response = client.list_findings( DetectorId=detector_id, **params ) findings = response.get("FindingIds", []) return json.dumps(findings, indent=2) except Exception as e: return f"Error listing GuardDuty findings: {str(e)}"