graph-poisoning-cert

KO | EN

gitlite — search

#javascript #react #ai #golang #machine-learning #deep-learning #linux #nodejs #windows #awesome #awesome-list #vue #openai #open-source

graph-poisoning-cert

(★ 10)

No description available.

graph-poisoning-cert Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Graph Poisoning Certification (GPC)

Система обнаружения и сертификации отравленных данных для графовых баз данных.
Реализована как **фильтр-прокси**, разворачиваемый в виде отдельного контейнера
между клиентом и Memgraph. Все данные проходят через фильтр перед загрузкой в БД.

## Архитектура

```
                         docker-compose
            ┌────────────────────────────────────────┐
            │                                        │
 Client ──► │  Filter Service (:8000) ──► Memgraph   │
   CSV/HTTP │  FastAPI + фильтр           (:7687)    │
            │                                        │
            └────────────────────────────────────────┘
```

- **Filter Service** (`gpc-filter`) — FastAPI-сервис, принимает CSV с рёбрами,
  прогоняет их через фильтр и загружает в Memgraph только безопасные данные.
- **Memgraph** (`gpc-memgraph`) — графовая БД, доступна для загрузки только через фильтр.
- **CLI** (`app.py`) — командная строка для подготовки данных, генерации атак и прямого управления.

## Структура проекта

```
graph-poisoning-cert/
  core/                    # Переиспользуемые модули
    db.py                  #   Подключение к Memgraph, загрузка/выгрузка рёбер
    config.py              #   Пороги, веса анализаторов, описания инвариантов
    analyzers.py           #   Motif / community / degree / type / feature similarity
    filter.py              #   Скоринг и классификация по триплетам, baseline stats
    invariants.py          #   Проверки инвариантов для подозрительных триплетов
    certify.py             #   Сертификация триплетов, верификация, отчёт (proof)
    parser.py              #   Парсинг CSV / edge-list, извлечение типов узлов
  filter_service.py        # FastAPI-сервис (REST API фильтра)
  app.py                   # CLI-приложение
  Dockerfile               # Образ для filter-сервиса
  docker-compose.yml       # Memgraph + Filter Service
  requirements.txt         # Python-зависимости
  requirements-attacks.txt # Зависимости для deeprobust (опционально)
  data/
    processed/             # Подготовленные baseline-графы
    poisoned/              # Сгенерированные отравленные файлы
    cache/                 # Отчёты сертификации (certificate_report.json)
```

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

- **Docker** и **Docker Compose**
- **Python 3.10+** (для CLI-утилит, опционально)

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

### 1. Запуск инфраструктуры

Одна команда поднимает Memgraph и Filter Service:

```bash
docker-compose up --build -d
```

После запуска:
- Filter Service: `http://localhost:8000`
- Swagger UI (документация API): `http://localhost:8000/docs`
- Memgraph Bolt: `bolt://localhost:7687`

Проверка работоспособности:

```bash
curl http://localhost:8000/health
```

Ожидаемый ответ:
```json
{"status": "ok", "memgraph_connected": true, "memgraph_error": null}
```

### 2. Установка Python-зависимостей (для CLI)

```bash
pip install -r requirements.txt
```

### 3. Подготовка и загрузка baseline-графа

Baseline — это эталонный граф, относительно которого фильтр оценивает новые данные.

```bash
# Скачать и подготовить датасет Wikipedia (Chameleon)
python app.py download --dataset chameleon

# Загрузить baseline в Memgraph
python app.py load-baseline --csv data/processed/chameleon/edges.csv
```

### 4. Загрузка данных через фильтр (основной сценарий)

Теперь все загрузки проходят через фильтр-сервис:

```bash
# Безопасные данные — фильтр пропустит (HTTP 200)
curl -X POST "http://localhost:8000/upload?threshold=0.6" \
  -F "file=@data/processed/chameleon/edges.csv"

# Отравленные данные — фильтр заблокирует (HTTP 403)
curl -X POST "http://localhost:8000/upload?threshold=0.6" \
  -F "file=@data/poisoned/poisoned_demo.csv"
```

> **PowerShell**: используйте `curl.exe` вместо `curl`, иначе вызовется
> `Invoke-WebRequest`. Параметры передавайте в URL, не через `-G -d`.

### 5. Остановка

