cyberplain 0.1.0__tar.gz

cyberplain-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/

cyberplain-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 William J. Laurento II
+
+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.
+

cyberplain-0.1.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: cyberplain
+Version: 0.1.0
+Summary: Plain-English defensive cybersecurity tools for Python and the command line
+Project-URL: Homepage, https://github.com/fortnitecodedrop-cmyk/new
+Project-URL: Repository, https://github.com/fortnitecodedrop-cmyk/new
+Project-URL: Issues, https://github.com/fortnitecodedrop-cmyk/new/issues
+Author: William J. Laurento II
+License: MIT
+License-File: LICENSE
+Keywords: cybersecurity,defensive-security,dns,pcap,port-scanner,security,tls
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: packets
+Requires-Dist: dpkt>=1.9.8; extra == 'packets'
+Description-Content-Type: text/markdown
+
+# CyberPlain
+
+CyberPlain is a defensive cybersecurity toolkit for Python and the command line. It uses normal English in its names, output, errors, and documentation so beginners can understand what a check did and experienced practitioners can automate it.
+
+> Use active network checks only on systems you own or have explicit written permission to test. CyberPlain is designed for defense, education, inventory, and authorized assessment—not exploitation, evasion, credential theft, or disruption.
+
+## What is included
+
+| Area | Command / API | What it does |
+|---|---|---|
+| Ports | `cyberplain ports` / `scan_ports()` | Bounded TCP connect scan with service names |
+| Packets | `cyberplain pcap` / `summarize_pcap()` | Offline PCAP/PCAPNG traffic inventory |
+| TLS | `cyberplain tls` / `inspect_tls()` | Certificate, cipher, version, and expiry explanation |
+| Web | `cyberplain headers` / `audit_headers()` | Reviews common HTTP security headers |
+| DNS | `cyberplain dns` | Forward and reverse address lookups |
+| Files | `cyberplain file` | SHA-256, size, and entropy clues |
+| Integrity | `cyberplain hash`, `manifest` | Hashing and directory change detection |
+| Passwords | `cyberplain password` | Local strength feedback; never sends the password |
+| Indicators | `cyberplain iocs`, `defang` | Extracts and safely formats URLs, domains, IPs, emails, and hashes |
+
+## Install
+
+```bash
+pip install cyberplain
+```
+
+For offline packet-capture analysis:
+
+```bash
+pip install "cyberplain[packets]"
+```
+
+## Quick examples
+
+```bash
+# You must explicitly confirm authorization for active port checks.
+cyberplain ports 192.168.1.10 --ports 22,80,443,8000-8010 --authorized
+
+cyberplain tls example.com
+cyberplain headers https://example.com
+cyberplain dns example.com
+cyberplain file download.zip
+cyberplain hash installer.exe
+cyberplain password
+cyberplain pcap capture.pcap
+cyberplain iocs suspicious-email.txt
+cyberplain defang https://example.com/path
+cyberplain manifest ./important-files --create baseline.json
+cyberplain manifest ./important-files --verify baseline.json
+```
+
+Python API:
+
+```python
+from cyberplain import assess_password, hash_file, scan_ports
+
+print(hash_file("download.zip"))
+print(assess_password("a long example passphrase"))
+
+result = scan_ports(
+    "192.168.1.10",
+    "22,80,443",
+    authorized=True,  # only after you confirm permission
+)
+print(result["results"])
+```
+
+## Design promises
+
+- Safe defaults and bounded concurrency.
+- No telemetry; checks run locally unless the feature obviously contacts the host you name.
+- Structured dictionaries/JSON for automation.
+- Plain-English context instead of unexplained security jargon.
+- Honest wording: a missing header or high-entropy file is a clue, not automatic proof of a vulnerability or malware.
+
+## Development and PyPI publishing
+
+### One-command publishing
+
+From PowerShell inside the extracted project folder:
+
+```powershell
+py publish.py
+```
+
+The script installs the official build/upload tools, deletes only the old local
+`dist` directory, builds fresh packages, validates them, asks for a final typed
+confirmation, and uploads to PyPI. Twine then prompts for the username
+`__token__` and your complete `pypi-...` API token. The token is never stored by
+this project.
+
+To test the complete workflow against TestPyPI first:
+
+```powershell
+py publish.py --test
+```
+
+### Manual publishing
+
+```bash
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[dev,packets]"
+pytest
+ruff check .
+python -m build
+twine check dist/*
+
+# Test upload first
+python -m twine upload --repository testpypi dist/*
+
+# Final upload (requires your PyPI API token)
+python -m twine upload dist/*
+```
+
+Before publishing, replace the placeholder GitHub URLs in `pyproject.toml`, confirm that the distribution name is available on PyPI, and choose your author/maintainer metadata.
+
+## Scope and roadmap
+
+No responsible package can literally cover every cybersecurity topic in one safe, maintainable release. CyberPlain 0.1 focuses on a strong defensive foundation. Good future additions include SARIF output, YARA rule scanning, OSV dependency checks, richer packet protocol summaries, certificate transparency lookup, and optional integrations with reputable threat-intelligence services.

cyberplain-0.1.0/README.md

