Inventory
The Zentral Inventory app is mandatory in a Zentral deployment. It is used to store all the inventory information.
Zentral configuration
A zentral.contrib.inventory
subsection must be present in the apps
section in the configuration.
metrics
OPTIONAL
This boolean is used to toggle the inventory metrics endpoint for Prometheus. false
by default.
metrics_options
OPTIONAL
A dictionary to configure the available inventory metrics. Only configured metrics will be published. Empty by default.
Six different metric families are available: android_apps
, deb_packages
, ios_apps
, osx_apps
, programs
, and os_versions
. To publish a metric family, the corresponding configuration dictionary must be set in the metrics_options
section. For each metric family, a mandatory sources
attribute must be set, to filter the inventory sources. A mandatory bundle_ids
or bundle_names
attribute (array of strings) must be set in the osx_apps
metric family configuration to filter the published bundle metrics. For the android_apps
, deb_packages
, ios_apps
, and programs
metric families, a names
attribute (array of strings) must be set, respectively to the list of Android app names, Debian package names, iOS app names, or Windows program names to include in the metrics.
Example:
{
"metrics": true,
"metrics_options": {
"android_apps": {
"sources": ["Workspace ONE"],
"names": ["Google Pay"],
},
"deb_packages": {
"sources": ["osquery"],
"names": ["firefox", "falcon-sensor"]
},
"ios_apps": {
"sources": ["Workspace ONE"],
"names": ["1Password"],
},
"osx_apps": {
"sources": ["Munki", "osquery"],
"bundle_ids": ["org.mozilla.firefox", "us.zoom.xos"]
},
"programs": {
"sources": ["osquery"],
"names": ["Firefox", "Zoom"]
},
"os_versions": {
"sources": ["Munki", "osquery"]
}
}
}
event_serialization
OPTIONAL
This subsection can be used to change the machine information serialization in the Zentral event metadata. There are two options available:
include_groups
OPTIONAL
This boolean is used to toggle the inclusion of the machine groups in the event metadata. true
by default.
include_principal_user
OPTIONAL
This boolean is used to toggle the inclusion of the principal user in the event metadata. true
by default.
HTTP API
/api/inventory/machines/tags/
- method: POST
- required permissions:
inventory.add_tag
inventory.add_taxonomy
inventory.add_machinetag
inventory.delete_machinetag
Use this endpoint to tag machines using principal user information (unique IDs or principal names).
Example payload:
{
"principal_users": {
"principal_names": ["janeDoe", "johnSmith"],
"unique_ids": ["max.mustermann@example.com"]
},
"tags": {
"taxonomy 1": "tag1",
"taxonomy 2": null
}
}
When posting this payload, Zentral will look for all the machines having matching principal users. For those machines, it will ensure that their are tagged with tag1
from the taxonomy taxonomy 1
, and will remove any other tag from the taxonomy taxonomy 1
and any tag from the taxonomy taxonomy 2
(idempotent operation). The required taxonomies and tags are automatically created.
The response format is:
{
"machines": {"found": 3},
"tags": {"added": 3,
"removed": 1}
}
/api/inventory/cleanup/
- method: POST
- required permissions:
inventory.delete_machinesnapshot
- optional parameter:
days
: The number of days (1
→3660
) of history to keep. Defaults to30
or the value ofsnapshot_retention_days
in the inventory app config.
Use this endpoint to trigger an inventory history cleanup.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
https://zentral.example.com/api/inventory/cleanup/\
|python3 -m json.tool
Response:
{
"task_id": "b1512b8d-1e17-4181-a1c3-93a7243fddd4",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-93a7243fddd4/"
}
/api/inventory/machines/archive/
- method: POST
- Content-Type: application/json
- required permission:
inventory.change_machinesnapshot
Use this endpoint to archive machines using their serial numbers. The inventory data will be kept in the database, in case the machines show up again, but the machines will not be displayed when browsing or exporting the inventory. Up to 1000 machines can be archived per API call.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"serial_numbers": ["0123456789"]}' \
https://zentral.example.com/api/inventory/machines/archive/\
|python3 -m json.tool
Response:
{"current_machine_snapshots": 0}
/api/inventory/machines/prune/
- method: POST
- Content-Type: application/json
- required permission:
inventory.delete_machinesnapshot
Use this endpoint to prune machines using their serial numbers. The inventory data will be removed from the database. Up to 1000 machines can be pruned per API call.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"serial_numbers": ["0123456789"]}' \
https://zentral.example.com/api/inventory/machines/prune/\
|python3 -m json.tool
Response:
{"current_machine_snapshots": 1,
"machine_snapshots": 2,
"machine_snapshot_commits": 13}
/api/inventory/android_apps/export/
- method: POST
- Content-Type: application/json
- required permission:
inventory.view_androidapp
- optional parameters:
export_format
:csv
orxlsx
. Defaults toxlsx
.source
: The ID of an inventory source. Only Android apps collected via this source will be included in the export.last_seen
:1d
,7d
,14d
,30d
,45d
,90d
. Only Android apps collected within this time window will be included in the export.display_name
: A search string.
Use this endpoint to trigger an Android apps export task. The result of this task will be a spreadsheet.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"display_name": "Chrome"}' \
https://zentral.example.com/api/inventory/android_apps/export/\
|python3 -m json.tool
Response:
{
"task_id": "b1512b8d-1e17-4181-a1c3-93a7243fddd3",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-93a7243fddd3/"
}
/api/inventory/deb_packages/export/
- method: POST
- Content-Type: application/json
- required permission:
inventory.view_debpackage
- optional parameters:
export_format
:csv
orxlsx
. Defaults toxlsx
.source
: The ID of an inventory source. Only Debian packages collected via this source will be included in the export.last_seen
:1d
,7d
,14d
,30d
,45d
,90d
. Only Debian packages collected within this time window will be included in the export.name
: A search string.
Use this endpoint to trigger a Debian packages export task. The result of this task will be a spreadsheet.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name": "Firefox", "last_seen": "90d"}' \
https://zentral.example.com/api/inventory/deb_packages/export/\
|python3 -m json.tool
Response:
{
"task_id": "b1512b8d-1e17-4181-a1c3-93a9243fddd3",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-93a9243fddd3/"
}
/api/inventory/ios_apps/export/
- method: POST
- Content-Type: application/json
- required permission:
inventory.view_iosapp
- optional parameters:
export_format
:csv
orxlsx
. Defaults toxlsx
.source
: The ID of an inventory source. Only iOS apps collected via this source will be included in the export.last_seen
:1d
,7d
,14d
,30d
,45d
,90d
. Only iOS apps collected within this time window will be included in the export.name
: A search string.
Use this endpoint to trigger an iOS apps export task. The result of this task will be a spreadsheet.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name": "1Password", "last_seen": "1d"}' \
https://zentral.example.com/api/inventory/ios_apps/export/\
|python3 -m json.tool
Response:
{
"task_id": "b1512b8d-1e17-4181-a1c3-83a9243fddd3",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-83a9243fddd3/"
}
/api/inventory/macos_apps/export/
- method: POST
- Content-Type: application/json
- required permission:
inventory.view_osxapp
inventory.view_osxappinstance
- optional parameters:
export_format
:csv
orxlsx
. Defaults toxlsx
.source
: The ID of an inventory source. Only macOS apps collected via this source will be included in the export.last_seen
:1d
,7d
,14d
,30d
,45d
,90d
. Only macOS apps collected within this time window will be included in the export.bundle_name
: A search string.
Use this endpoint to trigger a macOS apps export task. The result of this task will be a spreadsheet.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"bundle_name": "1Password", "last_seen": "14d", "source": 4641}' \
https://zentral.example.com/api/inventory/macos_apps/export/\
|python3 -m json.tool
Response:
{
"task_id": "c1512b8d-1e17-4181-a1c3-83a9243fddd3",
"task_result_url": "/api/task_result/c1512b8d-1e17-4181-a1c3-83a9243fddd3/"
}
/api/inventory/programs/export/
- method: POST
- Content-Type: application/json
- required permission:
inventory.view_program
inventory.view_programinstance
- optional parameters:
export_format
:csv
orxlsx
. Defaults toxlsx
.source
: The ID of an inventory source. Only Windows programs collected via this source will be included in the export.last_seen
:1d
,7d
,14d
,30d
,45d
,90d
. Only Windows programs collected within this time window will be included in the export.name
: A search string.
Use this endpoint to trigger a Windows programs export task. The result of this task will be a spreadsheet.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
-d '{"name": "1Password", "export_format": "csv"}' \
https://zentral.example.com/api/inventory/programs/export/\
|python3 -m json.tool
Response:
{
"task_id": "c2512b8d-1e17-4181-a1c3-83a9243fddd3",
"task_result_url": "/api/task_result/c2512b8d-1e17-4181-a1c3-83a9243fddd3/"
}
/api/inventory/machines/export_android_apps/
- method: POST
- required permission:
inventory.view_androidapp
- optional parameter:
source_name
: The name of an inventory source. Only machines with Android apps collected via this source will be included in the export.
Use this endpoint to trigger a machine Android apps export task. The result of this task will be a Zip archive containing a CSV file for each source.
Example of an export limited to the Workspace ONE
source:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/inventory/machines/export_android_apps/?source_name=Workspace%20ONE" \
|python3 -m json.tool
Response:
{
"task_id": "b1512b8d-1e17-4181-a1c3-93a7243fddd3",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-93a7243fddd3/"
}
/api/inventory/machines/export_deb_packages/
- method: POST
- required permission:
inventory.view_debpackage
- optional parameter:
source_name
: The name of an inventory source. Only machines with Debian packages collected via this source will be included in the export.
Use this endpoint to trigger a machine Debian packages export task. The result of this task will be a Zip archive containing a CSV file for each source.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
https://zentral.example.com/api/inventory/machines/export_deb_packages/\
|python3 -m json.tool
Response:
{
"task_id": "b1512b8d-1e17-4181-a1c3-93a7243fddd3",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-93a7243fddd3/"
}
/api/inventory/machines/export_ios_apps/
- method: POST
- required permission:
inventory.view_iosapp
- optional parameter:
source_name
: The name of an inventory source. Only machines with iOS apps collected via this source will be included in the export.
Use this endpoint to trigger a machine iOS apps export task. The result of this task will be a Zip archive containing a CSV file for each source.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
https://zentral.example.com/api/inventory/machines/export_ios_apps/\
|python3 -m json.tool
Response:
{
"task_id": "b1512b8d-1e17-4181-a1c3-93a7243fddd3",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-93a7243fddd3/"
}
/api/inventory/machines/export_macos_app_instances/
- method: POST
- required permissions:
inventory.view_osxapp
inventory.view_osxappinstance
- optional parameter:
source_name
: The name of an inventory source. Only machines with macOS apps collected via this source will be included in the export.
Use this endpoint to trigger a machine macOS app instances export task. The result of this task will be a Zip archive containing a CSV file for each source.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
https://zentral.example.com/api/inventory/machines/export_macos_app_instances/\
|python3 -m json.tool
Response:
{
"task_id": "b1512b8d-1e17-4181-a1c3-93a7243fddd3",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-93a7243fddd3/"
}
/api/inventory/machines/export_program_instances/
- method: POST
- required permissions:
inventory.view_program
inventory.view_programinstance
- optional parameter:
source_name
: The name of an inventory source. Only machines with Windows programs collected via this source will be included in the export.
Use this endpoint to trigger a machine Windows program instances export task. The result of this task will be a Zip archive containing a CSV file for each source.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
https://zentral.example.com/api/inventory/machines/export_program_instances/\
|python3 -m json.tool
Response:
{
"task_id": "b1512b8d-1e17-4181-a1c3-93a7243fddd3",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-93a7243fddd3/"
}
/api/inventory/machines/export_snapshots/
- method: POST
- required permissions:
inventory.view_machinesnapshot
- optional parameter:
source_name
: The name of an inventory source. Only machine snapshots collected via this source will be included in the export.
Use this endpoint to trigger a machine snapshots export task. The result of this task will be a Zip archive containing a JSONL file for each source.
Example:
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
https://zentral.example.com/api/inventory/machines/export_snapshots/\
|python3 -m json.tool
Response:
{
"task_id": "b1512b8d-1e17-4181-a1c3-93a7243fddd3",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-93a7243fddd3/"
}