Quick guide

XOAP Dispositifs are endpoints where the XOAP Connector is installed and enrolled into your workspace. Once connected, devices become visible in the Inventory module and can be used to run queries and commands, collect inventory data, and (if enabled during installation) participate in Image Management workflows.

Add a Device (Install XOAP Connector)

1. Aller à Inventory → Devices et cliquez sur + Add Device.
2. Dans le cadre de la Download the XOAP connector section, select the target platform (Windows / macOS / Linux) and click Télécharger.
3. En Enroll and start the XOAP connector, select the API key that should be used for enrollment.
4. Copy the generated installation command and run it on the target device:
   • Windows: Exécuter Windows PowerShell as Administrator
   • Linux/macOS: Run the command with appropriate privileges (for example, using sudo where required)
5. After installation completes, the Connector service is automatically started.
6. Once the device connects, it will appear in Inventory → Devices with an online status.

Delete a Device

1. En Inventory → Devices, click the Action menu (⋮) next to the device.
2. Sélectionner Supprimer.
3. Confirm the deletion.

Additional useful information

API key prerequisite

To enroll a device, you must first create an API key in XOAP (under Connexions). The installer uses this key to register the device to your workspace.

Service behavior

The XOAP Connector runs as a service (Windows) /daemon (Linux/Mac).

Image Management flag

If the device will be used for Image Management, install the connector using the –imagemanagement flag to enable the required functionality during enrollment.

Connectivity requirements

The device must be able to reach the XOAP backend (HTTPS/443, directly or via proxy) to enroll and stay connected.

Devices vs. Nodes

A single endpoint can appear both as a Device in Inventaire (XOAP Connector installed) and as a Node in Configuration Management (registered via configuration). These are complementary views—one does not exclude the other.

Mass deployment option (PSADT + Application Management)

Le XOAP Connector installer can be packaged as a PSAppDeployToolkit (PSADT) package and deployed via Application Management to:

• already managed Nœuds, and
• new endpoints as part of onboarding.

Technical documentation

Le Dispositifs page in Inventaire lists endpoints where the XOAP Connector is installed and enrolled into a workspace. Once connected, devices can execute Inventory features (for example Queries via osquery) and support operational actions such as running commands/scripts, transferring files, and installing applications.

A device can be managed in multiple XOAP areas at the same time:

• The same endpoint can appear as a Node in Configuration Management and as a Device in Inventaire. These are different feature areas and do not exclude each other.

Conditions préalables

• API key must exist in XOAP Connections before installing/enrolling the XOAP Connector.
• Local admin/root privileges are required to install the connector and set up the service.

Installing and enrolling the XOAP Connector

En Inventory → Devices → Add Agent, select the platform and API key. XOAP generates an install command that enrolls the device into the correct workspace.

Windows (PowerShell as Administrator):

.\XOAP.Connector.Installer.exe –install –apiKey APIKEY –workspace WORKSPACEID

Linux (run with sudo):

./XOAP.Connector.Installer –install –apiKey APIKEY  –workspace WORKSPACEID

Image Management flag

If the device should be used for Image Management, install the connector with the Image Management flag:

.\XOAP.Connector.Installer.exe –install –apiKey APIKEY –workspace WORKSPACEID –ImageManagement

If Image Management is not enabled during installation, the device will still work for Inventory features, but Image Management-specific capabilities may not be available.

Service startup

After installation, the XOAP Connector service is started automatically. If needed, it can be started manually:

Start-Service XOAPConnector

What gets installed during XOAP Connector installation

During installation, the XOAP Connector installation utility detects existing components first and installs only what is missing or required. If a component is already installed and meets the expected version, that step is skipped.

Components handled by the installer

1) XOAP Connector binaries

• Downloads the latest XOAP Connector release package and extracts it to:
  • C:\Program Files\XOAP\Connector
• Creates/updates the connector configuration as part of enrollment (API key + workspace).

2) XOAP Connector Windows Service

• Installs a Windows service named XOAPConnector
• Starts the service after installation (and typically configures it for automatic startup).

3) Installer persistence files

• Persists installer/support files under:
  • C:\Program Files\XOAP\Installer

4) osquery (Inventory / Queries dependency)

• Detects osquery installation and version.
• If missing (or older than required), downloads and installs osquery (MSI).
• If already installed and the version is equal/newer than required, installation is skipped.

5) Supporting tooling (prepared installers / prerequisites)

The installer can prepare prerequisites used by XOAP workflows (depending on scenario/feature usage):

• Packer (commonly required for Image Management-related workflows)
• Azure CLI (used when interacting with Azure workflows)
• WinGet initialization may be executed to support prerequisite handling on Windows.

Temporary download locations

Downloaded packages (for example connector ZIP and osquery MSI) are typically staged under:

