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.
Files changed (35) hide show
  1. decryptre-0.1.0/LICENSE +21 -0
  2. decryptre-0.1.0/PKG-INFO +350 -0
  3. decryptre-0.1.0/README.md +328 -0
  4. decryptre-0.1.0/decryptre/__init__.py +11 -0
  5. decryptre-0.1.0/decryptre/__main__.py +6 -0
  6. decryptre-0.1.0/decryptre/auto_detect.py +231 -0
  7. decryptre-0.1.0/decryptre/classical.py +426 -0
  8. decryptre-0.1.0/decryptre/cli.py +373 -0
  9. decryptre-0.1.0/decryptre/containers.py +47 -0
  10. decryptre-0.1.0/decryptre/data/SOURCE.md +33 -0
  11. decryptre-0.1.0/decryptre/data/trigrams.txt +5892 -0
  12. decryptre-0.1.0/decryptre/encodings.py +193 -0
  13. decryptre-0.1.0/decryptre/models.py +37 -0
  14. decryptre-0.1.0/decryptre/modern_crypto.py +280 -0
  15. decryptre-0.1.0/decryptre/ngrams.py +76 -0
  16. decryptre-0.1.0/decryptre/scorer.py +168 -0
  17. decryptre-0.1.0/decryptre/wordlists/SOURCE.md +25 -0
  18. decryptre-0.1.0/decryptre/wordlists/common-passwords.txt +10001 -0
  19. decryptre-0.1.0/decryptre/xor.py +144 -0
  20. decryptre-0.1.0/decryptre.egg-info/PKG-INFO +350 -0
  21. decryptre-0.1.0/decryptre.egg-info/SOURCES.txt +33 -0
  22. decryptre-0.1.0/decryptre.egg-info/dependency_links.txt +1 -0
  23. decryptre-0.1.0/decryptre.egg-info/entry_points.txt +2 -0
  24. decryptre-0.1.0/decryptre.egg-info/requires.txt +5 -0
  25. decryptre-0.1.0/decryptre.egg-info/top_level.txt +1 -0
  26. decryptre-0.1.0/pyproject.toml +45 -0
  27. decryptre-0.1.0/setup.cfg +4 -0
  28. decryptre-0.1.0/tests/test_auto_detect.py +47 -0
  29. decryptre-0.1.0/tests/test_classical.py +86 -0
  30. decryptre-0.1.0/tests/test_cli.py +76 -0
  31. decryptre-0.1.0/tests/test_encodings.py +52 -0
  32. decryptre-0.1.0/tests/test_modern_crypto.py +88 -0
  33. decryptre-0.1.0/tests/test_offline.py +30 -0
  34. decryptre-0.1.0/tests/test_scorer.py +45 -0
  35. decryptre-0.1.0/tests/test_xor.py +52 -0
@@ -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.
@@ -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