phantomstars

Détection et suivi automatisés des faux engagements sur GitHub

Un projet de JS Labs — faisant partie de l'initiative AI Slop Intelligence.
Tourne chaque jour. Attribue un score à chaque compte suspect. Détecte les campagnes de bots coordonnées.
Ouvre des issues directement sur les dépôts compromis afin que les mainteneurs puissent agir.

Soutenez ce projet

BTC   3QjWqhQbHdHgWeYHTpmorP8Pe1wgDjJy54
ETH   0x5851e6145F4773d1585b8686095FB16E368a4dA1
ZEC   t1KSR5YkNPbjqRSCoLKo5AddFWdm9Kzxh1B

Pourquoi ce projet existe

Les étoiles GitHub sont un signal de confiance. C'est ainsi que les développeurs décident quoi évaluer, de quoi dépendre et quoi recommander. Ce signal est en train d'être systématiquement corrompu.

Pendant le boom de l'IA de 2024-2026, une industrie de fermes de bots a émergé pour fabriquer de la crédibilité pour des dépôts de mauvaise qualité, souvent malveillants. Un projet avec 800 étoiles en 48 heures paraît légitime à un développeur qui parcourt les résultats de recherche. C'est tout l'intérêt. L'objectif des faux engagements n'est pas les étoiles en elles-mêmes ; c'est la preuve sociale que ces étoiles produisent, et les décisions en aval que cette preuve sociale influence.

Le schéma est identifiable. Des comptes créés la même semaine, sans bio, sans abonnés, sans dépôts d'origine, qui mettent une étoile aux mêmes 15 dépôts en l'espace de 2 heures. Pas une seule campagne, mais des dizaines qui tournent simultanément, chaque jour, à travers des milliers de comptes. Les données montrent des dépôts où 185 personnes sur 185 ayant interagi sont des bots. Un taux de fausseté de 100 %. Des places entières dans le classement construites sur du vide.

phantomstars a été créé parce que ce problème est traitable. Le rapport signal/bruit dans l'API publique de GitHub est, pour l'instant, encore suffisamment élevé pour que les campagnes coordonnées laissent des empreintes claires. Ce projet lit ces empreintes, publie les données brutes et notifie directement les mainteneurs de dépôts concernés.

Ce projet fait partie des travaux plus larges d'AI Slop Intelligence menés chez JS Labs, une recherche continue sur les mécanismes et les effets mesurables du contenu de mauvaise qualité généré par l'IA qui inonde les écosystèmes de développeurs. Les faux engagements ne sont pas un problème périphérique. C'est le mécanisme de distribution qui met le slop sous les yeux des vrais utilisateurs.

Ce qu'il fait

phantomstars exécute un job GitHub Actions quotidien qui :

1. Scrape la page GitHub Trending pour repérer les dépôts qui gagnent des étoiles aujourd'hui
2. Interroge l'API de recherche GitHub pour les dépôts créés au cours des 7 derniers jours avec une activité soudaine d'étoiles (la fenêtre plus large permet de détecter les campagnes de plusieurs jours manquées par les analyses limitées à 24 h)
3. Ajoute des dépôts candidats supplémentaires à partir des publications Reddit récentes dans r/osinttools et r/coolgithubprojects en extrayant les liens de dépôts GitHub des 2 derniers jours
4. Récupère les événements d'interaction récents (étoiles, forks) via l'API Events (dernières 24 heures par dépôt)
5. Récupère le profil complet de chaque compte ayant interagi via GraphQL : date de création du compte, nombre d'abonnés/abonnements, bio, historique des dépôts
6. Note chaque compte selon un modèle heuristique composite : ancienneté du compte, complétude du profil, schémas de dépôts et historique d'activité
7. Détecte les campagnes coordonnées à l'aide du regroupement par horodatage et de l'union-find : des grappes de comptes suspects ayant interagi dans une fenêtre de 3 heures
8. Applique la liste blanche des faux positifs avant les écritures dans le registre, les ratios par dépôt, les tableaux de bord et les notifications, afin que chaque métrique visible utilise la même population
9. Ajoute tous les suspects à un registre JSONL en ajout seul (append-only) et le commit dans ce dépôt
10. Publie un flux de renseignement par dépôt montrant quels dépôts sont ciblés, quelles sources de découverte les ont trouvés et si la fenêtre de l'API Events était complète ou plafonnée
11. Ouvre des issues GitHub directement sur les dépôts ciblés afin que les mainteneurs voient les données de la campagne dans leur propre outil de suivi d'issues
12. Écrit un rapport d'analyse formaté dans le résumé du job GitHub Actions

