DockerEC2Manager (v3.0)

A production-grade, containerized tool to list AWS EC2 instances securely. Optimized for speed, security, and scalability.

🚀 Key Features

• Security First: Runs as a non-privileged user. Supports IAM Roles, Instance Profiles, and Environment Variables.
• Scalable: Uses AWS SDK (boto3) pagination to handle accounts with thousands of instances.
• Machine Readable: Optional JSON output for easy integration with other automation tools.
• Lightweight: Multi-stage Alpine-based Docker build (~50MB image).
• Observability: Structured JSON logging and advanced health checks (verifies AWS connectivity).
• CI/CD Ready: Integrated GitHub Actions for automated testing and Docker validation.

📦 Requirements

• Docker (20.10+)
• AWS Credentials (IAM User or Role) with ec2:DescribeInstances and ec2:DescribeRegions permissions.

🛠 Usage

1. Build the Image

docker build -t docker-ec2-manager DockerEC2Manager/

2. Run the Container

The tool supports both positional arguments and flags.

Standard Text Output:

docker run --rm \
    -e AWS_ACCESS_KEY_ID=xxx \
    -e AWS_SECRET_ACCESS_KEY=xxx \
    docker-ec2-manager us-west-2

JSON Output (Ideal for piping to jq):

docker run --rm \
    -e AWS_ACCESS_KEY_ID=xxx \
    -e AWS_SECRET_ACCESS_KEY=xxx \
    docker-ec2-manager us-east-1 --json

Debug Mode:

docker run --rm -e AWS_ACCESS_KEY_ID=xxx -e AWS_SECRET_ACCESS_KEY=xxx \
    docker-ec2-manager us-east-1 --verbose

⚙️ Configuration

Flag	Description	Default
region	AWS Region to query	us-east-1
--json	Output results in JSON format	False
--verbose	Enable DEBUG level logging	False

🧪 Development & Testing

Local Setup

# Install dependencies
pip install -r DockerEC2Manager/requirements-dev.txt

# Run Unit Tests
export PYTHONPATH=$PYTHONPATH:$(pwd)/DockerEC2Manager
pytest DockerEC2Manager/test_list_instances.py -v

CI/CD Workflow

This project uses GitHub Actions (.github/workflows/ci.yml) to:

1. Run pytest on every push.
2. Verify the multi-stage Docker build.
3. Ensure 100% pass rate before deployment.

🏥 Health Checks

The container includes an advanced healthcheck.sh that verifies:

1. Application script integrity.
2. Python syntax.
3. Optional: Connectivity to the AWS STS API (if credentials are provided).

Check health status with:

docker inspect --format='{{json .State.Health}}' <container_id>

🛡 Security

• Non-Root: The container runs as appuser (UID 1000).
• Slim Image: No aws-cli or shells are exposed in the final production image (only sh for healthchecks).
• Credential Handling: Never hardcode keys. Use Docker secrets or environment variables.

📜 License

MIT - Created by elliotsecops