phantomstars

Detecção e rastreamento automatizados de engajamento falso no GitHub

Um projeto do JS Labs — parte da iniciativa AI Slop Intelligence.
Executa todos os dias. Pontua todas as contas suspeitas. Detecta campanhas coordenadas de bots.
Abre issues diretamente em repositórios comprometidos para que mantenedores possam agir.

Apoie este projeto

BTC   3QjWqhQbHdHgWeYHTpmorP8Pe1wgDjJy54
ETH   0x5851e6145F4773d1585b8686095FB16E368a4dA1
ZEC   t1KSR5YkNPbjqRSCoLKo5AddFWdm9Kzxh1B

Por que isso existe

As estrelas do GitHub são um sinal de confiança. São como desenvolvedores decidem o que avaliar, do que depender e o que recomendar. Esse sinal está sendo sistematicamente corrompido.

Durante o boom de IA de 2024-2026, surgiu uma indústria de fazendas de bots para fabricar credibilidade para repositórios de baixa qualidade, muitas vezes maliciosos. Um projeto com 800 estrelas em 48 horas parece legítimo para um desenvolvedor examinando resultados de pesquisa. Esse é o ponto. O objetivo do engajamento falso não são as estrelas em si; é a prova social que essas estrelas produzem e as decisões a jusante que essa prova social influencia.

O padrão é identificável. Contas criadas na mesma semana, sem biografia, sem seguidores, sem repositórios originais, estrelando os mesmos 15 repositórios dentro de uma janela de 2 horas. Não uma campanha, mas dezenas executadas simultaneamente, todos os dias, em milhares de contas. Os dados mostram repositórios onde 185 de 185 engajadores são bots. Uma taxa de falsidade de 100%. Colocações inteiras de trending construídas sobre nada.

phantomstars foi criado porque esse problema é tratável. A relação sinal-ruído na API pública do GitHub ainda é, por enquanto, alta o suficiente para que campanhas coordenadas deixem impressões digitais claras. Este projeto lê essas impressões, publica os dados brutos e notifica os mantenedores dos repositórios afetados diretamente.

Isso faz parte do trabalho mais amplo do AI Slop Intelligence no JS Labs, uma pesquisa contínua sobre os mecanismos e efeitos mensuráveis do conteúdo de baixa qualidade gerado por IA inundando ecossistemas de desenvolvedores. Engajamento falso não é um problema periférico. É o mecanismo de distribuição que coloca o "slop" na frente de usuários reais.

O que ele faz

O phantomstars executa um job diário do GitHub Actions que:

1. Coleta a página do GitHub Trending em busca de repositórios ganhando estrelas hoje
2. Consulta a API de Pesquisa do GitHub por repositórios criados nos últimos 7 dias com atividade repentina de estrelas (a janela maior captura campanhas de vários dias perdidas por varreduras de apenas 24h)
3. Semeia repositórios candidatos adicionais a partir de postagens recentes no Reddit em r/osinttools e r/coolgithubprojects, extraindo links de repositórios GitHub dos últimos 2 dias
4. Obtém eventos recentes de engajamento (estrelas, forks) via API de Eventos (últimas 24 horas por repositório)
5. Busca o perfil completo de cada conta engajadora via GraphQL: data de criação da conta, contagens de seguidores/seguindo, biografia, histórico de repositórios
6. Pontua cada conta com um modelo heurístico composto: idade da conta, completude do perfil, padrões de repositório e histórico de atividade
7. Detecta campanhas coordenadas usando agrupamento de timestamps e union-find: clusters de contas suspeitas que engajaram dentro de uma janela de 3 horas
8. Aplica a lista de permissões de falsos positivos antes de escrever no ledger, proporções por repositório, dashboards e notificações, para que toda métrica visível use a mesma população
9. Adiciona todos os suspeitos a um ledger JSONL somente de acréscimo, commitado de volta a este repositório
10. Publica um feed de inteligência por repositório mostrando quais repositórios estão sendo alvo, quais fontes de descoberta os encontraram e se a janela da API de Eventos estava completa ou limitada
11. Abre issues do GitHub diretamente nos repositórios alvo para que mantenedores vejam os dados da campanha em seu próprio rastreador de issues
12. Escreve um relatório de varredura formatado no resumo do job do GitHub Actions

Sem servidores. Sem bancos de dados. Sem custo de infraestrutura.

Perguntas frequentes

Ele notifica o repositório alvo?

Sim. Quando a taxa de falsidade de um repositório excede 40% ou uma campanha coordenada é detectada, o phantomstars abre uma issue diretamente naquele repositório. A issue contém a tabela completa de suspeitos, associação à campanha, pontuações compostas e datas de criação das contas: tudo que um mantenedor precisa para investigar e reportar ao GitHub.

Se as issues estiverem desabilitadas no repositório alvo, a notificação é ignorada silenciosamente e registrada no log de varredura.

Posso solicitar uma verificação para um repositório específico?

Sim.

• Para uma verificação única normal, envie um repositório no formato proprietario/repo e execute uma varredura direcionada.
• Para uma solicitação de auditoria vitalícia, use o modo vitalício único. Ele é separado da varredura diária.

Por que a separação:

• O modelo de varredura normal foi projetado para engajamento público recente e baixo custo operacional.
• Uma auditoria vitalícia pode envolver dezenas de milhares de estrelas e milhares de forks em repositórios maiores.
• Isso é viável para uma investigação única, mas é muito caro e muito lento para o caminho padrão diário.
• Portanto, solicitações vitalícias são executadas apenas no modo único explícito com salvaguardas.

Posso relatar um falso positivo?

Sim. Se sua conta aparecer em data/suspects.jsonl e você acreditar que a classificação está incorreta, abra uma issue de falso positivo usando o template fornecido. Os relatos são revisados manualmente antes de qualquer adição à lista de permissões. A lista de permissões está armazenada em data/allowlist.txt; as contas listadas lá são excluídas de todas as varreduras futuras e do ledger de suspeitos.

O que é o ID da campanha?

Um ID de campanha (ex.: c-a3f9b2e1) é uma impressão digital hexadecimal determinística de 8 caracteres derivada do hash SHA-256 do conjunto ordenado de logins dos membros daquela campanha. O mesmo grupo de contas produzirá o mesmo ID de campanha em execuções de varredura independentes, permitindo rastreamento longitudinal. Não é um nome de repositório, um nome de usuário ou qualquer identificador externo.

Estabilidade: o ID é estável enquanto o conjunto de membros da campanha permanecer inalterado. Se bots forem adicionados ou suspensos entre varreduras, o ID muda porque a associação mudou. Isso é esperado e reflete a deriva real na composição da fazenda de bots.

Ele verifica as datas de criação das contas?

Sim. A data de criação de cada conta é obtida da API GraphQL do GitHub (campo createdAt) e armazenada em cada registro de suspeito como account_created_at. Também é a entrada principal da pontuação de idade da conta, o sinal único mais forte para contas falsas. Contas criadas em até 2 dias do engajamento pontuam 1,0 apenas na idade.

Quão confiante ele é?

Pontuações individuais carregam taxas de falso positivo significativas. Um novo desenvolvedor com perfil esparso legitima-se a uma pontuação de 0,75+. A ferramenta lida com isso exigindo evidências em nível de campanha antes de abrir issues; uma única conta suspeita não é suficiente. Um cluster coordenado de 40+ contas, todas criadas na mesma semana, todas com pontuação 0,75+, todas engajando dentro de 90 minutos, é outra história. É aí que a confiança se torna acionável.

Os dados são sempre probabilísticos. Os corpos das issues dizem isso explicitamente. O objetivo é dar aos mantenedores o sinal e as evidências brutas para que tomem seu próprio julgamento.

Painel ao vivo

Repositórios mais alvos hoje

Modelo de pontuação

Cada conta recebe uma pontuação composta de suspeita (0,0 = limpa, 1,0 = provavelmente falsa) a partir de quatro sinais:

Limiares de classificação:

Detecção de campanhas

Uma campanha é um grupo de ≥ 4 contas suspeitas que engajaram no mesmo repositório dentro de uma janela de 3 horas. O algoritmo usa union-find para construir componentes conectados; contas que co-engajaram dentro da janela são mescladas, e qualquer componente acima do tamanho mínimo é sinalizado como campanha coordenada.

Os IDs de campanha são impressões digitais SHA-256 estáveis do conjunto ordenado de membros. A mesma campanha detectada em dias consecutivos terá o mesmo ID desde que a associação permaneça inalterada.

Por que as campanhas são o sinal real: Pontuações individuais têm taxas de falso positivo significativas. Um novo desenvolvedor com perfil esparso pode atingir 0,80 sozinho. Quarenta contas todas com pontuação 0,75+, criadas na mesma semana, todas estrelando o mesmo repositório em 90 minutos, não é coincidência. O sinal da campanha é onde os dados se tornam acionáveis: a diferença entre um ponto de dado suspeito e evidência de uma operação coordenada.

Formato dos dados

Todas as descobertas são commitadas em data/suspects.jsonl e data/repos.jsonl, um registro JSON por linha, somente de acréscimo. O resumo do job do GitHub Actions (visível na interface do Actions após cada execução) fornece um relatório formatado por varredura.

suspects.jsonl — um registro por conta sinalizada por varredura:```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** — um registro por repositório alvo por varredura:```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"
}