Pas de serveurs. Pas de bases de données. Pas de facture d'infrastructure.

Foire aux questions

Est-ce qu'il notifie le dépôt ciblé ?

Oui. Lorsque le taux de fausseté d'un dépôt dépasse 40 % ou qu'une campagne coordonnée est détectée, phantomstars ouvre une issue directement sur ce dépôt. L'issue contient le tableau complet des suspects, l'appartenance à la campagne, les scores composites et les dates de création des comptes : tout ce dont un mainteneur a besoin pour enquêter et faire un signalement à GitHub.

Si les issues sont désactivées sur un dépôt ciblé, la notification est ignorée silencieusement et consignée dans le journal d'analyse.

Puis-je demander une vérification pour un dépôt spécifique ?

Oui.

• Pour une vérification ponctuelle normale, soumettez un dépôt au format owner/repo et lancez une analyse ciblée.
• Pour une demande d'audit à vie, utilisez le mode ponctuel à vie. Il est séparé de l'analyse quotidienne.

Pourquoi cette distinction :

• Le modèle d'analyse normal est conçu pour les interactions publiques récentes et un coût d'exploitation faible.
• Un audit à vie peut impliquer des dizaines de milliers d'étoiles et des milliers de forks sur les dépôts plus importants.
• Cela est réalisable pour une investigation ponctuelle, mais c'est trop coûteux et trop lent pour le chemin quotidien par défaut.
• Les demandes à vie ne sont donc exécutées qu'en mode ponctuel explicite avec des garde-fous.

Puis-je signaler un faux positif ?

Oui. Si votre compte apparaît dans data/suspects.jsonl et que vous pensez que la classification est incorrecte, ouvrez une issue de faux positif en utilisant le modèle fourni. Les signalements sont examinés manuellement avant toute ajout à la liste blanche. La liste blanche est stockée dans data/allowlist.txt ; les comptes qui y figurent sont exclus de toutes les analyses futures et du registre des suspects.

Qu'est-ce que l'identifiant de campagne ?

Un identifiant de campagne (par ex. c-a3f9b2e1) est une empreinte hexadécimale déterministe de 8 caractères dérivée du hachage SHA-256 de l'ensemble trié des identifiants des membres de cette campagne. Le même groupe de comptes produira le même identifiant de campagne lors d'analyses indépendantes, ce qui permet un suivi longitudinal. Ce n'est ni un nom de dépôt, ni un nom d'utilisateur, ni un identifiant externe.

Stabilité : l'identifiant est stable tant que l'ensemble des membres de la campagne ne change pas. Si des bots sont ajoutés ou suspendus entre deux analyses, l'identifiant change car la composition des membres a changé. C'est attendu et reflète l'évolution réelle de la composition des fermes de bots.

Est-ce qu'il vérifie les dates de création des comptes ?

Oui. La date de création de chaque compte est récupérée depuis l'API GraphQL GitHub (champ createdAt) et stockée dans chaque enregistrement de suspect sous le nom account_created_at. C'est aussi l'entrée principale du score d'ancienneté du compte, le signal individuel le plus fort pour les faux comptes. Les comptes créés dans les 2 jours suivant leur interaction obtiennent un score de 1.0 sur la seule ancienneté.

Quel est son niveau de confiance ?

Les scores individuels comportent des taux de faux positifs significatifs. Un nouveau développeur avec un profil peu fourni obtient légitimement un score de 0.75 ou plus. L'outil en tient compte en exigeant des preuves au niveau de la campagne avant d'ouvrir des issues ; un seul compte suspect ne suffit pas. Une grappe coordonnée de plus de 40 comptes, tous créés la même semaine, tous avec un score de 0.75 ou plus, tous ayant interagi en 90 minutes, est une autre affaire. C'est là que la confiance devient exploitable.

