Metadata-Version: 2.4
Name: secgen
Version: 0.3.1
Summary: A brief tool to analyse and generate entropic passwords and keys.
Author-email: Cristopher Méndez Cervantes <cristophermendezcervantes@gmail.com>
Project-URL: Homepage, https://github.com/cristopherpydev/secgen
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# secgen

A comprehensive, secure, and highly configurable Python library for credential generation and entropy analysis.

This package provides developers with the tools to generate deterministic passwords, cryptographically secure tokens, numeric PINs, and mnemonic passwords. Additionally, it features an advanced analysis module to evaluate password strength through entropy calculations and brute-force crack time estimations.

## Features

* **Password Generation:** Create highly secure passwords with customizable length and character sets (uppercase, numbers, symbols).
* **Bulk Generation:** Generate large batches of secure passwords efficiently.
* **Token & PIN Creation:** Generate cryptographically secure hexadecimal tokens and numeric PINs.
* **Mnemonic Passwords:** Generate memorable yet secure passwords using customizable data streams.
* **Entropy Analysis:** Calculate the cryptographic strength of a password based on character pool and length.
* **Crack Time Estimation:** Estimate the time required to brute-force a password using modern hardware capabilities.

## Installation

You can install the package directly via pip:

```bash
pip install secgen
```

## Usage

### 1. Credential Generation (`generator.py`)

The generator module provides multiple functions to create different types of security credentials.

#### Standard Password Generation
Generate a single password with specific constraints.

```python
from secgen.generator import generate_password

# Generate a 24-character password with uppercase letters, numbers, and symbols
secure_pwd = generate_password(length=24, uppercase_letters=True, numbers=True, symbols=True)
print(secure_pwd)
# Output example: 'A$5xpu!23lzQ34?#u4v8K9@z'
```

#### Bulk Password Generation
Generate a list of passwords, ideal for administrative purposes or initial database seeding.

```python
from secgen.generator import generate_bulk_pwd

# Generate 5 passwords, each 12 characters long
bulk_pwds = generate_bulk_pwd(num=5, length=12, uppercase_letters=True, numbers=True, symbols=False)
print(bulk_pwds)
# Output example: ['aB3dEfg8Hijk', 'L1mnOpq2RstU', ...]
```

#### PIN and Token Generation
Generate purely numeric PINs and secure hexadecimal tokens.

```python
from secgen.generator import generate_pin, generate_token

# Generate a 6-digit PIN
user_pin = generate_pin(length=6)
print(user_pin) 
# Output example: '492018'

# Generate a 32-byte secure hexadecimal token
session_token = generate_token(bytes=32)
print(session_token) 
```

#### Mnemonic Password Generation
Generate symbolic passwords based on memorability levels. 

*Important requirement: This function requires a `data` directory containing a `mnemotechnic_stream.json` file relative to the generator module's location.*

```python
from secgen.generator import generate_symbolic_mnemopwd

# Generate a standard mnemonic password with medium complexity
mnemo_pwd = generate_symbolic_mnemopwd(lvl="medium", composition="standard")
print(mnemo_pwd)
```

### 2. Password Analysis (`analysis.py`)

The analysis module evaluates password strength by calculating entropy bits and estimating brute-force vulnerability.

#### Analyze a Single Password

```python
from secgen.analysis import analyze_one

result = analyze_one('A$5xpu!23lzQ34?#u4', crack_time=True)

print(result['crack_time']) 
# Output example: 'Millenia (Imposible with the actual technology)'

print(result['feedback']) 
# Output example: '\033[92mExcellent\033[0m' (Terminal colored output)
```
*Note: The `feedback` string includes ANSI color codes (Red, Yellow, Blue, Green) to render colored text directly in standard terminal environments.*

#### Analyze Multiple Passwords (Bulk)

```python
from secgen.analysis import analyze_many

passwords_to_check = ['A$5xpu!23lzQ34?#u4', 'FroDobolSon', 'a']
bulk_results = analyze_many(passwords_to_check)

for idx, data in enumerate(bulk_results):
    print(f"Password {idx + 1}:")
    print(f" - Strength: {data['feedback']}")
    print(f" - Crack Time: {data['crack_time']}\n")
```

## Dependencies

This library is built exclusively using Python's standard library modules (`random`, `os`, `json`, `secrets`, `math`) to ensure zero external dependencies and maximum security compatibility. 

## License

This project is licensed under the GNU General Public License v3.0. You are free to redistribute it and/or modify it under the terms of the Free Software Foundation. See the LICENSE file provided with the source code for more details.
