zoomeye-ai-search

Command-line tool for searching global network assets using ZoomEye AI, supporting advanced queries for asset discovery, CVE, and Bug Bounty research.

ZoomEye AI — Cyberspace Search

Search global network assets via the zoomeyeai CLI at https://www.zoomeye.ai.

Key features: Supports vul.cve, is_bugbounty, bugbounty.source, is_changed, is_new fields.

When to Use

Triggers (MUST load this skill)

• Searching global/overseas network assets
• Building dork queries for ZoomEye international
• Searching assets affected by a CVE
• Bug Bounty asset discovery and filtering
• Searching for assets added or changed in the last 7 days
• User mentions "zoomeyeai", "zoomeye.ai", "ZoomEye AI", "ZoomEye international"

Skip

• Purely theoretical discussion, no execution needed
• User asks about Shodan, Censys, or other search engines

Syntax-only mode

If the user only wants natural language → dork conversion ("how do I search for...", "write me the syntax for..."), skip environment checks and execution. Go directly to Workflow → Step 1 and output the dork.

Prerequisites

Step 1: Check Environment

Always verify the environment before executing any search:

# Check if installed
which zoomeyeai && zoomeyeai --version

# Check if token is configured
zoomeyeai info

Step 2: Guide the User Based on Results

If zoomeyeai is not installed:

pip3 install zoomeyeai

If zoomeyeai info returns an auth error (token not configured):

1. Tell the user they need a ZoomEye AI API-KEY:

   To use ZoomEye international search, you need an API-KEY:

   1. Go to https://www.zoomeye.ai/profile and log in
   2. Find your API-KEY in your profile
   3. Send me the key and I'll initialize it for you

2. Once the user provides the key:

   zoomeyeai init -apikey "<APIKEY>"
   

3. Verify:

   zoomeyeai info
   

   Confirm the response shows user info and quota, then proceed.

If zoomeyeai info returns normally:

Environment is ready. Proceed to workflow.

CLI Commands

zoomeyeai -h                        # Help
zoomeyeai --version                 # Version
zoomeyeai init -apikey "<KEY>"      # Initialize token
zoomeyeai info                      # Account info & quota
zoomeyeai search "<dork>" [options] # Core search command

Note: No clear command.

Search Options

Option	Description
-page <n>	Page number, default 1, sorted by update time
-pagesize <n>	Results per page, default 10, max 10000
-sub_type {v4,v6,web,all}	Data type. v4=IPv4 devices (default), v6=IPv6, web=websites/domains, all=everything
-facets <items>	Aggregate stats, comma-separated. Supports: product, device, service, os, port, country, subdivisions, city
-fields <fields>	Return fields, comma-separated. Default: ip,port,domain,update_time
-figure {pie,hist}	Data visualization. Requires -facets

Error Handling

Error	Cause	Action
Auth failure / login required	Token not configured	Run zoomeyeai init -apikey "<APIKEY>"
rate limit exceeded / empty results	Quota exhausted or rate limited	Wait and retry, or check quota → zoomeyeai info
Command timeout	Network issue or slow API	Retry once; if still failing, tell user to check network

Search Syntax

Basic Rules

• Search is case-insensitive (except == exact match)
• Search strings are word-segmented for matching
• Wrap string values in quotes: "Cisco System" or 'Cisco System'
• Escape internal quotes with \: "a\"b"
• Escape parentheses with \: portinfo\(\)

Logical Operators

Operator	Meaning	Example
=	Fuzzy match (contains keyword)	title="knownsec"
==	Exact match (case-sensitive, can search empty values)	title=="knownsec"
||	OR	service="ssh" || service="http"
&&	AND	device="router" && after="2020-01-01"
!=	NOT	country="US" && subdivisions!="new york"
()	Grouping / precedence	(country="US" && port!=80) || (country="US" && title!="404 Not Found")
*	Wildcard / fuzzy	title="google*"

Search Field Reference

Device & Service Fingerprints

Field	Description	Common Values
app	Application/product fingerprint	"Cisco ASA SSL VPN", "GitLab", "phpMyAdmin"
service	Service protocol	"ssh", "http", "ftp", "telnet", "mysql", "redis", "rdp", "smb"
device	Device type	"router", "switch", "storage-misc", "firewall", "webcam"
os	Operating system	"RouterOS", "Linux", "Windows", "IOS", "JUNOS"
title	HTML title	"admin", "login", "Cisco"
industry	Industry type	"government", "technology", "energy", "finance", "manufacturing"
product	Component/product name	"Cisco", "Apache", "Nginx"
protocol	Transport protocol	"TCP", "UDP", "TCP6", "SCTP"
is_honeypot	Honeypot filter	"True" / "False"

IP, Domain & Organization

Field	Description	Example
ip	IP address (v4/v6)	ip="8.8.8.8", ip="2600:3c00::f03c:91ff:fefc:574a"
cidr	CIDR range	cidr="52.2.254.36/24" (/24=C, /16=B, /8=A)
org	Organization name	org="Stanford University"
isp	ISP name	isp="China Mobile"
asn	AS number	asn=42893
port	Port number	port=80 (single port only)
hostname	Hostname	hostname="google.com"
domain	Domain/subdomain	domain="baidu.com"

Geolocation (English)

Field	Description	Example
country	Country (abbreviation or full name)	"US", "United States", "JP"
subdivisions	State/province (English)	"california", "new york", "tokyo"
city	City (English)	"san francisco", "london"

SSL/TLS Certificates

Field	Description	Example
ssl	Certificate content contains (use for product/company search)	ssl="google"
ssl.cert.fingerprint	SHA1 fingerprint	ssl.cert.fingerprint="F3C98F223D82CC41CF83D94671CCC6C69873FABF"
ssl.chain_count	Cert chain count	ssl.chain_count=3
ssl.cert.alg	Signature algorithm	ssl.cert.alg="SHA256-RSA"
ssl.cert.issuer.cn	Issuer CN	ssl.cert.issuer.cn="pbx.wildix.com"
ssl.cert.subject.cn	Subject CN	ssl.cert.subject.cn="example.com"
ssl.cert.pubkey.rsa.bits	RSA public key bits	ssl.cert.pubkey.rsa.bits=2048
ssl.cert.pubkey.ecdsa.bits	ECDSA public key bits	ssl.cert.pubkey.ecdsa.bits=256
ssl.cert.pubkey.type	Public key type	ssl.cert.pubkey.type="RSA"
ssl.cert.serial	Certificate serial	ssl.cert.serial="18460192207935675900910674501"
ssl.cipher.bits	Cipher bits	ssl.cipher.bits="128"
ssl.cipher.name	Cipher suite name	ssl.cipher.name="TLS_AES_128_GCM_SHA256"
ssl.cipher.version	Cipher suite version	ssl.cipher.version="TLSv1.3"
ssl.version	SSL/TLS version	ssl.version="TLSv1.3"
ssl.jarm	JARM fingerprint	ssl.jarm="29d29d15d29d29d00029d29d29d29dea0f89a2e5fb09e4d8e099befed92cfa"
ssl.ja3s	JA3S fingerprint	ssl.ja3s=45094d08156d110d8ee97b204143db14

HTTP Headers & Body

Field	Description	Example
http.header	HTTP response headers contain	http.header="http"
http.header_hash	Response header MD5	http.header_hash="27f9973fe57298c3b63919259877a84d"
http.header.server	Server header value	http.header.server="Nginx"
http.header.version	Server version	http.header.version="1.2"
http.header.status_code	HTTP status code	"200", "302", "404", "500"
http.body	HTML body contains	http.body="document"
http.body_hash	HTML body MD5	http.body_hash="84a18166fde3ee7e7c974b8d1e7e21b4"

Protocol Banners, Hashes & Time

Field	Description	Example
banner	Non-HTTP protocol banner	banner="FTP"
iconhash	Favicon hash (MD5 or mmh3)	iconhash="f3418a443e7d841097c714d69ec4bcb8", iconhash="1941681276"
filehash	Uploaded file hash	filehash="0b5ce08db7fb8fffe4e14d05588d49d9"
dig	DNS dig result	dig="baidu.com 220.181.38.148"
after	Updated after	after="2020-01-01" (must combine with other filters)
before	Updated before	before="2020-01-01" (must combine with other filters)

