Documentation

Hosts

Query and inspect discovered hosts with their services, geolocation, and cloud metadata.

GET /api/hosts

Search and filter hosts. Supports text search, country, cloud, port, ASN, service, and technology filters.

Parameters

Name	Type	Description	Default
q	string	Text search (IP, hostname, org)	-
country	string	Country code (US, FR, DE...)	-
cloud	string	Cloud provider (aws, gcp, azure, do)	-
port	int	Filter by open port	-
asn	int	AS number	-
service	string	Service name (http, ssh, ftp...)	-
technology	string	Detected technology	-
verified	bool	Only verified hosts	-
limit	int	Results per page	50
page	int	Page number	1

Example

curl "http://localhost:8080/api/hosts?country=FR&port=443&limit=10"

GET /api/hosts/:ip

Get detailed host information including all services, certificates, domains, and enrichment data.

Parameters

Name	Type	Description	Default
ip required	string	IP address (path parameter)	-

Example

curl "http://localhost:8080/api/hosts/192.168.1.1"

Services

Search services discovered across all scanned hosts.

GET /api/services

Search services by name, product, or text query.

Parameters

Name	Type	Description	Default
q	string	Text search	-
service	string	Service name filter	-
product	string	Product name filter	-
limit	int	Results per page	50

Example

curl "http://localhost:8080/api/services?service=ssh&limit=20"

Certificates

Search and inspect TLS/X.509 certificates collected during scans.

GET /api/certificates

Search certificates by subject, issuer, or text query.

Parameters

Name	Type	Description	Default
q	string	Text search	-
subject	string	Subject CN filter	-
issuer	string	Issuer CN filter	-
limit	int	Results per page	50
page	int	Page number	1

Example

curl "http://localhost:8080/api/certificates?subject=*.example.com"

GET /api/certificates/:fingerprint/hosts

Get all hosts using a specific certificate identified by its SHA256 fingerprint.

Parameters

Name	Type	Description	Default
fingerprint required	string	Certificate SHA256 fingerprint (path parameter)	-

Example

curl "http://localhost:8080/api/certificates/abc123def456/hosts"

Domains

Explore domains discovered through certificates, SNI, and reverse DNS.

GET /api/domains

Search discovered domains with optional protocol and status filters.

Parameters

Name	Type	Description	Default
q	string	Domain name search	-
protocol	string	Protocol filter (http, ssh, ftp, smtp)	-
status	int	HTTP status code filter	-
limit	int	Results per page	50
page	int	Page number	1

Example

curl "http://localhost:8080/api/domains?q=example.com&protocol=http"

GET /api/domains/stats

Get domain statistics overview (total domains, protocols, top TLDs).

Example

curl "http://localhost:8080/api/domains/stats"

GET /api/domains/:domain/services

Get all services discovered on a specific domain.

Parameters

Name	Type	Description	Default
domain required	string	Domain name (path parameter)	-

Example

curl "http://localhost:8080/api/domains/example.com/services"

GET /api/body

Get HTTP response body preview for a specific IP:port service.

Parameters

Name	Type	Description	Default
ip required	string	IP address	-
port required	int	Port number	-

Example

curl "http://localhost:8080/api/body?ip=192.168.1.1&port=443"

Search (MeowQL)

Advanced search using the MeowQL query language. See the MeowQL tab for full syntax reference.

GET /api/search

Host-centric MeowQL search. Returns hosts matching the query with their matched services.

Parameters

Name	Type	Description	Default
q required	string	MeowQL query (e.g. `port:443 country:US`)	-
limit	int	Results per page	50
page	int	Page number	1

Example

curl "http://localhost:8080/api/search?q=port%3A443+country%3AUS&limit=20"

GET /api/search/services

Service-centric MeowQL search. Returns individual services matching the query.

Parameters

Name	Type	Description	Default
q required	string	MeowQL query	-
limit	int	Results per page	50
page	int	Page number	1

Example

curl "http://localhost:8080/api/search/services?q=service%3Assh+country%3AFR"

GET /api/autocomplete

Autocomplete suggestions for MeowQL fields and values.

Parameters

Name	Type	Description	Default
q required	string	Partial input to autocomplete	-
field	string	Field name to get value suggestions for	-