• C:\Users\<user>\AppData\Local\Temp\…

Updating and uninstalling (optional operational commands)

Depending on your distribution/installer build, the connector utility may support lifecycle operations such as:

Update

\XOAP.Connector-Installer.exe –update

Uninstall

.\XOAP.Connector-Installer.exe –uninstall

Device actions in Inventory

From the device action menu (⋮) you can run operations on a connected device, such as:

• View agent log: Opens connector runtime logs for troubleshooting.
• Run Command: Executes a command from the Commands Library on the device.
• Run Query: Executes an osquery-based Inventory query on the device.
• Run Script: Runs a script on the device.
  • Scripts are selected from the XOAP Resources area (scripts must exist as resources first).
• Install applications: Assigns and triggers application installs (depending on your Application Management setup).
• Transfer file:
  • Télécharger: Retrieve a file from the device to XOAP (optionally add it to Resources).
  • Upload: Upload a file to the device either from XOAP Resources or from your local machine.
• Supprimer: Removes the device from the Inventory list (device-side uninstall is a separate action/process).

More information

Devices vs Nodes

A device can be managed as a Device (Inventory) and a Node (Configuration Management) at the same time.

Mass deployment

The XOAP Connector can be packaged (for example as a PSAppDeployToolkit (PSADT) package) and deployed at scale through Application Management to existing managed Nodes — and used as a standardized installer for new devices as well.

Image Management enablement

If a device is intended to participate in Image Management, install with –imagemanagement from the start to ensure the correct capabilities are enabled.

The post Devices appeared first on XOAP.

Quick guide

XOAP Queries are SQL-based queries that run directly on managed devices to collect inventory and operational data. When the XOAP Connector is installed, it also deploys osquery, and XOAP Queries use this osquery engine to execute SQL statements on the endpoint and return the results to XOAP.

Create a new Query

1. En Inventory → Queries, click + Add Query.
2. Enter a Query name.
3. Select the target OS.
4. (Optional) Add Tags and a Description.
5. En Command, paste the SQL query to be executed on the device.
6. Cliquez sur Add to create the query.

Edit a Query

1. Open the query details (for example, via the Details option/icon).
2. Cliquez sur Editer.
3. Update the query metadata (name, OS, tags, description) and/or the Command.
4. Save your changes.

Delete a Query

1. In the Queries list, select the query (or multiple queries).
2. Delete it using the Supprimer option/icon.
3. Confirm the deletion.

Additional useful information

OS compatibility

Not all queries work on every operating system. As a best practice, indicate OS scope in the query name (e.g., WIN_, LINUX_, MAC_, or ALL_) so it’s clear whether a query is OS-specific or universal.

Keep queries efficient

Prefer targeted filters and limit result size where possible. Heavy queries (large tables, many joins, or broad scans) can increase endpoint load and slow down data collection.

Technical documentation

Queries in XOAP are SQL statements executed on endpoints to retrieve inventory and security-relevant information (software, users, processes, services, browser extensions, local groups, etc.). XOAP uses these queries to collect structured data from devices and present it centrally in the Inventory module.

osquery is an open-source endpoint agent that exposes operating system data through a SQL interface. Internally, it maps OS information to virtual “tables” (for example processes, users, services, programs, chrome_extensions) that you can query using standard SQL syntax. The result is a consistent, queryable inventory layer across supported platforms.

When the XOAP Connector is installed on a device, osquery is deployed as part of the installation. XOAP then triggers the configured SQL query on the endpoint via the Connector and collects the results back into XOAP for reporting and analysis.

High-level flow:

1. You define a Query (SQL + target OS metadata) in XOAP.
2. XOAP triggers execution on selected endpoints through the XOAP Connector.
3. osquery runs the SQL locally and returns rows (results).
4. XOAP ingests and displays the returned data in Inventory.

Here are a few simple osquery SQL examples you can use as templates:

Basic system info

SELECT hostname, cpu_type, cpu_subtype, physical_memory

FROM system_info;

List local users

SELECT username, uid, description

FROM users

ORDER BY username;

Installed software (Windows-focused)

SELECT name, version, install_location, publisher

FROM programs

ORDER BY name;

The schema of the osquery tables can be found on https://osquery.io/schema/5.21.0/

The post Queries appeared first on XOAP.

Quick guide

Commands Library is a centralized repository for reusable commands that can be executed on managed devices. It lets you standardize common operational tasks (e.g., troubleshooting, data collection, quick checks) by storing commands in one place and reusing them across the environment. Commands can be created for different runtimes such as PowerShell, PowerShell Core, Bash/Shell, or CMD.

Add a new Command

1. Cliquez sur + Add Command.
2. Enter a Command name.
3. Select the Type (e.g., PowerShell Core, PowerShell, Bash/Shell, CMD).
4. (Optional) Add Tags and a Description.
5. Paste or write the Command content.
6. Cliquez sur Add to create the command.

