Command-line tool for searching global network assets using ZoomEye AI, supporting advanced queries for asset discovery, CVE, and Bug Bounty research.
---
name: zoomeye-ai-search
description: ZoomEye AI cyberspace search engine CLI. Use when searching global network assets, querying ZoomEye data, building ZoomEye AI dork queries, or conducting security research (asset discovery, vulnerability impact assessment, Bug Bounty, CVE correlation). CLI command: zoomeyeai, package: zoomeyeai, domain: zoomeye.ai.
---
# 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](#1-natural-language--dork-conversion) and output the dork.
## Prerequisites
### Step 1: Check Environment
Always verify the environment before executing any search:
```bash
# 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:**
```bash
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:
```bash
zoomeyeai init -apikey "<APIKEY>"
```
3. Verify:
```bash
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
```bash
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":
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
zoomeyeai search 'cidr="52.2.254.36/24"' -pagesize 100
zoomeyeai search 'cidr="52.2.254.36/16" && service="http"' -pagesize 100
```
## SDK Usage
```python
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 |
don't have the plugin yet? install it then click "run inline in claude" again.
restructured original skill into implexa 6-component format, extracted decision logic into explicit if-else branches, documented api key setup and quota constraints as inputs, formalized procedure as 7 sequential steps with explicit inputs/outputs, added edge cases for auth expiry/rate limits/timeouts/empty results, preserved all original search syntax and examples.
search global network assets via the zoomeyeai CLI to discover, fingerprint, and correlate devices, services, and vulnerabilities across the internet. use this skill when conducting asset discovery, vulnerability impact assessment, bug bounty research, or building complex dork queries for ZoomEye international data. triggers include: searching for CVE-affected assets, identifying bug bounty program targets, finding newly discovered or recently changed infrastructure, or explicit mentions of zoomeyeai/zoomeye.ai by the user.
required external connection:
ZOOMEYEAI_API_KEY (optional; CLI can init manually)zoomeyeai inforequired local environment:
pip3 install zoomeyeai)optional context:
step 1: verify zoomeyeai installation and api key.
run which zoomeyeai && zoomeyeai --version to confirm cli is installed. then run zoomeyeai info to verify api key is configured. if either fails, proceed to decision points.
step 2: convert user intent to dork syntax.
parse natural language request into ZoomEye dork query. use the geolocation, port/service, device/os, and additional keywords tables to map user terms to field names and operators (=, ==, &&, ||, !=, parentheses for grouping). example: "ssh services in the us" becomes country="US" && service="ssh". for syntax-only requests (no execution), stop here and output the dork.
step 3: select sub_type parameter.
choose data scope: v4 (ipv4 devices, default), v6 (ipv6), web (websites/domains), or all (everything). default to v4 for iot/infrastructure queries, web for domain/app queries, all if scope is unclear.
step 4: probe with small pagesize.
execute zoomeyeai search '<dork>' -pagesize 10 to validate dork syntax and confirm results exist. outputs include ip, port, domain, and update_time by default. check for parsing errors or empty result sets.
step 5: inspect data distribution with facets (optional).
run zoomeyeai search '<dork>' -facets country,service,os -pagesize 1 to preview aggregate stats without consuming full quota. use this to narrow or broaden the dork before bulk export.
step 6: bulk retrieval if results confirmed.
execute zoomeyeai search '<dork>' -pagesize 1000 (or desired page size up to 10000) to export full dataset. add -fields ip,port,domain,service,app,os,title to customize output. repeat with -page 2, -page 3, etc. if pagination needed.
step 7: validate output format and report results. confirm zoomeyeai cli returns json or plaintext results. save or parse results per user request (csv export, json parsing, or simple count). report total asset count, top countries/services/products, and any relevant fingerprints (ssl, http headers, cves).
if zoomeyeai cli is not installed:
guide user to run pip3 install zoomeyeai. wait for confirmation before proceeding.
if zoomeyeai info returns auth error (token not configured):
prompt user to retrieve api key from https://www.zoomeye.ai/profile (requires login). once user provides key, run zoomeyeai init -apikey "<KEY>". verify with zoomeyeai info and confirm user/quota info appears before proceeding to step 2.
if user requests syntax-only conversion (no execution): skip environment/auth checks. go directly to step 2 (dork conversion), output the formatted dork query, and stop. do not attempt to run zoomeyeai search.
if search returns empty results: confirm dork syntax is valid (check field names, quotes, operators). try broadening query (remove filters, use || instead of &&) or adjust pagesize. if dork is correctly formed and results are legitimately zero, report this to user.
if rate limit error or quota exhausted:
run zoomeyeai info to display remaining quota/points. wait before retry (zoomeyeai enforces per-second limits). if quota is zero, inform user that plan renewal or upgrade is required.
if network timeout or command hangs: retry once with smaller pagesize (e.g., pagesize=10 instead of 1000). if timeout persists, advise user to check network connectivity and zoomeye.ai service status. do not retry indefinitely.
if dork contains shell special characters (&&, ||, parentheses):
wrap entire dork in single quotes for safe shell execution, e.g., zoomeyeai search 'country="US" && service="ssh"'. if dork itself contains single quotes, switch to double quotes: zoomeyeai search "title='Cisco System'".
on success:
zoomeyeai returns json or plaintext records with fields: ip, port, domain, update_time (default), plus optional fields requested via -fields parameter. each record represents one asset (device, service, or web entity) matching the dork.
data format and location:
zoomeyeai search '...' > results.txt)zm.search() call, serializable to jsonpagination:
results are paginated. default pagesize is 10, max is 10000. use -page N and -pagesize N to retrieve specific pages.
facet aggregation:
if -facets country,service requested, output includes aggregate counts per facet value (e.g., country: {US: 1234, CN: 567}, service: {http: 890, ssh: 345}).
error output: auth errors, rate limit messages, and syntax errors print to stderr. non-zero exit code indicates failure.
zoomeyeai info showing remaining points)key indicators of success: