GuardDuty Runtime Monitoring Agent: Tracking AWS Security Agent Versions

Last Build Status Link to heading

The Hidden Challenge of AWS GuardDuty Versioning Link to heading

Ever tried to track the versions of AWS GuardDuty runtime monitoring agents? If you’re running containerized workloads in AWS and care about security, you’ve probably encountered this frustration. Despite AWS’s generally excellent documentation and API coverage, there’s a curious gap when it comes to GuardDuty runtime monitoring agent versions, particularly for Fargate.

I recently found myself needing to track these versions for a compliance project. The requirement seemed simple: document all security agent versions running in our environment. Most components were straightforward to inventory, but GuardDuty’s runtime monitoring agents proved elusive. AWS doesn’t expose these versions through any API, leaving us with a blind spot in our security documentation.

The Problem Space Link to heading

GuardDuty Runtime Monitoring is a powerful feature that helps detect threats in your containerized workloads. When enabled, AWS deploys security agents into your ECS Fargate tasks or EKS clusters. These agents monitor for suspicious activities and report back to GuardDuty.

The challenge? AWS regularly updates these agents with new capabilities and security fixes, but doesn’t provide an API to:

1. Check which version is currently deployed
2. View release history or changelogs
3. Verify SHA256 digests for container images

This creates several problems:

• Compliance teams can’t easily document the security agents in use
• Security teams can’t verify if the latest agent versions are deployed
• DevOps engineers can’t troubleshoot agent-related issues effectively

Building a Solution Link to heading

Rather than accepting this limitation, I decided to create a simple but effective solution: a JSON file that tracks the release history of GuardDuty runtime monitoring agents, complete with SHA256 digests.

The approach is straightforward:

1. Collect SHA256 digests for GuardDuty runtime monitoring agent images
2. Organize them by version and architecture (x86_64 and arm64)
3. Make the data available in a structured JSON format
4. Automate updates to keep the information current

The result is a public JSON endpoint that anyone can use to check GuardDuty runtime monitoring agent versions: https://guarddutysha.cageyv.dev/guardduty_runtime_image_sha256.json

Inside the JSON Structure Link to heading

The JSON file organizes GuardDuty agent versions into two main categories:

1. Fargate ECS agents - Used for Amazon ECS tasks
2. EKS agents - Used for Amazon EKS clusters

Each category contains version entries with their corresponding SHA256 digests, like this:

{
  "fargate_ecs": {
    "v1.7.0-Fg_x86_64": "sha256:bf9197abdf853607e5fa392b4f97ccdd6ca56dd179be3ce8849e552d96582ac8",
    "v1.7.0-Fg_arm64": "sha256:bf9197abdf853607e5fa392b4f97ccdd6ca56dd179be3ce8849e552d96582ac8",
    // Additional versions...
  },
  "eks": {
    "v1.10.0-Eks_x86_64": "sha256:6dcbe5b055e1ef0af903071ede0b08f755ad5b7e9774a67df5399efdaa1f3d7d",
    "v1.10.0-Eks_arm64": "sha256:6dcbe5b055e1ef0af903071ede0b08f755ad5b7e9774a67df5399efdaa1f3d7d",
    // Additional versions...
  }
}

What’s interesting is that for each version, the SHA256 digests are identical for both x86_64 and arm64 architectures. This suggests AWS is using multi-architecture images with the same digest, a common practice for container images that support multiple platforms.

How It Works Behind the Scenes Link to heading

The repository uses a simple but effective approach to maintain this data:

1. A Python script periodically checks for new GuardDuty agent versions
2. When new versions are detected, the JSON file is updated
3. GitHub Actions automate this process to keep the data current
4. Cloudflare Workers serve the JSON file for public access

The entire solution is open source and available on GitHub: guardduty-runtime-monitoring-agent-release-json

Practical Applications Link to heading

How might you use this information? Here are a few scenarios:

Compliance Documentation Link to heading

For organizations that need to document all security tools in their environment:

# Fetch the latest GuardDuty agent versions
curl -s https://guarddutysha.cageyv.dev/guardduty_runtime_image_sha256.json | jq '.fargate_ecs | keys'

Verification Scripts Link to heading

To verify that your containers are using the expected GuardDuty agent version:

import requests
import json

# Fetch the GuardDuty agent versions
response = requests.get('https://guarddutysha.cageyv.dev/guardduty_runtime_image_sha256.json')
guardduty_versions = json.loads(response.text)

# Check if a specific digest is a known GuardDuty agent
def is_guardduty_agent(digest):
    for platform in guardduty_versions:
        for version, sha in guardduty_versions[platform].items():
            if sha == digest:
                return True, platform, version
    return False, None, None

# Example usage
is_agent, platform, version = is_guardduty_agent("sha256:bf9197abdf853607e5fa392b4f97ccdd6ca56dd179be3ce8849e552d96582ac8")
if is_agent:
    print(f"This is a GuardDuty agent for {platform}, version {version}")

Security Monitoring Link to heading

For security teams that want to ensure the latest agent versions are deployed:

# Get the latest Fargate ECS agent version
LATEST_VERSION=$(curl -s https://guarddutysha.cageyv.dev/guardduty_runtime_image_sha256.json | jq -r '.fargate_ecs | keys | .[0]')
echo "Latest GuardDuty Fargate agent version: $LATEST_VERSION"

Current Limitations and Future Work Link to heading

While this solution addresses the immediate need, there are some limitations:

1. The EKS agent version naming is based on educated guesses, as AWS doesn’t publish this information
2. There’s no official changelog from AWS to link versions to specific features or fixes
3. The data is manually collected rather than provided through an official AWS channel

I’m hoping AWS will eventually provide an official API for this information. Until then, this JSON file serves as a useful stopgap for those of us who need to track GuardDuty runtime monitoring agent versions.

Contributing Link to heading

If you find this useful and want to contribute, there are several ways to help:

1. Report new agent versions when you encounter them
2. Suggest improvements to the JSON structure or API
3. Help document the differences between agent versions
4. Share how you’re using this data in your own projects

The GitHub repository is open for issues and pull requests: guardduty-runtime-monitoring-agent-release-json

Final Thoughts Link to heading

Sometimes the simplest solutions are the most effective. While AWS provides excellent tooling for most security needs, there are still gaps that the community can fill. This small project addresses one such gap, making it easier for all of us to track and verify the security agents protecting our containerized workloads.

What other AWS security information would you like to see made more accessible? Let me know in the comments or reach out directly.