Edit a Command

1. Open the command (e.g., via the Details / eye icon).
2. Dans le cadre de la Current version panel, click Editer.
3. Update the command content and/or metadata as needed.
4. Save the changes (a new version is created).

Delete a Command

1. Click the Supprimer (trash) icon next to the command.
2. Confirm deletion.

Additional useful information

OS compatibility

Some command types are OS-specific. Use Tags (e.g., windows, linux) and/or naming conventions to clearly indicate the target platform.

Prefer non-interactive commands

Avoid prompts and UI interactions; commands should run unattended.

Keep output readable

Return clear, structured output (and include error handling) to simplify troubleshooting and auditing.

Technical documentation

Le Commands Library is XOAP’s centralized store for versioned and reusable commands that can be executed on managed devices through the XOAP Inventory/Connector execution layer. It is designed for operational tasks such as troubleshooting, validation checks, log collection, and lightweight remediation actions.

A command in the library is defined by:

• Metadata (name, description, tags)
• Runtime type (PowerShell, PowerShell Core, Bash/Shell, CMD)
• Command body (the actual script/command text)
• Version information (version number and message)

Commands are executed on devices that have the XOAP Connector installed.

Command Types (Runtime)

When you create a command, you select a Type that defines the interpreter/runtime used on the device:

• PowerShell
  Runs using Windows PowerShell (typically 5.1 on Windows).
• PowerShell Core
  Runs using PowerShell 7+ (cross-platform when available).
• Bash/Shell
  Runs using a shell on Linux/macOS (typically /bin/bash or /bin/sh, depending on the device).
• CMD
  Runs using Windows Command Prompt (cmd.exe).

Versioning behavior

Commands are versioned artifacts. Any change to the command definition (especially the command body) should be treated as a new version so you can:

• Track who changed what and why
• Roll forward safely
• Keep operational actions reproducible across environments

Best practice: Use short, meaningful version messages (e.g., “Add service filter”, “Fix path quoting”, “Support PS7”).

Fields and what they mean

Dans le cadre de la Add Command dialog:

• Command name
  Unique, human-readable identifier. Use a consistent naming scheme like:
  windows-check-service-status / linux-journalctl-last-50
• Type
  The runtime/interpreter used to execute the command on the target device.
• Tags
  Used for filtering and organization (OS, purpose, team, environment).
• Description (optional)
  Short explanation of intent, expected output, and any prerequisites.
• Command
  The script/command content. This should be non-interactive and safe to run repeatedly.

Execution model and output

Commands are  executed remotely and return:

• Exit code (success/failure)
• Standard output (results)
• Standard error (errors)

Recommended patterns

• Return human-readable output plus simple structured output where possible (key/value lines).
• Use explicit exit codes:
  • 0 = success
  • non-zero = failure or partial failure
• Write errors to stderr and keep stdout for normal results.

Operational and security considerations

Non-interactive only

• Avoid prompts (Read-Host, pause, interactive confirmation).
• Assume the command runs unattended.

Idempotency

• Prefer commands that can be run multiple times without harmful side effects.
• For remediation-type commands, check current state before changing it.

Logging

• For troubleshooting commands, include contextual details (hostname, timestamp, relevant versions).

Best practices for building a maintainable library

• Naming convention: os-purpose-action (e.g., windows-inventory-installed-software)
• Tagging: OS + team + category (e.g., windows, security, troubleshooting)
• Small scope: One command = one purpose. Avoid “do everything” scripts.
• Document prerequisites: Required tools, modules, permissions, or paths.
• Test on pilots: Validate on a small set of devices before broad use.
• Prefer PowerShell Core for cross-platform: If your fleet supports it, it simplifies reuse.

Examples (simple, safe commands)

PowerShell (Windows) – list a service state

Get-Service -Name “WinRM” | Select-Object Name, Status, StartType

PowerShell (Windows) – last 50 event log errors (System)

Get-WinEvent -LogName System -MaxEvents 50 |
  Where-Object { $_.LevelDisplayName -in “Error”,”Critical” } |
  Select-Object TimeCreated, Id, ProviderName, Message

CMD (Windows) – basic network info

ipconfig /all

Bash (Linux) – disk usage summary

df -h

Troubleshooting

If a command fails to run or returns unexpected output, the most common causes are:

• Wrong Type selected (e.g., Bash command on Windows)
• Runtime not installed (e.g., PowerShell 7 missing for “PowerShell Core” commands)
• OS differences (paths, tools, service managers)
• Command is interactive or expects a TTY

Recommendation: Start with read-only diagnostics commands, then add remediation actions only after validation and clear approvals.

The post Commands library appeared first on XOAP.