6.1 SSM Agent, Hybrid Activation & Session Manager

AWS Systems Manager Core Architecture & SSM Agent

AWS Systems Manager (SSM) provides centralized operational visibility and control over cloud infrastructure, on-premises virtual machines, and edge devices. At the core of Systems Manager is the SSM Agent, an open-source software daemon installed inside the operating system that initiates and maintains bi-directional communication channels with AWS Systems Manager service endpoints.

The SSM Agent Lifecycle and Operating Model

The SSM Agent executes as an operating system service (amazon-ssm-agent on Linux, macOS, and Windows). It comes pre-installed on Amazon Linux 1/2/2023, Ubuntu Server (16.04, 18.04, 20.04, 22.04 LTS), macOS, and Windows Server AMIs. On unbundled operating systems (such as Red Hat Enterprise Linux, CentOS, Rocky Linux, SUSE Linux, or custom images), the agent must be installed via package managers (yum, dnf, apt, or snap).

Unlike legacy management protocols (such as SSH, RDP, or WinRM) that require open listening daemon ports and incoming network connections, the SSM Agent operates on an inversion-of-control (IoC) network architecture:

1. Outbound Polling and WebSockets: The agent initiates persistent, outbound HTTPS connections over TCP port 443 to AWS Systems Manager service endpoints.
2. Zero Inbound Ports: Security groups and host-level firewalls (such as iptables or Windows Defender Firewall) require zero inbound open ports. Inbound rules for port 22 (SSH) and port 3389 (RDP) must be completely eliminated.
3. Long-Polling and Command Channels: For Run Command and State Manager, the agent polls the ssm and ec2messages service channels. For Session Manager, the agent opens a bi-directional multiplexed WebSocket connection to the ssmmessages endpoint, allowing real-time interactive terminal emulation without direct network ingress.

[ EC2 Instance / On-Premises Host ]
  │
  │  Outbound Only (TCP Port 443 HTTPS / WebSockets)
  ▼
[ Internet Gateway / NAT Gateway / VPC Endpoints (PrivateLink) ]
  │
  ├──> com.amazonaws.<region>.ssm          (Control Plane / Metadata)
  ├──> com.amazonaws.<region>.ssmmessages   (Session Manager WebSockets)
  └──> com.amazonaws.<region>.ec2messages   (Run Command Messaging)

IAM Instance Profile: AmazonSSMManagedInstanceCore vs. Legacy Policies

For an Amazon EC2 instance to register with Systems Manager and execute commands, it must possess an attached IAM instance profile containing valid Systems Manager API authorization.

[!IMPORTANT] DOP-C02 Exam Trap: The managed policy AmazonEC2RoleforSSM is deprecated and must never be used in modern architectures or exam solutions. AmazonEC2RoleforSSM granted excessively broad permissions, including full S3 bucket access, resource creation, and broad CloudWatch writes. The modern, least-privilege AWS-managed policy is AmazonSSMManagedInstanceCore.

AmazonSSMManagedInstanceCore grants only the granular permissions strictly required for core agent functionality:

• ssm:DescribeAssociation, ssm:GetDeployablePatchSnapshotForInstance, ssm:GetDocument, ssm:GetManifest, ssm:GetParameter, ssm:GetParameters, ssm:ListAssociations, ssm:ListInstanceAssociations
• ssm:PutInventory, ssm:PutComplianceItems, ssm:PutConfigurePackageResult, ssm:UpdateAssociationStatus, ssm:UpdateInstanceAssociationStatus, ssm:UpdateInstanceInformation
• ssmmessages:CreateControlChannel, ssmmessages:CreateDataChannel, ssmmessages:OpenControlChannel, ssmmessages:OpenDataChannel
• ec2messages:AcknowledgeMessage, ec2messages:DeleteMessage, ec2messages:FailMessage, ec2messages:GetEndpoint, ec2messages:GetMessages, ec2messages:SendReply

If custom S3 bucket access (for command output or patch storage) or CloudWatch Logs streaming is required, create a targeted inline policy or complementary customer-managed IAM policy attached to the instance role rather than widening core agent permissions.

---

Private VPC Connectivity via AWS PrivateLink (VPC Endpoints)

In secure enterprise architectures, workloads frequently reside in private subnets with no Internet Gateway (IGW), no NAT Gateway, and no egress route to the public internet (0.0.0.0/0). Under these isolated conditions, the SSM Agent cannot reach public AWS endpoints.

To establish private connectivity, you must deploy Interface VPC Endpoints (powered by AWS PrivateLink) within the VPC subnets. The architecture requires three mandatory endpoints for foundational operation:

Supporting Endpoints for Enterprise Operations

