Scan Local Accounts

Overview

This guide configures Britive to enumerate local accounts and groups on a standalone VMware ESXi host. The scan writes a Britive Resource Manager scan report so Britive’s identity inventory stays current — the report surfaces local users, their shellAccess flag, and any local groups.

The scan is read-only. It works on free / unlicensed ESXi hosts too — the vSphere SOAP API allows reads after the 60-day evaluation window expires.

Reference script: britive/access-broker-examples/VMware/ESXi/scans/scan-esxi-users.py.

Before You Begin

ESXi service account configured (see Getting Started → Configure the ESXi Host). The service account needs read access at minimum — the existing Administrator role is sufficient.
Broker pool with outbound TCP 443 to the host.

How It Works

    sequenceDiagram
    participant Britive
    participant Broker
    participant ESXi as ESXi Host

    Britive->>Broker: Trigger scan (schedule or on-demand)
    Broker->>Broker: Run scan-esxi-users.py
    Broker->>ESXi: Login on ha-sessionmgr (service account)
    Broker->>ESXi: RetrieveUserGroups on ha-user-directory (findUsers=true)
    Broker->>ESXi: RetrieveUserGroups on ha-user-directory (findGroups=true)
    Broker->>ESXi: Logout
    Broker->>Broker: Write JSON output to $BROKER_INJECTED_SCAN_OUTPUT_PATH
    Broker-->>Britive: Return report
    Britive->>Britive: Ingest report into identity inventory

Environment Variables

Variable	Required	Description
`ESXI_HOST`	Yes	IP or hostname of the target ESXi host
`ESXI_SVC_USER`	Yes	Service account on the host
`ESXI_SVC_PASSWORD`	Yes	Service account secret (sensitive)
`BROKER_INJECTED_SCAN_OUTPUT_PATH`	Auto	Output file path — auto-injected by Britive at scan time
`ESXI_VERIFY_TLS`	No	`true` to verify TLS (default `false`)

Output Format

The script writes a JSON document with the shape Britive’s Resource Manager expects:

{
  "data": {
    "identities": [
      {"principal": "root", "fullName": "Administrator", "id": "0", "shellAccess": true}
    ],
    "groups": [
      {"principal": "root", "id": "0"}
    ],
    "permissions": [],
    "permission_mapping": []
  },
  "metadata": {
    "resource_id": "<ESXI_HOST>",
    "resource_type": "ESXi",
    "scan_errors": []
  }
}

permissions and permission_mapping are intentionally empty — those are defined on the resource type, not derived from scan output. On any SOAP failure the script writes an empty data document with the fault recorded in metadata.scan_errors and exits 1.

Register the Scan Script

In the Britive console: Resource Manager → Resource Types → ESXi → Scans.

Upload the script

Upload or reference scan-esxi-users.py on the broker host.

Map variables

Map ESXI_HOST, ESXI_SVC_USER, ESXI_SVC_PASSWORD to the resource parameters. BROKER_INJECTED_SCAN_OUTPUT_PATH is set automatically by Britive at scan time.

Set the schedule

Set a scan schedule (e.g. daily) or trigger ad-hoc from the resource page.

Verify

Trigger a scan

In the console: Resource Manager → Resources → <esxi-host> → Scan Now.

Confirm the inventory updates

Open Identity → Identity Inventory in Britive and filter for the ESXi resource. You should see the host’s local accounts listed within a minute of the scan completing.

Compare against the host

Sign in to the host as root and go to Manage → Security & users → Users. The list of accounts on the host should match what Britive shows.

Troubleshoot

Symptom	Cause	Fix
Scan exits `1` with `scan_errors` populated	Network unreachable, bad credentials, or TLS handshake failure	Confirm the broker can reach `https://<esxi-host>/sdk`; verify the service account credentials manually
Scan succeeds but Britive shows no identities	Output not written to `BROKER_INJECTED_SCAN_OUTPUT_PATH`	Confirm the broker has filesystem write access to the injected path; check broker logs
Local groups missing from inventory	The host has no local groups beyond `root`	Expected — ESXi rarely has local groups other than the built-in ones
TLS handshake failure	Host uses self-signed cert and `ESXI_VERIFY_TLS=true`	Either install a trusted cert or leave `ESXI_VERIFY_TLS=false` (default)

Next Steps

Getting Started — JIT temp local admin pattern
Rotate Local Accounts — rotate secrets on existing local accounts

Last updated on July 8, 2026

Rotate Local Accounts