Metadata-Version: 2.4
Name: blackhole-sec
Version: 0.1.0
Summary: Offline phishing checks, encrypted vault, metadata shredder and secure .bhb archives.
Author: Satin Networks
License: MIT
Project-URL: Homepage, https://github.com/satin-networks/blackhole-sec
Project-URL: Repository, https://github.com/satin-networks/blackhole-sec
Project-URL: Issues, https://github.com/satin-networks/blackhole-sec/issues
Keywords: security,opsec,phishing,vault,shredder,privacy,offline
Classifier: Development Status :: 4 - Beta
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.11
Classifier: Topic :: Security
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.1
Requires-Dist: rich>=13.0
Requires-Dist: cryptography>=42.0
Requires-Dist: argon2-cffi>=23.0
Requires-Dist: Pillow>=10.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: pydantic>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Dynamic: license-file

# blackhole-sec

A small offline toolkit I actually use: check sketchy links, keep passwords
in an encrypted vault, strip photo metadata before posting, and pack
directories into encrypted `.bhb` files instead of zip.

No accounts. No network calls. Nothing leaves your machine.

Full write-ups for each tool live here:
**https://satin-networks.github.io/blackhole-sec/**

```bash
pip install blackhole-sec
```

```bash
blackhole check "http://secure-paypal-login.tk/free-nitro"
blackhole vault init
blackhole shred analyze photo.jpg
blackhole bundle create ./mydir ./backup.bhb
```

## The four tools

### 1. check - is this link a trap?

Paste a Discord / email lure and get a straight answer. Everything runs
locally, the URL is never fetched.

```bash
blackhole check "http://secure.paypal.com.evil.tk/login?redirect=http://evil.com"
# MALICIOUS 68/100 (HIGH) hxxp[:]//secure[.]paypal[.]com[.]evil[.]tk/login...
#   +18 brand_impersonation: brand=paypal host=secure.paypal.com.evil.tk
#   +10 suspicious_tld: .tk
#   ...

blackhole check -f urls.txt --json > report.json
echo "http://paypal-secure.tk/login" | blackhole check --file -
```

Scoring is plain and explainable: each signal adds points, 0-20 is BENIGN,
21-49 SUSPICIOUS, 50+ MALICIOUS. Output is defanged (`hxxp[://]`) so you
can't click it by accident. Batch mode and `--threshold` fit nicely in scripts.

### 2. vault - passwords on your own disk

One encrypted file, one master password. Argon2id turns your master into a
key, AES-256-GCM does the rest. I never store the master anywhere.

```bash
blackhole vault init --vault ~/.blackhole/vault.db
blackhole vault set github --username alice --generate 24
blackhole vault get github --show
blackhole vault list
blackhole vault audit
blackhole vault gen --length 24
```

The file is chmod 0600. Every command locks when it finishes. `audit`
calls out reused, short, and stale passwords with a 0-100 score.

Lose the master and the vault is gone - there is no reset, by design.

### 3. shred - clean it before you post it

Photos carry GPS, camera model, and timestamps. `analyze` shows what's in
there, `clean` writes a `*.cleaned` copy with it stripped (your original
stays untouched), `verify` passes or fails for scripts, and `shred`
overwrites and deletes for real.

```bash
blackhole shred analyze photo.jpg
blackhole shred clean photo.jpg
blackhole shred verify photo.cleaned.jpg; echo $?
blackhole shred shred secret.txt --passes 7 --yes
```

### 4. bundle - encrypted archives that aren't zip

I got tired of zip passwords cracking in minutes and filenames leaking even
with AES. `.bhb` packs a directory to tar.gz and encrypts the whole blob.
Filenames, sizes, everything is hidden. Only blackhole opens it.

```bash
blackhole bundle create ./photos ./photos.bhb
blackhole bundle create ./photos ./photos.bhb --no-password  # writes photos.bhb.key
blackhole bundle extract ./photos.bhb ./restored --password
```

Wrong password or a tampered file just refuses to open. Extraction rejects
absolute paths, `..`, and symlinks.

```bash
blackhole intake "http://evil.tk/login" ./photo.jpg  # link + file in one go
```

## Install

Python 3.11 or newer.

```bash
pip install blackhole-sec
pip install -e ".[dev]"  # hacking on it
```

Depends on click, rich, cryptography, argon2-cffi, Pillow, pyyaml and
pydantic. That's it.

## Layout

```
src/blackhole_sec/
  check/    link scoring, no network
  vault/    encrypted store + generator
  shred/    metadata + secure delete
  bundle/   .bhb create / extract
  cli.py    everything wired together
tests/      offline fixtures, no network
docs/       longer write-ups for each tool
```

## Security notes

Short version is in `SECURITY.md`. The honest version:

- Standard primitives only (Argon2id, AES-GCM, `secrets`). Nothing home-rolled.
- `check` never touches the network. Input capped at 2048 chars.
- Secrets live in 0600 files. Keys are wiped best-effort after use.
- Not audited. Don't bet your life on any single tool, including this one.

Found something? Open a private advisory with version, OS, and steps.
Please don't post vault files or bundles anywhere public.

## License

MIT - see LICENSE. Built by Satin Networks alongside
[wisp](https://github.com/satin-networks/wisp), our local WireGuard manager.