If advanced features are enabled, additional endpoints must be provisioned in the VPC:

• Amazon S3: Required for downloading large software packages, scripts, or uploading Session Manager and Run Command logs. Use a Gateway VPC Endpoint (com.amazonaws.<region>.s3) attached to the route table for zero-cost, high-throughput S3 traffic.
• Amazon CloudWatch Logs: Required for streaming session transcripts and command output (com.amazonaws.<region>.logs).
• AWS KMS: Required for decrypting SecureString parameters and KMS-encrypted Session Manager streams (com.amazonaws.<region>.kms).

Security Group Configuration for VPC Endpoints

A frequent misconfiguration in private VPC deployments involves endpoint security groups:

• The security group attached to the Interface VPC Endpoints must permit inbound TCP port 443 from the private instance security groups (or the VPC CIDR block).
• The security group attached to the EC2 instances must permit outbound TCP port 443 destined for the VPC endpoint IP addresses or VPC CIDR block.
• Enable Private DNS names on all interface endpoints so that standard AWS endpoint hostnames (e.g., ssm.us-east-1.amazonaws.com) automatically resolve to the private elastic network interface (ENI) IP addresses within the VPC.

---

Hybrid Activations for On-Premises & Multi-Cloud Fleets

AWS Systems Manager is not limited to EC2 instances. Through Hybrid Activations, Systems Manager treats on-premises physical servers, VMware ESXi hypervisors, KVM hosts, Nutanix clusters, and virtual machines in other clouds (Azure, GCP) as first-class managed nodes.

The Hybrid Activation Workflow

[ Administrator / Automation Pipeline ]
  │
  ├─ 1. Calls ssm:CreateActivation
  ▼
[ AWS Systems Manager Service ] ──> Generates: Activation ID + Activation Code
                                              │
                                              │ (Secure Distribution)
                                              ▼
                                   [ On-Premises Server / VM ]
                                     │
                                     ├─ 2. Installs SSM Agent
                                     ├─ 3. amazon-ssm-agent -register
                                     │     -code "..." -id "..."
                                     ▼
                                   [ Registered Managed Node (mi-0123456789abcdef0) ]

1. Create an IAM Service Role: Create an IAM role for hybrid instances trusting the service principal ssm.amazonaws.com. Attach the AWS-managed policy AmazonSSMManagedInstanceCore (add AmazonSSMDirectoryServiceAccess only if the hybrid nodes must join an AWS Directory Service domain):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Service": "ssm.amazonaws.com"
      },
      "Action": "sts:AssumeRole"
    }
  ]
}

1. Generate Hybrid Activation Credentials: Use the AWS CLI or SDK to invoke CreateActivation:

aws ssm create-activation \
    --default-instance-name "OnPrem-AppServer-Prod" \
    --iam-role "SSMHybridServiceRole" \
    --registration-limit 100 \
    --expiration-date "2026-10-15T00:00:00Z" \
    --region "us-east-1"

This API call outputs two sensitive artifacts: the ActivationId (a unique GUID) and the ActivationCode (a single-use or multi-use secret token). The --registration-limit specifies the maximum number of servers that can register with this token, and --expiration-date limits the onboarding window (up to a maximum of 30 days).

1. Register the Target Server: On the target on-premises machine, install the SSM Agent and execute the registration command:

sudo systemctl stop amazon-ssm-agent
sudo amazon-ssm-agent -register \
    -code "YOUR_ACTIVATION_CODE" \
    -id "YOUR_ACTIVATION_ID" \
    -region "us-east-1"
sudo systemctl start amazon-ssm-agent

1. Node Identification: Once registered, the hybrid server appears in Systems Manager Fleet Manager with an instance ID prefixed by mi- (Managed Instance, e.g., mi-0a9b8c7d6e5f43210), distinguishing it from native EC2 instances (i-).

Standard vs. Advanced Instances Tier

Systems Manager offers two tiers for hybrid managed instances:

[!TIP] If an exam question requires interactive shell access via Session Manager into on-premises servers or multi-cloud instances, you must configure the Systems Manager Advanced Instances Tier for hybrid nodes.

Systems Manager Session Manager: Secure Bastionless Shell Access

Traditional infrastructure administration relied heavily on bastion hosts (jump boxes) deployed in public subnets, exposing SSH (TCP port 22) or RDP (TCP port 3389) to the internet or corporate VPNs. This operational model introduces severe security liabilities: public IP exposure, ongoing patching overhead of bastion appliances, complex SSH key pair lifecycle distribution, and a lack of tamper-proof centralized session auditing.

AWS Systems Manager Session Manager replaces bastion hosts entirely by providing a fully managed, browser- and CLI-based interactive shell, non-interactive command tunneling, and port forwarding.

