@agentsoc/beacon 0.0.1

package/README.md

@@ -0,0 +1,148 @@
+# AgentSOC Syslog Beacon CLI
+
+Lightweight, background-running log forwarder (beacon) for AgentSOC.
+
+## Overview
+
+The Syslog Beacon CLI allows you to configure, install, and run a lightweight log forwarding daemon that sends system logs to an AgentSOC ingest endpoint.
+
+## Requirements
+
+- [Node.js](https://nodejs.org/) v16 or higher
+
+## Installation
+
+### 🚀 Quick Install (One-Line Commands)
+
+#### macOS / Linux
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/yourusername/platform.agentsoc.com/main/apps/connectors/syslog-beacon-cli/install.sh | bash
+```
+
+#### Windows PowerShell
+
+```powershell
+irm https://raw.githubusercontent.com/yourusername/platform.agentsoc.com/main/apps/connectors/syslog-beacon-cli/install.ps1 | iex
+```
+
+#### Standard npm
+
+Published as [`@agentsoc/beacon`](https://www.npmjs.com/package/@agentsoc/beacon) (npm requires a lowercase scope; same AgentSOC package).
+
+```bash
+npm install -g @agentsoc/beacon
+```
+
+The `syslog-beacon` command is also installed as an alias for the same CLI.
+
+### Option 2: Run from source with Bun
+
+If you have the repository cloned and [Bun](https://bun.sh/) installed:
+
+```bash
+cd apps/connectors/syslog-beacon-cli
+bun install
+bun run src/cli.ts config --url <url> --key <key>
+bun run src/cli.ts run
+```
+
+### Installation Scripts
+
+Automated installation scripts are provided for easy setup:
+
+- **`install.sh`** - macOS/Linux installer
+- **`install.ps1`** - Windows PowerShell installer
+- **`install.bat`** - Windows batch installer
+
+These scripts automatically check for Node.js/npm, install the package, and verify the installation.
+
+## Usage
+
+The CLI provides the following commands:
+
+### Configure
+
+Configure the AgentSOC connection (saves to a local configuration file):
+
+```bash
+beacon config --url <url> --key <key>
+```
+
+**Required Parameters:**
+
+- `--url, -u <url>`: AgentSOC ingest URL (e.g., `https://api.agentsoc.com/ingest`)
+- `--key, -k <key>`: AgentSOC API Key (e.g., `sk_1234567890abcdef`)
+
+**Example:**
+
+```bash
+beacon config --url https://api.agentsoc.com/ingest --key sk_1234567890abcdef
+```
+
+**Note:** If you run `bun run src/cli.ts config` without the required parameters, you'll receive an error instructing you to provide the `-u` and `-k` options.
+
+### Run Foreground Daemon
+
+Run the forwarder daemon in the foreground:
+
+```bash
+beacon run [options]
+```
+
+**Options:**
+
+- `--batch-size <n>`: Set the batch size for log forwarding (default: 25)
+- `--flush-ms <n>`: Set the flush interval in milliseconds (default: 2000)
+
+**Example:**
+
+```bash
+beacon run --batch-size 50 --flush-ms 5000
+```
+
+_Note: You can also use environment variables `AGENTSOC_API_KEY` and `AGENTSOC_INGEST_URL` instead of running the `config` command._
+
+### Install Service
+
+Install the background service daemon (systemd on Linux, launchd on macOS):
+
+```bash
+beacon install
+```
+
+## Development
+
+- Start the daemon using npm script: `npm start` or `bun run start`
+- Install service using npm script: `npm run install-service` or `bun run install-service`
+- Build the distributable: `npm run build:simple` (compiles TypeScript to dist/)
+
+## Building & Distribution
+
+### Build the Package
+
+To build the TypeScript files into the `dist/` folder:
+
+```bash
+npm run build:simple
+```
+
+### Share Installation Scripts
+
+Users can install the package using one of the provided installation scripts:
+
+- Copy the `install.sh` script to your repository (macOS/Linux users)
+- Copy the `install.ps1` script to your repository (Windows PowerShell users)
+- Copy the `install.bat` script to your repository (Windows batch users)
+
+Users can then run:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/yourusername/platform.agentsoc.com/main/apps/connectors/syslog-beacon-cli/install.sh | bash
+```
+
+Or use npm:
+
+```bash
+npm install -g @agentsoc/beacon
+```

package/dist/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { loadConfig, saveConfig } from "./config.js";
+import { runBeacon } from "./run-beacon.js";
+import { installService } from "./service-install.js";
+const program = new Command();
+program
+    .name("beacon")
+    .description("AgentSOC Syslog Beacon - Lightweight background log forwarder")
+    .version("1.0.0", "-v, --version");
+program
+    .command("config")
+    .description("Configure the AgentSOC connection")
+    .option("-u, --url <url>", "AgentSOC ingest URL")
+    .option("-k, --key <key>", "AgentSOC API Key")
+    .action(async (options) => {
+    if (!options.url || !options.key) {
+        console.log("\n[beacon] Missing required options.\n");
+        console.log("Usage: beacon config --url <url> --key <key>\n");
+        console.log("Examples:");
+        console.log("  bun run src/cli.ts config -u https://api.agentsoc.com/ingest -k sk_1234567890abcdef");
+        console.log("  beacon config --url https://api.agentsoc.com/ingest --key sk_1234567890abcdef\n");
+        console.log("Options:");
+        console.log("  -u, --url <url>   AgentSOC ingest URL");
+        console.log("  -k, --key <key>   AgentSOC API Key\n");
+        process.exit(1);
+    }
+    await saveConfig({
+        ingestUrl: options.url,
+        apiKey: options.key,
+    });
+    console.log("[beacon] Config saved.");
+});
+program
+    .command("install")
+    .description("Install the background service daemon")
+    .action(async () => {
+    try {
+        await installService();
+    }
+    catch (err) {
+        console.error("[beacon] Install failed:", err);
+        process.exit(1);
+    }
+});
+program
+    .command("run")
+    .description("Run the forwarder daemon (foreground)")
+    .option("--batch-size <n>", "Batch size", "25")
+    .option("--flush-ms <n>", "Flush interval in ms", "2000")
+    .action(async (options) => {
+    const config = await loadConfig();
+    const apiKey = process.env.AGENTSOC_API_KEY || config.apiKey;
+    const ingestUrl = process.env.AGENTSOC_INGEST_URL || config.ingestUrl;
+    if (!apiKey || !ingestUrl) {
+        console.error("[beacon] Missing apiKey or ingestUrl. Run `beacon config` or set ENV vars.");
+        process.exit(1);
+    }
+    console.log("[beacon] Starting in foreground...");
+    const beacon = await runBeacon({
+        apiKey,
+        ingestUrl,
+        batchSize: parseInt(options.batchSize, 10),
+        flushMs: parseInt(options.flushMs, 10),
+    });
+    const stop = async () => {
+        console.log("\n[beacon] Stopping...");
+        await beacon.stop();
+        process.exit(0);
+    };
+    process.on("SIGINT", stop);
+    process.on("SIGTERM", stop);
+});
+program.parse(process.argv);

package/dist/config.js

@@ -0,0 +1,37 @@
+import os from "node:os";
+import path from "node:path";
+import fs from "node:fs/promises";
+export function getConfigDir() {
+    const home = os.homedir();
+    if (process.platform === "win32") {
+        return path.join(process.env.APPDATA || path.join(home, "AppData", "Roaming"), "agentsoc-beacon");
+    }
+    if (process.platform === "darwin") {
+        return path.join(home, "Library", "Application Support", "agentsoc-beacon");
+    }
+    const xdg = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+    return path.join(xdg, "agentsoc-beacon");
+}
+export function getConfigFile() {
+    return path.join(getConfigDir(), "config.json");
+}
+export async function loadConfig() {
+    try {
+        const file = getConfigFile();
+        const data = await fs.readFile(file, "utf8");
+        return JSON.parse(data);
+    }
+    catch (err) {
+        return {};
+    }
+}
+export async function saveConfig(config) {
+    const dir = getConfigDir();
+    try {
+        await fs.mkdir(dir, { recursive: true });
+        await fs.writeFile(getConfigFile(), JSON.stringify(config, null, 2), "utf8");
+    }
+    catch (err) {
+        console.error(`[syslog-beacon] Failed to save config to ${getConfigFile()}:`, err);
+    }
+}

package/dist/enrich.js

@@ -0,0 +1,32 @@
+import os from "node:os";
+import crypto from "node:crypto";
+import { loadConfig, saveConfig } from "./config.js";
+export async function getHostInfo() {
+    const config = await loadConfig();
+    let agentId = config.agentId;
+    if (!agentId) {
+        agentId = crypto.randomUUID();
+        config.agentId = agentId;
+        await saveConfig(config);
+    }
+    const hostname = os.hostname();
+    const osPlatform = os.platform();
+    let ip = "127.0.0.1";
+    let mac = "00:00:00:00:00:00";
+    const interfaces = os.networkInterfaces();
+    for (const name of Object.keys(interfaces)) {
+        const iface = interfaces[name];
+        if (!iface)
+            continue;
+        for (const info of iface) {
+            if (!info.internal && info.family === "IPv4") {
+                ip = info.address;
+                mac = info.mac;
+                break;
+            }
+        }
+        if (ip !== "127.0.0.1")
+            break;
+    }
+    return { agentId, hostname, ip, osPlatform, mac };
+}

package/dist/forwarder.js

@@ -0,0 +1,132 @@
+function parseSyslogPri(line) {
+    // Default mapping if line does not start with <PRI>
+    let severity = 5; // notice (maps to 'low' severity in our logic)
+    let facility = 1; // user-level messages
+    const match = line.match(/^<(\d+)>/);
+    if (match) {
+        const pri = parseInt(match[1], 10);
+        facility = Math.floor(pri / 8); // pri >> 3
+        severity = pri & 7; // pri % 8
+    }
+    else {
+        // If testing on macOS via log stream, the raw line might not contain <PRI>.
+        // Try to guess from keywords just for testing convenience:
+        const l = line.toLowerCase();
+        if (l.includes("critical") || l.includes("fatal") || l.includes("panic")) {
+            severity = 2; // crit
+        }
+        else if (l.includes("high") ||
+            l.includes("error") ||
+            l.includes("failed")) {
+            severity = 3; // err
+        }
+        else if (l.includes("medium") || l.includes("warn")) {
+            severity = 4; // warning
+        }
+        else if (l.includes("info")) {
+            severity = 6; // info
+        }
+        else if (l.includes("low") || l.includes("notice")) {
+            severity = 5; // notice
+        }
+    }
+    let severityStr = "info";
+    if (severity <= 2)
+        severityStr = "critical";
+    else if (severity === 3)
+        severityStr = "high";
+    else if (severity === 4)
+        severityStr = "medium";
+    else if (severity === 5)
+        severityStr = "low";
+    return { severityStr, facility };
+}
+function extractProcInfo(line) {
+    // Try to extract the program name from syslog format: hostname[pid]: message or hostname program: message
+    const match = line.match(/^\S+\s+(?:\S+\s+)?(\w+)(?:\[\d+\])?:\s*(.*)$/);
+    if (match) {
+        return { app: match[1], message: match[2] };
+    }
+    // Fall back to the whole line as message
+    return { message: line };
+}
+export class Forwarder {
+    opts;
+    buffer = [];
+    timer = null;
+    batchSize;
+    flushMs;
+    constructor(opts) {
+        this.opts = opts;
+        this.batchSize = opts.batchSize || 25;
+        this.flushMs = opts.flushMs || 2000;
+    }
+    pushLog(line) {
+        const { severityStr, facility } = parseSyslogPri(line);
+        const { app, message } = extractProcInfo(line);
+        // Build syslog event matching the ingest API schema
+        const event = {
+            full_log: message,
+            timestamp: new Date().toISOString(),
+            hostname: this.opts.host.hostname,
+            facility,
+            severity: severityStr,
+            id: `${this.opts.host.agentId}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+            agent: {
+                id: this.opts.host.agentId,
+                name: this.opts.host.hostname,
+                ip: this.opts.host.ip,
+                mac: this.opts.host.mac,
+            },
+        };
+        if (app) {
+            event.app = app;
+            event.process = {
+                name: app,
+            };
+        }
+        this.buffer.push(event);
+        if (this.buffer.length >= this.batchSize) {
+            this.flush();
+        }
+        else if (!this.timer) {
+            this.timer = setTimeout(() => this.flush(), this.flushMs);
+        }
+    }
+    async flush() {
+        if (this.timer) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.buffer.length === 0)
+            return;
+        const payload = this.buffer;
+        this.buffer = [];
+        console.log(`[syslog-beacon] Pushing ${payload.length} logs to API...`);
+        try {
+            const res = await fetch(this.opts.ingestUrl, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${this.opts.apiKey}`,
+                },
+                body: JSON.stringify(payload),
+            });
+            if (!res.ok) {
+                const text = await res.text();
+                console.error(`[syslog-beacon] Failed to push logs: HTTP ${res.status} ${text}`);
+            }
+            else {
+                console.log(`[syslog-beacon] Successfully pushed ${payload.length} logs`);
+            }
+        }
+        catch (err) {
+            console.error(`[syslog-beacon] Ingest error:`, err);
+        }
+    }
+    async stop() {
+        if (this.buffer.length > 0) {
+            await this.flush();
+        }
+    }
+}

package/dist/run-beacon.js

@@ -0,0 +1,17 @@
+import { getHostInfo } from './enrich.js';
+import { Forwarder } from './forwarder.js';
+import { SyslogSource } from './tail.js';
+export async function runBeacon(opts) {
+    const host = await getHostInfo();
+    const forwarder = new Forwarder({ ...opts, host });
+    const source = new SyslogSource((line) => {
+        forwarder.pushLog(line);
+    });
+    source.start();
+    return {
+        stop: async () => {
+            source.stop();
+            await forwarder.stop();
+        }
+    };
+}

package/dist/service-install.js

@@ -0,0 +1,67 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+import { loadConfig } from './config.js';
+export async function installService() {
+    const config = await loadConfig();
+    if (!config.apiKey || !config.ingestUrl) {
+        throw new Error('Config missing apiKey or ingestUrl. Please configure first.');
+    }
+    const isBun = process.execPath.endsWith('bun') || process.execPath.endsWith('bun.exe');
+    const runner = isBun ? process.execPath : 'node';
+    const cliPath = path.resolve(process.argv[1]);
+    const command = `${runner} ${cliPath} run`;
+    if (process.platform === 'linux') {
+        const serviceUnit = `[Unit]
+Description=AgentSOC Syslog Beacon
+After=network.target
+
+[Service]
+Type=simple
+ExecStart=${command}
+Restart=always
+RestartSec=10
+Environment=NODE_ENV=production
+
+[Install]
+WantedBy=multi-user.target
+`;
+        const dest = '/etc/systemd/system/syslog-beacon.service';
+        await fs.writeFile(dest, serviceUnit, 'utf8');
+        execSync('systemctl daemon-reload');
+        execSync('systemctl enable syslog-beacon');
+        execSync('systemctl start syslog-beacon');
+        console.log('[syslog-beacon] Installed systemd service');
+    }
+    else if (process.platform === 'darwin') {
+        const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.agentsoc.syslog-beacon</string>
+    <key>ProgramArguments</key>
+    <array>
+        <string>${runner}</string>
+        <string>${cliPath}</string>
+        <string>run</string>
+    </array>
+    <key>RunAtLoad</key>
+    <true/>
+    <key>KeepAlive</key>
+    <true/>
+</dict>
+</plist>
+`;
+        const dest = '/Library/LaunchDaemons/com.agentsoc.syslog-beacon.plist';
+        await fs.writeFile(dest, plist, 'utf8');
+        execSync(`launchctl load -w ${dest}`);
+        console.log('[syslog-beacon] Installed launchd service');
+    }
+    else if (process.platform === 'win32') {
+        console.log('[syslog-beacon] Windows service installation must be done via NSSM or WinSW. Skipping automatic install.');
+    }
+    else {
+        throw new Error(`Platform ${process.platform} is not supported for automatic service installation.`);
+    }
+}

