GuardDuty findings

Detector and filter operations run on the moto backend. The finding operations are implemented natively: CreateSampleFindings, ListFindings, GetFindings, ArchiveFindings, UnarchiveFindings, UpdateFindingsFeedback and GetFindingsStatistics, plus ListFilters. Findings are stored per account, region and detector, and survive PERSISTENCE=1 restarts. DeleteDetector removes the detector's findings.

Operation-level coverage: GuardDuty coverage matrix.

Sample findings

CreateSampleFindings generates schema-valid findings from the type string (<category>:<resourceClass>/<threatName>). Nine common types have real titles, descriptions and severities. Any other type gets a generic finding derived from the same convention. With no FindingTypes, one finding per known type is created. As in real AWS, sample findings do not refer to anything in your account.

$ DET=$(awsemu guardduty create-detector --enable --query DetectorId --output text)
$ awsemu guardduty create-sample-findings --detector-id $DET \
    --finding-types UnauthorizedAccess:IAMUser/InstanceCredentialExfiltration.OutsideAWS
$ awsemu guardduty list-findings --detector-id $DET \
    --finding-criteria '{"Criterion":{"severity":{"Gte":7}}}'

FindingCriteria works on any dotted field path (type, severity, service.archived, resource.resourceType, updatedAt and so on) with Eq, Neq, Equals, NotEquals, Gt, Gte, Lt, Lte (and the long names), Matches and NotMatches. Time fields compare as epoch milliseconds. SortCriteria and pagination (MaxResults, NextToken) are supported. A detector id that does not exist in the account and region returns BadRequestException.

Archive, feedback and statistics

ArchiveFindings and UnarchiveFindings set Service.Archived, so an auto-remediation function can archive what it handled and a query for service.archived = false returns only open findings. UpdateFindingsFeedback records USEFUL or NOT_USEFUL. GetFindingsStatistics returns COUNT_BY_SEVERITY and, with GroupBy, the grouped lists for account, date, finding type, resource or severity.

EventBridge delivery

Every sample finding is also published to the account's default event bus with source: aws.guardduty and detail-type: GuardDuty Finding. The event detail uses lowerCamelCase keys, as the real service does. A rule on that source can target SQS, Lambda or any other EventBridge target, so a GuardDuty to EventBridge to Lambda pipeline runs against the real API.

Known limitations

• •
  No real detection. Findings come only from CreateSampleFindings, which, as in AWS, produces generic findings that do not refer to anything in your account.
• •
  Other GuardDuty areas stay on the moto backend (detectors, filters, IP sets, members and so on), with whatever coverage moto has. See the coverage matrix for the exact operations.
• •
  Filters are not applied to findings. A filter with Action=ARCHIVE is stored but does not archive new findings automatically.