Les données sont toujours probabilistes. Les corps des issues le disent explicitement. L'objectif est de donner aux mainteneurs le signal et les preuves brutes pour se faire leur propre jugement.

Tableau de bord en direct

Les dépôts les plus ciblés aujourd'hui

Modèle de notation

Chaque compte reçoit un score de suspicion composite (0.0 = propre, 1.0 = probablement faux) à partir de quatre signaux :

Seuils de classification :

Détection de campagne

Une campagne est un groupe d'au moins 4 comptes suspects ayant tous interagi avec le même dépôt dans une fenêtre de 3 heures. L'algorithme utilise l'union-find pour construire des composantes connexes ; les comptes ayant co-interagi dans la fenêtre sont fusionnés, et toute composante au-dessus de la taille minimale est signalée comme campagne coordonnée.

Les identifiants de campagne sont des empreintes SHA-256 stables de l'ensemble trié des membres. La même campagne détectée plusieurs jours consécutifs aura le même identifiant tant que la composition des membres reste inchangée.

Pourquoi les campagnes sont le véritable signal : Les scores individuels ont des taux de faux positifs significatifs. Un nouveau développeur avec un profil peu fourni peut obtenir un score de 0.80 à lui seul. Quarante comptes ayant tous un score de 0.75 ou plus, créés la même semaine, mettant tous une étoile au même dépôt en 90 minutes, n'est pas une coïncidence. Le signal de campagne est là où les données deviennent exploitables : la différence entre un point de donnée suspect et une preuve d'opération coordonnée.

Format des données

