Skip to content

Commit cb37a1d

Browse files
wh0am1iwh0am1i
authored
Merge pull request #122 from wh0am1i/master
update Zoomeye api to v2
2 parents 1990637 + efe035e commit cb37a1d

30 files changed

Lines changed: 675 additions & 3333 deletions

‎.github/workflows/python-publish.yml‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# This workflow will upload a Python Package using Twine when a release is created
2+
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
3+
4+
# This workflow uses actions that are not certified by GitHub.
5+
# They are provided by a third-party and are governed by
6+
# separate terms of service, privacy policy, and support
7+
# documentation.
8+
9+
name: Upload Python Package
10+
11+
on:
12+
release:
13+
types: [published]
14+
15+
permissions:
16+
contents: read
17+
18+
jobs:
19+
deploy:
20+
21+
runs-on: ubuntu-latest
22+
23+
steps:
24+
- uses: actions/checkout@v3
25+
- name: Set up Python
26+
uses: actions/setup-python@v3
27+
with:
28+
python-version: '3.x'
29+
- name: Install dependencies
30+
run: |
31+
python -m pip install --upgrade pip
32+
pip install build
33+
- name: Build package
34+
run: python -m build
35+
- name: Publish package
36+
uses: pypa/gh-action-pypi-publish@27b31702a0e7fc50959f5ad993c78deac1bdfc29
37+
with:
38+
user: __token__
39+
password: ${{ secrets.PYPI_API_TOKEN }}

‎README.md‎

