fix(aws): correct GuardDuty finding date fields (#2459)

### Type of change
<!-- Mark the relevant option with an "x" -->
- [x] Bug fix (non-breaking change that fixes an issue)
- [x] Documentation update


### Summary
This PR fixes GuardDuty finding timestamp ingestion so Cartography reads
first/last seen from the correct GuardDuty API path.

Changes included:
- Read `CreatedAt` and `UpdatedAt` from top-level finding payload into
`createdat`/`updatedat`.
- Read `Service.EventFirstSeen` and `Service.EventLastSeen` into
snake_case node fields: `eventfirstseen` and `eventlastseen`.
- Keep backward-compatible fallback to top-level
`EventFirstSeen`/`EventLastSeen` if present.
- Update GuardDuty unit/integration test fixtures and assertions.
- Update AWS schema docs for `GuardDutyFinding::Risk` fields.


### Checklist

#### General
- [x] I have read the [contributing
guidelines](https://cartography-cncf.github.io/cartography/dev/developer-guide.html).
- [ ] The linter passes locally (`make lint`).
- [x] I have added/updated tests that prove my fix is effective or my
feature works.

#### Proof of functionality
<!-- Provide at least one of the following to help reviewers verify your
changes: -->
- [ ] Screenshot showing the graph before and after changes.
- [x] New or updated unit/integration tests.

#### If you are adding or modifying a synced entity
- [x] Included Cartography sync logs from a real environment
demonstrating successful synchronization of the new/modified entity.
Logs should show:
  - The sync job starting and completing without errors
  - The number of nodes/relationships created or updated
  - Example:
    ```
INFO:cartography.intel.aws.guardduty:Loading <N> GuardDuty findings for
region us-east-1 into graph.
    INFO:cartography.util:Syncing GuardDuty findings completed.
    ```

#### If you are changing a node or relationship
- [x] Updated the [schema
documentation](https://github.com/cartography-cncf/cartography/tree/master/docs/root/modules).
- [ ] Updated the [schema
README](https://github.com/cartography-cncf/cartography/blob/master/docs/schema/README.md).

#### If you are implementing a new intel module
- [ ] Used the NodeSchema [data
model](https://cartography-cncf.github.io/cartography/dev/writing-intel-modules.html#defining-a-node).


### Notes for reviewers
- Scope is intentionally limited to GuardDuty findings field mapping and
docs/tests alignment.

---------

Signed-off-by: Kunaal Sikka <kunaal@subimage.io>

Author: kunaals

cartography/intel/aws/guardduty.py

@@ -168,6 +168,7 @@ def transform_findings(findings: list[dict[str, Any]]) -> list[dict[str, Any]]:
     """Transform GuardDuty findings from API response to schema format."""
     transformed: list[dict[str, Any]] = []
     for f in findings:
+        service = f.get("Service", {})
         item: dict[str, Any] = {
             "id": f["Id"],
             "arn": f.get("Arn"),
@@ -176,8 +177,16 @@ def transform_findings(findings: list[dict[str, Any]]) -> list[dict[str, Any]]:
             "title": f.get("Title"),
             "description": f.get("Description"),
             "confidence": f.get("Confidence"),
-            "eventfirstseen": f.get("EventFirstSeen"),
-            "eventlastseen": f.get("EventLastSeen"),
+            "createdat": f.get("CreatedAt"),
+            "updatedat": f.get("UpdatedAt"),
+            "eventfirstseen": service.get(
+                "EventFirstSeen",
+                f.get("EventFirstSeen"),
+            ),
+            "eventlastseen": service.get(
+                "EventLastSeen",
+                f.get("EventLastSeen"),
+            ),
             "accountid": f.get("AccountId"),
             "region": f.get("Region"),
             "detectorid": f.get("DetectorId"),

cartography/models/aws/guardduty/findings.py

@@ -21,6 +21,8 @@ class GuardDutyFindingNodeProperties(CartographyNodeProperties):
     type: PropertyRef = PropertyRef("type")
     severity: PropertyRef = PropertyRef("severity")
     confidence: PropertyRef = PropertyRef("confidence")
+    createdat: PropertyRef = PropertyRef("createdat")
+    updatedat: PropertyRef = PropertyRef("updatedat")
     eventfirstseen: PropertyRef = PropertyRef("eventfirstseen")
     eventlastseen: PropertyRef = PropertyRef("eventlastseen")
     accountid: PropertyRef = PropertyRef("accountid")

docs/root/modules/aws/schema.md

@@ -241,6 +241,8 @@ Representation of an AWS [GuardDuty Finding](https://docs.aws.amazon.com/guarddu
 | confidence | The confidence level that GuardDuty has in the accuracy of the finding |
 | title | A short description of the finding |
 | description | A more detailed description of the finding |
+| createdat | Timestamp when GuardDuty created the finding |
+| updatedat | Timestamp when GuardDuty last updated the finding |
 | eventfirstseen | Timestamp when the activity that prompted GuardDuty to generate this finding was first observed |
 | eventlastseen | Timestamp when the activity that prompted GuardDuty to generate this finding was last observed |
 | accountid | The ID of the AWS account in which the finding was generated |

tests/data/aws/guardduty.py

@@ -316,6 +316,8 @@
         "confidence": 7.5,
         "title": "EC2 instance is communicating with a malicious IP address",
         "description": "EC2 instance i-99999999 is communicating with a malicious IP address 198.51.100.1.",
+        "createdat": datetime(2023, 1, 15, 10, 30, 0),
+        "updatedat": datetime(2023, 1, 15, 10, 45, 0),
         "eventfirstseen": datetime(2023, 1, 15, 10, 30, 0),
         "eventlastseen": datetime(2023, 1, 15, 10, 45, 0),
         "accountid": "123456789012",
@@ -334,6 +336,8 @@
         "confidence": 8.0,
         "title": "S3 bucket is being enumerated from an unusual location",
         "description": "S3 bucket test-bucket is being enumerated from an unusual location.",
+        "createdat": datetime(2023, 1, 16, 14, 20, 0),
+        "updatedat": datetime(2023, 1, 16, 14, 35, 0),
         "eventfirstseen": datetime(2023, 1, 16, 14, 20, 0),
         "eventlastseen": datetime(2023, 1, 16, 14, 35, 0),
         "accountid": "123456789012",
@@ -352,6 +356,8 @@
         "confidence": 6.0,
         "title": "IAM user is making anomalous API calls",
         "description": "IAM user GeneratedFindingUserName is making anomalous API calls.",
+        "createdat": datetime(2023, 1, 17, 9, 15, 0),
+        "updatedat": datetime(2023, 1, 17, 9, 30, 0),
         "eventfirstseen": datetime(2023, 1, 17, 9, 15, 0),
         "eventlastseen": datetime(2023, 1, 17, 9, 30, 0),
         "accountid": "123456789012",

tests/integration/cartography/intel/aws/test_guardduty.py

@@ -130,6 +130,44 @@ def test_sync_guardduty_findings(
         # Note: S3Bucket finding with severity 5.0 excluded by HIGH threshold
     }
 
+    # Assert - Check that finding date fields were populated from the expected API paths
+    finding_dates = neo4j_session.run(
+        """
+        MATCH (f:GuardDutyFinding)
+        RETURN
+            f.id AS id,
+            toString(f.createdat) AS createdat,
+            toString(f.updatedat) AS updatedat,
+            toString(f.eventfirstseen) AS eventfirstseen,
+            toString(f.eventlastseen) AS eventlastseen
+        """,
+    ).data()
+    assert {
+        (
+            row["id"],
+            row["createdat"],
+            row["updatedat"],
+            row["eventfirstseen"],
+            row["eventlastseen"],
+        )
+        for row in finding_dates
+    } == {
+        (
+            "74b1234567890abcdef1234567890abcdef",
+            "2023-01-15T10:30:00",
+            "2023-01-15T10:45:00",
+            "2023-01-15T10:30:00",
+            "2023-01-15T10:45:00",
+        ),
+        (
+            "96d3456789012cdef3456789012cdef01",
+            "2023-01-17T09:15:00",
+            "2023-01-17T09:30:00",
+            "2023-01-17T09:15:00",
+            "2023-01-17T09:30:00",
+        ),
+    }
+
     # Assert - Check that GuardDuty detectors are connected to the AWSAccount
     assert check_rels(
         neo4j_session,

tests/unit/cartography/intel/aws/test_guardduty.py

@@ -1,3 +1,5 @@
+from datetime import datetime
+
 from cartography.intel.aws.guardduty import transform_findings
 from tests.data.aws.guardduty import EXPECTED_TRANSFORM_RESULTS
 from tests.data.aws.guardduty import GET_FINDINGS
@@ -25,3 +27,43 @@ def test_transform_findings():
     # Expected IAM AccessKey finding
     expected_iam_finding = EXPECTED_TRANSFORM_RESULTS[2]
     assert transformed[2] == expected_iam_finding
+
+
+def test_transform_findings_prefers_service_event_fields():
+    findings = [
+        {
+            "Id": "finding-prefers-service",
+            "CreatedAt": datetime(2024, 1, 1, 0, 0, 0),
+            "UpdatedAt": datetime(2024, 1, 1, 1, 0, 0),
+            "EventFirstSeen": datetime(2024, 1, 1, 2, 0, 0),
+            "EventLastSeen": datetime(2024, 1, 1, 3, 0, 0),
+            "Service": {
+                "EventFirstSeen": datetime(2024, 1, 1, 4, 0, 0),
+                "EventLastSeen": datetime(2024, 1, 1, 5, 0, 0),
+            },
+            "Resource": {"ResourceType": "AccessKey"},
+        }
+    ]
+
+    transformed = transform_findings(findings)
+
+    assert transformed[0]["eventfirstseen"] == datetime(2024, 1, 1, 4, 0, 0)
+    assert transformed[0]["eventlastseen"] == datetime(2024, 1, 1, 5, 0, 0)
+
+
+def test_transform_findings_falls_back_to_top_level_event_fields():
+    findings = [
+        {
+            "Id": "finding-fallback-top-level",
+            "CreatedAt": datetime(2024, 2, 1, 0, 0, 0),
+            "UpdatedAt": datetime(2024, 2, 1, 1, 0, 0),
+            "EventFirstSeen": datetime(2024, 2, 1, 2, 0, 0),
+            "EventLastSeen": datetime(2024, 2, 1, 3, 0, 0),
+            "Resource": {"ResourceType": "AccessKey"},
+        }
+    ]
+
+    transformed = transform_findings(findings)
+
+    assert transformed[0]["eventfirstseen"] == datetime(2024, 2, 1, 2, 0, 0)
+    assert transformed[0]["eventlastseen"] == datetime(2024, 2, 1, 3, 0, 0)