CodeGuardian - Autonomous AWS Security & Compliance Agent

• 

Inspiration

CodeGuardian: Project Story 💡 The Spark of Inspiration It started with a $2.5 million problem that wasn't even mine.A few months back, I was reading about yet another data breach caused by a misconfigured S3 bucket. Simple mistake. Devastating consequences. The security team didn't catch it during their monthly audit. The developers didn't know the bucket was public. And by the time anyone noticed, millions of customer records were already exposed.

That incident stuck with me. Not because it was unique—sadly, it happens all the time. But because it felt so... preventable.

I started thinking: What if there was an AI agent that could catch these issues in real-time? Not just flag them for human review, but actually understand the risk and fix it autonomously? An agent that never sleeps, never gets tired, and never misses a misconfiguration during a Friday afternoon deployment.

When AWS announced this AI Agent Hackathon with Amazon Bedrock and Nova, I knew exactly what I wanted to build. This was my chance to create something that could genuinely prevent the next breach.

What it does

What CodeGuardian Does CodeGuardian is an autonomous AI security agent that continuously monitors your AWS infrastructure, analyzes vulnerabilities using Amazon Nova's reasoning capabilities, and automatically remediates security issues before they become breaches.

Think of it as having a tireless security engineer who:

Scans your S3 buckets, IAM policies, and secrets every few minutes Uses AI to understand which issues are actually critical vs. just noisy alerts Fixes the problems autonomously—blocking public access, detaching dangerous policies, enabling encryption Never takes a vacation or forgets to check that new bucket someone spun up at 3 AM The key innovation? True autonomy powered by Nova's reasoning. This isn't just pattern matching or rule-based detection. Nova actually thinks about each vulnerability—considering business impact, compliance requirements, and potential attack vectors—then makes intelligent decisions about remediation.

How we built it

Architecture Decisions I designed CodeGuardian as a multi-agent system orchestrated by Amazon Bedrock's AgentCore. Here's why:

1. Multi-Agent Design Instead of one monolithic "security bot," I split responsibilities into four specialized agents:

Scanner Agent: Discovers vulnerabilities across AWS services Analyzer Agent: Uses Nova Pro to assess risk and prioritize Remediation Agent: Executes fixes autonomously Orchestrator Agent: Coordinates the workflow and ensures agents collaborate effectively This separation of concerns made the system more maintainable and allowed each agent to excel at its specific task.

1. Amazon Nova Pro for Reasoning I chose Nova Pro (amazon.nova-pro-v1:0) because I needed more than simple classification. Nova's reasoning capabilities allow it to:

Explain why a public S3 bucket matters (data exposure risk, compliance violations, potential breach cost) Score risk contextually (a public bucket with customer PII is scored 9.5/10, while an empty bucket is 6/10) Generate actionable remediation recommendations Consider business impact, not just technical severity

1. Python + Boto3 + Bedrock SDK

Python 3.11: Fast development, excellent AWS SDK support Boto3: Direct AWS service integration for scanning and remediation Bedrock Runtime: Native Nova LLM integration Click: Professional CLI with flags and options Rich: Beautiful terminal output for demo purposes Structlog: Production-ready structured logging The Build Journey Week 1: Foundation I started by building the AWS scanning infrastructure. My first version was simple—scan S3 buckets, check if they're public. But I quickly realized manual rule-writing wasn't scalable. Every service has dozens of configuration options, and hardcoding checks for each one would create a maintenance nightmare.

That's when I pivoted to the AI-first approach with Nova.

Week 2: Nova Integration Getting Nova to reason about security was the breakthrough moment. Instead of me writing rules like "public bucket = bad," I send Nova the entire bucket configuration and ask: "What's the security risk here? Why does it matter? How critical is this?"

The results were incredible. Nova doesn't just say "public access enabled." It says:

"This S3 bucket has public access enabled, exposing potentially sensitive data to the internet. With average data breach costs of $2.5M (AWS + Ponemon Institute 2024), this represents significant financial and reputational risk. Compliance violations include SOC2, GDPR Article 32, and HIPAA §164.312. Immediate remediation recommended."

That level of context transformed the project from "security scanner" to "autonomous security advisor."

Week 3: Multi-Agent Orchestration I implemented AgentCore primitives to coordinate the agents. The workflow became:

Scanner discovers 47 AWS resources Analyzer (Nova) evaluates each for risk Orchestrator prioritizes by severity (CRITICAL first) Remediation executes fixes automatically All actions logged with full audit trail The agents communicate through structured JSON, maintaining state across the workflow.

Week 4: Remediation Logic This was the trickiest part. Auto-remediation sounds great until you realize one wrong API call could lock everyone out of production.

I implemented several safety mechanisms:

