Osquery
Osquery is an operating system instrumentation framework for Windows, OS X (macOS), Linux, and FreeBSD. Zentral can act as a remote server for Osquery, for configuration, query runs, file carvings, and log collection.
Zentral configuration
To activate the osquery module, you need to add a zentral.contrib.osquery
section to the apps
section in base.json
.
HTTP API
Requests
Authentication
API requests are authenticated using a token in the Authorization
HTTP header.
To get a token, you can create a service account. As a superuser, go to Setup > Manage users, and in the "Service accounts" subsection, click on the [Create] button. Pick a name for your service account and [Save]. You will be redirected to a token view. The token is only displayed once. To reveal it, click on the eye icon. Once you have saved it (in a password manager, in a configuration variable, โฆ), you can click on the [OK] button.
You can also add an API token to a normal user, although it is not recommended. To do so, click on the user in the User list, and click on the [+] button next to the API token boolean.
If you have lost or leaked a token, you can delete it by clicking on the user or service account name, and then click on the ๐ next to the API token boolean.
The format for the Authorization
header is the following:
Authorization: Token the_token_string
Content type
Zentral will parse the body of the request based on the Content-Type
HTTP header:
Content-Type: application/json
Content-Type: application/x-osquery-conf
Content-Type: application/yaml
/api/osquery/atcs/
List all ATCs.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_automatictableconstruction
- Optional filter parameter:
name
: name of the ATC.configuration_id
: primary key of the configuration.
Examples:
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/atcs/" \
|python3 -m json.tool
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/atcs/?name=Santa+rules" \
|python3 -m json.tool
Response:
[
{
"id": 1,
"name": "Santa rules",
"description": "Access the Google Santa rules.db",
"table_name": "santa_rules",
"query": "SELECT * FROM rules;",
"path": "/var/db/santa/rules.db",
"columns": [
"identifier",
"state",
"type",
"custommsg",
"timestamp"
],
"platforms": [
"darwin"
],
"created_at": "2023-01-30T09:39:35.965003",
"updated_at": "2023-01-30T09:39:35.965011"
}
]
Add a new ATC.
- method: POST
- Content-Type: application/json
- Required permission:
osquery.add_automatictableconstruction
Example:
atc.json
{
"name": "Access example",
"description": "Access the example example.db",
"table_name": "example_table",
"query": "SELECT * FROM example;",
"path": "/var/db/example/example.db",
"columns": [
"one",
"two",
"three"
],
"platforms": [
"darwin",
"linux"
]
}
$ curl -X POST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/atcs/" \
-d @atc.json \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "Access example",
"description": "Access the example example.db",
"table_name": "example_table",
"query": "SELECT * FROM example;",
"path": "/var/db/example/example.db",
"columns": [
"one",
"two",
"three"
],
"platforms": [
"darwin",
"linux"
],
"created_at": "2023-01-31T08:59:14.097316",
"updated_at": "2023-01-31T08:59:14.097333"
}
/api/osquery/atcs/<int:pk>
/
Get a ATC.
method: GET
Content-Type: application/json
Required permission: osquery.view_automatictableconstruction
<int:pk>
: the primary key of the ATC.
Example
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/atcs/2/" \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "Access example",
"description": "Access the example example.db",
"table_name": "example_table",
"query": "SELECT * FROM example;",
"path": "/var/db/example/example.db",
"columns": [
"one",
"two",
"three"
],
"platforms": [
"darwin",
"linux"
],
"created_at": "2023-01-31T08:59:14.097316",
"updated_at": "2023-01-31T08:59:14.097333"
}
Update a ATC.
- method: PUT
- Content-Type: application/json
- Required permission:
osquery.update_automatictableconstruction
<int:pk>
: the primary key of the ATC.
Example
atc_update.json
{
"name": "Access example",
"description": "Access the example example.db on all platforms",
"table_name": "example_table",
"query": "SELECT * FROM example;",
"path": "/var/db/example/example.db",
"columns": [
"one",
"two",
"three",
"four"
],
"platforms": [
"darwin",
"linux",
"windows",
"freebsd"
]
}
$ curl -X PUT \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/atcs/2/" \
-d @atc_update.json \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "Access example",
"description": "Access the example example.db on all platforms",
"table_name": "example_table",
"query": "SELECT * FROM example;",
"path": "/var/db/example/example.db",
"columns": [
"one",
"two",
"three",
"four"
],
"platforms": [
"darwin",
"linux",
"windows",
"freebsd"
],
"created_at": "2023-01-31T08:59:14.097316",
"updated_at": "2023-01-31T09:05:08.326755"
}
Delete a ATC.
- method: DELETE
- Required permission:
osquery.delete_automatictableconstruction
<int:pk>
: the primary key of the ATC.
Example
$ curl -X DELETE \
-H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/atcs/2/"
Response (204 No Content)
/api/osquery/configurations/
List all Configurations.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_configuration
- Optional filter parameter:
name
: Name of the configuration.
Examples:
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/configurations/" \
|python3 -m json.tool
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/configurations/?name=example" \
|python3 -m json.tool
Response:
[
{
"id": 1,
"name": "example",
"description": "",
"inventory": true,
"inventory_apps": true,
"inventory_ec2": false,
"inventory_interval": 600,
"options": {
"config_refresh": 120
},
"created_at": "2023-01-06T13:05:02.535763",
"updated_at": "2023-01-30T09:40:23.912582",
"file_categories": [],
"automatic_table_constructions": [
1
]
}
]
Add a new Configuration.
- method: POST
- Content-Type: application/json
- Required permission:
osquery.add_configuration
- Required fields:
name
: Name of the configuration.
Example:
configuration.json
{
"name": "example2",
"description": "description of example2",
"inventory": true,
"inventory_apps": true,
"inventory_ec2": false,
"inventory_interval": 600,
"options": {
"config_refresh": 120
},
"file_categories": [
1
],
"automatic_table_constructions": [
1
]
}
$ curl -X POST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/configurations/" \
-d @configuration.json \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "example2",
"description": "description of example2",
"inventory": true,
"inventory_apps": true,
"inventory_ec2": false,
"inventory_interval": 600,
"options": {
"config_refresh": 120
},
"created_at": "2023-02-01T11:37:00.622052",
"updated_at": "2023-02-01T11:37:00.622077",
"file_categories": [
1
],
"automatic_table_constructions": [
1
]
}
/api/osquery/configurations/<int:pk>
/
Get a Configuration.
method: GET
Content-Type: application/json
Required permission: osquery.view_configuration
<int:pk>
: The primary key of the configuration.
Example
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/configurations/2/" \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "example2",
"description": "description of example2",
"inventory": true,
"inventory_apps": true,
"inventory_ec2": false,
"inventory_interval": 600,
"options": {
"config_refresh": 120
},
"created_at": "2023-02-01T11:37:00.622052",
"updated_at": "2023-02-01T11:37:00.622077",
"file_categories": [
1
],
"automatic_table_constructions": [
1
]
}
Update a Configuration.
- method: PUT
- Content-Type: application/json
- Required permission:
osquery.update_configuration
<int:pk>
: The primary key of the configuration.- Required fields:
name
: Name of the configuration.
Example
configuration_update.json
{
"name": "example2",
"description": "description of example2 updated",
"inventory": true,
"inventory_apps": true,
"inventory_ec2": false,
"inventory_interval": 800,
"options": {
"config_refresh": 120
},
"file_categories": [],
"automatic_table_constructions": []
}
$ curl -X PUT \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/configurations/2/" \
-d @configuration_update.json \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "example2",
"description": "description of example2 updated",
"inventory": true,
"inventory_apps": true,
"inventory_ec2": false,
"inventory_interval": 800,
"options": {
"config_refresh": 120
},
"created_at": "2023-02-01T11:37:00.622052",
"updated_at": "2023-02-01T11:39:12.664992",
"file_categories": [],
"automatic_table_constructions": []
}
Delete a Configuration.
- method: DELETE
- Required permission:
osquery.delete_configuration
<int:pk>
: The primary key of the configuration.
Example
$ curl -X DELETE \
-H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/configurations/2/"
Response (204 No Content)
/api/osquery/configuration_packs/
List all Configuration Packs.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_configurationpack
- Optional filter parameter:
pack_id
: primary key of the pack.configuration_id
: primary key of the configuration.
Examples:
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/configuration_packs/" \
|python3 -m json.tool
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/configuration_packs/?pack_id=2" \
|python3 -m json.tool
Response:
[
{
"id": 1,
"configuration": 2,
"pack": 2,
"tags": [
1
]
}
]
Add a new Configuration Pack.
- method: POST
- Content-Type: application/json
- Required permission:
osquery.add_configurationpack
- Required fields:
pack
: primary key of an existing pack.configuration
: primary key of an existing configuration.
- Optional fields:
tags
: list of primary keys of existing tags.
Example:
configurationpack.json
{
"configuration": 1,
"pack": 2,
"tags": [
2
]
}
$ curl -X POST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/configuration_packs/" \
-d @configurationpack.json \
|python3 -m json.tool
Response:
{
"id": 2,
"configuration": 1,
"pack": 2,
"tags": [
2
]
}
/api/osquery/configuration_packs/<int:pk>
/
Get a Configuration Pack.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_configurationpack
<int:pk>
: The primary key of the configuration pack.
Example
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/configuration_packs/2/" \
|python3 -m json.tool
Response:
{
"id": 2,
"configuration": 1,
"pack": 2,
"tags": [
2
]
}
Update a Configuration Pack.
- method: PUT
- Content-Type: application/json
- Required permission:
osquery.update_configurationpack
<int:pk>
: The primary key of the configurationpack.- Required fields:
pack
: primary key of an existing pack.configuration
: primary key of an existing configuration.
- Optional fields:
tags
: list of primary keys of existing tags.
Example
configurationpack_update.json
{
"configuration": 1,
"pack": 1,
"tags": [
1
]
}
$ curl -X PUT \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/configuration_packs/2/" \
-d @configurationpack_update.json \
|python3 -m json.tool
Response:
{
"id": 2,
"configuration": 1,
"pack": 1,
"tags": [
1
]
}
Delete a Configuration Pack.
- method: DELETE
- Required permission:
osquery.delete_configurationpack
<int:pk>
: The primary key of the configuration pack.
Example
$ curl -X DELETE \
-H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/configuration_packs/2/"
Response (204 No Content)
/api/osquery/file_categories/
List all FileCategories.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_filecategory
- Optional filter parameter:
name
: name of the FileCategory.configuration_id
: primary key of the configuration.
Examples:
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/file_categories/" \
|python3 -m json.tool
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/file_categories/?name=example" \
|python3 -m json.tool
Response:
[
{
"id": 1,
"name": "example",
"slug": "example",
"description": "example description",
"file_paths": [],
"exclude_paths": [],
"file_paths_queries": [],
"access_monitoring": false,
"created_at": "2023-01-31T11:48:53.014319",
"updated_at": "2023-01-31T11:48:53.014332"
}
]
Add a new FileCategory.
- method: POST
- Content-Type: application/json
- Required permission:
osquery.add_filecategory
Example:
file_category.json
{
"name": "example2",
"slug": "example2",
"description": "example2 description",
"file_paths": ["/usr/example2"],
"exclude_paths": ["/home/you/exclude1", "/home/me/exclude2"],
"file_paths_queries": [],
"access_monitoring": true
}
$ curl -X POST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/file_categories/" \
-d @file_category.json \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "example2",
"slug": "example2",
"description": "example2 description",
"file_paths": [
"/usr/example2"
],
"exclude_paths": [
"/home/you/exclude1",
"/home/me/exclude2"
],
"file_paths_queries": [],
"access_monitoring": true,
"created_at": "2023-01-31T14:09:46.079654",
"updated_at": "2023-01-31T14:09:46.079664"
}
/api/osquery/file_categories/<int:pk>
/
Get a FileCategory.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_filecategory
<int:pk>
: the primary key of the FileCategory.
Example
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/file_categories/2/" \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "example2",
"slug": "example2",
"description": "example2 description",
"file_paths": [
"/usr/example2"
],
"exclude_paths": [
"/home/you/exclude1",
"/home/me/exclude2"
],
"file_paths_queries": [],
"access_monitoring": true,
"created_at": "2023-01-31T14:09:46.079654",
"updated_at": "2023-01-31T14:09:46.079664"
}
Update a FileCategory.
- method: PUT
- Content-Type: application/json
- Required permission:
osquery.update_filecategory
<int:pk>
: the primary key of the FileCategory.
Example
file_category_update.json
{
"name": "example2 updated",
"description": "example2 description updated",
"file_paths": [
"/usr/bin/example2"
],
"exclude_paths": [
"/home/you/exclude1"
],
"file_paths_queries": [],
"access_monitoring": false
}
$ curl -X PUT \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/file_categories/2/" \
-d @file_categories_update.json \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "example2 updated",
"slug": "example2-updated",
"description": "example2 description updated",
"file_paths": [
"/usr/bin/example2"
],
"exclude_paths": [
"/home/you/exclude1"
],
"file_paths_queries": [],
"access_monitoring": false,
"created_at": "2023-01-31T11:48:53.014319",
"updated_at": "2023-01-31T14:13:39.306239"
}
Delete a FileCategory.
- method: DELETE
- Required permission:
osquery.delete_filecategory
<int:pk>
: the primary key of the FileCategory.
Example
$ curl -X DELETE \
-H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/file_categories/2/"
Response (204 No Content)
/api/osquery/packs/
List all Packs.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_pack
- Optional filter parameter:
name
: Name of the pack.configuration_id
: primary key of the configuration.
Examples:
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/packs/" \
|python3 -m json.tool
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/packs/?name=Default" \
|python3 -m json.tool
Response:
[
{
"id": 1,
"name": "Default",
"slug": "default",
"description": "",
"discovery_queries": [],
"shard": null,
"event_routing_key": "",
"created_at": "2023-01-13T07:06:51.000733",
"updated_at": "2023-01-13T07:06:51.000743"
}
]
Add a new Pack.
- method: POST
- Content-Type: application/json
- Required permission:
osquery.add_pack
- Required fields:
name
: Name of the pack.
Example:
pack.json
{
"name": "Example",
"description": "description of the example",
"discovery_queries": ["SELECT 1 FROM users WHERE username like 'www%';"],
"shard": 50
}
$ curl -X POST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/packs/" \
-d @pack.json \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "Example",
"slug": "example",
"description": "description of the example",
"discovery_queries": [
"SELECT 1 FROM users WHERE username like 'www%';"
],
"shard": 50,
"event_routing_key": "",
"created_at": "2023-02-02T07:30:42.133421",
"updated_at": "2023-02-02T07:30:42.133434"
}
/api/osquery/packs/<int:pk>
/
Get a Pack.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_pack
<int:pk>
: The primary key of the pack.
Example
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/packs/2/" \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "Example",
"slug": "example",
"description": "description of the example",
"discovery_queries": [
"SELECT 1 FROM users WHERE username like 'www%';"
],
"shard": 50,
"event_routing_key": "",
"created_at": "2023-02-02T07:30:42.133421",
"updated_at": "2023-02-02T07:30:42.133434"
}
Update a Pack.
- method: PUT
- Content-Type: application/json
- Required permission:
osquery.update_pack
<int:pk>
: The primary key of the pack.- Required fields:
name
: Name of the pack.
Example
pack_update.json
{
"name": "Example Updated",
"description": "description of the example updated",
"discovery_queries": ["SELECT 1 FROM users WHERE username like 'www%';"],
"shard": 30
}
$ curl -X PUT \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/packs/2/" \
-d @pack_update.json \
|python3 -m json.tool
Response:
{
"id": 2,
"name": "Example Updated",
"slug": "example-updated",
"description": "description of the example updated",
"discovery_queries": [
"SELECT 1 FROM users WHERE username like 'www%';"
],
"shard": 30,
"event_routing_key": "",
"created_at": "2023-02-02T07:30:42.133421",
"updated_at": "2023-02-02T07:32:55.258776"
}
Delete a Pack.
- method: DELETE
- Required permission:
osquery.delete_pack
<int:pk>
: The primary key of the pack.
Example
$ curl -X DELETE \
-H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/packs/2/"
Response (204 No Content)
/api/osquery/packs/<slug:slug>
/
Create or update a standard Osquery pack.
- method:
PUT
,DELETE
This endpoint is designed to create or update a standard Osquery pack.
Examples
pack.json
{
"name": "First pack",
"platform": "darwin",
"queries": {
"Leverage-A_1": {
"query" : "select * from launchd where path like '%UserEvent.System.plist';",
"interval" : "3600",
"version": "1.4.5",
"description" : "(http://www.intego.com/mac-security-blog/new-mac-trojan-discovered-related-to-syria/)",
"value" : "Artifact used by this malware"
},
"Leverage-A_2": {
"query" : "select * from file where path = '/Users/Shared/UserEvent.app';",
"interval" : "3600",
"version": "1.4.5",
"description" : "(http://www.intego.com/mac-security-blog/new-mac-trojan-discovered-related-to-syria/)",
"value" : "Artifact used by this malware"
}
}
}
PUT
the pack.json file to Zentral:
$ curl -XPUT \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
-d @pack.json \
"https://zentral.example.com/api/osquery/packs/first-pack-slug/" \
|python3 -m json.tool
You should get a response close to this one:
{
"pack": {
"pk": 1,
"slug": "first-pack-slug"
},
"result": "created",
"query_results": {
"created": 2,
"deleted": 0,
"present": 0,
"updated": 0
}
}
If you PUT
the same file again, you will get this answer:
{
"pack": {
"pk": 1,
"slug": "first-pack-slug"
},
"result": "present",
"query_results": {
"created": 0,
"deleted": 0,
"present": 2,
"updated": 0
}
}
If you make a DELETE
request on the same URL, the pack and all its rules will be deleted:
$ curl -XDELETE \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
"https://zentral.example.com/api/osquery/packs/first-pack-slug/" \
|python3 -m json.tool
You should get a response close to this one:
{
"pack": {
"pk": 1,
"slug": "first-pack-slug"
},
"result": "deleted",
"query_results": {
"created": 0,
"deleted": 2,
"present": 0,
"updated": 0
}
}
If the pack is in the osquery format (broken JSON), with line-wrapping characters, or comments, use the application/x-osquery-conf
content type.
pack.conf (Real examples are available in the osquery repository.)
{
// Do not use this query in production!!!
"platform": "darwin",
"queries": {
"WireLurker": {
"query" : "select * from launchd where \
name = 'com.apple.periodic-dd-mm-yy.plist';",
"interval" : "3600",
"version": "1.4.5",
"description" : "(https://github.com/PaloAltoNetworks-BD/WireLurkerDetector)",
"value" : "Artifact used by this malware - ๐ฅ"
# ๐งจ
}
}
}
$ curl -XPUT \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/x-osquery-conf' \
--data-binary @pack.conf \
"https://zentral.example.com/api/osquery/packs/second-pack-slug/" \
|python3 -m json.tool
You should get a response close to this one:
{
"pack": {
"pk": 2,
"slug": "second-pack-slug"
},
"result": "created",
"query_results": {
"created": 1,
"deleted": 0,
"present": 0,
"updated": 0
}
}
You can also use a YAML payload, with the application/yaml
content type.
pack.yml
---
# Do not use this query in production!!!
platform: "darwin"
queries:
WireLurker:
query: >-
select * from launchd where
name = 'com.apple.periodic-dd-mm-yy.plist';
interval: 3600
version: 1.4.5
description: (https://github.com/PaloAltoNetworks-BD/WireLurkerDetector)
value: Artifact used by this malware - ๐ฅ
$ curl -XPUT \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/yaml' \
--data-binary @pack.yml \
"https://zentral.example.com/api/osquery/packs/second-pack-slug/" \
|python3 -m json.tool
You should get a response close to this one:
{
"pack": {
"pk": 2,
"slug": "third-pack-slug"
},
"result": "present",
"query_results": {
"created": 0,
"deleted": 0,
"present": 0,
"updated": 1
}
}
/api/osquery/pack_queries/
List all Pack Queries.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_packquery
- Optional filter parameter:
pack_id
: primary key of the pack.
Examples:
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/pack_queries/" \
|python3 -m json.tool
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/pack_queries/?pack_id=2" \
|python3 -m json.tool
Response:
[
{
"id": 1,
"pack": 2,
"query": 1,
"slug": "apps2",
"interval": 60,
"log_removed_actions": true,
"snapshot_mode": false,
"shard": null,
"can_be_denylisted": false,
"created_at": "2023-01-18T07:33:49.207023",
"updated_at": "2023-01-18T07:33:49.207035"
}
]
Add a new Pack Query.
- method: POST
- Content-Type: application/json
- Required permission:
osquery.add_packquery
- Required fields:
pack
: primary key of an existing pack.query
: primary key of an existing query.interval
: interval in seconds.
Example:
packquery.json
{
"pack": 3,
"query": 3,
"interval": 120,
"log_removed_actions": true,
"snapshot_mode": false,
"shard": 50,
"can_be_denylisted": false
}
$ curl -X POST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/pack_queries/" \
-d @packquery.json \
|python3 -m json.tool
Response:
{
"id": 2,
"pack": 3,
"query": 3,
"slug": "test-3673763",
"interval": 120,
"log_removed_actions": true,
"snapshot_mode": false,
"shard": 50,
"can_be_denylisted": false,
"created_at": "2023-02-03T11:54:19.190120",
"updated_at": "2023-02-03T11:54:19.190130"
}
/api/osquery/pack_queries/<int:pk>
/
Get a Pack Query.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_packquery
<int:pk>
: The primary key of the packquery.
Example
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/pack_queries/2/" \
|python3 -m json.tool
Response:
{
"id": 2,
"pack": 3,
"query": 3,
"slug": "test-3673763",
"interval": 120,
"log_removed_actions": true,
"snapshot_mode": false,
"shard": 50,
"can_be_denylisted": false,
"created_at": "2023-02-03T11:54:19.190120",
"updated_at": "2023-02-03T11:54:19.190130"
}
Update a Pack Query.
- method: PUT
- Content-Type: application/json
- Required permission:
osquery.update_packquery
<int:pk>
: The primary key of the packquery.- Required fields:
pack
: primary key of an existing pack.query
: primary key of an existing query.interval
: interval in seconds.
Example
packquery_update.json
{
"pack": 3,
"query": 3,
"interval": 60,
"log_removed_actions": false,
"snapshot_mode": true,
"shard": 10,
"can_be_denylisted": false
}
$ curl -X PUT \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H "Content-Type: application/json" \
"https://zentral.example.com/api/osquery/pack_queries/2/" \
-d @packquery_update.json \
|python3 -m json.tool
Response:
{
"id": 2,
"pack": 3,
"query": 3,
"slug": "test-3673763",
"interval": 60,
"log_removed_actions": false,
"snapshot_mode": true,
"shard": 10,
"can_be_denylisted": false,
"created_at": "2023-02-03T11:54:19.190120",
"updated_at": "2023-02-03T11:55:55.902529"
}
Delete a Pack Query.
- method: DELETE
- Required permission:
osquery.delete_packquery
<int:pk>
: The primary key of the packquery.
Example
$ curl -X DELETE \
-H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/pack_queries/2/"
Response (204 No Content)
/api/osquery/queries/
List all queries.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_query
- Optional filter parameter:
name
: name of the query.
Examples
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/queries/" \
|python3 -m json.tool
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/queries/?name=GetApps" \
|python3 -m json.tool
Response:
[
{
"id": 1,
"compliance_check_enabled": false,
"name": "GetApps",
"sql": "SELECT * FROM apps;",
"platforms": [],
"minimum_osquery_version": null,
"description": "Get list of Apps",
"value": "",
"version": 2,
"created_at": "2023-01-13T07:10:12.571288",
"updated_at": "2023-01-13T09:24:39.779067"
}
]
Add a new query.
- method: POST
- Content-Type: application/json
- Required permission:
osquery.add_query
NOTE:
compliance_check_enabled: true
only possible if sql query containsztl_status
.
Example
query.json
{
"compliance_check_enabled": false,
"name": "GetApps",
"sql": "SELECT * FROM apps;"
}
$ curl -X POST \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
-d @query.json \
"https://zentral.example.com/api/osquery/queries/" \
|python3 -m json.tool
Response:
{
"id": 1,
"compliance_check_enabled": false,
"name": "GetApps",
"sql": "SELECT * FROM apps;",
"platforms": [],
"minimum_osquery_version": null,
"description": "Get list of Apps",
"value": "",
"version": 1,
"created_at": "2023-01-13T07:10:12.571288",
"updated_at": "2023-01-13T09:24:39.779067"
}
/api/osquery/queries/<int:pk>
/
Get a query.
- method: GET
- Content-Type: application/json
- Required permission:
osquery.view_query
<int:pk>
: the primary key of the query.
Example
$ curl -H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/queries/1/" \
|python3 -m json.tool
Response:
{
"id": 1,
"compliance_check_enabled": false,
"name": "GetApps",
"sql": "SELECT * FROM apps;",
"platforms": [],
"minimum_osquery_version": null,
"description": "Get list of Apps",
"value": "",
"version": 1,
"created_at": "2023-01-13T07:10:12.571288",
"updated_at": "2023-01-13T09:24:39.779067"
}
Update a query.
- method: PUT
- Content-Type: application/json
- Required permission:
osquery.update_query
<int:pk>
: the primary key of the query.
Example
query_update.json
{
"name": "GetUsers",
"sql": "SELECT * FROM users;"
}
$ curl -X PUT \
-H "Authorization: Token $ZTL_API_TOKEN" \
-H 'Content-Type: application/json' \
-d @query_update.json \
"https://zentral.example.com/api/osquery/queries/1/" \
|python3 -m json.tool
Response:
{
"id": 1,
"compliance_check_enabled": false,
"name": "GetUsers",
"sql": "SELECT * FROM users;",
"platforms": [],
"minimum_osquery_version": null,
"description": "Get list of Apps",
"value": "",
"version": 2,
"created_at": "2023-01-14T07:10:12.571288",
"updated_at": "2023-01-14T09:24:39.779067"
}
Delete a query.
- method: DELETE
- Required permission:
osquery.delete_query
<int:pk>
: the primary key of the query.
Example
$ curl -X DELETE \
-H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/queries/1/"
Response (204 No Content)
/api/osquery/runs/<int:pk>/results/export/
Trigger a Osquery run export task.
- method: POST
- required permissions:
osquery.view_distributedqueryresult
- optional parameter:
export_format
: One ofcsv
,ndjson
orjson
. Defaults tocsv
.
Use this endpoint to trigger a Osquery run export task. The result of this task will be a file containing all the data collected during the run.
Example
curl -XPOST \
-H "Authorization: Token $ZTL_API_TOKEN" \
"https://zentral.example.com/api/osquery/runs/1/results/export/" \
|python3 -m json.tool
Response
{
"task_id": "b1512b8d-1e17-4181-a1c3-93a7243fddd3",
"task_result_url": "/api/task_result/b1512b8d-1e17-4181-a1c3-93a7243fddd3/"
}