Python application tutorial: Part 1

This tutorial explains how you can implement a Python application that sends and receives data from Kaspersky CyberTrace.

Part 1 of this tutorial describes an application that sends data to Kaspersky CyberTrace.

Part 2 of this tutorial describes an application that listens for incoming events from Kaspersky CyberTrace.

Introduction

In this part of the tutorial, you implement a Python application that sends data to Kaspersky CyberTrace. Kaspersky CyberTrace analyzes the received data for matched indicators. If there are matched indicators, Kaspersky CyberTrace sends its own events in response.

You can use any name for your application. This tutorial uses the send_events_cybertrace.py file name for this application in the examples.

We recommend using Python 3 for implementing this application. Code examples in this tutorial use the Python 3 syntax.

About the X-KF-ReplyBack flag

In this part of the tutorial, your application uses the X-KF-ReplyBack flag to receive events from Kaspersky CyberTrace without a listener application. You will implement an application that listens for Kaspersky CyberTrace events in Part 2 of this tutorial.

The X-KF-ReplyBack flag enables the ReplyBack mode. In this mode, Kaspersky CyberTrace sends its detection events to the same socket connection.

This flag is optional. If your application does not send this flag, Kaspersky CyberTrace sends its own events as specified in the OutputSettings > ConnectionString parameter.

About the X-KF-SendFinishedEvent flag

Your application uses the X-KF-SendFinishedEvent flag to make Kaspersky CyberTrace generate a special event in response to each received event.

Kaspersky CyberTrace generates this event by using the format specified in the OutputSettings > FinishedEventFormat parameter. The value of the enabled attribute of this parameter is ignored.

About the X-KF-SaveStatistic flag

Your application uses the X-KF-SaveStatistic flag to make Kaspersky CyberTrace save detection statistics for all events received during the current connection. The events will also be saved for retrospective scan.

Stage 1. Define the main() function

In this stage:

Import the socket module.
Your application uses functions from this module to establish connections with Kaspersky CyberTrace and send data.
Define the main() function.
In the CYBERTRACE_ADDR and CYBERTRACE_PORT variables, specify the address and port where Kaspersky CyberTrace listens for incoming events.
You can get this information on the Service settings page in Kaspersky CyberTrace Web.

import socket

CYBERTRACE_ADDR = "192.0.2.42"

CYBERTRACE_PORT = 9999

def main():

pass

if __name__ == '__main__':

main()

Stage 2. Add example events

In this stage:

In the main() function, define a list with example events.

The events in this list contain indicators. Your application sends these events to Kaspersky CyberTrace.

Each event must terminate with a newline character (\n). The newline character acts as a separator for events.

def main():

events = [

'192.0.2.1\n',

'ip=192.0.2.3\n',

'776735A8CA96DB15B422879DA599F474\n',

'EICAR md5=FEAF2058298C1E174C2B79AFFC7CF4DF\n',

'Regular event\n',

'44D88612FEA8A8F36DE82E1278ABB02F\n',

'val1=04BFFABE7980E7D84424001896D2572E val2=0F9CCE3EA0EDFD6F41FF8A769F721631\n',

'val=E9A6B1346D1A2447CABB980F3CC5DD27\n',

'Regular event\n',

'http://5a015004f9fc05290d87e86d69c4b237.com\n',

'Domain: http://fakess123bn.nu\n',

]

Stage 3. Establish a socket connection

In this stage:

In the main() function, add the code that establishes a connection to Kaspersky CyberTrace and closes it when all events are sent.

In this code, send the X-KF-SendFinishedEvent and X-KF-ReplyBack flags.

Send the X-KF-SendFinishedEvent and X-KF-ReplyBack flags when you establish a connection. These flags make Kaspersky CyberTrace always generate an event in response to a received event, even if the received event does not match any indicators.

Send the X-KF-SaveStatistic flag if you want Kaspersky CyberTrace to save detection statistics and events for retroscan during the current connection.

If you want to use the X-KF-ReplyBack flag, the X-KF-SendFinishedEvent flag must precede it.

If you want to use the X-KF-SaveStatistic flag, the X-KF-ReplyBack flag must precede it

ct_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

try:

ct_socket.connect((CYBERTRACE_ADDR, CYBERTRACE_PORT))

