Architecture
How Ira Works
A technical walkthrough of the multi-agent architecture — from telemetry ingestion through risk scoring to containment recommendations.
Architecture Overview
System architecture
Example Scenario
Credential exfiltration — step by step
A GuardDuty finding fires: UnauthorizedAccess:IAMUser/InstanceCredentialExfiltration.OutsideAWS.
Here's what happens next.
-
GuardDuty finding triggers the orchestrator
EventBridge routes the GuardDuty finding to the Step Functions orchestrator. The finding includes the affected IAM principal, the external IP, and the GuardDuty confidence score (HIGH).
-
Orchestrator fans out to sub-agents
The orchestrator initiates parallel execution of the CloudTrail Agent and VPC Flow Agent, scoped to the affected principal and instance respectively. The Config Agent is also initiated to assess the affected IAM role and instance profile.
-
CloudTrail Agent finds the signal chain
CloudTrail shows the IAM user assumed OrganizationAccountAccessRole from a Tor exit node IP — a role it has never assumed before. Two sensitive API calls (DescribeInstances, ListBuckets) followed immediately. The agent returns three correlated signals with HIGH severity.
-
VPC Flow Agent detects anomalous egress
VPC Flow shows 2GB of outbound traffic from the affected EC2 instance to the same external IP over 5 minutes, on port 443. No matching inbound session exists. The agent flags this as a potential data exfiltration pathway.
-
Config Agent finds drift on the IAM role
AWS Config history shows a managed policy was attached to the affected instance role 6 hours prior — AdministratorAccess. This drift event was not reviewed. Config Agent classifies this as HIGH severity drift.
-
Recommendation engine scores and ranks
All sub-agent results converge. Composite risk score: 94 (CRITICAL). Two containment recommendations are generated: (1) Revoke active IAM session for the affected user — risk reduction 87. (2) Detach AdministratorAccess policy from the instance role — risk reduction 72. Both are presented to the operator for approval.
Deployment
Single-tenant, AWS-native, Terraform-provisioned
Your account, your data
Ira deploys entirely within your AWS account. There is no shared data plane, no multi-tenant backend, and no call home. Your telemetry never leaves your account boundary.
IAM-scoped read access
The system uses IAM roles with read-only access scoped to the telemetry sources it analyses. It does not require write access to your environment to generate recommendations.
Terraform-provisioned
The complete infrastructure stack — Lambda functions, Step Functions orchestrator, EventBridge rules, DynamoDB state store — is provisioned via Terraform. Reproducible from a fresh account.
No internet egress required
All API calls are to AWS service endpoints within the same account. VPC endpoints are used where available. No data is transmitted to external services during analysis.
Design Principles
Why it works the way it does
The core constraint of Ira's design is this: the agent never takes external actions. Every containment action is presented as a recommendation — a structured, ranked, human-readable output — and requires explicit operator approval before anything in your environment changes.
This is not a limitation of the technology. It is the design. A security system that acts autonomously introduces a new attack surface: the system itself. If an adversary can trigger the agent into taking a containment action, they can use that action as a weapon. Human-in-the-loop is the right architecture for this domain.
The audit trail is equally important. Every analysis Ira runs produces a complete, queryable log: the signals it ingested, the scores it calculated, the recommendations it generated, and — after operator approval — the actions taken. That record exists regardless of whether a recommendation is accepted or rejected.