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):

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
Once the user provides the key:
```
zoomeyeai init -apikey "<APIKEY>"
```
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 |