Date/Time Packet Search Script via QP-API
- Michael Francisco
This guide will show how to operate the search API using the packet search script.
This script serves two purposes:
To operated packet search using the search API
To learn how the API operates and how to run customized scripts
Supported QManager versions with the QP-API service enabled:
5.4.5.1 (Ubuntu edition)
For the user to use the script it is required for the local unit (or the remote unit) to operate the QP-API. Otherwise the API requests will no go through.
How does it work?:
The script allows the user to operate date/time packet search using the QP-API.
Packet search will take a look at the indexed PCAPs captured by the capture program.
The script will access the API by hostname and will operate over SSL using port 8080
The user will select which directory they would like to search from and will indicate which date and which time range to search from
Once all the parameters have been set, the request is made in a form of a RESTful API and the server will go ahead and perform a search query
If the user is searching from another remote QP, they have an option to download the resulting output PCAP file onto the QP unit that they are working on.
If the user is searching on the same QP that the API is running on then the resulting output PCAP will end up in the designated output PCAP path set in the search parameters.
Steps into running the packet search script:
The QP-API scripts are located in /opt/qpapi_helpers which contain several scripts that can serve as examples on how to create customized scripts with various functionalities such as packet search, capture, managing PCAP files, etc.
1) Go to the qpapi_helpers directory
cd /opt/qpapi_helpers
2) Enable the virtual environment
source /opt/quantea/suite/KENV36/bin/activate or run this alias command
activate36
3) Operating the script itself
The script will have the following options
Search parameters:
Required fields are:
-H (hostname)
-D (directory)
-F (from date)
-f (from time)
-T (to date)
-t (to time)
-O (output file path)
Purpose | Parameter | Example | Notes |
|---|---|---|---|
Show the help menu | -h or --help | python packet_search.py --help |
|
Indicate the hostname (required) | -H or --hostname | python packet_search.py -H qp500unit |
|
Indicate source directory | -D or --directory | -D '/cifs/capture/records/Port0' | Needs single quotes for directory |
Date to search FROM | -F or --fromdate | -F 2024/07/01 | In YYYY/MM/DD format |
Time to search FROM | -f or --fromtime | -f 10:00:00 | In hh:mm:ss format |
Date to search TO | -T or --todate | -T 2024/07/02 | In YYYY/MM/DD format |
Time to search TO | -t or --totime | -t 00:00:00 | In hh:mm:ss format |
Seconds (to be released in the next version) | -S or --seconds | -S 60 | Search the last X seconds from the current time (to be released in the upcoming version) |
Search BPF syntax | -B or --bpf | -B ‘ip host 192.168.1.1’ | Requires singles quotes. See BPF syntax document for more examples. BPF Syntax Document |
Regular expression to search the packet with | -E or --expression | -E ‘google.com’ | Requires single quotes. Follows the regular expression convention. |
Output file | -O or --output | -O '/cifs/capture/permanent/search_output.pcap' | Requires single quotes. This is where the search result output will go to after search is completed. |
Perform a search on a remote QP and download the search results | -R or --remote | -R 1 | This is an optional parameter, this allows the user to search on an external QP and download the PCAP after search has been completed. The parameter will only take ‘-R 1’. |
Debug statement is printed out | -d or --DEBUG | -d 1 | To allow the debug statements to be printed. The parameter will be ‘-d 1’. |
Filter by VLAN ID | --vlan | --vlan 4 | This parameter will search VLAN packets and will write them to the PCAP file. Multiple VLANs can be added by comma separated numbers e.g. 4,1001,2000 |
Filter by VxLAN ID | --vxlan | --vxlan 60 | This parameter will search VxLAN packets with VNI of 60. Multiple VNI’s can be used by inputting comma separated numbers e.g. 70,120,1022 |
4) Examples
Here are several examples for reference: