# LiteSOC — Server Security Agent (Sentinel)

> A lightweight Go agent that watches your server logs in real-time, extracts SSH security events, and streams them to your LiteSOC dashboard. Installed in one command, uses <20 MB RAM.

- **Docs:** https://litesoc.io/docs/integrations/agent
- **Source:** https://github.com/litesoc/litesoc-agent
- **Install script:** https://litesoc.io/install.sh
- **Plans:** All plans (Free, Pro, Enterprise)
- **OS:** Linux (amd64, arm64, armv7)

## Overview

The LiteSOC Sentinel is an open-source, single-binary agent written in Go.

**How it works:**
1. **Watch** — Opens configured log files (e.g. /var/log/auth.log) using kernel inotify — no polling, no wasted CPU
2. **Parse** — Matches new lines against OpenSSH regex patterns to classify login failures, successes, and logouts
3. **Forward** — POSTs a structured JSON payload to https://api.litesoc.io/collect — API key sent in X-API-Key header only
4. **Heartbeat** — Every 60 seconds a lightweight ping is sent to https://api.litesoc.io/agent/heartbeat so the dashboard shows the server as Active

**Resource guarantees:**
- RAM: <20 MB (systemd enforces MemoryMax=32M)
- CPU: <1% (systemd enforces CPUQuota=5%)
- File watching: kernel inotify — zero polling loops

## One-Line Install

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

**Requirements:**
- Linux only (amd64, arm64, armv7)
- Must run as root (installs to /usr/local/bin, creates systemd unit)
- curl and tar must be present
- systemd required for the installer (binary can also run directly)

**Pin to a specific version:**
```bash
curl -sSL https://litesoc.io/install.sh | \
  LITESOC_KEY=lsoc_live_your_key \
  LITESOC_AGENT_VERSION=v1.2.0 \
  bash
```

**Build from source:**
```bash
git clone https://github.com/litesoc/litesoc-agent.git
cd litesoc-agent
make build        # host platform
make build-all    # linux/amd64, arm64, darwin
```

## Configuration

Default config is written to /etc/litesoc/config.yaml by the installer.

```yaml
# /etc/litesoc/config.yaml

api_endpoint: https://api.litesoc.io
heartbeat_interval: 60

log_watchers:
  # Debian / Ubuntu
  - path: /var/log/auth.log
    type: sshd
  # Fedora / RHEL / CentOS:
  # - path: /var/log/secure
  #   type: sshd
```

**Configuration reference:**

| Key | Type | Default | Description |
|---|---|---|---|
| api_endpoint | string | https://api.litesoc.io | LiteSOC ingestion API base URL |
| heartbeat_interval | int | 60 | Seconds between heartbeat pings |
| log_watchers[].path | string | — | Absolute path to a log file |
| log_watchers[].type | string | sshd | Parser type — only "sshd" is currently supported |

**API Key:** stored in /etc/litesoc/agent.env (chmod 600, root-only), loaded via systemd EnvironmentFile — never in config.yaml.

## Security Events Emitted

The agent maps sshd log patterns to LiteSOC standard events.

| sshd Log Pattern | Event Name | Reason (metadata) |
|---|---|---|
| Failed password for … from IP port N | auth.login_failed | failed_password |
| Invalid user X from IP port N | auth.login_failed | invalid_user |
| Accepted publickey/password for … from IP port N | auth.login_success | — |
| Disconnected from [user] … IP port N | auth.logout | — |

**Example payload sent to POST /collect:**

```json
{
  "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

Every 60 seconds the agent POSTs to POST /agent/heartbeat. Also fires immediately on startup.

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

{
  "agent_version": "1.0.0"
}
```

If the dashboard shows a server as Inactive, the agent has not sent a heartbeat within 2× the configured interval.

## Managing the systemd Service

```bash
# View live logs
journalctl -u litesoc-agent -f

# Check status
systemctl status litesoc-agent

# Restart after config change
systemctl restart litesoc-agent

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

# Uninstall
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
```

## Systemd Unit Hardening

The installed unit runs under a dedicated low-privilege `litesoc` system user (nologin, no home) with these security controls:

- NoNewPrivileges=true
- PrivateTmp=true
- ProtectSystem=strict
- ProtectHome=true
- ReadWritePaths=/var/log
- CapabilityBoundingSet= (empty — no Linux capabilities)
- MemoryMax=32M
- CPUQuota=5%
- Restart=always

## Troubleshooting

| Problem | Solution |
|---|---|
| Service fails to start | Run: journalctl -u litesoc-agent -n 50 — most common cause is missing/invalid LITESOC_KEY in /etc/litesoc/agent.env |
| Dashboard shows server as Inactive | Agent has not sent a heartbeat within 2× heartbeat_interval. Check service is running and HTTPS to api.litesoc.io:443 is not blocked |
| No events appearing | Confirm log_watchers path matches your distro. Ubuntu/Debian: /var/log/auth.log. RHEL/Fedora: /var/log/secure |
| 401 Unauthorized | Key in /etc/litesoc/agent.env does not match a valid active key. Regenerate in dashboard and restart service |
| High CPU/memory | Extremely noisy log file. systemd hard limits (MemoryMax=32M, CPUQuota=5%) prevent runaway usage |