Metadata-Version: 2.1
Name: sharkreduce
Version: 0.2.0
Summary: Convenience functionality to annotate and reduce wireshark captures.
Home-page: UNKNOWN
Author: Johannes Abel, Joseph Birkner, Tom Mirwald
License: BSD-3 Clause
Description: # SharkReduce ðŸ¦ˆðŸ”»
        
        Utility to convert wireshark captures to useful datasets.
        
        ## Installation
        
        ```bash
        pip install sharkreduce
        ```
        
        ## Steps to create reduced dataset
        
        ### Step 1: Export capture using tshark
        
        ```bash
        tshark -t e -Ndmnt -r all.pcapng -T fields \
          -e frame.time \
          -e eth.src_resolved \
          -e eth.dst_resolved  \
          -e _ws.col.Source \
          -e _ws.col.Destination \
          -e _ws.col.Protocol \
          -e tcp.len \
          -e udp.length \
          -e tcp.srcport \
          -e tcp.dstport \
          -e udp.srcport \
          -e udp.dstport \
          -e _ws.col.Time '(eth.type == 0x800) or (eth.type == 0x86dd)' > reduceme.tsv
        ```
        
        ### Step 2: Fill device id file
        
        Sharkreduce requires a device mac-address map file to create pretty reduced output.
        
        Run it once to pre-fill the file with all mac IDs from your capture:
        
        ```bash
        python3 -m sharkreduce -t 60000000 -n devices.yaml reduceme.tsv reduced.tsv
        ```
        
        **Note:** `-t 60000000` means that SharkReduce will create reduced bins of
        connections up to 60 seconds.
        
        **Note:** The command will initially create an empty `reduced.tsv`!
        
        The command will create a file called `devices.yaml` which looks like this:
        
        ```yaml
        devices: []
        ignore: {}
        unclassified:
          some-mac-adress:
            - dns-name
            - ip-adress
            - etc.
        ```
        
        For each unclassified mac address, you will see some aliases (IP/Hostname)
        which helps you to determine which device the MAC belongs to.
        
        If the MAC belongs to a device you want to analyse, think of a good name
        and create an entry under `devices`. Otherwise create an entry under `ignored`.
        Do this for all unclassified MACs:
        
        ```yaml
        devices:
          SuspiciousDevice:
            - some-mac-address
            - some-hostname
          OtherInterestingDevice:
            - other-mac
        ignore:
          - router-mac-address
          - broadcast address
        ```
        
        ### Step 3: Create initial reduced output.
        
        Re-run 
        
        ```bash
        python3 -m sharkreduce -t 60000000 -n devices.yaml reduceme.tsv reduced.tsv
        ```
        
        This time `reduced.tsv` should have a lot of data in it, with device identifiers
        that look very readable to you.
        
        ### Step 4: Create/fill activity file
        
        In order to determine activity periods for your devices to correctly
        fill the `active_use` column in the reduced output, you have to create an
        activity file. You can initialise the file like this:
        
        ```bash
        python3 -m sharkreduce --init-activity -t 3600000000 -n devices.yaml reduceme.tsv reduced.tsv
        ```
        
        This will READ from `reduced.tsv` to create a file called `activity.yaml`,
        where you can annotate your activity per device in ~1h intervals.
        
        Set the `active` field to True where you think you have been actively using the device.
        
        ### Step 5: Re-run sharkreduce with filled activity file
        
        If it exists, sharkreduce will use the content of `activity.yaml` to 
        fill the `active_use` column. So you just need to re-run ...
        
        ```bash
        python3 -m sharkreduce -t 60000000 -n devices.yaml reduceme.tsv reduced.tsv
        ```
        
        **Note:** If you change the `devices.yaml` you have to re-do steps 3, 4 and 5.
        
        ### Step 6: Party! ðŸ¥³
        
        Your pretty reduced capture with annotated device names and activity is now
        stored under `reduced.tsv`.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Requires-Python: >=3.6
Description-Content-Type: text/markdown
