decryptre 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- decryptre-0.1.0/LICENSE +21 -0
- decryptre-0.1.0/PKG-INFO +350 -0
- decryptre-0.1.0/README.md +328 -0
- decryptre-0.1.0/decryptre/__init__.py +11 -0
- decryptre-0.1.0/decryptre/__main__.py +6 -0
- decryptre-0.1.0/decryptre/auto_detect.py +231 -0
- decryptre-0.1.0/decryptre/classical.py +426 -0
- decryptre-0.1.0/decryptre/cli.py +373 -0
- decryptre-0.1.0/decryptre/containers.py +47 -0
- decryptre-0.1.0/decryptre/data/SOURCE.md +33 -0
- decryptre-0.1.0/decryptre/data/trigrams.txt +5892 -0
- decryptre-0.1.0/decryptre/encodings.py +193 -0
- decryptre-0.1.0/decryptre/models.py +37 -0
- decryptre-0.1.0/decryptre/modern_crypto.py +280 -0
- decryptre-0.1.0/decryptre/ngrams.py +76 -0
- decryptre-0.1.0/decryptre/scorer.py +168 -0
- decryptre-0.1.0/decryptre/wordlists/SOURCE.md +25 -0
- decryptre-0.1.0/decryptre/wordlists/common-passwords.txt +10001 -0
- decryptre-0.1.0/decryptre/xor.py +144 -0
- decryptre-0.1.0/decryptre.egg-info/PKG-INFO +350 -0
- decryptre-0.1.0/decryptre.egg-info/SOURCES.txt +33 -0
- decryptre-0.1.0/decryptre.egg-info/dependency_links.txt +1 -0
- decryptre-0.1.0/decryptre.egg-info/entry_points.txt +2 -0
- decryptre-0.1.0/decryptre.egg-info/requires.txt +5 -0
- decryptre-0.1.0/decryptre.egg-info/top_level.txt +1 -0
- decryptre-0.1.0/pyproject.toml +45 -0
- decryptre-0.1.0/setup.cfg +4 -0
- decryptre-0.1.0/tests/test_auto_detect.py +47 -0
- decryptre-0.1.0/tests/test_classical.py +86 -0
- decryptre-0.1.0/tests/test_cli.py +76 -0
- decryptre-0.1.0/tests/test_encodings.py +52 -0
- decryptre-0.1.0/tests/test_modern_crypto.py +88 -0
- decryptre-0.1.0/tests/test_offline.py +30 -0
- decryptre-0.1.0/tests/test_scorer.py +45 -0
- decryptre-0.1.0/tests/test_xor.py +52 -0
decryptre-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jason Marvello
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
decryptre-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,350 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: decryptre
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Offline, open-source CLI that decrypts text with or without a passphrase and re-encrypts it with the same methods.
|
|
5
|
+
Author: Jason Marvello
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/JasonMarvello/DecryptRE
|
|
8
|
+
Keywords: cryptography,ciphers,ctf,decryption,offline
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Environment :: Console
|
|
11
|
+
Classifier: Intended Audience :: Education
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Topic :: Security :: Cryptography
|
|
14
|
+
Requires-Python: >=3.9
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Requires-Dist: cryptography>=41.0
|
|
18
|
+
Requires-Dist: pycryptodome>=3.19
|
|
19
|
+
Provides-Extra: dev
|
|
20
|
+
Requires-Dist: pytest>=7.0; extra == "dev"
|
|
21
|
+
Dynamic: license-file
|
|
22
|
+
|
|
23
|
+
# DecryptRE
|
|
24
|
+
|
|
25
|
+
DecryptRE is a free, open-source Python command-line tool that **decrypts text
|
|
26
|
+
with or without a passphrase** and can **encrypt it again** with the same
|
|
27
|
+
methods.
|
|
28
|
+
|
|
29
|
+
It handles encodings (Base64, Base32, hex, URL, ASCII85), classical ciphers
|
|
30
|
+
(Caesar/ROT-N, Atbash, Vigenère, Rail Fence, simple substitution), XOR, and
|
|
31
|
+
passphrase-based modern crypto (Fernet and AES). It also recognises common
|
|
32
|
+
hashes.
|
|
33
|
+
|
|
34
|
+
**Everything runs offline.** There are no API calls, no telemetry, no remote
|
|
35
|
+
wordlists, and no internet connection is needed after installation. A test in
|
|
36
|
+
the repository enforces this.
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## ⚠️ Responsible use
|
|
41
|
+
|
|
42
|
+
DecryptRE is for **education, Capture-The-Flag puzzles, and data you own**.
|
|
43
|
+
|
|
44
|
+
- Only decrypt messages you created or have explicit permission to test.
|
|
45
|
+
- Do not use it against other people's accounts, files, or systems.
|
|
46
|
+
- "No passphrase" mode is a puzzle-solving aid, not a way to break real
|
|
47
|
+
encrypted services.
|
|
48
|
+
|
|
49
|
+
The authors accept no responsibility for misuse. See [LICENSE](LICENSE).
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
## What it can and cannot do
|
|
54
|
+
|
|
55
|
+
| Situation | What DecryptRE does |
|
|
56
|
+
| --- | --- |
|
|
57
|
+
| Text is encoded (Base64, hex, ...) | Decodes it. Encodings are not encryption. |
|
|
58
|
+
| Text uses a classical cipher | Tries the parameters and ranks results by how much they look like English. |
|
|
59
|
+
| Text uses XOR with a short key | Recovers single-byte keys and repeating keys (up to 32 bytes). |
|
|
60
|
+
| Text uses Fernet / AES **and you know the passphrase** | Decrypts it. |
|
|
61
|
+
| Text uses Fernet / AES **and you do not know the passphrase** | Tries every passphrase in an offline wordlist (a *dictionary attack*). If the passphrase is not in the list, it cannot be recovered. That is the point of modern cryptography. |
|
|
62
|
+
| Text is a hash (MD5, SHA-1, SHA-256, SHA-512) | Identifies the likely algorithm and clearly states that hashes are **one-way** and cannot be decrypted. |
|
|
63
|
+
|
|
64
|
+
Two honest statements that the code and docs repeat:
|
|
65
|
+
|
|
66
|
+
1. **"No passphrase" is not magic.** For encodings and classical ciphers it is
|
|
67
|
+
a bounded parameter search. For modern crypto it is a dictionary attack.
|
|
68
|
+
2. **Modern encryption cannot be brute-forced by this tool.** A real AES or
|
|
69
|
+
Fernet key derived from a strong passphrase is out of reach.
|
|
70
|
+
|
|
71
|
+
---
|
|
72
|
+
|
|
73
|
+
## Installation
|
|
74
|
+
|
|
75
|
+
Requirements: **Python 3.9 or newer**.
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
git clone https://github.com/JasonMarvello/DecryptRE.git
|
|
79
|
+
cd DecryptRE
|
|
80
|
+
python -m venv .venv
|
|
81
|
+
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
82
|
+
pip install .
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
That installs the `decryptre` command. To work on the code instead:
|
|
86
|
+
|
|
87
|
+
```bash
|
|
88
|
+
pip install -e ".[dev]"
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
---
|
|
92
|
+
|
|
93
|
+
## Quick start
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
# Decode Base64
|
|
97
|
+
decryptre decrypt --input "SGVsbG8sIHdvcmxkIQ==" --method base64
|
|
98
|
+
|
|
99
|
+
# Break a Caesar cipher without knowing the shift
|
|
100
|
+
decryptre decrypt --input "Wkh txlfn eurzq ira" --method caesar
|
|
101
|
+
|
|
102
|
+
# Let DecryptRE try every supported layer
|
|
103
|
+
decryptre decrypt --input "V2xqcGNwbyBhZmtrd3BkIGxjcCBxZnk6IG9wbnpvcCB4cCwgZXNweSBkc3RxZSB4cCBtbG52Lg=="
|
|
104
|
+
|
|
105
|
+
# Decrypt something you encrypted with a passphrase
|
|
106
|
+
decryptre encrypt --input "Secret note" --method aes --key "correct horse battery staple"
|
|
107
|
+
decryptre decrypt --input "decryptre:v1:..." --method aes --key "correct horse battery staple"
|
|
108
|
+
|
|
109
|
+
# Identify a hash
|
|
110
|
+
decryptre identify --input 5d41402abc4b2a76b9719d911017c592
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
`--input` accepts a **file path**, a **literal string**, or `-` to read from
|
|
114
|
+
standard input.
|
|
115
|
+
|
|
116
|
+
---
|
|
117
|
+
|
|
118
|
+
## Commands
|
|
119
|
+
|
|
120
|
+
### `decryptre decrypt`
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
decryptre decrypt --input <file|text|-> [options]
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
| Option | Default | Meaning |
|
|
127
|
+
| --- | --- | --- |
|
|
128
|
+
| `--method NAME` | `auto` | Method to use. `auto` tries everything. |
|
|
129
|
+
| `--key TEXT` | none | Passphrase or cipher key. |
|
|
130
|
+
| `--shift N` | try all | Caesar shift. |
|
|
131
|
+
| `--rails N` | try 2-12 | Rail Fence rails. |
|
|
132
|
+
| `--wordlist PATH` | bundled list | Passphrase list for Fernet/AES. |
|
|
133
|
+
| `--no-wordlist` | off | Skip the bundled wordlist. |
|
|
134
|
+
| `--no-substitution` | off | Skip the slow substitution solver in `auto` mode. |
|
|
135
|
+
| `--max-depth N` | `3` | Maximum number of layers to peel in `auto` mode. |
|
|
136
|
+
| `--max-candidates N` | `2000` | Hard budget for `auto` mode. |
|
|
137
|
+
| `--top N` | `5` | How many results to print. |
|
|
138
|
+
| `-v`, `--verbose` | off | Show extra detail. |
|
|
139
|
+
|
|
140
|
+
### `decryptre encrypt`
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
decryptre encrypt --input <file|text|-> --method NAME [options]
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
Uses the same method names. `--key` is required for Vigenère, XOR, Fernet and
|
|
147
|
+
AES. Extra options: `--shift` (Caesar, default 3), `--rails` (Rail Fence),
|
|
148
|
+
`--aes-mode gcm|cbc` (default `gcm`), `--kdf pbkdf2|scrypt` (default
|
|
149
|
+
`pbkdf2`), `--iterations` (PBKDF2, default 200000).
|
|
150
|
+
|
|
151
|
+
### `decryptre identify`
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
decryptre identify --input <file|text|->
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Reports whether a value looks like MD5, SHA-1, SHA-256 or SHA-512, and reminds
|
|
158
|
+
you that these are one-way functions. It never claims to "decrypt" a hash.
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## Supported methods
|
|
163
|
+
|
|
164
|
+
| Method | Aliases | Encrypt | Decrypt without a key | Notes |
|
|
165
|
+
| --- | --- | --- | --- | --- |
|
|
166
|
+
| Base64 | `b64` | yes | yes | Padding is added automatically. |
|
|
167
|
+
| Base32 | `b32` | yes | yes | Case-insensitive. |
|
|
168
|
+
| Base16 / hex | `hex`, `b16` | yes | yes | Optional `0x` prefix. |
|
|
169
|
+
| URL encoding | `url`, `percent`, `urlencode` | yes | yes | Percent escapes and `+`. |
|
|
170
|
+
| ASCII85 | `a85` | yes | yes | Adobe `<~ ~>` wrappers accepted. |
|
|
171
|
+
| Caesar / ROT-N | `caesar`, `rot`, `rot-n`, `rot13` | yes | yes (all 26 shifts) | |
|
|
172
|
+
| Atbash | `atbash` | yes | yes | Only one possible result. |
|
|
173
|
+
| Vigenère | `vig` | yes | yes (key length 1-12) | Needs a decent amount of text. |
|
|
174
|
+
| Rail Fence | `railfence`, `rail`, `rail-fence` | yes | yes (2-12 rails) | |
|
|
175
|
+
| Simple substitution | `sub` | yes | best effort (trigram solver) | May be partially wrong; read the output. |
|
|
176
|
+
| XOR | `xor` | yes | yes (single byte, repeating key up to 32 bytes) | `decryptre:xor:` output is understood automatically. |
|
|
177
|
+
| Fernet | `fernet` | yes | dictionary attack only | PBKDF2 + SHA-256. |
|
|
178
|
+
| AES-GCM / AES-CBC | `aes`, `aes-gcm`, `aes-cbc` | yes | dictionary attack only | PBKDF2 or scrypt KDF. |
|
|
179
|
+
|
|
180
|
+
---
|
|
181
|
+
|
|
182
|
+
## How `--method auto` works
|
|
183
|
+
|
|
184
|
+
Auto mode peels one layer at a time:
|
|
185
|
+
|
|
186
|
+
1. Try every applicable encoding decode.
|
|
187
|
+
2. Try the classical cipher breakers.
|
|
188
|
+
3. Try XOR when the text is binary or just came out of an encoding.
|
|
189
|
+
4. Try the passphrase dictionary on DecryptRE containers.
|
|
190
|
+
5. Score every result with an offline English model (letter frequencies,
|
|
191
|
+
trigrams and common words), keep the best few as the next frontier, and
|
|
192
|
+
repeat up to `--max-depth`.
|
|
193
|
+
|
|
194
|
+
A visited set prevents cycles such as Base64 that decodes to itself, and
|
|
195
|
+
`--max-candidates` bounds the total work. When several results are plausible,
|
|
196
|
+
they are printed best-first so you can choose:
|
|
197
|
+
|
|
198
|
+
```text
|
|
199
|
+
[1] score= -6.430 method=vigenere key=lantern
|
|
200
|
+
The password is hidden under the third stone on the beach.
|
|
201
|
+
|
|
202
|
+
[2] score=-10.068 method=vigenere key=nheqqlmwk
|
|
203
|
+
Ran soytlerp it eirune ewyot apl tleog lyfor uc hig aidie.
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
Higher (less negative) scores look more like English. They are a ranking aid,
|
|
207
|
+
not a probability.
|
|
208
|
+
|
|
209
|
+
---
|
|
210
|
+
|
|
211
|
+
## The `decryptre:v1:` container
|
|
212
|
+
|
|
213
|
+
AES needs a salt, an IV/nonce and the KDF settings. Instead of asking you to
|
|
214
|
+
remember them, `encrypt` stores them beside the ciphertext in a small,
|
|
215
|
+
self-describing envelope:
|
|
216
|
+
|
|
217
|
+
```text
|
|
218
|
+
decryptre:v1:<urlsafe-base64 of a JSON object>
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
```json
|
|
222
|
+
{
|
|
223
|
+
"v": 1,
|
|
224
|
+
"alg": "aes-gcm",
|
|
225
|
+
"kdf": "pbkdf2",
|
|
226
|
+
"iterations": 200000,
|
|
227
|
+
"salt": "...",
|
|
228
|
+
"nonce": "...",
|
|
229
|
+
"tag": "...",
|
|
230
|
+
"ciphertext": "..."
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
Fernet containers store the Fernet token plus the salt and iteration count.
|
|
235
|
+
AES-GCM authenticates the whole envelope; AES-CBC is validated by padding.
|
|
236
|
+
A wrong passphrase raises a clear error instead of printing garbage.
|
|
237
|
+
|
|
238
|
+
XOR encryption prints `decryptre:xor:<base64>` for the same reason: it keeps
|
|
239
|
+
the ciphertext safe to copy through a terminal or a text file.
|
|
240
|
+
|
|
241
|
+
---
|
|
242
|
+
|
|
243
|
+
## Examples
|
|
244
|
+
|
|
245
|
+
The [`examples/`](examples/) folder contains ready-to-run ciphertexts and the
|
|
246
|
+
exact commands and output in [`examples/expected-output.md`](examples/expected-output.md).
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
decryptre decrypt --input examples/caesar.txt --method caesar
|
|
250
|
+
decryptre decrypt --input examples/vigenere.txt --method vigenere
|
|
251
|
+
decryptre decrypt --input examples/layered.txt
|
|
252
|
+
decryptre decrypt --input examples/fernet.txt --method fernet --key sunshine
|
|
253
|
+
```
|
|
254
|
+
|
|
255
|
+
---
|
|
256
|
+
|
|
257
|
+
## Wordlists
|
|
258
|
+
|
|
259
|
+
The bundled `decryptre/wordlists/common-passwords.txt` is the 10,000 most
|
|
260
|
+
common passwords list from [SecLists](https://github.com/danielmiessler/SecLists)
|
|
261
|
+
(MIT). Provenance and license are documented in
|
|
262
|
+
[`decryptre/wordlists/SOURCE.md`](decryptre/wordlists/SOURCE.md).
|
|
263
|
+
|
|
264
|
+
Use your own list with `--wordlist path/to/list.txt` (one candidate per line;
|
|
265
|
+
blank lines and `#` comments are ignored), or skip the bundled one with
|
|
266
|
+
`--no-wordlist`. A longer list means more KDF work, so it is slower.
|
|
267
|
+
|
|
268
|
+
The substitution solver uses aggregate English trigram statistics derived
|
|
269
|
+
from a public-domain book; see
|
|
270
|
+
[`decryptre/data/SOURCE.md`](decryptre/data/SOURCE.md). Only counts are
|
|
271
|
+
included, never any text from the source.
|
|
272
|
+
|
|
273
|
+
---
|
|
274
|
+
|
|
275
|
+
## Limitations
|
|
276
|
+
|
|
277
|
+
- **Modern crypto is not brute-forced.** Fernet/AES are only opened when the
|
|
278
|
+
passphrase is supplied or present in the wordlist.
|
|
279
|
+
- **Short text is hard.** Vigenère and substitution need a reasonable amount
|
|
280
|
+
of text; a five-word message may not be enough.
|
|
281
|
+
- **Substitution solving is best effort.** It usually solves a paragraph, but
|
|
282
|
+
always read the result before trusting it.
|
|
283
|
+
- **Hashes cannot be reversed.** `identify` only names the algorithm.
|
|
284
|
+
- **One layer at a time.** Auto mode follows a beam of promising results, not
|
|
285
|
+
every possible path. Increase `--max-depth`, `--max-candidates` or `--top`
|
|
286
|
+
if a deep puzzle is missed.
|
|
287
|
+
- **This is not a password cracker for online services.** It never connects to
|
|
288
|
+
anything.
|
|
289
|
+
|
|
290
|
+
---
|
|
291
|
+
|
|
292
|
+
## Development
|
|
293
|
+
|
|
294
|
+
```bash
|
|
295
|
+
python -m venv .venv
|
|
296
|
+
source .venv/bin/activate
|
|
297
|
+
pip install -e ".[dev]"
|
|
298
|
+
python -m pytest
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
The test suite covers every module, includes known cipher vectors, checks
|
|
302
|
+
layered detection, and asserts that the package imports no networking code.
|
|
303
|
+
|
|
304
|
+
Project layout:
|
|
305
|
+
|
|
306
|
+
```text
|
|
307
|
+
decryptre/
|
|
308
|
+
encodings.py Base64/Base32/Base16/URL/ASCII85
|
|
309
|
+
classical.py Caesar, Atbash, Vigenere, Rail Fence, substitution
|
|
310
|
+
xor.py XOR encryption and key recovery
|
|
311
|
+
modern_crypto.py Fernet, AES, dictionary attack, hash identification
|
|
312
|
+
containers.py the decryptre:v1 envelope
|
|
313
|
+
ngrams.py offline English trigram model
|
|
314
|
+
scorer.py English-likelihood scoring
|
|
315
|
+
auto_detect.py layered search
|
|
316
|
+
cli.py the command line
|
|
317
|
+
data/ trigram counts (+ source notes)
|
|
318
|
+
wordlists/ bundled passphrase list (+ source notes)
|
|
319
|
+
tests/ pytest suite
|
|
320
|
+
examples/ sample ciphertexts and expected output
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
---
|
|
324
|
+
|
|
325
|
+
## Contributing
|
|
326
|
+
|
|
327
|
+
Contributions are welcome, especially beginner-friendly ones.
|
|
328
|
+
|
|
329
|
+
1. Open an issue describing the bug or the method you want to add.
|
|
330
|
+
2. Fork the repository and create a branch.
|
|
331
|
+
3. Add tests for your change and run `python -m pytest`.
|
|
332
|
+
4. Keep the code readable: this project is maintained by someone learning.
|
|
333
|
+
5. Open a pull request with a short explanation.
|
|
334
|
+
|
|
335
|
+
Please keep DecryptRE offline and keep the "does not break modern encryption"
|
|
336
|
+
statements accurate.
|
|
337
|
+
|
|
338
|
+
---
|
|
339
|
+
|
|
340
|
+
## Credits
|
|
341
|
+
|
|
342
|
+
- [SecLists](https://github.com/danielmiessler/SecLists) for the common
|
|
343
|
+
password list (MIT).
|
|
344
|
+
- Project Gutenberg for the public-domain text used to derive trigram counts.
|
|
345
|
+
- The Python `cryptography` and `pycryptodome` projects for the crypto
|
|
346
|
+
primitives.
|
|
347
|
+
|
|
348
|
+
## License
|
|
349
|
+
|
|
350
|
+
[MIT](LICENSE) © 2026 Jason Marvello
|
|
@@ -0,0 +1,328 @@
|
|
|
1
|
+
# DecryptRE
|
|
2
|
+
|
|
3
|
+
DecryptRE is a free, open-source Python command-line tool that **decrypts text
|
|
4
|
+
with or without a passphrase** and can **encrypt it again** with the same
|
|
5
|
+
methods.
|
|
6
|
+
|
|
7
|
+
It handles encodings (Base64, Base32, hex, URL, ASCII85), classical ciphers
|
|
8
|
+
(Caesar/ROT-N, Atbash, Vigenère, Rail Fence, simple substitution), XOR, and
|
|
9
|
+
passphrase-based modern crypto (Fernet and AES). It also recognises common
|
|
10
|
+
hashes.
|
|
11
|
+
|
|
12
|
+
**Everything runs offline.** There are no API calls, no telemetry, no remote
|
|
13
|
+
wordlists, and no internet connection is needed after installation. A test in
|
|
14
|
+
the repository enforces this.
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
## ⚠️ Responsible use
|
|
19
|
+
|
|
20
|
+
DecryptRE is for **education, Capture-The-Flag puzzles, and data you own**.
|
|
21
|
+
|
|
22
|
+
- Only decrypt messages you created or have explicit permission to test.
|
|
23
|
+
- Do not use it against other people's accounts, files, or systems.
|
|
24
|
+
- "No passphrase" mode is a puzzle-solving aid, not a way to break real
|
|
25
|
+
encrypted services.
|
|
26
|
+
|
|
27
|
+
The authors accept no responsibility for misuse. See [LICENSE](LICENSE).
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## What it can and cannot do
|
|
32
|
+
|
|
33
|
+
| Situation | What DecryptRE does |
|
|
34
|
+
| --- | --- |
|
|
35
|
+
| Text is encoded (Base64, hex, ...) | Decodes it. Encodings are not encryption. |
|
|
36
|
+
| Text uses a classical cipher | Tries the parameters and ranks results by how much they look like English. |
|
|
37
|
+
| Text uses XOR with a short key | Recovers single-byte keys and repeating keys (up to 32 bytes). |
|
|
38
|
+
| Text uses Fernet / AES **and you know the passphrase** | Decrypts it. |
|
|
39
|
+
| Text uses Fernet / AES **and you do not know the passphrase** | Tries every passphrase in an offline wordlist (a *dictionary attack*). If the passphrase is not in the list, it cannot be recovered. That is the point of modern cryptography. |
|
|
40
|
+
| Text is a hash (MD5, SHA-1, SHA-256, SHA-512) | Identifies the likely algorithm and clearly states that hashes are **one-way** and cannot be decrypted. |
|
|
41
|
+
|
|
42
|
+
Two honest statements that the code and docs repeat:
|
|
43
|
+
|
|
44
|
+
1. **"No passphrase" is not magic.** For encodings and classical ciphers it is
|
|
45
|
+
a bounded parameter search. For modern crypto it is a dictionary attack.
|
|
46
|
+
2. **Modern encryption cannot be brute-forced by this tool.** A real AES or
|
|
47
|
+
Fernet key derived from a strong passphrase is out of reach.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
## Installation
|
|
52
|
+
|
|
53
|
+
Requirements: **Python 3.9 or newer**.
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
git clone https://github.com/JasonMarvello/DecryptRE.git
|
|
57
|
+
cd DecryptRE
|
|
58
|
+
python -m venv .venv
|
|
59
|
+
source .venv/bin/activate # Windows: .venv\Scripts\activate
|
|
60
|
+
pip install .
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
That installs the `decryptre` command. To work on the code instead:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pip install -e ".[dev]"
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
---
|
|
70
|
+
|
|
71
|
+
## Quick start
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
# Decode Base64
|
|
75
|
+
decryptre decrypt --input "SGVsbG8sIHdvcmxkIQ==" --method base64
|
|
76
|
+
|
|
77
|
+
# Break a Caesar cipher without knowing the shift
|
|
78
|
+
decryptre decrypt --input "Wkh txlfn eurzq ira" --method caesar
|
|
79
|
+
|
|
80
|
+
# Let DecryptRE try every supported layer
|
|
81
|
+
decryptre decrypt --input "V2xqcGNwbyBhZmtrd3BkIGxjcCBxZnk6IG9wbnpvcCB4cCwgZXNweSBkc3RxZSB4cCBtbG52Lg=="
|
|
82
|
+
|
|
83
|
+
# Decrypt something you encrypted with a passphrase
|
|
84
|
+
decryptre encrypt --input "Secret note" --method aes --key "correct horse battery staple"
|
|
85
|
+
decryptre decrypt --input "decryptre:v1:..." --method aes --key "correct horse battery staple"
|
|
86
|
+
|
|
87
|
+
# Identify a hash
|
|
88
|
+
decryptre identify --input 5d41402abc4b2a76b9719d911017c592
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
`--input` accepts a **file path**, a **literal string**, or `-` to read from
|
|
92
|
+
standard input.
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
## Commands
|
|
97
|
+
|
|
98
|
+
### `decryptre decrypt`
|
|
99
|
+
|
|
100
|
+
```bash
|
|
101
|
+
decryptre decrypt --input <file|text|-> [options]
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
| Option | Default | Meaning |
|
|
105
|
+
| --- | --- | --- |
|
|
106
|
+
| `--method NAME` | `auto` | Method to use. `auto` tries everything. |
|
|
107
|
+
| `--key TEXT` | none | Passphrase or cipher key. |
|
|
108
|
+
| `--shift N` | try all | Caesar shift. |
|
|
109
|
+
| `--rails N` | try 2-12 | Rail Fence rails. |
|
|
110
|
+
| `--wordlist PATH` | bundled list | Passphrase list for Fernet/AES. |
|
|
111
|
+
| `--no-wordlist` | off | Skip the bundled wordlist. |
|
|
112
|
+
| `--no-substitution` | off | Skip the slow substitution solver in `auto` mode. |
|
|
113
|
+
| `--max-depth N` | `3` | Maximum number of layers to peel in `auto` mode. |
|
|
114
|
+
| `--max-candidates N` | `2000` | Hard budget for `auto` mode. |
|
|
115
|
+
| `--top N` | `5` | How many results to print. |
|
|
116
|
+
| `-v`, `--verbose` | off | Show extra detail. |
|
|
117
|
+
|
|
118
|
+
### `decryptre encrypt`
|
|
119
|
+
|
|
120
|
+
```bash
|
|
121
|
+
decryptre encrypt --input <file|text|-> --method NAME [options]
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Uses the same method names. `--key` is required for Vigenère, XOR, Fernet and
|
|
125
|
+
AES. Extra options: `--shift` (Caesar, default 3), `--rails` (Rail Fence),
|
|
126
|
+
`--aes-mode gcm|cbc` (default `gcm`), `--kdf pbkdf2|scrypt` (default
|
|
127
|
+
`pbkdf2`), `--iterations` (PBKDF2, default 200000).
|
|
128
|
+
|
|
129
|
+
### `decryptre identify`
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
decryptre identify --input <file|text|->
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
Reports whether a value looks like MD5, SHA-1, SHA-256 or SHA-512, and reminds
|
|
136
|
+
you that these are one-way functions. It never claims to "decrypt" a hash.
|
|
137
|
+
|
|
138
|
+
---
|
|
139
|
+
|
|
140
|
+
## Supported methods
|
|
141
|
+
|
|
142
|
+
| Method | Aliases | Encrypt | Decrypt without a key | Notes |
|
|
143
|
+
| --- | --- | --- | --- | --- |
|
|
144
|
+
| Base64 | `b64` | yes | yes | Padding is added automatically. |
|
|
145
|
+
| Base32 | `b32` | yes | yes | Case-insensitive. |
|
|
146
|
+
| Base16 / hex | `hex`, `b16` | yes | yes | Optional `0x` prefix. |
|
|
147
|
+
| URL encoding | `url`, `percent`, `urlencode` | yes | yes | Percent escapes and `+`. |
|
|
148
|
+
| ASCII85 | `a85` | yes | yes | Adobe `<~ ~>` wrappers accepted. |
|
|
149
|
+
| Caesar / ROT-N | `caesar`, `rot`, `rot-n`, `rot13` | yes | yes (all 26 shifts) | |
|
|
150
|
+
| Atbash | `atbash` | yes | yes | Only one possible result. |
|
|
151
|
+
| Vigenère | `vig` | yes | yes (key length 1-12) | Needs a decent amount of text. |
|
|
152
|
+
| Rail Fence | `railfence`, `rail`, `rail-fence` | yes | yes (2-12 rails) | |
|
|
153
|
+
| Simple substitution | `sub` | yes | best effort (trigram solver) | May be partially wrong; read the output. |
|
|
154
|
+
| XOR | `xor` | yes | yes (single byte, repeating key up to 32 bytes) | `decryptre:xor:` output is understood automatically. |
|
|
155
|
+
| Fernet | `fernet` | yes | dictionary attack only | PBKDF2 + SHA-256. |
|
|
156
|
+
| AES-GCM / AES-CBC | `aes`, `aes-gcm`, `aes-cbc` | yes | dictionary attack only | PBKDF2 or scrypt KDF. |
|
|
157
|
+
|
|
158
|
+
---
|
|
159
|
+
|
|
160
|
+
## How `--method auto` works
|
|
161
|
+
|
|
162
|
+
Auto mode peels one layer at a time:
|
|
163
|
+
|
|
164
|
+
1. Try every applicable encoding decode.
|
|
165
|
+
2. Try the classical cipher breakers.
|
|
166
|
+
3. Try XOR when the text is binary or just came out of an encoding.
|
|
167
|
+
4. Try the passphrase dictionary on DecryptRE containers.
|
|
168
|
+
5. Score every result with an offline English model (letter frequencies,
|
|
169
|
+
trigrams and common words), keep the best few as the next frontier, and
|
|
170
|
+
repeat up to `--max-depth`.
|
|
171
|
+
|
|
172
|
+
A visited set prevents cycles such as Base64 that decodes to itself, and
|
|
173
|
+
`--max-candidates` bounds the total work. When several results are plausible,
|
|
174
|
+
they are printed best-first so you can choose:
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
[1] score= -6.430 method=vigenere key=lantern
|
|
178
|
+
The password is hidden under the third stone on the beach.
|
|
179
|
+
|
|
180
|
+
[2] score=-10.068 method=vigenere key=nheqqlmwk
|
|
181
|
+
Ran soytlerp it eirune ewyot apl tleog lyfor uc hig aidie.
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
Higher (less negative) scores look more like English. They are a ranking aid,
|
|
185
|
+
not a probability.
|
|
186
|
+
|
|
187
|
+
---
|
|
188
|
+
|
|
189
|
+
## The `decryptre:v1:` container
|
|
190
|
+
|
|
191
|
+
AES needs a salt, an IV/nonce and the KDF settings. Instead of asking you to
|
|
192
|
+
remember them, `encrypt` stores them beside the ciphertext in a small,
|
|
193
|
+
self-describing envelope:
|
|
194
|
+
|
|
195
|
+
```text
|
|
196
|
+
decryptre:v1:<urlsafe-base64 of a JSON object>
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
```json
|
|
200
|
+
{
|
|
201
|
+
"v": 1,
|
|
202
|
+
"alg": "aes-gcm",
|
|
203
|
+
"kdf": "pbkdf2",
|
|
204
|
+
"iterations": 200000,
|
|
205
|
+
"salt": "...",
|
|
206
|
+
"nonce": "...",
|
|
207
|
+
"tag": "...",
|
|
208
|
+
"ciphertext": "..."
|
|
209
|
+
}
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Fernet containers store the Fernet token plus the salt and iteration count.
|
|
213
|
+
AES-GCM authenticates the whole envelope; AES-CBC is validated by padding.
|
|
214
|
+
A wrong passphrase raises a clear error instead of printing garbage.
|
|
215
|
+
|
|
216
|
+
XOR encryption prints `decryptre:xor:<base64>` for the same reason: it keeps
|
|
217
|
+
the ciphertext safe to copy through a terminal or a text file.
|
|
218
|
+
|
|
219
|
+
---
|
|
220
|
+
|
|
221
|
+
## Examples
|
|
222
|
+
|
|
223
|
+
The [`examples/`](examples/) folder contains ready-to-run ciphertexts and the
|
|
224
|
+
exact commands and output in [`examples/expected-output.md`](examples/expected-output.md).
|
|
225
|
+
|
|
226
|
+
```bash
|
|
227
|
+
decryptre decrypt --input examples/caesar.txt --method caesar
|
|
228
|
+
decryptre decrypt --input examples/vigenere.txt --method vigenere
|
|
229
|
+
decryptre decrypt --input examples/layered.txt
|
|
230
|
+
decryptre decrypt --input examples/fernet.txt --method fernet --key sunshine
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
---
|
|
234
|
+
|
|
235
|
+
## Wordlists
|
|
236
|
+
|
|
237
|
+
The bundled `decryptre/wordlists/common-passwords.txt` is the 10,000 most
|
|
238
|
+
common passwords list from [SecLists](https://github.com/danielmiessler/SecLists)
|
|
239
|
+
(MIT). Provenance and license are documented in
|
|
240
|
+
[`decryptre/wordlists/SOURCE.md`](decryptre/wordlists/SOURCE.md).
|
|
241
|
+
|
|
242
|
+
Use your own list with `--wordlist path/to/list.txt` (one candidate per line;
|
|
243
|
+
blank lines and `#` comments are ignored), or skip the bundled one with
|
|
244
|
+
`--no-wordlist`. A longer list means more KDF work, so it is slower.
|
|
245
|
+
|
|
246
|
+
The substitution solver uses aggregate English trigram statistics derived
|
|
247
|
+
from a public-domain book; see
|
|
248
|
+
[`decryptre/data/SOURCE.md`](decryptre/data/SOURCE.md). Only counts are
|
|
249
|
+
included, never any text from the source.
|
|
250
|
+
|
|
251
|
+
---
|
|
252
|
+
|
|
253
|
+
## Limitations
|
|
254
|
+
|
|
255
|
+
- **Modern crypto is not brute-forced.** Fernet/AES are only opened when the
|
|
256
|
+
passphrase is supplied or present in the wordlist.
|
|
257
|
+
- **Short text is hard.** Vigenère and substitution need a reasonable amount
|
|
258
|
+
of text; a five-word message may not be enough.
|
|
259
|
+
- **Substitution solving is best effort.** It usually solves a paragraph, but
|
|
260
|
+
always read the result before trusting it.
|
|
261
|
+
- **Hashes cannot be reversed.** `identify` only names the algorithm.
|
|
262
|
+
- **One layer at a time.** Auto mode follows a beam of promising results, not
|
|
263
|
+
every possible path. Increase `--max-depth`, `--max-candidates` or `--top`
|
|
264
|
+
if a deep puzzle is missed.
|
|
265
|
+
- **This is not a password cracker for online services.** It never connects to
|
|
266
|
+
anything.
|
|
267
|
+
|
|
268
|
+
---
|
|
269
|
+
|
|
270
|
+
## Development
|
|
271
|
+
|
|
272
|
+
```bash
|
|
273
|
+
python -m venv .venv
|
|
274
|
+
source .venv/bin/activate
|
|
275
|
+
pip install -e ".[dev]"
|
|
276
|
+
python -m pytest
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
The test suite covers every module, includes known cipher vectors, checks
|
|
280
|
+
layered detection, and asserts that the package imports no networking code.
|
|
281
|
+
|
|
282
|
+
Project layout:
|
|
283
|
+
|
|
284
|
+
```text
|
|
285
|
+
decryptre/
|
|
286
|
+
encodings.py Base64/Base32/Base16/URL/ASCII85
|
|
287
|
+
classical.py Caesar, Atbash, Vigenere, Rail Fence, substitution
|
|
288
|
+
xor.py XOR encryption and key recovery
|
|
289
|
+
modern_crypto.py Fernet, AES, dictionary attack, hash identification
|
|
290
|
+
containers.py the decryptre:v1 envelope
|
|
291
|
+
ngrams.py offline English trigram model
|
|
292
|
+
scorer.py English-likelihood scoring
|
|
293
|
+
auto_detect.py layered search
|
|
294
|
+
cli.py the command line
|
|
295
|
+
data/ trigram counts (+ source notes)
|
|
296
|
+
wordlists/ bundled passphrase list (+ source notes)
|
|
297
|
+
tests/ pytest suite
|
|
298
|
+
examples/ sample ciphertexts and expected output
|
|
299
|
+
```
|
|
300
|
+
|
|
301
|
+
---
|
|
302
|
+
|
|
303
|
+
## Contributing
|
|
304
|
+
|
|
305
|
+
Contributions are welcome, especially beginner-friendly ones.
|
|
306
|
+
|
|
307
|
+
1. Open an issue describing the bug or the method you want to add.
|
|
308
|
+
2. Fork the repository and create a branch.
|
|
309
|
+
3. Add tests for your change and run `python -m pytest`.
|
|
310
|
+
4. Keep the code readable: this project is maintained by someone learning.
|
|
311
|
+
5. Open a pull request with a short explanation.
|
|
312
|
+
|
|
313
|
+
Please keep DecryptRE offline and keep the "does not break modern encryption"
|
|
314
|
+
statements accurate.
|
|
315
|
+
|
|
316
|
+
---
|
|
317
|
+
|
|
318
|
+
## Credits
|
|
319
|
+
|
|
320
|
+
- [SecLists](https://github.com/danielmiessler/SecLists) for the common
|
|
321
|
+
password list (MIT).
|
|
322
|
+
- Project Gutenberg for the public-domain text used to derive trigram counts.
|
|
323
|
+
- The Python `cryptography` and `pycryptodome` projects for the crypto
|
|
324
|
+
primitives.
|
|
325
|
+
|
|
326
|
+
## License
|
|
327
|
+
|
|
328
|
+
[MIT](LICENSE) © 2026 Jason Marvello
|