Uncover is a go wrapper using APIs of well known search engines to quickly discover exposed hosts on the internet. It is built with automation in mind, so you can query it and utilize the results with your current pipeline tools. Currently, it supports shodan,shodan-internetdb, censys, and fofa search API.
- Simple and Handy utility to query multiple search engine
- Multiple Search engine support (Shodan, Censys, Fofa, Shodan-InternetDB)
- Automatic key/credential randomization
- stdin / stdout support for input and output
uncover requires go1.17 to install successfully. Run the following command to get the repo –
go install -v github.com/projectdiscovery/uncover/cmd/uncover@latest
This will display help for the tool. Here are all the flags it supports:
-q, -query string search query or list (file or comma separated or stdin)
-e, -engine string search engine to query (shodan,shodan-idb,fofa,censys) (default shodan)
-pc, -provider string provider configuration file (default “$HOME/.config/uncover/provider-config.yaml”)
-config string flag configuration file (default “$HOME/.config/uncover/config.yaml”)
-timeout int timeout in seconds (default 30)
-delay int delay between requests in seconds (0 to disable) (default 1)
-o, -output string output file to write found results
-f, -field string field to display in output (ip,port,host) (default “ip:port”)
-j, -json write output in JSONL(ines) format
-r, -raw write raw output as received by the remote api
-l, -limit int limit the number of results to return (default 100)
-nc, -no-color disable colors in output
-silent show only results in output
-version show version of the project
-v show verbose output
The default provider configuration file should be located at
$HOME/.config/uncover/provider-config.yaml and has the following contents as an example. In order to run this tool, the API keys / credentials needs to be added in this config file or set as environment variable.
When multiple keys/credentials are specified for same provider in the config file, random key will be used for each execution.
alternatively you can also set the API key as environment variable in your bash profile.
Required keys can be obtained by signing up on Shodan, Censys, Fofa.
uncover supports multiple ways to make the query including stdin or
echo ‘ssl:”Uber Technologies, Inc.”‘ | uncover
/ / / / _ \/ / _ \ | / / _ \/ /
/ // / / / / // // / |/ / / /
__,// //__/____/|/_// v0.0.1
[WRN] Use with caution. You are responsible for your actions
[WRN] Developers assume no liability and are not responsible for any misuse or damage.
[WRN] By using uncover, you also agree to the terms of the APIs used.
Running uncover with file input containing multiple search queries per line.
ssl:”Uber Technologies, Inc.”
Multiple Search Engine API (Shodan,Censys,Fofa)
uncover supports multiple search engine, as default shodan is used,
engine flag can be used to specify any available search engines.
uncover supports shodan-internetdb API to pull available ports for given IP/CIDR input.
shodan-idb used as default engine when IP/CIDR is provided as input, otherwise
shodan search engine is used.
-f, -field flag can be used to indicate which fields to return, currently,
host are supported and can be used to return desired fields.
uncover has a
-f, -field flag that can be used to customize the output format. For example, in the case of
uncover -f https://ip:port/version, ip:port will be replaced with results in the output while keeping the format defined, It can also be used to specify a known scheme/path/file in order to prepare the output so that it can be immediately passed as input to other tools in the pipeline.
Output of uncover can be further piped to other projects in workflow accepting stdin as input, for example:
uncover -q example -f ip | naabu– Runs naabu for port scanning on the found host.
uncover -q title:GitLab | httpx– Runs httpx for web server probing the found result.
uncover -q 188.8.131.52/24 | httpx– Runs httpx on host/ports obtained from shodan-internetdb.
- keys/ credentials are required to configure before running or using this project.
queryflag supports all the filters supported by underlying API in use.
queryflag input needs be compatible with search engine in use.
- results are limited to
100as default and can be increased with
shodan-idbAPI doesn’t requires an API key and works out of the box.
shodan-idbAPI is used as default engine when IP/CIDR is provided as input.