1.1.6

Converts JSON output from Tshark and converts it to Intermediate Log Format (ILF)

• Capture from local machine
• PCAP files for post processing
• From a remote machine via redis
• NOTE: It is not recommended to attempt to run more than 1 of these modes at a time

• A redis instance accessable by the translator
• dotnet 5 or newer
• Wireshark installed
  • On windows tshark.exe must be added to environment varibles unless you are running the translator in the same directory where tshark.exe is located
  • On linux systems, installing Wireshark will prompt the user if they would like to create a user for Wireshark to allow it to capture traffic without having to be run as root. It is highly recommended you take this path and do not run the translator as root if you do not have to.

• For the smoothest possible experience, have redis running before starting the translator
• Check the Interfaces listed in the local capture section of the configuration. This is the only option that should need to be changed if you are capturing live data from the host where this translator is running.
• TsharkTranslator invokes tshark/tshark.exe on the host machine, so all that is needed is to run the translator by running "dotnet TsharkTranslator.dll" for a compiled version or using the dotnet SDK to build and run the source code
• This will not work on virtual machines or containers if you want to capture the traffic going to the host of those vm's/containers

1. Set REDIS_HOST and REDIS_PASSWORD environment variables
2. Move into tsharkTranslator directory
   • cd tsharkTranslator
3. Edit the Configuration.json file to match your environment
4. Run dotnet run TsharkTranslator

Edit the Configuration.json file to match your environment, according to the following descriptions.

• The only mandatory redis connection is the forwarder connection which sends ILF to redis, which is forwarded to HBL
• For the host and password for Redis, TsharkTranslator will read from the environment variables, so set REDIS_HOST and REDIS_PASSWORD appropriately

• Enabled - Turns on and redis forwarding - this is only used for debugging reasons and should be left on
• Port - Port that the target redis instance uses - almost always 6379
• Channel - which channel to publish the ILF to
• Batch Forward - This will send ILF in batches which can greatly improve performance (not tested with ER learn)
• Minimum ILF buffer length - the minimum number of ILF logs to be sent in each batch - if network is extremely quiet, this can be lowered to prevent a delay in sending ILF

• settings which can modify TsharkTranslator

• Statistics - prints periodic messages that tell the user about the packet rate being encountered
• Regular Status updates - prints periodic messages to confirm program is running
• HeartbeatTick - prints a tick per ILF message for the translator wrapper to put into heartbeat messages - if this is enabled, Statistics and Regular Status updates will be disabled automatically - Exceptions will still be printed
• HeartbeatBatch - the number of ILF messages sent per tick reported (For high traffic scenarios)

• This can be used to receive ilf from a remote machine

• Enabled - Turns redis collection on/off
• Port - Port that the sending redis instance is using - almost alwyas 6379
• Channel - Channel that the logs will be sent on

• Controls tshark instances on the local machine

• Enabled - Turns local tshark capture on/off

• Interfaces - An array that specifies which interfaces to capture on. Works with numbers and names of interfaces \n\t - for linux systems the names of the interfaces are used in the array. On windows systems, run "tshark.exe -D" in CMD to get the interface numbers

• HandoffEnabled - Periodically restart tshark to save memory and allow .pcap files in temp to be removed to save disk space

• HandoffTime - How long between each hand off, measured in seconds

• tempOverride - Specifies a different temp directory than the environment varibles point to

• NoDeletePcap - Pcap files created in temp will not be deleted if enabled

• PCAP files can be placed in a directory to be translated for post mission analysis

• Enabled - Turns on or off pcap replay
• FilePath - Directory where pcap files are located

This is the section where the fields that will be in the ILF are specified. This will need to be coordinated with the writer of the HBL analytics to provide them with the fields needed to run their analytics

• For each layer and field, the "code" and "name" must be provided by the user

  • the code is what tshark refers to that layer or field as
    • These can be found in the wireshark documentation
  • the name is what that layer or field will appear as in the ILF. This is for personal preference and can be anything that the user wants

• If the field is an integer, the integer option should be true to match the event definitions in HBL. Integers are more efficent than strings (which are the alternative) and should be used whenever possible

This is a list in order of what the event types for the ILF will be. To get maximum efficiency out of HBL, event types should be as specific and granular as possible. This will need to be coordinated with the creator of the analytics, along with layers and fields

• These also have both name and code values, with code being what that layer shows up as in the tshark output and name being what the event type will be called
• If the code for the field is default, that name will be the fallback value if none of the other event types are applicable
  • default should only be used on one event type although this is not enforced and the application will go with the first one it encounters
• The list should be in reverse order, starting with default and ending with the most high level layer, i.e. default -> eth -> ip -> tcp/udp
• If the last layer of the packet being translated is not in the list of event types, the event will be given the defualt type

This software is licensed under the Apache 2.0 license.