vPenTest Agent troubleshooting guide
Overview
In some cases, you may experience issues with the vPenTest Agent depending on certain circumstances, such as hardware resources, firewall configurations, etc. For the most part, the VM that vPenTest uses should be easily plugged in and be good to go. The Agent is nothing but a standard Linux VM with a Ruby script on it along with Docker. That's it.
The vPenTest Agent's ruby script is simply a menu-driven interface that helps configure network configuration settings in cases where network administrators may not necessarily be familiar with Linux.
If you're experiencing any issues related to the VM or connectivity issues, you can use some of the information in this article to help troubleshoot and pinpoint exactly what's going on. The sections in this article are ordered based on the steps needed to get the Agent fully registered and functional.
Hardware resource requirements
Per the resource requirements in the Getting started guide and What are the resource requirements for the vPenTest Agent? documents, you will need to make sure that the VM has the following resources configured:
- Memory: 8 GB
- Hard Disk Space: 80 GB
- Networking adapter mode preference: Bridged
- Network Interface: 1 gbps wired ethernet
- Network download speeds: 5 MB/s
Credentials aren't working
In some cases, you may experience that your password isn't working after you've just deployed an OVA VM. If this is the case, refer to the following article to perform some troubleshooting steps related to this: Why does my Agent keep running out of disk space?
Network adapter doesn't exist
In many cases, the root problem of network connectivity issues is due to the network adapter simply not being attached to the VM.
You can confirm this by running the following command at the prompt:
# ifconfig
When you run this command, you should see an example of the following output (note where it shows eth0):
As you can see in the above example, the eth0 interface exists on this VM. You may not see eth0 and in some cases you may see ens33 instead; however, you should definitely have at least one interface other than docker0 and lo.
In some cases, you may also be to run dhclient to "refresh" your network interfaces, which would essentially just have your VM attempt to pull down DHCP IP address configuration settings.
If you do not see any other interfaces other than the loopback and docker interfaces, you will need to verify your VM's settings and perform additional troubleshooting steps based on your hypervisor (e.g. VMware, Hyper-V, etc.).
Not getting an IP address
If you have a network adapter as shown above and you're not getting an IP address, you should confirm that your network adapter is properly set up for either DHCP or static IP addressing, whichever your preference is.
You can refer to the following two articles on setting/configuring DHCP and/or static IP addresses:
If you're just looking to "refresh" a DHCP configuration, you can run the following command from the console:
# dhclient
The above command will request a new DHCP-assigned IP address configuration on all interfaces.
Having issues resolving DNS
In some cases, you may experience issues with DNS when trying to interact with any DNS names on the Internet. For example, if you've seen an error that states something along the lines of "temporary failure in name resolution", this points specifically to DNS.
To confirm if you're having issues with DNS, perform the following tests:
Ping 8.8.8.8
Run the following command from your terminal:
# ping 8.8.8.8
If you have Internet access, you should see the following results:
PING 8.8.8.8 (8.8.8.8) 56(84) bytes of data.
64 bytes from 8.8.8.8: icmp_seq=1 ttl=118 time=17.1 ms
64 bytes from 8.8.8.8: icmp_seq=2 ttl=118 time=16.7 ms
64 bytes from 8.8.8.8: icmp_seq=3 ttl=118 time=16.0 ms
^C
--- 8.8.8.8 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2003ms
rtt min/avg/max/mdev = 16.035/16.607/17.111/0.441 ms
If you don't see this, refer to the next section.
Ping google.com
Run the following command from your terminal:
# ping google.com
If DNS is working properly, you should see results similar to the following:
PING google.com (74.125.21.100) 56(84) bytes of data.
64 bytes from yv-in-f100.1e100.net (74.125.21.100): icmp_seq=1 ttl=108 time=17.1 ms
64 bytes from yv-in-f100.1e100.net (74.125.21.100): icmp_seq=2 ttl=108 time=18.2 ms
64 bytes from yv-in-f100.1e100.net (74.125.21.100): icmp_seq=3 ttl=108 time=18.2 ms
^C
--- google.com ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2003ms
rtt min/avg/max/mdev = 17.096/17.834/18.217/0.522 ms
If the first one worked and the second one didn't, you will need to configure the proper DNS settings. If the results of both of these commands worked properly, then you don't have any issues with DNS.
For additional support related to DNS issues, refer to the following article: What does the "Failed to resolve hostname" error mean?
Firewall restriction issues
If all of the above sections don't apply to you and you're having issues getting outbound to the Internet, you may have an issue related to your firewall's configuration. In order to successfully register the Agent, you need to add certain allowlist configurations if you're in a restricted environment.
For more information on which endpoints you need to allowlist, refer to the following article: Permitting access for the Agent (allowlist)
As a quick test, you can run the following command from your terminal with similar results being returned:
# telnet app.vpentest.io 443
Trying 52.0.65.126...
Connected to app.vpentest.io.
Escape character is '^]'.
If you don't see a "connected to" error, then you may need to refer to the article above to configure allowlists.
Getting a "Not ready to connect" message
Refer to the following article: What does the "Not ready to connect" Agent message mean?
Unable to see the vPenTest Agent menu
When you login to the root account of your Ubuntu instance, the vPenTest menu should immediately start, allowing you to choose an option. If you do not see this, there are a few things that you can do to figure out what's going on.
Check to see if the Agent's script is installed
Run the following command within your console:
ls -lh ~
When you run the above command, you should see the following output:
-rwxr-xr-x 1 root root 13K Jan 5 14:48 vpentest.rb
-rwxr-xr-x 1 root root 2.7K Dec 24 14:17 vpentest_updater.rb
If you do not see the above output, please run the following command:
curl -L https://app.vpentest.io/getting_started.sh | bash
Try running the Agent script manually
If you have the script already installed (based on the previous section), you can run the script manually by typing the following command:
# /root/vpentest.rb