Example

curl "http://localhost:8080/api/autocomplete?q=coun&field=country"

Statistics

Aggregated statistics about your scan data: countries, services, cloud providers, technologies.

GET/api/stats/dashboard

Dashboard overview: total hosts, services, certificates, top countries, top services, cloud distribution.

Example

curl "http://localhost:8080/api/stats/dashboard"

GET/api/stats/countries

Country breakdown with host count and cloud provider presence per country.

Example

curl "http://localhost:8080/api/stats/countries"

GET/api/stats/services

Service distribution across all hosts.

Example

curl "http://localhost:8080/api/stats/services"

GET/api/stats/cloud

Cloud provider distribution (AWS, GCP, Azure, DigitalOcean, etc.).

Example

curl "http://localhost:8080/api/stats/cloud"

GET/api/stats/technologies

Detected technologies and web frameworks distribution.

Example

curl "http://localhost:8080/api/stats/technologies"

GET/api/stats/products

Product and version distribution.

Example

curl "http://localhost:8080/api/stats/products"

GET/api/facets

Facet counts for filter dropdowns (distinct ports, services, countries, cloud providers).

Example

curl "http://localhost:8080/api/facets"

Geographic

Geographic distribution data for map visualizations and country analysis.

GET/api/geomap

Geographic host distribution data with optional service group filtering.

Parameters

Name	Type	Description	Default
groups	string	Comma-separated service groups (admin, http, mail, db)	-

Example

curl "http://localhost:8080/api/geomap?groups=admin,http"

GET/api/geomap/country/:code

Detailed country breakdown: services, ports, ASNs, cities, cloud providers.

Parameters

Name	Type	Description	Default
code required	string	ISO country code (e.g. US, FR)	-

Example

curl "http://localhost:8080/api/geomap/country/FR"

Export & Debug

Data export and system diagnostics endpoints.

GET/api/export

Export scan data in JSON or CSV format.

Parameters

Name	Type	Description	Default
format	string	Output format (json, csv)	json
type	string	Data type (hosts, services)	hosts

Example

curl "http://localhost:8080/api/export?format=csv&type=services"

GET/api/debug/stats

Detailed system statistics: NATS server, database records, enrichment pipeline state.

Example

curl "http://localhost:8080/api/debug/stats"

GET/api/tools/dns

DNS resolution helper. Resolves a domain name to IP addresses.

Parameters

Name	Type	Description	Default
domain required	string	Domain name to resolve	-

Example

curl "http://localhost:8080/api/tools/dns?domain=example.com"

Scanning

On-demand scan management. Requires a SynScan daemon connected via NATS.

GET/api/scanners

List active scanner nodes connected via NATS.

Example

curl "http://localhost:8080/api/scanners"

POST/api/scan

Submit a new scan request to connected scanner daemons. Requires JSON body.

Body Parameters (JSON)

Name	Type	Description	Default
target required	string	Target CIDR or IP range	-
ports	string	Ports to scan (e.g. 80,443,22)	80,443
rate	int	Packets per second	1000

Example

curl -X POST "http://localhost:8080/api/scan" \
  -H "Content-Type: application/json" \
  -d '{"target":"192.168.1.0/24","ports":"80,443","rate":5000}'

GET/api/events/recent

Get recent scan events feed (live discovery results).

Example

curl "http://localhost:8080/api/events/recent"

Authentication

API authentication is optional and controlled by the -api-pass flag on the datastore binary.

When authentication is enabled, include the X-API-Key header with every request:

Authenticated Request

curl -H "X-API-Key: YOUR_SECRET" "http://localhost:8080/api/hosts"

MeowQL Query Language

MeowQL is a query language inspired by Censys, Shodan, and FOFA. It compiles to optimized SQL queries with parameterized values.

Operators

