|
1 | | -# 🔐 CipherScope |
| 1 | +<div align="center"> |
2 | 2 |
|
3 | | -CipherScope is a **distributed and concurrent hash cracking system** written in Go. |
4 | | -It demonstrates practical concepts of **parallel computing and distributed systems**, combining: |
| 3 | +<h1>🔐 Cipher Scope</h1> |
5 | 4 |
|
6 | | -- Multi-core processing (goroutines) |
7 | | -- Distributed execution across multiple machines (e.g., TV Boxes) |
8 | | -- Task distribution via TCP sockets |
9 | | -- Efficient worker coordination and early termination |
| 5 | +<p>Hash cracker distribuído com dashboard web em tempo real.<br> |
| 6 | +Escrito em Go puro — roda em qualquer máquina, incluindo <strong>TV Box (ARM)</strong>.</p> |
10 | 7 |
|
11 | | -## 📌 Overview |
| 8 | +<img src="https://img.shields.io/badge/Go-1.22+-00ADD8?style=flat-square&logo=go&logoColor=white"/> |
| 9 | +<img src="https://img.shields.io/badge/Platform-Linux%20%7C%20ARM%20%7C%20Android-informational?style=flat-square"/> |
| 10 | +<img src="https://img.shields.io/badge/License-MIT-green?style=flat-square"/> |
12 | 11 |
|
13 | | -CipherScope supports two main attack strategies: |
| 12 | +</div> |
14 | 13 |
|
15 | | -### 1. Dictionary Attack |
16 | | -- Reads passwords from a wordlist file |
17 | | -- Hashes each entry and compares with the target |
18 | | - |
19 | | -### 2. Brute Force Attack |
20 | | -- Generates all possible combinations from a given charset and length |
21 | | -- Uses recursion + streaming (no full memory allocation) |
22 | | - |
23 | | -## 🧠 Architecture |
24 | | - |
25 | | -### 🔹 Hybrid Parallelism |
26 | | - |
27 | | -CipherScope combines: |
28 | | - |
29 | | -- **Intra-node parallelism** |
30 | | - - Goroutines + channels |
31 | | - - Utilizes all CPU cores |
32 | | - |
33 | | -- **Inter-node parallelism** |
34 | | - - Multiple workers across devices |
35 | | - - Master distributes workload |
36 | | - |
37 | | -### 🔹 System Components |
38 | | - |
39 | | -CipherScope/ |
40 | | -├── master/ # Task coordinator (distributes work) |
41 | | -├── worker/ # Executes tasks (runs on remote machines) |
42 | | -├── core/ # Engine, jobs, and task definitions |
43 | | -├── attacks/ # Dictionary and brute-force logic |
44 | | -├── crypto/ # Hashing algorithms |
45 | | -├── utils/ # Logging and helpers |
46 | | -├── main.go # Local (non-distributed) execution |
47 | | - |
48 | | -## ⚙️ Requirements |
49 | | - |
50 | | -- Go 1.20+ |
51 | | -- Machines in the same network (for distributed mode) |
| 14 | +--- |
52 | 15 |
|
53 | | -## 🔧 Installation |
| 16 | +## ✨ Funcionalidades |
54 | 17 |
|
55 | | -Clone the repository: |
| 18 | +- **Dashboard Web** — interface dark mode com progresso em tempo real via SSE |
| 19 | +- **Gerador de Hash** — gera MD5, SHA1 e SHA256 diretamente no browser |
| 20 | +- **Dictionary Attack** — lê wordlist em streaming (baixo uso de RAM) |
| 21 | +- **Brute Force Attack** — tenta combinações de 1 até N caracteres com charset configurável |
| 22 | +- **Modo Auto** — dictionary primeiro, brute force como fallback |
| 23 | +- **Modo Distribuído** — master/worker via TCP para usar múltiplas máquinas em paralelo |
| 24 | +- **Cross-platform** — compila para ARM32, ARM64, x86, Windows, macOS |
56 | 25 |
|
57 | | -```bash |
58 | | -git clone https://github.com/your-username/cipherscope.git |
59 | | -cd cipherscope |
60 | | -```` |
| 26 | +--- |
61 | 27 |
|
62 | | -## 🚀 Usage |
| 28 | +## 🚀 Como Usar |
63 | 29 |
|
64 | | -## 🖥️ 1. Run Master |
| 30 | +### Pré-requisitos |
65 | 31 |
|
66 | 32 | ```bash |
67 | | -go run master/main.go |
| 33 | +# Go 1.22+ |
| 34 | +go version |
68 | 35 | ``` |
69 | 36 |
|
70 | | -You will be prompted: |
71 | | - |
72 | | -Enter hash: |
73 | | -Enter hash type (md5, sha1, sha256): |
74 | | - |
75 | | -## 📺 2. Configure Workers |
| 37 | +### Compilar e rodar |
76 | 38 |
|
77 | | -Edit: |
78 | | - |
79 | | -📁 `worker/main.go` |
80 | | - |
81 | | -Replace: |
82 | | - |
83 | | -```go |
84 | | -"net.Dial("tcp", "MASTER_IP:9000") |
85 | | -``` |
| 39 | +```bash |
| 40 | +git clone https://github.com/JonathanMar/cipher-scope.git |
| 41 | +cd cipher-scope |
86 | 42 |
|
87 | | -With your master IP: |
| 43 | +# Rodar localmente (abre o browser automaticamente) |
| 44 | +go run . |
88 | 45 |
|
89 | | -```go |
90 | | -"net.Dial("tcp", "192.168.0.10:9000") |
| 46 | +# Compilar binário |
| 47 | +go build -o cipher-scope . |
| 48 | +./cipher-scope |
91 | 49 | ``` |
92 | 50 |
|
93 | | -## ▶️ 3. Run Workers |
| 51 | +O dashboard abre em `http://localhost:8080`. |
94 | 52 |
|
95 | | -### Option A: Local testing |
| 53 | +### Flags disponíveis |
96 | 54 |
|
97 | | -```bash |
98 | | -go run worker/main.go |
99 | 55 | ``` |
100 | | - |
101 | | -(Open multiple terminals) |
102 | | - |
103 | | -### Option B: TV Boxes / Remote Devices |
104 | | - |
105 | | -#### Build for ARM: |
106 | | - |
107 | | -```bash |
108 | | -GOOS=linux GOARCH=arm64 go build -o worker ./worker |
| 56 | +-addr string Endereço de escuta (default ":8080") |
| 57 | +-no-browser Não abrir o browser automaticamente |
109 | 58 | ``` |
110 | 59 |
|
111 | | -#### Transfer: |
| 60 | +### Acesso pela rede (TV Box / outro dispositivo) |
112 | 61 |
|
113 | 62 | ```bash |
114 | | -scp worker user@DEVICE_IP:/home/user/ |
115 | | -``` |
116 | | - |
117 | | -#### Run: |
| 63 | +# Na TV Box ou servidor: |
| 64 | +./cipher-scope -addr 0.0.0.0:8080 -no-browser |
118 | 65 |
|
119 | | -```bash |
120 | | -chmod +x worker |
121 | | -./worker |
| 66 | +# No celular ou PC na mesma rede, abra: |
| 67 | +# http://<IP-DA-TVBOX>:8080 |
122 | 68 | ``` |
123 | 69 |
|
124 | | -## 🧪 Example |
| 70 | +--- |
125 | 71 |
|
126 | | -Generate a test hash: |
| 72 | +## 📦 Cross-compile para TV Box (ARM) |
127 | 73 |
|
128 | 74 | ```bash |
129 | | -echo -n "abcde" | md5sum |
130 | | -``` |
| 75 | +# ARM64 (TV Boxes modernas: Amlogic S905X3+, Rockchip RK3318...) |
| 76 | +GOOS=linux GOARCH=arm64 go build -o cipher-scope-arm64 . |
131 | 77 |
|
132 | | -Run master and input: |
| 78 | +# ARM32 (TV Boxes antigas 32-bit) |
| 79 | +GOOS=linux GOARCH=arm GOARM=7 go build -o cipher-scope-arm32 . |
133 | 80 |
|
134 | | -``` |
135 | | -Hash: <generated hash> |
136 | | -Type: md5 |
137 | | -``` |
138 | | -
|
139 | | -Expected output: |
140 | | -
|
141 | | -``` |
142 | | -Password found: abcde |
143 | | -All workers stopped. |
| 81 | +# Copiar para a TV Box via SCP |
| 82 | +scp cipher-scope-arm64 user@192.168.x.x:/home/user/ |
144 | 83 | ``` |
145 | 84 |
|
146 | 85 | --- |
147 | 86 |
|
148 | | -## 📊 Performance |
| 87 | +## 🌐 Dashboard |
149 | 88 |
|
150 | | -### Time Complexity |
151 | | -
|
152 | | -* Dictionary Attack: |
153 | | -
|
154 | | - ``` |
155 | | - O(n) |
156 | | - ``` |
157 | | -
|
158 | | -* Brute Force: |
159 | | -
|
160 | | - ``` |
161 | | - O(|charset|^length) |
162 | | - ``` |
| 89 | +| Painel | Funcionalidade | |
| 90 | +|--------|---------------| |
| 91 | +| **Gerador de Hash** | Digite uma senha → copia o hash com 1 clique | |
| 92 | +| **Configuração** | Hash alvo, tipo, modo de ataque, workers, tamanho máximo, charset | |
| 93 | +| **Anel de Progresso** | Progresso visual em tempo real (SVG animado) | |
| 94 | +| **Stats** | H/s, ETA, tempo decorrido, tentativas | |
| 95 | +| **Resultado** | Banner de sucesso/falha com a senha encontrada | |
| 96 | +| **Log** | Histórico de eventos com timestamp | |
163 | 97 |
|
164 | 98 | --- |
165 | 99 |
|
166 | | -### Distributed Speedup |
| 100 | +## 🔌 API REST |
167 | 101 |
|
168 | | -``` |
169 | | -T ≈ N / (workers × CPU cores) |
170 | | -``` |
| 102 | +| Método | Endpoint | Descrição | |
| 103 | +|--------|----------|-----------| |
| 104 | +| `POST` | `/api/hash` | Gera hash de uma senha | |
| 105 | +| `POST` | `/api/crack` | Inicia um ataque | |
| 106 | +| `POST` | `/api/stop` | Para o ataque em andamento | |
| 107 | +| `GET` | `/api/progress` | SSE — progresso em tempo real | |
171 | 108 |
|
172 | | -Where: |
| 109 | +### Exemplo: gerar hash |
173 | 110 |
|
174 | | -* N = total combinations |
175 | | -* workers = number of machines |
| 111 | +```bash |
| 112 | +curl -X POST http://localhost:8080/api/hash \ |
| 113 | + -H 'Content-Type: application/json' \ |
| 114 | + -d '{"password":"hello","type":"md5"}' |
176 | 115 |
|
177 | | ---- |
| 116 | +# {"hash":"5d41402abc4b2a76b9719d911017c592"} |
| 117 | +``` |
178 | 118 |
|
179 | | -## ⚠️ Limitations |
| 119 | +### Exemplo: iniciar ataque |
180 | 120 |
|
181 | | -* No support for salted hashes (e.g., bcrypt, argon2) |
182 | | -* Brute force grows exponentially |
183 | | -* No dynamic load balancing (static distribution) |
184 | | -* No fault tolerance (worker failure not handled) |
| 121 | +```bash |
| 122 | +curl -X POST http://localhost:8080/api/crack \ |
| 123 | + -H 'Content-Type: application/json' \ |
| 124 | + -d '{ |
| 125 | + "hash": "5d41402abc4b2a76b9719d911017c592", |
| 126 | + "hashType": "md5", |
| 127 | + "mode": "auto", |
| 128 | + "workers": 4, |
| 129 | + "maxLength": 5, |
| 130 | + "charset": "abcdefghijklmnopqrstuvwxyz0123456789", |
| 131 | + "wordlist": "wordlist.txt" |
| 132 | + }' |
| 133 | +``` |
185 | 134 |
|
186 | 135 | --- |
187 | 136 |
|
188 | | -## 🧠 Future Improvements |
189 | | -
|
190 | | -* 🔄 Dynamic task queue (work stealing) |
191 | | -* 📊 Real-time metrics (hashes/sec) |
192 | | -* 🔐 Support for bcrypt / argon2 |
193 | | -* ⚡ GPU acceleration |
194 | | -* 🌍 gRPC instead of raw TCP |
195 | | -* 🖥️ CLI interface (cobra) |
196 | | -* 📈 Benchmarking tools |
197 | | -
|
198 | | ---- |
| 137 | +## 🖧 Modo Distribuído (Master / Worker) |
199 | 138 |
|
200 | | -## 🧪 Testing Tips |
| 139 | +Para distribuir o brute force entre várias máquinas na rede: |
201 | 140 |
|
202 | | -Use small values for quick tests: |
| 141 | +```bash |
| 142 | +# Máquina principal (master) — aguarda workers e distribui tarefas |
| 143 | +go run ./master -addr :9000 |
203 | 144 |
|
204 | | -```go |
205 | | -charset := "abc" |
206 | | -length := 3 |
| 145 | +# Cada TV Box / máquina worker |
| 146 | +go run ./worker -master 192.168.0.10:9000 -workers 4 |
207 | 147 | ``` |
208 | 148 |
|
209 | | ---- |
210 | | - |
211 | | -## 📚 Concepts Demonstrated |
212 | | - |
213 | | -* Goroutines and channels |
214 | | -* Producer–consumer pattern |
215 | | -* Context cancellation |
216 | | -* TCP networking in Go |
217 | | -* Distributed task scheduling |
218 | | -* Parallel brute force search |
| 149 | +O master divide o espaço de combinações entre os workers automaticamente. |
219 | 150 |
|
220 | 151 | --- |
221 | 152 |
|
222 | | -## 📄 License |
| 153 | +## 🗂️ Estrutura do Projeto |
223 | 154 |
|
224 | | -MIT License |
| 155 | +``` |
| 156 | +cipher-scope/ |
| 157 | +├── main.go # Servidor HTTP + embed da UI |
| 158 | +├── ui/ # Dashboard (HTML/CSS/JS) — embutido no binário |
| 159 | +├── server/ # Handlers HTTP, SSE e estado do ataque |
| 160 | +├── attacks/ # Dictionary e Brute Force |
| 161 | +├── core/ # Engine de workers, validação, tipos |
| 162 | +├── crypto/ # MD5, SHA1, SHA256 |
| 163 | +├── master/ # Nó master do modo distribuído |
| 164 | +├── worker/ # Nó worker do modo distribuído |
| 165 | +└── utils/ # Logger |
| 166 | +``` |
225 | 167 |
|
226 | 168 | --- |
227 | 169 |
|
228 | | -## 👨💻 Author |
| 170 | +## 🔧 Hashes suportados |
229 | 171 |
|
230 | | -Developed for academic purposes in **Parallel Computing**. |
| 172 | +| Tipo | Tamanho | |
| 173 | +|------|---------| |
| 174 | +| MD5 | 32 chars | |
| 175 | +| SHA1 | 40 chars | |
| 176 | +| SHA256 | 64 chars | |
231 | 177 |
|
232 | 178 | --- |
233 | 179 |
|
234 | | -## ⭐ Final Notes |
235 | | - |
236 | | -CipherScope is a **practical demonstration of distributed brute-force computation**, showing how: |
| 180 | +## 📄 Licença |
237 | 181 |
|
238 | | -* Workloads can be split across machines |
239 | | -* CPU cores can be fully utilized |
240 | | -* Systems can scale horizontally |
| 182 | +MIT © [JonathanMar](https://github.com/JonathanMar) |
0 commit comments