LiteSOC Sentinel

Overview

The LiteSOC Sentinel is an open-source, single-binary agent written in Go. It tails system log files, parses SSH authentication events using battle-tested regex patterns, and forwards them to the api.litesoc.io/collect endpoint in real-time. A 60-second heartbeat keeps your dashboard showing the server as Active.

How It Works

Requirements

One-Line Install

Copy your Agent Key from the LiteSOC dashboard under Settings → API Keys, then run:

curl -sSL https://litesoc.io/install.sh | LITESOC_KEY=lsoc_live_your_key bash

The script will detect your architecture, download the correct binary, create the litesoc system user, write the systemd unit, and start the service automatically.

Pin to a specific version

curl -sSL https://litesoc.io/install.sh | \
  LITESOC_KEY=lsoc_live_your_key \
  LITESOC_AGENT_VERSION=v1.2.0 \
  bash

Build from source

git clone https://github.com/litesoc/litesoc-agent.git
cd litesoc-agent
make build          # builds bin/litesoc-agent for the host platform
make build-all      # cross-compiles for linux/amd64, arm64, darwin

Configuration

The installer writes a default config to /etc/litesoc/config.yaml. Edit it to add more log files or change the heartbeat interval, then restart the service.

# /etc/litesoc/config.yaml

# Base URL for the LiteSOC API (no trailing slash)
api_endpoint: https://api.litesoc.io

# How often (seconds) the agent sends a heartbeat ping
heartbeat_interval: 60

# Log files to monitor
log_watchers:
  # Debian / Ubuntu
  - path: /var/log/auth.log
    type: sshd

  # Fedora / RHEL / CentOS — uncomment if applicable:
  # - path: /var/log/secure
  #   type: sshd

Security Events

The agent maps sshd log patterns to LiteSOC standard events. All forwarded events include actor_ip, actor_identifier (username), and a metadata object with the port and reason.

Example payload

{
  "event": "auth.login_failed",
  "user_ip": "203.0.113.42",
  "actor": { "id": "root" },
  "metadata": {
    "source": "sshd",
    "log_file": "/var/log/auth.log",
    "reason": "failed_password",
    "port": "22"
  }
}

Heartbeat & Dashboard Status

Every 60 seconds the agent POSTs to POST /agent/heartbeat. If the dashboard shows Inactive, the server has not sent a heartbeat within 2 × the configured interval.

// POST https://api.litesoc.io/agent/heartbeat
// Headers: X-API-Key: lsoc_live_...

{
  "agent_version": "1.0.0"
}

The heartbeat is also fired immediately on startup so the dashboard reflects the new agent within seconds, without waiting for the first 60-second tick.

Managing the Service

journalctl -u litesoc-agent -f

systemctl status litesoc-agent

systemctl restart litesoc-agent

systemctl stop litesoc-agent
systemctl disable litesoc-agent

# Edit the key — file is root-only (chmod 600)
nano /etc/litesoc/agent.env
systemctl restart litesoc-agent

systemctl stop litesoc-agent
systemctl disable litesoc-agent
rm /etc/systemd/system/litesoc-agent.service
rm /usr/local/bin/litesoc-agent
rm -rf /etc/litesoc
userdel litesoc
systemctl daemon-reload

Troubleshooting

journalctl -u litesoc-agent -n 50 --no-pager

systemctl is-active litesoc-agent
curl -I https://api.litesoc.io/health

# Check which file exists on your system
ls -lh /var/log/auth.log /var/log/secure 2>/dev/null

# Replace key and restart
echo 'LITESOC_KEY=lsoc_live_newkey' > /etc/litesoc/agent.env
chmod 600 /etc/litesoc/agent.env
systemctl restart litesoc-agent

systemctl show litesoc-agent | grep -E 'MemoryCurrent|CPUUsage'