Lines changed: 229 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,229 @@
1+
## ZoomEye-python
2+
3+
English | [中文文档](./docs/README_CN.md)
4+
5+
`ZoomEye` is a cyberspace search engine that allows users to search for network devices through a browser at <https://www.zoomeye.org>.
6+
7+
`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.
8+
9+
### 0x01 Installation Steps
10+
Install directly from `pypi`:
11+
12+
pip3 install zoomeye
13+
14+
Or install via `github`:
15+
16+
pip3 install git+https://github.com/knownsec/ZoomEye-python.git
17+
18+
19+
### 0x02 Using CLI
20+
After successfully installing `ZoomEye-python`, you can directly use the `zoomeye` command as follows:
21+
22+
```
23+
$ zoomeye -h
24+
usage: zoomeye [-h] [-v] {info,init,search,clear} ...
25+
26+
positional arguments:
27+
{info,init,search,clear}
28+
info Show ZoomEye account info
29+
init Initialize the token for ZoomEye-python
30+
search get network asset information based on query conditions.
31+
clear Manually clear the cache and user information
32+
33+
options:
34+
-h, --help show this help message and exit
35+
-v, --version show program's version number and exit
36+
```
37+
38+
#### 1. Token Initialization
39+
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.
40+
41+
You can view help through `zoomeye init -h`. Here's a demonstration using `APIKEY`:
42+
43+
```
44+
$ zoomeye init -apikey "01234567-acbd-00000-1111-22222222222"
45+
Username: your username
46+
Role: Professional
47+
Points: 800000
48+
Zoomeye Points: 0
49+
```
50+
51+
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.
52+
53+
#### 2. User Information
54+
Users can retrieve their account information, subscription details, and current points through the `info` command:
55+
56+
```
57+
$ zoomeye info
58+
username: <username>
59+
email: <email>
60+
phone: <phone number>
61+
created_at: 2021-01-15
62+
Subscription:: {'plan': 'Professional', 'end_date': '2025-12-31', 'points': 800000, 'zoomeye_points': 0}
63+
```
64+
65+
#### 3. Search
66+
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:
67+
68+
```
69+
$ zoomeye search "telnet"
70+
search "telnet"
71+
ip port domain update_time
72+
134.xx.xx.129 1901 [unknown] 2025-02-06T15:45:20
73+
134.xx.xx.138 1901 [unknown] 2025-02-06T15:45:19
74+
......
75+
76+
total: 20/9976411
77+
```
78+
79+
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:
80+
81+
1.ip IP address
82+
2.port Port
83+
3.domain Target domain
84+
4.update_time Target scan time
85+
86+
`search` supports the following parameters (`zoomeye search -h`) for data processing:
87+
88+
-facets facets Statistics items, comma-separated; supports country, subdivisions, city, product, service, device, os, and port.
89+
-fields field=regexp Return fields, comma-separated; default: ip, port, domain, update_time. For more info, see: https://www.zoomeye.org/doc/
90+
-sub_type {v4,v6,web,all} Data type, supports v4, v6, and web; default is v4.
91+
-page page Default is page 1, sorted by update time.
92+
-pagesize pagesize Number of queries per page, default is 10, maximum is 10,000 per page.
93+
-figure {pie,hist} Parameter for data visualization
94+
-save Save search results locally
95+
-force Ignore local cache files and fetch data directly from ZoomEye
96+
97+
#### 4. Data Aggregation
98+
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`)
99+
100+
```
101+
$ zoomeye search "telnet" -facets product -pagesize 1
102+
ip port domain update_time
103+
177.xxx.xx.142 2020 [unknown] 2025-02-06T15:59:49
104+
105+
total: 1/9976296
106+
----------------------------------------
107+
ZoomEye total data:9976296
108+
-------------product Top 10-------------
109+
product count
110+
MikroTik router config httpd 3326013
111+
[unknown] 2421245
112+
Apache httpd 2411293
113+
ProFTPD 285649
114+
Pulse Secure VPN httpd 182296
115+
Samsung printer telnetd 178147
116+
Huawei telnetd 144382
117+
Huawei switch telnetd 120421
118+
TP-LINK TL-WR841N WAP httpd 118836
119+
DVR httpd 100068
120+
```
121+
122+
#### 5. Data Export
123+
The `-save` parameter can be used to export data as follows:
124+
125+
```
126+
$ zoomeye search "telnet" -pagesize 1 -save
127+
search "telnet" -pagesize 1 -save
128+
ip port domain update_time
129+
88.xx.xxx.78 3011 [unknown] 2025-02-06T16:00:53
130+
131+
total: 1/9976301
132+
save file to telnet_1_1738829058.json successful!
133+
```
134+
135+
#### 6. Data Visualization
136+
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:
137+
138+
![](./images/pie.png)
139+
140+
And a histogram:
141+
142+
![](./images/hist.png)
143+
144+
#### 7. Cleanup Function
145+
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.
146+
Therefore, `ZoomEye-python` provides a cleanup command `zoomeye clear` to clear cache data and user configurations. Usage is as follows:
147+
148+
```
149+
$zoomeye clear -h
150+
usage: zoomeye clear [-h] [-setting] [-cache]
151+
152+
optional arguments:
153+
-h, --help show this help message and exit
154+
-setting clear user api key and access token
155+
-cache clear local cache file
156+
```
157+
158+
#### 12. Cache Mechanism
159+
`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.
160+
161+
### 0x04 Using SDK
162+
#### 1. Token Initialization
163+
Similarly, the SDK only supports authentication via `APIKEY`:
164+
165+
**APIKEY**
166+
```python
167+
from zoomeye.sdk import ZoomEye
168+
zm = ZoomEye(api_key="01234567-acbd-00000-1111-22222222222")
169+
```
170+
171+
#### 2. SDK API
172+
Here are the interfaces provided by the SDK and their descriptions:
173+
```
174+
1.userinfo()
175+
Get current user information
176+
177+
2.search(dork, qbase64='', page=1, pagesize=20, sub_type='all', fields='', facets='')
178+
Get network asset information based on search criteria.
179+
```
180+
181+
#### 3. Usage Example
182+
```python
183+
from zoomeye.sdk import ZoomEye
184+
>>> dir(ZoomEye)
185+
['__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']
186+
>>> zm = ZoomEye(api_key="01234567-acbd-00000-1111-22222222222")
187+
>>> zm.search('country=cn')
188+
{'code': 60000, 'message': 'success', 'query': 'country=cn', 'total': 823268005, 'data': [{...}], 'facets': {}}
189+
190+
```
191+
192+
### 0x05 Contributions
193+
[wh0ami1@knownsec 404](https://github.com/wh0ami1)
194+
[0x7F@knownsec 404](https://github.com/0x7Fancy)
195+
[dawu@knownsec 404](https://github.com/d4wu)
196+
[fenix@knownsec 404](https://github.com/13ph03nix)
197+
198+
199+
### 0x06 Issues
200+
**1. How to input dorks containing quotes?**
201+
202+
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\""'`.
203+
204+
> If there are no spaces or special characters, quotes can be omitted as the parameter parser will consume one set of quotes
205+
206+
![](./images/web_search.png)
207+
208+
![](./images/cli_search.png)
209+
210+
**2. zoomeye-ai**
211+
212+
If you are not a user from mainland China, please use <https://github.com/zoomeye-ai/ZoomEye-python>
213+
214+
### 0x07 404StarLink Project
215+
216+
![](https://github.com/knownsec/404StarLink-Project/raw/master/logo.png)
217+
218+
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.
219+
220+
- [https://github.com/knownsec/404StarLink-Project#community](https://github.com/knownsec/404StarLink-Project#community)
221+
222+
</br>
223+
224+
---------------------------------
225+
References:
226+
<https://www.zoomeye.org/doc>
227+
228+
knownsec 404
229+
Update Time: 2025.02.06

0 commit comments

Comments
 (0)