# EC2 Ephemeral Instance Sandbox

Run vulnerability scans on ephemeral EC2 instances with Amazon Bedrock
authentication. Uses SSM RunCommand for tool execution — no Lambda MicroVM
preview access required.

## Architecture

```
┌─────────────────────────────────────────────────────────────┐
│  Orchestrator (your machine / CI / Lambda)                   │
│                                                              │
│  ┌──────────────────┐         ┌──────────────────────────┐  │
│  │ Bedrock Converse  │◄───────►│ Agent Loop               │  │
│  │ (Claude Sonnet)   │         │ (ec2_agent.py)           │  │
│  └──────────────────┘         └────────────┬─────────────┘  │
│                                            │                 │
│  SSM RunCommand (bash, read_file, etc.)    │                 │
│  ─────────────────────────────────────────►▼                 │
│                                                              │
│  ┌───────────────────────────────────────────────────────┐   │
│  │  EC2 Instance (ephemeral, private subnet)              │   │
│  │  ┌─────────────────────────────────────────────────┐   │   │
│  │  │ SSM Agent (pre-installed on AL2023)               │   │   │
│  │  │  • bash execution with ASAN binaries             │   │   │
│  │  │  • file read/write in /work                      │   │   │
│  │  │  • grep/find across source                       │   │   │
│  │  └─────────────────────────────────────────────────┘   │   │
│  │  Security Group: NO inbound, egress to Bedrock only    │   │
│  │  Terminated after scan completes                       │   │
│  └───────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

## When to Use

- Your account doesn't have Lambda MicroVM preview access
- Scans may exceed Lambda's 15-minute timeout
- You want the simplest possible deployment (standard EC2)
- You need to install custom analysis tools (Semgrep, CodeQL, etc.)

## Prerequisites

- AWS CLI v2 configured with credentials that can:
  - `ec2:RunInstances`, `ec2:TerminateInstances`, `ec2:DescribeInstances`
  - `ssm:SendCommand`, `ssm:GetCommandInvocation`
  - `iam:PassRole` (for the instance profile)
  - `bedrock:InvokeModel*`
- Python 3.10+ with `boto3`
- A VPC with a private subnet (or public subnet for quick testing)

## Quick Start

```bash
# 1. Deploy infrastructure (IAM role, security group, instance profile)
aws cloudformation deploy \
  --template-file sandboxes/ec2/cfn-template.yaml \
  --stack-name vuln-scanner-ec2 \
  --capabilities CAPABILITY_NAMED_IAM \
  --parameter-overrides VpcId=vpc-xxx SubnetId=subnet-xxx

# 2. Run a scan
cd sandboxes/ec2
python3 run_scan.py \
  --target ./path/to/source \
  --model us.anthropic.claude-sonnet-4-6 \
  --region us-west-2

# 3. (Optional) Keep instance for debugging
python3 run_scan.py \
  --target ./path/to/source \
  --model us.anthropic.claude-sonnet-4-6 \
  --keep
```

## How It Works

1. **Launch** — Spins up a t4g.medium (ARM, 4GB) with AL2023, SSM agent, and
   the analysis toolchain (gcc, ASAN, git, python3). Waits for SSM to report
   the instance as `Online`.

2. **Upload** — Copies target source files to `/work/` on the instance via
   SSM RunCommand. For large repos, uses S3 as a transfer stage.

3. **Scan** — Runs the same Bedrock Converse agent loop as the MicroVM sandbox.
   Model requests tool calls (bash, read_file, write_file, search_files);
   orchestrator translates each to an SSM RunCommand and returns the output.

4. **Collect** — Pulls `VULN-FINDINGS.json` and crash artifacts from the
   instance via SSM.

5. **Terminate** — Instance is terminated (unless `--keep` is set).

## Comparison with MicroVM Approaches

| Aspect | Lambda MicroVM (Direct) | Lambda MicroVM (Zero-Egress) | EC2 |
|--------|------------------------|----------------------------|-----|
| Isolation | Firecracker hardware | Firecracker + zero network | Security group + ephemeral |
| Boot time | ~3 seconds | ~3 seconds | ~45-60 seconds |
| Access required | MicroVM preview | MicroVM preview | Any AWS account |
| Cost | Per-invocation | Per-invocation | ~$0.03/hr (t4g.medium) |
| Max scan time | 15 minutes | 15 minutes | Unlimited |
| Custom tools | Baked into image | Baked into image | Install at boot |
| Network | Egress to Bedrock | Zero egress | SG-controlled egress |

## Security Notes

- Security group blocks all inbound traffic
- Egress limited to Bedrock VPC endpoint and S3 (for SSM)
- Instance is terminated after scan — no persistent state
- Source code lives on an ephemeral EBS volume deleted on termination
- Instance profile grants `bedrock:InvokeModel*` for direct Bedrock access

## Code Reference

See [`sandboxes/ec2/`](../sandboxes/ec2/) for the implementation:
- `ec2_agent.py` — Orchestrator-side agent loop
- `ec2_sandbox.py` — EC2 instance lifecycle management
- `run_scan.py` — Standalone scan runner
- `cfn-template.yaml` — CloudFormation infrastructure template