Metadata-Version: 2.5
Name: xdr-mcp
Version: 1.3.0
Summary: MCP server for the F6 XDR platform API
Project-URL: Homepage, https://github.com/F6-Security/xdr-mcp
Project-URL: Issues, https://github.com/F6-Security/xdr-mcp/issues
Author-email: Future Joint-Stock Company <mxdr@f6.ru>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: mcp,model-context-protocol,security,xdr
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: httpx==0.28.1
Requires-Dist: mcp-types
Requires-Dist: mcp==2.1.1
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/F6-Security/xdr-mcp/HEAD/docs/logo.png" alt="F6" width="220">
</p>

# F6 XDR MCP Server

<p align="right"><a href="https://github.com/F6-Security/xdr-mcp/blob/HEAD/README.en.md">English</a></p>

[![PyPI](https://img.shields.io/pypi/v/xdr-mcp)](https://pypi.org/project/xdr-mcp/)
[![Python](https://img.shields.io/pypi/pyversions/xdr-mcp)](https://pypi.org/project/xdr-mcp/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/F6-Security/xdr-mcp/blob/HEAD/LICENSE)
[![CI](https://github.com/F6-Security/xdr-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/F6-Security/xdr-mcp/actions/workflows/ci.yml)

MCP-сервер к платформе [F6 XDR](https://f6.security). Даёт ИИ-ассистенту доступ к
алертам, инцидентам, письмам, файлам, хостам и журналу — поиском на языке запросов
платформы.

## Тулы

| Тул | Назначение |
| --- | --- |
| `xdr_search` | Поиск по секции; пустой запрос возвращает секцию целиком |
| `xdr_count` | Количество записей |
| `xdr_get_mapping` | Доступные поля поиска |
| `xdr_get_filters` | Доступные значения фильтров |
| `xdr_get_suggestions` | Реальные значения поля по префиксу |
| `xdr_list_artifacts` | Артефакты, собранные с хостов: багрепорты, логи, конфиги, дампы |
| `xdr_get_artifact_structure` | Файлы и папки внутри собранного артефакта |
| `xdr_download_artifact` | Скачать артефакт или его часть в локальную папку |
| `xdr_list_artifact_presets` | Пользовательские артефакты: сохранённые в консоли списки путей и команд |
| `xdr_collect_artifacts` | Запустить сбор артефактов с хоста |
| `xdr_abort_artifact_collection` | Остановить сбор, который ещё идёт |
| `xdr_mark_event` | Пометить объект: закрыть алерт, отметить ложное срабатывание |

Секции: `alerts`, `incidents`, `emails`, `files`, `events`, `connections`, `assets`,
`modules`, `audit`, `applications`, `application_versions`.

Первые семь тулов только читают. `xdr_download_artifact` пишет файлы на диск,
`xdr_mark_event` изменяет данные, а три тула сбора действуют на хостах; все они по
умолчанию выключены, см. раздел «Безопасность».

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

Нужен Python 3.10+ и персональный API-токен пользователя XDR.

```json
{
  "mcpServers": {
    "xdr": {
      "command": "uvx",
      "args": ["xdr-mcp"],
      "env": {
        "XDR_BASE_URL": "https://<your-xdr-host>",
        "XDR_API_KEY": "<token>"
      }
    }
  }
}
```

Этот блок подходит для Claude Desktop, Cursor и VS Code. Для Claude Code:

```sh
claude mcp add xdr \
  -e XDR_BASE_URL=https://<your-xdr-host> -e XDR_API_KEY=<token> \
  -- uvx xdr-mcp
```

Вместо `uvx` можно использовать `pip install xdr-mcp` и команду `xdr-mcp`, либо
контейнер — `docker run -i --rm -e XDR_BASE_URL -e XDR_API_KEY ghcr.io/f6-security/xdr-mcp`
(образ собран под `linux/amd64` и `linux/arm64`).

## Переменные окружения

| Переменная | Назначение |
| --- | --- |
| `XDR_BASE_URL` | Адрес вашей инсталляции XDR |
| `XDR_API_KEY` | Персональный API-токен пользователя |
| `XDR_ALLOW_WRITE` | `1` включает `xdr_mark_event`. По умолчанию выключен |
| `XDR_ALLOW_COLLECT` | `1` включает сбор артефактов с хостов: `xdr_collect_artifacts`, `xdr_abort_artifact_collection` и `xdr_list_artifact_presets`. По умолчанию выключен |
| `XDR_PASSWORD_PROMPT` | `1`: когда консоль просит второй фактор для защищённых частей сбора, сервер сам спрашивает его у вас в отдельном окне (macOS или zenity) и передаёт прямо в консоль, минуя модель. По умолчанию выключен |
| `XDR_DOWNLOAD_DIR` | Папка, куда `xdr_download_artifact` сохраняет артефакты; заданная, включает тул. В контейнере — путь внутри примонтированного тома |
| `XDR_CA_BUNDLE` | PEM-бандл для инсталляции за внутренним УЦ |

## Примеры запросов

```
alerts        severity : "critical" AND resolved : "false"
alerts        timestamp >= now-1d AND NOT false_positive : "true"
incidents     closed : "false" AND timestamp >= now-30d
emails        is_blocked : "true" AND timestamp >= now-1d
assets        edr_active : "true"
applications  vendor : "Microsoft Corporation"
audit         success : "false" AND timestamp >= now-7d
```

Условия объединяются через `AND`, `OR`, `NOT` и группируются скобками. Время —
обычно поле `timestamp`, относительное (`now-1d`, `now-6h`) или абсолютное.
Какие поля доступны в секции, покажет `xdr_get_mapping`; в `application_versions`
для дат используются `first_seen` и `last_seen`.

В строковых значениях работает `*` в любой позиции: `name : "VDI-5*"`,
`file_name : "*.exe"`. Без него значение должно совпасть точно. Если запрос ничего не
вернул, а значение могло писаться иначе, точное написание подскажет
`xdr_get_suggestions`: платформа отвечает на несовпавшее значение нулём записей, а не
ошибкой.

### Версии программного обеспечения

`applications` возвращает программное обеспечение, а `application_versions` —
записи его версий на активах. Сначала найдите нужное ПО в `applications`, затем
используйте его `uuid` в поле `software_id`:

```
application_versions  software_id : "<software_uuid>"
application_versions  software_id : "<software_uuid>" AND version : "1.2.3"
application_versions  asset : "<machine_id>" AND last_seen >= now-7d
```

`software_id` поддерживается поиском, хотя отсутствует в `xdr_get_mapping`.
Поле `asset` принимает `machine_id` или точный `current_name`, соответствующий
одному активу. Ответ включает `version`, `uuid`, `ts_created`, `ts_updated`
и сведения об активе, например `machine_id` и `computer_name`.

Для секции доступны все пять тулов, принимающих секцию. Пагинация использует `page_size`
и `offset`; сортировка — `version`, `ts_created`, `ts_updated` с необязательным
префиксом `-`. `xdr_count` считает записи версий на активах: одинаковая версия
на разных активах может встречаться несколько раз. Поле `version` имеет
`show_suggestions=false`, поэтому пустой список подсказок допустим.

## Безопасность

Всё, что возвращают читающие тулы, попадает в контекст языковой модели: адреса и
темы писем, имена файлов, хосты, журнал действий. Выдавайте серверу токен с
минимально необходимыми правами.

`xdr_mark_event` создаёт матчер — правило, которое применяется ко всем объектам,
подходящим под выражение, и этим тулом не отменяется. Поэтому тул выключен по
умолчанию; включайте `XDR_ALLOW_WRITE` осознанно и не добавляйте его в
авто-подтверждение MCP-клиента.

Собранные артефакты — одни из самых чувствительных данных платформы: дампы памяти,
учётные данные, история команд. `xdr_download_artifact` кладёт их на диск, а модели
возвращает только путь и размер — содержимое в контекст не попадает. Тул включается,
только когда задана `XDR_DOWNLOAD_DIR`; выбирайте для неё папку с ограниченным
доступом. Для списка и скачивания токену нужны права на артефакты.

`xdr_collect_artifacts` запускает на хосте сбор с правами SYSTEM или root. Сбор
нагружает хост, а пользовательские артефакты могут нести команды, которые на нём
выполнятся. Поэтому тулы сбора включаются своей переменной `XDR_ALLOW_COLLECT`, а не
`XDR_ALLOW_WRITE`. Произвольных команд тул не принимает, только пользовательские
артефакты, сохранённые человеком в консоли. За вызов — один хост, массового запуска
нет. Пути проверяются до запроса: неподходящий путь роняет весь сбор. Для путей,
пользовательских артефактов, багрепорта, дампов памяти, истории команд и ещё
нескольких частей платформа просит одноразовый код, если у пользователя токена нет
списка разрешённых IP. С `XDR_PASSWORD_PROMPT=1` сервер спрашивает его в отдельном
окне и отправляет прямо в консоль. Модель его не видит, а окно показывает, что и с
какого хоста собирается. Без этой переменной модель спросит код в чате. Остановить
можно только сбор, который ещё идёт: отмену завершённого платформа тоже принимает, и
его архив после этого не читается. Не добавляйте тулы сбора в авто-подтверждение
MCP-клиента.

Модель угроз и порядок сообщения об уязвимостях —
[SECURITY.md](https://github.com/F6-Security/xdr-mcp/blob/HEAD/SECURITY.md).

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

См. [CONTRIBUTING.md](https://github.com/F6-Security/xdr-mcp/blob/HEAD/CONTRIBUTING.md).

## Лицензия

[Apache License 2.0](https://github.com/F6-Security/xdr-mcp/blob/HEAD/LICENSE)