@@ -0,0 +1,120 @@
+# CyberPlain
+
+CyberPlain is a defensive cybersecurity toolkit for Python and the command line. It uses normal English in its names, output, errors, and documentation so beginners can understand what a check did and experienced practitioners can automate it.
+
+> Use active network checks only on systems you own or have explicit written permission to test. CyberPlain is designed for defense, education, inventory, and authorized assessment—not exploitation, evasion, credential theft, or disruption.
+
+## What is included
+
+| Area | Command / API | What it does |
+|---|---|---|
+| Ports | `cyberplain ports` / `scan_ports()` | Bounded TCP connect scan with service names |
+| Packets | `cyberplain pcap` / `summarize_pcap()` | Offline PCAP/PCAPNG traffic inventory |
+| TLS | `cyberplain tls` / `inspect_tls()` | Certificate, cipher, version, and expiry explanation |
+| Web | `cyberplain headers` / `audit_headers()` | Reviews common HTTP security headers |
+| DNS | `cyberplain dns` | Forward and reverse address lookups |
+| Files | `cyberplain file` | SHA-256, size, and entropy clues |
+| Integrity | `cyberplain hash`, `manifest` | Hashing and directory change detection |
+| Passwords | `cyberplain password` | Local strength feedback; never sends the password |
+| Indicators | `cyberplain iocs`, `defang` | Extracts and safely formats URLs, domains, IPs, emails, and hashes |
+
+## Install
+
+```bash
+pip install cyberplain
+```
+
+For offline packet-capture analysis:
+
+```bash
+pip install "cyberplain[packets]"
+```
+
+## Quick examples
+
+```bash
+# You must explicitly confirm authorization for active port checks.
+cyberplain ports 192.168.1.10 --ports 22,80,443,8000-8010 --authorized
+
+cyberplain tls example.com
+cyberplain headers https://example.com
+cyberplain dns example.com
+cyberplain file download.zip
+cyberplain hash installer.exe
+cyberplain password
+cyberplain pcap capture.pcap
+cyberplain iocs suspicious-email.txt
+cyberplain defang https://example.com/path
+cyberplain manifest ./important-files --create baseline.json
+cyberplain manifest ./important-files --verify baseline.json
+```
+
+Python API:
+
+```python
+from cyberplain import assess_password, hash_file, scan_ports
+
+print(hash_file("download.zip"))
+print(assess_password("a long example passphrase"))
+
+result = scan_ports(
+    "192.168.1.10",
+    "22,80,443",
+    authorized=True,  # only after you confirm permission
+)
+print(result["results"])
+```
+
+## Design promises
+
+- Safe defaults and bounded concurrency.
+- No telemetry; checks run locally unless the feature obviously contacts the host you name.
+- Structured dictionaries/JSON for automation.
+- Plain-English context instead of unexplained security jargon.
+- Honest wording: a missing header or high-entropy file is a clue, not automatic proof of a vulnerability or malware.
+
+## Development and PyPI publishing
+
+### One-command publishing
+
+From PowerShell inside the extracted project folder:
+
+```powershell
+py publish.py
+```
+
+The script installs the official build/upload tools, deletes only the old local
+`dist` directory, builds fresh packages, validates them, asks for a final typed
+confirmation, and uploads to PyPI. Twine then prompts for the username
+`__token__` and your complete `pypi-...` API token. The token is never stored by
+this project.
+
+To test the complete workflow against TestPyPI first:
+
+```powershell
+py publish.py --test
+```
+
+### Manual publishing
+
+```bash
+python -m venv .venv
+source .venv/bin/activate          # Windows: .venv\Scripts\activate
+pip install -e ".[dev,packets]"
+pytest
+ruff check .
+python -m build
+twine check dist/*
+
+# Test upload first
+python -m twine upload --repository testpypi dist/*
+
+# Final upload (requires your PyPI API token)
+python -m twine upload dist/*
+```
+
+Before publishing, replace the placeholder GitHub URLs in `pyproject.toml`, confirm that the distribution name is available on PyPI, and choose your author/maintainer metadata.
+
+## Scope and roadmap
+
+No responsible package can literally cover every cybersecurity topic in one safe, maintainable release. CyberPlain 0.1 focuses on a strong defensive foundation. Good future additions include SARIF output, YARA rule scanning, OSV dependency checks, richer packet protocol summaries, certificate transparency lookup, and optional integrations with reputable threat-intelligence services.

