From e3e89582c1a59ff1d171163dcc0bde0863426dc2 Mon Sep 17 00:00:00 2001 From: Hadi <112569860+anotherhadi@users.noreply.github.com> Date: Mon, 18 May 2026 22:59:48 +0200 Subject: [PATCH] Add commit hook & markdown scripts --- .github/scripts/inject-exec.py | 33 +++++++++++++++++++++ README.md | 52 ++++++++++++++++++++++++---------- docs/basics.md | 31 ++++++++++++++++++++ docs/legal-disclaimer.md | 7 +++++ flake.nix | 15 ++++++++++ internal/ui/docs/model.go | 4 ++- lefthook.yml | 15 ++++++++++ 7 files changed, 141 insertions(+), 16 deletions(-) create mode 100644 .github/scripts/inject-exec.py create mode 100644 docs/basics.md create mode 100644 docs/legal-disclaimer.md create mode 100644 lefthook.yml diff --git a/.github/scripts/inject-exec.py b/.github/scripts/inject-exec.py new file mode 100644 index 0000000..3dd1ad4 --- /dev/null +++ b/.github/scripts/inject-exec.py @@ -0,0 +1,33 @@ +#!/usr/bin/env python3 +import re +import subprocess +import sys +from pathlib import Path + +PATTERN = re.compile(r".*?", re.DOTALL) + + +def replace(match): + cmd = match.group(1).strip() + result = subprocess.run(cmd, shell=True, capture_output=True, text=True) + output = result.stdout + if result.returncode != 0: + print(f"[inject-exec] command failed ({result.returncode}): {cmd}", file=sys.stderr) + print(result.stderr, file=sys.stderr) + sys.exit(1) + output = re.sub(r"\n?|\n?", "", output) + if output and not output.endswith("\n"): + output += "\n" + return f"\n{output}" + + +def process(path): + content = Path(path).read_text() + new_content = PATTERN.sub(replace, content) + if new_content != content: + Path(path).write_text(new_content) + print(f"[inject-exec] updated {path}") + + +for p in sys.argv[1:]: + process(p) diff --git a/README.md b/README.md index 939077c..047c27b 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,23 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Go Report Card](https://goreportcard.com/badge/github.com/anotherhadi/spilltea)](https://goreportcard.com/report/github.com/anotherhadi/spilltea) + + + +- [Legal Disclaimer](#legal-disclaimer) +- [What is Spilltea?](#what-is-spilltea) +- [Features](#features) +- [Installation](#installation) +- [Project Management](#project-management) +- [Configuration](#configuration) +- [CLI Flags](#cli-flags) +- [Plugin System](#plugin-system) +- [Deployment](#deployment) +- [Tech Stack](#tech-stack) + + + + ## Legal Disclaimer **This tool is provided for educational purposes and authorized security testing only.** @@ -21,6 +38,7 @@ Use Spilltea only on systems and networks you own or have explicit written permission to test. Intercepting network traffic without authorization may violate local laws (such as the Computer Fraud and Abuse Act, GDPR, or equivalent legislation in your jurisdiction). The author(s) and contributors are not responsible for any misuse, damage, or legal consequences resulting from the use of this software. By using Spilltea, you agree that you are solely responsible for ensuring your usage is lawful and authorized. + ## What is Spilltea? @@ -81,6 +99,7 @@ environment.systemPackages = [ inputs.spilltea.packages.${pkgs.system}.default ] + ## Project Management Spilltea organizes work into **projects**. Each project maps to a SQLite database file that stores all intercepted traffic for that session & a log files. @@ -91,11 +110,6 @@ On startup, you choose: - **Existing project**: pick from a list of previous projects - **Temporary**: no name needed, stored in `/tmp/spilltea/projects/` and will be deleted on your next reboot! -## Plugin System - -Spilltea supports plugins written in **Lua**. Plugins are loaded from `~/.config/spilltea/plugins/` by default and do not require recompilation or access to the source code. -For a full reference and examples, see the [plugin documentation](./docs/plugins.md) or [plugin examples](./plugins/). - ## Configuration Spilltea is fully configured via a YAML file at `~/.config/spilltea/config.yaml`. @@ -103,16 +117,24 @@ Check the default configuration with all the options [here](./internal/config/de ## CLI Flags -| Flag | Short | Description | -| ----------------------- | ----- | ------------------------------------------------------------------------------ | -| `--config` | `-c` | Path to config file (default: `~/.config/spilltea/config.yaml`) | -| `--plugin-dir` | | Path to plugins dir, overrides config (default: `~/.config/spilltea/plugins/`) | -| `--host` | | Proxy host, overrides config | -| `--port` | `-p` | Proxy port, overrides config | -| `--project` | `-P` | Project name to open directly, or `tmp` for a temporary session | -| `--upstream-proxy` | | Upstream proxy URL, overrides config (e.g. `http://user:pass@host:8888`) | -| `--version` | `-v` | Print version and exit | -| `--add-default-plugins` | | Add the default plugins to your plugins dir and exit | +``` +Usage: spilltea [flags] + + --add-default-plugins copy built-in example plugins into the plugins dir and exit + -c, --config string path to config file + --host string proxy host (overrides config) + --plugins-dir string path to plugins dir (overrides config) + -p, --port int proxy port (overrides config) + -P, --project string project name to open directly, or "tmp" for a temporary session + --upstream-proxy string upstream proxy URL, e.g. http://user:pass@host:8888 (overrides config) + -v, --version print version +``` + + +## Plugin System + +Spilltea supports plugins written in **Lua**. Plugins are loaded from `~/.config/spilltea/plugins/` by default and do not require recompilation or access to the source code. +For a full reference and examples, see the [plugin documentation](./docs/plugins.md) or [plugin examples](./plugins/). ## Deployment diff --git a/docs/basics.md b/docs/basics.md new file mode 100644 index 0000000..4cce217 --- /dev/null +++ b/docs/basics.md @@ -0,0 +1,31 @@ +## Project Management + +Spilltea organizes work into **projects**. Each project maps to a SQLite database file that stores all intercepted traffic for that session & a log files. + +On startup, you choose: + +- **New project**: enter a name, stored in `~/.local/share/spilltea/projects/` by default +- **Existing project**: pick from a list of previous projects +- **Temporary**: no name needed, stored in `/tmp/spilltea/projects/` and will be deleted on your next reboot! + +## Configuration + +Spilltea is fully configured via a YAML file at `~/.config/spilltea/config.yaml`. +Check the default configuration with all the options [here](./internal/config/default_config.yaml) + +## CLI Flags + + +``` +Usage: spilltea [flags] + + --add-default-plugins copy built-in example plugins into the plugins dir and exit + -c, --config string path to config file + --host string proxy host (overrides config) + --plugins-dir string path to plugins dir (overrides config) + -p, --port int proxy port (overrides config) + -P, --project string project name to open directly, or "tmp" for a temporary session + --upstream-proxy string upstream proxy URL, e.g. http://user:pass@host:8888 (overrides config) + -v, --version print version +``` + diff --git a/docs/legal-disclaimer.md b/docs/legal-disclaimer.md new file mode 100644 index 0000000..dec1480 --- /dev/null +++ b/docs/legal-disclaimer.md @@ -0,0 +1,7 @@ +## Legal Disclaimer + +**This tool is provided for educational purposes and authorized security testing only.** + +Use Spilltea only on systems and networks you own or have explicit written permission to test. Intercepting network traffic without authorization may violate local laws (such as the Computer Fraud and Abuse Act, GDPR, or equivalent legislation in your jurisdiction). + +The author(s) and contributors are not responsible for any misuse, damage, or legal consequences resulting from the use of this software. By using Spilltea, you agree that you are solely responsible for ensuring your usage is lawful and authorized. diff --git a/flake.nix b/flake.nix index 68bc2e2..d894bd7 100644 --- a/flake.nix +++ b/flake.nix @@ -37,5 +37,20 @@ "${pname}" = pkg; default = pkg; }); + + devShells = forAllSystems (system: pkgs: { + default = pkgs.mkShell { + packages = with pkgs; [ + go + python3 + lefthook + doctoc + ]; + + shellHook = '' + lefthook install + ''; + }; + }); }; } diff --git a/internal/ui/docs/model.go b/internal/ui/docs/model.go index 50b2227..85e0cfc 100644 --- a/internal/ui/docs/model.go +++ b/internal/ui/docs/model.go @@ -19,12 +19,14 @@ import ( ) func readDoc(name string) string { - b, _ := spilltea.DocsFS.ReadFile("./docs/" + name) + b, _ := spilltea.DocsFS.ReadFile("docs/" + name) return string(b) } var contentMarkdown = strings.Join([]string{ readDoc("main.md"), + readDoc("legal-disclaimer.md"), + readDoc("basics.md"), readDoc("proxy.md"), readDoc("certificate.md"), readDoc("history.md"), diff --git a/lefthook.yml b/lefthook.yml new file mode 100644 index 0000000..7842814 --- /dev/null +++ b/lefthook.yml @@ -0,0 +1,15 @@ +pre-commit: + piped: true + commands: + inject-exec-basics: + glob: "docs/basics.md" + run: python3 .github/scripts/inject-exec.py {staged_files} + stage_fixed: true + inject-exec: + glob: "README.md" + run: python3 .github/scripts/inject-exec.py {staged_files} + stage_fixed: true + toc: + glob: "README.md" + run: doctoc --notitle {staged_files} + stage_fixed: true