Endpoint Sensors
Endpoint Sensors are lightweight Java processes deployed on Windows servers that collect real-time Windows Event Log telemetry and forward it to OrbisID. This event data feeds the Threat Detections engine, which identifies accounts exhibiting anomalous privileged behaviour.
Navigating to Endpoint Sensors
Go to Alerts → Endpoint Sensors in the left navigation menu.
Sensor Status Overview
The three summary cards show the health of your sensor fleet at a glance:
| Card | Description |
|---|---|
| Online | Sensors actively sending heartbeats |
| Degraded | Sensors connected but reporting errors or reduced throughput |
| Offline | Sensors that have not sent a heartbeat recently |
Sensor Table
| Column | Description |
|---|---|
| Sensor Name | Unique name assigned when the sensor was registered |
| System | The OrbisID target system the sensor is deployed on |
| Status | Online / Degraded / Offline |
| Hostname | The hostname of the machine running the sensor |
| IP Address | The IP address of the sensor machine |
| Version | The deployed sensor version |
| Events/min | Current throughput of account events being forwarded |
| Last Heartbeat | Timestamp of the most recent heartbeat received |
Viewing Sensor Details
Click the eye icon to open a full detail dialog, which shows all fields including OS information and registration date.
Deploying an Endpoint Sensor
The sensor is a standalone Java application distributed as an executable JAR (orbisid-monitor-agent.jar) and a Windows batch launcher.
Prerequisites
- Java 17 or later on the target machine (Java 8–16 will fail with
UnsupportedClassVersionError) - Network access from the target machine to the OrbisID backend (HTTPS, port 443 or your configured port)
- The sensor must run natively on the Windows host — Docker containers and remote collection are not supported
The sensor JAR requires Java 17+. Run java -version before installation. If the version is below 17, download Java 17 LTS from Adoptium.
Enrollment (Recommended)
The simplest deployment path uses the self-enrollment flow, which provisions the API key automatically:
- In OrbisID, go to Alerts → Endpoint Sensors → Deployment Guide tab
- Click Generate Enrollment Token (Administrator only)
- Download the sensor JAR and launcher script to the target machine
- Create
config.propertiesin the same folder as the JAR:orbisid.api.url=https://your-orbisid-host
orbisid.enrollment.token=<token from step 2>
orbisid.agent.name=MYSERVER-sensor - Run the launcher to complete enrollment:
The sensor registers itself, receives an API key, and begins forwarding events.
launch-orbisid-monitor-agent.bat
Manual Registration
Alternatively, register the sensor in advance and supply the API key manually:
- Click Register Sensor in the Endpoint Sensors table
- Fill in a Sensor Name and optionally link a Target System
- Copy the generated API key — it is shown only once
- Create
config.properties:orbisid.api.url=https://your-orbisid-host
orbisid.api.key=<your-api-key>
orbisid.agent.name=MYSERVER-sensor - Run via the batch launcher or directly:
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 for automatic startup and restart:
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 start OrbisIDSensor
Enable Required Windows Audit Policies
Windows does not write user account, group membership, or file share events to the Security Event Log by default. Without these policies enabled, critical events such as user creation (4720), password resets (4724), group membership changes (4728 / 4732 / 4756), and network share activity (5142–5144) will never appear in the log — even with the sensor running.
Run the following commands from an elevated (Administrator) command prompt on each monitored host:
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
These settings take effect immediately and persist across reboots. Verify with:
auditpol /get /subcategory:"User Account Management"
In domain environments, apply these policies via GPO under Computer Configuration → Windows Settings → Security Settings → Advanced Audit Policy Configuration → Audit Policies.
The sensor startup log will warn if any of these policies are disabled (AUDIT POLICY DISABLED: ...). Check the sensor log if expected events are not appearing in Threat Detections.
What Events Are Collected?
The sensor subscribes to the Windows Security, System, PowerShell/Operational, and WMI-Activity/Operational event channels and forwards the following event IDs:
| Event ID | Channel | Detection |
|---|---|---|
| 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 |
| 4648 | Security | Logon with explicit credentials |
| 4670 | Security | Object permissions changed |
| 4781 | Security | Account name changed |
| 4104 | PowerShell | Script block executed |
| 5142 / 5143 / 5144 | Security | Network share created / modified / deleted |
| 5857 / 5861 | WMI-Activity | WMI persistence activity |
| 7045 | System | New service registered |
Raw event data is retained for 90 days via automatic partition management.
Sensor Communication
The sensor communicates outbound-only — no inbound ports need to be opened:
| Channel | Endpoint | Purpose |
|---|---|---|
| Heartbeat | POST /api/v1/monitor-agents/heartbeat | Periodic health update (every 15s) |
| Events | POST /api/v1/monitor-agents/events | Batch event submission (every 30s or 500 events) |
| Enrollment | POST /api/v1/monitor-agents/enroll | One-time self-registration using enrollment token |
All requests are authenticated with the API key provisioned during enrollment or manual registration.
Editing and Managing Sensors
| Action | How |
|---|---|
| Edit sensor name or system link | Click the pencil icon |
| Regenerate API key | Click the key icon (generates a new key; update config.properties and restart the service) |
| Delete sensor | Click the trash icon (Administrator only) |
Deleting a sensor does not delete the event data or Threat Detections already created. Detections retain their sensor association for audit purposes.
Relationship to Threat Detections
Events collected by Endpoint Sensors are analysed in real time by the Threat Detections engine. When an event matches a detection rule, a new Threat Detection is raised (or an existing open detection is updated). The ML confidence model uses confirmed and dismissed detections to continuously improve scoring for each account/rule combination.
Relationship to Gap Analysis
Active Endpoint Sensors count as evidence of real-time monitoring capability in the PAM Gap Analysis. Controls covering event logging and alerting (NIST AU-2, ISO A.8.15, SOx ITGC-OP-1) automatically reflect Endpoint Sensor deployment in their evidence summaries.
Troubleshooting
| Symptom | Likely Cause | Resolution |
|---|---|---|
UnsupportedClassVersionError on startup | Java version below 17 | Install Java 17 LTS and update NSSM AppBinaryPath |
| Sensor shows Offline | Network issue or process stopped | Check the service status and network connectivity |
| Events/min = 0 | Agent running but no events collected | Verify the Windows Event Log service is running and the sensor account has read access to the Security log |
| No user / group / share detections | Windows audit policies disabled | Run the auditpol /set commands in Enable Required Windows Audit Policies. Check sensor startup log for AUDIT POLICY DISABLED warnings |
| Sensor not appearing in table | Enrollment token invalid or API key rejected | Check sensor logs for HTTP 401/403; regenerate the enrollment token |
| Degraded status | Elevated error rate | Check sensor logs for parsing errors or high event volume |