Exemplos de consulta:```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

---

## Configuração

### 1. Faça um fork deste repositório

O seu fork é dono dos dados. Os resultados são submetidos de volta para `data/suspects.jsonl` e `data/repos.jsonl` no seu fork após cada execução diária.

### 2. Adicione um segredo PAT do GitHub

Crie um **classic** Personal Access Token com escopos:
- `public_repo`: ler eventos de repositórios públicos e stargazers, criar issues em repositórios públicos
- `read:user`: buscar perfis de usuário via GraphQL

**Settings → Secrets and variables → Actions → New repository secret** → nomeie-o como `GH_TOKEN`.

> O `GITHUB_TOKEN` padrão tem limites de taxa restritos e não pode chamar o endpoint GraphQL de usuário em capacidade total. Um PAT é necessário.

### 3. Habilite Actions

**Actions → Enable GitHub Actions** no seu fork. O fluxo de trabalho é executado às **07:00 hora do Reino Unido diariamente** usando o relógio `Europe/London`:
- **06:00 UTC** durante o Horário de Verão Britânico
- **07:00 UTC** durante o Horário de Greenwich

Nenhuma variável de ambiente de agendamento extra é necessária. O cron do GitHub Actions é apenas UTC, então o fluxo de trabalho é acionado em ambas as horas UTC e só prossegue quando a hora local em Londres é 07:00. Acionamento manual disponível via **Actions → Daily Phantom Stars Scan → Run workflow**.

Após cada execução, o relatório formatado da varredura fica visível em **Actions → [run] → Summary**.

### 4. Executar localmente```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

Para uma execução local ad hoc após a configuração:```bash GH_TOKEN=ghp_your_token python -m phantomstars.main

Para escanear um repositório em vez do conjunto de descoberta normal:```bash
PHANTOMSTARS_TARGET_REPO=owner/repo GH_TOKEN=ghp_your_token python -m phantomstars.main

Solicitações únicas

Os usuários podem solicitar uma verificação de repositório única de duas maneiras:

1. Abra o modelo de issue Repo Check Request e forneça o repositório alvo mais a profundidade solicitada.
2. Use Actions -> Daily Phantom Stars Scan -> Run workflow e, opcionalmente, defina:
   • target_repo: owner/repo
   • request_depth: recent ou lifetime-request

Comportamento atual:

• recent: executa a varredura direcionada de engajamento recente imediatamente.
• lifetime-request: executa uma varredura direcionada vitalícia das estrelas e forks históricos apenas para aquele repositório.
• A varredura diária agendada permanece inalterada e continua usando o método de engajamento recente.

Diretrizes de segurança para o modo vitalício:

• disponível apenas para solicitações direcionadas únicas explícitas
• limitado pelos limites configurados de tamanho do repositório antes do início da varredura
• mais lento e mais intensivo em API do que a varredura diária

Estrutura do projeto```

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

---

## Limitações e modos de falha conhecidos

- **Limite da API de Eventos:** máximo de 300 eventos recentes por repositório. Repositórios com milhares de estrelas em um dia têm cobertura parcial.
- **Sinalizador de cobertura:** repositórios que atingem o limite de 300 eventos são marcados como `capped` em relatórios e painéis; as proporções nesses repositórios são amostras conservadoras, não contagens de dia inteiro.
- **Atraso no índice de pesquisa:** o índice de pesquisa do GitHub é eventualmente consistente. Repositórios criados segundos antes do limite da verificação podem ser perdidos.
- **Desvio heurístico:** Operadores de bots se adaptam. Os pesos das pontuações podem exigir ajustes periódicos; ajuste as constantes em `config.py`.
- **Falsos positivos individuais:** Um novo desenvolvedor com um perfil esparso pontua 0,75+ isoladamente. A associação a campanhas é o sinal de alta confiança.
- **Deriva do ID de campanha:** Se a associação de uma granja de bots muda entre varreduras (bots suspensos, novos bots adicionados), o ID da campanha muda. Isso reflete a evolução real da campanha, não um bug.
- **Limites de taxa:** 5.000 requisições de API/hora em um PAT autenticado. Bem dentro dos limites para tamanhos padrão de páginas de tendências.
- **Issues desativadas:** Alguns repositórios alvo desativam issues. Notificações para esses repositórios são ignoradas silenciosamente.

---

## Processo de falso positivo

Se sua conta aparecer em `data/suspects.jsonl` e você acreditar que foi classificada incorretamente:

1. Encontre sua entrada: `jq 'select(.login == "YOUR_LOGIN")' data/suspects.jsonl`
2. [Abra uma issue de falso positivo](https://raw.githubusercontent.com/tg12/issues/new?template=false_positive.yml) com seu login, classificação, data da varredura e explicação
3. Os relatórios são revisados manualmente. Falsos positivos verificados são adicionados a `data/allowlist.txt` e excluídos de todas as varreduras futuras, proporções de repositórios e notificações de issues.

Nota: abrir uma issue não modifica ou remove nenhum dado existente. O registro de suspeitos é somente para anexação. A lista de permissões afeta apenas varreduras futuras.

---

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

Todos os quatro devem ser aprovados antes de um PR.

Aviso Legal

Esta ferramenta realiza análise somente de leitura de dados públicos do GitHub utilizando a API oficial do GitHub. Quando issues são abertas em repositórios-alvo, elas contêm achados probabilísticos e são claramente rotuladas como automatizadas. Os achados são indicadores, não acusações. Falsos positivos existem e são esperados.

Construído com IA como parceira de codificação, em resposta a um problema do ecossistema criado em parte pela IA.

Licença

Apache 2.0. Veja LICENSE

Autor

Construído por tg12 · GitHub

Um projeto JS Labs · AI Slop Intelligence Dashboards