On-Premise Agent

The OrbisID On-Premise Agent is an optional component that runs in network segments where target systems are not directly reachable from the OrbisID server. It polls the OrbisID API for scan jobs, executes them locally, and submits results back.

Requires a Commercial edition (Pro or Enterprise) — not available on Community.

When to Use a On-Premise Agent

Deploy a On-Premise Agent when:

• Target systems are in segmented networks not accessible from the OrbisID server — this includes Windows systems in a segment the OrbisID server can't reach; Windows scanning itself no longer requires an agent (see Windows Scanning below), but network segmentation is handled the same way as any other connector
• You are using Custom Script system types (Enterprise edition)
• You are using PAM Vault Script credentials that need to run locally
• Security policy requires scans to originate from within the target network
• The OrbisID server itself has restricted outbound internet access — cloud/SaaS connectors (AWS, Okta, Google Cloud Platform, etc.) can be routed through an agent that does have the required egress, rather than requiring direct internet access from the OrbisID server

Architecture

The agent communicates only with the OrbisID server (outbound HTTPS). It does not need to accept inbound connections.

Installation

Prerequisites

• Network access to target systems (LDAP/SSH/JDBC/WinRM ports/etc)
• HTTPS access to the OrbisID server
• One of:
  • Docker 24+ (for containerised deployment)
  • Java 17+ (for JAR deployment)
  • Windows Server 2019+ (for the Windows Installer)

Scanning Windows systems specifically

Every agent deployment option (Docker, JAR, or the Windows Installer) can dispatch a Windows scan — WinRM connectivity is built directly into the agent, no separate helper process is needed. See Windows Scanning for the one caveat: the agent process handling a Windows target must itself be running on Windows, which the Windows Installer and a Windows-hosted JAR satisfy but a Docker deployment (Linux container) does not.

Option A: Docker (Recommended)

1. In OrbisID, navigate to Administration > On-Premise Agents
2. Click Add Agent and note the agent key
3. Click Download Docker Image to get the agent image tar file
4. On the agent host:

Linux

# Load the Docker image
docker load -i orbisid-scan-agent.tar

# Create a config directory
mkdir -p /opt/orbisid-agent

# Create the configuration file (see Configuration below)
nano /opt/orbisid-agent/config.yml

# Run the agent
docker run -d \
  --name orbisid-agent \
  --restart unless-stopped \
  -v /opt/orbisid-agent/config.yml:/app/config.yml:ro \
  orbisid/scan-agent:latest

macOS

# Load the Docker image
docker load -i orbisid-scan-agent.tar

# Create a config directory
mkdir -p /opt/orbisid-agent

# Create the configuration file (see Configuration below)
nano /opt/orbisid-agent/config.yml

# Run the agent
docker run -d \
  --name orbisid-agent \
  --restart unless-stopped \
  -v /opt/orbisid-agent/config.yml:/app/config.yml:ro \
  orbisid/scan-agent:latest

Windows

# Load the Docker image
docker load -i orbisid-scan-agent.tar

# Create a config directory
New-Item -ItemType Directory -Force -Path C:\OrbisID\agent

# Create the configuration file (see Configuration below)
notepad C:\OrbisID\agent\config.yml

# Run the agent
docker run -d `
  --name orbisid-agent `
  --restart unless-stopped `
  -v C:\OrbisID\agent\config.yml:/app/config.yml:ro `
  orbisid/scan-agent:latest

Option B: Windows Installer

A convenience installer for running the agent as a native Windows service — useful if you'd rather not manage a JVM process or Docker container by hand, and gives you a Windows-hosted agent process for Windows Scanning without any extra setup.

1. In OrbisID, navigate to Administration > On-Premise Agents
2. Click Add Agent and note the agent key
3. Click Download Windows Installer to get OrbisID-Agent-Setup.exe
4. Run the installer on the agent host (Windows Server 2019+, admin privileges required)
5. On the Java Runtime page, either use the bundled JRE (default) or point to an existing Java 17+ install
6. On the Agent Configuration page, enter the OrbisID backend URL and the agent key from step 2
7. Finish the wizard — the installer registers and starts OrbisID On-Premise Agent as a Windows service (via WinSW)