cyberplain-0.1.0/publish.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Build and publish CyberPlain to PyPI or TestPyPI."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import getpass
+
+ROOT = Path(__file__).resolve().parent
+DIST = ROOT / "dist"
+
+
+def run(command: list[str], *, cwd: Path | None = None) -> None:
+    subprocess.run(command, cwd=cwd or ROOT, check=True)
+
+
+def install_tools() -> None:
+    run([sys.executable, "-m", "pip", "install", "--upgrade", "pip", "build", "twine"])
+
+
+def clean_dist() -> None:
+    if DIST.exists():
+        shutil.rmtree(DIST)
+
+
+def build_package() -> None:
+    run([sys.executable, "-m", "build"])
+    run([sys.executable, "-m", "twine", "check", "dist/*"])
+
+
+def confirm_publish(test_mode: bool, skip_confirm: bool) -> None:
+    if skip_confirm:
+        return
+    target = "TestPyPI" if test_mode else "PyPI"
+    response = input(f"Type 'PUBLISH' to upload to {target} and press Enter: ")
+    if response != "PUBLISH":
+        raise SystemExit("Publishing cancelled.")
+
+
+def resolve_token(test_mode: bool, token: str | None) -> str:
+    if token:
+        return token
+
+    env_name = "TESTPYPI_TOKEN" if test_mode else "PYPI_TOKEN"
+    env_token = os.environ.get(env_name)
+    if env_token:
+        return env_token
+
+    return getpass.getpass(f"Enter your {('TestPyPI' if test_mode else 'PyPI')} API token: ")
+
+
+def upload_package(test_mode: bool, token: str | None, *, dry_run: bool) -> None:
+    repo = "testpypi" if test_mode else "pypi"
+    resolved = resolve_token(test_mode, token)
+
+    if dry_run:
+        print(f"Dry run: python -m twine upload --repository {repo} --username __token__ --password <token> dist/*")
+        return
+
+    run([
+        sys.executable,
+        "-m",
+        "twine",
+        "upload",
+        f"--repository={repo}",
+        "--username",
+        "__token__",
+        "--password",
+        resolved,
+        "dist/*",
+    ])
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Build and publish the CyberPlain package.")
+    parser.add_argument(
+        "--test",
+        action="store_true",
+        help="Upload to TestPyPI instead of the main PyPI index.",
+    )
+    parser.add_argument(
+        "--token",
+        help="Pass your PyPI/TestPyPI API token directly without an interactive prompt.",
+    )
+    parser.add_argument(
+        "--skip-confirm",
+        action="store_true",
+        help="Skip the interactive confirmation prompt.",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Build and validate the package without uploading it.",
+    )
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_args()
+    print("Installing packaging tools...")
+    install_tools()
+    print("Cleaning old build artifacts...")
+    clean_dist()
+    print("Building distribution artifacts...")
+    build_package()
+    print("Build and metadata checks passed.")
+    confirm_publish(args.test, args.skip_confirm)
+    print("Uploading package...")
+    upload_package(args.test, args.token, dry_run=args.dry_run)
+    if not args.dry_run:
+        print("Upload completed.")
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except subprocess.CalledProcessError as exc:
+        raise SystemExit(f"Command failed with exit code {exc.returncode}.") from exc

cyberplain-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cyberplain"
+version = "0.1.0"
+description = "Plain-English defensive cybersecurity tools for Python and the command line"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [{name = "William J. Laurento II"}]
+keywords = ["cybersecurity", "security", "port-scanner", "pcap", "tls", "dns", "defensive-security"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Security",
+]
+dependencies = []
+
+[project.optional-dependencies]
+packets = ["dpkt>=1.9.8"]
+dev = ["build>=1.2", "pytest>=8", "ruff>=0.6", "twine>=5"]
+
+[project.scripts]
+cyberplain = "cyberplain.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/fortnitecodedrop-cmyk/new"
+Repository = "https://github.com/fortnitecodedrop-cmyk/new"
+Issues = "https://github.com/fortnitecodedrop-cmyk/new/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cyberplain"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+

cyberplain-0.1.0/src/cyberplain/__init__.py

@@ -0,0 +1,8 @@
+"""CyberPlain: defensive cybersecurity in readable Python."""
+
+from .hashing import hash_file, verify_file
+from .passwords import assess_password
+from .ports import scan_ports
+
+__all__ = ["assess_password", "hash_file", "scan_ports", "verify_file"]
+__version__ = "0.1.0"

cyberplain-0.1.0/src/cyberplain/__init__.py.bak

@@ -0,0 +1,8 @@
+"""CyberPlain: defensive cybersecurity in readable Python."""
+
+from .hashing import hash_file, verify_file
+from .passwords import assess_password
+from .ports import scan_ports
+
+__all__ = ["assess_password", "hash_file", "scan_ports", "verify_file"]
+__version__ = "0.1.0"

