Metadata-Version: 2.4
Name: cyanide-honeypot
Version: 0.0.16
Summary: A medium-interaction honeypot with ML-based anomaly detection.
Author: tanhiowyatt
License: MIT
Project-URL: Homepage, https://github.com/tanhiowyatt/cyanide-honeypot
Project-URL: Bug Tracker, https://github.com/tanhiowyatt/cyanide-honeypot/issues
Project-URL: Documentation, https://github.com/tanhiowyatt/cyanide-honeypot/tree/main/docs
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: asyncssh<3.0,>=2.14.2
Requires-Dist: cryptography>=46.0.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: aiofiles>=23.0
Requires-Dist: aiohttp>=3.13.4
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: numpy==2.4.4
Requires-Dist: prometheus_client>=0.17.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: telnetlib3>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: opentelemetry-api>=1.20.0
Requires-Dist: opentelemetry-sdk>=1.20.0
Requires-Dist: opentelemetry-exporter-otlp>=1.20.0
Requires-Dist: requests>=2.33.0
Requires-Dist: torch>=2.2.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: urllib3>=2.6.3
Requires-Dist: joblib>=1.3.2
Provides-Extra: libvirt
Requires-Dist: libvirt-python>=10.0.0; extra == "libvirt"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
Requires-Dist: pytest-timeout>=2.1.0; extra == "dev"
Requires-Dist: freezegun>=1.2.0; extra == "dev"
Requires-Dist: pytest-black>=0.3.12; extra == "dev"
Requires-Dist: pytest-isort>=3.1.0; extra == "dev"
Requires-Dist: pytest-mypy>=0.10.3; extra == "dev"
Requires-Dist: pytest-ruff>=0.2.1; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.5.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: types-aiofiles>=23.1.0; extra == "dev"
Requires-Dist: types-PyYAML>=6.0.12.12; extra == "dev"
Requires-Dist: types-requests>=2.32.4; extra == "dev"
Provides-Extra: outputs
Requires-Dist: psycopg[binary,pool]>=3.1.0; extra == "outputs"
Requires-Dist: mysql-connector-python>=8.0.0; extra == "outputs"
Requires-Dist: pymongo>=4.5.0; extra == "outputs"
Requires-Dist: elasticsearch<10.0.0,>=8.0.0; extra == "outputs"
Requires-Dist: rethinkdb>=2.4.9; extra == "outputs"
Requires-Dist: hpfeeds>=2.0.0; extra == "outputs"
Dynamic: license-file

<p align="center">

  [![Stars](https://img.shields.io/github/stars/tanhiowyatt/cyanide-honeypot?style=flat&logo=GitHub&color=yellow)](https://github.com/tanhiowyatt/cyanide-honeypot/stargazers)
  [![CI](https://github.com/tanhiowyatt/cyanide-honeypot/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/tanhiowyatt/cyanide-honeypot/actions/workflows/ci.yml)
  [![Security Scan](https://github.com/tanhiowyatt/cyanide-honeypot/actions/workflows/security_scan.yml/badge.svg)](https://github.com/tanhiowyatt/cyanide-honeypot/actions/workflows/security_scan.yml)
  [![Quality gate](https://sonarcloud.io/api/project_badges/measure?project=tanhiowyatt_cyanide_honeypot&metric=alert_status)](https://sonarcloud.io/dashboard?id=tanhiowyatt_cyanide_honeypot)
  [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=tanhiowyatt_cyanide_honeypot&metric=coverage)](https://sonarcloud.io/component_measures/metric/coverage/list?id=tanhiowyatt_cyanide_honeypot)
  [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tanhiowyatt/cyanide-honeypot)
</p>


<p align="center">
  <a target="_blank" href="https://github.com/tanhiowyatt/cyanide-honeypot/blob/main/README.md">ENG</a> &nbsp; | &nbsp;
  <a target="_blank" href="https://github.com/tanhiowyatt/cyanide-honeypot/blob/main/docs/translations/readme-ru.md">RU</a> &nbsp; | &nbsp;
  <a target="_blank" href="https://github.com/tanhiowyatt/cyanide-honeypot/blob/main/docs/translations/readme-pl.md">PL</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/tanhiowyatt/cyanide-honeypot/main/src/cyanide/assets/branding/name.png" alt="Cyanide" width="500" height="auto">
</p>

# 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](docs/index.md)**.

*   [Quick Start](docs/user-reference/QuickStart.md)
*   [Advanced Configuration](docs/user-reference/AdvancedUsage.md)
*   [Developer Reference](docs/developer-reference/core/index.md)

---

### Quick Start
 
 ```bash
1. Clone the repository
git clone https://github.com/tanhiowyatt/cyanide-honeypot.git

2. Navigate to the project directory
cd cyanide-honeypot

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

```bash
1. Install the package
pip install cyanide-honeypot

2. Run the honeypot
cyanide-honeypot
```

---

### How the Honeypot Works

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

#### YAML Profiles (Behavior Foundation)
Service behavior is defined via **YAML profiles**:
- Emulated features (banners/versions, errors, constraints);
- Response logic (rules/templates, branching);
- Session state (authentication, context, counters);
- Realism factors (delays/jitter, randomization).

#### 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 honeypot 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 honeypot involves significant risks. The author is not responsible for any damage or misuse.

---

<p align="center">
  <i>Revision: 1.0 - May 2026 - Cyanide Honeypot</i>
</p>
