glassworm-hunter

# glassworm-hunter

![Glassworm Hunter Logo](https://assets.kitploit.com/production/public/readmes/12745/51866d5ae6a1cd658e373c844337ab4ba2f0095768bedf0ee57eb12450547a6a.jpg)

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

```bash
pip install glassworm-hunter
```

Ou com pipx:

```bash
pipx install glassworm-hunter
```

## Início rápido

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

```bash
glassworm-hunter scan --no-extensions
```

Escaneie um projeto específico:

```bash
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

```bash
# 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

1. **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.
2. **Não execute o código sinalizado.** Não execute, compile ou teste o projeto afetado até que seja resolvido.
3. **Descobertas CRÍTICAS:** Desinstale a extensão/pacote imediatamente. Gire seus tokens NPM, tokens GitHub, chaves SSH e quaisquer outras credenciais na máquina.
4. **Descobertas ALTAS:** Investigue o arquivo sinalizado. Se estiver em uma dependência que você não instalou explicitamente, remova-a.
5. **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:

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

SARIF para GitHub Code Scanning:

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

Enviar SARIF para o GitHub:

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

Usar códigos de saída no CI:

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

Excluir artefatos de build e código de fornecedor:

```bash
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:

```yaml
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:

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

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

```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):

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

## Créditos

- [Koi Security](https://www.koi.ai) — 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](https://www.aikido.dev) — 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](https://afine.com) — este scanner. Leia a pesquisa completa: [Hunting GlassWorm: Open-Source Detection for Invisible Supply Chain Payloads](https://afine.com/blogs/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