diff --git a/README.md b/README.md index e53d6c9..402e685 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,200 @@ # Random-Stuff -A collection of various Python apps and scripts I've written over the yeears that I've found interesting or useful. - -- **checkmedia.py**: A script to recursively scan all of the files in a directory and determine if any have been modified. -- **cookieMonster.py**: A library to encrypt and decrypt HTML header cookies to transmit data securely. -- **genpw.py**: A simple script to combine multiple words together to generate a password. -- **heartbeat.py**: A 2-host heartbeat script to create an active/standby pair. -- **linux_sys_stats.py**: A script that pulls relevent system stats and prints them -- **mac_sys_stats.py**: A script that pulls relevent system stats and prints them -- **myfuncs.py**: A library pf small utlities I've found useful -- **paravia.c**: An old C code implementation of Santa Paravia and Fiumaccio -- **pong.py**: A simple app for a Tufty 2040 that will display your name and dislay a game of pong. -- **pythonrc.py**: An enhanced and optimized version of [lonetwin's pythonrc](https://github.com/lonetwin/pythonrc) -- **quova.py**: A very early attempt to emulate the Quova protocol -- **random_cow.py**: A script to randomly choose a cowsay, get a fortune and print it -- **summarize_git.py**: A script to use an LLM to generate a concise summary of a Git repo. -- **sys_stats_api.py**: A simple REST API wrapper for \*\_sys_stats.py to get the stats and send them in JSON. -- **tcpQueue.py**: A library to allow sending/receiving data over a TCP connection for distributed computing. -- **vushta.py**: A script to generate a random Forbidden Delight. -- **web_stats.py**: An app to pull all of the stats from different hosts, consolidate them and generate graphs. +> A curated grab-bag of Python (and a little C) apps, scripts, and libraries +> collected over the years — the useful, the interesting, and the just-plain-fun. + +[![Language: Python](https://img.shields.io/badge/language-Python%203-3776AB?logo=python&logoColor=white)](https://www.python.org/) +[![Language: C](https://img.shields.io/badge/language-C-A8B9CC?logo=c&logoColor=black)](#retro--fun) +[![License: GPL v2](https://img.shields.io/badge/license-GPL%20v2-blue.svg)](LICENSE.md) +[![Security Policy](https://img.shields.io/badge/security-policy-brightgreen.svg)](SECURITY.md) + +Nothing here shares a single theme — that's the point. Each item is a +self-contained tool or library that solved a real problem (or scratched a real +itch). Browse the categories below, grab what looks useful, and ignore the rest. + +--- + +## Table of Contents + +- [Highlights](#highlights) +- [System Monitoring & Stats](#system-monitoring--stats) +- [Networking & Distributed Computing](#networking--distributed-computing) +- [Security & Cryptography](#security--cryptography) +- [LLM-Powered Tools](#llm-powered-tools) +- [Web App Example](#web-app-example) +- [Retro & Fun](#retro--fun) +- [Shared Libraries & Dotfiles](#shared-libraries--dotfiles) +- [Getting Started](#getting-started) +- [Contributing](#contributing) +- [Security](#security) +- [License](#license) + +--- + +## Highlights + +If you only look at a few things, make it these: + +- 🔐 **[`cookieMonster.py`](cookieMonster.py)** — securely encrypt/decrypt data + inside HTTP header cookies using Fernet, with the key interleaved among the + payload segments. +- 📦 **[`tcpQueue.py`](tcpQueue.py)** — a bidirectional TCP message queue with + on-disk SQLite (WAL) durability and optional HMAC-SHA256 authentication. +- ❤️ **[`heartbeat.py`](heartbeat.py)** — a deterministic (no split-brain) + primary/secondary failover daemon for two-node clusters. +- 🤖 **[`summarize_git.py`](summarize_git.py)** — point a local LLM at a repo and + get back a concise, human-readable summary. + +--- + +## System Monitoring & Stats + +Tools for collecting, exposing, and visualizing host metrics. + +| Script | What it does | +| ------ | ------------ | +| [`linux_sys_stats.py`](linux_sys_stats.py) | Pulls relevant system stats on Linux (via `top`) and prints them. | +| [`mac_sys_stats.py`](mac_sys_stats.py) | The macOS counterpart — same idea, tuned for `top -l 1`. | +| [`sys_stats_api.py`](sys_stats_api.py) | A tiny Flask REST wrapper that serves the `*_sys_stats.py` output as JSON (auto-selects Linux/macOS at runtime). | +| [`web_stats.py`](web_stats.py) | Polls multiple hosts, consolidates their stats, and renders graphs with matplotlib. | +| [`checkmedia.py`](checkmedia.py) | Recursively hashes every file in a directory (multithreaded, SQLite-backed) to detect if anything has been modified. | + +**Quick look — serve stats as JSON:** + +```bash +pip install flask +python3 sys_stats_api.py # then GET the endpoint it exposes +``` + +--- + +## Networking & Distributed Computing + +| Script | What it does | +| ------ | ------------ | +| [`tcpQueue.py`](tcpQueue.py) | Durable, crash-safe bidirectional message queue over TCP. Frames are length-prefixed with per-message opcodes and optional HMAC-SHA256 auth; queues persist to a WAL-mode SQLite DB. | +| [`heartbeat.py`](heartbeat.py) | Two-node active/standby failover daemon. Uses a deterministic `(ip, port)` election rule to avoid split-brain, with a state-change callback hook for VIP/service takeover. | +| [`quova.py`](quova.py) | An early Python 3 emulator of the Quova GeoIP protocol, backed by the MaxMind GeoLiteCity database. | + +--- + +## Security & Cryptography + +| Script | What it does | +| ------ | ------------ | +| [`cookieMonster.py`](cookieMonster.py) | Encrypts/decrypts arbitrary data for transport inside HTTP cookies using Fernet, splitting and interleaving the key with the ciphertext (base85-encoded). | +| [`genpw.py`](genpw.py) | Generates memorable passphrases by combining multiple random words. | +| [`checkmedia.py`](checkmedia.py) | File-integrity monitor — detects tampering by comparing content hashes against a saved baseline. | + +> ⚠️ These tools are provided as-is. Review the code and the [Security Policy](SECURITY.md) +> before relying on them for anything sensitive. + +--- + +## LLM-Powered Tools + +Both talk to a local, OpenAI-compatible endpoint (e.g. [LM Studio](https://lmstudio.ai/) +at `http://127.0.0.1:1234`) — no data leaves your machine. + +| Script | What it does | +| ------ | ------------ | +| [`summarize_git.py`](summarize_git.py) | Uses a local LLM to generate a concise summary of a Git repository. | +| [`summarize_readmes.py`](summarize_readmes.py) | Walks subdirectories, feeds their READMEs to a local LLM, and produces a combined summary — sizing input to the model's context window automatically. | + +--- + +## Web App Example + +[`PyWebApp/`](PyWebApp/) is a small, self-contained web application demonstrating +[CherryPy](https://cherrypy.dev/) + [Django](https://www.djangoproject.com/) +templating together with the `cookieMonster` encrypted-cookie library for secure +session data. It ships with HTML templates and a helper script to generate a +self-signed SSL certificate. + +```bash +cd PyWebApp +pip install -r requirements.txt +python3 index.py # serves on port 8080 by default +``` + +--- + +## Retro & Fun + +| Item | What it does | +| ---- | ------------ | +| [`paravia.c`](paravia.c) | A C implementation of the classic *Santa Paravia en Fiumaccio* medieval city-management game. | +| [`pong.py`](pong.py) | A [MicroPython](https://micropython.org/) badge app for the [Pimoroni Tufty 2040](https://shop.pimoroni.com/products/tufty-2040) — displays your name and an animated game of Pong. | +| [`random_cow.py`](random_cow.py) | Picks a random `cowsay` cow, grabs a `fortune`, and prints the two together. | +| [`vushta.py`](vushta.py) | Generates a random "Forbidden Delight" — an homage to the pleasures of the City of Vushta. | + +--- + +## Shared Libraries & Dotfiles + +| Item | What it does | +| ---- | ------------ | +| [`myfuncs.py`](myfuncs.py) | A grab-bag of small utility helpers (timing decorators, timeouts, etc.) reused across the other scripts. | +| [`pythonrc.py`](pythonrc.py) | An enhanced, optimized Python interactive-shell startup file — colored prompts, history, tab completion, source listing, and more. Based on [lonetwin's pythonrc](https://github.com/lonetwin/pythonrc). | + +**Use the enhanced interactive shell:** + +```bash +export PYTHONSTARTUP=/path/to/pythonrc.py +python3 +``` + +--- + +## Getting Started + +Everything here targets **Python 3** (the C and MicroPython items are the +exceptions). There's no single package to install — each script is standalone, +so just grab the one you want and install its dependencies. + +```bash +git clone https://github.com/DNSGeek/Random-Stuff.git +cd Random-Stuff +``` + +Common third-party dependencies, by tool: + +| Dependency | Used by | +| ---------- | ------- | +| `cryptography` | `cookieMonster.py`, `PyWebApp/` | +| `flask` | `sys_stats_api.py` | +| `matplotlib`, `requests` | `web_stats.py`, `summarize_git.py` | +| `cherrypy`, `django` | `PyWebApp/` | +| `python-daemon`, `pygeoip` | `quova.py` | + +Install what a given tool needs, e.g.: + +```bash +pip install cryptography # for cookieMonster.py +``` + +Most scripts print usage with `-h`/`--help` or have configuration constants +documented near the top of the file. + +--- + +## Contributing + +Issues and pull requests are welcome. Because these are independent tools, +please keep a change scoped to a single script where possible, and match the +existing style (type hints and docstrings are used throughout the Python code). + +--- + +## Security + +Found a vulnerability? Please report it responsibly — see [SECURITY.md](SECURITY.md) +for the disclosure process. Don't open a public issue for security reports. + +--- + +## License + +This project is licensed under the **GNU General Public License v2** — see +[LICENSE.md](LICENSE.md) for the full text. (`pythonrc.py` retains its original +MIT license from the upstream project.)