Add synterloper/README.md

synterloper/README.md

@@ -0,0 +1,73 @@
+# SYNterloper - First-boot Truncated Rolling PCAP Logger
+
+**SYNterloper** is a utility for creating a persistent, rolling packet capture for a specific network port (defaulting to TCP/22 for SSH). Its primary purpose is to provide a simple, low-overhead log of connection attempts for troubleshooting, security analysis, and auditing.
+
+The tool is delivered as a single, self-contained script designed for automated deployment on first-boot, making it ideal for cloud environments like AWS, where it can be included in **User Data** to configure new instances.
+
+## Core Functionality
+
+-   **Self-Contained:** A single script handles installation, service creation, and uninstallation. No external dependencies like `git` are required for deployment.
+-   **System Service:** Runs as a standard `systemd` (Linux) or `rc.d` (FreeBSD) service.
+-   **Rolling Buffer & Automatic Pruning:** Creates hourly log files and prunes logs older than 7 days to manage disk space.
+-   **Efficient Capture:** Captures only packet headers to keep logs small and focused.
+-   **Self-Managing:** The script copies itself to `/usr/local/sbin/synterloper` during installation, making it easy to manage or uninstall later.
+
+## Automated Deployment (AWS User Data)
+
+To install SYNterloper on a new EC2 instance, paste the entire contents of the `synterloper.sh` script into the "User Data" field at launch.
+
+#### Example User Data:
+
+```bash
+#!/bin/bash
+#
+# User Data script to install SYNterloper.
+# The contents of synterloper.sh are placed directly below.
+#
+
+# --- Start of synterloper.sh ---
+
+# PASTE THE ENTIRE CONTENTS OF THE synterloper.sh SCRIPT HERE
+
+# --- End of synterloper.sh ---
+
+```
+
+When the instance boots, the cloud-init service will execute this script, which will then run the `install_synterloper` function by default.
+
+## Manual Installation
+
+To install on an existing system:
+1.  Save the script's contents to a file named `synterloper.sh`.
+2.  Make it executable: `chmod +x synterloper.sh`.
+3.  Run it with root privileges: `sudo ./synterloper.sh`.
+
+## Usage and Verification
+
+#### Service Management
+
+-   **Check Status (Linux):** `systemctl status synterloper.service`
+-   **Check Status (FreeBSD):** `service synterloper status`
+
+#### Reading Capture Files
+
+The raw `.pcap` files are stored in `/var/log/synterloper/`.
+
+**To read the most recent log file from the command line:**
+```sh
+sudo tcpdump -n -r $(ls -t /var/log/synterloper/*.pcap | head -1)
+```
+
+## Uninstallation
+
+Because the installation process places a copy of the script in the system's path, you can easily uninstall the tool at any time.
+
+```sh
+sudo /usr/local/sbin/synterloper uninstall
+```
+
+For non-interactive uninstallation, pipe `yes` to the command (note: this is not required for the updated script, but is a common pattern).
+```sh
+sudo /usr/local/sbin/synterloper uninstall
+```
+This command will stop the service, remove all system files it created (service definitions, cron jobs), delete the log directory, and remove the `/usr/local/sbin/synterloper` script itself.