Custom Script

Description

The Custom Script connector executes a user-provided script on an On-Premise Agent to scan any system type that OrbisID does not natively support. The script receives connection details as JSON on stdin and must output discovered accounts as JSON on stdout.

This connector enables scanning of custom applications, cloud platforms, SaaS APIs, mainframes, or any other target where you can write code to enumerate accounts.

System Type Classification

The System Type is user-selectable for Custom Script systems. Choose the classification that best describes the target system:

Classification	Use When
Server	Target is a server OS
Infrastructure	Target is a database or platform
Application	Target is a business application
Directory Service	Target is an identity store

Version Support

OrbisID Edition	Supported
Community	No
Pro	No
Enterprise	Yes

Custom Script scanning requires the Enterprise edition.

How It Works

1. OrbisID creates a scan job and dispatches it to an On-Premise Agent
2. The agent writes a JSON payload with connection details to the script's stdin
3. The script executes and returns discovered accounts as JSON on stdout
4. The agent submits the results to OrbisID

The script runs on the On-Premise Agent host, not on the OrbisID server.

Script Modes

Mode	Description
Path	The script already exists on the On-Premise Agent host at a specified path
Upload	The script is uploaded to OrbisID and pushed to the agent at scan time

Script Interface

Input (stdin)

The script receives a JSON object:

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

parameters are the key-value pairs configured on the target system in OrbisID.

Output (stdout)

The script must write a JSON object:

{
  "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 or login name
displayName	No	String	Friendly name
accountType	No	String	HUMAN or NON_HUMAN
enabled	No	Boolean	Whether the account is active
groups	No	String[]	Group or role memberships
lastLogon	No	ISO 8601	Last login timestamp
attributes	No	Object	Additional key-value metadata

Connection Testing

When Test Connection is run in OrbisID, the agent executes the script with a --test argument appended to the command. The script should perform a lightweight connectivity check and exit with:

• Code 0 — success
• Non-zero — failure (error message on stderr)

Connection Requirements

On-Premise Agent Required

Custom Script systems must use an On-Premise Agent. The OrbisID server does not execute scripts directly.

1. Deploy and configure an On-Premise Agent
2. Assign the agent (or agent group) to the target system
3. Place the script on the agent host (Path mode) or upload it via OrbisID (Upload mode)

Script Runtime Requirements

The script runtime (Python, Node.js, Bash, PowerShell, etc.) must be installed on the On-Premise Agent host.

Network Requirements

The On-Premise Agent must have network access to the target system on whatever ports the script uses.

Configuration Steps

1. Navigate to Systems in the sidebar
2. Click Add System
3. Set OS Type to Custom Script
4. Fill in the fields:

Field	Value
Name	Descriptive name (e.g., aws-iam-accounts)
Hostname / IP	Hostname passed to the script as hostname in the JSON input
Port	Port passed to the script as port
System Type	Choose the appropriate classification
Script Mode	Path or Upload
Script Path	(Path mode) Full path to the script on the agent host
Parameters	Key-value pairs passed to the script as parameters
Credential	The credential whose username/password are passed to the script

5. For Upload mode, click Upload Script and select your script file
6. Click Test Connection — the agent runs the script with --test
7. Click Save

Example Script

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

The example demonstrates:

1. Reading connection details from stdin
2. Handling the --test flag
3. Connecting to a hypothetical target system
4. Enumerating accounts
5. Writing the result JSON to stdout

See On-Premise Agent — Custom Scripts for the full script specification.

Troubleshooting

Symptom	Likely Cause	Resolution
Scan fails: "Requires Scan Agent"	No On-Premise Agent assigned	Assign an agent or agent group to the system
Connection test fails: non-zero exit	Script connectivity error	Test the script manually on the agent host: echo '{"hostname":"..."}' | python3 script.py --test
No accounts returned	Script outputs empty accounts array or malformed JSON	Validate the JSON output format; check script logs
Script not found (Path mode)	Path incorrect or permissions wrong	Verify the script path on the agent host and ensure it is executable
Upload not available	Agent offline	Ensure the agent is online before uploading; scripts are pushed at scan time