What began as preparation for AWS incident-response exercises has grown into something much bigger: a public, production-inspired security engineering project built around practical runbooks, evidence preservation, controlled containment, recovery, and safe automation.
The AWS Incident Response Playbook documents my continuing journey into AWS cloud security, incident response, automation, and detection engineering. It brings together my background in infrastructure, Linux, cloud platforms, technical support, and operational troubleshooting with a structured approach to handling security incidents in AWS.
You can follow the project through my:
Why I Started This Project
The project originally grew from my preparation for the AWS Incident Response Demonstrated microcredential and related AWS SimuLearn exercises, including incident-response and compliance-enforcement scenarios.
My initial objective was straightforward: organize the procedures, AWS services, commands, and decision points needed to respond to common cloud security incidents.
However, I did not want to create another collection of disconnected study notes.
Real incident response is rarely as simple as finding a suspicious resource and immediately disabling or deleting it. Responders must first understand the scope of the incident, protect evidence, confirm account and Region context, evaluate business impact, obtain authorization, contain the threat, eliminate persistence, and restore services from trusted sources.
Because of that, the project gradually evolved into a broader question:
How can documented AWS incident-response procedures be turned into a structured, safe, testable, and eventually deployable security operations platform?
That question now drives the project roadmap.
The Core Philosophy
Several principles guide everything being built in the repository.
Evidence Before Destructive Action
Before isolating, disabling, replacing, or deleting a resource, responders should preserve the information needed to understand what happened.
That can include:
- CloudTrail activity
- AWS Config history
- Resource metadata and tags
- Network and security group associations
- IAM credential status
- S3 access configuration
- EBS snapshots
- Incident timelines and responder actions
Containment may sometimes need to happen immediately, but destructive action without sufficient evidence can make root-cause analysis and recovery more difficult.
Dry Run First
Response automation can affect availability, identity access, network connectivity, and customer-facing workloads. For that reason, mutating actions in the project default to dry-run behavior.
The responder must deliberately authorize an actual change.
Targeted Containment
The goal is to apply the smallest effective containment action instead of creating a broader outage.
Examples include disabling one compromised IAM access key rather than disabling an entire identity system, or replacing the security group associations of a specific EC2 instance rather than disrupting an entire VPC.
Rollback Is Part of the Design
Containment and rollback are not separate afterthoughts.
Where an action is reversible, the original state should be recorded before the change. Restoration should then require a validated record, explicit authorization, and confirmation that recovery is appropriate.
Human Control Over High-Impact Actions
Automation should help responders move faster and more consistently, but it should not remove human judgment from decisions that could interrupt legitimate workloads or restore an unsafe configuration.
These principles are now embedded in both the documentation and the automation framework.
Phase 1: Building the Foundation
The first phase established the project as a structured incident-response reference.
It introduced 20 scenario-based runbooks covering areas such as:
- EC2 instance compromise and isolation
- IAM credential compromise
- Data exfiltration
- Public S3 exposure
- Compliance enforcement
- RDS security incidents
- Backdoor IAM users
- Malicious Lambda or scheduled persistence
- AWS account root compromise
- Unauthorized API calls
- CloudTrail investigation
- AWS Config drift
- Security group exposure
- EBS forensic preservation
- Step Functions incident orchestration
The foundation also added severity classification, initial triage, evidence-collection guidance, emergency procedures, AWS CLI references, Athena queries for CloudTrail investigation, and reusable incident and evidence-log templates.
Phase 1 transformed a collection of scenarios into a practical study resource, tabletop exercise guide, and responder reference.
Phase 2: Professionalizing the Documentation
Once the core content existed, the next challenge was usability.
A playbook is only valuable during an incident when responders can find the correct procedure quickly, understand its risks, and determine what to do next.
Phase 2 therefore focused on turning the repository into a professionally organized documentation system.
Repository and Navigation Improvements
The main README was redesigned around responder tasks instead of merely listing files. Documentation indexes, domain-based navigation, a roadmap, a changelog, release history, contribution guidelines, a security policy, and a Code of Conduct were added.
Visual Response Flows
The runbooks were expanded with incident summaries, Mermaid response flows, decision diagrams, and reusable architecture sources.
These visuals make it easier to understand the path from detection and triage through investigation, containment, eradication, recovery, and lessons learned.
Framework Alignment
The scenarios were mapped to:
- MITRE ATT&CK
- NIST incident-response guidance
- AWS Well-Architected Security Pillar guidance
The project also distinguishes direct framework mappings from contextual or inferred relationships so the documentation does not imply a stronger connection than the available evidence supports.
Decision Intelligence
Runbooks were enhanced with responder checkpoints for:
- Escalation
- Evidence preservation
- Containment approval
- Business impact
- Destructive-action safeguards
- Rollback
- Trusted recovery
This shifted the documentation from simply describing commands to helping responders understand when an action should—or should not—be performed.
Documentation Validation
A Markdown link validator and GitHub Actions workflow now check internal documentation links when changes are pushed or pull requests are submitted.
Phase 2 concluded with the v2.0.0 Production Documentation milestone.
Phase 3: Moving From Documentation to Automation
The project is now in Phase 3, where documented procedures are being converted into modular and auditable AWS response automation.
The objective is not to automate every incident decision. The objective is to automate repeatable operations while preserving context validation, evidence capture, approval boundaries, least privilege, rollback, and human oversight.
Phase 3, Commit 1: Automation Framework
The first automation milestone introduced the shared structure used by the response functions.
It included:
- A normalized incident-event contract
- AWS account and Region validation
- Structured logging
- Incident-resource tagging
- Shared response utilities
- Dry-run sample events
- Least-privilege IAM examples
- Terraform deployment scaffolding
- Packaging scripts
- Unit tests and CI validation
The initial actions covered EC2 metadata collection, EC2 isolation, EBS evidence snapshots, IAM access key disablement, and SNS incident notification.
This work was released as v2.1.0 — Automation Framework.
Current Status: v2.2.0 Response Actions
As of August 2, 2026, Phases 1 and 2 are complete. Phase 3 is in progress, and its first two commits have been completed.
The current project milestone is:
v2.2.0 — Response Actions
This release expanded the framework into a catalog of 11 response actions covering EC2, EBS, IAM, S3, and SNS workflows.
The current catalog includes:
- EC2 metadata collection
- Quarantine security group preparation
- EC2 network isolation
- EC2 security group restoration
- EBS evidence snapshot creation
- IAM access key disablement
- IAM access key restoration
- S3 public access inspection
- S3 public access containment
- S3 Block Public Access restoration
- SNS incident notification
The release also added checksummed rollback manifests, state-aware idempotency, expanded IAM and Terraform deployment scopes, machine-readable action definitions, sample events, troubleshooting guidance, cleanup instructions, cost guidance, and 31 mock-based unit tests.
Mutating actions continue to default to dry-run mode. Restoration actions require explicit confirmation and a matching rollback manifest. Account or Region mismatches fail closed instead of continuing with uncertain context.
What We Are Building Next
The next milestone is Phase 3, Commit 3 — Step Functions Incident Orchestration, targeted for release as v2.3.0.
The individual Lambda actions currently operate independently. The next step is to coordinate them into a controlled response workflow.
The planned state machine will orchestrate:
- Incident-event validation
- Read-only metadata collection
- Evidence snapshot creation
- Containment approval
- EC2 isolation or another authorized response
- Responder notification
- Structured audit output
- Rollback preparation
- Failure, retry, timeout, and compensation paths
High-impact containment will include explicit human approval gates. The workflow will also preserve completed evidence steps when a later action fails and produce a clear execution record for responders.
The Remaining Phase 3 Roadmap
After Step Functions orchestration, the current roadmap includes several additional milestones.
Systems Manager Investigation
AWS Systems Manager Automation documents will collect supported host-level information without requiring responders to open SSH or RDP.
The Linux-first investigation workflow is planned to collect selected information about processes, services, packages, users, networking, scheduled tasks, and logs while keeping evidence collection separate from containment.
Detection-to-Response Integration
EventBridge and CloudWatch integrations will connect selected CloudTrail, GuardDuty, Security Hub, and AWS Config findings to the response framework.
The default behavior will remain notify-only or approval-required. Automatic execution will be limited to explicitly classified, low-risk actions.
Terraform Productionization
The current deployment scaffold will evolve into reusable Terraform modules for Lambda, IAM, logging, notification, orchestration, event routing, and evidence storage.
The roadmap also includes multi-account deployment patterns for AWS Organizations environments, delegated security accounts, cross-account roles, permission boundaries, and controlled environment configurations.
End-to-End Authorized Incident Lab
Phase 3 will conclude with a reference lab demonstrating the complete workflow:
- Generate or inject a supported incident event
- Normalize and validate it
- Collect metadata and evidence
- Pause for containment approval
- Isolate the affected workload
- Notify the responder
- Record structured results
- Demonstrate rollback or trusted recovery
- Tear down the environment safely
This capstone is planned to become the v3.0.0 Automated Response Platform milestone.
Beyond Phase 3
The longer-term roadmap extends beyond automation.
Phase 4: Deployable Practice Labs
The project will provide isolated, repeatable, and cost-conscious labs for EC2 compromise, S3 exposure, IAM compromise, RDS exposure, CloudTrail investigation, AWS Config remediation, Systems Manager evidence collection, orchestration, and detection-to-response workflows.
Phase 5: Detection Engineering
A detection library will connect AWS telemetry to explainable incident signals. Planned content includes EventBridge patterns, CloudWatch filters, Athena and CloudTrail queries, GuardDuty and Security Hub handling, identity anomalies, S3 changes, logging tampering, and network-exposure detection.
Phase 6: Operational Maturity
The final planned phase will move beyond individual tools and runbooks toward a sustainable cloud security operations model, including multi-account operations, incident command, communications, evidence custody, exercises, metrics, and continuous improvement.
Together, these phases are intended to evolve the repository from a scenario-based reference into a complete learning and engineering platform for AWS incident response.
What This Project Means to Me
This repository is more than a collection of security documents.
It represents the connection between the systems I have supported throughout my career and the cloud security capabilities I continue to develop.
My background has taught me that effective incident response depends on more than knowing a service or memorizing a command. It requires disciplined troubleshooting, an understanding of infrastructure dependencies, careful communication, evidence-based decisions, and respect for operational risk.
Building this project allows me to apply those lessons to modern AWS environments while strengthening my experience in:
- Cloud incident response
- Security engineering
- Python and Lambda automation
- Infrastructure as Code
- AWS security services
- Detection engineering
- Testing and CI
- Technical documentation
- Operational safety and recovery design
It also gives me a structured way to turn study, experimentation, and lab work into a public, reusable project that can continue to improve.
An Open and Continuing Journey
The AWS Incident Response Playbook remains an independent educational and operational reference. It is not an official AWS guide, and its procedures should never be applied blindly to a production environment.
Every organization has different architectures, legal obligations, evidence requirements, approval processes, and business priorities. Any containment or remediation action must be authorized, validated, tested, and adapted to the environment where it will be used.
The repository is public because I want the journey to remain visible—from the first runbooks to the eventual automated workflows, deployable labs, and detection library.
There is still a great deal to build, but the direction is clear:
Prepare carefully, preserve evidence, automate safely, maintain human control, and recover from trusted sources.
Follow the project through my GitHub profile, or explore the complete AWS Incident Response Playbook repository.