cyberplain-0.1.0/src/cyberplain/cli.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import argparse
+import getpass
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from .dnscheck import resolve_host, reverse_lookup
+from .files import inspect_file
+from .hashing import create_manifest, hash_file, verify_file, verify_manifest
+from .httpcheck import audit_headers
+from .iocs import defang, extract_iocs, refang
+from .passwords import assess_password
+from .pcap import summarize_pcap
+from .ports import scan_ports
+from .tlscheck import inspect_tls
+
+
+def _emit(data: Any) -> None:
+    print(json.dumps(data, indent=2, default=str))
+
+
+def _authorized(args: argparse.Namespace) -> bool:
+    if not args.authorized:
+        raise ValueError("Add --authorized to confirm that you have permission to test this host.")
+    return True
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cyberplain", description="Defensive cybersecurity tools that explain their results."
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    ports = sub.add_parser("ports", help="Check which TCP ports accept connections")
+    ports.add_argument("host")
+    ports.add_argument("--ports", default="22,80,443")
+    ports.add_argument("--timeout", type=float, default=0.5)
+    ports.add_argument("--show-closed", action="store_true")
+    ports.add_argument(
+        "--authorized",
+        action="store_true",
+        help="I own or have explicit permission to test this host",
+    )
+
+    tls = sub.add_parser("tls", help="Explain a site's TLS certificate")
+    tls.add_argument("host")
+    tls.add_argument("--port", type=int, default=443)
+
+    headers = sub.add_parser("headers", help="Review common HTTP security headers")
+    headers.add_argument("url")
+
+    dns = sub.add_parser("dns", help="Resolve a hostname or reverse-resolve an IP address")
+    dns.add_argument("value")
+    dns.add_argument("--reverse", action="store_true")
+
+    hashing = sub.add_parser("hash", help="Calculate a safe file fingerprint")
+    hashing.add_argument("path")
+    hashing.add_argument("--algorithm", default="sha256")
+    hashing.add_argument("--expected")
+
+    file_parser = sub.add_parser("file", help="Inspect file metadata, hash, and entropy")
+    file_parser.add_argument("path")
+
+    password = sub.add_parser("password", help="Assess a password locally without transmitting it")
+    password.add_argument(
+        "--value", help="Avoid this option on shared systems because shell history may retain it"
+    )
+
+    ioc = sub.add_parser("iocs", help="Extract indicators from a text file or stdin")
+    ioc.add_argument("path", nargs="?", help="Omit to read stdin")
+    transform = sub.add_parser("defang", help="Make a URL or domain safer to paste")
+    transform.add_argument("value")
+    transform.add_argument("--reverse", action="store_true")
+
+    pcap = sub.add_parser("pcap", help="Summarize an offline PCAP/PCAPNG file")
+    pcap.add_argument("path")
+    pcap.add_argument("--limit", type=int, default=100_000)
+
+    manifest = sub.add_parser("manifest", help="Create or verify a directory integrity manifest")
+    manifest.add_argument("directory")
+    manifest.add_argument("--create")
+    manifest.add_argument("--verify")
+    return parser
+
+
+def run(args: argparse.Namespace) -> Any:
+    if args.command == "ports":
+        return scan_ports(
+            args.host,
+            args.ports,
+            authorized=_authorized(args),
+            timeout=args.timeout,
+            include_closed=args.show_closed,
+        )
+    if args.command == "tls":
+        return inspect_tls(args.host, args.port)
+    if args.command == "headers":
+        return audit_headers(args.url)
+    if args.command == "dns":
+        return reverse_lookup(args.value) if args.reverse else resolve_host(args.value)
+    if args.command == "hash":
+        return (
+            {"path": args.path, "matches": verify_file(args.path, args.expected, args.algorithm)}
+            if args.expected
+            else {
+                "path": args.path,
+                "algorithm": args.algorithm,
+                "digest": hash_file(args.path, args.algorithm),
+            }
+        )
+    if args.command == "file":
+        return inspect_file(args.path)
+    if args.command == "password":
+        return assess_password(
+            args.value
+            if args.value is not None
+            else getpass.getpass("Password (input stays local): ")
+        )
+    if args.command == "iocs":
+        text = (
+            Path(args.path).read_text(encoding="utf-8", errors="replace")
+            if args.path
+            else sys.stdin.read()
+        )
+        return extract_iocs(text)
+    if args.command == "defang":
+        return {"result": refang(args.value) if args.reverse else defang(args.value)}
+    if args.command == "pcap":
+        return summarize_pcap(args.path, args.limit)
+    if args.command == "manifest":
+        if bool(args.create) == bool(args.verify):
+            raise ValueError("Choose exactly one of --create FILE or --verify FILE.")
+        return (
+            create_manifest(args.directory, args.create)
+            if args.create
+            else verify_manifest(args.directory, args.verify)
+        )
+    raise ValueError("Unknown command")
+
+
+def main() -> None:
+    try:
+        _emit(run(build_parser().parse_args()))
+    except (ValueError, OSError, RuntimeError, PermissionError) as error:
+        print(f"CyberPlain could not complete the check: {error}", file=sys.stderr)
+        raise SystemExit(2) from error
+
+
+if __name__ == "__main__":
+    main()

cyberplain-0.1.0/src/cyberplain/dnscheck.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import ipaddress
+import socket
+
+
+def resolve_host(host: str) -> dict[str, object]:
+    records = socket.getaddrinfo(host, None, proto=socket.IPPROTO_TCP)
+    addresses = sorted({record[4][0] for record in records})
+    explained = []
+    for value in addresses:
+        address = ipaddress.ip_address(value)
+        explained.append(
+            {
+                "address": value,
+                "version": address.version,
+                "scope": "public" if address.is_global else "private or special-use",
+            }
+        )
+    return {"host": host, "addresses": explained}
+
+
+def reverse_lookup(address: str) -> dict[str, object]:
+    ipaddress.ip_address(address)
+    try:
+        hostname, aliases, addresses = socket.gethostbyaddr(address)
+        return {
+            "address": address,
+            "hostname": hostname,
+            "aliases": aliases,
+            "addresses": addresses,
+        }
+    except socket.herror:
+        return {"address": address, "hostname": None, "aliases": [], "addresses": []}