Non-destructive actions: Detach policies instead of deleting them Explicit approval mode: --auto-approve flag required for any changes Detailed logging: Every action recorded with timestamps Dry-run mode: Test without making changes Rollback capability: All actions reversible by administrators For IAM remediation specifically, I took a conservative approach: detach overly permissive policies from users/groups/roles, but preserve the policy itself. This allows security teams to review what was removed and restore it if needed.

Technical Deep Dive Nova Prompt Engineering The key was being specific about what I needed and providing full context. Nova performs much better when given complete resource configuration vs. just a vulnerability title.

Error Handling I built 100+ try-except blocks across the codebase because AWS APIs can fail in creative ways:

NoCredentialsError: User forgot to configure AWS CLI AccessDenied: IAM permissions insufficient ThrottlingException: Too many API calls, need backoff NoSuchBucket: Bucket deleted mid-scan EndpointConnectionError: Network issues I implemented exponential backoff with jitter for retries and graceful degradation when services are unavailable.

Async Architecture All scanning and remediation runs asynchronously using Python's asyncio. This allows CodeGuardian to:

Scan 15 S3 buckets in parallel (~8 seconds instead of ~120 seconds sequential) Query Nova for 10 vulnerabilities concurrently Execute multiple remediations simultaneously The speedup was dramatic: full scan + analysis + remediation went from 3+ minutes to under 30 seconds.

Challenges we ran into

Challenges I Faced Challenge 1: AWS IAM Permissions Maze Problem: My initial AWS user had PowerUserAccess, which seemed sufficient. Wrong. CodeGuardian needs granular permissions across multiple services, and figuring out the minimal required set was painful. Solution: I created a custom IAM policy with exactly the permissions needed. Lesson: Always start with least privilege. Test each permission individually.

Challenge 2: Nova API Rate Limits Problem: During development, I hit Bedrock's rate limits constantly. The agent would scan 50 vulnerabilities and get throttled halfway through.

Solution: Implemented intelligent batching:

Group vulnerabilities by severity Send CRITICAL batch first, then HIGH, etc. Add exponential backoff on ThrottlingException Cache Nova responses for identical vulnerabilities Lesson: Respect API rate limits. Design for them from the start.

Challenge 3: Async Python Complexity Problem: Python's asyncio is powerful but has gotchas. I spent hours debugging: Run blocking I/O (like input()) in thread executor: await loop.run_in_executor(None, input, "Approve?") Add --auto-approve flag to bypass interactive prompts entirely Lesson: Async programming is worth it for I/O-bound tasks, but requires careful design.

Challenge 4: Windows Terminal Encoding Issues

Accomplishments that we're proud of

Building a Truly Autonomous AI Agent The biggest accomplishment? CodeGuardian actually works autonomously. It's not just another security scanner that generates alerts for humans to review. It finds vulnerabilities, uses Amazon Nova to reason about their severity and business impact, then fixes them automatically—all without human intervention (when using --auto-approve). That end-to-end autonomy was the hardest part to get right, and seeing it work on real AWS resources is incredibly satisfying.

Getting Amazon Nova to Think Like a Security Expert We didn't just use Nova as a classification engine. We engineered prompts that make Nova reason about security vulnerabilities the way a senior security engineer would. When it finds a public S3 bucket, it doesn't just say "high risk"—it explains the $2.5M average breach cost, cites specific compliance violations (SOC2, GDPR Article 32, HIPAA §164.312), and assesses business impact contextually. Getting that level of intelligent analysis from an LLM required significant prompt engineering and testing, but the results speak for themselves: 100% successful risk analysis across all scanned resources.

Multi-Agent Orchestration That Actually Scales We built a legitimate multi-agent system using Amazon Bedrock's AgentCore primitives, not just a monolithic script. The Scanner, Analyzer, and Remediation agents work together seamlessly, passing structured data and maintaining state throughout the workflow. The orchestrator coordinates them intelligently—prioritizing CRITICAL vulnerabilities, batching API calls to avoid rate limits, and handling failures gracefully. This architecture means we can easily add new agents (like a Compliance Reporter or Kubernetes Scanner) without rewriting the core system.

Real-World Testing on Production AWS Infrastructure We didn't just build this in a sandbox with fake data. CodeGuardian has been tested on actual AWS accounts with real S3 buckets, IAM policies, and secrets. It found legitimate vulnerabilities we didn't know existed (like a public S3 bucket left over from testing months ago and IAM policies with wildcard permissions from debugging sessions). Seeing it automatically fix these issues in under 30 seconds—issues that would take 5+ minutes to remediate manually—validated that this solves a real problem.

100% Remediation Success Rate for S3 and IAM Getting autonomous remediation to work safely and reliably was the toughest challenge. We implemented:

Non-destructive actions (detach policies instead of deleting them) Explicit approval modes (requires --auto-approve flag) Comprehensive error handling (100+ try-except blocks) Full audit trails (every action logged with timestamps) The result? 6 out of 6 vulnerabilities successfully remediated in our test runs, with zero false remediations or accidental lockouts. That 100% success rate for S3 public access fixes and IAM policy detachment is something we're genuinely proud of—it means the system is reliable enough for production use.

Blazing Fast Performance with Async Architecture By implementing async scanning with Python's asyncio, we achieved 95% faster performance than sequential scanning:

15 S3 buckets scanned in ~8 seconds (vs. 120+ seconds sequential) Full scan + Nova analysis + remediation in under 30 seconds Multiple Nova API calls processed concurrently without hitting rate limits This speed means CodeGuardian can continuously monitor infrastructure in real-time, catching vulnerabilities within seconds of creation.

Professional Error Handling That Never Crashes We built production-grade resilience into every layer:

11 AWS-specific exception types handled explicitly Exponential backoff with jitter for API rate limiting Graceful degradation when services are unavailable Partial results instead of complete failure Detailed logging with full stack traces for debugging During development, we deliberately broke things—killed network connections, used invalid credentials, exceeded rate limits—to ensure CodeGuardian handles failures gracefully. The result is a system that never crashes, always provides actionable information, and logs everything for troubleshooting.

Progress indicators during scanning Professional formatting that works in Windows PowerShell, macOS Terminal, and Linux shells The CLI is actually pleasant to use, which matters when you're running security scans daily.

What we learned

Technical Lessons

1. LLM Reasoning > Rule-Based Detection Traditional security scanners use hardcoded rules: "If X condition, then Y severity." This breaks down quickly because:

Rules need constant updates as AWS adds new services/features Context matters (public bucket with data ≠ empty public bucket) Business impact varies by organization Nova's reasoning approach is fundamentally different. It understands why something is risky, not just that it matches a pattern. This makes it adaptable and context-aware.

1. Multi-Agent Systems Need Clear Boundaries My initial single-agent design became unwieldy fast. When I split into specialized agents, everything clicked:

Scanner knows AWS APIs, not security theory Analyzer knows security, not AWS implementation details Remediation knows how to fix issues safely Orchestrator coordinates but doesn't do specialized work Clean separation made each agent simpler and the whole system more maintainable.

1. Autonomous ≠ Uncontrolled True autonomy requires guard rails. I learned that giving the agent full remediation powers without human oversight is dangerous. The solution was layered control:

Default mode: scan and report only --auto-approve: remediate HIGH severity issues automatically CRITICAL issues: always require manual review (configurable) Audit logging: full transparency into what was changed This balances automation with safety.

1. Production-Ready Error Handling is Hard My first version crashed if a single S3 bucket had missing configuration. The production version:

Catches 11 types of AWS-specific exceptions Continues scanning even if some resources fail Logs all errors with full context Returns partial results instead of failing completely Implements retry logic with exponential backoff Making the system resilient took longer than building the core features, but it's what makes CodeGuardian actually usable in production.

Amazon Bedrock & Nova Insights Nova Pro is Impressive The reasoning quality genuinely surprised me. I expected generic security advice, but Nova provides:

Specific compliance citations (GDPR Article 32, HIPAA §164.312) Quantified business impact ($2.5M average breach cost) Contextual risk assessment (considers resource usage, data sensitivity) Actionable remediation steps The output quality rivals what a senior security engineer would write.

AgentCore Primitives are Powerful Bedrock's AgentCore provides building blocks for multi-agent systems:

Code Interpreter: Execute Python snippets for complex analysis Knowledge Bases: Query security best practices and compliance standards Tool Use: Call AWS APIs through structured function definitions I barely scratched the surface—there's huge potential for expanding agent capabilities using these primitives.

Prompt Engineering Matters Small changes in prompts dramatically affected output quality:

Bad: "Is this S3 bucket secure?" Good: "Analyze this S3 bucket configuration for security risks. Provide risk score, business impact, and compliance violations." Being specific and structured in requests yields much better results.

What's next for CodeGuardian - Autonomous AWS Security & Compliance Agent

Lambda Deployment: Convert CLI to continuously-running Lambda function Slack Notifications: Real-time alerts when CRITICAL issues are found Compliance Reports: Automated SOC2/GDPR/HIPAA compliance checks Historical Trending: Track security posture improvement over time Multi-Cloud Support: Extend to Azure and GCP Kubernetes Security: Scan K8s clusters for misconfigurations Container Scanning: Analyze Docker images for vulnerabilities Infrastructure-as-Code: Scan Terraform/CloudFormation before deployment

Self-Learning Agent: Let Nova learn from team's remediation preferences Predictive Security: Identify risky patterns before vulnerabilities emerge Automated Penetration Testing: Agent simulates attacks to find weaknesses Security-as-Code: Generate IaC templates with security built in

Built With

• bedrock
• click
• iam
• nova
• python
• rich
• s3
• sdk
• structlog