Ares, the ciphey rewrite: an A* search over candidate decodings

The decoder tries paths, not single ciphers

The original Ciphey decides which decoding to try next, and the README of this Rust rewrite argues that this is the slow part. The claim is quantitative: for every one decode Ciphey can do, ciphey can do about seven, which the project puts at a 700 percent increase in speed. The mechanism behind that claim is a search algorithm rather than a faster decoder. ciphey uses A* search, with a heuristic that estimates the cost of reaching the goal from the current state. The goal is a string that looks like plain text, and the cost is how unlikely that string looks. So instead of a linear chain of guesses, ciphey explores a tree of decoding paths and follows the most promising branch, which is why an input that needs Rot13 then Base64 is found without trying the whole cross product of the sixteen decoders.

How the heuristic and the search interact

The details of the search are worth reading, because the naive version of this idea is much slower than the project claims. Three things make it work. First, very fast decoders such as Base64 are exempted from the heuristic and are run first at every node, since applying them is cheap and often productive. Second, the heuristic for the remaining decoders comes from cipher_identifier, which returns the probability that a given string is a particular cipher, so the estimate reflects how plausible each next step is rather than a fixed cost per decoder. Third, results are cached so a path already explored is not recomputed, and the search tree is pruned to keep memory usage down. On top of that the tool tracks statistics per decoder and reorders them dynamically, so Caesar, which the README describes as popular, is tried before Beaufort, which is not.

Plaintext detection is the part that decides the answer

A search needs a way to know when it has arrived, and that is the gibberish detection layer. The project describes it as configurable sensitivity, which allows more accurate plain text identification across different encodings, with classical ciphers such as Caesar using low sensitivity to handle English-like results better while most other decoders default to medium. The stated purpose is to reduce false positives and false negatives, making the tool more reliable across a wider range of encoded texts. The underlying checkers are a qudgaram, trigram and English dictionary checker used to calculate the probability of plain text, with the thresholds changed depending on the cipher, since Caesar returns text that looks like English while Base64 does not. There is also a database of about 500 popular regular expressions covering API keys and MAC addresses, and an is_password function that checks whether a string is an exact password seen in a data dump.

A 500 MB model is optional, not default

The newer option is enhanced plain text detection using a BERT-based model taken from the gibberish-or-not crate, and it is the one feature with a real cost. The README states that it increases plain text detection accuracy by approximately 40 percent and reduces false positives and false negatives. It can be enabled during first-run setup or later with a flag, and it requires a one-time download of a 500MB AI model, which needs a free Hugging Face account. The Cargo manifest shows where that weight comes from in the dependency tree, with the rand and half versions pinned to specific values for candle-core compatibility, which is the BERT runtime. The distinction to hold on to is that this is opt-in: the default path is the heuristic checkers, and the model is a heavier but more accurate alternative.

A timer so a failed decode does not hang

The README names the original tool's worst failure mode directly. Ciphey could run forever, and if it could not decode your text you would never know. ciphey carries a timer built into both the library and the CLI, so the search eventually expires rather than spinning. The CLI defaults to five seconds, and the Discord bot defaults to ten, with the reason given being that network messages take time to send. This is a sensible design decision that changes how the tool behaves in practice. A search that finds nothing in five seconds tells you something, whereas a hanging process tells you nothing and has to be killed. The timeout is also what makes the tool safe to run from a script without a wrapper.

Installing from Cargo or building the container

Three ways in are described. The simplest is the Discord server, where you join, go to the bots channel and use the bot with the $ciphey command, with $help for the usage information. The second best, for a local machine, is Cargo.

cargo install ciphey

After that you run it with ciphey. The third option is to clone the repository and build a container image, since the project ships a Dockerfile.

docker build .

The Dockerfile is a two-stage Alpine build. The builder stage uses the rust:alpine image with build-base, pkgconfig and openssl-dev installed, copies the manifest, the lock file, the source and the benches, and runs cargo build --release. The runtime stage is alpine:3.12 and copies only the compiled binary to /usr/local/bin/ciphey with the entrypoint set to it. So the shipped image contains no toolchain and no source, just the binary.

Library first, with a CLI on top

The project describes itself as library first, with two main parts: the library and the CLI, where the CLI simply uses the library. That is what makes the tool usable as a component. The listed things built on top are a Discord bot, better testing of the whole program, and the CLI itself. The Cargo manifest confirms the split, with a lib target named ciphey pointing at src/lib.rs and a bin target pointing at src/main.rs, both marked as not for benchmarking. Development uses cargo-nextest for the test runner, criterion for the benchmarks in the benches directory, and a justfile that wraps the common workflows: build-all runs cargo build and docker build, test-all runs build, check, clippy and test, and the fix target runs clippy with the fix flag and then cargo fmt before committing.

Where ciphey is the wrong tool

Four limits are clear. First, this is a decoding tool for ciphers and encodings, not a cryptanalysis tool with a key, so an input protected by a real cipher with a key you do not have is not its problem to solve. Second, the plain text heuristic is a probability, so it can be wrong in both directions, and the README itself frames the sensitivity levels and the BERT option as attempts to reduce that error rather than eliminate it. Third, the sixteen decoders are a fixed list, and while the README says the project intends to grow towards the roughly fifty that Ciphey supports, the coverage today is a subset. Fourth, the tool is a decoder for text you have been given. Running it over credentials you are not authorised to read is not a use case the project is built for, and the presence of an is_password check against known data dumps is a feature for analysing dumps you already hold, not a search tool.

Testing, releases and the project it replaces

The project claims around 120 tests, documentation tests that keep the docs from going stale, and enforced documentation on all of the major components. The repository root backs that up with a tests directory, benches, a docs directory and a Cargo.lock. Releases are named rather than numbered plainly, with v0.10.0 called Amphitrite and 0.9.0 called Paidia, and the 0.11.0 release is labelled as major changes. The Cargo manifest carries version 0.12.0, so the manifest is ahead of the last tagged release, and the last push to the repository was on 2026-10-13. The licence field on the repository says MIT, and the project states that it fully intends to replace Ciphey with ciphey, by the same people who built the original.

Editorial conclusion

Use ciphey when you are given an encoded string and no key, and you need to find the plain text quickly, because the A* search with a plaintext heuristic is what lets it explore nested encodings instead of guessing one cipher at a time. Do not turn it on production systems or point it at data you are not authorised to read, and be careful with the enhanced detection mode, since enabling it downloads a 500MB model that needs a Hugging Face account. Verify first that the plain text you get back is actually the answer rather than a coincidence of the heuristic, that the 5 second CLI timer is long enough for your input, and that your system can store a half gigabyte model if you intend to use the BERT-based detection.

Frequently asked questions

Official sources

1. bee-san/Ares on GitHub
2. Issues
3. License: MIT
4. README
5. Releases