ua-spectral/botlens대규모 리뷰 분석, LLM 라벨링, 31개 테마 분류 체계를 통해 타사 Discord 봇의 보안 및 개인정보 보호 문제를 감사하는 연구 아티팩트 겸 MCP 서버입니다.
논문: Kofi Ampomah and Tu Le. Measuring Users' Security and Privacy Concerns About Third-Party Community Bots on Discord. Network and Distributed System Security (NDSS) Symposium 2027. https://dx.doi.org/10.14722/ndss.2027.230535
아티팩트 검토자 안내:
ARTIFACT-EVALUATION.md부터 시작하십시오. 이 문서는 논문의 모든 주장을 이를 재현하는 정확한 명령에 매핑하고, 예상 출력과 실행 시간을 나열하며, 어떤 구성 요소가 범위 밖인지 설명합니다.
이 저장소에는 BotLens 파이프라인의 소스 코드가 포함되어 있으며, 이 파이프라인은 대규모 리뷰 분석과 메타데이터 감사를 통해 Discord의 제3자 커뮤니티 기반 봇에서 보안 및 개인정보(S&P) 관련 우려를 분석합니다. 이 파이프라인은 Top.gg에서 스크레이핑한 23,102개 봇에 걸친 183,142개의 사용자 리뷰를 처리하고, 8,832개의 리뷰를 S&P 관련 리뷰로 식별하며 — 관측된 파이프라인 산출률은 4.82% — 이를 31개 테마의 S&P 분류 체계에 매핑합니다.
BotLens/
├── README.md # This file
├── ARTIFACT-EVALUATION.md # Claim → command → expected output
├── LICENSE # See License below
├── CITATION.cff # How to cite (also used by Zenodo)
├── botlens-ndss-data.zip # The data; unpack to data/ (see Data below)
├── requirements-lock.txt # Exact versions used for the paper
├── requirements.txt # Looser version bounds
│
├── config/ # Pipeline configuration
│ ├── __init__.py
│ ├── settings.py # Paths, model params, thresholds
│ └── taxonomy.py # 31-theme S&P taxonomy (single source of truth)
│
├── scrapers/ # Data collection scripts
│ ├── topgg_metadata_scraper.py # Bot metadata scraper (Top.gg pages)
│ ├── topgg_reviews_scraper.py # Bot review scraper (Top.gg reviews)
│ └── discord_server_scanner.py # Server bot scanner — OUT OF SCOPE, see below
│
├── scripts/ # Pipeline stages + analysis
│ ├── stage0_preprocess.py # Merge, clean, detect language, translate
│ ├── stage1_llm_labeling.py # Binary S&P classification via Ollama
│ ├── stage1b_active_learning.py # Active learning loop
│ ├── stage2_prepare_data.py # Train/val/test splits with balancing
│ ├── stage3_finetune_deberta.py # Fine-tune DeBERTa-v3-large classifier
│ ├── stage4_classify_all.py # Classify all 183K reviews
│ ├── stage5_theme_assignment.py # Assign 31-theme taxonomy themes
│ ├── stage6_emotion_classification.py # GoEmotions → Ekman-style groups
│ ├── stage7_analysis.py # Sec. IV-A: SPRR, TPR, per-tag/per-bot tables
│ ├── stage8_visualizations.py # Figs. 2–9
│ ├── rq3_permissions_metadata.py # RQ3 (Sec. IV-D): statistics + Figs. 10–14, 18
│ ├── language_affective_analysis.py # Appendix B: Fig. 17
│ ├── experiment_labeling_pct.py # Labeling-budget experiment (10–45%)
│ ├── create_irr_sheets.py # Inter-rater reliability labeling sheets
│ ├── compute_kappa.py # Cohen's kappa (Sec. III-C3)
│ ├── check_langs.py # Language distribution (Table IV; needs raw crawl)
│ └── prep_30pct_for_al.py # Prepare labels for active learning
│
├── tests/
│ └── test_smoke.py # Fast integrity checks, no data required
│
└── mcp_server/ # BotLens MCP server (Sec. V)
├── server.py # The six tools of Sec. V-B2 (+ internal helpers)
├── example_client.py # MCP SDK client reproducing Use Cases 1 and 2
└── benchmark_latency.py # Sec. V-D latency session
스크립트가 작성하는 모든 그림은 논문의 그림 번호를 따라 이름이 지정됩니다
(figures/fig02_sprr_over_time.png는 Fig. 2이며, 나머지도 마찬가지입니다). 스크립트는
논문에 있는 그림과 정확히 동일한 그림을 생성합니다: Figs. 2–14, 17, 18. Fig. 1은 파이프라인
개략도이며, Figs. 15–16은 BotLens 보고서 UI의 스크린샷입니다.
아티팩트는 **https://github.com/ua-spectral/BotLens**에서 릴리스됩니다. 각 GitHub 릴리스는 DOI와 함께 Zenodo에 영구 보관되며, DOI는 논문의 아티팩트 부록과 저장소의 릴리스 페이지에 명시되어 있습니다.
데이터는 저장소에 botlens-ndss-data.zip(41 MB; 파일 하나가 압축 해제 시 515 MB로, GitHub의
파일당 제한을 초과함)으로 포함되어 배포됩니다. 저장소 루트에서 한 번 압축을 해제하십시오:
python -m zipfile -e botlens-ndss-data.zip .
이렇게 하면 config/ 옆에 data/가 생성되며, 그 외에 다운로드해야 할 것은 없습니다. 레이아웃은 다음과 같습니다:
BotLens/
└── data/
├── processed/
│ ├── all_reviews_classified.csv # 183,142 rows — required by the MCP server
│ ├── privacy_reviews_full.csv # 8,832 S&P reviews w/ themes + affect
│ ├── bot_metadata_cleaned.csv # 23,102 bots (Table I, MCP fallback)
│ ├── train.csv / val.csv / test.csv
│ └── label_map.json
├── results/ # Tables behind the paper's numbers
├── reference_figures/ # Our output of every generated figure
└── irr/ # Annotator workbooks (Sec. III-C3)
data/ 안에서 sha256sum -c SHA256SUMS.txt로 무결성을 검증하세요.
data/README.md는 모든 파일을 설명합니다.
| 단계 | 스크립트 | 설명 | 주요 출력 |
|---|---|---|---|
| 0 | stage0_preprocess.py | 리뷰 + 메타데이터 병합, 언어 감지, Argos Translate | data/raw/reviews.csv |
| 1 | stage1_llm_labeling.py | Ollama/Llama 3 8B 이진 S&P 분류 | phase1_binary_labels.csv |
| 1b | stage1b_active_learning.py | 불확실성 샘플링 + 다수결 레이블 | 개선된 훈련 세트 |
| 2 | stage2_prepare_data.py | 신뢰도 필터링, 5:1 다운샘플링, 계층적 분할 | train/val/test.csv |
| 3 | stage3_finetune_deberta.py | DeBERTa-v3-large 미세 조정 (30% 레이블링에서 F1 = 0.938) | best_model/ |
| 4 | stage4_classify_all.py | 전체 183,142개 리뷰에 대한 배치 추론 | all_reviews_classified.csv |
| 5 | stage5_theme_assignment.py | Ollama가 31개 테마 분류 체계의 테마를 할당 | privacy_reviews_themed.csv |
| 6 | stage6_emotion_classification.py | GoEmotions (RoBERTa) → 8개 정서 그룹 | privacy_reviews_full.csv |
| 7 | stage7_analysis.py | SPRR, TPR, 태그별 및 봇별 SPRR, 테마별 정서 | data/results/analysis_summary.json |
| 8 | stage8_visualizations.py | 그림 2–9, Fig. 2 OLS 추세 포함 (R² = 0.35) | figures/fig02_* … fig09_* |
unassigned로 레이블된 리뷰는 제외합니다.31개 테마 S&P 분류 체계(논문 표 V)는 Akgul et al. (USENIX Security 2024)에서
계승한 20개 테마와 본 연구에서 귀납적으로 개발한 11개 테마 — 2개의 추가
보안 및 안전 테마와 9개의 Discord 특화 테마 — 로 구성됩니다.
config/taxonomy.py가 단일 진실 공급원이며, stage8_visualizations.py는
여기서 그룹화를 도출합니다.
테마 그룹 1 — 데이터 관행 (7개, 모두 계승): 데이터 수집, 데이터 공유, 데이터 삭제, 개인 식별 정보 제거, 데이터 노출, 데이터 은닉, 위치 및 추적
테마 그룹 2 — 사용자 권리 및 제어 (7개, 모두 계승): 동의, 프라이버시 제어, 익명성 / 식별, 광고, 프라이버시 정책 및 법률, 프라이버시 침해, 긍정적 프라이버시
테마 그룹 3 — 보안 및 안전 (6개 계승 + 2개 신규): 데이터 보안, 비밀번호 문제, 데이터 정확성, 안전, 데이터 판매, 감시, 피싱 및 사기 (신규), 데이터 보존 (신규)
테마 그룹 4 — Discord 특화 위험 (9개, 모두 신규): 과도한 청취, 권한 범위 불일치, 메시지 콘텐츠 접근, DM 프라이버시, 게이트웨이 인텐트 남용, 웹훅 오용, 서버 프로파일링, 음성 프라이버시, 봇 모더레이션 투명성
scrapers/topgg_metadata_scraper.py)병렬 undetected-chromedriver 인스턴스를 사용하여 90개 이상의 카테고리 태그에 걸쳐 Top.gg에서 공개 봇 메타데이터를 수집하며, 자동 재시작과 진행 상황 지속성을 지원합니다.
scrapers/topgg_reviews_scraper.py)4개의 동시 브라우저 인스턴스를 사용하는 비동기 Playwright로 Top.gg 봇 페이지에서 공개 사용자 리뷰를 스크래핑합니다. 페이지네이션, 중복 제거, 봇별 JSON 내보내기를 처리합니다. 리뷰어 표시 이름은 공개 페이지에 표시되지만 의도적으로 읽거나 보관하지 않으며, 리뷰 콘텐츠와 공개 메타데이터만 수집됩니다.
scrapers/discord_server_scanner.py) — 범위 외이 스크립트는 실제 Discord 사용자 계정으로 로그인을 자동화하여 서버의 APP 배지
멤버를 열거하고, scan_server_bots(논문 사용 사례 2)를 시연하는 데 사용되는
봇 매니페스트를 생성합니다.
아티팩트 검토자는 이 스크립트를 실행해서는 안 됩니다. 사용자 계정을 자동화하는 것은
Discord의 서비스 약관에 위배되며, 실행하려면 실제 자격 증명을 .env에 넣어야 합니다.
이는 기록의 완전성을 위해서만 포함되었습니다. 이 스크립트 없이 scan_server_bots를
실행하려면 한 줄에 하나의 봇 이름이 담긴 텍스트 파일을 전달하십시오 — ARTIFACT-EVALUATION.md를
참조하십시오.
mcp_server/server.py는 Model Context Protocol을 통해 다음 도구들을 노출하며,
모든 MCP 호환 클라이언트에서 온디맨드 S&P 의사결정 지원을 제공합니다.