urlDNA

официальный

Динамическое сканирование и анализ потенциально вредоносных URL-адресов с помощью urlDNA.io

GitHub

Что можно делать с urlDNA MCP?

Мгновенная проверка безопасности URL — Запросите быструю проверку, является ли URL БЕЗОПАСНЫМ, ВРЕДОНОСНЫМ или НЕ ОЦЕНЕННЫМ, с помощью fast_check.
Полное сканирование URL — Отправьте URL на комплексное сканирование с помощью new_scan и получите результаты по ID через get_scan.
Поиск угроз на основе CQL — Ищите сканирования по доменам, IP-адресам, технологиям и вредоносным флагам с помощью search с выражениями И/ИЛИ.
Управление сохраненными запросами — Создавайте, просматривайте, обновляйте и удаляйте повторно используемые CQL-фильтры с помощью create_query, list_queries, update_query и delete_query.
Мониторинг брендов — Просматривайте бренды, получайте детали и извлекайте связанные сканирования с помощью list_brands, get_brand и brand_scans.
Просмотр документации API — Получите полную документацию OpenAPI для urlDNA напрямую с помощью search_docs.

Документация

urlDNA MCP Server

Блог

Claude Prompt

urlDNA MCP Server обеспечивает нативное использование инструментов для LLM-агентов, ориентированных на безопасность, таких как OpenAI GPT, Google Gemini и Claude Desktop, предоставляя прямой интерфейс для взаимодействия с платформой threat intelligence urlDNA через API.

Репозиторий предоставляет тот же набор инструментов через два транспорта:

stdio для локальных интеграций на рабочем столе, таких как Claude Desktop.
streamable-http для размещённых развёртываний, таких как Cloud Run.

Установка и настройка

В этом проекте используется uv для быстрого управления Python-пакетами.

Предварительные требования

Установите uv, если он ещё не установлен:

# On macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or with pip
pip install uv

Быстрый старт

Клонируйте и настройте проект:

git clone <repository-url>
cd urlDNA-mcp-server
uv sync

Запустите MCP-сервер локально (режим stdio):

uv run python urldna_mcp/run.py

Запустите MCP-сервер в режиме streamable HTTP:

uv run python urldna_mcp/server.py

Размещённый сервер считывает следующие переменные окружения:

PORT: HTTP-порт для привязки. По умолчанию — 8080.
MCP_PATH: Публичный путь конечной точки MCP. По умолчанию — /.

Разработка

# Install development dependencies
uv sync --dev

# Run tests (when available)
uv run pytest

# Format code
uv run black .

# Type checking
uv run mypy .

# Lint code
uv run flake8 .

Размещённый MCP-сервер

Сервер urlDNA MCP уже размещён и доступен по адресу:

https://mcp.urldna.io/

Этот сервер доступен через streamable HTTP, что делает его подходящим для Cloud Run и других платформ, управляемых запросами.

Вы можете использовать его напрямую с любой платформой или LLM, поддерживающей спецификацию MCP (например, Claude Desktop, OpenAI GPT, Google Gemini).

Поддерживаемые инструменты

Сканирование

Инструмент	Описание
`fast_check`	Мгновенная проверка, был ли URL просканирован. Возвращает SAFE / MALICIOUS / UNRATED.
`new_scan`	Отправка URL на полное сканирование и ожидание результата (~30–60 секунд).
`get_scan`	Получение полного результата сканирования по ID.

Поиск

Инструмент	Описание
`search`	Поиск сканирований с помощью CQL (Custom Query Language) по домену, IP, технологиям, флагу вредоносности и другим параметрам. Поддерживает выражения `AND` и `OR`, а также пагинацию (страница 2+ требует PREMIUM).

Сохранённые запросы

Инструмент	Описание
`list_queries`	Список всех сохранённых запросов для аутентифицированного пользователя.
`get_query`	Получение конкретного сохранённого запроса и его фильтров по ID.
`create_query`	Создание нового сохранённого запроса с одним или несколькими условиями фильтра CQL.
`update_query`	Обновление имени и фильтров существующего запроса (полная замена).
`delete_query`	Окончательное удаление сохранённого запроса по ID.
`query_scans`	Получение всех соответствующих сканирований для сохранённого запроса.

Мониторинг брендов

Инструмент	Описание
`list_brands`	Список доступных брендов с необязательным поиском по имени и фильтром видимости (ALL / FREE / PREMIUM / USER_BRANDS).
`get_brand`	Получение полных сведений о конкретном бренде по ID.
`brand_scans`	Получение всех сканирований, связанных с брендом. Поддерживает дополнительную фильтрацию CQL.

Справочник API

Инструмент	Описание
`search_docs`	Получение полной документации urlDNA OpenAPI.

Интеграция с Claude Desktop

Для интеграции urlDNA MCP server в Claude Desktop обновите ваш claude_desktop_config.json:

{
  "mcpServers": {
    "urlDNA": {
      "command": "uv",
      "args": [
        "--directory",
        "<YOUR_PATH>\\urldna_mcp",
        "run",
        "urldna_mcp\\run.py"
      ],
      "env": {
        "x-api-key": "<urlDNA_API_KEY>"
      }
    }
  }
}