Syntax	Description	SQL Equivalent
field:value	Contains (case-insensitive)	LIKE '%value%'
field="exact"	Exact match	= 'exact'
field!=value	Not equal	!= 'value'
field=~pattern	Regex match	GLOB
field=wild	Wildcard match	GLOB
field>10	Greater than	> 10
field<100	Less than	< 100
field>=5	Greater or equal	>= 5
field<=20	Less or equal	<= 20
field:*	Field exists	IS NOT NULL
field:{a,b,c}	Set / IN (multiple values)	IN ('a','b','c')
A and B	Logical AND (explicit)	AND
A B	Logical AND (implicit, space)	AND
A or B	Logical OR	OR
not A	Negation	NOT
-field:value	Negation prefix	NOT ... LIKE
(A or B)	Grouping	( ... )

Fields Reference

Host Fields

Field	Type	Description
ip	IP	IP address, supports CIDR notation
hostname	String	Hostname
domain	String	Associated domains
domain.source	String	Domain source (certificate, sni, reverse_dns)
country	String	ISO country code
city	String	City name
asn	Integer	AS number
org	String	AS organization
cloud	String	Cloud provider (aws, gcp, azure)
cloud.region	String	Cloud region
timezone	String	Timezone

Service Fields

Field	Type	Description
port	Integer	Port number
service	String	Service name (http, ssh, ftp...)
product	String	Product name (nginx, OpenSSH...)
version	String	Version string
banner	String	Service banner
enrichment	String	Enrichment status

HTTP Fields

Field	Type	Description
http.title	String	Page title
http.server	String	Server header
http.status	Integer	HTTP status code
http.body	String	Response body preview
http.webserver	String	Webserver software
http.ssl	Boolean	Uses SSL/TLS
http.body_hash	String	SHA256 body hash
http.favicon	String	Favicon MD5 hash
tech	String	Detected technologies
framework	String	Detected framework

TLS Fields

Field	Type	Description
tls.cert.cn	String	Subject Common Name
tls.cert.issuer	String	Issuer Common Name
tls.cert.names	String	Subject Alternative Names (SANs)
tls.cert.issuer_org	String	Issuer organization
tls.cert.not_before	Integer	Not before timestamp
tls.cert.expired	Integer	Not after timestamp
tls.cert.is_ca	Boolean	Is CA certificate
tls.cert.sig_algo	String	Signature algorithm
tls.cert.serial	String	Serial number (hex)
tls.jarm	String	JARM TLS fingerprint
tls.self_signed	Boolean	Self-signed certificate

Dynamic JSON Fields

Prefix	Source	Example
enrichment.*	services.enrichment_data	enrichment.anonymous_login:true
fingerprint.*	services.fingerprint_data	fingerprint.jarm:"2ad..."
http.headers.*	http_data.headers	http.headers.X-Powered-By:"PHP"
http.tech.*	http_data.technologies	http.tech.name:"jQuery"

Examples

port:443 country:FR

HTTPS servers in France

http.title:"login" and not cloud:aws

ip:192.168.1.0/24 and service:ssh

SSH in a subnet

(port:8443 or port:443) and tls.cert.cn:"*.com"

Web servers with *.com cert

port:{22,80,443} and org:"Google"

Common ports at Google

enrichment.anonymous_login:true and service:ftp

FTP with anonymous login

http.headers.Vary:RSC

React Server Components

-cloud:* and country:FR

Non-cloud hosts in France

Quick Start

The datastore must start first as it embeds the NATS server if not messages will be lost. For local usage:

$ ./datastore 
$ ./grab local
$ ./synscan -d # to get scan capabilities from datastore

For multi module usage:

$ ./datastore -nats-host 192.168.0.12 -nats-token natssecret
$ ./grab enrich --nats-token natssecret --nats-url nats://192.168.0.12:4222
$ ./grab finger --nats-token natssecret --nats-url nats://192.168.0.12:4222
$ ./synscan -d --nats-token natssecret --nats-url nats://192.168.0.12:4222 # daemon mode
$ ./synscan --nats-token natssecret --nats-url nats://192.168.0.12:4222 -t 192.168.0.0/24 -P 50 # direct scan mode

Pipeline Overview

The three modules communicate via NATS topics in a processing pipeline:

SynScan ──scan.port.open──> Grabber (finger) ──scan.port.fingerprinted──> Grabber (enrich) ──scan.port.enriched──> Datastore

