An adaptive, AI-driven honeynet designed to dynamically control deception infrastructure based on observed attacker activity.
Status: 🚧 MVP in active development
DeceptionX is an open-source security research project exploring how honeypots, IDS telemetry, automated reasoning, and controlled infrastructure can work together to create an adaptive deception environment.
The goal is to move beyond static honeypots toward a system that can observe → reason → decide → adapt, while maintaining strong security boundaries and an auditable control layer.
Traditional honeypots are largely static. They expose a predefined service, collect activity, and leave the analysis to the operator.
This creates several limitations:
- Attackers can fingerprint predictable environments.
- Raw security alerts require manual interpretation.
- Honeypot exposure usually does not adapt to attacker behavior.
- Security decisions may not have a structured audit trail.
DeceptionX explores a closed-loop approach:
Security Telemetry
↓
Perception
↓
Decision / Agent
↓
potctl
↓
Controlled Honeypot Actions
↓
New Telemetry
↺
The system is designed so that reasoning is separated from enforcement. The agent can propose a decision, while the Go-based control layer is responsible for validating and executing permitted infrastructure actions.
┌──────────────────┐
│ Honeypots │
│ SSH / HTTP │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Suricata │
│ IDS │
│ eve.json │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Perception │
│ Parse / │
│ Normalize │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Agent / Decision │
│ Reasoning │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ potctl │
│ Go Control Layer │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Controlled │
│ Docker Actions │
└──────────────────┘
│
▼
┌──────────────────┐
│ SQLite / Audit │
│ History │
└──────────────────┘
DeceptionX separates decision-making from infrastructure enforcement.
The reasoning layer should not directly control Docker or the honeynet. Instead:
Agent
↓
Decision
↓
Validation
↓
potctl
↓
Allowed Action
This provides a clear security boundary between probabilistic reasoning and deterministic infrastructure control.
The project is being developed incrementally.
- Isolated Linux honeynet environment
- Cowrie SSH honeypot
- HTTP decoy service
- Docker-based service deployment
- Suricata IDS
- JSON-based security telemetry
- Suricata
eve.jsonmonitoring - Event parsing
- Event normalization
- File offset tracking
- Protection against duplicate processing
- Partial-line handling
- Automated tests
- Go-based control plane
- Docker integration
- Structured logging with zerolog
- SQLite state and audit storage
- REST API
-
/stateendpoint -
/toggleendpoint - API key authentication
- Target allow-list validation
- Local-only API exposure
- Structured decision model
- Decision validation
- Supported actions such as
expose,hide, andno_change
The broader agent reasoning and adaptive decision loop is still under active development.
Security is a core part of DeceptionX rather than an additional feature.
The project follows several principles:
Components should receive only the permissions required for their function.
The enforcement layer validates decisions before performing infrastructure changes.
Security-sensitive targets and actions are explicitly restricted rather than accepting arbitrary input.
The potctl API is designed for local communication and should not be exposed directly to an untrusted network.
API access requires authentication rather than relying only on network location.
Important state changes and decisions are stored so that system behavior can be reviewed later.
The honeynet should run inside an isolated lab environment and must not be used against systems or networks without authorization.
| Component | Technology |
|---|---|
| Control layer | Go |
| Perception | Go, fsnotify |
| Docker control | Moby/Docker API |
| Logging | zerolog |
| Storage | SQLite |
| IDS | Suricata |
| SSH honeypot | Cowrie |
| HTTP decoy | Custom HTTP service |
| Agent | Python |
| Decision validation | Pydantic |
| Dashboard | React (planned/in development) |
The technology stack may evolve as the project develops.
DeceptionX/
│
├── agent/ # Python agent and decision logic
├── core/ # Core security/control components
├── honeypots/ # Honeypot and decoy services
├── infra/ # Lab and infrastructure configuration
├── frontend/ # Dashboard
├── docs/ # Architecture and build documentation
├── scripts/ # Testing and attack simulations
│
├── CONTRIBUTING.md
├── CODE_OF_CONDUCT.md
├── LICENSE
└── README.md
The structure is evolving alongside the project.
DeceptionX is currently designed primarily for an isolated Linux security lab.
Depending on the component being developed:
- Git
- Linux
- Docker
- Docker Compose
- Go
- Python
- Basic networking knowledge
git clone https://github.com/codewithMohak/DeceptionX.git
cd DeceptionXFrom the appropriate Go module:
go test ./...For the perception package:
go test ./internal/perceptionAdditional setup instructions are being documented as the project develops.
⚠️ Important: DeceptionX is a security research project. Run the honeynet only inside an isolated environment and only against systems you are authorized to test.
DeceptionX is being developed incrementally through focused milestones.
The development process emphasizes:
Research
↓
Design
↓
Implementation
↓
Testing
↓
Security Review
↓
Documentation
Contributions are welcome in areas such as:
- Security research
- Honeypot development
- Detection engineering
- Go development
- Python development
- Agent systems
- Testing
- Documentation
- Frontend/dashboard development
See CONTRIBUTING.md for contribution guidelines.
DeceptionX is currently an MVP / active research build.
The current implementation focuses on establishing the core pipeline:
Telemetry
↓
Perception
↓
Decision
↓
Control
↓
Audit
More advanced capabilities will be added incrementally and documented as they become implemented and tested.
Planned areas of development include:
- Adaptive exposure policies
- Expanded attacker behavior modeling
- MITRE ATT&CK mapping
- Attack graph construction
- Improved deception personas
- Anti-fingerprinting techniques
- Rich security telemetry
- Dashboard visualization
- Expanded evaluation and benchmarking
- Multi-agent experimentation
- Kubernetes-based scaling
- Structured CTI output such as STIX/TAXII
The roadmap will evolve as research and implementation progress.
DeceptionX builds upon ideas from research in cyber deception, autonomous honeynets, and intelligent security systems.
Relevant work includes:
- Mirra (2025) — Towards Autonomous Cyber Deception: An AI Agent for Dynamic Honeynet Management
- De Gaspari et al. (2019) — Towards Intelligent Cyber Deception Systems
- Newsham et al. (2025) — Inducing Personality in LLM-Based Honeypot Agents
- Mirra et al. (2026) — Towards Agentic Honeynet Configuration
The project's architecture and research direction are documented further in:
Additional project documentation is available under docs/.
This includes:
- Architecture
- Lab setup
- Development notes
- Evaluation
- Build logs
- Research notes
As the project grows, documentation will be expanded alongside implementation.
Contributions, security research, testing, documentation improvements, and ideas are welcome.
Before contributing, please read:
For security-sensitive issues, please follow the project's security reporting process.
DeceptionX is released under the MIT License.
Mohak Agarwal
Security researcher and engineer building DeceptionX as an open-source security research project.
DeceptionX is an evolving research project.
Build it. Break it. Observe it. Improve it.