package/dist/tail.js

@@ -0,0 +1,71 @@
+import { spawn } from "node:child_process";
+import dgram from "node:dgram";
+export class SyslogSource {
+    onLog;
+    tailProc;
+    udpServer;
+    constructor(onLog) {
+        this.onLog = onLog;
+    }
+    start() {
+        if (process.platform === "linux") {
+            this.tailProc = spawn("tail", [
+                "-F",
+                "/var/log/syslog",
+                "/var/log/auth.log",
+            ]);
+            this.tailProc.stdout?.on("data", (data) => {
+                const lines = data.toString().split("\n");
+                for (const line of lines) {
+                    if (line.trim())
+                        this.onLog(line);
+                }
+            });
+            this.tailProc.stderr?.on("data", (data) => {
+                console.error(`[syslog-tail] ${data.toString()}`);
+            });
+        }
+        else if (process.platform === "darwin") {
+            this.tailProc = spawn("log", [
+                "stream",
+                "--predicate",
+                'process == "sshd" or process == "sudo" or process == "login" or process == "logger"',
+                "--style",
+                "syslog",
+            ]);
+            console.log("[syslog-tail] macOS log stream started");
+            this.tailProc.stdout?.on("data", (data) => {
+                const lines = data.toString().split("\n");
+                for (const line of lines) {
+                    if (line.trim())
+                        this.onLog(line);
+                }
+            });
+            this.tailProc.stderr?.on("data", (data) => {
+                console.error(`[syslog-tail] ${data.toString()}`);
+            });
+        }
+        else {
+            // Windows or other - start a UDP server
+            this.udpServer = dgram.createSocket("udp4");
+            this.udpServer.on("message", (msg) => {
+                this.onLog(msg.toString("utf8").trim());
+            });
+            this.udpServer.on("error", (err) => {
+                console.error(`[syslog-udp] error:\n${err.stack}`);
+                this.udpServer?.close();
+            });
+            this.udpServer.bind(5140, () => {
+                console.log("[syslog-udp] listening on UDP 5140");
+            });
+        }
+    }
+    stop() {
+        if (this.tailProc) {
+            this.tailProc.kill();
+        }
+        if (this.udpServer) {
+            this.udpServer.close();
+        }
+    }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@agentsoc/beacon",
+  "version": "0.0.1",
+  "description": "Lightweight, background-running log forwarder (beacon) for AgentSOC",
+  "type": "module",
+  "bin": {
+    "beacon": "./dist/cli.js",
+    "syslog-beacon": "./dist/cli.js"
+  },
+  "main": "./dist/cli.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "bun run --cwd ../../.. bun build --target bun --entry-points ./apps/connectors/syslog-beacon-cli/src/cli.ts --outdir ./apps/connectors/syslog-beacon-cli/dist --minify",
+    "build:simple": "tsc",
+    "start": "bun run src/cli.ts run",
+    "install-service": "bun run src/cli.ts install"
+  },
+  "dependencies": {
+    "commander": "^11.1.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.6.0"
+  }
+}