Packages API
While Packages can be installed, examined, and exported from the UI, the Packages API enables you to install, export, and analyze Packages using any REST client. This is useful when you want to automate some aspects of package management, such as an update to an installed package.
Note
This API is authenticated using a Personal API Token.
It is also possible to install packages using the GraphQL API, specifically installPackageFromZip() .
Endpoints
There are three endpoints exposed by this API: install
,
export
, and analyze
.
In the table ${HOST}
is the host name or IP address,
and ${PORT}
is the TCP/IP port. For LogScale
cloud deployments, SSL/TLS is enabled. The following table lists the
available endpoints and their use case:
Endpoint | Use Case |
---|---|
${HOST}:${PORT}/api/v1/packages/install
| Used to install a package from a Zip file. The Zip file containing the package is provided as part of the request. |
${HOST}:${PORT}/api/v1/packages/export
| Used to create a package using the resources specified. A Zip file containing the package is returned. |
${HOST}:${PORT}/api/v1/packages/analyze
| Used to analyze a package before installation. You can check a package in the Package Marketplace, or check against a package provided in a Zip file. This is useful for gaining insight into a package, and avoiding potential conflicts or errors. |
Installing a Package
The Packages API install
endpoint enables you to
install a package from a provided Zip file.
This POST
request uses query parameters, and includes a
Zip file containing the package in the request. The query parameters for
requests are shown in the following table:
Query Parameter | Description |
---|---|
view
| String. The repository or view to install the package into. |
overwrite
|
Boolean. If true , and the package is already
installed, it is overwritten.
|
queryOwnershipType
|
String. Can be one of user or
organization . If user then
queries are run on behalf of the user. If
organization , queries run on behalf of the
organization. If installing a package to the sandbox you need to
set the value to user .
|
You need to pass the Zip file containing the package to be installed to the endpoint.
Examples
The following example installs a package into the user's
sandbox
repository, and queries are run on behalf of
the user.
curl -v -X POST '${HOST}:${PORT}/api/v1/packages/install?view=sandbox&overwrite=true&queryOwnershipType=user' \
-H "Authorization: Bearer $PERSONAL_API_TOKEN" \
-H 'Accept: application/json, multipart/mixed' \
-H 'Content-Type: multipart/form-data' \
-F 'file=@test-package.zip'
Note that in this example, the package is installed over an existing
version of the package. If the package existed but you did not set
overwrite
to true
, then the request
fails with an error message response such as the following:
{
"installationErrors": [
"Package already installed. You can force update it by setting `overwriteIfAlreadyInstalled` to true"
],
"parseErrors": [],
"responseType": "PackageErrorReport"
}
Exporting a Package
The Packages API export
endpoint enables you to export
specifed resources to a package. The package is exported as a Zip file.
You specify the resources you want to include in the package in a JSON
body to a POST
request. The fields you can provide in
the JSON body are listed in the following table:
Field | Description |
---|---|
version
|
Required. The version you want to
assign to the package, for example, 0.1.0 .
|
packageName
|
Required. The name you want to
assign to the package. This has the format
packagescope/packagename , for example,
akamai/asec , or apache/http-server .
|
viewName
| Required. The name of the repository of view in which the resources to be exported to the package exist. |
packageType
|
Required. The value can be
application or library . If
application , then all specifed components are
installed when the package is installed. If
library , specified compponents are not
installed when the package is installed, and need to be created
individually from a component template before usage.
|
author
| The author name for the package. This is displayed in the package information panel in LogScale. |
authorEmail
| An email address for the author of the package. This is displayed in the package information panel in LogScale. |
iconUrl
|
The URL to an icon for the package. The icon should be a 64x64
pixel PNG or SVG file. The URL can be a direct HTTP URL or a
Base64 encoded data URL. The data URL is the preferred option. A
data URL has the format: data:image/png;base64,
iVB0ORw0kg... . A default icom is provided if none is
specified here.
|
licenseUrl
| A URL to the license you want to apply to your package. This is displayed in the package information panel in LogScale. The default is to link to an Apache 2.0 license. |
description
| This is a short description of the package that you see when the package is listed in the installed packages panel of LogScale. This helps identify the main purpose of the package, which is helpful when many packages are installed. |
readme
|
Any README text about the package you would
like to display. This is displayed in the package information
panel in LogScale. The text also appears in a
README.md in the package. You can use
Markdown in the text used here.
|
dashboardIds
| An array of IDs for the dashboards you want to include in the package. The IDs can be obtained by using the GraphQL API. |
alertIds
| An array of IDs for the alerts you want to include in the package. The IDs can be obtained by using the GraphQL API. |
filterAlertIds
| An array of IDs for the filter alerts you want to include in the package. The IDs can be obtained by using the GraphQL API. |
aggregateAlertIds
| An array of IDs for the aggregate alerts you want to include in the package. The IDs can be obtained by using the GraphQL API. |
parserIds
| An array of IDs for the parsers you want to include in the package. The IDs can be obtained by using the GraphQL API. |
savedQueryIds
| An array of IDs for the queries you want to include in the package. The IDs can be obtained by using the GraphQL API. |
actionIds
| An array of IDs for the actions you want to include in the package. The IDs can be obtained by using the GraphQL API. |
scheduledSearchIds
| An array of IDs for the scheduled searches you want to include in the package. The IDs can be obtained by using the GraphQL API. |
viewInteractionIds
| An array of IDs for the view interactions you want to include in the package. The IDs can be obtained by using the GraphQL API. |
includeLabels
|
A boolean value. If true , any labels assigned
to resources are included in the package. Default is
false .
|
fileNames
| An array of any lookup files you want to be included in the package. These are JSON or CSV files that you already uploaded into LogScale. They can be viewed or uploaded in the UI under the main menu item. |
Note
See the documentation for general information on Packages, and especially the documentation for Package File Formats, which describes many of the fields mentioned in the previous table in much more detail.
Examples
When you're in the planning stages of building your package, it can be useful to get a list of IDs for resources you may want to include in the package. For example, using the GraphQL API, you could get a list of queries, and their IDs, using the following Curl command:
curl -v -X POST ${HOST}:${PORT}/graphql \
-H "Authorization: Bearer $PERSONAL_API_TOKEN" \
-H "Content-Type: application/json" \
-d @- << EOF
{
"query" : "query {
repository(name: \"sandbox\", includeHidden: false) {
name, id, type, dataType, savedQueries {
id, name, displayName, labels
}
}
}"
}
EOF
Would give a response similar to the following:
{
"data": {
"repository": {
"name": "sandbox_Gnam4KWNEr3fdFUiFHh7NaJI",
"id": "sandbox_Gnam4KWNEr3fdFUiFHh7NaJI",
"savedQueries": [
{
"id": "a7pWyzMR5C8d8Bug8iBPrcoJXkhunAJD",
"name": "Three CPUs",
"displayName": "Three CPUs"
},
{
"id": "fbFvMCuYkZf85nrjTMLHiEt1aG6eHFBG",
"name": "humioquery",
"displayName": "humioquery"
}
],
"dataType": "ANYDATA",
"type": "PERSONAL"
}
}
}
You can see the names and IDs in the response. See repository() for more details on this GraphQL query.
When you've identified the resources you want to include in a package, you can export the package by running a Curl command to such as the following:
curl -v -X POST '${HOST}:${PORT}/api/v1/packages/export' \
-H "Authorization: Bearer $PERSONAL_API_TOKEN" \
-H 'Accept: application/zip' \
-H 'Content-Type: application/json' \
-d '{"fileNames": ["test.csv"], "packageName": "fbscope/fbname", "version": "0.0.1", "viewName": "sandbox", "packageType": "application", "savedQueryIds": ["fbFvMCuYkZf85nrjTMLHiEt1aG6eHFBG"], "parserIds": ["kv-generic", "json"], "actionIds": ["kZuZjfuWx2D7XqP3FgEoZ0ePnF5WFbK4"]}' \
--compressed -o exported.zip
Analyzing a Package
The Packages API analyze
endpoint enables you to
analyze a package, prior to installation. You do this when you want to
analyze a package from the Package Marketplace, or you
want to analyze a package before you install it. This enables you to
identify potential conflicts with existing packages or other issues before
installing the package.
Query Parameter | Description |
---|---|
view
| The repository or view you are analyzing the package against. Packages are always installed to a specific repository or view. |
packageSpecifier
|
If you are analyzing a package in the Marketplace, you need to
specify the package scope, package name, and version using the
format packagescope/packagename@version . For example,
apache/http-server@1.0.1 .
|
Examples
To analyze the apache/http-server
package in the
marketplace, using the sandbox
repository:
curl -X POST '${HOST}:${PORT}/api/v1/packages/analyze?view=sandbox&packageSpecifier=apache/http-server@1.0.1' \
-H "Authorization: Bearer $PERSONAL_API_TOKEN" \
-H 'Accept: application/json'
An example response is:
{
"ignoredFiles": [],
"packageEntityResultsJson": [
{
"description": "Apache error log analysis (var/log/apache2/error.log)",
"entityType": "Dashboard",
"name": "Error log analysis",
"status": "New"
},
{
"description": "Domains extracted from the `referer` field matching known indicators of compromise (IOC)",
"entityType": "Dashboard",
"name": "IOC matches for referer domain",
"status": "New"
},
{
"description": "Visitor insights analysis (from access logs)",
"entityType": "Dashboard",
"name": "Visitor insights",
"status": "New"
},
{
"description": "Apache HTTP error analysis (from access logs)",
"entityType": "Dashboard",
"name": "HTTP errors",
"status": "New"
},
{
"description": "Overview dashboard for Apache access logs",
"entityType": "Dashboard",
"name": "Overview",
"status": "New"
},
{
"description": "IP addresses from `client_ip` field matching known indicators of compromise (IOC)",
"entityType": "Dashboard",
"name": "IOC matches for client IP",
"status": "New"
},
{
"entityType": "Parser",
"name": "apache_access",
"status": "New"
},
{
"entityType": "Parser",
"name": "apache_error",
"status": "New"
},
{
"entityType": "File",
"name": "status_code.csv",
"status": "New"
}
],
"packageManifestResultJson": {
"description": "Assets for monitoring Apache HTTP servers",
"logoUrl": "data:image/png;base64, iVB...xyz",
"name": "apache/http-server",
"packageType": "application",
"status": "New",
"version": "1.0.1"
},
"responseType": "PackageAnalysisResultJson"
}
To analyze a provided Zip file, against the sandbox
repository:
curl -X POST '${HOST}:${PORT}/api/v1/packages/analyze?view=sandbox' \
-H "Authorization: Bearer $PERSONAL_API_TOKEN" \
-H 'Accept: application/json, multipart/mixed' \
-H 'Content-Type: multipart/form-data' \
-F 'file=@test-package.zip'
If the same version of the package was already installed you'd get a response such as the following:
{
"existingVersion": "0.1.0",
"ignoredFiles": [],
"packageEntityResultsJson": [
{
"entityType": "SavedQuery",
"name": "Three CPUs",
"status": "Unchanged"
}
],
"packageManifestResultJson": {
"description": "Test package do not use",
"name": "testscope/testpackage",
"packageType": "application",
"status": "Unchanged",
"version": "0.1.0"
},
"responseType": "PackageAnalysisResultJson"
}
You can see in this case that the installed package is the same as the one specified in the request.
If the package was not already installed you would get a response such as the following:
{
"ignoredFiles": [],
"packageEntityResultsJson": [
{
"entityType": "SavedQuery",
"name": "Three CPUs",
"status": "New"
}
],
"packageManifestResultJson": {
"description": "Test package do not use",
"name": "testscope/testpackage",
"packageType": "application",
"status": "New",
"version": "0.1.0"
},
"responseType": "PackageAnalysisResultJson"
}
This indicates it would be a new package, that contains a single new resource, a saved query.