cyberplain-0.1.0/src/cyberplain/files.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import math
+from collections import Counter
+from pathlib import Path
+
+from .hashing import hash_file
+
+
+def shannon_entropy(data: bytes) -> float:
+    if not data:
+        return 0.0
+    counts = Counter(data)
+    return -sum((count / len(data)) * math.log2(count / len(data)) for count in counts.values())
+
+
+def inspect_file(path: str | Path, sample_bytes: int = 2_000_000) -> dict[str, object]:
+    target = Path(path)
+    with target.open("rb") as handle:
+        sample = handle.read(sample_bytes)
+    entropy = shannon_entropy(sample)
+    return {
+        "path": str(target),
+        "size_bytes": target.stat().st_size,
+        "sha256": hash_file(target),
+        "sample_entropy": round(entropy, 3),
+        "entropy_explanation": (
+            "High entropy can be normal for compressed or encrypted files; it is only a clue."
+            if entropy > 7.2
+            else "The sampled bytes do not have unusually high entropy."
+        ),
+    }

cyberplain-0.1.0/src/cyberplain/hashing.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import hashlib
+import hmac
+import json
+from pathlib import Path
+
+ALGORITHMS = {"sha256", "sha384", "sha512", "blake2b"}
+
+
+def hash_file(path: str | Path, algorithm: str = "sha256", chunk_size: int = 1024 * 1024) -> str:
+    if algorithm not in ALGORITHMS:
+        raise ValueError(f"Choose one of: {', '.join(sorted(ALGORITHMS))}")
+    digest = hashlib.new(algorithm)
+    with Path(path).open("rb") as handle:
+        for chunk in iter(lambda: handle.read(chunk_size), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def verify_file(path: str | Path, expected: str, algorithm: str = "sha256") -> bool:
+    return hmac.compare_digest(hash_file(path, algorithm), expected.strip().lower())
+
+
+def create_manifest(directory: str | Path, output: str | Path | None = None) -> dict[str, str]:
+    root = Path(directory).resolve()
+    manifest = {
+        str(path.relative_to(root)): hash_file(path)
+        for path in sorted(root.rglob("*"))
+        if path.is_file() and (output is None or path.resolve() != Path(output).resolve())
+    }
+    if output:
+        Path(output).write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+    return manifest
+
+
+def verify_manifest(
+    directory: str | Path, manifest: str | Path | dict[str, str]
+) -> dict[str, list[str]]:
+    root = Path(directory).resolve()
+    expected = (
+        json.loads(Path(manifest).read_text(encoding="utf-8"))
+        if not isinstance(manifest, dict)
+        else manifest
+    )
+    actual_paths = {str(path.relative_to(root)): path for path in root.rglob("*") if path.is_file()}
+    missing = sorted(set(expected) - set(actual_paths))
+    added = sorted(set(actual_paths) - set(expected))
+    changed = sorted(
+        name
+        for name in set(expected) & set(actual_paths)
+        if not verify_file(actual_paths[name], expected[name])
+    )
+    return {"changed": changed, "missing": missing, "added": added}

cyberplain-0.1.0/src/cyberplain/httpcheck.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import urllib.error
+import urllib.request
+from urllib.parse import urlparse
+
+IMPORTANT_HEADERS = {
+    "strict-transport-security": "Tells browsers to keep using HTTPS.",
+    "content-security-policy": "Limits where scripts, styles, and other content may load from.",
+    "x-content-type-options": "Stops browsers from guessing a file's content type.",
+    "referrer-policy": "Controls how much referral information leaves the site.",
+    "permissions-policy": "Limits browser features such as camera and location access.",
+}
+
+
+def audit_headers(url: str, timeout: float = 8.0) -> dict[str, object]:
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname:
+        raise ValueError("Use a complete http:// or https:// URL.")
+    request = urllib.request.Request(
+        url, method="GET", headers={"User-Agent": "CyberPlain/0.1 defensive-audit"}
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=timeout) as response:
+            headers = {key.lower(): value for key, value in response.headers.items()}
+            status = response.status
+            final_url = response.url
+    except urllib.error.HTTPError as error:
+        headers = {key.lower(): value for key, value in error.headers.items()}
+        status = error.code
+        final_url = error.url
+    present = {
+        name: {"value": headers[name], "purpose": purpose}
+        for name, purpose in IMPORTANT_HEADERS.items()
+        if name in headers
+    }
+    missing = {name: purpose for name, purpose in IMPORTANT_HEADERS.items() if name not in headers}
+    notes = []
+    if parsed.scheme != "https":
+        notes.append("The starting URL does not use HTTPS.")
+    if "server" in headers:
+        notes.append(
+            "The Server header may reveal implementation details; minimize it when practical."
+        )
+    return {
+        "url": url,
+        "final_url": final_url,
+        "status": status,
+        "present_security_headers": present,
+        "missing_security_headers": missing,
+        "notes": notes,
+        "warning": "Missing headers are review items, not automatic proof of a vulnerability.",
+    }

cyberplain-0.1.0/src/cyberplain/iocs.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import ipaddress
+import re
+from urllib.parse import urlparse
+
+URL_RE = re.compile(r"https?://[^\s<>\"']+", re.IGNORECASE)
+EMAIL_RE = re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.IGNORECASE)
+IP_RE = re.compile(r"(?<![\w.])(?:\d{1,3}\.){3}\d{1,3}(?![\w.])")
+HASH_RE = re.compile(r"\b(?:[a-fA-F0-9]{32}|[a-fA-F0-9]{40}|[a-fA-F0-9]{64})\b")
+
+
+def extract_iocs(text: str) -> dict[str, list[str]]:
+    ips = []
+    for candidate in IP_RE.findall(text):
+        try:
+            ips.append(str(ipaddress.ip_address(candidate)))
+        except ValueError:
+            pass
+    urls = [item.rstrip(".,);]") for item in URL_RE.findall(text)]
+    domains = []
+    for url in urls:
+        host = urlparse(url).hostname
+        if host:
+            domains.append(host.casefold())
+    return {
+        "urls": sorted(set(urls)),
+        "domains": sorted(set(domains)),
+        "ip_addresses": sorted(set(ips)),
+        "email_addresses": sorted(set(EMAIL_RE.findall(text))),
+        "hashes": sorted({value.lower() for value in HASH_RE.findall(text)}),
+    }
+
+
+def defang(value: str) -> str:
+    return value.replace("https://", "hxxps://").replace("http://", "hxxp://").replace(".", "[.]")
+
+
+def refang(value: str) -> str:
+    return value.replace("hxxps://", "https://").replace("hxxp://", "http://").replace("[.]", ".")

