Scan Agent

The OrbisID Scan 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 Scan Agent

Deploy a Scan Agent when:

• Target systems are in segmented networks not accessible from the OrbisID server
• 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

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 ports)
• HTTPS access to the OrbisID server
• One of:
  • Docker 24+ (for containerised deployment)
  • Java 17+ (for JAR deployment)

Option A: Docker (Recommended)

1. In OrbisID, navigate to Administration > Scan 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

Option B: JAR

1. In OrbisID, navigate to Administration > Scan 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 Scan 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 > Scan 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.

Custom Scripts

Requires Enterprise edition.

Custom scripts allow you to scan any system type by providing your own script that OrbisID executes via the Scan 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 Scan 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 > Scan 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 > Scan 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