honeycloud 0.1.2

Adaptive cloud honeypot platform — deploy decoys, monitor attacks, score threats with ML

🍯 HoneyCloud

Adaptive cloud honeypot platform — deploy decoys, monitor attacks in real-time, and score threats with ML.

HoneyCloud is a CLI tool that deploys a real SSH honeypot (via Cowrie + Docker), monitors incoming attack events with MITRE ATT&CK tagging, and scores attacker IPs using a lightweight Isolation Forest anomaly detector.

---

Install

pip install honeycloud

---

Commands

honeycloud deploy

Deploys a Cowrie SSH honeypot. Two modes:

honeycloud deploy --mock          # Simulated deploy — no Docker required
honeycloud deploy                 # Real Cowrie honeypot via Docker (port 2222)
honeycloud deploy --port 8022     # Real Cowrie honeypot on a custom port

Mock mode — simulates the deployment pipeline with animated steps, no Docker needed:

Real Docker deploy — pulls cowrie/cowrie:latest, runs it with --network none (zero egress so attackers can't pivot out). Re-running the command safely detects if the container already exists:

---

honeycloud monitor

Streams incoming attack events with severity, source IP, country, target port, and MITRE ATT&CK technique.

honeycloud monitor               # Replay a captured attack session
honeycloud monitor --live        # Continuous live stream (Ctrl+C to stop)

---

honeycloud score <ip>

Scores an IP address for threat level using a lightweight Isolation Forest anomaly detector. Extracts behavioural features (connection frequency, port entropy, protocol diversity, inter-arrival time) and cross-references known malicious infrastructure (Shodan, Censys, Tor exit nodes).

honeycloud score 45.33.32.156    # Known SSH bruteforcer → CRITICAL
honeycloud score 192.168.1.1     # Private/internal IP  → LOW

---

Tests

10 tests covering CLI end-to-end behaviour and scoring unit logic. Runs on Python 3.9, 3.10, and 3.11 via GitHub Actions CI.

pip install -e .
pip install pytest
pytest tests/ -v

---

Architecture

Attacker hits a fake server → event is captured → ML analyzes it → system responds and shares intel.

Layer 01 — Deception

Four fake services running as traps — SSH, SMB/FTP, HTTP, and Database. Each is a real-looking decoy powered by tools like Cowrie and Dionaea. When an attacker connects, every action they take is silently logged as a structured JSON event. They think they're attacking a real server. They're not.

Layer 02 — Intelligence

The JSON events flow into Kafka (a high-speed event queue) which feeds Flink (a stream processor that cleans, enriches, and geo-tags the data). Flink passes the enriched data into the 3-Layer ML Pipeline which detects, classifies, and predicts the attack. Output is a Threat Intel Object — a structured package of everything known about this attacker.

Layer 03 — Response

Four things happen simultaneously with that Threat Intel Object:

• Response Engine — blocks the IP, morphs the honeypot, fires a SIEM alert
• Data Storage — saves everything to PostgreSQL, Redis, and S3
• Threat Sharing — exports IOCs to MISP, VirusTotal, AlienVault
• Dashboard — updates the live Grafana attack map and kill chain view

The ML Pipeline

A zoom-in on the intelligence brain:

• Layer 0 — takes 6 behavioral features per connection as input
• Layer 1 — Detect — Isolation Forest + Anomaly Transformer scores how anomalous the event is. Score below 0.5 gets discarded. Above 0.5 moves forward.
• Layer 2 — Classify — XGBoost + Random Forest ensemble labels the attack type and tags it to a MITRE ATT&CK technique
• Layer 3 — Predict — Bi-LSTM predicts the next attack move. GAT connects related IPs into campaign clusters
• Layer X — Output — a clean JSON object with attack type, confidence, MITRE ID, next vector prediction, and campaign ID ready for export

A raw TCP connection enters Layer 01 and exits Layer X as attributed, classified, predicted threat intelligence. The current release implements Layer 01 (Cowrie deploy) and a lightweight Isolation Forest for Layer 1 — Detect. The full pipeline is the planned production architecture.

---

Datasets

Will be trained and validated on four real-world honeypot capture datasets:

1. CIC-Honeynet — T-Pot, 20+ honeypot types
2. Hornet-40 — 8 global cities, 40 days, NetFlow (Valeros, 2021)
3. Dionaea/AWS — 451k+ protocol-level attack events
4. AWS Geo Honeypot — geo-tagged attack corpus

---

License

MIT