Metadata-Version: 2.4
Name: encid
Version: 1.0.0
Summary: Fast recursive decoder and identifier for encodings, hashes, ciphertext, and CTF-style data.
Project-URL: Homepage, https://admin12121.com
Project-URL: Source, https://github.com/admin12121/encid
Project-URL: Issues, https://github.com/admin12121/encid/issues
Author: admin12121
Maintainer: admin12121
License-Expression: MIT
License-File: LICENSE
Keywords: cryptography,ctf,decoder,forensics,hash,identifier
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: bcrypt>=4.1
Requires-Dist: cryptography>=42
Description-Content-Type: text/markdown

# encid

`encid` is a terminal tool for CTF, cryptography, and forensic triage. It identifies encoded data, structured password hashes, encryption wrappers, ciphertext-like material, file signatures, and ambiguous raw bytes, then recursively decodes safe layers while reporting confidence, evidence, warnings, and the full decode chain.

The project is maintained by **admin12121**.

- Website: https://admin12121.com
- Source: https://github.com/admin12121/encid
- Issues: https://github.com/admin12121/encid/issues

`encid` is heuristic by design. Some values cannot be proven from bytes alone. For example, a 128-character hex string may be SHA-512, SHA3-512, BLAKE2b, KDF output, key material, ciphertext, or random bytes. In those cases, encid reports ambiguity instead of claiming a false exact answer.

## Status

Current public release target: **0.2.0**.

The project is actively monitored and updated. The `0.x` series is intended to be useful and installable while the API and output schema continue to evolve before a future `1.0.0` stable release.

## Installation

Install from PyPI after publication:

```bash
uv tool install -U encid
encid --version
```

Install directly from a Git checkout:

```bash
git clone https://github.com/admin12121/encid.git
cd encid
uv tool install -e .
encid --version
```

Run from the repository during development:

```bash
uv sync
uv run encid "SGVsbG8="
```

`encid` depends on maintained `bcrypt` and `cryptography` packages for password verification and supported decrypt operations. It does not implement cryptographic primitives by hand.

## Quick Start

```bash
encid
encid open tui
encid --no-tui "SGVsbG8="
encid --json "7069636f4354467b6865785f746573747d"
encid --all --explain "MULTI_LAYER_STRING"
encid --risky "CLASSICAL_OR_ESOLANG_CTF_TEXT"
```

When attached to a real terminal, `encid` opens the interactive TUI by default. Use `--no-tui` for one-shot text output and `--json` for machine-readable output.

Quote inputs that contain shell metacharacters, especially password hashes with `$`:

```bash
encid '$2b$10$d/J7oricbiXeHkPdELJYLu6UXJ6vK98ftQImJOBpGY3G.lAVRvhW.'
```

## TUI Commands

```text
/help      show commands
/bye       exit
/clear     clear the console
/risky     enable broader decoders
/safe      disable risky decoders
/all       toggle alternate candidate chains
/explain   toggle reasons and evidence
/json      toggle JSON rendering inside the TUI
/depth N   set recursive decode depth
/decrypt   start password/key verification or decryption
/type T    choose bcrypt, sha256, xor, aes-256-cbc, and other supported types
/passwd    enter password/key with masked input
```

Command suggestions appear in a popup while typing `/`.

## Decode And Identify

`encid` can identify and decode common CTF and forensic layers:

- Hex/base16, binary, decimal charcodes, octal charcodes
- Base64/base64url, base32, base45, base58, base62, base36, base85/ascii85, base91, base92
- URL percent encoding, HTML entities, Unicode/JS escapes, quoted-printable
- gzip, zlib, raw deflate, bzip2, xz/lzma
- UTF-16LE/UTF-16BE
- Morse, Baconian, ROT13, ROT47, ROT5/ROT18, Caesar, Atbash
- Affine, rail fence, simple columnar transposition
- Brainfuck and Ook
- UUEncode, XXEncode, yEnc
- Braille byte patterns, emoji binary, whitespace binary, zero-width Unicode binary
- JWT header/payload decode

JSFuck, AAEncode, and JJEncode are identified, but encid does not execute JavaScript.

## Password Verification And Decryption

`encid decrypt` handles two separate operations:

