Skip to main content

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.

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
  • You have Windows systems to scan — Windows scanning always requires an agent (see Windows Scanning below); this is the one case where an agent isn't optional
  • 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 — required if you need to scan Windows systems)
Scanning Windows systems specifically

Only the Windows Installer (below) bundles the Windows scan helper needed to scan WINDOWS-type systems. The Docker image and manual JAR deployments (Linux or Windows) can scan Active Directory, Linux, SQL Server, and other non-Windows types, but not Windows targets. See Windows Scanning for details.

  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:
# 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

The Windows Installer is the only deployment option that bundles the Windows scan helper — use this if you need to scan WINDOWS-type systems.

  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), including the bundled orbisid-windows-scanner.exe helper used for WinRM/PowerShell Remoting

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

Option C: JAR (Windows, manual)​

Use this only for non-Windows scanning (Active Directory, Linux, SQL Server, etc.) from a Windows host — it does not include the Windows scan helper, so WINDOWS-type systems assigned to an agent deployed this way will fail with an actionable error. Use Option B if you need 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\
  1. 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
  1. 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​

SettingDefaultDescription
server.urlrequiredFull URL of the OrbisID server (e.g., https://orbisid.example.com)
server.agent-keyrequiredAgent authentication key (generated in OrbisID admin)
poll.interval30How often (in seconds) the agent checks for new jobs
agent.namehostnameDescriptive name displayed in the OrbisID admin UI
logging.levelINFOLog verbosity. Use DEBUG for troubleshooting.
scan.timeout3600Maximum 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.

Three exceptions are not agent-routable:

  • Microsoft Entra ID (formerly Azure AD) — scans directly from the OrbisID server only
  • CSV — the Manual Upload source mode reads a file already stored on the OrbisID server, so it cannot run on a remote agent (the Network Share source mode is unaffected if the agent can reach that share)
  • CSV PAM — always reads from the OrbisID server's local filesystem

Assigning an Agent Group to any of these three will fail with an "Unsupported OS type" error; leave them unassigned so they scan directly from the OrbisID server.

Windows Scanning​

Windows scanning connects via WinRM (PowerShell Remoting) using a bundled helper (orbisid-windows-scanner.exe) rather than a Java client, so it can keep pace with changes to Windows' own remoting stack. Because it uses Windows' real, native WinRM client (the same one Invoke-Command/New-PSSession use), it's also subject to that client's normal trust policies — unlike the previous Java implementation, which bypassed them. This makes Windows scanning agent-only, with four requirements beyond a normal agent deployment:

  1. The agent must be installed on Windows via the Windows Installer. Docker and manual JAR deployments (Linux or Windows) do not include the helper.
  2. Target hosts must have PowerShell Remoting enabled, not just a bare WinRM listener. From an elevated PowerShell prompt on each target:
Enable-PSRemoting -Force

winrm quickconfig alone is not sufficient — Enable-PSRemoting also registers the PowerShell remoting endpoint the helper connects to.

  1. Non-domain (workgroup) targets must be trusted by the agent host if connecting over plain HTTP (port 5985). Windows only allows Negotiate/NTLM authentication to a non-domain-joined computer when that computer is listed in the WinRM client's TrustedHosts, or when Kerberos applies (both machines domain-joined). This commonly affects cloud VMs with auto-generated hostnames (e.g. AWS EC2's EC2AMAZ-... default names). From an elevated PowerShell prompt on the agent host (not the target):
Set-Item WSMan:\localhost\Client\TrustedHosts -Value "EC2AMAZ-XXXXXXX" -Concatenate -Force
Restart-Service WinRM

Use -Value "*" instead of a specific hostname to trust all targets from this agent (simpler, but trusts any host it connects to). Alternatively, configure a WinRM HTTPS listener on the target and use port 5986 — non-domain credentials over HTTPS use Basic authentication in this tool, which doesn't go through the native NTLM/TrustedHosts path at all, and is the more secure option regardless.

A failed connection due to this will surface Windows' own WinRM error text (mentioning TrustedHosts and error code 0x8009030d) in the scan/test failure message.

  1. Non-built-in local admin accounts need UAC remote-restriction disabled on the target if connecting over plain HTTP 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 produces the same 0x8009030d/"A specified logon session does not exist" error as a missing TrustedHosts entry — even with correct credentials and TrustedHosts already configured. From an elevated PowerShell prompt on the target (not the agent host):
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.

Once all of the above are in place, assign the Windows system to an Agent Group containing the Windows-installed agent and scan as normal.

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​

FieldRequiredTypeDescription
usernameYesStringAccount username
displayNameNoStringFriendly display name
accountTypeNoStringHUMAN or NON_HUMAN
enabledNoBooleanWhether the account is active
groupsNoString[]Group memberships
lastLogonNoISO 8601Last login timestamp
attributesNoObjectAdditional key-value metadata

Script Modes​

ModeDescription
PathThe script already exists on the agent host at a specified path
UploadThe 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​

CodeMeaning
0Success - password returned on stdout
Non-zeroFailure - 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​

SymptomPossible CauseSolution
Agent shows "Offline"Agent not running or network issueCheck agent process, verify HTTPS connectivity to OrbisID
Jobs stay "Queued"No agent available for the system's groupAssign an agent to the system's group, or check agent status
Scan fails with connection errorAgent cannot reach target systemVerify network connectivity from agent host to target
Vault script returns empty passwordScript error or vault configurationCheck agent logs, test script manually on the agent host
Windows scan/test fails: "must be scanned via a Scan Agent"No Agent Group assigned to the systemAssign the system to an Agent Group containing a Windows-installed agent
Windows scan/test fails: "not running on Windows"The system's Agent Group only has Docker/Linux-JAR agentsAdd a Windows-installed agent (via the Windows Installer) to the group
Windows scan/test fails: "WinRM cannot process the request... 0x8009030d"Two possible causes: (1) non-domain target not in the agent host's WinRM TrustedHosts (common for cloud VMs, e.g. EC2AMAZ-... hostnames), or (2) a non-built-in local admin account hitting UAC remote-restriction filtering on the targetFix (1) on the agent host; fix (2) on the target — see Windows Scanning for both. If both are already correct, double-check the credential's password hasn't changed
Windows scan/test fails with another WinRM connection errorTarget does not have PowerShell Remoting enabledRun Enable-PSRemoting -Force on the target (see Windows Scanning)