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.

shell
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:

json
{
  "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 Files 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:

shell
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:

json
{
  "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:

shell
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:

shell
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:

json
{
  "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:

shell
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:

json
{
  "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:

json
{
  "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.