Additional Fields

The following fields are available:

Field	Description	Example
vul.cve	Search by CVE ID	vul.cve="CVE-2021-44228"
is_bugbounty	Bug Bounty program assets	is_bugbounty=true
bugbounty.source	Bug Bounty data source	bugbounty.source="hackerone", "bugcrowd", "intigriti", "yeswehack", "openbugbounty", "all"
is_changed	Asset changed within 7 days (new + updated)	is_changed=true
is_new	Newly discovered within 7 days	is_new=true

Workflow (AI Decision Tree)

Once the environment is verified, follow these steps:

1. Natural Language → Dork Conversion

Geolocation Keywords

User says	Field	Conversion
"US", "United States", "America"	country	country="US"
"Japan", "JP"	country	country="JP"
"Germany", "DE"	country	country="DE"
"California", "CA"	subdivisions	subdivisions="california"
"New York", "NY"	city or subdivisions	city="new york"
Any English city/state name	city / subdivisions	city="london"

Port/Service Keywords

User says	Field	Conversion
"port XX", "open port XX"	port	port=80
"SSH", "SSH service"	service	service="ssh"
"HTTP", "web", "website"	service	service="http"
"database", "MySQL", "Redis", "MongoDB"	service	service="mysql"
"RDP", "remote desktop"	service or port	service="rdp"

Device/OS Keywords

User says	Field	Conversion
"router"	device	device="router"
"switch"	device	device="switch"
"webcam", "camera"	device	device="webcam"
"Linux", "Linux server"	os	os="Linux"
"Windows", "Windows server"	os	os="Windows"
"Cisco"	app	app="Cisco"

Additional Keywords

User says	Field	Conversion
"CVE-2021-44228", "Log4j vulnerability", "impact of CVE"	vul.cve	vul.cve="CVE-2021-44228"
"Bug Bounty assets", "bounty program"	is_bugbounty	is_bugbounty=true
"HackerOne assets", "Bugcrowd's"	bugbounty.source	bugbounty.source="hackerone"
"new in last 7 days", "recently discovered", "new assets"	is_new	is_new=true
"changed in last 7 days", "recently updated"	is_changed	is_changed=true
"all Bug Bounty sources"	bugbounty.source	bugbounty.source="all"

Conversion Examples

Natural Language	Dork
"SSH services in the US"	country="US" && service="ssh"
"Log4j vulnerability affected assets globally"	vul.cve="CVE-2021-44228"
"Nginx servers on HackerOne"	bugbounty.source="hackerone" && http.header.server="Nginx"
"Redis services discovered in the last 7 days"	service="redis" && is_new=true
"Routers in Japan, exclude honeypots"	country="JP" && device="router" && is_honeypot!="True"
"Changed GitLab assets in Bug Bounty"	is_bugbounty=true && is_changed=true && app="GitLab"
"Windows RDP in Germany"	country="DE" && service="rdp" && os="Windows"
"Assets with port 3389 open, recently changed"	port=3389 && is_changed=true
"Admin panels in California"	(title="admin" || title="login") && subdivisions="california"
"Let's Encrypt certs on US assets"	ssl.cert.issuer.cn="Let's Encrypt" && country="US"

2. Build the Dork

Combine fields with operators:

• Narrow down → &&: country="US" && service="redis" && os="Linux"
• Broaden → ||: port=80 || port=443 || port=8080
• Exclude → !=: country="US" && subdivisions!="california"
• Complex logic → (): (country="US" && port!=80) || (country="JP" && title!="404 Not Found")

3. Choose sub_type

Scenario	sub_type
IoT, servers, cameras, ICS, IPv4 assets	v4 (default)
IPv6 assets	v6
Websites, web apps, domains	web
Unsure, need everything	all

4. Execution Strategy (Quota Optimization)

Follow "probe → verify → export":

# Step 1: Small probe to confirm dork syntax and results
zoomeyeai search "<dork>" -pagesize 10

# Step 2: Check data distribution with facets (pagesize=1 saves quota)
zoomeyeai search "<dork>" -facets country,service,os -pagesize 1

# Step 3: Bulk retrieval
zoomeyeai search "<dork>" -pagesize 1000

