[CL4B] GuardDuty Basics Scenario in Python

.doc_gen/metadata/guardduty_metadata.yaml

@@ -0,0 +1,158 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# GuardDuty code examples for the SDK for Python.
+guardduty_Hello:
+  title: Hello &GD;
+  title_abbrev: Hello &GD;
+  synopsis: get started using &GD;.
+  category: Hello
+  languages:
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/guardduty
+          excerpts:
+            - description:
+              snippet_tags:
+                - python.example_code.guardduty.Hello
+  services:
+    guardduty: {ListDetectors}
+guardduty_CreateDetector:
+  title: Create a &GD; detector using an &AWS; SDK
+  title_abbrev: Create a detector
+  synopsis: create a &GD; detector.
+  category: Actions
+  languages:
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/guardduty
+          excerpts:
+            - description:
+              snippet_tags:
+                - python.example_code.guardduty.GuardDutyWrapper.decl
+                - python.example_code.guardduty.CreateDetector
+  services:
+    guardduty: {CreateDetector}
+guardduty_GetDetector:
+  title: Get a &GD; detector using an &AWS; SDK
+  title_abbrev: Get a detector
+  synopsis: get a &GD; detector.
+  category: Actions
+  languages:
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/guardduty
+          excerpts:
+            - description:
+              snippet_tags:
+                - python.example_code.guardduty.GuardDutyWrapper.decl
+                - python.example_code.guardduty.GetDetector
+  services:
+    guardduty: {GetDetector}
+guardduty_ListDetectors:
+  title: List &GD; detectors using an &AWS; SDK
+  title_abbrev: List detectors
+  synopsis: list &GD; detectors.
+  category: Actions
+  languages:
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/guardduty
+          excerpts:
+            - description:
+              snippet_tags:
+                - python.example_code.guardduty.GuardDutyWrapper.decl
+                - python.example_code.guardduty.ListDetectors
+  services:
+    guardduty: {ListDetectors}
+guardduty_CreateSampleFindings:
+  title: Create &GD; sample findings using an &AWS; SDK
+  title_abbrev: Create sample findings
+  synopsis: create &GD; sample findings.
+  category: Actions
+  languages:
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/guardduty
+          excerpts:
+            - description:
+              snippet_tags:
+                - python.example_code.guardduty.GuardDutyWrapper.decl
+                - python.example_code.guardduty.CreateSampleFindings
+  services:
+    guardduty: {CreateSampleFindings}
+guardduty_ListFindings:
+  title: List &GD; findings using an &AWS; SDK
+  title_abbrev: List findings
+  synopsis: list &GD; findings.
+  category: Actions
+  languages:
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/guardduty
+          excerpts:
+            - description:
+              snippet_tags:
+                - python.example_code.guardduty.GuardDutyWrapper.decl
+                - python.example_code.guardduty.ListFindings
+  services:
+    guardduty: {ListFindings}
+guardduty_GetFindings:
+  title: Get &GD; findings using an &AWS; SDK
+  title_abbrev: Get findings
+  synopsis: get &GD; findings.
+  category: Actions
+  languages:
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/guardduty
+          excerpts:
+            - description:
+              snippet_tags:
+                - python.example_code.guardduty.GuardDutyWrapper.decl
+                - python.example_code.guardduty.GetFindings
+  services:
+    guardduty: {GetFindings}
+guardduty_DeleteDetector:
+  title: Delete a &GD; detector using an &AWS; SDK
+  title_abbrev: Delete a detector
+  synopsis: delete a &GD; detector.
+  category: Actions
+  languages:
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/guardduty
+          excerpts:
+            - description:
+              snippet_tags:
+                - python.example_code.guardduty.GuardDutyWrapper.decl
+                - python.example_code.guardduty.DeleteDetector
+  services:
+    guardduty: {DeleteDetector}
+guardduty_Scenario:
+  title: Learn the basics of &GD; using an &AWS; SDK
+  title_abbrev: Learn the basics
+  synopsis: learn the basics of &GD;.
+  category: Scenarios
+  languages:
+    Python:
+      versions:
+        - sdk_version: 3
+          github: python/example_code/guardduty
+          excerpts:
+            - description: Create a wrapper class that encapsulates &GD; functions.
+              snippet_tags:
+                - python.example_code.guardduty.GuardDutyWrapper.class
+            - description: Use the wrapper class to run an interactive scenario at a command prompt.
+              snippet_tags:
+                - python.example_code.guardduty.GuardDutyScenario
+  services:
+    guardduty: {CreateDetector, GetDetector, ListDetectors, CreateSampleFindings, ListFindings, GetFindings, DeleteDetector}

python/example_code/guardduty/README.md

@@ -0,0 +1,115 @@
+# Amazon GuardDuty code examples for the SDK for Python
+
+## Overview
+
+Shows how to use the AWS SDK for Python (Boto3) to work with Amazon GuardDuty.
+
+<!--custom.overview.start-->
+<!--custom.overview.end-->
+
+_Amazon GuardDuty is a threat detection service that continuously monitors for malicious activity and unauthorized behavior to protect your AWS accounts and workloads._
+
+## ⚠ Important
+
+* Running this code might result in charges to your AWS account. For more details, see [AWS Pricing](https://aws.amazon.com/pricing/) and [Free Tier](https://aws.amazon.com/free/).
+* Running the tests might result in charges to your AWS account.
+* We recommend that you grant your code least privilege. At most, grant only the minimum permissions required to perform the task. For more information, see [Grant least privilege](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html#grant-least-privilege).
+* This code is not tested in every AWS Region. For more information, see [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services).
+
+<!--custom.important.start-->
+<!--custom.important.end-->
+
+## Code examples
+
+### Prerequisites
+
+For prerequisites, see the [README](../../README.md#Prerequisites) in the `python` folder.
+
+Install the packages required by these examples by running the following in a virtual environment:
+
+```
+python -m pip install -r requirements.txt
+```
+
+<!--custom.prerequisites.start-->
+<!--custom.prerequisites.end-->
+
+### Get started
+
+- [Hello GuardDuty](guardduty_hello.py#L15) (`ListDetectors`)
+
+### Single actions
+
+Code excerpts that show you how to call individual service functions.
+
+- [CreateDetector](guardduty_wrapper.py#L35)
+- [CreateSampleFindings](guardduty_wrapper.py#L108)
+- [DeleteDetector](guardduty_wrapper.py#L189)
+- [GetDetector](guardduty_wrapper.py#L78)
+- [GetFindings](guardduty_wrapper.py#L162)
+- [ListDetectors](guardduty_wrapper.py#L56)
+- [ListFindings](guardduty_wrapper.py#L135)
+
+### Scenarios
+
+Code examples that show you how to accomplish a specific task by calling multiple functions within the same service.
+
+- [Learn the basics of GuardDuty](scenario_guardduty_basics.py)
+
+## Run the examples
+
+### Instructions
+
+
+<!--custom.instructions.start-->
+<!--custom.instructions.end-->
+
+#### Hello GuardDuty
+
+This example shows you how to get started using GuardDuty.
+
+```
+python guardduty_hello.py
+```
+
+
+#### Learn the basics of GuardDuty
+
+This example shows you how to do the following:
+
+* Create a GuardDuty detector to enable threat detection.
+* Generate sample findings for demonstration purposes.
+* List and examine findings by severity.
+* Delete the detector to clean up resources.
+
+```
+python scenario_guardduty_basics.py
+```
+
+### Tests
+
+⚠ Running tests might result in charges to your AWS account.
+
+
+To find instructions for running these tests, see the [README](../../README.md#Tests)
+in the `python` folder.
+
+
+
+<!--custom.tests.start-->
+<!--custom.tests.end-->
+
+## Additional resources
+
+- [Amazon GuardDuty User Guide](https://docs.aws.amazon.com/guardduty/latest/ug/what-is-guardduty.html)
+- [Amazon GuardDuty API Reference](https://docs.aws.amazon.com/guardduty/latest/APIReference/Welcome.html)
+- [AWS SDK for Python (Boto3) GuardDuty reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/guardduty.html)
+
+<!--custom.resources.start-->
+<!--custom.resources.end-->
+
+---
+
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+SPDX-License-Identifier: Apache-2.0

python/example_code/guardduty/guardduty_hello.py

@@ -0,0 +1,63 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Purpose
+
+Shows how to use the AWS SDK for Python (Boto3) to get started with Amazon GuardDuty.
+This example demonstrates the most basic GuardDuty operation: listing existing detectors
+in the current region.
+"""
+
+import logging
+import boto3
+from botocore.exceptions import ClientError
+
+from guardduty_wrapper import GuardDutyWrapper
+
+
+# snippet-start:[python.example_code.guardduty.Hello]
+def hello_guardduty():
+    """
+    Use the AWS SDK for Python (Boto3) to check if GuardDuty is available
+    in the current region and list any existing detectors.
+    This function is typically used to verify GuardDuty service connectivity.
+    """
+    print("Hello, Amazon GuardDuty!")
+
+    try:
+        # Create GuardDuty wrapper
+        guardduty_wrapper = GuardDutyWrapper.from_client()
+
+        # List existing detectors
+        detector_ids = guardduty_wrapper.list_detectors()
+
+        if detector_ids:
+            print(f"Found {len(detector_ids)} GuardDuty detector(s) in this region:")
+            for detector_id in detector_ids:
+                print(f"  - {detector_id}")
+        else:
+            print("No GuardDuty detectors found in this region.")
+            print(
+                "You can create a detector to start using GuardDuty threat detection."
+            )
+
+    except ClientError as e:
+        error_code = e.response["Error"]["Code"]
+        if error_code == "AccessDeniedException":
+            print("Access denied. Please check your AWS credentials and permissions.")
+        elif error_code == "UnauthorizedOperation":
+            print(
+                "Unauthorized operation. Please ensure you have GuardDuty permissions."
+            )
+        else:
+            print(f"Error accessing GuardDuty: {e}")
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+
+
+# snippet-end:[python.example_code.guardduty.Hello]
+
+if __name__ == "__main__":
+    logging.basicConfig(level=logging.WARNING, format="%(levelname)s: %(message)s")
+    hello_guardduty()