Metadata-Version: 2.4
Name: tesec
Version: 2.7.0
Summary: Beginner-friendly security utility library
Author: rihomies
Author-email: rihomies@gmail.com
License: MIT
Keywords: security,utilities,hashing,entropy,binary-analysis,masking,networking
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

Small, safe, beginner-friendly utilities for security tooling, scripts,
automation, reverse engineering, and general Python development.

`tesec` is a **defensive** utility library. It does pure computation —
hashing, parsing, statistics, formatting; and never executes the files it
analyzes, never touches the network, and never performs exploitation.

```python
import tesec

tesec.success("Starting")

token = tesec.random_token(32)
digest = tesec.sha256_file("sample.exe")

print(token)
print(digest)

data = open("sample.exe", "rb").read()

print(tesec.entropy(data))
```

Zero third-party dependencies: everything is built on the Python standard
library, plus one optional prebuilt native C accelerator.

## Installation

```bash
pip install tesec
```

That's it. `import tesec` and you are ready. No configuration required,
no compiler needed.

## Usage

### Console helpers

| Function | Output |
| --- | --- |
| `tesec.info(message)` | `[INFO] message` |
| `tesec.success(message)` | `[+] message` |
| `tesec.warning(message)` | `[!] message` |
| `tesec.error(message)` | `[-] message` |
| `tesec.set_color_enabled(enabled=None)` | Force colors on/off, or re-detect |

Colors are used only on ANSI-capable terminals; Windows 10+ consoles are
enabled automatically, `NO_COLOR` and `FORCE_COLOR` are respected, and the
output is routed through the standard `logging` machinery to stderr.

### Hashing

```python
tesec.md5(b"hello")          # 5d41402abc4b2a76b9719d911017c592
tesec.sha1(b"hello")         # aaf4c61ddcc5e8a2dabede0f3b482cd9aea9434d
tesec.sha256(b"hello")       # 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
tesec.sha384(b"hello")
tesec.sha512(b"hello")
tesec.hash_file("sample.exe")                 # SHA-256 by default
tesec.hash_file("sample.exe", algorithm="sha512")
tesec.sha256_file("sample.exe")               # convenience alias
```

All functions accept `bytes`, `bytearray`, or `memoryview`, and return
lowercase hex strings. Supported algorithms: `md5`, `sha1`, `sha256`,
`sha384`, `sha512`. Anything else raises `UnsupportedAlgorithmError`.

> `md5` and `sha1` are cryptographically broken — use them only for
> fingerprinting and legacy interoperability.

### Secure random

```python
tesec.random_bytes(32)   # b'...' 32 raw bytes
tesec.random_hex(16)     # 32 hex characters
tesec.random_token(32)   # 43 url-safe characters (e.g. API keys)
```

All functions are backed by the standard library `secrets` module, which
uses the operating system's cryptographic random source. They are suitable
for API keys and session tokens but are **not** password generators by
themselves.

### Network

```python
tesec.is_ipv4("8.8.8.8")                 # True
tesec.is_ipv6("2001:db8::1")             # True
tesec.is_private_ip("192.168.1.10")      # True
tesec.is_public_ip("8.8.8.8")            # True
tesec.in_network("192.168.1.50", "192.168.1.0/24")  # True
```

Pure parsers built on `ipaddress`; no network connections are ever made.
Note that some ranges (e.g. CGNAT `100.64.0.0/10`) are neither private nor
public, and that `127.0.0.1`/`::1` count as private. `in_network` raises
`InvalidInputError` for malformed input.

### Secret masking

```python
tesec.mask_secret("sk_live_123456789")          # *************6789
tesec.mask_secret("secret123456", visible=4)    # ********3456
tesec.mask_email("example@gmail.com")           # e*****e@gmail.com
```

Masking is for display and logging only, it is **not** encryption.

### Binary analysis

```python
tesec.entropy(b"\x00" * 1000)   # ~0.0  (bits per byte, 0.0-8.0)
tesec.byte_frequency(b"aaab")   # {0: 0, 1: 0, ..., 97: 3, 98: 1, ...}
tesec.analyze_bytes(data)
# {"size": 1024, "entropy": 7.21, "null_bytes": 12, "ascii_ratio": 0.31}
tesec.analyze_file("sample.exe")
# {"size": ..., "entropy": ..., "null_bytes": ..., "ascii_ratio": ..., "path": "sample.exe"}
```

Entropy is a statistical measure, not malware detection — see
[Security considerations](#security-considerations).

### Exceptions

```python
tesec.TesecError                   # base class
tesec.InvalidInputError            # bad type or value
tesec.UnsupportedAlgorithmError    # unsupported hash algorithm
```


### Comparing both native and python

```
tesec version : 1.0.0
native module    : available
input size       : 67108864 bytes (64.0 MiB)
repeats          : 3

function         python       native   speedup
-------------------------------------------------
entropy          4635.1 ms   215.0 ms     21.6x
byte_frequency   4674.9 ms    88.5 ms     52.8x
```

Numbers above were measured on a development machine (Windows 11, AMD
Ryzen); your results will differ. Run the benchmark yourself to see your
own numbers.

### When it matters

The native implementation helps most for **large buffers** (multi-megabyte
binaries, memory dumps, packet captures). For small inputs — a few hundred
bytes — the Python fallback is perfectly fine and the overhead of the C call
can dominate, so the speedup is negligible. Use `entropy()` on whatever size
you have; the dispatch is automatic.

## Supported Python versions and platforms

- CPython 3.8, 3.9, 3.10, 3.11, 3.12, and 3.13, on Windows, Linux, and macOS.
- The native binary targets the CPython **limited API** (abi3), so a single
  prebuilt binary per platform works on every CPython 3.8+.
- Any platform where no prebuilt binary is available still works through the
  pure-Python fallback.

## License

MIT — see [LICENSE](LICENSE)
