rsyslog

If your Linux endpoints already send logs through rsyslog to an internal collector, Beacon can use the same path. One rsyslog file on each endpoint reads Beacon’s local event log and forwards every event to your collector over TCP. Your collector then passes the events on to your SIEM, such as Microsoft Sentinel, the way it handles your other logs. The endpoints need no connection to your SIEM and no extra agent. Your existing rsyslog forwarding is not changed.

Before you start

Linux endpoints running rsyslog 8, the default on Ubuntu, Debian, RHEL, Rocky, and Alma.
A collector that accepts syslog over TCP, and its hostname and port.

Beacon events can be up to 64 KB. UDP cannot carry messages that large, so this path uses TCP even if your other logs go over UDP.

1. Install Beacon on each endpoint

Run the block for your distribution. It downloads the latest package for the endpoint’s architecture, checks it against the published checksums, and installs it.

VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"; VERSION="${VERSION##*/v}"
PKG="beacon_${VERSION}_linux_$(dpkg --print-architecture).deb"
BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"
curl -fsSLO "${BASE}/${PKG}" && curl -fsSLO "${BASE}/checksums.txt"
grep "  ${PKG}$" checksums.txt | sha256sum --check - && sudo apt install "./${PKG}"

VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"; VERSION="${VERSION##*/v}"
case "$(uname -m)" in x86_64) ARCH=amd64 ;; aarch64) ARCH=arm64 ;; esac
PKG="beacon_${VERSION}_linux_${ARCH}.rpm"
BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"
curl -fsSLO "${BASE}/${PKG}" && curl -fsSLO "${BASE}/checksums.txt"
grep "  ${PKG}$" checksums.txt | sha256sum --check - && sudo dnf install "./${PKG}"

Check it:

beacon endpoint status --system

running=true and telemetry=enabled mean Beacon is recording. It writes one JSON object per line to /var/log/beacon-agent/runtime.jsonl. See Linux install for what the package sets up.

2. Configure the collector

The collector has to accept syslog over TCP and messages up to 128 KB. If it is rsyslog, add this to its configuration and restart it:

/etc/rsyslog.d/10-beacon-input.conf on the collector

# Accept syslog over TCP, with messages up to 128 KB.
global(maxMessageSize="128k")
module(load="imtcp")
input(type="imtcp" port="514")

If your collector already has a TCP input, keep it and raise its maximum message size to 128 KB. For a collector that is not rsyslog, set the equivalent: a TCP syslog input with newline-separated messages and a maximum message size of at least 128 KB. A smaller limit cuts large events off, and a cut-off event is no longer valid JSON.

3. Add the forwarding file to each endpoint

Save this as /etc/rsyslog.d/60-beacon.conf, replacing collector.example.internal and 514 with your collector’s hostname and TCP port:

/etc/rsyslog.d/60-beacon.conf

# /etc/rsyslog.d/60-beacon.conf
# Forwards Beacon endpoint events to your collector over TCP.

# Beacon events can be up to 64 KB. rsyslog's default limit is 8 KB.
global(maxMessageSize="128k")

module(load="imfile")

input(type="imfile"
      File="/var/log/beacon-agent/runtime.jsonl"
      Tag="beacon:"
      Ruleset="beacon")

ruleset(name="beacon") {
  action(type="omfwd"
         Target="collector.example.internal"
         Port="514"
         Protocol="tcp"
         queue.type="LinkedList"
         queue.filename="beacon-forward"
         queue.maxDiskSpace="1g"
         queue.saveOnShutdown="on"
         action.resumeRetryCount="-1"
         action.resumeInterval="10")
}

This file:

Reads Beacon’s log and keeps up with it when Beacon rotates it.
Sends only Beacon’s events, each tagged beacon, over their own TCP connection. They do not go to /var/log/syslog or to your existing forwarding.
Queues events on disk, up to 1 GB, while the collector is unreachable, and sends them when it comes back.

Check the configuration, then restart rsyslog:

sudo rsyslogd -N1
sudo systemctl restart rsyslog

rsyslogd -N1 should end with End of config validation run and print no errors. If it reports one of these, your rsyslog configuration already has the setting:

Error	Fix
`module 'imfile' already in this config`	Delete the `module(load="imfile")` line from `60-beacon.conf`.
`parameter 'maxmessagesize' specified more than once`	Delete the `global(...)` line from `60-beacon.conf` and raise your existing setting to `128k`. rsyslog keeps the first value it reads, so leaving the smaller one in place cuts large events off.

Deploy with Salt

The file is the same on every endpoint, so Salt only needs to place it and restart rsyslog when it changes:

beacon/rsyslog.sls

beacon-rsyslog-forwarding:
  file.managed:
    - name: /etc/rsyslog.d/60-beacon.conf
    - source: salt://beacon/60-beacon.conf
    - user: root
    - group: root
    - mode: '0644'

rsyslog:
  service.running:
    - enable: True
    - watch:
      - file: beacon-rsyslog-forwarding

4. Confirm events arrive

On an endpoint, write a test event:

sudo beacon endpoint test-event --system

Within a few seconds your collector receives a message tagged beacon. Its body is one JSON event whose message field is Beacon endpoint pipeline validation event. Search your collector or SIEM for that text. The first time rsyslog starts with this file, it also sends the events already in the log. After that it sends only new ones.

What gets sent

Each message is one Beacon event, unchanged, as a single line of JSON. Events can include prompt text, commands the agent ran, file paths, and tool input, after Beacon’s redaction and its 64 KB per-event limit. See Retention and redaction to control what Beacon keeps, and the event schema for the fields. rsyslog sends the events with facility local0 and severity notice. To change them, add Facility="..." and Severity="..." to the input(...) block.

If events do not arrive

Run sudo rsyslogd -N1 again and fix any error it prints.
Check sudo journalctl -u rsyslog for connection errors, and that the endpoint can reach the collector’s TCP port.
On RHEL-family endpoints with SELinux enforcing, rsyslog may be denied the collector’s port. If the audit log shows a denial, allow the port with sudo semanage port -a -t syslogd_port_t -p tcp <port>.
If large events arrive cut off, raise the collector’s maximum message size to 128 KB.

Linux install

What the package installs and how the service runs.

Microsoft Sentinel

Build Sentinel tables and queries for Beacon events.

Get Started

Deploy Asymptote

How Asymptote Works

Manage Asymptote

Agent Harness Integrations

For Security & IT Teams

Support

Contributing

Before you start

1. Install Beacon on each endpoint

2. Configure the collector

3. Add the forwarding file to each endpoint

Deploy with Salt

4. Confirm events arrive

What gets sent

If events do not arrive

Linux install

Microsoft Sentinel

​Before you start

​1. Install Beacon on each endpoint

​2. Configure the collector

​3. Add the forwarding file to each endpoint

​Deploy with Salt

​4. Confirm events arrive

​What gets sent

​If events do not arrive

​Related

Linux install

Microsoft Sentinel

Before you start

1. Install Beacon on each endpoint

2. Configure the collector

3. Add the forwarding file to each endpoint

Deploy with Salt

4. Confirm events arrive

What gets sent

If events do not arrive

Related