cyberplain-0.1.0/src/cyberplain/models.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class Finding:
+    title: str
+    severity: str
+    explanation: str
+    recommendation: str = ""
+    evidence: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(slots=True)
+class CheckResult:
+    subject: str
+    summary: str
+    findings: list[Finding] = field(default_factory=list)
+    details: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "subject": self.subject,
+            "summary": self.summary,
+            "findings": [item.to_dict() for item in self.findings],
+            "details": self.details,
+        }

cyberplain-0.1.0/src/cyberplain/passwords.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import math
+import re
+
+COMMON = {
+    "password",
+    "password1",
+    "123456",
+    "12345678",
+    "qwerty",
+    "letmein",
+    "admin",
+    "welcome",
+    "iloveyou",
+}
+
+
+def assess_password(password: str) -> dict[str, object]:
+    pools = [
+        (r"[a-z]", 26, "lowercase letter"),
+        (r"[A-Z]", 26, "uppercase letter"),
+        (r"[0-9]", 10, "number"),
+        (r"[^A-Za-z0-9]", 33, "symbol"),
+    ]
+    pool_size = sum(size for pattern, size, _ in pools if re.search(pattern, password))
+    entropy = len(password) * math.log2(pool_size) if pool_size else 0.0
+    warnings: list[str] = []
+    lower = password.casefold()
+    if len(password) < 14:
+        warnings.append(
+            "Use at least 14 characters; length usually helps more than forced substitutions."
+        )
+    if lower in COMMON:
+        warnings.append("This is an extremely common password.")
+    if re.search(r"(.)\1{2,}", password):
+        warnings.append("Avoid repeating the same character three or more times.")
+    if any(sequence in lower for sequence in ("1234", "abcd", "qwerty", "asdf")):
+        warnings.append("Avoid predictable keyboard or counting sequences.")
+    score = 0 if lower in COMMON else min(4, int(entropy // 22))
+    labels = ["very weak", "weak", "fair", "strong", "very strong"]
+    return {
+        "score": score,
+        "rating": labels[score],
+        "length": len(password),
+        "estimated_entropy_bits": round(entropy, 1),
+        "warnings": warnings,
+        "advice": "Prefer a password manager and a unique generated password or long passphrase.",
+        "note": "Entropy is only an estimate and does not prove resistance to real password cracking.",
+    }

cyberplain-0.1.0/src/cyberplain/pcap.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import socket
+from collections import Counter
+from pathlib import Path
+
+
+def summarize_pcap(path: str | Path, packet_limit: int = 100_000) -> dict[str, object]:
+    """Summarize a PCAP file without replaying or modifying any traffic."""
+    try:
+        import dpkt
+    except ImportError as error:
+        raise RuntimeError("Packet analysis needs: pip install 'cyberplain[packets]'") from error
+    protocols: Counter[str] = Counter()
+    endpoints: Counter[str] = Counter()
+    conversations: Counter[str] = Counter()
+    total_bytes = 0
+    first_time = last_time = None
+    count = 0
+    with Path(path).open("rb") as handle:
+        try:
+            reader = dpkt.pcap.Reader(handle)
+        except (ValueError, dpkt.dpkt.NeedData):
+            handle.seek(0)
+            reader = dpkt.pcapng.Reader(handle)
+        for timestamp, buffer in reader:
+            count += 1
+            if count > packet_limit:
+                break
+            first_time = timestamp if first_time is None else first_time
+            last_time = timestamp
+            total_bytes += len(buffer)
+            try:
+                ethernet = dpkt.ethernet.Ethernet(buffer)
+                ip = ethernet.data
+                if isinstance(ip, dpkt.ip.IP):
+                    source, destination = socket.inet_ntoa(ip.src), socket.inet_ntoa(ip.dst)
+                elif isinstance(ip, dpkt.ip6.IP6):
+                    source, destination = (
+                        socket.inet_ntop(socket.AF_INET6, ip.src),
+                        socket.inet_ntop(socket.AF_INET6, ip.dst),
+                    )
+                else:
+                    protocols[type(ip).__name__.upper()] += 1
+                    continue
+                protocol = {6: "TCP", 17: "UDP", 1: "ICMP", 58: "ICMPv6"}.get(
+                    ip.p, f"IP protocol {ip.p}"
+                )
+                protocols[protocol] += 1
+                endpoints.update((source, destination))
+                conversations[f"{source} -> {destination}"] += 1
+            except (dpkt.dpkt.NeedData, dpkt.dpkt.UnpackError, ValueError):
+                protocols["Malformed or unsupported"] += 1
+    return {
+        "file": str(path),
+        "packets_read": min(count, packet_limit),
+        "truncated": count > packet_limit,
+        "bytes_observed": total_bytes,
+        "duration_seconds": round(last_time - first_time, 3)
+        if first_time is not None and last_time is not None
+        else 0,
+        "protocols": dict(protocols.most_common()),
+        "top_endpoints": dict(endpoints.most_common(20)),
+        "top_conversations": dict(conversations.most_common(20)),
+        "plain_english": "This is a traffic inventory, not a verdict that any endpoint is malicious.",
+    }

cyberplain-0.1.0/src/cyberplain/ports.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import concurrent.futures
+import socket
+import time
+from collections.abc import Iterable
+from dataclasses import asdict, dataclass
+
+from .safety import public_ip_warning, require_authorization
+
+COMMON_PORTS = {
+    20: "FTP data",
+    21: "FTP",
+    22: "SSH",
+    23: "Telnet",
+    25: "SMTP",
+    53: "DNS",
+    67: "DHCP server",
+    68: "DHCP client",
+    80: "HTTP",
+    110: "POP3",
+    123: "NTP",
+    135: "Microsoft RPC",
+    139: "NetBIOS",
+    143: "IMAP",
+    161: "SNMP",
+    389: "LDAP",
+    443: "HTTPS",
+    445: "SMB",
+    465: "SMTPS",
+    587: "SMTP submission",
+    636: "LDAPS",
+    993: "IMAPS",
+    995: "POP3S",
+    1433: "Microsoft SQL Server",
+    1521: "Oracle DB",
+    2049: "NFS",
+    2375: "Docker API (unencrypted)",
+    3306: "MySQL",
+    3389: "Remote Desktop",
+    5432: "PostgreSQL",
+    5900: "VNC",
+    6379: "Redis",
+    8080: "Alternate HTTP",
+    8443: "Alternate HTTPS",
+    9200: "Elasticsearch",
+    27017: "MongoDB",
+}
+
+
+@dataclass(slots=True)
+class PortResult:
+    port: int
+    state: str
+    service: str
+    response_ms: float | None
+
+    def to_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+def parse_ports(spec: str) -> list[int]:
+    """Parse ``22,80,443,8000-8010`` into a sorted list of ports."""
+    ports: set[int] = set()
+    for raw_part in spec.split(","):
+        part = raw_part.strip()
+        if not part:
+            continue
+        if "-" in part:
+            start_text, end_text = part.split("-", 1)
+            start, end = int(start_text), int(end_text)
+            if end < start:
+                raise ValueError(f"Invalid port range: {part}")
+            ports.update(range(start, end + 1))
+        else:
+            ports.add(int(part))
+    if not ports or any(port < 1 or port > 65535 for port in ports):
+        raise ValueError("Ports must be between 1 and 65535.")
+    if len(ports) > 1024:
+        raise ValueError("A single scan is limited to 1,024 ports.")
+    return sorted(ports)
+
+
+def _check_port(address: str, port: int, timeout: float) -> PortResult:
+    started = time.perf_counter()
+    try:
+        with socket.create_connection((address, port), timeout=timeout):
+            elapsed = round((time.perf_counter() - started) * 1000, 2)
+            return PortResult(port, "open", COMMON_PORTS.get(port, "Unknown"), elapsed)
+    except (TimeoutError, ConnectionRefusedError, OSError):
+        return PortResult(port, "closed or filtered", COMMON_PORTS.get(port, "Unknown"), None)
+
+
+def scan_ports(
+    host: str,
+    ports: Iterable[int] | str = (22, 80, 443),
+    *,
+    authorized: bool = False,
+    timeout: float = 0.5,
+    workers: int = 64,
+    include_closed: bool = False,
+) -> dict[str, object]:
+    """Run a bounded TCP connect scan against an authorized host."""
+    require_authorization(authorized)
+    port_list = parse_ports(ports) if isinstance(ports, str) else sorted(set(ports))
+    if not port_list or len(port_list) > 1024:
+        raise ValueError("Choose between 1 and 1,024 ports.")
+    if any(not isinstance(port, int) or port < 1 or port > 65535 for port in port_list):
+        raise ValueError("Ports must be integers between 1 and 65535.")
+    if not 0.05 <= timeout <= 10:
+        raise ValueError("Timeout must be between 0.05 and 10 seconds.")
+    workers = max(1, min(int(workers), 128))
+    address = socket.gethostbyname(host)
+    with concurrent.futures.ThreadPoolExecutor(max_workers=workers) as executor:
+        results = list(executor.map(lambda p: _check_port(address, p, timeout), port_list))
+    visible = results if include_closed else [item for item in results if item.state == "open"]
+    return {
+        "host": host,
+        "resolved_address": address,
+        "ports_checked": len(port_list),
+        "open_count": sum(item.state == "open" for item in results),
+        "warning": public_ip_warning(address),
+        "results": [item.to_dict() for item in visible],
+    }

cyberplain-0.1.0/src/cyberplain/reporting.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def to_json(data: Any, output: str | Path | None = None) -> str:
+    rendered = json.dumps(data, indent=2, default=str) + "\n"
+    if output:
+        Path(output).write_text(rendered, encoding="utf-8")
+    return rendered
+
+
+def to_markdown(data: dict[str, Any], title: str = "CyberPlain Report") -> str:
+    lines = [f"# {title}", ""]
+    for key, value in data.items():
+        heading = key.replace("_", " ").title()
+        if isinstance(value, (dict, list)):
+            lines.extend(
+                (
+                    f"## {heading}",
+                    "",
+                    "```json",
+                    json.dumps(value, indent=2, default=str),
+                    "```",
+                    "",
+                )
+            )
+        else:
+            lines.append(f"- **{heading}:** {value}")
+    return "\n".join(lines).rstrip() + "\n"

cyberplain-0.1.0/src/cyberplain/safety.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import ipaddress
+
+
+class AuthorizationRequired(PermissionError):
+    """Raised when an active network check lacks explicit authorization."""
+
+
+def require_authorization(authorized: bool) -> None:
+    if not authorized:
+        raise AuthorizationRequired(
+            "This active network check requires permission. Pass authorized=True only for "
+            "systems you own or are explicitly allowed to test."
+        )
+
+
+def public_ip_warning(value: str) -> str | None:
+    try:
+        address = ipaddress.ip_address(value)
+    except ValueError:
+        return None
+    if address.is_global:
+        return "This is a public Internet address; confirm the exact testing scope first."
+    return None

cyberplain-0.1.0/src/cyberplain/tlscheck.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import socket
+import ssl
+from datetime import datetime, timezone
+
+
+def inspect_tls(host: str, port: int = 443, timeout: float = 5.0) -> dict[str, object]:
+    context = ssl.create_default_context()
+    with (
+        socket.create_connection((host, port), timeout=timeout) as raw,
+        context.wrap_socket(raw, server_hostname=host) as secure,
+    ):
+        certificate = secure.getpeercert()
+        cipher = secure.cipher()
+        expires_text = certificate.get("notAfter")
+        expires = (
+            datetime.strptime(expires_text, "%b %d %H:%M:%S %Y %Z").replace(tzinfo=timezone.utc)
+            if expires_text
+            else None
+        )
+        days = (expires - datetime.now(timezone.utc)).days if expires else None
+        return {
+            "host": host,
+            "port": port,
+            "tls_version": secure.version(),
+            "cipher": cipher[0] if cipher else None,
+            "certificate_subject": dict(item[0] for item in certificate.get("subject", [])),
+            "certificate_issuer": dict(item[0] for item in certificate.get("issuer", [])),
+            "expires_utc": expires.isoformat() if expires else None,
+            "days_until_expiry": days,
+            "subject_alt_names": [
+                value for kind, value in certificate.get("subjectAltName", []) if kind == "DNS"
+            ],
+            "plain_english": f"The certificate is trusted and expires in {days} days."
+            if days is not None
+            else "The certificate is trusted.",
+        }

cyberplain-0.1.0/tests/test_cli.py

@@ -0,0 +1,7 @@
+from cyberplain.cli import build_parser, run
+
+
+def test_cli_dns_parser():
+    args = build_parser().parse_args(["dns", "localhost"])
+    result = run(args)
+    assert result["host"] == "localhost"

cyberplain-0.1.0/tests/test_core.py

@@ -0,0 +1,45 @@
+from pathlib import Path
+
+import pytest
+
+from cyberplain.hashing import create_manifest, hash_file, verify_file, verify_manifest
+from cyberplain.iocs import defang, extract_iocs, refang
+from cyberplain.passwords import assess_password
+from cyberplain.ports import parse_ports, scan_ports
+
+
+def test_port_parser():
+    assert parse_ports("443,80,8000-8002") == [80, 443, 8000, 8001, 8002]
+
+
+def test_scan_requires_authorization():
+    with pytest.raises(PermissionError):
+        scan_ports("127.0.0.1", "80")
+
+
+def test_hash_and_verify(tmp_path: Path):
+    target = tmp_path / "hello.txt"
+    target.write_text("hello", encoding="utf-8")
+    digest = hash_file(target)
+    assert len(digest) == 64
+    assert verify_file(target, digest)
+
+
+def test_manifest_detects_changes(tmp_path: Path):
+    target = tmp_path / "hello.txt"
+    target.write_text("first", encoding="utf-8")
+    manifest = create_manifest(tmp_path)
+    target.write_text("second", encoding="utf-8")
+    assert verify_manifest(tmp_path, manifest)["changed"] == ["hello.txt"]
+
+
+def test_ioc_extraction_and_defang():
+    result = extract_iocs("Visit https://example.com/a from 192.0.2.8 or email a@example.com")
+    assert result["domains"] == ["example.com"]
+    assert result["ip_addresses"] == ["192.0.2.8"]
+    assert refang(defang("https://example.com")) == "https://example.com"
+
+
+def test_password_feedback():
+    assert assess_password("password")["rating"] == "very weak"
+    assert assess_password("correct horse battery staple plus")["score"] >= 3