theProtector is a Bash host monitoring framework with eBPF, YARA and honeypot modules

One script with switchable modules rather than a resident agent

theProtector v2.3 is described as a comprehensive host-based security monitoring framework that implements real-time threat detection through eBPF kernel monitoring, YARA pattern matching, network honeypots and anti-evasion techniques. The design goal stated in the overview is multi-layer monitoring combining user-space and kernel-space detection mechanisms, operating continuously while maintaining minimal system overhead.

The mechanism is worth understanding because it determines what you are signing up for. This is a Bash script, theProtector.sh, that you invoke with subcommands. The modules are separate invocations that can be run one at a time:

# Run specific monitoring modules
sudo ./theprotector.sh yara        # YARA scanning only
sudo ./theprotector.sh honeypot    # Network honeypots only
sudo ./theprotector.sh ebpf        # eBPF monitoring only

and the README lists a performance mode for reduced overhead, plus a basic scan, an enhanced mode with all features, a test command that shows capabilities, and a status command. The distinction between the basic scan and enhanced monitoring is the model's main switch, and enhanced also triggers the threat intelligence update automatically.

For continuous operation the script installs itself as scheduled work, either an hourly cron job or a systemd service, with systemd marked as recommended for servers:

# Install scheduled monitoring (hourly cron job)
sudo ./theprotector.sh install

# Install systemd service (recommended for servers)
sudo ./theprotector.sh systemd

The unprivileged path exists too. The README notes that unprivileged usage, running without sudo, is also supported, and the log locations section distinguishes a root user path of /var/log/ghost-sentinel/ from a non-root path of $HOME/.ghost-sentinel/logs/. That is a meaningful design choice for a tool that runs privileged, since an unprivileged run is a different threat model with a different set of things it can actually see.

One structural note about the repository. The top level holds theprotector.sh alongside TheProtectorV4.sh, Slack.sh, TheProtectV4Dashboard.go, a flake.nix and flake.lock, and a file named tech paper for Protector. So the README describes the v2.3 script while the tree also carries other generations of the project, and a Nix flake bundles theprotector.sh as a wrapper script that includes all optional dependencies.

The config file is shell syntax, with every module behind a boolean

Configuration is a file called sentinel.conf placed in the same directory as the script, and it is written in shell variable syntax rather than in a format the script parses. That means the script sources it, and the values are available as ordinary environment variables to the code that runs.

The file is organised by what it controls. Monitoring modules:

# Monitoring modules
MONITOR_NETWORK=true
MONITOR_PROCESSES=true
MONITOR_FILES=true
MONITOR_USERS=true
MONITOR_ROOTKITS=true
MONITOR_MEMORY=true

# Advanced features
ENABLE_ANTI_EVASION=true
ENABLE_EBPF=true
ENABLE_HONEYPOTS=true
ENABLE_API_SERVER=true
ENABLE_YARA=true
ENABLE_THREAT_INTEL=true

Six monitoring areas and six advanced features, each a boolean. The monitoring group is what the scanner checks, and the enable group is which of the heavier mechanisms actually run, which is how you turn off the parts you cannot support on a given host.

Performance tuning follows, and the values are specific enough to be worth reading:

# Performance tuning
PERFORMANCE_MODE=false
MAX_FIND_DEPTH=2
SCAN_TIMEOUT=180
PARALLEL_JOBS=2

A scan timeout of 180 seconds and two parallel jobs are conservative defaults, and MAX_FIND_DEPTH of 2 bounds how deep the file search descends, which is the setting that decides whether a scan of a large tree finishes in minutes or hours.

Notifications and threat intelligence are configured next, with email and two webhook URLs for outbound alerting, syslog on by default, and API keys for AbuseIPDB and VirusTotal with a refresh interval of six hours. The network settings close the file, and they carry the two values that can break a deployment:

# Network settings
API_PORT=8080
HONEYPOT_PORTS=("2222" "8080" "23" "21" "3389")

The API port defaults to 8080, and the honeypot list includes 8080 as well as the SSH port 22 replaced by 23, 21 and 3389. If the API server is enabled on 8080 and the honeypot module also wants 8080, one of them fails to bind. That collision is in the shipped defaults rather than in your configuration, so it is worth checking before enabling both.

Two environment variables override the file: DASHBOARD_PORT for the API port and GHOST_SENTINEL_LOG_DIR for the log directory. Whitelisting is also done in the same file, with WHITELIST_PROCESSES matched exactly, WHITELIST_CONNECTIONS as a list of addresses, and EXCLUDE_PATHS for directories to skip.

The REST API and the JSON output that lets you pipe results elsewhere

theProtector has two integration surfaces, a REST API and a JSON file, and the second is the more useful of the pair for most people.

The API server runs as a subcommand and listens locally by default:

sudo ./theprotector.sh api
# Access dashboard at http://127.0.0.1:8080

The dashboard and the API share the port, and the four documented endpoints are:

# System status
curl http://127.0.0.1:8080/api/status

# Recent alerts
curl http://127.0.0.1:8080/api/alerts

# Latest scan results
curl http://127.0.0.1:8080/api/scan

# Honeypot activity
curl http://127.0.0.1:8080/api/honeypot

Everything binds to 127.0.0.1, so the API is not reachable from another host unless you change the binding yourself, and the DASHBOARD_PORT environment variable is the documented way to move the port when 8080 is already taken on the machine.

The JSON output is the more portable surface. The scan writes latest_scan.json with a documented structure:

