When “no detectors” is still valid evidence
My first fetcher in paramify-fetchers, and the question every fetcher has to answer: what does an empty result mean?
My first contribution to paramify-fetchers was a fetcher for AWS GuardDuty findings. The repo already had a fetcher for GuardDuty's detector configuration. This one lists the findings themselves, so threat-detection evidence shows what GuardDuty actually saw, not only that it was switched on. It maps to KSI-SVC-EIS and KSI-MLA-RVL.
A window, not a history
The fetcher lists each detector, asks for findings updated within a lookback window (seven days by default), and expands each one: severity, type, resource, account, region, and whether it has been archived. It finishes with a summary of counts by severity, by type, and active versus archived.
aws guardduty list-detectors
aws guardduty list-findings # updatedAt >= now - lookback_days
aws guardduty get-findings # full detail for each finding IDIt keeps no state between runs. Each run is a fresh snapshot of the window, so there's no local file to lose or carry between environments, and the evidence stays recent without anyone pruning it. Region and profile are optional targets, so the same fetcher fans out across accounts using whatever identity the runner already has. It holds no secrets of its own.
What does nothing mean?
The interesting decision was about empty results. There are three ways to get nothing back from GuardDuty:
- GuardDuty isn't enabled in the region, so there are no detectors.
- Detectors exist, but nothing was updated in the window.
- The API call failed, usually because the role lacks a permission.
The first two are facts about the environment, and the fetcher records them as valid evidence. An empty detector list is the evidence that GuardDuty is off, which is exactly what a validator downstream needs in order to fail it. If the fetcher crashed instead, a gap in the environment would look like a problem with the tooling, and the finding would never reach the people who need to fix it.
The third is different. A permission error says nothing about the environment, so the fetcher logs it as a failure rather than quietly reporting zero detectors. Only GuardDuty's own "not enabled" response is translated into an empty result.
Same question, opposite answer
The rule flips for vulnerability reports. There, an empty file fails the run, because intake would read it as "every issue is resolved." I wrote about that in Vulnerability evidence straight from the scanner.
Both rules come from asking who reads the output next and what they will conclude from an empty result. A validator can turn "no detectors" into a clear fail. An issue intake would turn "no findings" into a false all-clear. The fetcher's job is to make sure nothing means the same thing to its reader as it does in the environment.
Teammates have refined the fetcher since I first merged it, which is how a shared repo should work.