Topic	Producer	Consumer	Queue Group
scan.port.open	SynScan	Grabber (finger), Datastore	fingerprint-workers, datastore-workers
scan.port.fingerprinted	Grabber (finger)	Grabber (enrich), Datastore	enrichment-workers, datastore-workers
scan.port.enriched	Grabber (enrich)	Datastore	datastore-workers

Enrichment Modules

The grabber includes 60 enrichment modules that extract protocol-specific data from discovered services. Each module connects to the target, speaks the native protocol, and returns structured JSON data stored in enrichment_data. Query enrichment results via MeowQL: enrichment.field:value.

Web & HTTP

Module	Aliases	Description
http	https, http-proxy, https-proxy	HTTP headers, title, status, body hash, favicon, technologies (Wappalyzer), framework, CMS, redirects, SSL info
ipp	ipps	Internet Printing Protocol: printer name, state, model, firmware, URIs, jobs
icecast	-	Icecast streaming server: version, station info, stream metadata
couchdb	-	CouchDB: version, server info, database list, cluster config
elasticsearch	-	Elasticsearch: version, cluster name/status, node count, indices
influxdb	-	InfluxDB: version, build info, database list

Module	Aliases	Description
smtp	smtps, submission	SMTP banner, EHLO capabilities, STARTTLS, auth methods, relay testing
pop3	pop-3	POP3 banner, capabilities, STLS support
pop3s	pop3-ssl	POP3 over TLS: same as pop3 with native TLS
imap	-	IMAP banner, capabilities, STARTTLS, auth mechanisms
imaps	imap-ssl	IMAP over TLS: same as imap with native TLS

Databases

Module	Aliases	Description
mysql	mariadb	MySQL/MariaDB: version, server capabilities, auth plugin, charset, connection ID
postgres	postgresql	PostgreSQL: version, server parameters, auth methods, SSL state
mongodb	mongod	MongoDB: version, server info (buildInfo), databases, replicaSet status
redis	-	Redis: version, mode, OS, memory, connected clients, auth required
oracle	oracle-tns	Oracle TNS: version, service names, listener status
mssql	ms-sql-s	Microsoft SQL Server: version, instance name, named pipes, TCP port
cassandra	-	Cassandra: version, cluster name, datacenter, CQL version, partitioner
memcached	-	Memcached: version, uptime, current connections, items, memory stats

Directory & Discovery

Module	Aliases	Description
ldap	-	LDAP: root DSE, naming contexts, supported controls, server info
ldaps	ldap-ssl	LDAP over TLS: same as ldap with native TLS
dns	domain	DNS: version.bind, recursion available, DNSSEC support, zone transfer test
netbios	netbios-ns, netbios-ssn	NetBIOS: computer name, domain, MAC address, group names
x11	-	X11: version, vendor, auth required, screens info

Remote Access

Module	Aliases	Description
ssh	-	SSH: version, key exchange algorithms, host key types, ciphers, MACs, compressions
telnet	-	Telnet: banner, negotiated options, terminal type
vnc	-	VNC: version, security types, auth required, desktop name
rdp	ms-wbt-server	RDP: version, NLA required, TLS support, certificate info

File Transfer

Module	Aliases	Description
ftp	ftps	FTP: banner, FEAT capabilities, anonymous login, STARTTLS, system type
rsync	-	Rsync: version, module list with descriptions
tftp	-	TFTP: accessibility check, error responses
nfs	nfsd	NFS: version, exported shares, access permissions
git	-	Git: version, protocol capabilities
afp	-	Apple Filing Protocol: server name, machine type, AFP versions, UAMs, flags

Messaging

Module	Aliases	Description
mqtt	-	MQTT: version, broker info, anonymous access, CONNACK response
amqp	-	AMQP: version, product, platform, capabilities, mechanisms
xmpp	jabber	XMPP: server features, mechanisms, TLS support, stream info
irc	ircd	IRC: server name, version, network, user count, MOTD, supported features
mumble	-	Mumble: version, users online, max users, bandwidth, welcome text
teamspeak	ts3	TeamSpeak 3: version, platform, clients online, channels, server name
sip	-	SIP: server/user-agent, supported methods, allow headers

Network & Infrastructure

