Metadata-Version: 2.4
Name: kuma-api
Version: 3.0.1
Summary: SDK для работы с API SIEM Kuma
Author-email: Anatolii <mixtol21@gmail.com>
License: MIT License
        
        Copyright (c) 2025 Anatolii
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://support.kaspersky.com/help/KUMA/3.4/en-US/217973.htm
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.0
Dynamic: license-file

# KAPI - KUMA API Python Client

[![PyPI](https://img.shields.io/pypi/v/kuma-api?logo=pypi&logoColor=white)](https://pypi.org/project/kuma-api)
[![GitHub](https://img.shields.io/badge/GitHub-repo-181717?logo=github&logoColor=white)](https://github.com/Mixtol/kapi)


## Описание

KUMA API Python Client — это библиотека для взаимодействия с SIEM KUMA, предоставляющая удобный интерфейс как для публичного REST API, так и для приватных API-методов, используемых в веб-интерфейсе системы.

**Особенности:**
- Поддержка как стабильного публичного API (документированного), так и приватных методов;
- Minor&Major индексы версии идентичны официальным веткам методов;
- Унифицированный интерфейс для работы со всеми сущностями KUMA (алерты, события, тенанты и др.);
- Автоматическая обработка ответов (JSON, текст, бинарные данные);
- Поддержка аутентификации через Bearer Token.

## Установка

```bash
pip install kuma-api
```

## Quickstart Инициализация клиента

### Для работы с публичным REST API

```python
import kuma

# Инициализация клиента с публичным API
client = kuma.RestClient(
    url="https://kuma.example.com",
    token="YOUR_BEARER_TOKEN",
    verify='core.cert'  # Путь к SSL-сертификату (рекомендуется для продакшена)
)
code, response = client.<object>.<method>()
```

### Для работы с приватным API (только для внутреннего использования)

```python
import kuma

# Инициализация клиента с приватным API
client = kuma.PrivateClient(
    url="https://kuma.example.com",
    username="USER",
    password="PASSWORD"
)
code, response = client.<object>.<method>()
```

**Важно:** Приватный API может изменяться между версиями KUMA и поддерживает подключение только с одного разрешенного хоста.

## Примеры использования REST

### Расширенные функции

Помимо стандартных REST-методов в клиенте есть ряд более комплексых методов, которые используют дополнительную логику или сразу несколько *public* методов, например преобразование Активного листа в Словарь и наоборот.
Подробное описание и примеры функций — в [EXTENTIONS.md](EXTENTIONS.md).

### Работа с алертами

#### Поиск
```python
# Поиск алертов по фильтру
status, alerts = client.alerts.search(
    status="new",
    from="2023-01-01T00:00:00Z",
    to="2023-01-31T23:59:59Z",
    tenantID="tenant-123"
)
if status == 200:
    for alert in alerts:
        print(f"Found alert: {alert['id']}")

# Поиск с пагинацией (автоматическая загрузка всех страниц)
status, all_alerts = client.alerts.searchp(limit=500, status="assigned")
if status == 200:
    print(f"Total alerts found: {len(all_alerts)}")
```

#### Управление алертами
```python
# Назначение алерта на пользователя
assign_status, _ = client.alerts.assign(
    alerts_ids=["123e4567-e89b-12d3-a456-426614174000"],
    user_id="user-123"
)
if assign_status == 200:
    print("Alert assigned successfully")

# Закрытие алерта с указанием причины
close_status, _ = client.alerts.close(
    alert_id="123e4567-e89b-12d3-a456-426614174000",
    reason="responded"
)
if close_status == 200:
    print("Alert closed")

# Добавление комментария к алерту
comment_status, _ = client.alerts.comment(
    alert_id="123e4567-e89b-12d3-a456-426614174000",
    comment="False positive, ignoring"
)
if comment_status == 200:
    print("Comment added")
```

#### Работа с связанными событиями
```python
# Связывание события с алертом
link_status, _ = client.alerts.link_event(
    alert_id="alert-123",
    cluster_id="cluster-456",
    event_id="event-789",
    event_timestamp=1672531200,
    comment="Related event found"
)
if link_status == 200:
    print("Event linked")

# Отвязывание события от алерта
unlink_status, _ = client.alerts.unlink_event(
    alert_id="alert-123",
    event_id="event-789"
)
if unlink_status == 200:
    print("Event unlinked")

```

#### Обработка ошибок
```python
status, response = client.alerts.get("invalid-id")
if status != 200:
    print(f"Error {status}: {response}")
    # Для 404: "Alert not found"
    # Для 403: "Access denied"
```


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

Официальная документация по публичному API доступна по адресу:
https://support.kaspersky.com/help/KUMA/3.4/en-US/217973.htm

**Примечание:** Приватные API-методы не задокументированы и могут изменяться вендором без предупреждения между версиями системы.
