Metadata-Version: 2.4
Name: passcheck-cli
Version: 1.0.0
Summary: Password security CLI: breach checking (HIBP k-anonymity), secure generation, and ML-powered strength scoring.
Author: NameRectified
License: MIT
Project-URL: Homepage, https://github.com/NameRectified/passcheck
Project-URL: Repository, https://github.com/NameRectified/passcheck
Keywords: password,security,hibp,breach,strength,generator
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests
Requires-Dist: pyperclip
Requires-Dist: scikit-learn
Requires-Dist: joblib
Dynamic: license-file

# PassCheck

A cross-platform CLI tool for password security: breach checking via the HIBP API, secure password generation, and ML-powered strength scoring with specific suggestions.

### Flow Diagram
```mermaid
flowchart TD
    CLI["CLI (passcheck.py)"]
    CH["checker.py<br/>HIBP breach check"]
    SC["scorer.py<br/>ML + fallback"]
    GEN["generator.py"]
    ML["ML pipeline<br/>(training/*)"]

    CLI --> CH
    CLI --> SC
    CLI --> GEN
    SC --> ML
```
## Quick Install

```bash
pip install passcheck-cli
```

Then run `passcheck` anywhere.

For development, clone the repo and install in editable mode:

```bash
git clone https://github.com/NameRectified/passcheck.git
cd passcheck
pip install -e .
```

## Usage

### Interactive mode

```bash
passcheck
```

Shows a menu where you can pick **Check** or **Generate** without remembering flags.

### Check a password

```bash
passcheck check
Password: ********

Breach Status: Found in 2,266,543 data breaches
Strength:       25/100 (weak)

Suggestions:
  • This password appears in 2,266,543 data breach(es) — never reuse it
  • Add at least one uppercase letter
  • Add at least one special character
  • Avoid sequential characters like '123' or 'abc'
  • Use a mix of upper/lowercase, digits, and special characters

Suggested replacement: :_Y8$4Ur/v-&6FuN (copied to clipboard)
```

You can also pass the password directly:
```bash
passcheck check yourpassword
```
Omitting the argument prompts hidden-ly with `getpass`.

### Generate a password

```bash
passcheck generate -l 16

Generated:      G_j2*8TUP8?7
Strength:       65/100 (strong)
Copied to clipboard.
```

- `-l`, `--length`: Password length (default: 16)

## Features

- **Breach checking**: Uses the [Have I Been Pwned](https://haveibeenpwned.com/API/v3#PwnedPasswords) API with k-anonymity — never sends the full hash over the network.
- **Password generation**: Uses `secrets` module. Excludes ambiguous characters (`0`, `O`, `1`, `l`, `I`, `|`). Guarantees at least one uppercase, one lowercase, three digits, and one special character.
- **ML strength scoring**: RandomForest model trained on 3500 passwords. Scores 0–100 with specific suggestions for improvement.
- **Specific suggestions**: Suggestions derived from the actual password — not generic templates.

## Requirements

- Python 3.10+
- `requests`, `pyperclip`, `scikit-learn`, `joblib`

## Project Structure

```
passcheck/
├── src/passcheck/
│   ├── __init__.py    Package metadata
│   ├── cli.py         CLI entry point
│   ├── checker.py     Breach checking (HIBP API)
│   ├── generator.py   Password generation
│   ├── scorer.py      ML strength analysis + suggestions
│   ├── features.py    ML feature extraction
│   ├── config.py      Configuration constants
│   └── models/        Trained model (.pkl, shipped in the wheel)
├── training/          ML pipeline (features, dataset, training)
├── tests/             pytest test suite (32 tests)
├── requirements.txt
└── pyproject.toml
```

## Running Tests

```bash
pytest tests/
```

## License

MIT