Module	Aliases	Description
smb	microsoft-ds	SMB: version, OS, computer name, domain, signing required, shares list
snmp	-	SNMP: sysDescr, sysName, sysLocation, sysContact, uptime
ntp	-	NTP: version, stratum, reference ID, monlist support
modbus	-	Modbus: device identification, vendor, product code, model
coap	-	CoAP: resources (/.well-known/core), supported content formats
openvpn	-	OpenVPN: protocol detection, key exchange response
pptp	-	PPTP: vendor, hostname, firmware version, framing/bearer capabilities
upnp	ssdp	UPnP/SSDP: device description, services, manufacturer, model

Other Protocols

Module	Aliases	Description
rpc	rpcbind, portmapper	RPC portmapper: registered programs, versions, protocols, ports
rtsp	-	RTSP: server, supported methods, content-base
minecraft	-	Minecraft: version, protocol, description (MOTD), player count, max players
ajp13	-	AJP (Apache JServ): CPing/CPong detection, backend server info
lpd	printer	LPD (Line Printer Daemon): queue list, printer status
mpd	-	Music Player Daemon: version, status, stats, current playlist
nntp	-	NNTP (Usenet): banner, capabilities, posting allowed, groups count
syslog	-	Syslog: protocol detection, message format
ldp	-	Label Distribution Protocol: version, keepalive, label space, capabilities
banner	-	Generic banner grabber: raw TCP banner for unrecognized services
ntlm_parser	-	NTLM challenge parser: OS version, hostname, domain, DNS info from NTLMSSP

Query enrichment data in MeowQL using the enrichment.* prefix:

enrichment.anonymous_login:true and service:ftp

FTP servers with anonymous access

enrichment.auth_required:false and service:redis

Redis without authentication

enrichment.version:"8.0" and service:mysql

MySQL 8.0 instances

enrichment.signing_required:false and service:smb

SMB without signing

Configuration

All three modules support CLI flags and optional YAML config files. CLI flags always take priority. Config files are optional when NATS is running on localhost or --nats-url is provided.

Grabber

CLI flags config.yaml

All settings can be provided via CLI flags, a YAML config file, or both. CLI flags always take priority. Without -c or --nats-url, the grabber tries config.yaml in the current directory, then falls back to defaults with nats://localhost:4222.

CLI Flags — finger

Flag	Default	Description
-c, --config	config.yaml	Path to YAML config file (optional)
-w, --workers	500	Override worker count
--nats-url	nats://localhost:4222	NATS server URL
--nats-token	-	NATS auth token
--probe-timeout	9000	Per-probe timeout in ms
--global-timeout	30000	Global timeout per port in ms

CLI Flags — enrich

Flag	Default	Description
-c, --config	config.yaml	Path to YAML config file (optional)
-w, --workers	500	Override worker count
--nats-url	nats://localhost:4222	NATS server URL
--nats-token	-	NATS auth token
--enrich-timeout	10000	Per-module scan timeout in ms
--global-timeout	30000	Hard deadline per job in ms

CLI Flags — local

Flag	Default	Description
-c, --config	config.yaml	Path to YAML config file (optional)
-w, --workers	500	Override worker count
--nats-url	nats://localhost:4222	NATS server URL
--nats-token	-	NATS auth token
--probe-timeout	9000	Per-probe timeout in ms
--enrich-timeout	10000	Per-module scan timeout in ms
--global-timeout	30000	Global timeout in ms

config.yaml — NATS Connection

Key	Type	Default	Description
nats.url	string	nats://localhost:4222	NATS server URL
nats.auth.token	string	""	Authentication token (leave empty if no auth)

config.yaml — Fingerprint

Key	Type	Default	Description
fingerprint.workers	int	500	Number of concurrent fingerprint workers
fingerprint.probe_timeout_ms	int	9000	Timeout per individual nmap probe (ms)
fingerprint.global_timeout_ms	int	30000	Total timeout for all probes on a single port (ms)

config.yaml — Enrichment

Key	Type	Default	Description
enrichment.workers	int	500	Number of concurrent enrichment workers
enrichment.enrich_timeout_ms	int	10000	Per-module scan timeout (ms), overrides module defaults
enrichment.global_timeout_ms	int	30000	Hard deadline per enrichment job (ms)

config.yaml — Logging

