preaper

A secure process termination tool that makes killing processes easier and safer than traditional kill commands.

Features

• Multiple target types: Process ID (PID), process name, or port number
• Escalating signals: Graceful termination with SIGTERM → SIGINT → SIGHUP → SIGKILL sequence
• Direct action: No prompts or user input required - acts immediately
• Security focused: Input sanitization, command injection protection, and race condition prevention
• Self-protection: Skips its own PID and refuses to terminate init/system services (e.g., systemd, sshd)
• Smart validation: PID verification and command validation for safety
• Port support: Terminate processes listening on specific ports with server/client control
• Parallel processing: Terminates multiple processes simultaneously (default) or sequentially

Installation

Simply download and make executable:

curl -O https://raw.githubusercontent.com/meeghele/preaper/main/preaper
chmod +x preaper
sudo mv preaper /usr/local/bin/

Or clone the repository:

git clone https://github.com/meeghele/preaper.git
cd preaper
sudo cp preaper /usr/local/bin/

Usage

preaper TARGET

Target Types

Target Type	Format	Example	Description
Process ID	NUMBER	preaper 12345	Terminate process by PID (1-4194304)
Process Name	NAME	preaper firefox	Terminate all processes whose executable name matches exactly
Port	:NUMBER	preaper :8080	Terminate processes listening on port

Options

Option	Description
--sequential	Terminate processes sequentially instead of parallel (default)
--server-only	For ports: terminate only server processes (default)
--clients-only	For ports: terminate only client processes
--server-and-clients	For ports: terminate both server and client processes

Examples

Kill by Process ID:

preaper 12345        # Terminate process ID 12345

Kill by Process Name:

preaper firefox                  # Terminate all firefox processes (parallel)
preaper --sequential httpd       # Terminate all httpd processes (sequential)
preaper node                     # Terminate all node processes

Kill by Port:

preaper :8080                    # Terminate server on port 8080 (server-only)
preaper --clients-only :8080     # Terminate clients connected to port 8080
preaper --server-and-clients :80 # Terminate both server and clients on port 80
preaper --sequential :5432       # Terminate server on port 5432 (sequential)

Help:

preaper --help       # Show usage information
preaper -h           # Show usage information

Signal Sequence

preaper uses an escalating signal approach for graceful termination:

1. SIGTERM (15) - Graceful shutdown request, wait 3 seconds
2. SIGINT (2) - Interrupt signal, wait 2 seconds
3. SIGHUP (1) - Hangup signal, wait 1 second
4. SIGKILL (9) - Forced termination, no wait

This sequence allows processes to clean up resources and terminate gracefully before forcing termination.

Security Features

preaper includes multiple security measures to prevent unsafe operations:

• Input sanitization: Prevents command injection attacks
• PID verification: Prevents race conditions by validating process identity
• Self-termination protection: Cannot kill its own process
• Critical process protection: Refuses to terminate PID 1 and core daemons (init, systemd, launchd, sshd, login)
• Command validation: Verifies process command hasn't changed during termination
• Input length limits: Maximum 256 characters, no control characters
• Process name validation: Alphanumeric with ._/- allowed only
• Port range validation: Valid port numbers (1-65535) only
• PID range validation: Valid process IDs (1-4194304) only

Requirements

• Bash 4.0 or higher
• Standard UNIX tools: ps, lsof, kill, sleep

Exit Codes

Code	Description
0	Success
1	Error (invalid input, missing dependencies, termination failed)

Dependencies

preaper automatically checks for required commands:

• ps - Process status information
• lsof - List open files (for port-based termination)
• kill - Send signals to processes
• sleep - Wait between signal attempts

Testing

Run the test suite:

make test

Or run tests directly:

./test_preaper.sh

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome, please follow the semantic versioning branch naming convention:

• main: Production-ready code
• develop: Integration branch for features
• feat/: New features (feat/user-authentication)
• fix/: Bug fixes (fix/connection-timeout)
• chore/: Maintenance (chore/update-dependencies)

Author

Michele Tavella - meeghele@proton.me