ua-spectral/botlensArtefato de pesquisa e servidor MCP que audita preocupações de segurança e privacidade em bots de Discord de terceiros por meio de análise de avaliações em larga escala, rotulagem por LLM e uma taxonomia de 31 temas.
Artigo: Kofi Ampomah e 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
Revisores de artefatos: comece por
ARTIFACT-EVALUATION.md. Ele mapeia cada afirmação do artigo para o comando exato que a reproduz, lista as saídas e os tempos de execução esperados, e indica quais componentes estão fora do escopo.
Este repositório contém o código-fonte do pipeline BotLens, que analisa preocupações de segurança e privacidade (S&P) em bots comunitários de terceiros no Discord por meio de análise de avaliações em larga escala e auditoria de metadados. O pipeline processa 183.142 avaliações de usuários de 23.102 bots coletados do Top.gg, identifica 8.832 avaliações como relevantes para S&P — um rendimento observado do pipeline de 4,82% — e as mapeia em uma taxonomia de S&P de 31 temas.
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
Cada figura que os scripts geram recebe o nome do número da figura do artigo
(figures/fig02_sprr_over_time.png é a Fig. 2, e assim por diante). Os scripts produzem
exatamente as figuras do artigo: Figs. 2–14, 17 e 18. A Fig. 1 é o esquema do pipeline
e as Figs. 15–16 são capturas de tela da interface do relatório do BotLens.
O artefato é disponibilizado em https://github.com/ua-spectral/BotLens. Cada release do GitHub é arquivado permanentemente no Zenodo com um DOI; o DOI é fornecido no apêndice de artefatos do artigo e na página de releases do repositório.
Os dados são distribuídos no repositório como botlens-ndss-data.zip (41 MB; um arquivo
é descompactado para 515 MB, além do limite por arquivo do GitHub). Descompacte-o uma vez, na
raiz do repositório:
python -m zipfile -e botlens-ndss-data.zip .
Isso cria data/ ao lado de config/; nada mais precisa ser baixado. A estrutura é:
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)
Verifique a integridade com sha256sum -c SHA256SUMS.txt de dentro de data/.
data/README.md descreve cada arquivo.
| Etapa | Script | Descrição | Saída Principal |
|---|---|---|---|
| 0 | stage0_preprocess.py | Mescla avaliações + metadados, detecção de idioma, Argos Translate | data/raw/reviews.csv |
| 1 | stage1_llm_labeling.py | Classificação binária S&P com Ollama/Llama 3 8B | phase1_binary_labels.csv |
| 1b | stage1b_active_learning.py | Amostragem por incerteza + rótulos por voto majoritário | Conjunto de treino aprimorado |
| 2 | stage2_prepare_data.py | Filtragem por confiança, downsampling 5:1, divisões estratificadas | train/val/test.csv |
| 3 | stage3_finetune_deberta.py | Fine-tuning do DeBERTa-v3-large (F1 = 0,938 com 30% de rotulagem) | best_model/ |
| 4 | stage4_classify_all.py | Inferência em lote sobre todas as 183.142 avaliações | all_reviews_classified.csv |
| 5 | stage5_theme_assignment.py | Ollama atribui temas da taxonomia de 31 temas | privacy_reviews_themed.csv |
| 6 | stage6_emotion_classification.py | GoEmotions (RoBERTa) → 8 grupos de afeto | privacy_reviews_full.csv |
| 7 | stage7_analysis.py | SPRR, TPR, SPRR por tag e por bot, afeto por tema | data/results/analysis_summary.json |
| 8 | stage8_visualizations.py | Figs. 2–9, incluindo a tendência OLS da Fig. 2 (R² = 0,35) | figures/fig02_* … fig09_* |
unassigned.A taxonomia de S&P de 31 temas (Tabela V do artigo) compreende 20 temas herdados de
Akgul et al. (USENIX Security 2024) e 11 temas desenvolvidos indutivamente neste
estudo — 2 temas adicionais de Segurança & Proteção e 9 temas específicos do Discord.
config/taxonomy.py é a única fonte de verdade; stage8_visualizations.py
deriva seus agrupamentos a partir dele.