Key	Type	Default	Description
logging.level	string	info	Log level: debug, info, warn, error
logging.format	string	console	Output format: console (human-readable) or json

Example config.yaml

nats:
  url: "nats://localhost:4222"
  auth:
    token: "SECRET"

fingerprint:
  workers: 500
  probe_timeout_ms: 9000
  global_timeout_ms: 30000

enrichment:
  workers: 500
  enrich_timeout_ms: 10000
  global_timeout_ms: 30000

logging:
  level: "info"
  format: "console"

CLI-only examples (no config.yaml needed)

# Fingerprint with all defaults (NATS on localhost)
./grab finger

# Fingerprint with explicit NATS + token
./grab finger --nats-url nats://10.0.0.1:4222 --nats-token SECRET

# Enrichment with custom timeouts
./grab enrich --nats-url nats://10.0.0.1:4222 --enrich-timeout 15000 --global-timeout 60000

# Local mode (finger + enrich) with workers override
./grab local --nats-url nats://10.0.0.1:4222 --nats-token SECRET -w 100

# Mix: config file + CLI overrides
./grab finger -c config.yaml --nats-token NEW_TOKEN --probe-timeout 5000

SynScan

CLI flags config.yaml

TCP SYN scanner. Config file is optional — if present it provides defaults that CLI flags override. Requires root or CAP_NET_RAW on Linux.

CLI Flags

Flag	Default	Description
-t, --target	-	Target CIDR or IP range (required in scan mode)
-p, --ports	80,443,22,8080,8443	Ports to scan
-P, --top-ports	-	Scan the N most common ports (mutually exclusive with -p)
-i, --interface	auto	Network interface
-r, --rate-limit	1000	Packets per second
-T, --timeout	5000	Timeout in ms
-c, --config	config.yaml	YAML config file (optional)
--nats-url	nats://localhost:4222	NATS server URL
--nats-token	-	NATS auth token
--resume	-	Resume scan from token (hex 24 chars)
-d, --daemon	false	Daemon mode: wait for scan requests via NATS
-v, --verbose	false	Verbose output

config.yaml — Target

Key	Type	Default	Description
synscan.target.cidr	string	-	Target CIDR or IP range
synscan.target.ports	string	80,443,22,8080,8443	Ports to scan
synscan.target.top_ports	int	0	Scan the N most common ports (overrides ports if set)

config.yaml — Network & Performance

Key	Type	Default	Description
synscan.network.interface	string	auto	Network interface name
synscan.performance.rate_limit	int	1000	Packets per second
synscan.performance.timeout_ms	int	5000	Timeout in ms

config.yaml — NATS & Logging

Key	Type	Default	Description
nats.url	string	nats://localhost:4222	NATS server URL
nats.auth.token	string	""	NATS auth token
logging.level	string	info	Log level: debug, info, warn, error
logging.format	string	console	Output format: console or json

Example config.yaml

nats:
  url: "nats://localhost:4222"
  auth:
    token: "SECRET"

synscan:
  target:
    cidr: "192.168.1.0/24"
    ports: "22,80,443,8080,8443"
  network:
    interface: ""
  performance:
    rate_limit: 5000
    timeout_ms: 5000

logging:
  level: "info"
  format: "console"

CLI examples

# Basic scan
sudo ./synscan -t 192.168.1.0/24 -p 80,443

# Top 100 ports at high rate
sudo ./synscan -t 10.0.0.0/16 --top-ports 100 -r 10000

# With NATS auth
sudo ./synscan -t 192.168.1.0/24 -p 1-1000 --nats-token SECRET

# Daemon mode (waits for NATS scan requests)
sudo ./synscan --daemon --nats-url nats://10.0.0.1:4222 --nats-token SECRET

# Resume interrupted scan
sudo ./synscan -t 10.0.0.0/8 -p 80,443 --resume a1b2c3d4e5f6...

Datastore

CLI flags ENV vars

The datastore is configured via CLI flags. Several flags can also be set via environment variables.

NATS Server

