CloudMapper Installation Guide

This guide provides two deployment methods: CloudFormation template (recommended) for automated deployment with encryption options, or direct EC2 launch from the AMI. Both methods support EBS encryption with customer-managed KMS keys.

Prerequisites: You need an AWS account with appropriate permissions to create CloudFormation stacks, EC2 instances, and IAM roles.

AMI Encryption Note: The CloudMapper AMI is unencrypted to meet AWS Marketplace distribution requirements. However, encryption is enabled by default when you deploy instances using our CloudFormation template. You can choose your own KMS key for enhanced security.

Choose Your Deployment Method

CloudFormation Deployment

Recommended

Best for: Production deployments, automated setup, teams

Automated IAM role creation
EBS encryption enabled by default
Choose your own KMS key
Security group configuration
One-click deployment
Easy stack updates

Use CloudFormation

Direct EC2 Launch

Manual

Best for: Testing, development, custom configurations

Manual IAM role setup required
Encryption configured at launch
Security group setup required
More configuration steps
Full control over all settings
Faster initial launch

Launch from AMI

Method 1: CloudFormation Deployment (Recommended)

Subscribe to CloudMapper on AWS Marketplace

Navigate to the AWS Marketplace and subscribe to CloudMapper to get access to the AMI and CloudFormation templates.

Go to AWS Marketplace in your AWS Console
Search for "CloudMapper by Buckshot Technologies"
Click on the product listing
Review pricing and terms
Click "Continue to Subscribe"
Accept the terms and conditions
Click "Continue to Configuration"

Configure Product Options

Select your deployment region and CloudFormation template version.

                                        Configuration Options:
                                        Fulfillment Option: CloudFormation Template
Software Version: Latest (1.1.0)
Region: Select your preferred AWS region

                                    

Click "Continue to Launch" after making your selections.

Launch CloudFormation Stack

Deploy CloudMapper using the provided CloudFormation template.

Launch Options:

Action: Launch CloudFormation
Template: cloudmapper-standard.yaml
Access: VPC with internet access

Security Features:

FIPS 140-2 Compliant
OIDC SSO Integration
HTTPS-Only Access
Air-gapped Compatible

Click "Launch" to proceed to CloudFormation.

Configure CloudFormation Parameters

Customize your CloudMapper deployment with the following parameters:

Encryption Enabled by Default: The CloudFormation template automatically enables EBS encryption for your CloudMapper instance. You can optionally provide your own customer-managed KMS key for additional control.

Instance Configuration:

InstanceType: t3.medium              # Recommended: t3.medium for most deployments
VpcId: vpc-xxxxxxxxx                 # Target VPC
SubnetId: subnet-xxxxxxxxx           # Public or private subnet
AssociatePublicIpAddress: true       # Optional - create public IP

# Instance Type Options (all x86_64):
# - t3.small/medium/large/xlarge/2xlarge (general purpose)
# - m5.large/xlarge, m6i.large/xlarge (compute-optimized for larger workloads)
# Note: Graviton2 (ARM64) support planned for future releases

Encryption Configuration (New in v1.1.3):

EncryptVolume: true                  # Enable EBS encryption (default: true, RECOMMENDED)
                                                     # Set to false only if your organization requires unencrypted volumes

KmsKeyId:                            # Optional: Your customer-managed KMS key
                                     # Leave empty to use AWS-managed key (aws/ebs)
                                     # Provide ARN for customer-managed key:
                                     # arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012

# Encryption Options:
# 1. Default (Recommended): EncryptVolume=true, KmsKeyId empty
#    → Uses AWS-managed key (aws/ebs) - no additional setup required
# 
# 2. Enhanced Control: EncryptVolume=true, provide KmsKeyId
#    → Uses your customer-managed key - full control over key rotation and access
#
# 3. No Encryption: EncryptVolume=false
#    → Not recommended for production environments

Why the AMI is Unencrypted: AWS Marketplace cannot distribute AMIs encrypted with AWS-managed keys across accounts. The unencrypted AMI is only used as a template - your deployed instance's EBS volume is automatically encrypted when you deploy using CloudFormation.

Security Configuration:

AllowedCIDR: 10.0.0.0/8             # CIDR for HTTPS/HTTP access (default: 10.0.0.0/8)
                                                     # Restrict to your organization's IP range
                                                     # Use 0.0.0.0/0 only for testing

# Optional SSH Access (for AWS Marketplace scanning only)
KeyName:                             # Leave empty to disable SSH (recommended)
                                     # Provide EC2 key pair name to enable SSH with ec2-user

