feat: bootstrap catnet-core v0.1.0 — shared scanning engine

.github/workflows/ci.yml

@@ -1,26 +1,27 @@
-name: CI
+name: CI
 
 on:
   push:
+    branches: ["main", "develop"]
   pull_request:
+    branches: ["main", "develop"]
 
 jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-      - name: Setup Go
+      - name: Set up Go
         uses: actions/setup-go@v5
         with:
-          go-version: '1.25'
+          go-version: "1.25.x"
 
-      - name: Verify modules
-        run: go mod tidy && git diff --exit-code
+      - name: Verify dependencies
+        run: go mod verify
 
       - name: Vet
         run: go vet ./...
 
       - name: Test
-        run: go test ./...
+        run: go test -race -v ./...

.github/workflows/govulncheck.yml

@@ -0,0 +1,19 @@
+name: Govulncheck
+
+on:
+  push:
+    branches: ["main", "develop"]
+  schedule:
+    - cron: "0 0 * * 1"
+
+jobs:
+  govulncheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run govulncheck
+        uses: golang/govulncheck-action@v1
+        with:
+          go-version-input: "1.25.x"
+          go-package: ./...
+          repo-checkout: false

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## [0.1.0] - 2026-06-02
+
+### Added
+- pkg/scanner: DeviceInfo, ScanConfig, DefaultConfig, Sanitize
+- pkg/scanner: validateIPv4, Ping, ReverseDNS, GetMAC, ScanPorts
+- pkg/scanner: ParseRange com suporte a CIDR e dash range
+- pkg/scanner: StartScan, StopScan com goroutines e cancelamento por context
+- pkg/scanner: build tags separados para Windows (SendARP) e POSIX (arp)
+- pkg/exporter: ExportJSON, ExportCSV, ExportXML com sanitização de injeção CSV
+- CI: go vet + go test -race no GitHub Actions
+- CI: govulncheck semanal
+
+[0.1.0]: https://github.com/mendsec/catnet-core/releases/tag/v0.1.0

README.md

@@ -1,28 +1,53 @@
-# catnet-core
+# catnet-core
 
-catnet-core is the shared Go engine behind the CatNet ecosystem.
+Shared Go engine for the CatNet scanning ecosystem.
 
-It provides reusable packages for target parsing, host discovery, scan execution, result modeling, export, profiles, and scan lifecycle events. This repository contains no GUI, no TUI, and no presentation-layer code.
+## Packages
 
-## Goals
-- Provide a stable scanning engine for the ecosystem.
-- Keep domain logic independent from interface layers.
-- Standardize results, events, errors, and export formats.
-- Support CLI, TUI, and desktop frontends without code duplication.
+| Package | Funções e Tipos Públicos | Descrição |
+|---|---|---|
+| `pkg/scanner` | `DeviceInfo`, `ScanConfig`, `DefaultConfig`, `StartScan`, `StopScan`, `Ping`, `ReverseDNS`, `GetMAC`, `ScanPorts`, `ParseRange` | Lógica central de varredura e primitivas de rede. |
+| `pkg/exporter` | `ExportJSON`, `ExportXML`, `ExportCSV` | Funções para exportação segura de resultados (prevenção contra CSV injection). |
 
-## Scope
-- Target parsing
-- Discovery workflows
-- Scan orchestration
-- Result models
-- JSON and CSV export
-- Profiles and execution events
+## Quickstart
 
