hashident 0.1.0__tar.gz

hashident-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Javier Mendoza
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hashident-0.1.0/PKG-INFO

@@ -0,0 +1,422 @@
+Metadata-Version: 2.4
+Name: hashident
+Version: 0.1.0
+Summary: Identify likely hash algorithms from a hash string.
+Author: Javier Mendoza
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jmendoza167/hash_identifier
+Project-URL: Issues, https://github.com/jmendoza167/hash_identifier/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Information Technology
+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: Programming Language :: Python :: 3.14
+Classifier: Topic :: Security
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Dynamic: license-file
+
+# hashident
+
+[![CI](https://github.com/jmendoza167/hash_identifier/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jmendoza167/hash_identifier/actions/workflows/ci.yml)
+
+hashident is a command-line tool that tells you which algorithm most likely
+produced a hash string. It ranks every matching format with a confidence
+level and the reasons behind it, says how hard the hash is to crack, and
+prints ready-to-run Hashcat and John the Ripper commands. It is built for CTF
+players, students working through security coursework, and auditors who find
+password hashes and need to know what they are looking at. It runs on Python
+3.10+ with no third-party dependencies.
+
+## Why hashident
+
+Many hash identifiers print a flat list of every format with the right length
+and leave the rest to you. hashident tries to answer the next questions too:
+
+- **Ranked, with reasons.** Candidates are ordered best first and labelled
+  HIGH, MEDIUM or LOW confidence, with the reasons for each: the shape that
+  matched, why one format outranks another, and what else the input could be.
+- **Ready-to-run commands.** Each likely format comes with its Hashcat mode,
+  John format and the exact commands to start a wordlist attack, plus notes
+  where a tool needs the hash in a slightly different form.
+- **Strength ratings.** Every format is rated WEAK, MODERATE or STRONG, with
+  a one-line explanation (fast and unsalted, or salted and deliberately slow).
+- **Context hints.** Tell it where the hash came from (`--from windows`,
+  `linux`, `web` or `db`) and the ranking adapts: 32 hex characters from a
+  Windows box are more likely NTLM than MD5. When a hint would change the
+  answer, hashident suggests it.
+- **Built for scripts too.** Batches of hashes from files or pipes, a compact
+  table for many values, meaningful exit codes, and `--json` output with a
+  versioned schema.
+
+## Example
+
+One hash gets a full report:
+
+```sh
+hashident 8743b52063cd84097a65d1633f5c74f5
+```
+
+<!-- readme-test: output 8743b52063cd84097a65d1633f5c74f5 -->
+```text
+Input:   8743b52063cd84097a65d1633f5c74f5
+Length:  32 characters
+
+#  Format  Confidence  Hashcat  John
+-  ------  ----------  -------  -------
+1  MD5     MEDIUM      0        raw-md5
+2  NTLM    LOW         1000     nt
+
+1. MD5 - medium confidence
+   Reasons:
+     - 32 hexadecimal characters
+     - most common format with this shape
+     - also matches NTLM: same length and charset
+   Strength: WEAK - Fast and unsalted: GPUs test billions of guesses per second.
+   Crack it (save the hash to hash.txt first):
+     hashcat -m 0 -a 0 hash.txt wordlist.txt
+     john --format=raw-md5 --wordlist=wordlist.txt hash.txt
+
+Low-confidence candidates are shown in the table only.
+
+Tip: hash from a Windows system? Re-run with --from windows (NTLM ranks first)
+```
+
+Several hashes get a compact table, one row per value. Given a file
+`hashes.txt`:
+
+<!-- readme-test: file hashes.txt -->
+```text
+# hashes from the lab box
+8743b52063cd84097a65d1633f5c74f5
+b89eaac7e61417341b710b727768294d0e6a277b
+$2a$05$LhayLxezLhK1LhWvKxCyLOj0j1u.Kj0jZ0pEmm134uzrQlFvQJLF6
+*FCF7C1B8749CF99D88E5F34271D636178FB5D130
+$1$ehAsHC4t$4IbK3fHS/H1YGtNYBrIEB1
+not-a-hash
+```
+
+```sh
+hashident -f hashes.txt
+```
+
+<!-- readme-test: output -f hashes.txt -->
+```text
+Line    Value                                       Format       Conf    Hashcat
+------  ------------------------------------------  -----------  ------  -------
+2       8743b52063cd84097a65d1633f5c74f5            MD5          MEDIUM  0
+3       b89eaac7e61417341b710b727768294d0e6a277b    SHA-1        MEDIUM  100
+4       $2a$05$LhayLxezLhK1L...pEmm134uzrQlFvQJLF6  bcrypt       HIGH    3200
+5       *FCF7C1B8749CF99D88E5F34271D636178FB5D130   MySQL 4.1+   HIGH    300
+6       $1$ehAsHC4t$4IbK3fHS/H1YGtNYBrIEB1          md5crypt     HIGH    500
+7       not-a-hash                                  no match     -       -
+
+6 values: 1 MD5, 1 SHA-1, 1 bcrypt, 1 MySQL 4.1+, 1 md5crypt, 1 no match
+Tip: --from windows would change the top format for 1 of 6 values.
+Run hashident on a single value to see its full report and crack commands.
+```
+
+The first column is the line number in the file, so you can find each value
+again. Long values are shortened in the middle to keep every line within 80
+columns. In a terminal, confidence levels and strength ratings are colored.
+
+## Installation
+
+hashident needs Python 3.10 or newer.
+
+### From PyPI
+
+hashident is on [PyPI](https://pypi.org/project/hashident/). The easiest way
+to install a command-line tool is [pipx](https://pipx.pypa.io), which gives it
+its own environment and puts the `hashident` command on your PATH:
+
+```sh
+pipx install hashident
+hashident --version
+```
+
+Upgrade later with `pipx upgrade hashident`. To install with pip instead, use
+a virtual environment and run `python -m pip install hashident`.
+
+### From source
+
+To work on hashident itself, or to run the tests:
+
+```sh
+git clone https://github.com/jmendoza167/hash_identifier.git
+cd hash_identifier
+python -m venv .venv
+```
+
+Activate the virtual environment:
+
+| Shell | Command |
+| --- | --- |
+| PowerShell (Windows) | `.\.venv\Scripts\Activate.ps1` |
+| Git Bash (Windows) | `source .venv/Scripts/activate` |
+| bash or zsh (Linux, macOS) | `source .venv/bin/activate` |
+
+Then install hashident into it and check that it runs:
+
+```sh
+python -m pip install -e .
+hashident --version
+```
+
+If PowerShell refuses to run `Activate.ps1`, allow scripts for the current
+session only with `Set-ExecutionPolicy -Scope Process RemoteSigned`, then
+activate again.
+
+To run the tests, install the development extra and run pytest:
+
+```sh
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+## Usage
+
+```text
+usage: hashident [-h] [--version] [--from {windows,linux,web,db}]
+                 [--color {auto,always,never} | --no-color] [-f PATH] [-v]
+                 [--json]
+                 [hash ...]
+```
+
+Run `hashident --help` for the full reference.
+
+### Identify a hash
+
+```sh
+hashident 8743b52063cd84097a65d1633f5c74f5
+```
+
+### Quoting hashes with `$` or `*`
+
+Wrap hashes that contain `$` (bcrypt, md5crypt, sha512crypt) or start with `*`
+(MySQL) in **single quotes**. Otherwise the shell changes them before
+hashident sees them: bash and PowerShell both treat `$2a` as a variable, and
+bash expands `*` as a filename pattern. Double quotes are not enough, because
+both shells still expand `$` inside them.
+
+The same command works in PowerShell and bash:
+
+```sh
+hashident '$2a$05$LhayLxezLhK1LhWvKxCyLOj0j1u.Kj0jZ0pEmm134uzrQlFvQJLF6'
+hashident '*FCF7C1B8749CF99D88E5F34271D636178FB5D130'
+```
+
+In Windows `cmd.exe`, leave the quotes off: cmd does not expand `$`, and it
+would pass the single quotes on as part of the hash.
+
+Hashes read from a file or a pipe are never touched by the shell, so they need
+no quoting.
+
+### Several hashes: arguments, files and stdin
+
+Pass several hashes as arguments, read them from a file with `-f`, or pipe
+them in:
+
+```sh
+hashident 8743b52063cd84097a65d1633f5c74f5 b89eaac7e61417341b710b727768294d0e6a277b
+hashident -f hashes.txt
+```
+
+```sh
+# bash
+cat hashes.txt | hashident
+hashident < hashes.txt
+```
+
+```powershell
+# PowerShell
+Get-Content hashes.txt | hashident
+```
+
+- Arguments come first, in order, then the lines of `-f PATH`. `-f -` reads
+  standard input. With neither, hashident reads standard input when it is
+  piped or redirected, and shows help otherwise.
+- In files and piped input, blank lines and lines starting with `#` are
+  skipped, and surrounding whitespace is stripped.
+- Files can be UTF-8 or UTF-16 with a byte order mark, so files written by
+  `>` in Windows PowerShell 5.1 work as they are.
+- A missing or unreadable file, or input with no hashes in it, is an error
+  (exit code 2).
+
+### Context hints: `--from`
+
+If you know where the hash came from, say so. Formats common in that
+environment are ranked higher:
+
+```sh
+hashident --from windows 8743b52063cd84097a65d1633f5c74f5
+```
+
+Now NTLM ranks above MD5. The values are `windows`, `linux`, `web` and `db`.
+A hint changes which plausible format comes first; it never makes an
+ambiguous match certain, so both stay MEDIUM confidence. Without `--from`,
+hashident suggests a value when one would change the top result.
+
+### Verbose: `-v`
+
+```sh
+hashident -v 8743b52063cd84097a65d1633f5c74f5
+hashident -v -f hashes.txt
+```
+
+With one hash, `-v` also shows the details and commands of LOW-confidence
+candidates, which are normally listed in the table only. With several, it
+prints a full report for each value instead of the compact table, each under
+a rule such as `== line 3 ====`.
+
+### Color: `--color`, `--no-color` and `NO_COLOR`
+
+Output is colored only when it goes to a terminal. Piped or redirected output
+is plain.
+
+| Option | Effect |
+| --- | --- |
+| `--color auto` | Default: color in a terminal, unless `NO_COLOR` is set |
+| `--color always` | Color even when piped, e.g. into `less -R` |
+| `--color never`, `--no-color` | No color |
+
+Setting the [`NO_COLOR`](https://no-color.org) environment variable to any
+non-empty value turns color off in `auto` mode. The flags take precedence over
+`NO_COLOR`:
+
+```sh
+# bash
+NO_COLOR=1 hashident 8743b52063cd84097a65d1633f5c74f5
+```
+
+```powershell
+# PowerShell
+$env:NO_COLOR = '1'
+hashident 8743b52063cd84097a65d1633f5c74f5
+```
+
+### JSON: `--json`
+
+`--json` prints one JSON object per hash, each on its own line
+([JSON Lines](https://jsonlines.org)), so large inputs stream and other tools
+can process them line by line. It is never colored, and `-v` has no effect on
+it: JSON always includes everything.
+
+Pretty-print the output with Python:
+
+```sh
+hashident --json 8743b52063cd84097a65d1633f5c74f5 | python -m json.tool
+hashident --json -f hashes.txt | python -m json.tool --json-lines
+```
+
+Print each value's line number and best format:
+
+```sh
+hashident --json -f hashes.txt | python -c "import sys, json; [print(r['position'], r['candidates'][0]['format'] if r['matched'] else 'no match') for r in map(json.loads, sys.stdin)]"
+```
+
+Or use [jq](https://jqlang.org) to list the values that matched nothing:
+
+```sh
+hashident --json -f hashes.txt | jq -r 'select(.matched | not) | .input'
+```
+
+In Windows PowerShell 5.1, if piping into Python fails with
+`Unexpected UTF-8 BOM`, your console is set to UTF-8 *with* a byte order mark,
+which PowerShell adds to everything it pipes into a program. Switch to UTF-8
+without one for the session:
+
+```powershell
+$OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+```
+
+The schema is described under JSON output below.
+
+## Supported formats
+
+| Format | Hashcat mode | John format | Strength |
+| --- | --- | --- | --- |
+| MD5 | 0 | `raw-md5` | Weak |
+| NTLM | 1000 | `nt` | Weak |
+| SHA-1 | 100 | `raw-sha1` | Weak |
+| SHA-224 | 1300 | `raw-sha224` | Moderate |
+| SHA-256 | 1400 | `raw-sha256` | Moderate |
+| SHA-512 | 1700 | `raw-sha512` | Moderate |
+| MySQL 4.1+ | 300 | `mysql-sha1` | Weak |
+| md5crypt | 500 | `md5crypt` | Weak |
+| sha512crypt | 1800 | `sha512crypt` | Strong |
+| bcrypt | 3200 | `bcrypt` | Strong |
+
+Several formats share a shape: 32 hex characters fit both MD5 and NTLM, and
+40 fit both SHA-1 and a MySQL 4.1+ hash without its leading `*`. That is why
+hashident ranks candidates instead of naming one.
+
+For MySQL 4.1+, Hashcat mode 300 expects the 40 hex characters without the
+`*`, while John's `mysql-sha1` format needs it. hashident prints a note saying
+which form each tool wants.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Every hash matched a known format |
+| 1 | No hash matched |
+| 2 | Invalid arguments, or input that cannot be read or contains no hashes |
+| 3 | Some hashes matched and some did not |
+
+The codes are the same with `--json` and `-v`.
+
+## JSON output
+
+Each line of `--json` output is one object for one input value:
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `schema_version` | int | Schema version, currently `1` |
+| `input` | string | The value as received |
+| `source` | string | `"argument"`, `"<stdin>"` or the path given to `-f` |
+| `position` | int | Argument index or line number, starting at 1 |
+| `context` | string or null | The `--from` value, or null |
+| `matched` | bool | Whether any known format matched |
+| `candidates` | list | Matching formats, best first; empty if none |
+| `tips` | list | `--from` values that would change the top format |
+
+Each candidate has `rank`, `format`, `score`, `confidence`, `hashcat_mode`,
+`john_format`, `strength`, `strength_note`, `reasons`, `commands` and `notes`.
+Each tip has `context` and `top_format`. Absent values, such as a format John
+does not support, are `null`. Keys are snake_case, and the output is pure
+ASCII: other characters are written as `\uXXXX` escapes.
+
+**Versioning:** new keys may be added within `schema_version` 1, so ignore
+keys you don't recognize. Renaming or removing a key, or changing its type,
+increases `schema_version`.
+
+## Responsible use
+
+hashident only identifies hashes. It has no cracking built in: the commands
+it prints are suggestions for Hashcat or John the Ripper, which you run
+yourself. Only analyze hashes you are authorized to work with, such as CTF
+challenges, your own systems, coursework material, or systems covered by a
+written agreement for a security assessment.
+
+## Credits
+
+The example hashes used in the tests and in this README come from the
+[Hashcat example hashes](https://hashcat.net/wiki/doku.php?id=example_hashes)
+list. The plaintext for all of them is `hashcat`. The MySQL 4.1+ example is
+Hashcat's mode 300 hash written in MySQL's own `*` format.
+
+## License
+
+MIT. See [LICENSE](https://github.com/jmendoza167/hash_identifier/blob/main/LICENSE).