phkhanhtrinh23/agasФреймворк для атаки с использованием группового накручивания репутации на основе LLM-агентов, который манипулирует ранжированием рекомендательных систем на основе коллаборативной фильтрации типа «чёрный ящик», применяя адаптивные многоролевые стратегии и уклоняясь от обнаружения.
Это официальный код к статье: "An Efficient and Effective Agentic Group Shilling Attack on Recommender Systems". В этой статье представлен AGAS — это управляемая LLM атака накруткой против рекомендательных систем на основе коллаборативной фильтрации типа «чёрный ящик». Один Coordinator управляет пулом фальшивых пользователей-workers на протяжении последовательности раундов. В каждом раунде Coordinator выбирает одну из восьми стратегий и назначает роль каждому worker. Затем workers решают, какие элементы оценивать, используя собственный цикл рассуждений в стиле ReAct.
agent_attack_rs/ bash/ # Reviewer-friendly shell scripts (RQ1–RQ5) prompts/ # Coordinator + per-role prompt templates scripts/run_agas.py # Single entry point (--dataset --victim ...) src/agas/ roles.py # Role enum {PR, SN, CA, IN} (paper symbols) signals.py # WorkerSignals (τ, γ, φ) + EnvSignals (ρ, Δρ, η, ξ, a) strategies.py # 8-strategy enum agents/ # Coordinator + Worker policies simulation/ # Episode runner (= AGAS algorithm outer loop) llm/ # OpenAI / Ollama recsys/ # Surrogate + 11-victim backends data/ # Dataset loaders + preprocessing pipeline tests/ # Pytest suite
## 2. Краткое описание метода
AGAS создаёт четыре рабочие роли (символы в `roles.py`):
| Символ | Полное название | Что делает |
|--------|----------------|-------------------------------------------------------------------------|
| `PR` | Profiler | Безопасные оценки филлерных элементов для зондирования платформы и создания мостовых пулов. |
| `SN` | Sniper | Роль полезной нагрузки; прямая атака на цель или продвижение мостового элемента. |
| `CA` | Camouflageur | Скрытная роль; восстанавливает доверие с помощью внешне безобидной активности. |
| `IN` | Inactive | Без действий в этом раунде (охлаждение или карантин). |
В каждом раунде Координатор выбирает ровно одну из восьми стратегий из
`strategies.py` (см. `method_strategies.tex`):
1. **Victim Probe** (`S1_VICTIM_PROBE`)
2. **Bridge Building** (`S2_BRIDGE_BUILDING`, только для жертв графа)
3. **Warm-up** (`S3_WARM_UP`)
4. **First Push** (`S4_FIRST_PUSH`)
5. **Silent Slowdown** (`S5_SILENT_SLOWDOWN`)
6. **Profile Cleanup** (`S6_PROFILE_CLEANUP`)
7. **Safe Replacement** (`S7_SAFE_REPLACEMENT`)
8. **Main Attack** (`S8_MAIN_ATTACK`)
Координатор принимает эти решения на основе двух групп сигналов (`signals.py`):
* **Сигналы рабочих** `τ_{t,w}, γ_{t,w}, φ_{t,w}` — доверие, риск и
структурный валидатор. Уравнения обновления точно соответствуют
`method_coordinator.tex` (`eq:trust_update`, `eq:risk_update`, `eq:risk_decay`,
`eq:profile_validator`).
* **Сигналы среды** `ρ^{(t)}, Δρ^{(t)}, η_t, ξ_t = (q_t, s_t), a_t` —
ранг, изменение ранга, коэффициент принятия, сигнал подавления, флаг тревоги.
Оценка подозрительности `q_t` — это взвешенная с коэффициентом 0.2 сумма пяти
нормализованных членов `(d̂_t, δ̂_t, m̂_t, ŝ_t, g_t)` из `eq:round_suppression_terms` и
`eq:round_suppression_score`.
### Цикл раунда (ASCII)```
┌─────────────────────────────────────────────────┐
t=0…T-1 ──► │ 1. Observe ρ^{(t)}, update memory m_t │
│ 2. Update τ, γ, φ, η, ξ, a │
│ 3. Coordinator picks Strategy ∈ {S1…S8} │
│ and assigns Role ∈ {PR, SN, CA, IN} per worker│
│ 4. Workers act (filler / bridge / target items) │
│ 5. Validate + accept actions → ΔR̃^{(t+1)} │
│ 6. Refit / query victim → ρ^{(t+1)} │
└─────────────────────────────────────────────────┘
│
▼
t* = argmin_t ρ^{(t)}, return R* = [R ; R̃^{(≤t*)}]
Внешний цикл реализован в src/agas/simulation/episode.py и повторяет
algorithms/agas_end_to_end.tex.
| Компонент | Требование | Протестировано с |
|---|---|---|
| Python | ≥ 3.10 | 3.13.5 |
| PyTorch | ≥ 2.1 (только targets) | 2.11.0+cu128 |
| CUDA | опционально | 12.8 |
| NumPy | ≥ 1.24 | 2.4.2 |
| Pandas | ≥ 2.0 | 3.0.1 |
| SciPy | ≥ 1.10 | 1.17.0 |
| scikit-learn | ≥ 1.3 | 1.8.0 |
| openai SDK | ≥ 1.12 | 2.21.0 |
PyTorch и CUDA требуются только для victim-моделей глубокого обучения (дополнение [targets]). Основной цикл AGAS и пути на основе правил / суррогатных моделей работают на CPU без зависимости от GPU.
pip install -e .
pip install -e '.[targets]'
Обязательные переменные окружения:
| Переменная | Назначение | По умолчанию |
|--------------------|---------------------------------------------------------------|--------------------------|
| `OPENAI_API_KEY` | Ключ OpenAI Responses API для координатора / рабочих LLM. | *(не задано → fallback)* |
| `OPENAI_MODEL` | Имя модели, передаваемое в OpenAI. | `gpt-5.1` |
## 4. Наборы данных
В статье оценка проводится на шести публичных CF-бенчмарках (см. `experiment.tex`):
| Короткое имя | Источник | Пользователи | Объекты | Взаимодействия | Скачать | Поместите исходные файлы в |
|--------------|---------------------------|-------------:|--------:|-------------------:|-------------------------------------------------------------------|---------------------|
| ML-100K | MovieLens 100K | 943 | 1,682 | 100,000 | [GroupLens](https://files.grouplens.org/datasets/movielens/ml-100k.zip) | `data/ml-100k/` |
| ML-1M | MovieLens 1M | 6,040 | 3,706 | 1,000,209 | [GroupLens](https://files.grouplens.org/datasets/movielens/ml-1m.zip) | `data/ml-1m/` |
| Genome 2021 | MovieLens Tag Genome 2021 | 37,941 | 84,661 | 2,000,000 (capped) | [GroupLens](https://grouplens.org/datasets/movielens/tag-genome-2021/) | `data/genome2021/` |
| Netflix | Netflix Prize | 342,445 | 17,434 | 2,000,000 (capped) | [Kaggle](https://www.kaggle.com/datasets/netflix-inc/netflix-prize-data) | `data/netflix/` |
| Douban | Douban Movie | 28,057 | 49,176 | 8,085,679 | [HKUST](http://shichuan.org/HIN_dataset.html) | `data/douban/` |
| Amazon | Amazon Reviews 2018 | 998,653 | 30,964 | 2,000,000 (capped) | [UCSD](https://nijianmo.github.io/amazon/index.html) | `data/amazon/` |