blackhole-sec 0.1.0__tar.gz

blackhole_sec-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Satin Networks
+
+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.

blackhole_sec-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+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.

blackhole_sec-0.1.0/README.md

@@ -0,0 +1,137 @@
+# 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.

blackhole_sec-0.1.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "blackhole-sec"
+version = "0.1.0"
+description = "Offline phishing checks, encrypted vault, metadata shredder and secure .bhb archives."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+authors = [{ name = "Satin Networks" }]
+keywords = ["security", "opsec", "phishing", "vault", "shredder", "privacy", "offline"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Topic :: Security",
+  "Topic :: Security :: Cryptography",
+]
+dependencies = [
+  "click>=8.1",
+  "rich>=13.0",
+  "cryptography>=42.0",
+  "argon2-cffi>=23.0",
+  "Pillow>=10.0",
+  "pyyaml>=6.0",
+  "pydantic>=2.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0", "ruff>=0.4", "build", "twine"]
+
+[project.scripts]
+blackhole = "blackhole_sec.cli:main"
+blackhole-sec = "blackhole_sec.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/satin-networks/blackhole-sec"
+Repository = "https://github.com/satin-networks/blackhole-sec"
+Issues = "https://github.com/satin-networks/blackhole-sec/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+ignore = ["BLE001", "S110", "S101", "PLR2004", "EM101", "EM102", "TRY003"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

blackhole_sec-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

blackhole_sec-0.1.0/src/blackhole_sec/__init__.py

@@ -0,0 +1,3 @@
+"""Blackhole-sec: offline personal opsec toolkit."""
+__version__ = "0.1.0"
+__all__ = ["__version__"]

blackhole_sec-0.1.0/src/blackhole_sec/bundle/__init__.py

