Using the Python OpenDXL Client

This article walks through the process of installing, provisioning, and running a subset of the samples that are included with the OpenDXL Python Client.


The samples examined in this article demonstrate how to use the two distinct messaging models that are supported by DXL. A publish/subscribe event-based model and a service-based model with point-to-point (request/response) communication.

Client Installation and Provisioning

The following steps detail how to install and provision the OpenDXL Python Client:

Event-based Communication

The DXL fabric supports an event-based communication model. This model is typically referred to as “publish/subscribe” wherein clients register interest by subscribing to a particular topic and publishers periodically send events to that topic. The event is delivered by the DXL fabric to all of the currently subscribed clients for the topic. Therefore, a single event sent can reach multiple clients (one-to-many). It is important to note that in this model the client passively receives events when they are sent by a publisher.




For example, McAfee Advanced Threat Defense (ATD) servers send events to the topic /mcafee/event/atd/file/report when they have successfully determined the reputation of a submitted file. Any clients currently subscribed to this topic will receive the report and can take immediate action.

Run Sample

A "basic event sample" is included with the OpenDXL Python Client SDK that demonstrates sending and receiving 1000 events via the Python client.


To run the sample execute the following from the root directory of the extracted OpenDXL Python Client SDK:


python sample\basic\event_example.py

Sample Output

The output should appear similar to the following (1000 events are received and timing information is displayed).

Code Details

This section walks through the different portions of code that comprise the "basic event sample" in detail. Full code for the sample is available within the extracted SDK or via the OpenDXL Python Client GitHub Repository.


As shown above, several variables are defined in the header of the "basic event sample":

  • EVENT_TOPIC: The topic that the events will be sent (and received) on:
    • /isecg/sample/basicevent
  • TOTAL_EVENTS: The total number of events to send (1000)
  • event_count_condition: While not critical to understanding the basic DXL event concepts, this condition (and associated lock) is used to control how incoming events are tracked (they will be received on multiple threads)
  • event_count: Tracks the number of events that have been received


Python: Connecting to the DXL fabric
  1. # Create DXL configuration from file
  2. config = DxlClientConfig.create_dxl_config_from_file(CONFIG_FILE)
  4. # Create the client
  5. with DxlClient(config) as client:
  7. # Connect to the fabric
  8. client.connect()


The next portion of code (shown above) connects to the DXL fabric. The first step is to create a DxlClientConfig object that contains the information necessary to connect to a DXL fabric. In this particular sample, the create_dxl_config_from_file method was used to create a configuration object from a configuration file.


The next line of code creates a DxlClient object by passing the previously created configuration object to its constructor. It is also important to note that the client is created using the Python with statement. While not necessary, the withstatement provides a simple way to control the lifetime of the client object and will automatically clean up any client-related resources when the client block ends (you do not need to explicitly call disconnect or destroy).


In the final line of code above, the connect method is invoked to connect to the DXL fabric.



The next portion of code (shown above) registers an event callback that will receive events that are published to the /isecg/sample/basiceventtopic.


The first step is to derive an event callback (MyEventCallback) from the EventCallback base class and override the on_event method. This method will be invoked for each event that is sent to the DXL fabric for topics that are associated with the callback. The main portion of this method displays the payload of the event received and increments the total count of events. While not critical to understanding the basic DXL event concepts, the event_count_condition condition is used to limit the increment code to one thread at a time. Further, the condition is used to notify that another event has been received.


The final line in this portion of code registers the newly created callback with the /isecg/sample/basicevent topic by invoking the add_event_callback method on the client.


Python: Send Events
  1. # Loop and send the events
  2. for event_id in range(TOTAL_EVENTS):
  3. # Create the event
  4. event = Event(EVENT_TOPIC)
  5. # Set the payload
  6. event.payload = str(event_id).encode()
  7. # Send the event
  8. client.send_event(event)


The next portion of code (shown above) sends out 1000 events on the /isecg/sample/basicevent topic.


