mushorg · north-echo · Apr 12, 2026
diff --git a/docs/wiki/Attack-Patterns-and-Analysis.md b/docs/wiki/Attack-Patterns-and-Analysis.md
@@ -0,0 +1,80 @@
+# Attack Patterns and Analysis
+
+This page documents common attack patterns observed against Conpot honeypots. Understanding what to expect helps operators distinguish noise from targeted activity.
+
+## Traffic Tiers
+
+Internet-facing honeypot traffic generally falls into three tiers:
+
+### Tier 1: Internet Background Noise
+- **SSH brute-force** — Mirai variants and credential-stuffing bots. Arrives within hours of deployment. Uses well-known default credential lists (`root/admin`, `root/123456`, `root/P`, `admin/admin`). Automated, high-volume, not ICS-aware.
+- **HTTP scanning** — Web crawlers, vulnerability scanners, and bots probing for web application vulnerabilities. Will hit your HMI on port 80.
+- **Generic port probes** — SYN scans from Shodan, Censys, ZoomEye, and similar internet-wide scanners. These index your open ports but don't send protocol-specific payloads.
+
+**Expected timeline:** Minutes to hours after deployment.
+
+### Tier 2: Protocol-Aware Scanning
+- **Modbus device identification** — Function code 43 (Read Device Identification) or reads of holding registers 0-10. Often from researchers or scanning platforms cataloging ICS devices.
+- **S7comm connection requests** — COTP connection setup followed by S7 communication setup. SZL reads (system info) are reconnaissance. Usually automated.
+- **BACnet Who-Is broadcasts** — BACnet device discovery. Common from building automation scanners.
+- **SNMP walks** — Full MIB walks using community string `public`. Used for device fingerprinting.
+
+**Expected timeline:** Days to weeks. Depends on how quickly internet indexers discover your honeypot.
+
+### Tier 3: Targeted Interaction
+- **Modbus write commands** — Function codes 5 (Write Single Coil), 6 (Write Single Register), 15 (Write Multiple Coils), 16 (Write Multiple Registers). Someone attempting to alter device state. Rare and significant.
+- **S7 PLC control** — CPU start/stop commands, program uploads/downloads, memory writes. Extremely rare against honeypots.
+- **Repeated visits from the same source** — An IP that returns multiple times with increasingly specific queries is likely a human operator, not a bot.
+
+**Expected timeline:** Weeks to months, if ever. This is the high-value data.
+
+## SSH Attack Patterns
+
+If you're running an SSH honeypot (e.g., Cowrie) alongside Conpot, you'll see significantly more activity:
+
+### Common Credential Lists
+Botnets use dictionaries derived from default credentials in IoT devices and ICS equipment:
+- `root/root`, `root/admin`, `root/123456`, `root/password`
+- `admin/admin`, `admin/1234`
+- Device-specific: `root/P` (Mirai), `ubnt/ubnt`, `pi/raspberry`
+- ICS-specific: `ADMIN/ADMIN`, `USER/USER` (some PLCs ship with these)
+
+### Post-Authentication Behavior
+When a honeypot accepts credentials, bots typically:
+1. **Fingerprint** — `uname -a`, `cat /proc/cpuinfo`, `free -m`
+2. **Kill competitors** — Kill processes belonging to other botnets
+3. **Download payload** — `curl`/`wget` from a C2 server, sometimes with `/dev/tcp` fallback
+4. **Establish persistence** — Inject SSH keys into `authorized_keys`, set immutable flag with `chattr +ai`
+5. **Beacon** — Send confirmation back to C2 (e.g., echo a specific string)
+
+### Distinguishing Bots from Humans
+| Signal | Bot | Human |
+|--------|-----|-------|
+| Timing | Milliseconds between commands | Seconds to minutes |
+| Credential rotation | Systematic dictionary | Few targeted guesses |
+| Commands | Identical across sessions | Adapted to responses |
+| Payload | Same binary every time | May compile on target |
+| Sessions | Parallel, many at once | Sequential, one at a time |
+
+## Analysis Tips
+
+### Correlating with Threat Intelligence
+Cross-reference source IPs against:
+- **GreyNoise** — classifies IPs as benign scanners vs. malicious
+- **AbuseIPDB** — community-reported malicious IPs
+- **Shodan** — shows what services the attacker's IP exposes (often compromised devices themselves)
+- **CISA advisories** — match observed TTPs against published ICS threat alerts
+
+### Tracking Campaigns
+Group related sessions by:
+- SSH key fingerprint (same key = same operator)
+- C2 server addresses in download commands
+- Malware hash (SHA256 of captured binaries)
+- Credential list overlap
+- ASN clustering (multiple IPs from the same hosting provider)
+
+### What to Report
+If you observe Tier 3 activity (actual ICS manipulation attempts), consider:
+- Reporting to CISA via their [incident reporting form](https://www.cisa.gov/report)
+- Sharing IOCs (IPs, hashes, C2 domains) with the ICS-CERT community
+- Contributing anonymized data to threat intelligence platforms
diff --git a/docs/wiki/Home.md b/docs/wiki/Home.md
@@ -0,0 +1,22 @@
+# Conpot Community Wiki
+
+Community-driven documentation for [Conpot](https://github.com/mushorg/conpot), the ICS/SCADA honeypot.
+
+## Deployment
+
+- [Production Deployment Guide](Production-Deployment-Guide) — Rootless Podman, security hardening, firewall isolation
+- [Writing Custom Templates](Writing-Custom-Templates) — Create device profiles that mimic real ICS equipment
+
+## Research
+
+- [Attack Patterns and Analysis](Attack-Patterns-and-Analysis) — What to expect from captured honeypot traffic
+- [ICS Honeypot Research](ICS-Honeypot-Research) — Published papers and resources
+
+## Reference
+
+- [Common Problems](Common-Problems) — Troubleshooting FAQ
+
+## Google Summer of Code
+
+- [Getting started](GSoC:-Getting-started-with-Conpot!)
+- [GSoC 2018 Final Report](GSoC-2018---Final-Report)
diff --git a/docs/wiki/ICS-Honeypot-Research.md b/docs/wiki/ICS-Honeypot-Research.md
@@ -0,0 +1,48 @@
+# ICS Honeypot Research
+
+A curated list of published research on ICS/SCADA honeypots, including papers that use or reference Conpot.
+
+## Foundational Papers
+
+- **Serbanescu, A. V., et al.** (2015). *ICS Threat Analysis Using a Large-Scale Honeynet.* — Early large-scale study using Conpot deployments across multiple countries to analyze ICS-targeted scanning patterns.
+
+- **Antrobus, R., et al.** (2019). *The Forgotten I in IIoT: A Vulnerability Scanner for Industrial Internet of Things.* IEEE International Symposium on Software Reliability Engineering. — Demonstrates how ICS honeypots can be fingerprinted and proposes improvements.
+
+- **Jicha, A., et al.** (2016). *SCADA Honeypots: An In-Depth Analysis of Conpot.* IEEE Conference on Communications and Network Security. — Detailed analysis of Conpot's protocol emulation fidelity and detection vectors.
+
+## Honeypot Design and Evasion
+
+- **Vetterl, A. & Clayton, R.** (2018). *Bitter Harvest: Systematically Fingerprinting Low- and Medium-Interaction Honeypots at Internet Scale.* USENIX Workshop on Offensive Technologies (WOOT). — Demonstrates fingerprinting of Conpot and other honeypots via protocol response analysis. Essential reading for improving template realism.
+
+- **Zamiri-Gourabi, M., et al.** (2019). *Gas What? Revisiting and Improving the Classification of ICS Honeypots.* — Evaluates classification techniques for distinguishing real ICS devices from honeypots.
+
+## Threat Landscape Studies
+
+- **Mirian, A., et al.** (2016). *An Internet-Wide View of ICS Devices.* IEEE International Conference on Privacy, Security and Trust. — Censys-based census of internet-exposed ICS devices. Provides context for what scanning tools find.
+
+- **Samtani, S., et al.** (2018). *Identifying SCADA Vulnerabilities Using Passive and Active Vulnerability Assessment Techniques.* IEEE Conference on Intelligence and Security Informatics. — Combines dark web intelligence with honeypot data.
+
+## Deployment Methodologies
+
+- **Vasilomanolakis, E., et al.** (2016). *Multi-Stage Attack Detection and Signature Generation with ICS Honeypots.* IEEE/IFIP Network Operations and Management Symposium. — Proposes multi-stage attack detection using correlated honeypot events.
+
+- **Hink, R. C. B., et al.** (2015). *Assessing and Reducing the Vulnerability of SCADA Systems.* In *Securing Critical Infrastructures and Critical Control Systems: Approaches for Threat Protection.* — Broader context for honeypot deployment within ICS security programs.
+
+## Related Projects
+
+- [Conpot](https://github.com/mushorg/conpot) — ICS/SCADA honeypot (Modbus, S7comm, BACnet, SNMP, HTTP)
+- [GRFICSv2](https://github.com/Fortiphyd/GRFICSv2) — Virtual ICS environment for security research
+- [GRFICS](https://github.com/djformby/GRFICS) — Original graphical realism framework for ICS
+- [HoneyPLC](https://github.com/sefcom/honeyplc) — High-interaction PLC honeypot
+- [Cowrie](https://github.com/cowrie/cowrie) — SSH/Telnet honeypot, often deployed alongside Conpot
+- [T-Pot](https://github.com/telekom-security/tpotce) — Multi-honeypot platform that includes Conpot
+- [OpenPLC](https://github.com/thiagoralves/OpenPLC_v3) — Open-source PLC runtime (can be used for high-interaction honeypots)
+
+## Datasets
+
+- [ICS-PCAP](https://github.com/automayt/ICS-pcap) — Collection of ICS protocol packet captures
+- [Conpot log samples](https://github.com/mushorg/conpot/tree/main/docs) — Example output from Conpot protocol handlers
+
+## Contributing
+
+Know of a paper or project that should be listed here? Open an issue or submit a PR referencing this wiki page.
diff --git a/docs/wiki/Production-Deployment-Guide.md b/docs/wiki/Production-Deployment-Guide.md
@@ -0,0 +1,201 @@
+# Production Deployment Guide
+
+This guide covers deploying Conpot in a production honeypot environment using rootless Podman with security hardening. While Conpot can be run directly via `pip install`, containerized deployment provides better isolation — especially important when capturing live attacker traffic.
+
+## Architecture Overview
+
+A typical ICS honeypot deployment consists of:
+
+- **Conpot container** — emulates ICS protocols (Modbus, S7comm, BACnet, SNMP, HTTP/HMI)
+- **Log ingestion pipeline** — tails Conpot JSON logs and stores events in a database
+- **Firewall zones** — separates honeypot-facing traffic from management access
+
+```
+Internet --> [Firewall] --> Honeypot Zone (ICS ports) --> Conpot Container
+                        --> Management Zone (SSH, dashboard) --> Admin only
+```
+
+## Prerequisites
+
+- Linux host (RHEL/Fedora/Rocky recommended for SELinux support)
+- Podman (rootless)
+- A dedicated non-root user (e.g., `honeypot`)
+- firewalld with zone support
+
+## Step 1: Create a Dedicated User
+
+```bash
+sudo useradd -r -m -s /bin/bash honeypot
+sudo loginctl enable-linger honeypot   # allows rootless containers to persist
+```
+
+## Step 2: Directory Structure
+
+```bash
+sudo -u honeypot mkdir -p /home/honeypot/honeypot/{templates,config,conpot-logs,data}
+```
+
+- `templates/` — custom Conpot templates (device profiles)
+- `config/` — `conpot.cfg` configuration
+- `conpot-logs/` — bind-mounted log directory for ingestion
+- `data/` — database and enrichment data
+
+## Step 3: Run Conpot with Security Hardening
+
+```bash
+sudo -u honeypot bash -c 'export XDG_RUNTIME_DIR=/run/user/$(id -u) && \
+podman run -d \
+  --name conpot \
+  --restart=always \
+  --read-only \
+  --cap-drop=ALL \
+  --cap-add=NET_BIND_SERVICE \
+  --security-opt=no-new-privileges \
+  --tmpfs /tmp:rw,noexec,nosuid,size=64m \
+  -v /home/honeypot/honeypot/templates/my-template:/path/to/conpot/templates/my-template:ro \
+  -v /home/honeypot/honeypot/conpot-logs:/var/log/conpot:rw \
+  -v /home/honeypot/honeypot/config/conpot.cfg:/etc/conpot/conpot.cfg:ro \
+  -p 80:80/tcp \
+  -p 102:102/tcp \
+  -p 502:502/tcp \
+  -p 161:161/udp \
+  docker.io/honeynet/conpot:latest \
+  /usr/bin/python3 /home/conpot/.local/bin/conpot \
+    --template my-template \
+    -c /etc/conpot/conpot.cfg \
+    -f --logfile /var/log/conpot/conpot.log \
+    --temp_dir /tmp'
+```
+
+### What the Security Flags Do
+
+| Flag | Purpose |
+|------|---------|
+| `--read-only` | Container filesystem is immutable — attacker can't write to it |
+| `--cap-drop=ALL` | Strips all Linux capabilities |
+| `--cap-add=NET_BIND_SERVICE` | Only adds back the ability to bind low ports |
+| `--security-opt=no-new-privileges` | Prevents privilege escalation via setuid binaries |
+| `--tmpfs /tmp:noexec,nosuid` | Writable temp space, but nothing can be executed from it |
+| `:ro` volume mounts | Templates and config are read-only inside the container |
+
+## Step 4: Firewall Zone Isolation
+
+Create a dedicated firewall zone that only exposes honeypot ports to the internet, and a separate management zone restricted to your admin IPs.
+
+```bash
+# Create honeypot zone — accepts only ICS traffic
+sudo firewall-cmd --permanent --new-zone=ics-honeypot
+sudo firewall-cmd --permanent --zone=ics-honeypot --set-target=ACCEPT
+sudo firewall-cmd --permanent --zone=ics-honeypot --add-port=502/tcp    # Modbus
+sudo firewall-cmd --permanent --zone=ics-honeypot --add-port=102/tcp    # S7comm
+sudo firewall-cmd --permanent --zone=ics-honeypot --add-port=47808/udp  # BACnet
+sudo firewall-cmd --permanent --zone=ics-honeypot --add-port=80/tcp     # HTTP/HMI
+sudo firewall-cmd --permanent --zone=ics-honeypot --add-port=161/udp    # SNMP
+
+# Assign your external interface
+sudo firewall-cmd --permanent --zone=ics-honeypot --change-interface=eno1
+
+# Create management zone — restricted to admin IPs
+sudo firewall-cmd --permanent --new-zone=management
+sudo firewall-cmd --permanent --zone=management --add-source=YOUR.ADMIN.IP/32
+sudo firewall-cmd --permanent --zone=management --add-port=22222/tcp    # Real SSH (non-standard port)
+sudo firewall-cmd --permanent --zone=management --add-port=8888/tcp     # Dashboard
+
+# Default zone drops everything
+sudo firewall-cmd --set-default-zone=drop
+sudo firewall-cmd --reload
+```
+
+**Key principle:** The honeypot ports are open to the world, but management access (real SSH, dashboards) is only reachable from specific admin IPs. An attacker interacting with Conpot has no path to your management services.
+
+## Step 5: SELinux
+
+Ensure SELinux is enforcing. Rootless Podman containers automatically get proper SELinux labels (`container_t` process label, `container_file_t` for volumes).
+
+```bash
+getenforce          # should say "Enforcing"
+sudo semanage port -a -t ssh_port_t -p tcp 22222   # if using non-standard SSH port
+```
+
+Do **not** disable SELinux. It is your strongest containment layer against container escape.
+
+## Step 6: Audit Rules for Container Escape Detection
+
+Add audit rules to detect container breakout attempts:
+
+```bash
+cat << 'EOF' | sudo tee /etc/audit/rules.d/honeypot.rules
+# Namespace manipulation (container escape indicator)
+-a always,exit -F arch=b64 -S unshare -S setns -k container_escape
+
+# Mount/umount (filesystem breakout)
+-a always,exit -F arch=b64 -S mount -S umount2 -F auid>=1000 -k container_mount
+
+# Ptrace (process injection)
+-a always,exit -F arch=b64 -S ptrace -k container_ptrace
+
+# Kernel module loading (rootkit indicator)
+-a always,exit -F arch=b64 -S init_module -S finit_module -S delete_module -k kernel_module
+
+# Honeypot user SSH key tampering
+-w /home/honeypot/.ssh/ -p wa -k honeypot_ssh
+
+# Container runtime config changes
+-w /home/honeypot/.config/containers/ -p wa -k container_config
+EOF
+
+sudo augenrules --load
+```
+
+Check for suspicious events with:
+```bash
+sudo ausearch -k container_escape --start recent
+```
+
+## Step 7: Health Monitoring
+
+A simple health check script that verifies ports are listening:
+
+```bash
+#!/bin/bash
+# /usr/local/bin/honeypot-health.sh
+for port in 502 102 80 161; do
+    if ! ss -tln | grep -q ":${port} "; then
+        echo "ALERT: port $port down" | logger -t honeypot-health
+    fi
+done
+```
+
+Run via systemd timer or cron every 2-5 minutes.
+
+## Step 8: Log Rotation
+
+Conpot logs can grow quickly under heavy scanning. Configure rotation:
+
+```
+# /etc/logrotate.d/conpot
+/home/honeypot/honeypot/conpot-logs/*.log {
+    daily
+    rotate 30
+    compress
+    missingok
+    notifempty
+    copytruncate
+}
+```
+
+**Note:** If you have a log watcher tailing Conpot's JSON output, be aware that log rotation can cause the watcher to lose its file handle. Use `copytruncate` (truncates in place rather than renaming) or implement rotation-aware watching with inotify `CREATE` events.
+
+## Common Issues
+
+### Conpot exits immediately
+Check that your template path inside the container matches the installed location. The path varies by Conpot version — inspect the image with `podman run --rm -it conpot:latest find / -name "templates" -type d`.
+
+### Ports already in use
+If another service is bound to port 502 or 102, Conpot will fail silently. Check with `ss -tlnp` before starting.
+
+### No events in logs
+Verify the log directory is writable by the container user. With rootless Podman, UID mapping can cause permission issues. Check `podman unshare ls -la /home/honeypot/honeypot/conpot-logs/`.
+
+### Internal container IPs in logs
+Rootless Podman uses an internal network (typically `10.89.0.0/24`). If you're ingesting logs into a database, filter out events where `source_ip` falls within RFC 1918 ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`) to avoid counting internal traffic as attacks.