```bash
docker-compose down
```

## Тестирование (pytest)

```bash
pip install -r requirements.txt
pip install -r requirements-dev.txt
```

- **Быстрый прогон** (без Memgraph, без скачивания больших датасетов и тяжёлых бенчмарков):

```bash
  pytest tests/ -m "not infra and not dataset and not benchmark" -q
  ```

- **Полный прогон** (все тесты, включая сеть и датасеты — может занять несколько минут):

```bash
  pytest tests/ -v
  ```

- **Интеграционные тесты с Memgraph** (нужен запущенный стек, Bolt на `localhost:7687`):

```bash
  docker-compose up -d
  pytest tests/ -m infra -v
  ```

Тесты с маркером `infra` автоматически **пропускаются** (`skipped`), если Memgraph недоступен — это нормально для CI без Docker. Чтобы проверить фильтр и загрузку в БД локально, сначала выполните `docker compose up -d` (или `docker-compose up -d`).

После старта контейнеров Bolt может быть готов не сразу: фикстура `memgraph_reachable` **до 45 секунд** повторяет подключение (переменные `MEMGRAPH_WAIT_SEC`, `MEMGRAPH_RETRY_INTERVAL`). Для быстрого отказа без ожидания: `MEMGRAPH_WAIT_SEC=0 pytest ...`.

## Бенчмарк (сравнение с другими решениями)

Библиотека `benchmark/` позволяет запускать эксперименты для сравнения GPC
с решениями из `solutions/` (GNNGuard, GNNCert, graph_cert, GRB, PGNNCert,
sparse_smoothing). Подробное руководство: [Benchmark Runbook](docs/superpowers/plans/2026-03-28-benchmark-runbook.md).

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

```bash
pip install -r requirements-benchmark.txt
python -m benchmark.smoke_test                          # проверка пайплайна
python benchmark/prepare_datasets.py --name cora_ml --source deeprobust
python -m benchmark.run_benchmark --datasets cora_ml --tools gpc --attacks random_injection --budgets 1.0 --seeds 42
python -m benchmark.export_tables data/benchmark_results/results_*.json   # таблицы: utility (Gain/Rec), детекция рёбер, сертификация узлов
python -m benchmark.visualize data/benchmark_results/results_benchmark_*.json
```

Сводка метрик по блокам (utility / edge PR-AUC / node certification) описана в [Benchmark protocol](docs/benchmark_protocol.md).

## REST API фильтра

### `GET /health` — проверка работоспособности

```bash
curl http://localhost:8000/health
```

Возвращает статус сервиса и подключения к Memgraph.

### `POST /upload` — загрузка данных через фильтр

Принимает CSV с рёбрами. Если данные безопасны — загружает в Memgraph (HTTP 200).
Если обнаружена атака — блокирует и возвращает отчёт (HTTP 403).

```bash
curl -X POST "http://localhost:8000/upload?threshold=0.6" \
  -F "file=@edges.csv"
```

Пример ответа при блокировке:
```json
{
  "error": "Upload blocked — data flagged as harmful by the filter.",
  "filter_report": {
    "edges_scanned": 200,
    "threshold": 0.6,
    "avg_scores": {"sds": 0.16, "seds": 0.98, "cds": 0.78},
    "method_flags": {"sds": false, "seds": true, "cds": true},
    "harmful": true,
    "decision": "HARMFUL",
    "top_suspicious_edges": [...]
  }
}
```

Принудительная загрузка (обход фильтра):

```bash
curl -X POST "http://localhost:8000/upload?threshold=0.6&force=true" \
  -F "file=@edges.csv"
```

### `POST /scan` — сканирование без загрузки

Проверяет данные фильтром, но не загружает их в Memgraph.

```bash
curl -X POST "http://localhost:8000/scan?threshold=0.6" \
  -F "file=@edges.csv"
```

### `POST /certify` — полная сертификация

Запускает полный пайплайн: фильтр + MILP-оптимизация + SAT-верификация + генерация доказательств.

```bash
curl -X POST "http://localhost:8000/certify?threshold=0.6&milp_timeout=120" \
  -F "file=@data/poisoned/poisoned_demo.csv"
```

Возвращает Certificate Report (также сохраняется в `data/cache/certificate_report.json`).

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