Flag	Env Var	Default	Description
-nats-url	-	-	External NATS URL. If empty, starts embedded NATS server
-nats-host	-	0.0.0.0	Embedded NATS listen address
-nats-port	-	4222	Embedded NATS port
-nats-token	DATASTORE_NATS_TOKEN	-	NATS auth token
-nats-user	DATASTORE_NATS_USER	-	NATS username
-nats-pass	DATASTORE_NATS_PASSWORD	-	NATS password
-queue-group	-	datastore-workers	NATS consumer queue group name

Database

Flag	Env Var	Default	Description
-db-path	-	./scanner.db	SQLite database file path

API & Web UI

Flag	Env Var	Default	Description
-no-api	-	false	Disable REST API and Web UI entirely
-api-port	-	18080	API and Web UI listen port
-api-bind	-	127.0.0.1	API and Web UI bind address
-api-pass	DATASTORE_API_PASSWORD	-	API password (sent via X-API-Key header)

General

Flag	Env Var	Default	Description
-verbose	-	false	Enable debug logging

Examples

# Minimal (embedded NATS, no auth, API on :8080)
./datastore -verbose

# Production (embedded NATS + auth + API password)
./datastore -nats-token="SECRET" -api-pass="APIKEY"

# External NATS with user/password
./datastore -nats-url="nats://remote:4222" -nats-user="admin" -nats-pass="secret"

# Using environment variables
export DATASTORE_NATS_TOKEN="SECRET"
export DATASTORE_API_PASSWORD="APIKEY"
./datastore -verbose

Model Context Protocol (MCP)

The datastore exposes an MCP server over HTTP at /mcp, allowing LLMs (Claude, GPT, etc.) to query the scan database directly through 12 structured tools. The MCP endpoint is always available when the API is running.

Getting Started

Start the datastore normally — the MCP endpoint is served at http://<host>:<port>/mcp alongside the REST API:

./datastore -verbose

The MCP server uses the Streamable HTTP transport. All MCP clients that support HTTP can connect directly.

IDE Configuration

To integrate the datastore as an MCP server in Opencode, Claude Code, Cursor, VS Code or any compatible MCP client, create a .mcp.json file at the project root:

{
  "mcpServers": {
    "meow-datastore": {
      "type": "url",
      "url": "http://127.0.0.1:18080/mcp"
    }
  }
}

Available Tools

12 tools are exposed via MCP. Each tool is called by the LLM with JSON parameters and returns structured results. Most tools accept an optional fields parameter (comma-separated) to control which columns appear in results, reducing token usage.

meow_stats

High-level statistical overview of the dataset: total host/service/certificate counts, enrichment breakdown, top services, countries, cloud providers, products, and web technologies.

Parameter	Type	Required	Description
fields	string	no	Stat sections to include (comma-separated). Default: total_hosts,total_services,total_certificates,enrichment,top_services,top_countries. Additional: cloud_providers, top_products, top_technologies

meow_search

Search the database using MeowQL. Supports two modes: hosts (default) returns unique hosts, services returns individual IP:port entries.

Parameter	Type	Required	Description
query	string	yes	MeowQL query (e.g. port:443 and country:FR)
mode	string	no	hosts (default) or services
limit	number	no	Results per page (default: 50, max: 500)
page	number	no	Page number (default: 1)
fields	string	no	Fields to include (services mode only, comma-separated). Default: ip,port,service,product,version,country,cloud,org,enrichment_keys. Use enrichment.* fields to get enrichment values

meow_count

Lightweight count-only query. Returns the number of matching hosts or services without any row data. Much more token-efficient than meow_search when you only need a count.

Parameter	Type	Required	Description
query	string	yes	MeowQL query (e.g. port:443 and country:FR)
mode	string	no	hosts (default) or services

meow_host

Complete host profile by IP address: geolocation, network identity (ASN, org), cloud metadata, all services with fingerprint and enrichment data, TLS certificates, and associated domains.

Parameter	Type	Required	Description
ip	string	yes	IPv4 or IPv6 address (e.g. 10.0.0.1)
sections	string	no	Sections to include (comma-separated): services, certificates, domains. Default: all three
fields	string	no	Fields per service/certificate row (comma-separated). Service defaults: port,service,product,version,enrichment.*. Certificate defaults: port,fingerprint,subject_cn,issuer_cn,self_signed,expired

meow_pivot

