glassworm-hunter

Glassworm Hunter Logo

Detecte payloads de ataque da cadeia de suprimentos GlassWorm em sua máquina. Escaneia extensões do VS Code, pacotes npm, pacotes Python e repositórios git.

Este scanner detecta a própria técnica de ataque — payloads invisíveis de seletores de variação Unicode, padrões de decodificação GlassWorm, indicadores de C2 e código de coleta de credenciais.

Instalação

pip install glassworm-hunter

Ou com pipx:

pipx install glassworm-hunter

Início rápido

Escaneie seu diretório atual sem escanear extensões VS Code/Cursor:

glassworm-hunter scan --no-extensions

Escaneie um projeto específico:

glassworm-hunter scan /path/to/project

O que ele detecta

Detecção de técnica (captura variantes desconhecidas)

Payloads Unicode invisíveis — caracteres seletores de variação (U+FE00-FE0F, U+E0100-E01EF) usados para codificar código oculto. Usos legítimos são 1-2 caracteres para emoji. GlassWorm usa milhares.
Padrões de decodificação GlassWorm — a aritmética codePointAt + faixa de seletor de variação que decodifica payloads invisíveis
Caracteres de substituição bidirecional — ataque Trojan Source (CVE-2021-42574)
Preenchimento Hangul — identificadores JavaScript válidos invisíveis (U+3164)
eval/Function com conteúdo dinâmico — sumidouros de execução alimentados por strings decodificadas
Acesso a credenciais — código lendo .npmrc, .gitcredentials, chaves SSH, variáveis de ambiente de tokens
Padrões de comunicação C2 — chamadas RPC Solana, URLs do Google Calendar, canais de dados WebRTC em contextos inesperados

Correspondência de IoCs conhecidos (suplementar)

21 IDs de extensões maliciosas conhecidas do VS Code/OpenVSX (todas as 5 ondas)
4 pacotes npm maliciosos conhecidos
14 endereços IP de C2 conhecidos
3 endereços de carteira Solana C2 conhecidos
Email do atacante e artefatos de caminho de build

Níveis de severidade

Nível	Significado
CRÍTICO	Payload GlassWorm ativo detectado (cluster Unicode invisível no código, padrão de decodificador)
ALTO	IoC malicioso conhecido correspondido (IP C2, carteira, dependência de extensão em malware conhecido)
MÉDIO	Padrão suspeito que vale a pena revisar (eval + conteúdo dinâmico, acesso a credenciais, Trojan Source)
BAIXO	Informativo (densidade incomum de caracteres de largura zero, scripts de instalação suspeitos)

Opções de CLI

glassworm-hunter scan [OPÇÕES] [CAMINHOS...]

Opção	Padrão	Descrição
`--extensions / --no-extensions`	ativado	Escanear extensões VS Code/Cursor/Codium
`--npm-scan / --no-npm-scan`	ativado	Escanear node_modules
`--pip-scan / --no-pip-scan`	desativado	Escanear pacotes Python site-packages
`--git / --no-git`	ativado	Escanear repositórios git
`--format [console\|json\|sarif]`	console	Formato de saída
`--output FILE`	stdout	Escrever relatório em arquivo
`--severity [critical\|high\|medium\|low]`	low	Severidade mínima a relatar
`--max-file-size SIZE`	10MB	Pular arquivos maiores que isso
`--include-hidden`	desativado	Escanear arquivos/diretórios ocultos
`--quiet`	desativado	Suprimir saída de progresso
`--verbose`	desativado	Mostrar cada arquivo sendo escaneado
`--exclude PATTERN`	—	Padrões glob a excluir (repetível)
`--disable-rule RULE_ID`	—	Suprimir regras de detecção específicas (repetível)
`--ioc-file FILE`	—	Carregar indicadores IoC adicionais de um arquivo JSON

Uma barra de progresso Rich é mostrada no stderr durante a varredura. Ela é suprimida automaticamente com --quiet ou --verbose. Uma linha de resumo (arquivos escaneados, descobertas, caminho de saída) é sempre impressa no stderr após a conclusão da varredura.

Outros comandos

# Listar todos os IDs de regras de detecção (para uso com --disable-rule)
glassworm-hunter rules

# Atualizar banco de dados IoC local do GitHub (fonte padrão:
# https://raw.githubusercontent.com/afine-com/glassworm-hunter/main/data/ioc.json)
glassworm-hunter update

# Atualizar de uma fonte personalizada (ex.: servidor interno de inteligência de ameaças)
glassworm-hunter update --source https://internal.corp/ioc.json

