Uncover: Quickly Discover Exposed Hosts on the Internet from Linux

Recently, I’ve written a detailed guide on the Smap alternative to Nmap that takes advantage of the Shodan API to generate identical output like Nmap, except it also fetches open port data from Shodan as an add-on to standard Nmap.

No doubt, Shodan is an amazing way to find devices connected to the internet. However, it is not the only search engine. There are several platforms like Censys and Fofa that offer you the chance to check if the device is connected to the internet.

If you have a list of IP addresses and check it on Shodan (to know whether they are exposed to the internet), in a very rare situation, you might not see any result declaring that they are not exposed.

You leave that situation for further investigation. However, it is recommended to check IP addresses on multiple platforms to verify that they are 100% not exposed to the internet from anywhere.

To achieve this, you can take the help of various tools that help you perform all search engine searches from one tool without letting you manually visit each search engine for testing.

Of all those tools, one is the Uncover tool, which can give you the power to perform tests on hosts to check whether they are exposed to the internet.

What is the Uncover Tool in Linux?

Uncover is an open-source application that uses a popular search engine API to quickly discover exposed hosts on the internet. It will let you know if the hosts are present on the internet. You can further investigate it with other tools.

To date, it supports popular search engine APIs like shodan, shodan-internetdb, censys, and fofa. Either you manually visit this search engine to investigate your host or use tools like Uncover to automate this process and give your valuable time to the real meat.

Uncover Tool Features

Below are some known features of this tool.

  • Free and open-source under the MIT license.
  • Supports shodan, shodan-internetdb, censys, and fofa search APIs.
  • Multiple creadentials/keys will be randomly picked.
  • stdin / stdout support for input and output.

Install the Uncover Tool on Linux

The application is wrapped purely in the Go programming language, meaning you will not be compromised for speed. However, if you have not installed Go on your system, then do check out our detailed guide on the installation and configuration of Go on Linux.

Once Go is installed, you will get access to the go command through which you can install it by using the following command.

$ go install -v github.com/projectdiscovery/uncover/cmd/[email protected]

Note: After the installation, if you are unable to access the uncover command from anywhere, then execute the sudo ln -s ~/go/bin/uncover /usr/bin/ command to create a symbolic link which will allow it to be accessed from anywhere.

Once the application is installed, you need to provide an API key in the Uncover configuration file or you can pass it as an environmental variable.

Uncover Tool Configuration

There are two ways to configure the API key for the Uncover tool. One is by editing the provider-config.yaml config file. The other is by adding the API key as an environment variable in your bash profile.

You can follow any one of the following methods to make it work.

Method 1: Adding the API key to the Config File

The default configuration file is located at ~/.config/uncover/provider-config.yaml, which will be created when you run the tool for the first time. If you look at the content of this file by using the cat command, you will get the following output.

$ cat ~/.config/uncover/provider-config.yaml

Below is the output of the above command.

Uncover configuration file
Uncover: configuration file

In the configuration file, you need to add at least one search engine API key to make it work properly. For that, create a new account on any of the search engines such as Shodan, Censys, or Fofa and copy and paste the API key in the configuration file as shown.

Note: You can add multiple keys separated by commas. While scanning, it will randomly pick the API for querying the hosts.

Adding search engine API key to Uncover config file
Adding search engine API key to the Uncover config file

Method 2: Adding API key to Bash Profile

If you want to set the API keys as an environment variable in your bash profile. Then you can use the below snippet depending upon the search engine API keys you have.

export SHODAN_API_KEY=xxx
export CENSYS_API_ID=xxx
export CENSYS_API_SECRET=xxx
export FOFA_EMAIL=xxx
export FOFA_KEY=xxx

For example, I’ve got the Shodan API key. For that, I will pass the API key to the SHODAN_API_KEY variable and paste the alias in the .bashrc or .bash_profile as shown below.

$ vim ~/.bashrc
#OR
$ vim ~/.bash_profile

Below is the output of the above command.

Adding search engine API key to user shell configuration file
Adding the search engine API key to the user shell configuration file

Save and close, and reload your bash file by using the source ~/.bashrc or source ~/.bash_profile command.

Uncover Tool Usage

There are multiple ways to use it, by specifying single hosts at a time or by creating a text file with multiple hosts and passing them as parameters.

#Example 1

Test that a single host is exposed to the internet by using the following command with the -q flag to query the IP/CIDR input.

$ uncover -q 193.34.XX.XX

If the specified host is exposed to the internet, then it will be output with the port number, as shown below.

Verifying the single host is exposed to internet
Verifying the single host is exposed to the internet

If you want to check if a specific port of the host is exposed to the internet, then specify the port with the host IP address, as shown below.

$ uncover -q 193.34.XX.XX:80

If the output is empty, then it means that the specified port of the host is not exposed to the internet.

Verifying the single host with port is exposed to internet
Verifying the single host with a port is exposed to the internet

#Example 2

If you have multiple hosts, then create a new text file and add each host in the new line and pass the text file as input to the uncover command.

$ uncover -q hosts.txt

Below is the output of the above command.

Verifying the multiple host is exposed to internet
Verifying that multiple hosts are exposed to the internet

#Example 3

Uncover supports multiple search engines to query the results. By default, Shodan is used. However, you can use the -e flag to specify other search engines.

Note: It is recommended to add all the search engine API keys that you plan to use to avoid any inaccurate output.

$ echo hosts.txt | uncover -e shodan,censys,fofa

Below is the output of the above command.

Verifying the hosts with multiple search engine
Verifying the hosts with multiple search engines

#Example 4

You can use the -f flag to specify which field to return in the output. Currently, ip, port, and host are supported, as shown below.

$ uncover -q hosts.txt -f ip
#OR 
$ uncover -q hosts.txt -f host

Below is the output of the above command.

Checking the hosts for specific field
Checking the hosts for a specific field

I’ve tried to cover all the essential parts of this tool. Still, if you have a hunger for more, then do check the help section by executing the uncover -h command.

Remove Uncover Tool from Linux

If you change your mind and don’t want to have this tool anymore, then execute the following command to remove it from your system.

$ rm ~/go/bin/uncover
$ sudo unlink /usr/bin/uncover

That’s all for today. If you have any questions or queries regarding this tool, then do let us know in the comment section.

Leave a Reply