Endpoint Sensor

Beta

The Endpoint Sensor is currently in beta. The API endpoints and configuration format may change in future releases.

The OrbisID Endpoint Sensor is a lightweight Java application deployed natively on Windows servers. It subscribes to Windows Event Log channels, filters for security-relevant events, and forwards them to OrbisID in real time. This data feeds the Threat Detections engine.

Requires Enterprise edition.

Architecture

The sensor communicates outbound-only over HTTPS. No inbound ports are required on the monitored host.

Prerequisites

• Windows Server 2016 or later
• Java 17+ installed on the monitored host
• HTTPS network access from the monitored host to the OrbisID server (port 443 or your configured port)
• The sensor must run natively on the Windows host — Docker and remote collection are not supported

Java version requirement

The sensor requires Java 17+. Run java -version to check. If the version is below 17, download Java 17 LTS from Adoptium.

Enrollment

Self-Enrollment (Recommended)

Self-enrollment automatically provisions the sensor's API key without manual steps in the OrbisID UI.

1. In OrbisID, go to Alerts → Endpoint Sensors → Deployment Guide tab
2. Click Generate Enrollment Token (Administrator only) — the token is valid for 24 hours
3. Download the sensor JAR (orbisid-monitor-agent.jar) and the launcher script (launch-orbisid-monitor-agent.bat) to the target machine
4. Create config.properties in the same directory as the JAR:

config.properties

orbisid.api.url=https://your-orbisid-host
orbisid.enrollment.token=<enrollment-token-from-step-2>
orbisid.agent.name=MYSERVER-sensor

5. Run the launcher:

launch-orbisid-monitor-agent.bat

On first run the sensor registers itself, receives a permanent API key, writes it to config.properties, and begins forwarding events.

Manual Registration

1. In OrbisID, navigate to Alerts → Endpoint Sensors
2. Click Register Sensor
3. Enter a Sensor Name and optionally link a Target System
4. Copy the generated API key — it is shown only once
5. Create config.properties:

config.properties

orbisid.api.url=https://your-orbisid-host
orbisid.api.key=<your-api-key>
orbisid.agent.name=MYSERVER-sensor

6. Run the sensor:

java -jar orbisid-monitor-agent.jar

Running as a Windows Service

Use NSSM (Non-Sucking Service Manager) to run the sensor as a Windows service:

nssm install OrbisIDSensor "C:\Program Files\Eclipse Adoptium\jdk-17...\bin\java.exe"
nssm set OrbisIDSensor AppParameters "-jar C:\OrbisID\orbisid-monitor-agent.jar"
nssm set OrbisIDSensor AppDirectory "C:\OrbisID"
nssm set OrbisIDSensor Start SERVICE_AUTO_START
nssm start OrbisIDSensor

Download NSSM from nssm.cc. The service starts automatically on boot and restarts on failure.

Configuration Reference

Property	Required	Default	Description
orbisid.api.url	Yes	—	Full URL of the OrbisID server (e.g., https://orbisid.example.com)
orbisid.api.key	Yes*	—	API key for authentication (*not required if using enrollment token)
orbisid.enrollment.token	Yes*	—	One-time enrollment token (*only used on first run; replaced by API key)
orbisid.agent.name	No	hostname	Display name shown in the OrbisID Endpoint Sensors table

Windows Audit Policy Requirements

Windows does not log user account, group membership, or file share events by default. Enable the required audit subcategories on each monitored host from an elevated command prompt:

auditpol /set /subcategory:"User Account Management" /success:enable /failure:enable
auditpol /set /subcategory:"Security Group Management" /success:enable /failure:enable
auditpol /set /subcategory:"File Share" /success:enable /failure:enable

Verify the settings:

auditpol /get /subcategory:"User Account Management"

Group Policy (domain environments)

Apply these via GPO under Computer Configuration → Windows Settings → Security Settings → Advanced Audit Policy Configuration → Audit Policies.

API Endpoints

All sensor API endpoints require authentication via the X-Api-Key header.

POST /api/v1/monitor-agents/enroll

Self-enrollment. Called once on first run.

Headers:

X-Enrollment-Token: <enrollment-token>

Request body:

{
  "name": "MYSERVER-sensor",
  "hostname": "MYSERVER",
  "ipAddress": "192.168.1.50",
  "osVersion": "Windows Server 2022"
}

Response:

{
  "agentId": "uuid",
  "apiKey": "orbis_...",
  "message": "Enrolled successfully"
}

POST /api/v1/monitor-agents/heartbeat

Periodic health update sent every 15 seconds.

Headers:

X-Api-Key: <api-key>

Request body:

{
  "agentId": "uuid",
  "eventsPerMinute": 12,
  "status": "ONLINE"
}

POST /api/v1/monitor-agents/events

Batch event submission. Sent every 30 seconds or when 500 events have accumulated.

Headers:

X-Api-Key: <api-key>

Request body:

{
  "agentId": "uuid",
  "events": [
    {
      "eventId": 4720,
      "channel": "Security",
      "timestamp": "2025-03-01T14:23:00Z",
      "subjectUsername": "admin",
      "targetUsername": "newuser",
      "workstation": "DC01",
      "rawXml": "<Event>...</Event>"
    }
  ]
}

Collected Events

The sensor collects the following Windows Event IDs:

Event ID	Channel	Description
4648	Security	Logon with explicit credentials
4670	Security	Object permissions changed
4672	Security	Special privileges assigned to new logon
4688	Security	Admin process launched (cmd, powershell, regedit, sc.exe)
4697	Security	Service installed
4698	Security	Scheduled task created
4719	Security	Audit policy modified
4720	Security	User account created
4722	Security	Account re-enabled
4724	Security	Password reset attempt
4726	Security	User account deleted
4728 / 4732 / 4756	Security	Member added to privileged group
4738	Security	User account attributes changed
4740	Security	Account locked out
4781	Security	Account name changed
4104	PowerShell/Operational	Script block executed
5142 / 5143 / 5144	Security	Network share created / modified / deleted
5857 / 5861	WMI-Activity/Operational	WMI persistence activity
7045	System	New service registered

Raw event data is retained for 90 days via automatic partition management.

Troubleshooting

Symptom	Likely Cause	Resolution
UnsupportedClassVersionError on startup	Java version below 17	Install Java 17 LTS
Sensor shows Offline in OrbisID	Network issue or process stopped	Check service status and HTTPS connectivity to OrbisID
Events/min = 0	No events being collected	Verify Windows Event Log service is running and sensor account has read access to the Security log
No user / group / share detections	Windows audit policies disabled	Run the auditpol /set commands above; check sensor startup log for AUDIT POLICY DISABLED warnings
Sensor not appearing in table	Enrollment token expired or API key rejected	Check sensor logs for HTTP 401/403; generate a new enrollment token
Degraded status	Elevated error rate	Check sensor logs for parsing errors