.. | ||
README.md | ||
synterloper.sh |
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) orrc.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:
#!/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:
- Save the script's contents to a file named
synterloper.sh
. - Make it executable:
chmod +x synterloper.sh
. - 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:
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.
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).
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.