Skip to main content

Python library and command-line tool for ZoomEye (

Project description

English | 中文文档

ZoomEye is a cyberspace search engine, users can search for network devices using a browser

ZoomEye-python is a Python library developed based on the ZoomEye API. It provides the ZoomEye command line mode and can also be integrated into other tools as an SDK. The library allows technicians to search, filter, and export ZoomEye data more conveniently.

0x01 installation

It can be installed directly from pypi:

pip3 install zoomeye

or installed from github:

pip3 install git+

0x02 how to use cli

After successfully installing ZoomEye-python, you can use the zoomeye command directly, as follows:

$ zoomeye -h
usage: zoomeye [-h] [-v] {info,search,init,ip,history,clear} ...
 positional arguments:
     info                Show ZoomEye account info
     search              Search the ZoomEye database
     init                Initialize the token for ZoomEye-python
     ip                  Query IP information
     history             Query device history
     clear               Manually clear the cache and user information

 optional arguments:
   -h, --help            show this help message and exit
   -v, --version         show program's version number and exit

1.initialize token

Before using the ZoomEye-python cli, the user token needs to be initialized. The credential is used to verify the user’s identity to query data from ZoomEye; we provide two authentication methods:

2.APIKEY (recommend)

You can view the help through zoomeye init -h, and use APIKEY to demonstrate below:

$ zoomeye init -apikey "01234567-acbd-00000-1111-22222222222"
successfully initialized
Role: developer
Quota: 10000

Users can login to ZoomEye and obtain APIKEY in personal information (; APIKEY will not expire, users can reset in personal information according to their needs.

in addition, we also provide the initialization method of username/password. After authentication in this way, the JWT-token will be returned, which has certain timeliness and requires the user to login again after failure.

2.query quota

Users can query personal information and data quota through the info command, as follows:

$ zoomeye info
Role: developer
Quota: 10000

4.number of data

Through the -num parameter, we can specify the number of search and display, and the specified number is the number of consumed quantities. you can query the volume of the dork in the ZoomEye database through the -count parameter, as follows:

$ zoomeye search "telnet" -count
One thing to note, the consumption of the -num parameter is an integer multiple of 20, because the minimum number of a single query of the ZoomEye API is 20.


We can use -facet and -stat to perform data statistics, use -facet to query the statistics of the dork’s full data (obtained through API after statistics by ZoomEye), and -stat You can perform statistics on the query result set. The fields supported by the two commands include:

# host searhc
app      statistics by application type
device   statistics by device type
service  statistics by service type
os       statistics by operating system type
port     statistics by port
country  statistics by country
city     statistics by city

# web search
webapp      statistics by Web application
component   statistics by Web container
framework   statistics by Web framework
server      statistics by Web server
waf         statistics by Web firewall(WAF)
os          statistics by operating system
country     statistics by country

use -facet to count the application types of all telnet devices:

$ zoomeye search "telnet" -facet app
app                                count
[unknown]                          28317914
BusyBox telnetd                    10176313
Linux telnetd                      3054856
Cisco IOS telnetd                  1505802
Huawei Home Gateway telnetd        1229112
MikroTik router config httpd       1066947
Huawei telnetd                     965378
Busybox telnetd                    962470
Netgear broadband router...        593346
NASLite-SMB/Sveasoft Alc...        491957

use -stat to count and query the application types of 20 telnet devices:

$ zoomeye search "telnet" -stat app
app                                count
Cisco IOS telnetd                  7
[unknown]                          5
BusyBox telnetd                    4
Linux telnetd                      3
Pocket CMD telnetd                 1 filter

Use the -filter parameter to query the list of partial segments in the data result set, or filter based on content. The segments supported by this command include:

# host/search
app           show application type details
version       show version information details
device        show device type details
port          show port information details
city          show city details
country       show country details
asn           show as number details
banner        show details of characteristic response
timestamp     show record data time
*             when this symbol is included, show all field details

# web/search
app         show application type details
headers     HTTP header
keywords    meta keyword
title       HTTP Title information
site        site search
city        show city details
country     show country details
webapp      Web application
component   Web container
framework   Web framework
server      Web server
waf         Web firewall(WAF)
os          operating system
timestamp   updated timestamp
*           when this symbol is included, show all field details

Compared to the omitted display by default, the complete data can be viewed through -filter, as follows:

$ zoomeye search "telnet" -num 1 -filter banner
ip         banner
222.*.*.*  \xff\xfb\x01\xff\xfb\x03\xff\xfd\x03TELNET session now in ESTABLISHED state\r\n\r\n

total: 1

When using -filter to filter, the syntax is: key1,key2,key3=value, where key3=value is the filter condition, and the displayed content is key1,key2 Example:

$ zoomeye search telnet -num 1 -filter port,app,banner=Telnet

 ip                        port                          app
 240e:*:*:*::3             23                            LANDesk remote management

In the above example: banner=Telnet is the filter condition, and port,app is the displayed content. If you need to display banner, the filter statement is like this

$ zoomeye search telnet -num 1 -filter port,app,banner,banner=Telnet export

The -save parameter can export data. the syntax of this parameter is the same as that of -filter, and the result is saved to a file in the format of line json, as follows:

$ zoomeye search "telnet" -save banner=telnet
save file to telnet_1_1610446755.json successful!

$ cat telnet_1_1610446755.json
{'ip': '', 'banner': '\\xff\\xfb\\x01\\xff\\xfb\\x03\\xff\\xfd\\x03TELNET session now in ESTABLISHED state\\r\\n\\r\\n'}
if you use -save without any parameters, the query result will be saved as a file according to the json format of ZoomEye API. this method is generally used to integrate data while retaining metadata; the file can be as input, it is parsed and processed again through cli, such as zoomeye search "xxxxx.json".

8.graphical data

The -figure parameter is a data visualization parameter. This parameter provides two display methods: pie (pie chart) and hist (histogram). The data will still be displayed without specifying it. When -figure is specified , Only graphics will be displayed. The pie chart is as follows:

The histogram is as follows:

9. IP history

ZoomEye-python provides the function of querying IP historical device data. Use the command history [ip] to query the historical data of IP devices. The usage is as follows:

$zoomeye history "207.xx.xx.13" -num 1
Hostnames:                    [unknown]
Country:                      United States
City:                         Lake Charles
Lastupdated:                  2021-02-18T03:44:06
Number of open ports:         1
Number of historical probes:  1

timestamp                  port/service               app                        raw_data
2021-02-18 03:44:06        80/http                    Apache httpd               HTTP/1.0 301 Moved Permanently...

By default, five fields are shown to users:

1. time     recorded time
2. service  Open service
3. port     port
4. app      web application
5. raw      fingerprint information

Use zoomeye history -h to view the parameters provided by history.

$zoomeye history -h

usage: zoomeye history [-h] [-filter filed=regexp] [-force] ip

positional arguments:
  ip                    search historical device IP

optional arguments:
  -h, --help            show this help message and exit
  -filter filed=regexp  filter data and print raw data detail. field:
  -force                ignore the local cache and force the data to be
                        obtained from the API

The following is a demonstration of -filter:

$zoomeye history "207.xx.xx.13" -filter "time=^2019-08,port,service"
Hostnames:                    [unknown]
Country:                      United States
City:                         Lake Charles
Lastupdated:                  2019-08-16T10:53:46
Number of open ports:         3
Number of historical probes:  3

time                       port                       service
2019-08-16 10:53:46        389                        ldap
2019-08-08 23:32:30        22                         ssh
2019-08-03 01:55:59        80                         http

The -filter parameter supports the filtering of the following five fields:

1.time      scan time
2.port      port information
3.service   open service       web application
5.banner    original fingerprint information
*           when this symbol is included, show all field details

A display of the id field is added during the display. id is the serial number. For the convenience of viewing, it cannot be used as a filtered field.

Note: At present, only the above five fields are allowed to filter.

The user quota will also be consumed when using the history command. The user quota will be deducted for the number of pieces of data returned in the history command. For example: IP “” has a total of 944 historical records, and the user quota of 944 is deducted for one query.

10. search IP information

You can query the information of the specified IP through the zoomeye ip command, for example:

$ zoomeye ip 185.*.*.57
Hostnames:                    [unknown]
Isp:                          [unknown]
Country:                      Saudi Arabia
City:                         [unknown]
Organization:                 [unknown]
Lastupdated:                  2021-03-02T11:14:33
Number of open ports:         4{2002, 9002, 123, 25}

port      service        app                    banner
9002      telnet                                \xff\xfb\x01\xff\xfb\x0...
123       ntp            ntpd                   \x16\x82\x00\x01\x05\x0...
2002      telnet         Pocket CMD telnetd     \xff\xfb\x01\xff\xfb\x0...
25        smtp           Cisco IOS NetWor...    220 Cisco Net...

The zoomeye ip command also supports the filter parameter -filter, and the syntax is the same as that of zoomeye search. E.g:

$ zoomeye ip "185.*.*.57" -filter "app,app=ntpd"
Hostnames:                    [unknown]
Isp:                          [unknown]
Country:                      Saudi Arabia
City:                         [unknown]
Organization:                 [unknown]
Lastupdated:                  2021-02-17T02:15:06
Number of open ports:         0
Number of historical probes:  1


The fields supported by the filter parameter are:

1.port       port information
2.service    open service        web application
4.banner     original fingerprint information

Note: This function limits the number of queries per user per day based on different user levels.

Registered users and developers can query 10 times a day

Advanced users can query 20 times a day

VIP users can query 30 times a day

After the number of times per day is used up, it will be refreshed after 24 hours, that is, counting from the time of the first IP check, and the number of refreshes after 24 hours.

11.cleanup function

Users search for a large amount of data every day, which causes the storage space occupied by the cache folder to gradually increase; if users use ZoomEye-python on a public server, it may cause their own API KEY and ACCESS TOKEN to leak . For this reason, ZoomEye-python provides the clear command zoomeye clear, which can clear the cached data and user configuration. The usage is as follows:

$zoomeye clear -h
usage: zoomeye clear [-h] [-setting] [-cache]

optional arguments:
  -h, --help  show this help message and exit
  -setting    clear user api key and access token
  -cache      clear local cache file cache

ZoomEye-python provides a caching in cli mode, which is located under ~/.config/zoomeye/cache to save user quota as much as possible; the data set that the user has queried will be cached locally for 5 days. when users query the same data set, quotas are not consumed.

13.domain name query

ZoomEye-python provides the domain name query function (including associated domain name query and subdomain name query). To query a domain name, run the domain [domain name] [query type] command as follows:

$ python domain 0
name                                                   timestamp      ip                       2021-06-27                               2021-06-27                                 2021-06-27                         2021-06-27                              2021-06-27                               2021-06-27

total: 30/79882

By default, the user is presented with three more important fields:

1. name             域名全称
2. timestamp        建立时间戳
3. ip               ip地址

Use zoomeye domain -h to view parameters provided by the domain.

$ python domain -h
usage: zoomeye domain [-h] [-page PAGE] q {0,1}

positional arguments:
  q           search key word(
  {0,1}       0: search associated domain;1: search sub domain

optional arguments:
  -h, --help  show this help message and exit
  -page PAGE  view the page of the query result

The following is a demonstration of -page :(default query for the first page when not specified)

$ python domain 0 -page 3
name                                                   timestamp      ip                      2021-06-27                       2021-06-27    2021-06-27                                         2021-06-27                     2021-06-27                         2021-06-27                                      2021-06-27                              2021-06-27

...                        2021-06-27                                      2021-06-27                               2021-06-27                                2021-06-27

total: 90/79882

0x04 use SDK

1.initialize token

Similarly, the SDK also supports two authentication methods, username/password and APIKEY, as follows:


from zoomeye.sdk import ZoomEye

zm = ZoomEye(username="username", password="password")


from zoomeye.sdk import ZoomEye

zm = ZoomEye(api_key="01234567-acbd-00000-1111-22222222222")


The following are the interfaces and instructions provided by the SDK:

  use username/password or APIKEY for authentication
2.dork_search(dork, page=0, resource="host", facets=None)
  search the data of the specified page according to dork
3.multi_page_search(dork, page=1, resource="host", facets=None)
  search multiple pages of data according to dork
  get current user information
  get the number of all matching results under the current dork
  extract the data of the specified field from the search results
  get statistical results of all data from search results
  query historical data information of an ip
  traverse the web-search result set, and output the domain name and ip address
  traverse the host-search result set and output the ip address and port

3.SDK example

$ python3
>>> import zoomeye.sdk as zoomeye
>>> dir(zoomeye)
['ZoomEye', 'ZoomEyeDict', '__builtins__', '__cached__', '__doc__',
'__file__', '__loader__', '__name__', '__package__', '__spec__',
'fields_tables_host', 'fields_tables_web', 'getpass', 'requests',
'show_ip_port', 'show_site_ip', 'zoomeye_api_test']
>>> # Use username and password to login
>>> zm = zoomeye.ZoomEye()
>>> zm.username = ''
>>> zm.password = 'password'
>>> print(zm.login())
>>> data = zm.dork_search('apache country:cn')
>>> zoomeye.show_site_ip(data)
213.***.***.46.rev.vo*** ['46.***.***.213']
me*****on.o**** ['203.***.***.114']
soft********63221110.b*** ['126.***.***.110']
soft********26216022.b*** ['126.***.***.22']
soft********5084068.b*** ['126.***.***.68']
soft********11180040.b*** ['126.***.***.40']

As in the above example, we use dork_search() to search, and we can also set the facets parameter to obtain the aggregated statistical results of the full data of the dork. for the fields supported by facets, please refer to 2.use cli - 5.statistics. as follows:

>>> data = zm.dork_search('telnet', facets='app')
>>> zm.get_facet()
{'product': [{'name': '', 'count': 28323128}, {'name': 'BusyBox telnetd', 'count': 10180912}, {'name': 'Linux telnetd', ......
multi_page_search() can also search. use this function when you need to obtain a large amount of data, where the page field indicates how many pages of data are obtained; and dork_search() only obtains the data of a specified page. filter

the dork_filter() function is provided in the SDK, we can filter the data more conveniently and extract the specified data fields as follows:

>>> data = zm.dork_search("telnet")
>>> zm.dork_filter("ip,port")
[['180.*.*.166', 5357], ['180.*.*.6', 5357], ......
since the fields returned by web-search and host-search interfaces are different, you need to fill in the correct fields when filtering. the fields included in web-search: app / headers / keywords / title / ip / site / city / country the fields included in host-search: app / version / device / ip / port / hostname / city / country / asn / banner

0x06 issue

1.The minimum number of requests for SDK and command line tools is 20
Due to API limitations, the minimum unit of our query is 20 pieces of data at a time. for a new dork, whether it is to view the total number or specify to search for only 1 piece of data, there will be an overhead of 20 pieces; of course, in the cli, we provide a cache, the data that has been searched is cached locally (~/.config/zoomeye/cache), and the validity period is 5 days, which can greatly save quota.
2.How to enter dork with quotes?
When using cli to search, you will encounter dork with quotes, for example: "<body style=\"margin:0;padding:0\"> <p align=\"center\"> <iframe src=\ "index.xhtml\"", when dork contains quotation marks or multiple quotation marks, the outermost layer of dork must be wrapped in quotation marks to indicate a parameter as a whole, otherwise command line parameter parsing will cause problems. Then the correct search method for the following dork should be: '"<body style=\"margin:0;padding:0\"> <p align=\"center\"> <iframe src=\"index.xhtml\" "'.
3.Why is there inconsistent data in facet?
The following figure shows the full data statistics results of telnet. the result of the first query is that 20 data query requests (including the statistical results) were initiated by cli one day ago by default, and cached in a local folder; the second time We set the number of queries to 21, cli will read 20 cached data and initiate a new query request (actually the smallest unit is 20, which also contains statistical results), the first query and the second query a certain period of time is in between. during this period of time, ZoomEye periodically scans and updates the data, resulting in the above data inconsistency, so cli will use the newer statistical results.
4.Why may the total amount of data in ZoomEye-python and the browser search the same dork be different?
ZoomEye provides two search interfaces: /host/search and /web/search. In ZoomEye-python, only /host/search is used by default, and /web/search is not used. Users can choose the search method according to their needs by specifying the type parameter.
5.The quota information obtained by the info command may be inconsistent with the browser side?
The browser side displays the free quota and recharge quota (, but only the free quota information is displayed in ZoomEye-python, we will fix it in the subsequent version This question.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for zoomeye, version
Filename, size File type Python version Upload date Hashes
Filename, size zoomeye- (40.1 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size zoomeye- (45.4 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page