Deception Engine

Active defense through deception — fake services, canary tokens, and honeypots that lure attackers into controlled environments and log every move.

Instead of detecting attacks after the fact, Deception Engine creates an artificial attack surface that looks real. Every interaction is captured, scored, and mapped to MITRE ATT&CK techniques.

Features

• Canary Tokens — fake AWS keys, SSH keys, DB credentials, and API tokens for planting as bait
• Ghost Sessions — spawn honeypots on random ports that capture full attacker interaction
• Risk Scoring — 10-signal weighted evaluation with adaptive thresholds (0–100 scale)
• Deception Layer — routes suspicious traffic to honeypots while keeping production clean
• Weakness Scanner — auto-audit via nuclei, sqlmap, hydra, and path-scan
• ATT&CK Mapping — 12 MITRE technique mappings plus 10 D3FEND countermeasure mappings

Quick Start

from deception_engine.fakes.canary_tokens import CanaryTokenGenerator

gen = CanaryTokenGenerator()
token = gen.generate("aws_key", label="prod-backdoor")
# Plant in a fake config — anyone who uses it triggers an alert

from deception_engine.core.deception_layer import DeceptionLayer

layer = DeceptionLayer()
ghost = layer.spawn(source_session_id="attacker-123", risk_score=72.5)
# Ghost is now capturing everything on a random port

Install

pip install deception-engine
pip install "deception-engine[scanners]"  # with scanner dependencies

Usage

from deception_engine.core.gateway import Gateway
from deception_engine.core.risk_scorer import RiskScorer
from deception_engine.core.deception_layer import DeceptionLayer
from deception_engine.fakes.canary_tokens import CanaryTokenGenerator

gen = CanaryTokenGenerator()
layer = DeceptionLayer()
scorer = RiskScorer()
gateway = Gateway(deception_layer=layer, risk_scorer=scorer)

response = gateway.handle_request(request)

CLI

deception-engine start --config config/honeypot_profiles.yaml
deception-engine scan --target https://example.com
deception-engine canary --type aws_key --label prod-backdoor
deception-engine report --session attacker-123

Architecture

deception_engine/
├── core/               # Gateway, deception layer, risk scorer, behavior analyzer
├── fakes/              # Canary token generator, fake backends, fake frontends
├── scanners/           # Weakness scanner, signature generator
├── capture/            # Session recording and traffic capture
├── config/             # YAML honeypot profiles and routing rules
└── cli.py              # CLI entry point

Request → Gateway → Risk Scorer → [Clean] → Production
                        ↓
                  [Suspicious] → Deception Layer → Ghost Session → Capture Log

Risk Scoring Signals

Signal	Weight	Description
Payload Malice	0.18	SQL injection, XSS, command injection patterns
Request Rate	0.15	Requests/sec relative to baseline
Source Reputation	0.13	IP, ASN, and threat intel lookups
Path Entropy	0.12	Randomness of requested paths
Header Anomalies	0.10	Unusual or missing HTTP headers
Auth Attempts	0.10	Failed login and brute-force patterns
Session Duration	0.08	Time in honeypot vs. real services
Data Access	0.07	Attempts to read sensitive files
Lateral Movement	0.05	Port scanning or internal probes
Exfiltration	0.02	Large outbound data transfers

Roadmap

• Database honeypots (MySQL, PostgreSQL, Redis)
• Built-in web dashboard for session visualization
• Automated response playbooks
• Kubernetes and Docker deployment modes

License

MIT License — see LICENSE for details. Part of the COSMIC ecosystem.