Package com.paloaltonetworks.cortex.data_lake

A collection of classes to ease the consumption of Palo Alto Networks Cortex API's The main goals of this package are, in one hand, to provide full low-level coverage of the following Cortex API's and, in the other hand, implement convenience high level interfaces to traverse large response sets (to abstract the developer from the tedious task of implementing pagination controls or response parsers). Query Service

Overview

The Library is composed of a HTTP/2 connectivity layer implemented by the Http2Fetch class and by a low-level collection of classes providing access to their corresponding Cortex API's. For instance, the QueryService class is responsible for providing methods to create query jobs, get their running status, retrieve jobs results, etc. Some low-level classes have a high-level companion subclass implementing convenience interfaces to abstract unnecessary complexity to the developer. For instance, the QueryServiceClient implements the java.lang.Iterable and java.util.stream.Stream interfaces to navigate through the results generated by a given query job.

This package provides, as well, a set of helper classes that mimic both the payloads and responses required/provided by the different API's. For instance, the developer can instantiate a QueryParams object be used in the QueryService.createJob(String, QueryParams) method and will receive a QueryJob object instantiated with the JSON parsed response obtained from the API call.

Parsing validity both of the requests and responses is also part of the feature set provided by this package. Checked QueryServiceParseException exceptions are thrown in these conditions. Unchecked QueryServiceParseRuntimeException exceptions are thrown when the developer is using the provided async methods.

Non 2xx/3xx responses provided by the Cortex API are converted into checked QueryServiceException / unchecked QueryServiceRuntimeException exceptions.

Any external exception like java.io.IOException generated by the JAVA runtine or dependant packages is transparently forwarded to the developer.

Installation

Either build from the sources or download an already compiled package from https://github.com/xhoms/pan-cortex-data-lake-java into a folder pointed by your CLASSPATH environment variable. The package has a single dependency: the javax.json API. So you'll need, as well, to download both the API implementation and its Service Provider into a CLASSPATH covered folder.

The package CI/CD build process uses version 1.1.14 of org.glassfish.javax.json and its companion javax.json packages so it is highly recommended to use them in production as well.

Quickstart

This section should give a good indiction of how to get started with this package Querying the Cortex Data Lake

The following very basic example illustrates how to execute a basic SQL job in the Cortex Query API service and navigate through its results using the Iterable interface.

import java.util.Map;
import java.util.Map.Entry;
import java.util.AbstractMap.SimpleImmutableEntry;
import java.util.function.Function;

import com.paloaltonetworks.cortex.data_lake.Constants;
import com.paloaltonetworks.cortex.data_lake.QueryServiceClient;

public class StreamExample {
    private static final String accessToken = "eyJh...yx7Q";
    private static final String sqlCmd = "SELECT * FROM `<instance_id>.firewall.traffic` LIMIT 100";
    private static final Function<Boolean, Map.Entry<String, String>> cred = new Function<Boolean, Map.Entry<String, String>>() {

        @Override
        public Entry<String, String> apply(Boolean force) {
            if (force != null && force) {
                return new SimpleImmutableEntry<String, String>(Constants.USFQDN, accessToken);
            } else {
                return null;
            }
        }
    };

    public static void main(String[] args) throws Exception {
        QueryServiceClient qsc = new QueryServiceClient(cred);
        qsc.stream(sqlCmd).forEach((item) -> System.out.println(item));
    }
}

In this case the developer is instantiating the QueryServiceClient class because he is only interested on running the query and processing the results. The QueryServiceClient takes care of everything (creating the job, polling for it to be completed, paginating through the results and deleting the job once all of them have been consumed). To access all these method individually you migh instantiate the QueryService class instead. But, as they're exposed in the QueryServiceClient as well (subclass), developers might end up working always with the high level implementations of any given service (when available).

A collection of compatible Credentials objects as well as building blocks to interface with Cortex hub OAuth2 authentication is available in the package com.paloaltonetworks.cortex.hub at https://github.com/xhoms/pan-cortex-hub-java

All service classes (QueryServiceClient in this case) provide constructors to reuse a Http2Fetch object so the developer can share the same TLS connection options when working with multiple Cortex services at once. Constructors based on URI atributes are also available. In the previous case, the constructor of the QueryServiceClient object instantiates a mTLS-based Http2Fetch object using provided PKCS12 client certificate filename and password.