Installing the API to a Local Machine

1. Initial Installation

   • Ensure you are installing on a Kali Linux Machine.
   • Download the zip file or clone directly to your preferred directory.
   • Make sure there is internet connection on the Kali Machine at all times.
   • After downloading, go to the downloaded directory (i.e., inside the new downloaded directory.
   • Make sure you have extensions.txt, fasttrack.txt, metasploit, pswds.lst, url.txt and user.txt in the downloaded directory.
   • Nmap-Vulners Installation:
     • Go to this link: Nmap-Vulners
     • Download the repository locally.
     • Follow the steps in the Installation section, it's simple and straightforward.
     • You will need to locate the hidden .nmap directory on the Kali machine. If you cannot find this directory then it is probably in /usr/share/nmap/scripts directory.
     • Copy the nmap-vulners.nse script here.
   • Vulscan Installation
     • Go to this link: Vulscan
     • Follow the steps in the Installation section.
     • This should take place in the same nmap scripts directory as above in nmap-vulners.

2. Pre-run Configurations

   • Inside the API directory, open a terminal and enter npm install. This will install all node dependencies required.
   • DO NOT MODIFY THE .env FILE with any of your own paths.
   • Any of the passwordlists and extension files inside the API can be modified to reflect what you want. However it is recommended to not do so because they already contain good estimates of what is required.
   • Finally, inside the API in a terminal, enter node pentestApi.js and hit enter.
   • Make sure the console output says Server has started, this means that The API has now started, and is waiting for connections.
   • NOTE: The API runs on port 3005, and normally you shouldn't have anything running on this port. If you do get an error, make sure that there is no process running on port 3005 and kill such a process!

3. Sending Requests to the API

   • A request can be sent from anywhere in the form of an HTTP request, i.e., from inside code, from a platform or simply from a terminal in the form of http://hostaddress:port/starttest/192.168.1/startIP/endIP/phases.
   • A sample request looks like the following -
     curl http://localhost:3005/starttest/192.168.1/212/212/ivd
     
     1. In this example we used the curl command to send a request to a RESTful HTTP route. We used localhost because we sent the request from the same machine, in other cases acquire the IP Address of the Kali Machine and send a request to that IP, followed by the port.
     2. The route parameters include the startest keyword followed by the local subnet which is 192.168.1 in most cases.
     3. This is followed by a start IP address, in this case start from 192.168.1.212. The next parameter is the end IP Address. In this case its the same device. This means it only pen-tests one device.
        The last parameter is to specify the phases of testing, which for now need to include all 3 phases,
        i -> Information Gathering
        v -> Vulnerabililty Assessment
        d -> Dictionary Attacks
   • A request can also be sent from anywhere in the form of an MQTT request, i.e., from inside code or from a platform by the following simple steps:
     1. Publishing a message on the pentest/start topic.
     2. This message needs to be a JSON of the following format:
        {
        ip: []
        domain: ''
        }
     3. The message has to be stringified using JSON.stringify() method.
     4. A sample method of publishing this message is shown in the portal.html file in this directory.
     5. The ip array in the message is an array of various IP Addresses to run the test on, only the last 8 bits, eg: if you want to test the IP addresses 192.168.1.1 and 192.168.1.13, then you would only pass the "1" and the "13" as elements of this array!
     6. The domain field in the JSON message is the beginning 24 bits of the IP address without the trailing ".".
     7. Once the message is published, the client should also subscribe to 2 topics which are pentest/updates and the pentest/complete
     8. After this process, the user just has to wait for results and they will appear once the tests are complete.
     9. To further analyze the results, parsing is required which is explained the below section on Report Generation.

     10. NOTE:

         Even though the setup for MQTT can be longer than HTTP, the benefits are more than simple HTTP.
         • It is an asynchronous pattern which is more intuitive.
         • More variety of IP Addresses can be tested.
         • It is lightweight and can be requested from anywhere in the code.

Report Generation

1. Structure of the report generated

   • Report is in JSON structure with fields for various results of tools used in the security test.

   • Sample Report JSON ->

     
     
     
     
   
   
   • The fields of the JSON are as shown in the template and each device tested comes in the devices array which is the top level field of the report.
   • A sample code in plain HTML/JS is shown in the portal.html file provided in the directory.
   • The 2 methods in the html file show different ways of sending the request which are MQTT based or HTTP based.

   • NOTE

     • HTTP Based request only allows an IP address range sequentially, so different addresses cannot be tested in the same domain, eg: 192.168.1.1 -> 192.168.1.10 in order.
     • MQTT Based request allows any random IP address within the same LAN/domain, eg: 192.168.1.1 & 192.168.1.37 & 192.168.1.14
     • HTTP Based request takes time to get a response because the tests take time to complete, however MQTT Based requests are asynchronous by nature and non-blocking so they are recommended!
     • Parsing the json in typescript or JS is a simple one liner -> var res = JSON.parse(msg);.