@@ -0,0 +1,154 @@
+"""Secure directory archives (.bhb).
+
+Plain zip has two problems I kept running into: weak passwords crack fast,
+and filenames sit in the clear even with AES. .bhb packs a directory to
+tar.gz, then encrypts the whole thing with Argon2id -> AES-256-GCM.
+Only blackhole can open it, which is the point.
+
+Layout v1, big-endian:
+  BHB1 | kdf_id | t,m,p | salt | nonce | ct_len | ct
+  ct holds the tar.gz. The header is used as AAD.
+
+Two modes: password, or no password (writes a .key file you need to keep).
+"""
+from __future__ import annotations
+
+import io
+import os
+import struct
+import tarfile
+from pathlib import Path
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from ..vault.crypto import DEFAULT_M, DEFAULT_P, DEFAULT_T, b64d, b64e, derive_key, generate_salt
+
+MAGIC = b"BHB1"
+VERSION_KDF_ARGON = 1
+VERSION_KDF_NONE = 0
+HEADER_FMT = ">4sBIIIH"  # magic, kdf_id, t, m, p, salt_len
+NONCE_LEN = 12
+
+
+def _build_tar(src_dir: Path) -> bytes:
+    buf = io.BytesIO()
+    with tarfile.open(fileobj=buf, mode="w:gz") as tf:
+        for root, _, files in os.walk(src_dir):
+            for fn in sorted(files):
+                full = Path(root) / fn
+                arc = full.relative_to(src_dir).as_posix()
+                # ZipSlip-class defense at build time
+                if arc.startswith("/") or ".." in Path(arc).parts:
+                    raise ValueError(f"unsafe path: {arc}")
+                ti = tf.gettarinfo(str(full), arcname=arc)
+                ti.uid = ti.gid = 0
+                ti.uname = ti.gname = ""
+                ti.mtime = int(ti.mtime)
+                with open(full, "rb") as f:
+                    tf.addfile(ti, f)
+    return buf.getvalue()
+
+
+def _safe_extract(tar_bytes: bytes, dest: Path) -> list[str]:
+    dest.mkdir(parents=True, exist_ok=True)
+    out: list[str] = []
+    buf = io.BytesIO(tar_bytes)
+    with tarfile.open(fileobj=buf, mode="r:gz") as tf:
+        for m in tf.getmembers():
+            # Reject everything but regular files/dirs (no symlinks, fifos, devices)
+            if not (m.isfile() or m.isdir()):
+                continue
+            p = Path(m.name)
+            if m.name.startswith("/") or ".." in p.parts or m.name.startswith("~"):
+                continue
+            target = dest / p
+            if m.isdir():
+                target.mkdir(parents=True, exist_ok=True)
+            else:
+                target.parent.mkdir(parents=True, exist_ok=True)
+                f = tf.extractfile(m)
+                if f is None:
+                    continue
+                target.write_bytes(f.read())
+                try:
+                    os.chmod(target, m.mode & 0o777)
+                except Exception:
+                    pass
+                out.append(m.name)
+    return out
+
+
+def create_bundle(src_dir: str | Path, out: str | Path, password: str | None,
+                  t: int = DEFAULT_T, m: int = DEFAULT_M, p: int = DEFAULT_P) -> dict:
+    src = Path(src_dir)
+    dst = Path(out)
+    if not src.is_dir():
+        raise ValueError("src must be a directory")
+    tar_bytes = _build_tar(src)
+    if password:
+        salt = generate_salt()
+        key = derive_key(password, salt, t, m, p)
+        kdf_id = VERSION_KDF_ARGON
+        keyfile = None
+    else:
+        salt = generate_salt(8)  # header salt marker only
+        key = os.urandom(32)
+        kdf_id = VERSION_KDF_NONE
+        keyfile = str(dst) + ".key"
+        Path(keyfile).write_text(b64e(key))
+        os.chmod(keyfile, 0o600)
+    nonce = os.urandom(NONCE_LEN)
+    header = struct.pack(HEADER_FMT, MAGIC, kdf_id, t, m, p, len(salt)) + salt + nonce
+    aad = header  # authenticate everything before ct
+    ct = AESGCM(key).encrypt(nonce, tar_bytes, aad)
+    # wipe key material best-effort
+    try:
+        for i in range(len(key)):
+            key[i] = 0  # type: ignore
+    except Exception:
+        pass
+    with open(dst, "wb") as f:
+        f.write(header + struct.pack(">Q", len(ct)) + ct)
+    os.chmod(dst, 0o600)
+    return {"bundle": str(dst), "keyfile": keyfile, "bytes_in": len(tar_bytes),
+            "bytes_out": dst.stat().st_size, "kdf": "argon2id" if password else "keyfile"}
+
+
+def extract_bundle(bundle: str | Path, dest: str | Path, password: str | None = None,
+                   keyfile: str | Path | None = None) -> list[str]:
+    data = Path(bundle).read_bytes()
+    hlen = struct.calcsize(HEADER_FMT)
+    magic, kdf_id, t, m, p, slen = struct.unpack(HEADER_FMT, data[:hlen])
+    if magic != MAGIC:
+        raise ValueError("not a .bhb bundle (bad magic)")
+    off = hlen
+    salt = data[off:off + slen]
+    off += slen
+    nonce = data[off:off + NONCE_LEN]
+    off += NONCE_LEN
+    (ct_len,) = struct.unpack(">Q", data[off:off + 8])
+    off += 8
+    ct = data[off:off + ct_len]
+    if len(ct) != ct_len:
+        raise ValueError("truncated bundle")
+    header = data[:off - 8]  # up to nonce inclusive == AAD
+    if kdf_id == VERSION_KDF_ARGON:
+        if not password:
+            raise ValueError("bundle needs a password (--password)")
+        key = derive_key(password, salt, t, m, p)
+    elif kdf_id == VERSION_KDF_NONE:
+        kf = keyfile or (str(bundle) + ".key")
+        key = b64d(Path(kf).read_text().strip())
+    else:
+        raise ValueError(f"unsupported kdf_id {kdf_id}")
+    try:
+        tar_bytes = AESGCM(key).decrypt(nonce, ct, header)
+    except Exception as e:
+        raise ValueError("decryption failed: wrong password/keyfile or tampered bundle") from e
+    finally:
+        try:
+            for i in range(len(key)):
+                key[i] = 0  # type: ignore
+        except Exception:
+            pass
+    return _safe_extract(tar_bytes, Path(dest))

blackhole_sec-0.1.0/src/blackhole_sec/check/__init__.py

@@ -0,0 +1,6 @@
+"""Check subpackage: offline phishing URL analysis."""
+from .features import FeatureResult, analyze_url
+from .report import defang, format_text, to_dict
+from .scorer import score_features, verdict_for_score
+
+__all__ = ["FeatureResult", "analyze_url", "defang", "format_text", "score_features", "to_dict", "verdict_for_score"]