ct_socket.sendall(b'X-KF-SendFinishedEventX-KF-ReplyBackX-KF-SaveStatistic')

# Code from the next stage goes here

finally:

ct_socket.close()

Stage 4. Send events

In this stage:

In the code from the previous stage, in the try... finally block, iterate over the events list and send each event to Kaspersky CyberTrace.
The 16384 parameter in the socket.recv() function specifies the size of a message buffer. If you expect a response to contain more than 16384 bytes, increase the buffer value. This may be required if individual events contain a large number of matched indicators.

for event in events:

ct_socket.sendall(event.encode())

response = ct_socket.recv(16384)

Add console output for sent events and received responses.

for event in events:

print("Sending:\n{}".format(event))

ct_socket.sendall(event.encode())

response = ct_socket.recv(16384)

print("Response:\n{}".format(response.decode()))

Stage 5. Run your application

In this stage:

Run your application from the console:
python3 ./send_events_cybertrace.py

Below is an example of the application output. Kaspersky CyberTrace sends an event for each matched indicator and an event for the finished lookup operation.

Sending:

val1=192.0.2.1 val2=ip=192.0.2.3

Response:

- category=KL_IP_Reputation matchedIndicator=192.0.2.1 url=- src=- ip=192.0.2.1 md5=- sha1=- sha256=- usrName=- confidence=100 category=test first_seen=01.01.2017 00:00 ip=192.0.2.1 ip_geo=ru last_seen=16.07.2020 10:02 popularity=1 threat_score=75

- category=KL_IP_Reputation matchedIndicator=192.0.2.3 url=- src=- ip=192.0.2.3 md5=- sha1=- sha256=- usrName=- confidence=100 category=test first_seen=15.01.2017 00:00 ip=192.0.2.3 ip_geo=ru last_seen=16.07.2020 09:51 popularity=1 threat_score=75

LookupFinished

Sending:

EICAR md5=FEAF2058298C1E174C2B79AFFC7CF4DF

Response:

- category=KL_Malicious_Hash_MD5 matchedIndicator=FEAF2058298C1E174C2B79AFFC7CF4DF url=- src=- ip=- md5=FEAF2058298C1E174C2B79AFFC7CF4DF sha1=- sha256=- usrName=- confidence=100 MD5=FEAF2058298C1E174C2B79AFFC7CF4DF SHA1=D01D17F6B13C7255A234F558ED85078EA5DD3F3D SHA256=4CA914C9791CF2BF2AC69F9A2B21006F0361E247F2CE92F0A9F166DBC6B43670 file_size=1989 first_seen=10.07.2015 23:53 last_seen=13.07.2020 14:35 popularity=1 threat=HEUR:Trojan.Win32.Generic

LookupFinished

Sending:

Regular event

Response:

LookupFinished

Full code for Part 1

Below is the full code for Part 1 of this tutorial.

import socket

CYBERTRACE_ADDR = "192.0.2.42"

CYBERTRACE_PORT = 9999

def main():

events = [

'192.0.2.1\n',

'ip=192.0.2.3\n',

'val1=192.0.2.1 val2=ip=192.0.2.3\n',

'776735A8CA96DB15B422879DA599F474\n',

'EICAR md5=FEAF2058298C1E174C2B79AFFC7CF4DF\n',

'Regular event\n',

'44D88612FEA8A8F36DE82E1278ABB02F\n',

'val1=04BFFABE7980E7D84424001896D2572E val2=0F9CCE3EA0EDFD6F41FF8A769F721631\n',

'val=E9A6B1346D1A2447CABB980F3CC5DD27\n',

'Regular event\n',

'http://5a015004f9fc05290d87e86d69c4b237.com\n',

'Domain: http://fakess123bn.nu\n',

]

ct_socket = socket.socket(socket.AF_INET, socket.SOCK_STREAM)

try:

ct_socket.connect((CYBERTRACE_ADDR, CYBERTRACE_PORT))

ct_socket.sendall(b'X-KF-SendFinishedEventX-KF-ReplyBackX-KF-SaveStatistic')

for event in events:

print("Sending:\n{}".format(event))

ct_socket.sendall(event.encode())

response = ct_socket.recv(16384)

print("Response:\n{}".format(response.decode()))

finally:

ct_socket.close()

if __name__ == '__main__':

main()

Page top