Tous les résultats sont commités dans data/suspects.jsonl et data/repos.jsonl, un enregistrement JSON par ligne, en ajout seul. Le résumé du job GitHub Actions (visible dans l'interface Actions après chaque exécution) fournit un rapport formaté pour chaque analyse.

suspects.jsonl — un enregistrement par compte signalé et par analyse :```json { "login": "user98432", "account_age_score": 0.9, "profile_score": 0.8, "repo_pattern_score": 0.8, "activity_score": 0.85, "composite": 0.842, "classification": "likely_fake", "campaign_id": "c-a3f9b2e1", "scan_date": "2026-05-17", "account_created_at": "2026-05-15", "target_repos": ["owner/repo-a", "owner/repo-b"] }

**repos.jsonl** — un enregistrement par dépôt ciblé par analyse :```json
{
  "full_name": "owner/suspicious-repo",
  "total_scanned": 87,
  "likely_fake": 62,
  "suspicious": 18,
  "known_likely_fake": 27,
  "known_likely_fake_ratio": 0.310,
  "repeat_offenders": 11,
  "allowlisted_excluded": 3,
  "fakeness_ratio": 0.713,
  "classification": "likely_fake",
  "campaign_count": 3,
  "discovery_sources": ["github_search_recent", "reddit_osinttools"],
  "event_sample_complete": false,
  "scan_date": "2026-05-17"
}

Exemples de requêtes :```bash

All likely_fake accounts from today

jq 'select(.scan_date == "2026-05-17" and .classification == "likely_fake") | .login' data/suspects.jsonl

Accounts created in the last 3 days that were flagged

jq 'select(.account_created_at >= "2026-05-14") | [.login, .account_created_at, .classification] | @tsv' -r data/suspects.jsonl

Which repos were targeted today, sorted by fakeness ratio

jq 'select(.scan_date == "2026-05-17") | [.full_name, .fakeness_ratio, .likely_fake] | @tsv' -r data/repos.jsonl | sort -t$'''\t''' -k2 -rn

Repos with the highest recycled-bot share from previously seen likely_fake accounts

jq 'select(.scan_date == "2026-05-17") | [.full_name, .known_likely_fake_ratio, .repeat_offenders] | @tsv' -r data/repos.jsonl | sort -t$'''\t''' -k2 -rn

All members of a specific campaign

jq 'select(.campaign_id == "c-a3f9b2e1") | [.login, .account_created_at, .composite] | @tsv' -r data/suspects.jsonl

Repos a specific account targeted

jq 'select(.login == "user98432") | .target_repos[]' data/suspects.jsonl

High-confidence repos: fakeness ratio above 60%

jq 'select(.fakeness_ratio >= 0.6) | [.full_name, .fakeness_ratio, .campaign_count] | @tsv' -r data/repos.jsonl | sort -t$'\t' -k2 -rn

---

## Configuration

### 1. Forkez ce dépôt

Les données appartiennent à votre fork. Les résultats sont commités sur `data/suspects.jsonl` et `data/repos.jsonl` de votre fork après chaque exécution quotidienne.

### 2. Ajoutez un secret PAT GitHub

Créez un Personal Access Token **classique** avec les scopes :
- `public_repo` : lire les événements des dépôts publics et les stargazers, créer des issues sur les dépôts publics
- `read:user` : récupérer les profils utilisateurs via GraphQL

**Paramètres → Secrets et variables → Actions → Nouveau secret de dépôt** → nommez-le `GH_TOKEN`.

> Le `GITHUB_TOKEN` par défaut a des limites de débit restreintes et ne peut pas appeler le point de terminaison GraphQL utilisateur à pleine capacité. Un PAT est requis.

### 3. Activez Actions

**Actions → Activer GitHub Actions** sur votre fork. Le workflow s'exécute chaque jour à **07:00, heure du Royaume-Uni**, en utilisant l'horloge `Europe/London` :
- **06:00 UTC** pendant l'heure d'été britannique
- **07:00 UTC** pendant l'heure moyenne de Greenwich

Aucune variable d'environnement de planification supplémentaire n'est requise. Le cron de GitHub Actions est en UTC uniquement, donc le workflow se déclenche aux deux heures UTC et ne continue que lorsque l'heure locale de Londres est 07:00. Le déclenchement manuel est disponible via **Actions → Daily Phantom Stars Scan → Exécuter le workflow**.

Après chaque exécution, le rapport de scan formaté est visible dans **Actions → [run] → Résumé**.

### 4. Exécutez en local```bash
git clone https://github.com/YOUR_USERNAME/phantomstars.git
cd phantomstars
python -m venv venv && source venv/bin/activate
pip install -e .
GH_TOKEN=ghp_your_token python -m phantomstars.main

Pour une exécution locale ad hoc après configuration :```bash GH_TOKEN=ghp_your_token python -m phantomstars.main

Pour analyser un seul dépôt au lieu de l'ensemble de découverte normal :```bash
PHANTOMSTARS_TARGET_REPO=owner/repo GH_TOKEN=ghp_your_token python -m phantomstars.main

Requêtes ponctuelles

Les utilisateurs peuvent demander une vérification ponctuelle de dépôt de deux manières :

1. Ouvrir le modèle d'issue Repo Check Request et fournir le dépôt cible ainsi que la profondeur demandée.
2. Utiliser Actions -> Daily Phantom Stars Scan -> Run workflow et définir en option :
   • target_repo : owner/repo
   • request_depth : recent ou lifetime-request

Comportement actuel :

• recent : exécute immédiatement l'analyse ciblée d'engagement récent.
• lifetime-request : exécute une analyse ciblée sur l'ensemble de la durée de vie (lifetime) des étoiles et des forks historiques pour ce dépôt uniquement.
• L'analyse planifiée quotidienne reste inchangée et continue d'utiliser la méthode d'engagement récent.

Garde-fous pour le mode lifetime :

• uniquement disponible pour les requêtes ciblées ponctuelles explicites
• plafonné par les limites de taille de dépôt configurées avant le début de l'analyse
• plus lent et plus intensif en API que l'analyse quotidienne

Structure du projet```

phantomstars/ ├── .github/ │ ├── workflows/daily-scan.yml # Runs daily at 07:00 Europe/London │ └── ISSUE_TEMPLATE/false_positive.yml ├── src/phantomstars/ │ ├── config.py # All constants, no argparse, no env parsing │ ├── models.py # Frozen dataclasses │ ├── github_client.py # REST + GraphQL, tenacity retries, rate-limit aware │ ├── heuristics.py # Per-user composite scoring engine │ ├── campaigns.py # Timestamp clustering + union-find │ ├── storage.py # JSONL append + query helpers │ ├── reporter.py # README dashboard injector │ ├── notifier.py # GitHub Issues notifier (files on targeted repos) │ └── main.py # Orchestration entry point ├── tests/ │ ├── conftest.py │ ├── test_heuristics.py │ └── test_campaigns.py ├── data/ │ ├── suspects.jsonl # Append-only account findings ledger │ ├── repos.jsonl # Append-only per-repo intelligence │ └── allowlist.txt # Accounts excluded from future scans └── pyproject.toml

---

## Limitations et modes de défaillance connus

- **Plafond de l'API Events:** maximum 300 événements récents par dépôt. Les dépôts qui reçoivent des milliers d'étoiles en une journée ont une couverture partielle.
- **Indicateur de couverture:** les dépôts qui atteignent le plafond de 300 événements sont marqués comme `capped` dans les rapports et les tableaux de bord ; les ratios sur ces dépôts sont des échantillons conservateurs, pas des comptages sur la journée complète.
- **Latence de l'index de recherche:** l'index de recherche de GitHub est à cohérence éventuelle. Les dépôts créés quelques secondes avant la limite d'analyse peuvent être manqués.
- **Dérive des heuristiques:** les opérateurs de bots s'adaptent. Les poids des scores peuvent nécessiter un ajustement périodique ; modifiez les constantes dans `config.py`.
- **Faux positifs individuels:** un nouveau développeur avec un profil peu fourni obtient un score de 0.75+ isolément. L'appartenance à une campagne est le signal de haute confiance.
- **Dérive de l'ID de campagne:** si la composition d'une ferme de bots change entre deux analyses (bots suspendus, nouveaux bots ajoutés), l'ID de campagne change. Cela reflète l'évolution réelle de la campagne, pas un bug.
- **Limites de taux:** 5,000 requêtes API/heure avec un PAT authentifié. Bien en dessous des limites pour les tailles de pages tendances standard.
- **Problèmes désactivés:** certains dépôts ciblés désactivent les problèmes. Les notifications pour ces dépôts sont ignorées silencieusement.

---

## Processus de faux positif

Si votre compte apparaît dans `data/suspects.jsonl` et que vous pensez qu'il est classé incorrectement :

1. Trouvez votre entrée : `jq 'select(.login == "YOUR_LOGIN")' data/suspects.jsonl`
2. [Ouvrez un problème de faux positif](https://raw.githubusercontent.com/tg12/issues/new?template=false_positive.yml) avec votre identifiant, la classification, la date d'analyse et une explication
3. Les rapports sont examinés manuellement. Les faux positifs vérifiés sont ajoutés à `data/allowlist.txt` et exclus de toutes les analyses futures, des ratios de dépôts et des notifications de problèmes.

Remarque : ouvrir un problème ne modifie ni ne supprime aucune donnée existante. Le registre des suspects est en append-only. La liste d'autorisation n'affecte que les analyses futures.

---

## Contribuer```bash
pip install -e ".[dev]"
python -m black .
python -m ruff check .
python -m mypy src
python -m pytest

All four must pass before a PR.

Disclaimer

Cet outil effectue une analyse en lecture seule des données publiques de GitHub à l'aide de l'API GitHub officielle. Lorsque des issues sont déposées sur des dépôts ciblés, elles contiennent des résultats probabilistes et sont clairement étiquetées comme automatisées. Les résultats sont des indicateurs, pas des accusations. Les faux positifs existent et sont attendus.

Construit avec l'IA comme partenaire de codage, en réponse à un problème d'écosystème créé en partie par l'IA.

Licence

Apache 2.0. Voir LICENSE

Auteur

Construit par tg12 · GitHub

Un projet de JS Labs · AI Slop Intelligence Dashboards