--------------------------------------------------------------------------------

                                Hyenae NG

                                  Readme

--------------------------------------------------------------------------------

  Hyenae NG
    Advanced Network Packet Generator

  Copyright (C) 2020 Robin Richter

  Contact  : hyenae.tool@googlemail.com
  Homepage : https://github.com/r-richter/hyenae-ng
  
--------------------------------------------------------------------------------

  1. About Hyenae NG

  Hyenae NG (Next Generation) is a re-write of the original Hyenae tool which
  was originally published back in the year 2010.

  Besides switching from C to C++, using modern design concepts, Hyenae NG was
  (just like the original Hyenae) written with maximum portability in mind.
  Since the original Hyenae had a very complex command line syntax Hyenae NG
  comes with a fast and intuitively usable command line menu that will allow
  you to effectively set up even complex stress-tests or attacks scenarios
  within seconds.
  
  Hyenae NG currently has the following features:

  - Ethernet-Frame generation (Fully customizable)
  - ARP-Frame generation (Fully customizable)
  - IPv4-Frame generation (Fully customizable)
  - IPv6-Frame generation (Fully customizable)
  - ICMPv4-Frame generation (Fully customizable)
  - ICMPv6-Frame generation (Fully customizable)
  - TCP-Frame generation (Fully customizable)
  - UDP-Frame generation (Fully customizable)
  - Fixed or Random Send Delay
  - Pattern based address randomization
  - Clean and easy to use command line menu (No RTFM'ing required;))
  - Platform Independent

  Hyenae NG can be used for a variety of stress- and pen-testing
  scenarios such as:

  - SYN-Flooding
  - ICMP-Flooding
  - SMURF-Attacks
  - ARP-Cache Poisoning (MITM)
  - ...and many more

--------------------------------------------------------------------------------

  2. Contribution

  If you like this project and would like to contribute to it (in which way
  ever), feel free to do so via my GitHub page or by contacting me. I'm also
  always open for improvement ideas.

--------------------------------------------------------------------------------

  3. Project Goals
 
  The original Hyenae project started out as a study of network stack
  implementations but then quickly gained more complex features such as a
  remote daemon and an attack asistent. Even if it was widely accepted and is
  still a very commonly used tool in todays pen-testing workflows it has a
  complex command line syntax and requires some training and research in order
  to be used properly.
   
  With Hyenae NG i would like to provide the complexity and felxibility of
  Hyenae in a clean and easy to use command line tool which can be instantly
  used without any futher research on the command line arguments to pass for
  the specific scenarios.

--------------------------------------------------------------------------------

  4. Basic Usage

  Once you start Hyenae NG, it will enter the main menu state. From here you can
  set up your desired output, generator and dispatcher configuration.

    4.1 Output Setup
 
    The output setup let you choose from several different output option. You
    can either have Hyenae NG's output ignore by selecting "No Output" our you
    can have it send to either a file or a network adapter. Once you have
    selected an output, you can enter it's sub setup by selecting it again by
    either entering it's menu item number again or by simply pressing enter.
    Outputs that have a sub-setup are marked with a (...) once they are
    selected.

    4.2 Generator Setup

    The generator setup let you chose from several different generators. Most
    generators provide a payload option for which you can select another
    generator and so on. Since network frame generators are nested in transport
    layers, their available payload generators will differ based on the
    previously chosen frame generator. Here is an example of a typical
    payload nesting for an ethernet packet:

      Ethernet +-> ARP
               |
               +-> IPv4 +-> ICMPv4 -> ICMP Echo Payload
               |        +-> TCP
               |        +-> UDP
               |        +-> ...
               |
               +-> IPv6 +-> ICMPv4 -> ICMP Echo Payload
                        +-> ICMPv6 -> ICMP Echo Payload
                        +-> TCP
                        +-> UPD
                        +-> ...

    4.3 Dispatcher Setup

    The dispatcher setup will let you set up the actual data dispatcher. You
    can define stop-limits or configure a fixed or random send delay in order
    to break flood detection mechanisms on your target system.

    4.4 Start Dispatcher

    Once you have set a generator, you can choose this option to start up the
    dispatcher and start sending packets. If you haven't set a generator yet, 
    an error message will be shown instead. The dispatcher will operate until
    either a stop-limit (if set) is reached or the user presses any key. After
    the dispatcher has stopped you can either return to the main menu by
    entering 0 or start it again by either entering 1 or simply pressing enter.

--------------------------------------------------------------------------------

  5. Generator Patterns
 
   A lot of packet generator parameters can be providing with a generator pattern.
   These patterns will be used in order to generate a new value on every new
   packet. Here are some examples of a few basic patterns:
 
     # Random 5-digit number
   
       *****
     
     # Incremental 3-digit number
   
       +++
   
     # Decremental 2-digit number
   
       --
   
     # Random number between 100 and 199
   
       1**
   
     # Incremental number from 1 to 991
   
       ++1
   
     # Decremental number from 299 to 200
   
       2--
   
  Generator patterns are used for address fields too, here are a few more
  examples:
 
    # Random IPv4 address between .200 and .255
   
      129.168.0.2**
     
    # Incremental MAC address between :00 and :FF
   
      AA:BB:CC:DD:EE:++
     
    # Decremental IPv6 address between :FFFF and :FF00
   
      1000:2000:3000:4000:5000:6000:7000:FF--

--------------------------------------------------------------------------------