- Password hashes are verified, not decrypted.
- Ciphertexts are decrypted only when the type and required parameters are known.

Examples:

```bash
encid decrypt --ask-password '$2b$10$...'
encid decrypt --type sha256 --ask-password 2bb80d...
encid decrypt --type xor --password key 0d070a...
encid decrypt --type aes-256-cbc --ask-password --iv-hex 00112233445566778899aabbccddeeff "..."
encid decrypt --type openssl-aes-256-cbc --ask-password "U2FsdGVkX1..."
encid decrypt --list-types
```

Prefer `--ask-password` over `--password` for real secrets. Command-line arguments may be recorded by shell history or visible to local process-inspection tools.

Supported verification/decrypt types include:

- Hash verification: bcrypt, Django PBKDF2, LDAP SHA/SSHA, MD5, SHA-1, SHA-2, SHA-3, BLAKE2b
- Decryption: XOR, OpenSSL AES-256-CBC, AES CBC/ECB/CTR/GCM, ChaCha20-Poly1305, Fernet

For AES/ChaCha/Fernet, the password/key alone may not be enough. Many formats also require an IV or nonce, salt, authentication tag, KDF, mode, and padding details.

## Confidence Model

Each decode attempt starts with structural evidence from the decoder, then scoring adjusts the result using:

- alphabet checks and round-trip validation
- printable/text ratio and UTF-8 validity
- entropy
- known flag/secret-like patterns
- score improvement over the previous layer
- risk penalties for broad or brute-force transforms
- identifier evidence from decoded output

The result is still probabilistic. Treat confidence as a triage aid, not proof.

## Output Types

- `encoded`: encid found and applied one or more decode layers.
- `hash`: encid recognized a structured password-hash format.
- `encryption`: encid recognized a structured encryption format.
- `encryption-candidate`: entropy and structure suggest ciphertext-like data, but not enough to prove exact encryption.
- `ambiguous`: raw material matches multiple possible meanings, such as digest-width hex.
- `identifier`: token, key, certificate, file, archive, capture, or similar structured material.
- `plain/unknown`: no strong signal was found.

## Security Model

- All analysis runs locally.
- Encid does not send input, keys, passwords, or results to a network service.
- Password/key input in the TUI is masked.
- `--ask-password` uses a no-echo prompt.
- Risky decoders are opt-in because they can produce plausible false positives.
- Weak legacy algorithms and modes are supported only to analyze existing data; their presence is not an endorsement for new systems.

## Project Layout

```text
encid/
  encid.py          CLI, recursive engine, result builder
  tui.py            stdlib curses TUI renderer and prompt loop
  crypto.py         password hash verification and supported decrypt operations
  decoders/         decoding transforms and decoder registry
  identifiers/      hash, token, crypto, file, and encoding identifiers
  scoring/          entropy, text scoring, confidence ranking
  models.py         shared dataclasses
assets/
  logo.svg
tests/
```

`main.py` is kept as a compatibility wrapper for `python main.py ...`.

## Development

```bash
uv sync
uv run python -m unittest discover -s tests -v
uv run python -m compileall encid tests
uv build
```

For a release build, prefer:

```bash
rm -rf dist/
uv lock
uv run python -m unittest discover -s tests -v
uv build --no-sources
```

## Distribution Notes

PyPI/uv:

- Build wheel and sdist with `uv build --no-sources`.
- Publish with `uv publish` and a PyPI API token.
- Users install with `uv tool install -U encid`.

Arch Linux / pacman:

- Use the `packaging/arch/PKGBUILD` template after the PyPI sdist is published.
- Build with `makepkg -si`.
- Runtime dependencies are Python, bcrypt, and cryptography.

## Current Limits

- Hashes are verified when a password is supplied; they are not cracked.
- Encryption cannot be decrypted without the correct type, key/password, and required parameters.
- Raw hex cannot prove its algorithm by length alone.
- Classical cipher detection is advisory unless a decode chain produces readable output.
- Morse code loses letter case; case-sensitive encodings may not be recoverable after Morse.
- Deep file forensics is future work: steganography, images, audio spectrograms, PCAP stream carving, PDFs, Office macros, nested archives, QR codes, and EXIF extraction.

## License

MIT. See [LICENSE](LICENSE).
