ua-spectral/botlensИсследовательский артефакт и MCP-сервер, который проводит аудит проблем безопасности и конфиденциальности в сторонних Discord-ботах посредством крупномасштабного анализа отзывов, разметки с помощью LLM и таксономии из 31 темы.
Статья: 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, который анализирует проблемы безопасности и конфиденциальности (S&P) в сторонних ботах сообществ Discord посредством крупномасштабного анализа отзывов и аудита метаданных. Конвейер обрабатывает 183 142 пользовательских отзыва о 23 102 ботах, собранных с Top.gg, выделяет 8 832 отзыва как относящихся к S&P — наблюдаемая производительность конвейера составляет 4,82% — и сопоставляет их с таксономией S&P из 31 темы.
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 — это рис. 2, и так далее). Скрипты создают
ровно те рисунки, что и в статье: рис. 2–14, 17 и 18. Рис. 1 — это схема
конвейера, а рис. 15–16 — скриншоты интерфейса отчёта BotLens.
Артефакт опубликован по адресу https://github.com/ua-spectral/BotLens. Каждый релиз на GitHub постоянно архивируется на Zenodo с присвоением DOI; DOI указан в приложении об артефакте к статье и на странице релиза репозитория.
Данные поставляются в репозитории в виде botlens-ndss-data.zip (41 МБ; один файл
распаковывается до 515 МБ, что превышает лимит GitHub на файл). Распакуйте его один раз в
корневом каталоге репозитория:
python -m zipfile -e botlens-ndss-data.zip .
Это создаёт data/ рядом с config/; больше ничего скачивать не нужно. Структура такова:
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)
Проверьте целостность с помощью sha256sum -c SHA256SUMS.txt изнутри data/.
data/README.md описывает каждый файл.
| Этап | Скрипт | Описание | Ключевой результат |
|---|---|---|---|
| 0 | stage0_preprocess.py | Объединение отзывов + метаданных, определение языка, Argos Translate | data/raw/reviews.csv |
| 1 | stage1_llm_labeling.py | Бинарная классификация S&P с помощью Ollama/Llama 3 8B | 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 (F1 = 0.938 при 30% разметки) | 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, включая тренд OLS на рис. 2 (R² = 0.35) | figures/fig02_* … fig09_* |
unassigned.Таксономия S&P из 31 темы (таблица V в статье) включает 20 тем, унаследованных от
Akgul et al. (USENIX Security 2024), и 11 тем, разработанных индуктивно в этом
исследовании — 2 дополнительные темы по безопасности и защищённости и 9 тем, специфичных для Discord.
config/taxonomy.py является единственным источником истины; stage8_visualizations.py
выводит свои группировки из него.