# Forçar sobrescrita do banco de dados IoC local existente
glassworm-hunter update --force

# Imprimir versão
glassworm-hunter version

Códigos de saída

Código	Significado
0	Nenhuma descoberta
1	Descobertas detectadas
2	Erro do scanner

Se você encontrar algo

Não entre em pânico. O scanner encontrou um indicador, não uma violação confirmada. Algumas detecções podem ser falsos positivos, e nossa equipe está continuamente trabalhando para reduzi-los e melhorar a precisão da detecção.
Não execute o código sinalizado. Não execute, compile ou teste o projeto afetado até que seja resolvido.
Descobertas CRÍTICAS: Desinstale a extensão/pacote imediatamente. Gire seus tokens NPM, tokens GitHub, chaves SSH e quaisquer outras credenciais na máquina.
Descobertas ALTAS: Investigue o arquivo sinalizado. Se estiver em uma dependência que você não instalou explicitamente, remova-a.
Descobertas MÉDIAS: Revise o código. Esses padrões são suspeitos, mas podem ser legítimos em alguns contextos.

Integração CI/CD

Saída JSON para processamento automatizado:

glassworm-hunter scan . --format json --output report.json --no-extensions

SARIF para GitHub Code Scanning:

glassworm-hunter scan . --format sarif --output results.sarif --no-extensions

Enviar SARIF para o GitHub:

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: results.sarif

Usar códigos de saída no CI:

glassworm-hunter scan . --severity critical --no-extensions || exit 1

Excluir artefatos de build e código de fornecedor:

glassworm-hunter scan . --exclude "dist/**" --exclude "*.min.js" --no-extensions

Sem acesso à rede

Este scanner é totalmente offline por padrão. Ele lê apenas arquivos locais. Sem telemetria, sem contato telefônico, sem verificações automáticas de atualização. Bancos de dados de IoC são incluídos no pacote.

O único comando que faz uma requisição de rede é glassworm-hunter update, que busca o banco de dados IoC mais recente do GitHub (ou de uma URL --source personalizada). Ele nunca é chamado automaticamente.

Arquivo de configuração

Coloque um .glassworm.yml na raiz do seu projeto para definir padrões:

exclude:
  - "*.min.js"
  - "vendor/**"
  - "dist/**"

disable_rules:
  - zero-width-chars

severity: medium

Flags de CLI sobrescrevem valores do arquivo de configuração.

Arquivos IoC personalizados

Use --ioc-file para carregar indicadores adicionais de um arquivo JSON. Isso é útil para inteligência de ameaças específica da equipe ou interna:

glassworm-hunter scan /path --ioc-file /path/to/team_ioc.json

O arquivo deve seguir o mesmo esquema de data/ioc.json:

{
  "schema_version": "1.0",
  "extensions": [{"id": "publisher.name"}],
  "npm_packages": [{"name": "pkg", "malicious_versions": "1.0.0"}],
  "c2_ips": [{"ip": "1.2.3.4"}],
  "c2_wallets": [{"address": "..."}],
  "attacker_artifacts": [{"type": "email", "value": "[email protected]"}]
}

O arquivo personalizado é mesclado sobre todas as outras camadas de IoC (codificado → empacotado → usuário ~/.glassworm/ioc.json → --ioc-file).

Camadas do banco de dados IoC

O scanner usa um sistema IoC de 3+1 camadas (cada camada mescla sobre a anterior, nunca remove):

Codificado — embutido no código-fonte Python, sempre disponível
Empacotado — data/ioc.json enviado com o pacote
Usuário — ~/.glassworm/ioc.json, atualizado via glassworm-hunter update
Personalizado — flag --ioc-file, maior prioridade

Créditos

Koi Security — descoberta original do GlassWorm (outubro de 2025) e rastreamento contínuo em várias ondas, incluindo a campanha OpenVSX/VSCode, pivô binário Rust e pivô macOS. Os dados de IoC neste scanner baseiam-se em suas pesquisas publicadas.
Aikido Security — análise da onda de março de 2026 do GlassWorm visando repositórios GitHub e pacotes npm, junto com Socket, Step Security e a comunidade OpenSourceMalware.
AFINE — este scanner. Leia a pesquisa completa: Hunting GlassWorm: Open-Source Detection for Invisible Supply Chain Payloads

Windows

O scanner funciona no Windows. 4 testes falham a menos que você execute um prompt de comando elevado (Administrador).

Licença

MIT

Ler mais

glassworm-hunter v1.0.4

Categorias