5. Shell Quoting Rules

Scenario	Outer Quote	Example
Dork with field="value" only, no single quotes	Single quotes	zoomeyeai search 'country="US" && service="ssh"'
Dork contains single quote character	Double quotes	zoomeyeai search "title='Cisco System'"
Dork contains &&, || shell special chars	Single quotes (safest)	zoomeyeai search 'service="ssh" || service="http"'

Key rule: prefer single quotes as the outer wrapper. Only switch to double quotes when the dork itself contains single quote characters.

Common Search Scenarios

CVE Vulnerability Impact Assessment

# Global distribution of a CVE
zoomeyeai search 'vul.cve="CVE-2021-44228"' -facets country -pagesize 1

# CVE + specific product version
zoomeyeai search 'vul.cve="CVE-2021-44228" && app="Log4j"' -pagesize 100

Bug Bounty Asset Discovery

# Bug Bounty assets from a specific platform
zoomeyeai search 'is_bugbounty=true && bugbounty.source="hackerone"' -pagesize 10

# Specific product in Bug Bounty
zoomeyeai search 'is_bugbounty=true && app="GitLab"' -pagesize 10

# HTTP services across all Bug Bounty platforms
zoomeyeai search 'is_bugbounty=true && bugbounty.source="all" && service="http"' -pagesize 10

New & Changed Asset Monitoring

# SSH services discovered in last 7 days
zoomeyeai search 'service="ssh" && is_new=true' -pagesize 10

# Web assets changed in last 7 days
zoomeyeai search 'service="http" && is_changed=true' -facets country -pagesize 1

# Newly discovered assets affected by a CVE
zoomeyeai search 'vul.cve="CVE-2024-1234" && is_new=true' -pagesize 100

Global Exposure Discovery

# Exposed database services in a country
zoomeyeai search 'country="US" && (service="redis" || service="mysql" || service="mongodb")' -pagesize 10

# Assets of an organization
zoomeyeai search 'org="Stanford University"' -pagesize 100

# Global RDP services, excluding honeypots
zoomeyeai search 'service="rdp" && is_honeypot!="True"' -pagesize 10

Web Application Identification

# Web servers by Server header
zoomeyeai search 'http.header.server="nginx" && country="US"' -sub_type web -pagesize 10

# Admin panels by title
zoomeyeai search '(title="admin" || title="login") && country="JP"' -sub_type web -pagesize 10

# Specific apps by body content
zoomeyeai search 'http.body="phpMyAdmin"' -sub_type web -pagesize 10

SSL Certificate & Fingerprint

# Assets linked to a company's certificate
zoomeyeai search 'ssl="google"' -pagesize 10

# Let's Encrypt issued certificates
zoomeyeai search "ssl.cert.issuer.cn=\"Let's Encrypt\" && country=\"US\"" -pagesize 10

# JARM fingerprint search
zoomeyeai search 'ssl.jarm="29d29d15d29d29d00029d29d29d29dea0f89a2e5fb09e4d8e099befed92cfa"' -pagesize 10

Subnet & IP Scanning

zoomeyeai search 'cidr="52.2.254.36/24"' -pagesize 100
zoomeyeai search 'cidr="52.2.254.36/16" && service="http"' -pagesize 100

SDK Usage

from zoomeyeai.sdk import ZoomEye

zm = ZoomEye(api_key="your-api-key")

# Account info & quota
zm.userinfo()
# Returns: {"email": "", "username": "", "quota": {"plan": "", "end_date": "", "points": "", "zoomeye_points": ""}}

# Search
result = zm.search(
    dork='country=us',
    qbase64='',                  # Base64-encoded query (alternative to dork)
    page=1,
    pagesize=20,                 # SDK default is 20
    sub_type='all',              # v4 / v6 / web / all
    fields='ip,port,domain,os,app,title',
    facets='country,service'
)

Notes

Item	Detail
Quota	Each search consumes quota. Use -pagesize 1 + -facets first, then bulk retrieve
Geolocation	Use English names, e.g. country="United States" or country="US"
-save	Not available. Export data manually or use SDK
before/after	Cannot be used alone; must combine with other filters
Shell quoting	Always wrap the dork in quotes. Prefer single quotes