# Note: SSM Session Manager is ALWAYS enabled for secure access

Cost Optimization:

AWS Savings Plans: Save up to 66% on compute costs (purchased separately)
Reserved Instances: Save up to 72% for 1-3 year commitments (purchased separately)
Estimated Monthly Cost: $30-35/month (t3.medium) + $4/month (50GB EBS) + CloudMapper license
Coming Soon: Graviton2 (ARM64) support for 20% better price-performance

Enhanced Security Features (v1.1.3+):

EBS Encryption: Enabled by default with AWS-managed or customer-managed KMS key
Data Protection: EBS deletion protection + termination protection enabled
IMDSv2: Instance metadata service v2 enforced
Access Control: SSH disabled by default, SSM Session Manager recommended
Optional SSH: Hardened with public key only, ec2-user only, connection limits
IAM Permissions: Read-only AWS access (cannot modify resources)
Network Isolation: Restrictive security group (10.0.0.0/8 default)
FIPS 140-2: Encryption at rest meets compliance requirements

Review and Deploy

Review your configuration and deploy the stack.

Review all parameters and settings
Check the "I acknowledge that AWS CloudFormation might create IAM resources" box
Click "Create Stack"
Monitor the stack creation process (typically 5-10 minutes)

Note: The CloudFormation stack will create IAM roles with necessary permissions for CloudMapper to scan your AWS infrastructure.

Access CloudMapper

Once the stack is created, access your CloudMapper instance via HTTPS.

Web Access (HTTPS Only):

# Public IP Access (if AssociatePublicIpAddress=true)
https://your-instance-public-ip

# Private IP Access (always available within VPC)
https://your-instance-private-ip

# Find your instance IPs from CloudFormation Outputs
aws cloudformation describe-stacks --stack-name your-stack-name \
  --query 'Stacks[0].Outputs[?OutputKey==`CloudMapperPublicIP`].OutputValue' \
  --output text

aws cloudformation describe-stacks --stack-name your-stack-name \
  --query 'Stacks[0].Outputs[?OutputKey==`CloudMapperPrivateIP`].OutputValue' \
  --output text

Public IP: Only available if you set AssociatePublicIpAddress=true during deployment. Private IP is always available for VPC-internal access.

Self-Signed Certificate: CloudMapper uses a self-signed SSL certificate. Your browser will show a security warning.

Accepting Self-Signed Certificate in Browser

Navigate to https://your-instance-ip
Browser will show "Your connection is not private" or similar warning
Chrome/Edge: Click "Advanced" → "Proceed to [IP] (unsafe)"
Firefox: Click "Advanced" → "Accept the Risk and Continue"
Safari: Click "Show Details" → "visit this website"

Production Recommendation: For production environments, we recommend placing an Application Load Balancer (ALB) in front of your CloudMapper instance with a trusted SSL certificate from AWS Certificate Manager (ACM).

SSM Access (Recommended - Always Available):

# Connect via AWS Systems Manager Session Manager (RECOMMENDED)
aws ssm start-session --target i-1234567890abcdef0

# Alternative: Use AWS Console
# 1. Go to EC2 → Instances
# 2. Select your CloudMapper instance
# 3. Click "Connect" → "Session Manager" → "Connect"

# SSM provides secure, audited terminal access without SSH keys

Optional SSH Access (For AWS Marketplace Scanning):

FIPS Mode: CloudMapper runs in FIPS 140-2 mode. You MUST use FIPS-compliant algorithms when connecting via SSH.

# SSH is disabled by default. To enable during deployment:
# 1. Provide a KeyName for EC2 key pair in CloudFormation parameters
# 2. SSH access will be available with ec2-user

# Connect via SSH with FIPS-compliant algorithms (REQUIRED)
ssh -o "KexAlgorithms=ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521" \
    -o "Ciphers=aes128-ctr,aes192-ctr,aes256-ctr,aes128-gcm@openssh.com" \
    -i /path/to/your-key.pem ec2-user@your-instance-public-ip

# Or add to ~/.ssh/config for permanent fix:
Host cloudmapper *.cloudmapper.*
  User ec2-user
  KexAlgorithms ecdh-sha2-nistp256,ecdh-sha2-nistp384,ecdh-sha2-nistp521
  Ciphers aes128-ctr,aes192-ctr,aes256-ctr
  MACs hmac-sha2-256,hmac-sha2-512

# SSH Hardening Features:
# - Public key authentication only (no passwords)
# - Only ec2-user allowed (root disabled)
# - Connection limits: 3 auth attempts, 2 sessions max
# - 5-minute inactivity timeout