{
  "version": "2.3",
  "scan_start": "2025-01-15T10:30:00Z",
  "scan_end": "2025-01-15T10:32:15Z",
  "hostname": "server-01",
  "summary": {
    "total_alerts": 3,
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 0
  },
  "alerts": [
    {
      "level": 2,
      "message": "Suspicious process detected",
      "timestamp": "2025-01-15T10:31:22Z"
    }
  ]
}

Alerts carry a numeric level rather than a string severity, and the summary breaks the counts down by critical, high, medium and low. The README shows the pairing with jq for a SIEM pipeline:

# Syslog output (automatic if SYSLOG_ENABLED=true)
logger -t "theprotector" -p security.alert "Alert message"

# JSON log parsing
tail -f /var/log/ghost-sentinel/latest_scan.json | jq '.alerts[]'

The log file layout is documented in full: sentinel.log for general activity, an alerts directory with daily files named YYYYMMDD.log, latest_scan.json, honeypot.log for connection attempts, ebpf_events.log for kernel-level events, and a quarantine directory holding quarantined files with forensic data. Syslog output is automatic when SYSLOG_ENABLED is true, which is how the script talks to a SIEM that already collects syslog rather than making you poll a file.

Optional dependencies decide which modules are real

The README is explicit that the monitoring capabilities rest on external tools, and lists them per distribution.

# Ubuntu/Debian
sudo apt update
sudo apt install yara jq inotify-tools bcc-tools netcat-openbsd python3

The Fedora and Arch equivalents differ in package names rather than in tools: dnf install yara jq inotify-tools bcc-tools nmap-ncat python3 on Fedora and RHEL, and pacman -S yara jq inotify-tools bcc netcat python on Arch.

Each tool has a job, and the mapping tells you what a missing package costs you. yara provides the advanced malware detection rules, which is what the YARA scanning module scans with. jq handles enhanced JSON processing and output formatting, and is also what the documented SIEM pipeline uses. inotify-tools provides real-time file system monitoring, which is the mechanism behind the file monitoring module and the live response to changes. bcc-tools provides the eBPF kernel instrumentation that the process and system call tracing depends on. netcat implements the network honeypot listeners. python3 provides the API server and the advanced monitoring features.

That last mapping is the one to weigh. The API server, the dashboard and the advanced monitoring features are Python components, and the script is the orchestrator around them. So the eBPF path needs a kernel 4.9 or newer, the shell needs Bash 4.0 or newer, and the advanced features need a working Python 3 with whatever the script imports.

The test command is the way to find out what you actually have before you rely on it. The README describes the test subcommand as testing installation and showing capabilities, and it appears both in the quick start and in the basic commands list.

A Nix route is also offered. The flake bundles theprotector.sh as a wrapper script that includes all optional dependencies, installed with nix profile install github:IHATEGIVINGAUSERNAME/theprotector. That is the practical answer for the dependency sprawl, since the wrapper resolves the package name differences between distributions for you.

What a monitoring script cannot do for you

Three limits, and the first is about trust in the tooling itself.

The first is that this is a shell script, run with root, from a repository with no GitHub releases. The top level contains the script, a second script named TheProtectorV4.sh, another named Slack.sh, a Go file named TheProtectV4Dashboard.go, and a file whose name is a tech paper with a space in it. There is no release, no versioned artefact, no checksum to verify and no changelog. You are running a script you have read, which is defensible for a tool you are auditing yourself, and it is a different risk profile from a signed binary with a documented release history.

The second is the fundamental limit of host-based detection. The feature list says it detects suspicious activities, malware and evasion attempts, and the modules are process execution tracking, system call analysis, YARA pattern matching, honeypots, anti-evasion cross-validation and IP reputation checking. All of that observes the machine it runs on. An attacker who never executes on that host, or who acts only through the interfaces the honeypots occupy, is not what these modules are built to find. The honeypot list of 2222, 8080, 23, 21 and 3389 is a small set of well-known ports, and a honeypot listener is a signal, not a defence.

The third is that this sits alongside a real security stack rather than replacing one. The feature list mentions container support and optimized monitoring for containerized environments, and the dependencies include nmap-ncat and bcc-tools, but nothing in the README describes how the script behaves inside a container, which is a question with more than one answer and where the eBPF and inotify paths can behave differently from a bare host.

The alternative approach is a dedicated host security agent from an established vendor, which brings signed releases, a documented update path, a support commitment and a rule set that other people maintain. The difference in approach is that theProtector gives you a script you can read end to end, modify, and run on a host with no agent infrastructure, and it gives that up in exchange for no vendor support, no signed distribution and no evidence of the rule set being maintained by anyone but the author. For a lab machine, a homelab, or a short-lived box you are about to rebuild, that trade is good. For a host holding anything you would not want to lose, it is not the whole answer.

The README's own framing, the description line in the repository, calls it a tool for the paranoid admin on a budget, and the GPL-3.0 licence and the licence file in the repository root leave the code open for inspection and modification.

Editorial conclusion

Adopt theProtector if you run a small number of Linux hosts you already administer and want visibility into process execution, file changes and inbound scanning without deploying a full security platform, because the whole thing is one shell script with a config file and a JSON output you can pipe elsewhere. Do not adopt it as your production endpoint security, since it is a script with no releases, no signed artefacts and a repository that also contains a second shell script and a Go dashboard file at the top level. Verify first that your kernel is 4.9 or newer and your shell is Bash 4.0 or newer, since the eBPF path needs both, that the optional tools the README lists are actually installed, because several modules degrade without them, that the honeypot ports in HONEYPOT_PORTS do not collide with a service you already run on 8080, and that the API listener on 127.0.0.1 stays local unless you deliberately expose it.

Frequently asked questions

Official sources

1. IHATEGIVINGAUSERNAME/theProtector on GitHub
2. Issues
3. License: GPL-3.0
4. README