phkhanhtrinh23/agasLLM 기반 에이전트 집단 어그로 공격 프레임워크로, 적응형 다중 역할 전략을 사용하여 블랙박스 협업 필터링 추천 순위를 조작하면서 탐지를 회피합니다.
이것은 논문 "추천 시스템에 대한 효율적이고 효과적인 에이전트 그룹 셸링 공격"의 공식 코드입니다. 이 논문은 AGAS를 소개하는데, 이는 블랙박스 협업 필터링 추천 시스템에 대한 LLM 기반 셸링 공격입니다. 하나의 Coordinator가 여러 라운드에 걸쳐 가짜 사용자 worker 풀을 조정합니다. 각 라운드에서 Coordinator는 여덟 가지 전략 중 하나를 선택하고 모든 worker에게 역할을 할당합니다. 그런 다음 worker는 자체적인 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 | 이번 라운드에는 아무 동작도 하지 않음 (쿨다운 또는 격리). |
각 라운드마다 Coordinator는 `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`)
Coordinator는 두 가지 신호 그룹(`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`는 `eq:round_suppression_terms`와
`eq:round_suppression_score`의 다섯 가지 정규화 항 `(d̂_t, δ̂_t, m̂_t, ŝ_t, g_t)`의
0.2 가중 합입니다.
### 라운드 루프 (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] extra)에만 필요합니다. 핵심 AGAS 루프와 규칙 기반 / 대리 모델 경로는 GPU 의존성 없이 CPU에서 실행됩니다.
pip install -e .
pip install -e '.[targets]'
필수 환경 변수:
| 변수 | 용도 | 기본값 |
|--------------------|---------------------------------------------------------------|--------------------------|
| `OPENAI_API_KEY` | Coordinator / worker LLM용 OpenAI Responses API 키. | *(미설정 → 폴백)* |
| `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/` |
원본 다운로드 파일을 `data/<dataset>/`에 넣은 후, 다음을 실행하세요:```bash
python scripts/preprocess_all.py --data-root data --output-root processed
각 데이터셋은 processed/<dataset>/ 아래의 표준 interactions.csv + items.csv 파일로 재작성됩니다. 스모크 테스트는 MovieLens와 함께 제공되는 훨씬 작은 ml-latest-small 샘플을 사용합니다.
전처리 파이프라인은 분할 파일을 저장하지 않습니다 — 전체 상호작용 로그를 내보냅니다. 분할은 런타임에 적용됩니다:
| 단계 | 사용 데이터 | 세부 사항 |
|---|---|---|
| 학습 | interactions.csv의 모든 상호작용 | 대리 모델(및 모든 대상 모델)은 전체 과거 평점 집합에 적합됩니다. |
| 공격 평가 | 세그먼트 사용자에 대한 순위 | 각 라운드 후, 대상 아이템의 평균 순위는 최소 하나의 대상 클러스터 아이템에 ≥ 4.0을 평가한 실제 선량한 사용자(최대 2,000명)에 걸쳐 측정됩니다. 홀드아웃 테스트 세트는 디스크에 기록되지 않습니다. |
| 가짜 주입 | 메모리 내에서 추가됨 | 가짜 사용자 상호작용이 추가되고 모델은 각 라운드마다 점진적으로 재적합됩니다. 이들은 표준 CSV 파일에 절대 혼합되지 않습니다. |
이는 표준 셸링 공격 평가 프로토콜을 따릅니다: 공격자는 학습 세트 사용자에 대한 피해자의 순위를 관찰하고 그에 따라 최적화하며, 블랙박스 배포 시나리오를 모방합니다.