Entangle

Entangle is a distributed computing system designed to brute-force Enigma machine ciphertexts. It utilizes a custom binary protocol and a Kernel-Agent architecture to distribute the computational workload across multiple worker nodes.

This project demonstrates core concepts of distributed systems:

• Custom Instruction Set Architecture (ISA) over TCP.
• Centralized Task Scheduling (Kernel).
• Fault Tolerance (Watchdog & Retry Queues).
• Turing-Complete VM abstraction for workers.

📂 Project Structure

• kernel.py: The central server. Manages the search space (Enigma rotor settings) and assigns tasks to agents. Monitors agent health.
• agent.py: The worker node. Connects to the kernel, receives task ranges (e.g., check 1000 keys), runs a local VM to decrypt and check for a "crib" (known plaintext).
• protocol.py: Defines the communication protocol (Opcodes) and packet structure.
• dummy_enigma.py: A utility tool to generate valid Enigma ciphertexts and rotor settings for testing.
• whitepaper.md: Detailed technical explanation of the architecture.

🚀 Quick Start

1. Prerequisites

• Python 3.8+
• No external dependencies required (uses standard library socket, threading, pickle).

2. Generate a Challenge

First, generate a ciphertext and a known "crib" (a word you expect to be in the message). Run the helper script:

python dummy_enigma.py

Follow the prompts:

1. Enter a plaintext (e.g., THE TRAJECTORY IS SAFE).
2. Enter a rotor setting (e.g., A B C).
3. Copy the resulting Ciphertext and the Crib (e.g., TRAJECTO).

Note: You must manually update the ciphertext and crib variables in agent.py with these values before running the agents.

3. Update the Agent

Open agent.py and modify the mission parameters around line 130:

# agent.py
ciphertext = "YOUR GENERATED CIPHERTEXT HERE"
crib = "TRAJECTO" 

4. Run the Kernel (Server)

Start the central scheduler. It will listen on 0.0.0.0:9998.

python kernel.py

5. Run Agents (Workers)

Open new terminal tabs/windows to simulate multiple machines. You can run as many agents as you like.

# Terminal 2
python agent.py

# Terminal 3
python agent.py

6. Observe

• The Kernel will show workers connecting and tasks being assigned (Assigned 00000~01000).
• The Agents will show their progress scanning rotor settings.
• When an agent finds the key, it sends OP_FOUND to the Kernel.
• The Kernel will announce: [!!!] CRACKED BY 127.0.0.1:xxxxx | KEY: [0, 1, 2]

🛠 Architecture

graph TD
    K[Kernel Scheduler] -- OP_TASK_RSP --> A1[Agent 1]
    K -- OP_TASK_RSP --> A2[Agent 2]
    K -- OP_TASK_RSP --> A3[Agent 3]
    
    A1 -- OP_GET_TASK --> K
    A2 -- OP_FOUND (Solution) --> K
    
    subgraph "Worker Logic (VM)"
    A1 --> VM[Virtual Machine]
    VM --> E[Enigma Step]
    VM --> C[Check Crib]
    end

Loading

⚠️ Educational Purpose

This project is a Proof of Concept (PoC) for a university portfolio. It uses pickle for object serialization, which is not secure for untrusted networks. Do not run this on public networks without adding authentication and secure serialization (e.g., JSON/Protobuf).