Все эндпоинты (кроме `/health`) поддерживают следующие query-параметры:

| Параметр | По умолчанию | Описание |
|---|---|---|
| `threshold` | 0.6 | Порог подозрительности триплета (`threshold_suspicious`); в legacy-скане связан с SDS/SeDS/CDS |
| `node_label` | Article | Метка узлов в Memgraph |
| `edge_type` | LINKS_TO | Тип рёбер в Memgraph |
| `sample_size` | 20000 | Размер выборки для baseline статистики |
| `community_max_nodes` | 5000 | Макс. узлов для определения сообществ |
| `baseline_limit` | null | Ограничить число baseline-рёбер из Memgraph |
| `src_col` | null | Имя колонки-источника в CSV (автодетекция если не указан) |
| `dst_col` | null | Имя колонки-назначения в CSV (автодетекция если не указан) |
| `force` | false | Только `/upload`: загрузить даже при обнаружении атаки |
| `milp_timeout` | 120 | Только `/certify`: таймаут MILP-солвера (секунды) |

## CLI-утилита

CLI (`app.py`) используется для подготовки данных, генерации атак и прямого управления.

### Команды

```bash
# Скачать и подготовить датасет
python app.py download --dataset chameleon

# Импортировать локальный CSV / edge-list
python app.py prepare --input edges.csv --name my_graph

# Загрузить baseline в Memgraph
python app.py load-baseline --csv data/processed/chameleon/edges.csv

# Сгенерировать отравленные данные
python app.py generate-poisoned --csv data/processed/chameleon/edges.csv \
  --attack deeprobust_random --n 200 --name poisoned_demo

# Сканировать файл (baseline из Memgraph)
python app.py scan --file data/poisoned/poisoned_demo.csv

# Сканировать файл (baseline из CSV, без Memgraph)
python app.py scan --file data/poisoned/poisoned_demo.csv \
  --source csv --baseline-csv data/processed/chameleon/edges.csv

# Сканировать и загрузить в Memgraph
python app.py load --file data/poisoned/poisoned_demo.csv

# Полная сертификация
python app.py certify --file data/poisoned/poisoned_demo.csv \
  --source csv --baseline-csv data/processed/chameleon/edges.csv
```

### Генерация атак

Доступные типы атак для демонстрации:

| Атака | Описание |
|---|---|
| `deeprobust_random` | Атака через библиотеку DeepRobust (случайная модификация) |
| `hub_injection` | Новые узлы, связанные с хабами (наиболее связными вершинами) |
| `reciprocity_break` | Рёбра без обратных (нарушение взаимности) |
| `random_injection` | Случайное добавление рёбер между существующими узлами |

Для `deeprobust_random` требуется дополнительная установка:

```bash
pip install -r requirements-attacks.txt
```

## Как устроен фильтр

Для каждого триплета (ребра) вычисляется **TotalAnomalyScore** — взвешенная сумма
анализаторов относительно baseline: мотивы, модулярность/сообщества, степень (в т.ч. по типам узлов),
совместимость типов `(type_src, relation, type_dst)` и при наличии данных — сходство признаков концов ребра.

Параметр `threshold` в HTTP API задаёт порог подозрительности (`threshold_suspicious`):
выше порога триплет классифицируется как подозрительный и дальше обрабатывается по конфигурации
(инварианты или жёсткий отказ). Обёртки `scan_edges` / `score_edge` для совместимости
всё ещё отображают часть сигналов в поля SDS / SeDS / CDS и старое правило «2 из 3 методов».

## Механизм сертификации

Помимо сканирования, реализован полный конвейер формальной сертификации.

### MILP-оптимизация (PuLP)

Формулируется задача целочисленного линейного программирования:
- **Переменные**: `x_i in {0,1}` для каждого ребра (baseline + новые).
- **Ограничения**:
  - *Взаимность*: взаимные рёбра включаются/исключаются вместе.
  - *Композиция*: если (A->B) и (B->C) включены и (A->C) существует, оно тоже включается.
  - *Аномальность*: рёбра с AAS > 0.85 принудительно исключаются.
  - *Согласованность*: конфликтующие межобщественные рёбра не могут быть включены одновременно.
- **Цель**: максимизировать число сохранённых рёбер.

### SAT-верификация (Z3)