Infrastructure correlation: find all hosts sharing a common indicator (banner, JARM, certificate, product, ASN).

Parameter	Type	Required	Description
by	string	yes	Pivot type: banner_hash, jarm, cert, product, asn
value	string	yes	Indicator value (SHA256, JARM, product name, AS number...)
limit	number	no	Max results (default: 100, max: 1000)
fields	string	no	Fields per row (comma-separated). Default: ip,port,service,product,country_code. Additional: version, cloud_provider, as_org

meow_certs

TLS certificate search and audit. Full-text search across CN, issuer, SAN, org, fingerprint. Pre-built filters for security auditing.

Parameter	Type	Required	Description
query	string	no	Text search (e.g. example.com, Let's Encrypt)
filter	string	no	all (default), expired, self_signed, expiring_soon, weak_key
limit	number	no	Max results (default: 50, max: 500)
fields	string	no	Fields per certificate (comma-separated). Default: fingerprint,subject_cn,issuer_cn,status,self_signed,host_count,not_after. Additional: subject_org, issuer_org, names, algorithm, bits, signature_algorithm, serial, is_ca, not_before

meow_domains

Domain intelligence from discovered domains (HTTP Host headers, TLS certificates, reverse DNS). Two modes: list with aggregated stats, or detail mode with all services for a specific domain.

Parameter	Type	Required	Description
domain	string	no	Specific domain for detail mode (e.g. example.com)
query	string	no	Substring filter in list mode (e.g. corp)
protocol	string	no	Protocol filter in list mode (http, https, ssh...)
limit	number	no	Max results (default: 50, max: 500)
fields	string	no	Fields per row (comma-separated). List default: domain,services_count,protocols. Detail default: ip,port,protocol,status_code,title,country. Additional: version, banner, server, redirect_url, org, cloud

meow_export

Export scan results in structured formats for downstream tools. Supports MeowQL filtering.

Parameter	Type	Required	Description
query	string	no	MeowQL filter (e.g. service:http and country:FR)
type	string	no	ip_list (default), services, hosts
limit	number	no	Max entries (default: 1000, max: 10000)

meow_dns

DNS resolution (A, AAAA, CNAME, MX, NS, TXT) or reverse lookup (PTR). Automatically cross-references resolved IPs with the scan database.

Parameter	Type	Required	Description
query	string	yes	Domain (e.g. example.com) or IP for reverse lookup (e.g. 8.8.8.8)

meow_status

Operational status: table row counts, enrichment pipeline progress, per-service breakdown.

Parameter	Type	Required	Description
No parameters

meow_scan

Submit a SYN scan request to connected synscan instances via NATS. Requires at least one active scanner (use meow_scanners to check). Results appear in the datastore as the scan progresses.

Parameter	Type	Required	Description
target	string	yes	Target specification: CIDR (192.168.1.0/24), range (10.0.0.1-10.0.0.254), or nmap-style. Multiple targets comma-separated
ports	string	no	Port specification: single (80), range (1-1024), or comma-separated (22,80,443). Default: top 1000 ports
rate	number	no	Packets per second rate limit (default: 10000)

meow_scanners

List all active synscan instances connected to the NATS bus. Shows each scanner's node ID, hostname, status (idle/scanning), current scan progress, and transport type. Use this to check scanner availability before submitting a scan.

Parameter	Type	Required	Description
No parameters

Recommended Workflow

Typical tool usage order for an LLM:

 1. meow_stats       → understand the dataset scope
 2. meow_count       → quick counts without fetching rows
 3. meow_search      → find targets with MeowQL queries
 4. meow_host        → full details on a specific IP
 5. meow_pivot       → correlate infrastructure (banner, JARM, cert, product, ASN)
 6. meow_certs       → audit TLS certificates
 7. meow_domains     → domain intelligence (virtual hosting, CDN backends)
 8. meow_export      → extract IP lists or JSON for nmap, nuclei, httpx
 9. meow_dns         → resolve domains and cross-reference with scans
10. meow_status      → check enrichment pipeline progress
11. meow_scanners    → check available scanner instances
12. meow_scan        → submit a new SYN scan via NATS

curl

Select an endpoint to generate command

Select an endpoint and send a request

Response data will appear here