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.
This should take place in the same nmap scripts directory as above in nmap-vulners.
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!
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
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.
The route parameters include the startest keyword followed by the local subnet which is
192.168.1 in most cases.
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:
Publishing a message on the pentest/start topic.
This message needs to be a JSON of the following format: { ip: [] domain: '' }
The message has to be stringified using JSON.stringify() method.
A sample method of publishing this message is shown in the portal.html
file in this directory.
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!
The domain field in the JSON message is the beginning 24 bits of the IP address without
the trailing ".".
Once the message is published, the client should also subscribe to 2 topics which are
pentest/updates and the pentest/complete
After this process, the user just has to wait for results and they will appear once the tests
are complete.
To further analyze the results, parsing is required which is explained the below section on
Report Generation.
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
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);.