Basic Paging Sample

This sample executes a McAfee Active Response search for the running processes on a particular endpoint as specified by its IP address.

The names of the processes are received in pages and displayed.

Prerequisites

• The samples configuration step has been completed (see Samples Configuration)
• A McAfee Active Response (MAR) Service is available on the DXL fabric
• The Python client has been authorized to perform MAR searches (see Authorize Client To Perform MAR Search in the OpenDXL Python SDK Documentation)

Configuration

Update the following line in the sample:

HOST_IP = "<SPECIFY_IP_ADDRESS>"

To specify the IP address of a host to retrieve the process list from. For Example:

HOST_IP = "192.168.1.1"

Running

To run this sample execute the sample/basic/basic_paging_example.py script as follows:

c:\dxlmarclient-python-sdk-0.2.1>python sample/basic/basic_paging_example.py

The output should appear similar to the following:

Page: 1
    MARService.exe
    OneDrive.exe
    RuntimeBroker.exe
    SearchIndexer.exe
    SearchUI.exe
Page: 2
    ShellExperienceHost.exe
    SkypeHost.exe
    System
    UpdaterUI.exe
    VGAuthService.exe
Page: 3
    WUDFHost.exe
    WmiApSrv.exe
    WmiPrvSE.exe
    WmiPrvSE.exe
    [System Process]

...

Details

The majority of the sample code is shown below:

# The size of each page
PAGE_SIZE = 5
# The IP address of the host to retrieve the processes for
HOST_IP = "192.168.1.1"

# Create the client
with DxlClient(config) as client:

    # Connect to the fabric
    client.connect()

    # Create the McAfee Active Response (MAR) client
    marclient = MarClient(client)

    # Start the search
    results_context = \
        marclient.search(
            projections=[{
                ProjectionConstants.NAME: "Processes",
            }],
            conditions={
                ConditionConstants.OR: [{
                    ConditionConstants.AND: [{
                        ConditionConstants.COND_NAME: "HostInfo",
                        ConditionConstants.COND_OUTPUT: "ip_address",
                        ConditionConstants.COND_OP: OperatorConstants.EQUALS,
                        ConditionConstants.COND_VALUE: HOST_IP
                    }]
                }]
            }
        )

    # Iterate the results of the search in pages
    if results_context.has_results:
        for index in range(0, results_context.result_count, PAGE_SIZE):
            # Retrieve the next page of results (sort by process name, ascending)
            results = results_context.get_results(index, PAGE_SIZE,
                                                  sort_by="Processes|name",
                                                  sort_direction=SortConstants.ASC)
            # Display items in the current page
            print("Page: " + str((index//PAGE_SIZE)+1))
            for item in results[ResultConstants.ITEMS]:
                print("    " + item[ResultConstants.ITEM_OUTPUT]["Processes|name"])

Once a connection is established to the DXL fabric, a dxlmarclient.client.MarClient instance is created which will be used to perform searches.

Next, a search to collect process information from a particular system (as specified by its IP address) is performed by invoking the dxlmarclient.client.MarClient.search() method of the dxlmarclient.client.MarClient instance.

Once the search has completed, the processes that were found on the system are displayed in pages sorted by process name in ascending order. The dxlmarclient.client.ResultsContext.get_results() method of the dxlmarclient.client.ResultsContext object is invoked for each page that is displayed.

It is also worth noting that in this particular sample constants are used for the key names when describing the search projections and conditions. Constants are also used when processing the results of the search. See the dxlmarclient.constants package for more information on the constants that are available for use with the MAR DXL Python client.

While the use of constants is completely optional, it avoids hard-coding strings that could be mistyped and is especially useful within integrated development environments (IDEs) that perform auto-completion.