search
Query urlDNA threat intelligence scans using custom search syntax to filter by domain, IP, URL, device, country, technology, and security status for security analysis.
Instructions
Search scans using urlDNA custom search syntax.
Searchable fields include: domain, ip, submitted_url, target_url, device, country_code, title, technology, favicon, malicious, and many more.
Operators supported: =, !=, LIKE, !LIKE, >, >=, <, <=
Examples: - domain = www.google.com AND title LIKE search - device = MOBILE AND country_code = IT - malicious = false AND technology LIKE wordpress
Args: query (str): Query in urlDNA CQL syntax. Returns: dict: List of scan. Raises: RuntimeError: If ssearch fails.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Implementation Reference
- urldna_mcp/tools/search.py:7-53 (handler)The full implementation of the 'search' tool handler, registered via @mcp.tool() within the register_search function. It handles the query by calling the urlDNA API search endpoint.
def register_search(mcp): @mcp.tool() def search(query: str): """ Search scans using urlDNA custom search syntax. Searchable fields include: domain, ip, submitted_url, target_url, device, country_code, title, technology, favicon, malicious, and many more. Operators supported: =, !=, LIKE, !LIKE, >, >=, <, <= Examples: - domain = www.google.com AND title LIKE search - device = MOBILE AND country_code = IT - malicious = false AND technology LIKE wordpress Args: query (str): Query in urlDNA CQL syntax. Returns: dict: List of scan. Raises: RuntimeError: If ssearch fails. """ # Get urlDNA API key try: urlDNA_api_key = get_api_key() except Exception as e: raise RuntimeError(f"[new_scan] Failed to retrieve API key: {e}") headers = { "Authorization": urlDNA_api_key, "Content-Type": "application/json", "User-Agent": "urlDNA-MCP" } # Perform the search request res = requests.post( f"{config.urlDNA_API_URL}/search", json={"query": query}, headers=headers ) if not res.ok: raise RuntimeError(f"Search failed: {res.status_code} - {res.text}") return res.json() - urldna_mcp/server.py:17-20 (registration)Registration of the search tool (via register_search(mcp)) along with other tools in the FastMCP SSE server.
register_new_scan(mcp) register_get_scan(mcp) register_search(mcp) register_fast_check(mcp) - urldna_mcp/run.py:17-20 (registration)Registration of the search tool (via register_search(mcp)) along with other tools in the FastMCP stdio server.
register_new_scan(mcp) register_get_scan(mcp) register_search(mcp) register_fast_check(mcp) - urldna_mcp/tools/search.py:11-29 (schema)Docstring providing input schema (query: str in CQL syntax), output (dict of scans), examples, and fields for the search tool.
""" Search scans using urlDNA custom search syntax. Searchable fields include: domain, ip, submitted_url, target_url, device, country_code, title, technology, favicon, malicious, and many more. Operators supported: =, !=, LIKE, !LIKE, >, >=, <, <= Examples: - domain = www.google.com AND title LIKE search - device = MOBILE AND country_code = IT - malicious = false AND technology LIKE wordpress Args: query (str): Query in urlDNA CQL syntax. Returns: dict: List of scan. Raises: RuntimeError: If ssearch fails. """