Bastion Host vs. Session Manager Architectural Comparison

Auditing, Logging, and KMS Envelope Encryption

Session Manager provides enterprise-grade governance by capturing all interactive shell input and output, streaming it directly to persistent AWS logging services without saving transcripts to local instance disks.

1. Amazon S3 Logging: Session Manager delivers complete raw session transcripts to a designated S3 bucket. To prevent tampering, configure S3 Object Lock in compliance mode and enforce server-side encryption with an AWS KMS Customer Managed Key (CMK).
2. Amazon CloudWatch Logs: Real-time log streaming delivers session data into dedicated CloudWatch Log Streams, enabling metric filters, CloudWatch Logs Insights querying, and automated alerts upon detection of dangerous commands (e.g., rm -rf / or unauthorized sudo attempts).
3. End-to-End KMS Encryption: While session traffic over WebSockets is encrypted via TLS by default, enterprise compliance frameworks require double-layer encryption. By configuring a KMS CMK in Session Manager preferences, session payloads are encrypted at the client/agent level before transmission across the WebSocket tunnel.

Advanced Capabilities: Port Forwarding & Non-Interactive SSH

Session Manager is not restricted to standard shell access; it supports multiplexed tunneling protocols via SSM Documents:

• Local Port Forwarding (AWS-StartPortForwardingSession): Forwards a local port on an administrator workstation directly to a port on the remote managed node:

aws ssm start-session \
    --target i-0123456789abcdef0 \
    --document-name AWS-StartPortForwardingSession \
    --parameters '{"portNumber":["80"],"localPortNumber":["8080"]}'

• Remote Port Forwarding to Private Resources (AWS-StartPortForwardingSessionToRemoteHost): Allows an engineer to connect to private database instances (such as Amazon RDS, Aurora, or private ElastiCache clusters) that cannot run the SSM Agent themselves. The session uses an intermediate private EC2 instance as an SSM proxy:

aws ssm start-session \
    --target i-0123456789abcdef0 \
    --document-name AWS-StartPortForwardingSessionToRemoteHost \
    --parameters '{"host":["mydb.cluster-xyz.us-east-1.rds.amazonaws.com"],"portNumber":["5432"],"localPortNumber":["5432"]}'

• Native SSH/SCP Tunneling (AWS-StartSSHSession): Engineers who require existing developer tool integrations (such as Visual Studio Code Remote, Ansible over SSH, or scp file copying) can route native SSH over Session Manager by adding a ProxyCommand directive to their local ~/.ssh/config:

# SSH over AWS Systems Manager Session Manager
host i-* mi-*
    ProxyCommand sh -c "aws ssm start-session --target %h --document-name AWS-StartSSHSession --parameters 'portNumber=%p'"

Granular IAM Authorization and Tag-Based Access Control

Enterprise security policies dictate that developers must only access development instances, while production instances require elevated privileges. Session Manager enforces this through IAM policy condition keys:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "AllowSessionStartWithSpecificDocument",
      "Effect": "Allow",
      "Action": [
        "ssm:StartSession"
      ],
      "Resource": [
        "arn:aws:ssm:*:*:document/SSM-SessionManagerRunShell",
        "arn:aws:ec2:*:*:instance/*"
      ],
      "Condition": {
        "StringEquals": {
          "ssm:resourceTag/Environment": "Development"
        }
      }
    },
    {
      "Sid": "AllowCoreSessionManagerActions",
      "Effect": "Allow",
      "Action": [
        "ssm:DescribeSessions",
        "ssm:GetConnectionStatus",
        "ssm:DescribeInstanceInformation",
        "ssm:DescribeInstanceProperties"
      ],
      "Resource": "*"
    },
    {
      "Sid": "AllowSessionTerminationForSelfOnly",
      "Effect": "Allow",
      "Action": [
        "ssm:TerminateSession",
        "ssm:ResumeSession"
      ],
      "Resource": [
        "arn:aws:ssm:*:*:session/${aws:username}-*"
      ]
    }
  ]
}

Session Manager Configuration Preferences

Through Systems Manager Session Manager preferences, organizations globally enforce:

• Idle Session Timeout: Terminates inactive shell sessions automatically after a configurable duration (1 to 60 minutes; 20 minutes default).
• Run As Operating System User: Maps authenticated IAM users to a specific, restricted OS account (e.g., ssm-user or dev-operator) instead of granting unrestricted root or administrative access.
• Mandatory S3 / CloudWatch Logging: Blocks session creation if the target logging destinations are unreachable or if encryption keys cannot be accessed, preventing "dark" unaudited terminal sessions.