The body of the for loop is iterated for TOTAL_EVENTS times (1000). The first step in the body of the for loop is to construct a new Event that will be sent to the /isecg/sample/basicevent topic. Next, a payload is set on the event that contains the index of the loop (from 0 to 999). The final line of the loop body sends the event to the DXL fabric by invoking the send_event method on the client.


Python: Wait for Events to be Received
  1. # Wait until all events have been received
  2. print "Waiting for events to be received..."
  3. with event_count_condition:
  4. while event_count[0] < TOTAL_EVENTS:
  5. event_count_condition.wait()
  7. # Print the elapsed time
  8. print "Elapsed time (ms): " + str((time.time() - start) * 1000)


The final portion of code waits for all of the events to be received by the registered callback.


While not critical to understanding the basic DXL event concepts, the event_count_condition condition is used to wait for TOTAL_EVENTS to be received. Once all of the events have been received the elapsed time for the sample is displayed.

Service-based Communication

The DXL fabric allows for “services” to be registered and exposed that respond to requests sent by invoking clients. This communication is point-to-point (one-to-one), meaning the communication is solely between an invoking client and the service that is being invoked. It is important to note that in this model the client actively invokes the service by sending it requests.


For example, the McAfee Threat Intelligence Exchange (TIE) service is exposed via DXL allowing for DXL clients to actively request reputations for files and certificates.



Run Sample

A "basic service sample" is included with the OpenDXL Python Client SDK that demonstrates registering and invoking a DXL service.


To run the sample execute the following from the root directory of the extracted OpenDXL Python Client SDK:


python sample\basic\service_example.py

Sample Output

The output should appear similar to the following (a request is received by the service and it delivers a response back to the invoking client).


Python: Sample Output
  1. Service received request payload: ping
  2. Client received response payload: pong

Code Details

This section walks through the different portions of code that comprise the "basic service sample" in detail. Full code for the sample is available within the extracted SDK or via the OpenDXL Python Client GitHub Repository.


Python: Define Service Topic
  1. # The topic for the service to respond to
  2. SERVICE_TOPIC = "/isecg/sample/basicservice"


As shown above, a variable is defined that contains a topic to associate with the service. Multiple topics can be associated with a service, each topic represents a different "method" that can be invoked by remote DXL clients.


The next portion of the sample connects to the DXL fabric. This code is identical to the "Connecting to the DXL fabric" portion detailed in the "Event-based Communication" sample above and therefore is not detailed here.



The next portion of code (shown above) registers a DXL service that will respond to requests that are received on the /isecg/sample/basicservice topic.


The first step is to derive a request callback (MyRequestCallback) from the RequestCallback base class and override the on_request method. This method will be invoked for each request that is sent to the DXL fabric for the service topic that is associated with the callback.


The implementation of the on_request method displays the payload of the Request message that was received. Next, it creates a Response message that will be sent back to the invoking client. The payload of the Response message is set to "pong". The last line of this method sends the response back to the invoking client by passing the newly created Response object to the send_response method of the client.


The final three lines in this portion create a service registration, associate the newly created request callback with a service topic, and register the service with the DXL fabric. A ServiceRegistrationInfo object is created which represents the service (named "myService") to register. The service topic /isecg/sample/basicservice is associated with the request callback by invoking the add_topic method of the service registration object. Finally, the service is registered with the DXL fabric by passing the service registration object to the register_service_sync method of the client.



The next portion of code (shown above) invokes the DXL service that was registered in the previous code portion and displays the information contained in the received response.


The first step is to create a Request message that will be sent to the /isecg/sample/basicservice topic. The payload of the Request object is set to "ping".


Next, the service is invoked by passing the newly created Request object to the sync_request method of the client. This method will wait until a Response is received from the service or a timeout occurs.


Finally, the message_type is checked to ensure the Response received is not an ErrorResponse. If it is not an error, the payload associated with the Response message is displayed.

Next Steps

Refer to the Python OpenDXL Bootstrap Application guide to learn how you can significantly reduce the time necessary to create an OpenDXL solution.