## ZoomEye-python
English | [中文文档](./docs/README_CN.md)
`ZoomEye` is a cyberspace search engine that allows users to search for network devices through a browser at <https://www.zoomeye.org>.
`ZoomEye-python` is a Python library developed based on the `ZoomEye API`, providing both command-line interface and SDK integration capabilities for other tools. This library enables technical professionals to **search** and **export** ZoomEye data more conveniently.
### 0x01 Installation Steps
Install directly from `pypi`:
pip3 install zoomeye
Or install via `github`:
pip3 install git+https://github.com/knownsec/ZoomEye-python.git
### 0x02 Using CLI
After successfully installing `ZoomEye-python`, you can directly use the `zoomeye` command as follows:
```
$ zoomeye -h
usage: zoomeye [-h] [-v] {info,init,search,clear} ...
positional arguments:
{info,init,search,clear}
info Show ZoomEye account info
init Initialize the token for ZoomEye-python
search get network asset information based on query conditions.
clear Manually clear the cache and user information
options:
-h, --help show this help message and exit
-v, --version show program's version number and exit
```
#### 1. Token Initialization
Before using `ZoomEye-python CLI`, you need to initialize the user `token`. This credential is used to verify user identity for querying data from `ZoomEye`; only API-KEY authentication is supported.
You can view help through `zoomeye init -h`. Here's a demonstration using `APIKEY`:
```
$ zoomeye init -apikey "01234567-acbd-00000-1111-22222222222"
Username: your username
Role: Professional
Points: 800000
Zoomeye Points: 0
```
Users can obtain their `APIKEY` by logging into `ZoomEye` and accessing their profile (<https://www.zoomeye.org/profile>). The `APIKEY` doesn't expire, and users can reset it in their profile as needed.
#### 2. User Information
Users can retrieve their account information, subscription details, and current points through the `info` command:
```
$ zoomeye info
username: <username>
email: <email>
phone: <phone number>
created_at: 2021-01-15
Subscription:: {'plan': 'Professional', 'end_date': '2025-12-31', 'points': 800000, 'zoomeye_points': 0}
```
#### 3. Search
Search is the core functionality of `ZoomEye-python`, accessed through the `search` command. The `search` command requires a search keyword (`dork`). Here's a simple search example:
```
$ zoomeye search "telnet"
search "telnet"
ip port domain update_time
134.xx.xx.129 1901 [unknown] 2025-02-06T15:45:20
134.xx.xx.138 1901 [unknown] 2025-02-06T15:45:19
......
total: 20/9976411
```
Using the `search` command is as simple as searching on `ZoomEye` through a browser. By default, we display the most important fields that users can use to understand target information:
1.ip IP address
2.port Port
3.domain Target domain
4.update_time Target scan time
`search` supports the following parameters (`zoomeye search -h`) for data processing:
-facets facets Statistics items, comma-separated; supports country, subdivisions, city, product, service, device, os, and port.
-fields field=regexp Return fields, comma-separated; default: ip, port, domain, update_time. For more info, see: https://www.zoomeye.org/doc/
-sub_type {v4,v6,web,all} Data type, supports v4, v6, and web; default is v4.
-page page Default is page 1, sorted by update time.
-pagesize pagesize Number of queries per page, default is 10, maximum is 10,000 per page.
-figure {pie,hist} Parameter for data visualization
-save Save search results locally
-force Ignore local cache files and fetch data directly from ZoomEye
#### 4. Data Aggregation
We can use `-facets` for data aggregation statistics. Using `-facets` allows you to query the aggregation status of the full data set for that dork (aggregated by `ZoomEye` and retrieved via `API`)
```
$ zoomeye search "telnet" -facets product -pagesize 1
ip port domain update_time
177.xxx.xx.142 2020 [unknown] 2025-02-06T15:59:49
total: 1/9976296
----------------------------------------
ZoomEye total data:9976296
-------------product Top 10-------------
product count
MikroTik router config httpd 3326013
[unknown] 2421245
Apache httpd 2411293
ProFTPD 285649
Pulse Secure VPN httpd 182296
Samsung printer telnetd 178147
Huawei telnetd 144382
Huawei switch telnetd 120421
TP-LINK TL-WR841N WAP httpd 118836
DVR httpd 100068
```
#### 5. Data Export
The `-save` parameter can be used to export data as follows:
```
$ zoomeye search "telnet" -pagesize 1 -save
search "telnet" -pagesize 1 -save
ip port domain update_time
88.xx.xxx.78 3011 [unknown] 2025-02-06T16:00:53
total: 1/9976301
save file to telnet_1_1738829058.json successful!
```
#### 6. Data Visualization
The `-figure` parameter is for data visualization, offering both `pie` and `hist` (histogram) display options. When specified, it must be used together with `-facets`. Data is still displayed without specification. Here's an example of a pie chart:
And a histogram:
#### 7. Cleanup Function
Users search for large amounts of data daily, which can lead to increasing storage space in the cache folder. If users use `ZoomEye-python` on public servers, their `API KEY` and `ACCESS TOKEN` might be exposed.
Therefore, `ZoomEye-python` provides a cleanup command `zoomeye clear` to clear cache data and user configurations. 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
```
#### 12. Cache Mechanism
`ZoomEye-python` provides a caching mechanism in `cli` mode, located at `~/.config/zoomeye/cache`, to conserve user quotas as much as possible. Data sets queried by users are cached locally for 5 days, and when users query the same data set, it won't consume their quota.
### 0x04 Using SDK
#### 1. Token Initialization
Similarly, the SDK only supports authentication via `APIKEY`:
**APIKEY**
```python
from zoomeye.sdk import ZoomEye
zm = ZoomEye(api_key="01234567-acbd-00000-1111-22222222222")
```
#### 2. SDK API
Here are the interfaces provided by the SDK and their descriptions:
```
1.userinfo()
Get current user information
2.search(dork, qbase64='', page=1, pagesize=20, sub_type='all', fields='', facets='')
Get network asset information based on search criteria.
```
#### 3. Usage Example
```python
from zoomeye.sdk import ZoomEye
>>> dir(ZoomEye)
['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getstate__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_check_header', '_request', 'search', 'userinfo']
>>> zm = ZoomEye(api_key="01234567-acbd-00000-1111-22222222222")
>>> zm.search('country=cn')
{'code': 60000, 'message': 'success', 'query': 'country=cn', 'total': 823268005, 'data': [{...}], 'facets': {}}
```
### 0x05 Contributions
[wh0ami1@knownsec 404](https://github.com/wh0ami1)
[0x7F@knownsec 404](https://github.com/0x7Fancy)
[dawu@knownsec 404](https://github.com/d4wu)
[fenix@knownsec 404](https://github.com/13ph03nix)
### 0x06 Issues
**1. How to input dorks containing quotes?**
When using CLI for search queries containing quotes, such as `"<body style=\"margin:0;padding:0\"> <p align=\"center\"> <iframe src=\"index.xhtml\""`, the dork must be wrapped in quotes to represent it as a complete parameter when it contains quotes or multiple quotes. Otherwise, the command-line parameter parsing will have issues. The correct search format for this dork should be: `'"<body style=\"margin:0;padding:0\"> <p align=\"center\"> <iframe src=\"index.xhtml\""'`.
> If there are no spaces or special characters, quotes can be omitted as the parameter parser will consume one set of quotes
**2. zoomeye-ai**
If you are not a user from mainland China, please use <https://github.com/zoomeye-ai/ZoomEye-python>
### 0x07 404StarLink Project
ZoomEye-python is part of 404Team's [StarLink Project](https://github.com/knownsec/404StarLink-Project). If you have any questions about ZoomEye-python or want to connect with other users, you can refer to the StarLink Project's community joining methods.
- [https://github.com/knownsec/404StarLink-Project#community](https://github.com/knownsec/404StarLink-Project#community)
</br>
---------------------------------
References:
<https://www.zoomeye.org/doc>
knownsec 404
Update Time: 2025.02.06
Raw data
{
"_id": null,
"home_page": "https://github.com/knownsec/zoomeye-python",
"name": "zoomeye",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "security tool, zoomeye, command tool",
"author": "404 Team@Knownsec",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/32/bf/83937aa8351be1b53dbcd75d5897714bf95d2f7a0ecadcb07531ae6e3bc7/zoomeye-3.0.0.tar.gz",
"platform": null,
"description": "## ZoomEye-python\n\nEnglish | [\u4e2d\u6587\u6587\u6863](./docs/README_CN.md) \n\n`ZoomEye` is a cyberspace search engine that allows users to search for network devices through a browser at <https://www.zoomeye.org>.\n\n`ZoomEye-python` is a Python library developed based on the `ZoomEye API`, providing both command-line interface and SDK integration capabilities for other tools. This library enables technical professionals to **search** and **export** ZoomEye data more conveniently.\n\n### 0x01 Installation Steps\nInstall directly from `pypi`:\n\n pip3 install zoomeye\n\nOr install via `github`:\n\n pip3 install git+https://github.com/knownsec/ZoomEye-python.git\n\n\n### 0x02 Using CLI\nAfter successfully installing `ZoomEye-python`, you can directly use the `zoomeye` command as follows:\n\n```\n$ zoomeye -h\nusage: zoomeye [-h] [-v] {info,init,search,clear} ...\n\npositional arguments:\n {info,init,search,clear}\n info Show ZoomEye account info\n init Initialize the token for ZoomEye-python\n search get network asset information based on query conditions.\n clear Manually clear the cache and user information\n\noptions:\n -h, --help show this help message and exit\n -v, --version show program's version number and exit\n```\n\n#### 1. Token Initialization\nBefore using `ZoomEye-python CLI`, you need to initialize the user `token`. This credential is used to verify user identity for querying data from `ZoomEye`; only API-KEY authentication is supported.\n\nYou can view help through `zoomeye init -h`. Here's a demonstration using `APIKEY`:\n\n```\n$ zoomeye init -apikey \"01234567-acbd-00000-1111-22222222222\"\nUsername: your username\nRole: Professional\nPoints: 800000\nZoomeye Points: 0\n```\n\nUsers can obtain their `APIKEY` by logging into `ZoomEye` and accessing their profile (<https://www.zoomeye.org/profile>). The `APIKEY` doesn't expire, and users can reset it in their profile as needed.\n\n#### 2. User Information\nUsers can retrieve their account information, subscription details, and current points through the `info` command:\n\n```\n$ zoomeye info\nusername: <username>\nemail: <email>\nphone: <phone number>\ncreated_at: 2021-01-15\nSubscription:: {'plan': 'Professional', 'end_date': '2025-12-31', 'points': 800000, 'zoomeye_points': 0}\n```\n\n#### 3. Search\nSearch is the core functionality of `ZoomEye-python`, accessed through the `search` command. The `search` command requires a search keyword (`dork`). Here's a simple search example:\n\n```\n$ zoomeye search \"telnet\" \nsearch \"telnet\" \nip port domain update_time \n134.xx.xx.129 1901 [unknown] 2025-02-06T15:45:20 \n134.xx.xx.138 1901 [unknown] 2025-02-06T15:45:19\n......\n\ntotal: 20/9976411\n```\n\nUsing the `search` command is as simple as searching on `ZoomEye` through a browser. By default, we display the most important fields that users can use to understand target information:\n\n 1.ip IP address\n 2.port Port\n 3.domain Target domain\n 4.update_time Target scan time\n\n`search` supports the following parameters (`zoomeye search -h`) for data processing:\n\n -facets facets Statistics items, comma-separated; supports country, subdivisions, city, product, service, device, os, and port.\n -fields field=regexp Return fields, comma-separated; default: ip, port, domain, update_time. For more info, see: https://www.zoomeye.org/doc/\n -sub_type {v4,v6,web,all} Data type, supports v4, v6, and web; default is v4.\n -page page Default is page 1, sorted by update time.\n -pagesize pagesize Number of queries per page, default is 10, maximum is 10,000 per page.\n -figure {pie,hist} Parameter for data visualization\n -save Save search results locally\n -force Ignore local cache files and fetch data directly from ZoomEye\n\n#### 4. Data Aggregation\nWe can use `-facets` for data aggregation statistics. Using `-facets` allows you to query the aggregation status of the full data set for that dork (aggregated by `ZoomEye` and retrieved via `API`)\n\n```\n$ zoomeye search \"telnet\" -facets product -pagesize 1\nip port domain update_time \n177.xxx.xx.142 2020 [unknown] 2025-02-06T15:59:49 \n\ntotal: 1/9976296\n ----------------------------------------\n ZoomEye total data:9976296\n -------------product Top 10-------------\n product count \n MikroTik router config httpd 3326013 \n [unknown] 2421245 \n Apache httpd 2411293 \n ProFTPD 285649 \n Pulse Secure VPN httpd 182296 \n Samsung printer telnetd 178147 \n Huawei telnetd 144382 \n Huawei switch telnetd 120421 \n TP-LINK TL-WR841N WAP httpd 118836 \n DVR httpd 100068 \n```\n\n#### 5. Data Export\nThe `-save` parameter can be used to export data as follows:\n\n```\n$ zoomeye search \"telnet\" -pagesize 1 -save\nsearch \"telnet\" -pagesize 1 -save\nip port domain update_time \n88.xx.xxx.78 3011 [unknown] 2025-02-06T16:00:53 \n\ntotal: 1/9976301\nsave file to telnet_1_1738829058.json successful!\n```\n\n#### 6. Data Visualization\nThe `-figure` parameter is for data visualization, offering both `pie` and `hist` (histogram) display options. When specified, it must be used together with `-facets`. Data is still displayed without specification. Here's an example of a pie chart:\n\n\n\nAnd a histogram:\n\n\n\n#### 7. Cleanup Function\nUsers search for large amounts of data daily, which can lead to increasing storage space in the cache folder. If users use `ZoomEye-python` on public servers, their `API KEY` and `ACCESS TOKEN` might be exposed.\nTherefore, `ZoomEye-python` provides a cleanup command `zoomeye clear` to clear cache data and user configurations. Usage is as follows:\n\n```\n$zoomeye clear -h\nusage: zoomeye clear [-h] [-setting] [-cache]\n\noptional arguments:\n -h, --help show this help message and exit\n -setting clear user api key and access token\n -cache clear local cache file\n```\n\n#### 12. Cache Mechanism\n`ZoomEye-python` provides a caching mechanism in `cli` mode, located at `~/.config/zoomeye/cache`, to conserve user quotas as much as possible. Data sets queried by users are cached locally for 5 days, and when users query the same data set, it won't consume their quota.\n\n### 0x04 Using SDK\n#### 1. Token Initialization\nSimilarly, the SDK only supports authentication via `APIKEY`:\n\n**APIKEY**\n```python\nfrom zoomeye.sdk import ZoomEye\nzm = ZoomEye(api_key=\"01234567-acbd-00000-1111-22222222222\")\n```\n\n#### 2. SDK API\nHere are the interfaces provided by the SDK and their descriptions:\n```\n1.userinfo()\n Get current user information\n\n2.search(dork, qbase64='', page=1, pagesize=20, sub_type='all', fields='', facets='')\n Get network asset information based on search criteria.\n```\n\n#### 3. Usage Example\n```python\nfrom zoomeye.sdk import ZoomEye\n>>> dir(ZoomEye)\n['__class__', '__delattr__', '__dict__', '__dir__', '__doc__', '__eq__', '__format__', '__ge__', '__getattribute__', '__getstate__', '__gt__', '__hash__', '__init__', '__init_subclass__', '__le__', '__lt__', '__module__', '__ne__', '__new__', '__reduce__', '__reduce_ex__', '__repr__', '__setattr__', '__sizeof__', '__str__', '__subclasshook__', '__weakref__', '_check_header', '_request', 'search', 'userinfo']\n>>> zm = ZoomEye(api_key=\"01234567-acbd-00000-1111-22222222222\")\n>>> zm.search('country=cn')\n{'code': 60000, 'message': 'success', 'query': 'country=cn', 'total': 823268005, 'data': [{...}], 'facets': {}}\n\n```\n\n### 0x05 Contributions\n[wh0ami1@knownsec 404](https://github.com/wh0ami1) \n[0x7F@knownsec 404](https://github.com/0x7Fancy) \n[dawu@knownsec 404](https://github.com/d4wu) \n[fenix@knownsec 404](https://github.com/13ph03nix)\n\n\n### 0x06 Issues\n**1. How to input dorks containing quotes?**\n\nWhen using CLI for search queries containing quotes, such as `\"<body style=\\\"margin:0;padding:0\\\"> <p align=\\\"center\\\"> <iframe src=\\\"index.xhtml\\\"\"`, the dork must be wrapped in quotes to represent it as a complete parameter when it contains quotes or multiple quotes. Otherwise, the command-line parameter parsing will have issues. The correct search format for this dork should be: `'\"<body style=\\\"margin:0;padding:0\\\"> <p align=\\\"center\\\"> <iframe src=\\\"index.xhtml\\\"\"'`.\n\n> If there are no spaces or special characters, quotes can be omitted as the parameter parser will consume one set of quotes\n\n\n\n\n\n**2. zoomeye-ai**\n\nIf you are not a user from mainland China, please use <https://github.com/zoomeye-ai/ZoomEye-python>\n\n### 0x07 404StarLink Project\n\n\n\nZoomEye-python is part of 404Team's [StarLink Project](https://github.com/knownsec/404StarLink-Project). If you have any questions about ZoomEye-python or want to connect with other users, you can refer to the StarLink Project's community joining methods.\n\n- [https://github.com/knownsec/404StarLink-Project#community](https://github.com/knownsec/404StarLink-Project#community)\n\n</br>\n\n---------------------------------\nReferences: \n<https://www.zoomeye.org/doc> \n\nknownsec 404 \nUpdate Time: 2025.02.06\n",
"bugtrack_url": null,
"license": null,
"summary": "Python library and command-line tool for ZoomEye (https://www.zoomeye.org/doc)",
"version": "3.0.0",
"project_urls": {
"Homepage": "https://github.com/knownsec/zoomeye-python"
},
"split_keywords": [
"security tool",
" zoomeye",
" command tool"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6426fd87d7392d84710d3b29a5afb1599f7a50cc7f04eff4740f48e957b315a2",
"md5": "9912a83647cfc90ee799f4919172f720",
"sha256": "1bbc81d8f2df585517acc7b9d9ad19e36ff6e6a574f5585db282d6a257b30622"
},
"downloads": -1,
"filename": "zoomeye-3.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9912a83647cfc90ee799f4919172f720",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 26009,
"upload_time": "2025-02-07T02:20:18",
"upload_time_iso_8601": "2025-02-07T02:20:18.500736Z",
"url": "https://files.pythonhosted.org/packages/64/26/fd87d7392d84710d3b29a5afb1599f7a50cc7f04eff4740f48e957b315a2/zoomeye-3.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "32bf83937aa8351be1b53dbcd75d5897714bf95d2f7a0ecadcb07531ae6e3bc7",
"md5": "ceaf41b73300758c6ff376366b8e0b5b",
"sha256": "84a15f9a48a98ada3c1ce963d4e4e37dd0701c2a4fbf7e35637ba0163380bf72"
},
"downloads": -1,
"filename": "zoomeye-3.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ceaf41b73300758c6ff376366b8e0b5b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 26572,
"upload_time": "2025-02-07T02:20:19",
"upload_time_iso_8601": "2025-02-07T02:20:19.669579Z",
"url": "https://files.pythonhosted.org/packages/32/bf/83937aa8351be1b53dbcd75d5897714bf95d2f7a0ecadcb07531ae6e3bc7/zoomeye-3.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-07 02:20:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "knownsec",
"github_project": "zoomeye-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "certifi",
"specs": [
[
"==",
"2021.10.8"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"2.0.8"
]
]
},
{
"name": "colorama",
"specs": [
[
"==",
"0.4.4"
]
]
},
{
"name": "graphviz",
"specs": [
[
"==",
"0.19"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.3"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.26.0"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"1.26.7"
]
]
}
],
"lcname": "zoomeye"
}
JSON