The service can be managed like any other Windows service (services.msc, or sc query OrbisIDAgent).

Option C: JAR (Windows, manual)

Same agent, run manually as a JVM process on Windows instead of through the installer's service wrapper. Like Option B, an agent running this way can also handle Windows-type systems — see Windows Scanning.

1. In OrbisID, navigate to Administration > On-Premise Agents
2. Click Add Agent and note the agent key
3. Click Download JAR to get the agent JAR file
4. On the agent host, ensure Java 17+ is installed (java -version)
5. Create a directory and copy the JAR:

mkdir C:\OrbisID\agent
copy orbisid-agent.jar C:\OrbisID\agent\

6. Create the configuration file:

C:\OrbisID\agent\config.yml

server:
  url: https://your-orbisid-host
  agent-key: <your-agent-key>

poll:
  interval: 30

agent:
  name: agent-corp-01

logging:
  level: INFO

scan:
  timeout: 3600

7. Run the agent:

java -jar C:\OrbisID\agent\orbisid-agent.jar --config C:\OrbisID\agent\config.yml

For production, install it as a Windows Service using NSSM (Non-Sucking Service Manager):

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

Download NSSM from nssm.cc. After installation, the agent starts automatically on boot and restarts on failure.

Option D: JAR (Linux)

1. In OrbisID, navigate to Administration > On-Premise Agents
2. Click Add Agent and note the agent key
3. Click Download JAR to get the agent JAR file
4. On the agent host:

# Create a directory for the agent
mkdir -p /opt/orbisid-agent
cp orbisid-agent.jar /opt/orbisid-agent/

# Create the configuration file
nano /opt/orbisid-agent/config.yml

# Run the agent
java -jar /opt/orbisid-agent/orbisid-agent.jar \
  --config /opt/orbisid-agent/config.yml

For production, create a systemd service:

/etc/systemd/system/orbisid-agent.service

[Unit]
Description=OrbisID On-Premise Agent
After=network.target

[Service]
Type=simple
User=orbisid
WorkingDirectory=/opt/orbisid-agent
ExecStart=/usr/bin/java -jar orbisid-agent.jar --config config.yml
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Configuration

The agent is configured via a config.yml file:

config.yml

# OrbisID server connection
server:
  url: https://your-orbisid-host
  agent-key: <your-agent-key>

# Polling behaviour
poll:
  interval: 30        # Seconds between job polls

# Agent identification
agent:
  name: agent-dmz-01  # Descriptive name for this agent

# Logging
logging:
  level: INFO          # DEBUG, INFO, WARN, ERROR

# Scan execution
scan:
  timeout: 3600        # Maximum scan duration in seconds (default: 1 hour)

Configuration Reference