Результат MILP проверяется SAT-солвером:
- Те же ограничения в булевой логике.
- Если выполнимо — граф согласован.
- Если невыполнимо — извлекается минимальное ядро конфликта.

### Генерация доказательств

Для каждого ребра формируется:
- **Сертификат включения**: причина, доказательство согласованности, зависимости.
- **Доказательство исключения**: причина удаления, набор конфликтов.
- **Бюджет возмущений**: максимальное число рёбер, которые можно безопасно добавить.

Результат сохраняется в `data/cache/certificate_report.json`.

### Пример отчёта сертификации

```
============================================================
  CERTIFICATION REPORT
============================================================
  Total edges (baseline + new): 36301
  Certified edges:              36136
  Removed edges:                165
  Perturbation budget:          31353
  MILP status:                  Optimal
  SAT verification:             CONSISTENT
  Report saved to:              data/cache/certificate_report.json
============================================================
```

## Просмотр содержимого Memgraph

### Через mgconsole (встроенная консоль)

```bash
docker exec -it gpc-memgraph mgconsole
```

```cypher
MATCH (n) RETURN count(n);
MATCH ()-[r]->() RETURN count(r);
MATCH (n)-[r]->(m) RETURN n.id, type(r), m.id LIMIT 20;
```

### Через Memgraph Lab (веб-интерфейс)

Добавьте в `docker-compose.yml`:

```yaml
  lab:
    image: memgraph/lab
    container_name: gpc-lab
    ports:
      - "3000:3000"
    depends_on:
      - memgraph
    environment:
      - QUICK_CONNECT_MG_HOST=memgraph
      - QUICK_CONNECT_MG_PORT=7687
```

Затем откройте `http://localhost:3000`.

## Использование с пользовательскими датасетами

### Импорт локального файла

```bash
# CSV с автодетекцией колонок
python app.py prepare --input /path/to/my_edges.csv --name my_graph

# Явное указание колонок
python app.py prepare --input /path/to/data.csv --name my_graph \
  --src-col node_from --dst-col node_to

# Ненаправленный граф с ограничением рёбер
python app.py prepare --input /path/to/edges.txt --name my_graph \
  --undirected --limit 50000
```

### Загрузка по URL

```bash
python app.py download --url https://example.com/graph.zip --dataset my_graph
```

### Полный цикл на пользовательских данных

```bash
# 1. Подготовить данные
python app.py prepare --input my_data.csv --name my_graph \
  --src-col source --dst-col target

# 2. Загрузить baseline в Memgraph
python app.py load-baseline --csv data/processed/my_graph/edges.csv \
  --node-label Entity --edge-type RELATES_TO

# 3. Сгенерировать атаку
python app.py generate-poisoned --csv data/processed/my_graph/edges.csv \
  --attack hub_injection --n 100 --name attack_test

# 4. Проверить через фильтр-сервис
curl -X POST "http://localhost:8000/upload?threshold=0.6&node_label=Entity&edge_type=RELATES_TO" \
  -F "file=@data/poisoned/attack_test.csv"
```

### Поддержка CSV-форматов

| Колонки в файле | Поведение |
|---|---|
| `src, dst` | Используются напрямую |
| `id1, id2` | Первые две колонки = src, dst (автодетекция) |
| `from, to, type, weight` | Первые две = src, dst; остальные игнорируются |
| Любые имена | Указать `--src-col` / `--dst-col` (CLI) или `src_col` / `dst_col` (API) |

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

| Переменная | По умолчанию | Описание |
|---|---|---|
| `MG_HOST` | 127.0.0.1 | Хост Memgraph (внутри docker-compose: `memgraph`) |
| `MG_PORT` | 7687 | Порт Bolt |
| `MG_USER` | *(пусто)* | Пользователь Memgraph |
| `MG_PASSWORD` | *(пусто)* | Пароль Memgraph |

## Примечания

- Для крупных графов используйте `--baseline-limit` и `--sample-size`.
- Memgraph доступен на `bolt://localhost:7687`.
- Для сертификации через CLI не требуется запущенный Memgraph (при `--source csv`).
- Swagger UI с интерактивной документацией API: `http://localhost:8000/docs`.

graph-poisoning-cert

graph-poisoning-cert Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

graph-poisoning-cert

graph-poisoning-cert Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README