Security Best Practice: SSH is disabled by default. SSM Session Manager provides more secure, audited access. SSH can be enabled temporarily for AWS Marketplace scanning requirements. Note: Standard SSH connections will fail with "Connection closed" if FIPS-compliant algorithms are not specified. See SSH Access Guide for detailed configuration.

Success! CloudMapper is now ready to scan and visualize your AWS infrastructure.

Method 2: Direct EC2 Launch from AMI

Manual Setup Required: This method requires manual configuration of IAM roles, security groups, and encryption settings. CloudFormation deployment (Method 1) is recommended for most users.

Create IAM Role for CloudMapper

Before launching the instance, create an IAM role with necessary permissions.

Using AWS CLI:

# Create trust policy file
cat > cloudmapper-trust-policy.json << 'EOF'
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ec2.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}
EOF

# Create IAM role
aws iam create-role \
  --role-name CloudMapperInstanceRole \
  --assume-role-policy-document file://cloudmapper-trust-policy.json \
  --description "CloudMapper read-only access role"

# Attach managed policies
aws iam attach-role-policy \
  --role-name CloudMapperInstanceRole \
  --policy-arn arn:aws:iam::aws:policy/ReadOnlyAccess

aws iam attach-role-policy \
  --role-name CloudMapperInstanceRole \
  --policy-arn arn:aws:iam::aws:policy/AmazonSSMManagedInstanceCore

# Create instance profile
aws iam create-instance-profile \
  --instance-profile-name CloudMapperInstanceProfile

# Add role to instance profile
aws iam add-role-to-instance-profile \
  --instance-profile-name CloudMapperInstanceProfile \
  --role-name CloudMapperInstanceRole

Via AWS Console: Navigate to IAM → Roles → Create Role → EC2 → Attach ReadOnlyAccess and AmazonSSMManagedInstanceCore policies.

Create Security Group

Create a security group that allows HTTPS/HTTP access to CloudMapper.

# Create security group
aws ec2 create-security-group \
  --group-name CloudMapperSG \
  --description "CloudMapper web interface access" \
  --vpc-id vpc-xxxxxxxxx

# Add HTTPS ingress rule
aws ec2 authorize-security-group-ingress \
  --group-id sg-xxxxxxxxx \
  --protocol tcp \
  --port 443 \
  --cidr 10.0.0.0/8

# Add HTTP ingress rule
aws ec2 authorize-security-group-ingress \
  --group-id sg-xxxxxxxxx \
  --protocol tcp \
  --port 80 \
  --cidr 10.0.0.0/8

# Optional: Add SSH access (not recommended)
# aws ec2 authorize-security-group-ingress \
#   --group-id sg-xxxxxxxxx \
#   --protocol tcp \
#   --port 22 \
#   --cidr 10.0.0.0/8

Launch EC2 Instance from AMI

Launch the CloudMapper instance with encryption options.

Encryption Recommendation: Enable EBS encryption when launching. You can choose between AWS-managed keys (default) or your own customer-managed KMS key.

Option 1: Launch with AWS-managed encryption (Recommended)

aws ec2 run-instances \
  --image-id ami-0b8fb75ca1181d1e0 \
  --instance-type t3.medium \
  --iam-instance-profile Name=CloudMapperInstanceProfile \
  --security-group-ids sg-xxxxxxxxx \
  --subnet-id subnet-xxxxxxxxx \
  --block-device-mappings '[
    {
      "DeviceName": "/dev/xvda",
      "Ebs": {
        "VolumeSize": 50,
        "VolumeType": "gp3",
        "DeleteOnTermination": false,
        "Encrypted": true
      }
    }
  ]' \
  --metadata-options 'HttpTokens=required,HttpPutResponseHopLimit=1' \
  --disable-api-termination \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=CloudMapper}]'

Option 2: Launch with customer-managed KMS key

aws ec2 run-instances \
  --image-id ami-0b8fb75ca1181d1e0 \
  --instance-type t3.medium \
  --iam-instance-profile Name=CloudMapperInstanceProfile \
  --security-group-ids sg-xxxxxxxxx \
  --subnet-id subnet-xxxxxxxxx \
  --block-device-mappings '[
    {
      "DeviceName": "/dev/xvda",
      "Ebs": {
        "VolumeSize": 50,
        "VolumeType": "gp3",
        "DeleteOnTermination": false,
        "Encrypted": true,
        "KmsKeyId": "arn:aws:kms:us-east-1:123456789012:key/12345678-1234-1234-1234-123456789012"
      }
    }
  ]' \
  --metadata-options 'HttpTokens=required,HttpPutResponseHopLimit=1' \
  --disable-api-termination \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=CloudMapper}]'