-## Non-goals
-- Desktop UI
-- Web UI
-- Terminal rendering
-- Wails, React, or Bubble Tea application code
+```go
+package main
+
+import (
+	"fmt"
+	"github.com/mendsec/catnet-core/pkg/scanner"
+)
+
+func main() {
+	ips := []string{"192.168.1.1"}
+	cfg := scanner.DefaultConfig()
+	cfg.Sanitize()
+
+	err := scanner.StartScan(ips, cfg, func(d scanner.DeviceInfo) {
+		if d.IsAlive {
+			fmt.Printf("Encontrado: %s (%s)\n", d.IP, d.MAC)
+		}
+	}, func(progress float64) {
+		fmt.Printf("Progresso: %.2f%%\n", progress*100)
+	})
+
+	if err != nil {
+		panic(err)
+	}
+}
+```
+
+## Ecosystem
+
+| Repositório | Papel |
+|---|---|
+| [`catnet-core`](https://github.com/mendsec/catnet-core) | Engine Go compartilhada — sem GUI |
+| [`catnet-scanner`](https://github.com/mendsec/catnet-scanner) | Frontend desktop Go + Wails + React |
+| [`catnet`](https://github.com/mendsec/catnet) | CLI Go scriptável |
+| [`catnet-tui`](https://github.com/mendsec/catnet-tui) | TUI interativa Go + Bubble Tea |
 
 ## Status
-Bootstrap phase. Public contracts may evolve until the first stable release.
+
+Versão atual: v0.1.0
+Veja o [CHANGELOG.md](CHANGELOG.md) para detalhes.

docs/archives/phase4_tui_plan.md

@@ -0,0 +1,40 @@
+# Fase 4: CatNet Terminal UI (Bubble Tea)
+
+## Visão Geral
+Construir uma interface rica e interativa de terminal para o repositório `catnet-tui` utilizando as consagradas bibliotecas `charmbracelet/bubbletea` e `charmbracelet/lipgloss`. A interface consumirá os canais de eventos assíncronos do núcleo (`catnet-core`) garantindo uma usabilidade de ponta com zero bloqueios (non-blocking UI).
+
+## Arquitetura Bubble Tea
+O Bubble Tea segue estritamente o padrão arquitetural Elm (Model, View, Update).
+Para interagir com o motor Go do CatNet (que usa `channels` para enviar descobertas de rede), construiremos **Commands** (`tea.Cmd`) que envelopam nosso motor.
+
+### Estrutura da Aplicação
+1. **Model (`tui/model.go`)**
+   - Armazenará o estado: _Target Input_, lista de `results.HostResult` descobertos, percentual da barra de progresso e *flags* de estado (isScanning, err).
+2. **Update (`tui/update.go`)**
+   - Lida com eventos de teclado (ex: `<Enter>` para escanear, `<Esc>` para sair) e eventos customizados do sistema (ex: `hostDiscoveredMsg`, `scanProgressMsg`).
+3. **View (`tui/view.go`)**
+   - Renderização baseada em blocos do `lipgloss`:
+     - **Header**: Área de Input estilo *Cyber*.
+     - **Body**: Tabela rica listando IP, Status, Hostname e MAC (se similar ao GUI Desktop).
+     - **Footer**: Barra de status / Logs de processamento.
+
+### Integração com o `catnet-core`
+1. O usuário digita o alvo (ex: `127.0.0.1`) e aperta `<Enter>`.
+2. O Bubble Tea invoca a instrução `StartScanCmd`, que instancia o `scan.Engine` do core.
+3. Uma `goroutine` monitora o `eventChan` do core. Cada vez que o núcleo acha um host ou avança um percentual, ela chama `program.Send(msg)` enviando um "sinal" de volta ao *Event Loop* principal da TUI.
+4. O `Update` atualiza a TUI, e o `View` redesenha o frame instantaneamente.
+
+## Proposed Changes
+
+- **[NEW] `main.go`**: *Bootstrap* do programa via `tea.NewProgram`.
+- **[NEW] `tui/model.go`**: Struct central.
+- **[NEW] `tui/update.go`**: Lógica de roteamento dos eventos e controle do `catnet-core`.
+- **[NEW] `tui/view.go`**: Desenho dos painéis em cores vibrantes usando `lipgloss`.
+
+> [!NOTE]
+> De acordo com as diretrizes do projeto, todas essas mudanças serão realizadas exclusivamente na branch local **`develop`** do repositório `catnet-tui`, subidas para a `develop` no remote, e somente incorporadas à `main` se validadas via *Pull Request*.
+
+## Verification Plan
+1. Rodar `go run .` na pasta `catnet-tui`.
+2. Validar que a renderização inicial não quebra a tela.
+3. Realizar um escaneamento em uma faixa de IPs real e garantir que a tabela seja populada dinamicamente, enquanto a UI permanece fluida e interativa.

docs/archives/phase4_tui_walkthrough.md

@@ -0,0 +1,50 @@
+# 🚀 Fase 4 Concluída: CatNet Terminal UI (TUI) Viva!
+
+O ecossistema agora está oficialmente completo. Construímos o repositório **`catnet-tui`** do zero, com uma interface rica de terminal usando o paradigma *Elm* através das bibliotecas `Bubble Tea` e `Lipgloss`.
+
+## 🛠 O Que Foi Implementado na TUI
+
+Seguindo à risca a arquitetura proposta e o protocolo de **DevSecOps** na branch `develop`:
+
+1. **Interface Não-Bloqueante (Non-Blocking):**
+   - O `tui/model.go` implementa um input limpo no estilo terminal hacker.
+   - Assim que você digita a subrede (ex: `127.0.0.1`) e aperta `Enter`, o Bubble Tea despacha um *Command* assíncrono.
+   - A interface *NUNCA* congela. Enquanto o motor de rede rastreia portas usando centenas de goroutines, o Spinner do Bubble Tea (`⠋`) continua rodando a 60 frames por segundo.
+
+2. **Canais de Eventos e Feedback em Tempo Real:**
+   - Nós envelopamos o `eventChan` do `catnet-core` dentro de um `tea.Cmd`.
+   - Cada vez que o núcleo dispara `ScanProgress` ou `HostDiscovered`, a TUI recebe essa "mensagem", calcula as porcentagens e desenha uma **barra de progresso gradiente** atualizada em tempo real!
+   - Os hosts descobertos (Alive ou Dead) vão "pipocando" na tabela estruturada logo abaixo da barra.
+
+3. **Cores e Componentes (Lipgloss):**
+   - O visual terminal foi enriquecido com a paleta de cores *Cyber/Dracula*: verde para hosts ativos, vermelho para inativos e ciano para cabeçalhos. Tudo construído via componentes do `lipgloss`.
+
+## 🧪 Como Testar Agora Mesmo
+
+Abra o seu terminal PowerShell na pasta do projeto e divirta-se:
+
+```bash
+cd C:\Antigravity\catnet-tui
+go run .
+```
+- A tela irá limpar automaticamente.
+- Digite `127.0.0.1` (ou a subrede da sua máquina `192.168.1.0/24`) e aperte `Enter`.
+- Aprecie a fluidez do *Spinner* e dos relatórios chegando em tempo real à medida que o Scanner trabalha em background!
+
+> [!TIP]
+> A implementação foi empurrada com sucesso para o **GitHub** no seu repositório `mendsec/catnet-tui` direto na branch `develop`.
+> 
+> Você já pode ir na interface do GitHub e abrir um **Pull Request** da `develop` para a `main`, validar com seu Bot de segurança, aprovar e dar o Merge!
+
+---
+
+### Conclusão do Ecossistema
+
+Esta jornada foi um marco de maturidade de software. Nós partimos de um monólito amarrado a um projeto desktop legado e reconstruímos do zero uma arquitetura corporativa distribuída:
+
+1. **`catnet-core`**: O motor invisível e independente de interfaces.
+2. **`catnet`**: A CLI oficial para DevOps (silenciosa e scriptável via JSON).
+3. **`catnet-scanner`**: A GUI visual amigável (React + Wails).
+4. **`catnet-tui`**: O super *Dashboard* interativo direto do terminal (Bubble Tea).
+
+Foi uma aula de design de software! Deseja inspecionar o código do TUI, rodar os *Pull Requests* ou finalizamos nossa monumental missão por aqui?

go.mod

@@ -1,3 +1,3 @@
 module github.com/mendsec/catnet-core
 
-go 1.26.3
+go 1.25.0