Setting	Default	Description
server.url	required	Full URL of the OrbisID server (e.g., https://orbisid.example.com)
server.agent-key	required	Agent authentication key (generated in OrbisID admin)
poll.interval	30	How often (in seconds) the agent checks for new jobs
agent.name	hostname	Descriptive name displayed in the OrbisID admin UI
logging.level	INFO	Log verbosity. Use DEBUG for troubleshooting.
scan.timeout	3600	Maximum time (in seconds) a single scan can run before being killed

Agent Groups

Agent groups let you organise agents by network segment and assign systems to groups. When a scan job is created for a system, it is dispatched to an agent in the system's assigned group.

1. In OrbisID, navigate to Administration > On-Premise Agents
2. Create a group (e.g., "DMZ Agents")
3. Add agents to the group
4. Assign systems to the group

Systems not assigned to any group are scanned by the OrbisID server directly (if reachable) or by any available agent — except WINDOWS-type systems, which must be assigned to a group with at least one Windows-installed agent. Windows scanning cannot fall back to direct scanning by the OrbisID server.

Connector Support via Agent

Assigning an Agent Group to a system routes both its scans and its Test Connection checks through that agent instead of the OrbisID server. This works for almost every connector type — directory/network connectors (Active Directory, Linux, Windows, LDAP, SQL Server, Oracle, MySQL/MariaDB, PostgreSQL, network devices, etc.) as well as cloud/REST connectors (AWS, Azure-adjacent SaaS platforms, Okta, HashiCorp Vault, PAM platforms, and the rest of the OSType catalogue).

Agent-routed Active Directory scans and connection tests fully honour the system's Port, Use LDAPS (SSL), Use StartTLS, Trust All TLS Certificates, and referral-handling settings — the agent uses the same connection logic as a direct scan from the OrbisID server, not a simplified fallback.

Two exceptions are not agent-routable:

• CSV in Manual Upload mode — the file is stored in the OrbisID server's own database, so it cannot run on a remote agent. CSV in Network Share mode is unaffected and runs via an assigned Agent Group like any other connector, provided the agent host can reach that share.
• CSV PAM — always reads from the OrbisID server's local filesystem

An Agent Group assigned to a Manual Upload CSV system or a CSV PAM system is silently ignored — both always run locally on the OrbisID server regardless of assignment.

Windows Scanning

Windows scanning connects via WinRM using winrm4j, a pure Java client — there is no external helper process or bundled executable involved, and no dependency on Windows' own native WinRM/PowerShell-Remoting client stack. This has two practical consequences that differ from older guidance you may have seen for this connector:

• No agent is required at all. The OrbisID server scans Windows systems directly, in-process, the same way it already does for Active Directory and Linux. Deploy an agent for a Windows system only for the same reasons you'd deploy one for any other connector — the target sits in a network segment the OrbisID server can't reach, or policy requires the scan to originate from within that network.
• If you do route a Windows scan through an agent, the agent process itself must be running on Windows — a plain Docker deployment (a Linux container) cannot dispatch a Windows scan, even though it can dispatch every other connector type. The Windows Installer and a JAR run directly on a Windows host (Option C) both work.

Because winrm4j talks WinRM directly rather than going through Windows' native client, Windows client-side settings like TrustedHosts are not involved and don't need to be configured anywhere, on either the OrbisID server or an agent host — this is a change from the old PowerShell-Remoting-based helper this connector used previously. What still applies, because it's enforced by the target, not the calling client:

1. The target host needs a WinRM listener enabled. From an elevated command prompt on the target:

winrm quickconfig

This is the same requirement described in the Windows connector's own Connection Requirements — nothing extra is needed for agent-routed scans versus a direct scan from the OrbisID server.

2. Non-built-in local admin accounts need UAC remote-restriction disabled on the target if connecting with a local (non-domain) account that isn't the literal built-in Administrator account (SID ending -500). Windows filters that account's token for network logons by default (UAC remote restrictions), which surfaces as an authentication failure (0x8009030d / "A specified logon session does not exist") even with correct credentials. From an elevated PowerShell prompt on the target:

New-ItemProperty -Path HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Policies\System `
  -Name LocalAccountTokenFilterPolicy -PropertyType DWord -Value 1 -Force

Not needed if the credential is the actual built-in Administrator account, which is already exempt from this restriction, or a domain account.

3. Self-signed certificates on a WinRM HTTPS listener (port 5986) are accepted automatically — certificate validation is intentionally disabled for this connector, since a local winrm quickconfig-style listener has no trusted chain by default. No certificate import is required on either side.

Windows Server 2025 specifically, WinRM-over-HTTPS with a real (CA-issued) certificate, and domain/Kerberos authentication are not yet verified against a live target — this connector has been confirmed end-to-end against Windows 11/Windows Server with a local account over plain HTTP.

To route a Windows system through an agent rather than scanning it directly, assign it to an Agent Group containing a Windows-hosted agent, same as any other connector.

Custom Scripts

Requires Enterprise edition.

Custom scripts allow you to scan any system type by providing your own script that OrbisID executes via the On-Premise Agent.

Script Interface

The script receives a JSON payload on stdin with connection details:

{
  "hostname": "target-host.example.com",
  "port": 443,
  "username": "service-account",
  "password": "decrypted-password",
  "parameters": {
    "custom_param_1": "value1",
    "custom_param_2": "value2"
  }
}

The script must output a JSON result on stdout:

{
  "success": true,
  "accounts": [
    {
      "username": "admin",
      "displayName": "Administrator",
      "accountType": "HUMAN",
      "enabled": true,
      "groups": ["Administrators", "Remote Desktop Users"],
      "lastLogon": "2025-01-10T14:30:00Z",
      "attributes": {
        "department": "IT",
        "custom_field": "value"
      }
    }
  ],
  "errorMessage": null
}

Account Fields

Field	Required	Type	Description
username	Yes	String	Account username
displayName	No	String	Friendly display name
accountType	No	String	HUMAN or NON_HUMAN
enabled	No	Boolean	Whether the account is active
groups	No	String[]	Group memberships
lastLogon	No	ISO 8601	Last login timestamp
attributes	No	Object	Additional key-value metadata

Script Modes

Mode	Description
Path	The script already exists on the agent host at a specified path
Upload	The script is uploaded to OrbisID and delivered to the agent at scan time

Connection Testing

When Test Connection is run for a Custom Script system, the agent executes the script with a --test flag appended to the command. The script should perform a lightweight connectivity check and exit with code 0 for success or non-zero for failure.

Example Script

An example Python script is available for download in OrbisID at Systems > Add System > Custom Script > Download Example Script.

The example demonstrates:

1. Reading JSON from stdin
2. Connecting to a target system
3. Discovering accounts
4. Outputting the result JSON on stdout
5. Handling the --test flag for connection tests

PAM Vault Scripts

PAM vault scripts run on the On-Premise Agent to retrieve the current password from a PAM vault at scan time, avoiding the need to store passwords in OrbisID.

Script Interface

The script receives a JSON payload on stdin:

{
  "accountId": "admin",
  "parameters": {
    "safe": "Linux-Root",
    "object": "Operating System-LinuxSSH-target01-root",
    "folder": "Root"
  }
}

The parameters are the key-value pairs configured on the credential in OrbisID.

The script must output only the password on stdout (no newline, no JSON wrapping).

Exit Codes

Code	Meaning
0	Success - password returned on stdout
Non-zero	Failure - error message on stderr

Example

#!/usr/bin/env python3
import sys
import json

data = json.loads(sys.stdin.read())

# Call your PAM vault API here
# Example: CyberArk CCP, BeyondTrust API, etc.
password = retrieve_from_vault(
    safe=data["parameters"]["safe"],
    object=data["parameters"]["object"]
)

sys.stdout.write(password)

Monitoring

Agent Status

In Administration > On-Premise Agents, each agent shows:

• Status - Online or Offline (based on heartbeat)
• Last Heartbeat - When the agent last checked in
• Current Job - What the agent is currently scanning (if anything)
• Version - Agent software version

Agent Logs

Agent logs can be viewed and downloaded from the administration UI. You can also adjust the log level remotely:

1. Navigate to Administration > On-Premise Agents
2. Select an agent
3. Change the log level (DEBUG, INFO, WARN, ERROR)
4. Download log files

Troubleshooting

Symptom	Possible Cause	Solution
Agent shows "Offline"	Agent not running or network issue	Check agent process, verify HTTPS connectivity to OrbisID
Jobs stay "Queued"	No agent available for the system's group	Assign an agent to the system's group, or check agent status
Scan fails with connection error	Agent cannot reach target system	Verify network connectivity from agent host to target
Vault script returns empty password	Script error or vault configuration	Check agent logs, test script manually on the agent host
Windows scan/test fails: "not running on Windows"	The system's Agent Group only has Docker agents	Add a Windows-installed agent (via the Windows Installer or Option C) to the group — a Docker (Linux container) agent cannot dispatch a Windows scan
Windows scan/test fails: "no response from host"	Target has no WinRM listener, or a firewall is blocking it	Run winrm quickconfig on the target; check firewall rules for port 5985/5986
Windows scan/test fails: "A specified logon session does not exist" / 0x8009030d	A non-built-in local admin account is being filtered by UAC remote restrictions on the target	Set LocalAccountTokenFilterPolicy on the target — see Windows Scanning