Замените <YOUR_PATH> на родительский каталог, содержащий этот репозиторий, и <urlDNA_API_KEY> на ваш API-ключ с https://urldna.io.

Для размещённых MCP-клиентов укажите им https://mcp.urldna.io/ или ваш собственный развёрнутый MCP_PATH.

После настройки вы можете обращаться к Claude на естественном языке, например:

«Поищи в urlDNA вредоносные сканирования с заголовком, похожим на paypal»

«Создай сохранённый запрос для мобильных сканирований из Италии, помеченных как вредоносные»

«Покажи все сканирования, связанные с брендом Google»

Claude автоматически вызовет нужный инструмент и вернёт результаты с платформы urlDNA.

Использование MCP-сервера с OpenAI GPT

from openai import OpenAI

# Initialize OpenAI client (assumes OPENAI_API_KEY is set via environment variable)
client = OpenAI()

response = client.responses.create(
    model="gpt-3.5-turbo",  # Note: MCP tool use requires a Responses API-compatible model
    input=[
        {
            "role": "system",
            "content": [{"type": "input_text", "text": "You are a cybersecurity analyst using urlDNA."}]
        },
        {
            "role": "user",
          "content": [{"type": "input_text", "text": "Search in urlDNA for malicious scans with title like paypal or login"}]
        }
    ],
    text={"format": {"type": "text"}},
    reasoning={},
    tools=[
        {
            "type": "mcp",
            "server_label": "urlDNA",
            "server_url": "https://mcp.urldna.io/",
            "headers": {
                "x-api-key": "<URLDNA_API_KEY>"  # Replace with your urlDNA API key
            },
            "allowed_tools": [
                # --- Scanning ---
                "new_scan",       # Submit a URL for a full scan and wait for the result
                "get_scan",       # Retrieve a scan result by ID
                "fast_check",     # Lightweight instant safety check (SAFE / MALICIOUS / UNRATED)

                # --- Search ---
                "search",         # Search scans using CQL (Custom Query Language, AND/OR supported)

                # --- Saved Queries (PREMIUM) ---
                "list_queries",
                "get_query",
                "create_query",
                "update_query",
                "delete_query",
                "query_scans",

                # --- Brand Monitoring (PREMIUM) ---
                "list_brands",
                "get_brand",
                "brand_scans",

                # --- API Reference ---
                "search_docs",
            ],
            "require_approval": "never"
        }
    ],
    temperature=0.7,
    top_p=1,
    max_output_tokens=2048,
    store=True
)

print(response.output)

Использование MCP-сервера с Google Gemini

Gemini подключается к серверу urlDNA MCP через fastmcp, а инструменты обнаруживаются автоматически, а не передаются в виде списка allowed_tools.

import os
import asyncio
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport
from google import genai

async def main():
    # 1. Connect FastMCP client directly to streamable-http
    transport = StreamableHttpTransport(
        "https://mcp.urldna.io/",
        headers={"x-api-key": os.getenv("URLDNA_API_KEY", "YOUR_KEY")},
    )
    client_mcp = Client(transport)

    async with client_mcp:
        ai = genai.Client(vertexai=True, project=os.getenv("GOOGLE_CLOUD_PROJECT", "YOUR_PROJECT_ID"))
        response = await ai.aio.models.generate_content(
            model="gemini-2.5-flash",
            contents="Search in urlDNA for malicious scans with title like paypal",
            # Pass the live MCP session (not just tool declarations) so Gemini
            # can automatically call tools and receive their results.
            config=genai.types.GenerateContentConfig(tools=[client_mcp.session]),
        )

        print(response.text)


if __name__ == "__main__":
    asyncio.run(main())

Развёртывание в контейнере

Сборка и запуск с помощью Docker:

# Build the container
docker build -t urldna-mcp-server .

# Run the server
docker run -p 8080:8080 -e x-api-key=<URLDNA_API_KEY> urldna-mcp-server

# Optional: override the public MCP path if you do not want /
docker run -p 8080:8080 -e MCP_PATH=/custom-path -e x-api-key=<URLDNA_API_KEY> urldna-mcp-server

# Cloud Run example
gcloud run deploy urldna-mcp-server \
  --source . \
  --allow-unauthenticated \
  --set-env-vars MCP_PATH=/

Синтаксис поиска

Инструменты search и brand_scans передают предоставленный CQL напрямую в API urlDNA. Вы можете комбинировать условия с помощью AND или OR.

Примеры:

malicious = true AND technology LIKE wordpress
domain = google.com OR domain = youtube.com
(domain = paypal.com OR title LIKE paypal) AND country_code = IT

Участие в разработке

Сделайте форк репозитория
Создайте ветку для функции: git checkout -b feature-name
Установите зависимости для разработки: uv sync --dev
Внесите изменения и убедитесь, что тесты проходят
Отформатируйте код: uv run black .
Отправьте pull request

Контакты и поддержка

Для поддержки или доступа к API посетите https://urldna.io или напишите на urldna@urldna.io.