garfieldwtf/cowrie repository overview

⁠Cowrie SSH/Telnet Honeypot - Docker Image by garfieldwtf

This Docker image provides a ready-to-run Cowrie⁠ medium-interaction SSH and Telnet honeypot. Cowrie is designed to log brute-force attacks and the shell interaction performed by the attacker.

This image is built directly from the official Cowrie GitHub repository, offering a lightweight and easily deployable way to observe and log malicious activity on your network.

⁠✨ Features

• Based on Official Source: Built from the latest stable code in the official Cowrie repository⁠.
• SSH & Telnet Support: Listens for both SSH (port 2222 by default in the image) and Telnet (port 2223 by default) connections.
• Configurable: Easily customize Cowrie's behavior using environment variables or by mounting your own cowrie.cfg file.
• Persistent Logging: Store logs, downloads, and attacker interactions on your host machine by mounting volumes.
• Lightweight: Minimal image size, focusing only on the essential components to run Cowrie efficiently.
• Easy to Use: Simple docker run or docker-compose commands to get started in seconds.

⁠🚀 Quick Start

Get a Cowrie instance up and running instantly with default settings:

docker run -d \
  --name cowrie-honeypot \
  -p 2222:2222 \
  -p 2223:2223 \
  garfieldwtf/cowrie:latest

This command will:

• Start a container named cowrie-honeypot in the background (-d).
• Map the host's port 2222 to the container's port 2222 (SSH).
• Map the host's port 2223 to the container's port 2223 (Telnet).
• Use the default configuration.

Test the honeypot:

ssh -p 2222 root@localhost
# Password: 123456 (or any password, it's a honeypot!)

⁠📋 Prerequisites

• Docker: Make sure Docker is installed on your system. Get it from docker.com⁠.
• Basic Docker Knowledge: Familiarity with docker run, volumes, and environment variables is helpful.

⁠🔧 Configuration

Cowrie is highly configurable. There are two primary ways to configure this image:

⁠1. Using Environment Variables

The image supports overriding common settings via environment variables. This is the simplest method for basic changes.

Example with environment variables:

docker run -d \
  --name cowrie-honeypot \
  -e COWRIE_HOSTNAME="webserver" \
  -e COWRIE_SSH_PORT=2222 \
  -p 2222:2222 \
  -p 2223:2223 \
  garfieldwtf/cowrie:latest

⁠2. Using a Custom cowrie.cfg File

For advanced configuration (e.g., enabling MySQL output, changing download handling), mount your own configuration file.

1. Create a custom config file: Copy the default cowrie.cfg from the Cowrie project⁠ and modify it as needed. Save it, for example, as /path/to/your/cowrie.cfg.
2. Mount the file into the container:

   docker run -d \
     --name cowrie-honeypot \
     -v /path/to/your/cowrie.cfg:/cowrie/cowrie-git/etc/cowrie.cfg \
     -p 2222:2222 \
     -p 2223:2223 \
     garfieldwtf/cowrie:latest
   

   Copy

⁠💾 Persisting Data (Logs, Downloads, etc.)

To prevent data loss when the container is removed, mount volumes for important directories.

• Logs: Usually stored in /cowrie/cowrie-git/var/log/cowrie/
• Downloads: Files downloaded by attackers are stored in /cowrie/cowrie-git/var/lib/cowrie/downloads/
• User Database: /cowrie/cowrie-git/etc/userdb.txt

Example with persistent volumes:

docker run -d \
  --name cowrie-honeypot \
  -v /host/path/cowrie/log:/cowrie/cowrie-git/var/log/cowrie \
  -v /host/path/cowrie/downloads:/cowrie/cowrie-git/var/lib/cowrie/downloads \
  -p 2222:2222 \
  -p 2223:2223 \
  garfieldwtf/cowrie:latest

⁠🐳 Using Docker Compose

For a more manageable setup, especially with custom configs and volumes, use docker-compose.yml.

Create a docker-compose.yml file:

version: '3.8'

services:
  cowrie:
    image: garfieldwtf/cowrie:latest
    container_name: cowrie-honeypot
    restart: unless-stopped
    ports:
      - "2222:2222"
      - "2223:2223"
    environment:
      - COWRIE_HOSTNAME=honeypot
      # - COWRIE_OUTPUT_JSONLOG=true # Add other env vars as needed
    volumes:
      # Mount custom config (optional)
      # - ./cowrie.cfg:/cowrie/cowrie-git/etc/cowrie.cfg
      # Persist logs and downloads
      - ./cowrie/log:/cowrie/cowrie-git/var/log/cowrie
      - ./cowrie/downloads:/cowrie/cowrie-git/var/lib/cowrie/downloads
    # Uncomment to run as a specific user/group (e.g., UID 1000)
    # user: "1000:1000"

Then run:

docker-compose up -d

⁠📂 Image Details

• Base Image: [Specify base image, e.g., python:3.11-slim-bookworm]
• Working Directory: /cowrie/cowrie-git
• Exposed Ports:
  • 2222 (SSH)
  • 2223 (Telnet)
• Entrypoint Script: docker-entrypoint.sh (Handles initial setup and config overrides)
• User: Runs as a non-root user (cowrie) for security.

⁠📜 Logs and Monitoring

View live logs from your honeypot:

docker logs -f cowrie-honeypot

Access the main Cowrie log file inside the persistent volume:

tail -f /host/path/cowrie/log/cowrie.json

⁠🔒 Security Considerations

• Port Exposure: Be extremely careful when exposing ports directly to the internet. Ports 2222 and 2223 will be attacked immediately. Ensure your host firewall is configured appropriately.
• Container Updates: Regularly pull the latest image (docker pull garfieldwtf/cowrie:latest) and recreate your container to get the latest Cowrie updates and security fixes.
• Run as Non-Root: The container runs Cowrie with a non-root user by default. Avoid overriding this unless necessary.
• Network Isolation: Consider running the honeypot in an isolated Docker network or a VM segment to limit potential lateral movement, should the container be compromised (though Cowrie is designed to prevent this).

⁠🤝 Contributing

If you encounter issues or have suggestions for this Docker image, please feel free to open an issue or pull request on the GitHub repository for this image⁠ (Note: You'll need to create this repo if it doesn't exist).

For issues specific to Cowrie itself, please refer to the official Cowrie GitHub repository⁠.

⁠📄 License

This Docker image packaging is provided under the MIT License⁠. Cowrie itself is licensed under the Hippocratic License - please review its terms on the official project page⁠.