Via AWS Console: Go to EC2 → Launch Instance → Search for CloudMapper AMI → Configure encryption in Storage section → Enable "Encrypted" and optionally select your KMS key.

Verify Encryption and Access Instance

Confirm encryption is enabled and access your CloudMapper instance.

Verify EBS Encryption:

# Get instance details
aws ec2 describe-instances \
  --instance-ids i-xxxxxxxxxxxxxxxxx \
  --query 'Reservations[0].Instances[0].[InstanceId,PublicIpAddress,PrivateIpAddress]' \
  --output table

# Verify volume encryption
aws ec2 describe-volumes \
  --filters "Name=attachment.instance-id,Values=i-xxxxxxxxxxxxxxxxx" \
  --query 'Volumes[*].[VolumeId,Encrypted,KmsKeyId,Size,VolumeType]' \
  --output table

Encryption Verified: The "Encrypted" column should show "True" and "KmsKeyId" should show either your customer-managed key ARN or "alias/aws/ebs" for AWS-managed encryption.

Access Your Instance:

# Via SSM Session Manager (recommended)
aws ssm start-session --target i-xxxxxxxxxxxxxxxxx

# Via HTTPS (in browser)
https://your-instance-public-ip

IAM Policies & Permissions

Pre-configured: The CloudFormation template automatically creates the necessary IAM role with appropriate permissions. No manual IAM configuration required.

Applied IAM Policies

ReadOnlyAccess AWS Managed
Broad read-only permissions across AWS services for comprehensive infrastructure discovery.
AmazonSSMManagedInstanceCore AWS Managed
Enables AWS Systems Manager Session Manager for secure shell access without SSH keys.
AWSBackupServiceRolePolicyForBackup AWS Managed (Backup Service Only)
Applied to backup service role when backups are enabled. Allows AWS Backup to create snapshots and backups of your CloudMapper instance.
AWSBackupServiceRolePolicyForRestores AWS Managed (Backup Service Only)
Applied to backup service role when backups are enabled. Allows AWS Backup to restore instances and volumes from backup recovery points.

What This Means

Can Read: All AWS resource configurations, metadata, and relationships across your account.
Cannot Modify: No permissions to create, update, or delete any AWS resources.
SSM Access: Allows secure terminal access through AWS console without SSH keys.
CloudWatch: Can send metrics and logs for monitoring and troubleshooting.

Built-in Services

AWS Systems Manager

Status: ALWAYS ENABLED

Recommended access method. SSM Session Manager provides secure, audited terminal access. Access via AWS Console → Systems Manager → Session Manager.

SSH Access

Status: Optional (Disabled by Default)

Can be enabled with EnableSSH=true and KeyName parameter. Hardened with public key only, ec2-user access. Required for AWS Marketplace scanning.

CloudWatch Integration

Status: Enabled by Default

Automatic metrics and logs collection for monitoring instance health and application performance.

AWS Backup

Status: Optional (Recommended)

Daily automated backups with 30-day retention and 7-day cold storage transition. EBS deletion protection always ON.

CloudFormation Stack Outputs

After successful deployment, your CloudFormation stack provides these outputs for easy access and management.

Instance Information

CloudMapperInstanceId: EC2 instance ID
CloudMapperPrivateIP: Private IP (always available)
CloudMapperPublicIP: Public IP (if enabled)
CloudMapperURL: HTTPS web URL (if public IP enabled)

Access & Management

SSMSessionCommand: Ready-to-use SSM command
BackupVaultName: Backup vault (if enabled)
Version: Deployed CloudMapper version

View Stack Outputs:

# List all stack outputs
aws cloudformation describe-stacks --stack-name your-cloudmapper-stack \
  --query 'Stacks[0].Outputs' --output table

# Get specific output (e.g., SSM command)
aws cloudformation describe-stacks --stack-name your-cloudmapper-stack \
  --query 'Stacks[0].Outputs[?OutputKey==`SSMSessionCommand`].OutputValue' \
  --output text

Zero Configuration Required: CloudMapper automatically detects its AWS region and begins discovery using the attached IAM role permissions.

Additional Configuration

Load Balancer with Trusted Certificate

Deploy an ALB with ACM certificate for production environments.

Setup Guide

OIDC SSO Setup

Configure single sign-on with your identity provider.

Learn More

Need Help? Check our Troubleshooting Guide, join GitHub Discussions, or report an issue.

Documentation

AWS Marketplace