If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/bee-san/Ciphey shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1d ago
• 3 active contributors
• Distributed ownership (top contributor 39% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Small team — 3 contributors active in recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live bee-san/Ciphey repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/bee-san/Ciphey.

What it runs against: a local clone of bee-san/Ciphey — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in bee-san/Ciphey | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of bee-san/Ciphey. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/bee-san/Ciphey.git
#   cd Ciphey
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of bee-san/Ciphey and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "bee-san/Ciphey(\\.git)?\\b" \\
  && ok "origin remote is bee-san/Ciphey" \\
  || miss "origin remote is not bee-san/Ciphey (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/main.rs" \\
  && ok "src/main.rs" \\
  || miss "missing critical file: src/main.rs"
test -f "src/lib.rs" \\
  && ok "src/lib.rs" \\
  || miss "missing critical file: src/lib.rs"
test -f "src/checkers/mod.rs" \\
  && ok "src/checkers/mod.rs" \\
  || miss "missing critical file: src/checkers/mod.rs"
test -f "src/decoders/README.md" \\
  && ok "src/decoders/README.md" \\
  || miss "missing critical file: src/decoders/README.md"
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/bee-san/Ciphey"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Ciphey is a high-speed automated decryption and decoding library written in Rust that identifies and cracks unknown ciphers, encodings, and hashes without requiring the encryption key. It combines decoders (Base64, Base91, Base58, Z85, Brainfuck, etc.), checkers (gibberish detection via gibberish-or-not, wordlist validation), and an A* pathfinding algorithm to test ~7 decoding chains per second—7x faster than its Python predecessor—and enforces a configurable timeout (5s CLI default, 10s Discord bot) to prevent infinite execution. Hybrid library + CLI: src/lib.rs exports the core decoding engine (dependency-injected decoders, checkers, and A* solver), src/main.rs wraps it for CLI use with clap argument parsing. Supporting infrastructure: benches/ contains criterion benchmarks for crackers/decoders/checkers, docs/ houses architecture docs (especially docs/ares_architecture.md and docs/astar_algorithm_improvements.md for the current search strategy), configuration via TOML, and embedded wordlists via include_dir! macro.

Security researchers, CTF competitors, and incident responders who need to quickly crack unknown encrypted or encoded artifacts during forensic investigations or capture-the-flag competitions; developers building automation tools (Discord bots, CLI apps, backend services) who want to integrate decryption capabilities without reimplementing cipher detection logic.

Actively developed and production-ready. The project uses aggressive release builds (profile.release with LTO, symbol stripping, single codegen unit), maintains ~120+ tests across benches/ and embedded documentation tests, runs comprehensive CI workflows (codespell, dependency review, security scorecards in .github/workflows/), and publishes to crates.io as v0.12.0. Recent changelogs (docs/changes/ dated 2024-07) show active feature work (Vigenère decoder, A* refactoring, wordlist checker).

Low-to-moderate risk. The single maintainer (bee-san) is mitigated by the library-first design and active GitHub workflow automation; the dependency tree is substantial (~35 direct deps across encoding, database, ML) but all pinned in Cargo.lock. The A* algorithm refactors (docs/changes/2024-07-10-astar-*.md) suggest ongoing architecture changes that could introduce subtle bugs in decoder selection. No visible deprecation warnings in the codebase, but the 0.12.0 version suggests pre-1.0 API surface may shift.

Active development on A* heuristic refinement: recent change logs (docs/changes/2024-07-10-*.md) document removal of decoder popularity weighting, simplified heuristic rewrites, and improved string pruning. Work ongoing on expanding decoder coverage (Vigenère added 2024-03-21), sensitivity trait standardization, and database/wordlist improvements. Discord bot and CLI are stable outputs from the library.

git clone https://github.com/bee-san/ciphey.git
cd ciphey
cargo build --release
cargo install --path .
ciphey --help

Or use cargo install ciphey directly, or docker build . for containerized usage.

Daily commands:

cargo run --release -- <ciphertext>

Or as library in Rust code:

use ciphey::crack;
let result = crack(input_text, timeout_secs).await;

For development: cargo test (with serial_test for test isolation), cargo bench --bench benchmark_whole_program for performance profiling.

• src/main.rs — CLI entry point; initializes the application, parses user input, and orchestrates the main decryption/decoding workflow
• src/lib.rs — Library root; exposes the public API and core modules (checkers, decoders, crackers) for programmatic use
• src/checkers/mod.rs — Core abstraction for result validation; all decoders and crackers depend on checkers to confirm plaintext correctness
• src/decoders/README.md — Architecture documentation for decoder implementations; essential to understand how new encodings are added
• Cargo.toml — Rust manifest with build configuration; defines all external dependencies including cipher_identifier and lemmeknow
• docs/ares_architecture.md — High-level system design documentation describing A* search algorithm, heuristic strategy, and overall pipeline
• src/cli_input_parser/mod.rs — Parses CLI arguments and constructs configuration; bridges user intent to internal execution engine

Add a New Decoder (e.g., Base32)

1. Create a new decoder module file in src/decoders/ following the naming convention (src/decoders/base32.rs)
2. Implement the Decoder trait with decode() method and metadata (name, description) (src/decoders/base32.rs)
3. Register the decoder in the module tree and export from src/decoders/mod.rs (src/decoders/mod.rs)
4. Add benchmark test to measure decode performance relative to other decoders (benches/benchmark_decoders.rs)
5. Document the decoder's behavior, limitations, and sensitivity trait (if applicable) in inline comments (src/decoders/base32.rs)

Add a New Checker (e.g., Custom API Validation)

1. Create a new checker module in src/checkers/ implementing the CheckerType trait (src/checkers/custom_api_checker.rs)
2. Implement check() to call your external API and return CheckerResult (src/checkers/custom_api_checker.rs)
3. Add the new variant to CheckerType enum (src/checkers/checker_type.rs)
4. Register in the checker factory/dispatcher logic in src/checkers/mod.rs (src/checkers/mod.rs)
5. Add benchmark to src/checkers/ or benches/benchmark_checkers.rs to measure latency (benches/benchmark_checkers.rs)

Add a New CLI Flag or Configuration Option

1. Define new field in the config struct (likely in src/config/mod.rs or a clap derive struct) (src/config/mod.rs)
2. Add clap attribute to CLI argument parser in src/cli_input_parser/mod.rs (src/cli_input_parser/mod.rs)
3. Parse and pass the flag through src/main.rs into the orchestration logic (src/main.rs)
4. Update help text and add usage example to docs (docs/README.md)

Optimize Search Heuristic for New Cipher Type

1. Review current A* heuristic design and node weighting in docs/astar.md (docs/astar.md)
2. Profile execution on your cipher type using benches/benchmark_whole_program.rs (benches/benchmark_whole_program.rs)
3. Modify heuristic weights or pruning rules (likely in core search module, referenced in docs/ares_architecture.md) (docs/ares_architecture.md)
4. Re-benchmark and document the change in docs/changes/ with a new change record (docs/changes)

• Rust — Performance-critical tool for brute-forcing and searching; Rust provides zero-cost abstractions, memory safety, and fearless concurrency without GC overhead
• A Search (docs/astar.md)* — Efficient graph traversal with heuristics to prioritize high-likelihood decoding paths and avoid exploring dead-ends early
• cipher_identifier crate — Rapid cipher type detection to bootstrap the search with likely candidates, reducing search space
• gibberish-or-not & lemmeknow — Fast language and pattern recognition checkers; gibberish-or-not detects English via entropy/frequency, lemmeknow matches known formats (URLs, emails, etc.)
• Crossbeam parallelism — Work-stealing thread pools for parallel decoder execution without blocking; multiple CPUs attack different cipher candidates simultaneously
• Clap CLI framework — Declarative argument parsing with derive macros; reduces boilerplate and maintains consistency with standard Unix conventions

• Pluggable checker architecture with multiple backends (English, Regex, Wordlist, Athena, Human)
  • Why: undefined
  • Consequence: undefined

1. Timeout enforcement: Both library and CLI enforce a timeout (5s CLI, 10s Discord bot), so long-running decoders may be killed mid-execution; custom code must respect Decoder::timeout() contracts. 2. Database mmap'd file: memmap2 is used for wordlist reads; ensure the database file is not corrupted or the process may panic; wordlist path is configurable but defaults to built-in via include_dir!. 3. A heuristic sensitivity:* Recent refactors (docs/changes/2024-07-10-*) removed popularity weighting; changing heuristic scoring can dramatically degrade search performance or cause the solver to miss solutions. 4. Single-threaded event loop: Despite rayon and crossbeam deps, the main search loop is single-threaded; decoder parallelism happens at the wordlist-checker level only. 5. No persistence of partial results: If the timeout expires, all work is lost; there is no checkpointing or incremental solving.

• A* Search Algorithm — Core to Ciphey's performance: instead of exhaustive decoder testing, A* uses a heuristic (gibberish score, wordlist membership) to prioritize promising decoding paths, enabling the 7x speed improvement over exhaustive Python Ciphey.
• Pluggable Trait-Based Architecture — Decoders, checkers, and crackers are decoupled via Rust traits; new decoding methods (Vigenère, ROT13, etc.) are added without modifying core search logic, enabling rapid expansion to the 16+ decoder count.
• Natural Language Processing for Validation (Gibberish Detection) — The gibberish-or-not crate (v5.0.7) provides probabilistic scoring of whether decoded output looks like English; this is critical for the checker phase to distinguish valid decryptions from false positives.
• Memory-Mapped I/O — Wordlist reading via memmap2 allows Ciphey to check millions of words against decoded text without loading entire dictionaries into RAM, crucial for sustained performance across long inputs.
• Work-Stealing Parallelism (Rayon) — Rayon's parallel iterators are used in wordlist checkers to test multiple candidate words simultaneously across CPU cores, enabling linear speed scaling for I/O-heavy validation phases.
• Timeout-Driven Termination — Unlike Python Ciphey which could run indefinitely, Ciphey implements hard timeout enforces (5s CLI, 10s Discord) to guarantee bounded execution; critical for server-side deployments and user experience.
• Cryptanalysis (Frequency Analysis, Pattern Matching) — Decoders like ROT variants and substitution ciphers rely on frequency-based heuristics; LemmeKnow provides pattern libraries (regex) to pre-identify cipher families before attempting decode, reducing search space.

• bee-san/ciphey — The original Python-based Ciphey; this Rust project explicitly aims to replace it with 7x speed improvement.
• bee-san/discord-bot — Official Discord bot integration built on top of the Ciphey library, demonstrating the library-first architecture in production.
• swanandx/lemmeknow — Rust port of PyWhat (format identifier); Ciphey depends on it (v0.8.0 in Cargo.toml) for rapid cipher/encoding type detection before attempting decryption.
• RustCrypto/cryptography-rs — Ecosystem reference for cryptographic primitives; Ciphey focuses on detection and brute-force cracking rather than implementing low-level crypto, so it complements rather than competes.
• tytso/e4crypt — Linux ext4 encryption tool; relevant for understanding filesystem-level encryption scenarios Ciphey might encounter in forensic contexts.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for decoder pipeline chaining

The repo has benchmark files (benches/benchmark_decoders.rs, benches/benchmark_crackers.rs) but lacks comprehensive integration tests for the A* decoder chaining logic. Given the complex decoder-specific node implementation (docs/astar_decoder_specific_nodes.md) and sensitivity trait system (docs/2024-07-02-sensitivity-trait.md), new contributors should add tests validating that decoders chain correctly through the A* search algorithm, particularly edge cases around plaintext identification (docs/plaintext_identification.md) and multiple valid decoding paths.

• [ ] Create tests/integration_decoders.rs for end-to-end decoder chaining scenarios
• [ ] Test multi-stage decoding (e.g., base64 → base91 → plaintext detection)
• [ ] Validate sensitivity trait behavior with different decoder combinations (referencing docs/sensitivity.md)
• [ ] Add tests for the wait-athena checker pattern documented in docs/2024-07-10-wait-athena-checker.md
• [ ] Run benchmarks to ensure no performance regression (benches/benchmark_whole_program.rs)

Implement missing CI workflow for Rust security audit and MSRV validation

The repo has comprehensive CI (.github/workflows/) including scorecards, dependabot, and codespell, but lacks a security audit workflow and Minimum Supported Rust Version (MSRV) testing. With production-ready release builds and security considerations documented in SECURITY.md, adding GitHub Actions to validate the crate against cargo-audit and test against an explicit MSRV (declared in Cargo.toml) would strengthen supply chain security.

• [ ] Create .github/workflows/security-audit.yml using cargo-audit or rustsec
• [ ] Add MSRV field to Cargo.toml (currently missing; appears to be Rust 2021 edition)
• [ ] Create .github/workflows/msrv-check.yml that tests against declared MSRV using rustup
• [ ] Ensure workflows run on PR and push events (mirroring existing patterns in .github/workflows/codespell.yml)
• [ ] Document MSRV policy in CONTRIBUTING.md (currently not in file list)

Add structured benchmarking documentation and regression tracking

The repo has 4 benchmark files (benches/benchmark_checkers.rs, benches/benchmark_crackers.rs, benches/benchmark_decoders.rs, benches/benchmark_whole_program.rs) with criterion configured, but no documentation on running benchmarks or comparing results. Given the profile.release optimizations (LTO, codegen-units=1) and complex A* algorithm documented in docs/astar.md, contributors should add benchmark documentation and set up baseline tracking to catch performance regressions.

• [ ] Create docs/BENCHMARKING.md explaining how to run each benchmark file with criterion
• [ ] Document what each benchmark measures (e.g., decoding throughput, A* search iterations)
• [ ] Add a new GitHub workflow (docs/changes reference suggests this is relevant) that runs benchmarks on PRs against main branch
• [ ] Include instructions for saving/comparing baseline results using criterion's compare feature
• [ ] Add example output showing expected performance ranges for each benchmark

• Add missing decoder benchmarks: benches/benchmark_decoders.rs exists but the file structure suggests not all decoders (Brainfuck, Z85, Base65536) are explicitly benchmarked; add criterion benchmarks for each decoder's encode/decode cycle to establish performance baselines and catch regressions.
• Expand decoder documentation tests: The codebase enforces docs but src/decoders/ likely lacks /// # Examples sections for every decoder; add doctest examples (e.g., /// # Examples\n/// \``\n/// ciphey::decoders::base64::decode("SGVsbG8=")\n/// ```) for at least 5 decoders to improve discoverability.
• Implement Decoder trait for ROT13: Searching the decoders/ directory suggests ROT13 is missing despite being mentioned in the 16-decoder count; implement src/decoders/rot13.rs with configurable shift (1-25) and integrate into the decoder registry to expand coverage of simple substitution ciphers.

The Ciphey project demonstrates reasonable security awareness with a documented security policy and incident response plan. However, there are several areas requiring attention: (1)

• High · Outdated Alpine Linux Base Image — Dockerfile, line: FROM alpine:3.12. The Dockerfile uses 'alpine:3.12' which was released in 2020 and is no longer maintained. This image contains known vulnerabilities and security patches that are no longer being applied. Alpine 3.12 reached end-of-life in 2021. Fix: Update to a recent stable Alpine version such as 'alpine:3.20' or 'alpine:latest' to ensure security patches are applied.
• Medium · Missing Security Headers in Docker Build — Dockerfile. The Dockerfile lacks security best practices such as running as a non-root user. The application runs with root privileges inside the container, which increases the impact of any potential container escape or application vulnerability. Fix: Add a non-root user and configure the container to run as that user. Example: 'RUN addgroup -g 1000 ciphey && adduser -D -u 1000 -G ciphey ciphey' and 'USER ciphey'.
• Medium · Potential Security Dependency: rusqlite with bundled SQLite — Cargo.toml, rusqlite dependency. The dependency 'rusqlite' uses the 'bundled' feature which compiles SQLite from source. While this ensures compatibility, it may not receive security updates as quickly as system-managed SQLite packages, and the bundled version needs to be manually tracked for vulnerabilities. Fix: Monitor SQLite security advisories closely. Consider using the system SQLite when available, or regularly update the bundled version. Implement dependency scanning in CI/CD pipeline.
• Medium · Unsafe Deserialization via serde — src/api_library_input_struct.rs, serde dependency in Cargo.toml. The codebase uses serde for serialization/deserialization. Without explicit validation of input sources, there is a potential risk of deserialization attacks if untrusted data is deserialized. The API library input struct (api_library_input_struct.rs) may be vulnerable. Fix: Implement strict input validation for all deserialized data. Use serde validators or custom validation logic. Consider using a schema validation library. Document which input sources are trusted.
• Medium · Missing HTTPS Configuration for API — src/api_library_input_struct.rs. The repository appears to expose an API library interface but there's no visible enforcement of HTTPS/TLS for communications, and no security headers configuration is documented. Fix: Implement TLS/HTTPS enforcement for all API endpoints. Add security headers (HSTS, CSP, X-Frame-Options). Document security requirements for API consumers.
• Low · Fixed Dependency Version Constraint — Cargo.toml, half dependency. The 'half' dependency is pinned to exactly version '2.7.1' with '=2.7.1', which may prevent security updates from being applied automatically and could lock in vulnerabilities. Fix: Use a more flexible version constraint like '2.7.1' or '2.7' to allow patch updates, while still maintaining compatibility. Monitor for security updates to this dependency.
• Low · Missing Dependency Version Bounds — Cargo.toml, multiple dependencies. Several dependencies use wildcard or minimal version specifications without upper bounds (e.g., 'ansi_term = 0.12.1'), which could potentially pull in breaking changes or unmaintained versions. Fix: Review and specify appropriate version bounds for all dependencies. Use caret (^) for compatible versions and tilde (~) for patch updates as appropriate.
• Low · Verbose Panic Handling in Release Build — Cargo.toml, human-panic dependency. The release profile sets 'panic = abort', which is appropriate, but the 'human-panic' dependency may expose stack traces or system information in error messages that could leak sensitive information. Fix: Configure human-panic to provide user-friendly messages without exposing technical details. Test error output to ensure no sensitive information is leaked.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.