Versão: Próxima

Auditoria de Segurança

O Invowk inclui um scanner de segurança integrado que analisa invowkfiles, módulos, dependências vendorizadas e conteúdo de scripts em busca de vulnerabilidades na cadeia de suprimentos, injeção de scripts, travessia de caminhos, padrões suspeitos e problemas de integridade de lock files.

Início Rápido

# Scan current directory
invowk audit

# Scan a specific module
invowk audit ./tools.invowkmod

# Only show high and critical findings
invowk audit --severity high

# JSON output for CI
invowk audit --format json

# Include global modules
invowk audit --include-global

Como Funciona

O comando invowk audit constrói um snapshot imutável de todos os artefatos descobertos (invowkfiles, módulos, scripts, lock files), e então executa 6 checkers de segurança integrados concorrentemente. Após todos os checkers completarem, um correlacionador cruza os achados para detectar ameaças compostas.

invowk audit [path]
  │
  ├── Descoberta ──► Snapshot imutável (ScanContext)
  │
  ├── Checkers Concorrentes (6 integrados + LLM opcional)
  │   ├── Script Checker ──► achados de execução, travessia, ofuscação
  │   ├── Network Checker ──► achados de exfiltração
  │   ├── Env Checker ──► achados de exfiltração
  │   ├── Lock File Checker ──► achados de integridade
  │   ├── Symlink Checker ──► achados de travessia de caminhos
  │   ├── Module Metadata Checker ──► achados de confiança
  │   └── LLM Checker (opt-in) ──► achados multi-categoria
  │
  ├── Correlacionador ──► detecção de ameaças compostas
  │
  └── Relatório ──► saída em texto ou JSON

Alvos de Scan

O scanner auto-detecta o tipo de alvo baseado no caminho:

Caminho	O que é Escaneado
Diretório (padrão `.`)	Invowkfile raiz + todos os diretórios `*.invowkmod` + fontes de descoberta
Diretório `*.invowkmod`	Módulo único (invowkfile + lock file + deps vendorizadas)
Arquivo `*.cue`	Invowkfile standalone único

Ao escanear um diretório, o scanner também descobre módulos de caminhos includes configurados e opcionalmente de ~/.invowk/cmds/ (com --include-global).

Checkers Integrados

Script Checker

Analisa conteúdo e caminhos de scripts em busca de padrões de execução perigosos.

Detecta:

Execução remota de código: curl | bash, wget | sh, download-e-execução silencioso
Travessia de caminhos: sequências ../ no conteúdo do script
Ofuscação: codificação/decodificação base64, eval com conteúdo dinâmico, sequências hexadecimais
Arquivos de script excepcionalmente grandes (>5 MiB)

Network Checker

Escaneia scripts em busca de padrões de acesso à rede que podem indicar exfiltração de dados.

Detecta:

Padrões de reverse shell (bash, Python, Perl, netcat)
Exfiltração DNS (dig, nslookup com subdomínios dinâmicos)
URLs codificadas (alvos de rede codificados em base64)
Comandos de rede suspeitos em contextos inesperados

Environment Checker

Analisa configuração de ambiente e conteúdo de scripts em busca de riscos de exposição de credenciais.

Detecta:

env_inherit_mode: "all" arriscado (expõe todas as variáveis de ambiente do host)
Acesso a variáveis sensíveis: AWS_SECRET_ACCESS_KEY, GITHUB_TOKEN, DATABASE_URL, senhas, chaves privadas
Padrões de extração de credenciais em scripts

Lock File Checker

Valida a integridade do lock file do módulo para detecção de adulteração.

Detecta:

Incompatibilidades de hash SHA-256 entre conteúdo travado e real
Entradas órfãs (módulos travados que não estão mais na árvore de dependências)
Entradas ausentes (dependências ainda não travadas)
Entradas ambíguas e problemas de formato de versão

Symlink Checker

Percorre diretórios de módulos verificando ataques de escape via symlinks.

Detecta:

Symlinks apontando para fora do limite do módulo
Cadeias de symlinks (symlink → symlink)
Symlinks pendentes (alvo não existe)

Module Metadata Checker

Analisa cadeias de dependências e metadados de módulos em busca de riscos na cadeia de suprimentos.

Detecta:

Typosquatting: Nomes de módulos similares a módulos populares (distância de Levenshtein)
Fan-out: Módulos com quantidade excessiva de dependências
Versões não fixadas: Dependências sem versões fixadas
Deps transitivas não declaradas: Dependências requeridas por sub-dependências mas não declaradas no invowkmod.cue raiz
Confiança em módulos globais: Módulos de ~/.invowk/cmds/ que contornam a revisão local

Detecção de Ameaças Compostas

O correlacionador identifica quando achados de diferentes checkers aparecem na mesma superfície de ataque, indicando ameaças coordenadas:

Ameaça Composta	Checkers Envolvidos	Severidade
Exfiltração de credenciais	Env + Network	Crítica
Escape path + symlink	Script + Symlink	Crítica
Exfiltração ofuscada	Script + Network	Crítica
Fraqueza na cadeia de confiança	Module Metadata + Lock File	Alta

Escalação automática de severidade:

3+ categorias distintas na mesma superfície → Crítica
Alta + qualquer outro achado na mesma superfície → Crítica
2+ achados Médios na mesma superfície → Alta

Níveis de Severidade

Nível	Significado
`critical`	Ação imediata necessária; provável exploit ativo ou ataque coordenado
`high`	Risco sério; deve ser resolvido antes de usar o módulo
`medium`	Preocupação notável; justifica investigação
`low`	Problema menor; considere resolver
`info`	Observação informativa; normalmente nenhuma ação necessária

Use --severity para filtrar o nível mínimo exibido:

# Apenas achados críticos e altos
invowk audit --severity high

# Tudo incluindo informativos
invowk audit --severity info

Flags

Flag	Padrão	Descrição
`--format`	`text`	Formato de saída: `text` ou `json`
`--severity`	`low`	Severidade mínima: `info`, `low`, `medium`, `high`, `critical`
`--include-global`	`false`	Incluir `~/.invowk/cmds/` no scan

Códigos de Saída

Código	Significado
`0`	Nenhum achado no ou acima do limiar de severidade
`1`	Achados detectados
`2`	Erro de scan

Análise com LLM

Para análise semântica mais profunda além da correspondência de padrões, habilite a auditoria com LLM usando a flag --llm. Isso envia conteúdo de scripts para um LLM local ou remoto através de qualquer API compatível com OpenAI.

Por que análise com LLM?

Os checkers integrados usam padrões regex — são rápidos e determinísticos mas só detectam padrões conhecidos. A análise com LLM raciocina sobre a intenção do código, detectando vetores de ataque inéditos, falhas lógicas sutis e problemas de segurança dependentes de contexto que regex não consegue expressar.

Configuração

O checker LLM funciona com qualquer servidor que implemente a API OpenAI /v1/chat/completions. A configuração padrão usa o Ollama, o servidor LLM local mais popular:

# 1. Instalar Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 2. Baixar um modelo focado em código
ollama pull qwen2.5-coder:7b

# 3. Executar a auditoria com análise LLM
invowk audit --llm

Servidores Compatíveis

Servidor	URL Padrão	Notas
Ollama	`http://localhost:11434/v1`	Alvo padrão, melhor experiência local
LM Studio	`http://localhost:1234/v1`	Interface gráfica, bom navegador de modelos
llamafile	`http://localhost:8080/v1`	Executável único, instalação zero
vLLM	`http://localhost:8000/v1`	Produção, otimizado para GPU
OpenAI	`https://api.openai.com/v1`	Nuvem, requer chave de API

Flags do LLM

Flag	Padrão	Variável de Ambiente	Descrição
`--llm`	`false`	—	Habilitar análise com LLM
`--llm-url`	`http://localhost:11434/v1`	`INVOWK_LLM_URL`	URL base da API
`--llm-model`	`qwen2.5-coder:7b`	`INVOWK_LLM_MODEL`	Nome do modelo
`--llm-api-key`	(vazio)	`INVOWK_LLM_API_KEY`	Chave de API (vazio para servidores locais)
`--llm-timeout`	`2m`	`INVOWK_LLM_TIMEOUT`	Timeout por requisição
`--llm-concurrency`	`2`	`INVOWK_LLM_CONCURRENCY`	Máximo de requisições LLM paralelas

Modelos Recomendados

Modelo	RAM	Qualidade	Notas
`qwen2.5-coder:7b`	8 GB	Boa	Padrão, cabe na maioria das máquinas
`qwen2.5-coder:14b`	16 GB	Melhor	Bom equilíbrio
`qwen2.5-coder:32b`	24 GB	Excelente	Nível GPT-4o para código
`deepseek-coder:33b`	24 GB	Excelente	Melhor para raciocínio chain-of-thought

Auto-Detecção de Modelo

Quando --llm está habilitado, o invowk verifica se o modelo configurado está disponível no servidor antes de escanear. Se o modelo não for encontrado, ele mostra:

A lista de modelos disponíveis no servidor
Uma sugestão do melhor modelo focado em código (detectado dinamicamente por correspondência de padrões)

$ invowk audit --llm --llm-model modelo-inexistente
LLM model not found: "modelo-inexistente" is not available on the server; try: qwen2.5-coder:14b
available models: llama3:8b, qwen2.5-coder:14b, mistral:7b

A detecção reconhece famílias de modelos focados em código (qwen2.5-coder, deepseek-coder, codellama, codegemma, starcoder, codestral) independente da versão ou variante de quantização.

Exemplos

# Auto-detect best available provider (local Ollama first, then cloud)
invowk audit --llm-provider auto

# Use a specific provider (works with OAuth — no API key needed)
invowk audit --llm-provider claude
invowk audit --llm-provider codex
invowk audit --llm-provider gemini

# Override model within a provider
invowk audit --llm-provider claude --llm-model claude-opus-4-6

# Manual configuration (Ollama, LM Studio, or any OpenAI-compatible server)
invowk audit --llm
invowk audit --llm --llm-url http://localhost:1234/v1

# Combined: provider + high severity + JSON
invowk audit --llm-provider auto --severity high --format json

Como Funciona

O checker LLM:

Verifica se o modelo configurado existe no servidor (com sugestões se não)
Filtra scripts: exclui referências somente-arquivo e scripts vazios
Agrupa scripts por contagem de caracteres (~6000 chars) e quantidade (máx 5 por lote)
Envia cada lote ao LLM com um prompt de sistema de analista de segurança
Parseia achados JSON estruturados da resposta
Valida severidade e categoria contra enums existentes (defesa contra alucinação)
Integra achados no mesmo pipeline dos checkers integrados

Achados do LLM participam da detecção de ameaças compostas — se o LLM identifica um padrão de exfiltração e um checker integrado identifica acesso a variáveis sensíveis no mesmo módulo, o correlacionador escala para Crítica.

O conteúdo dos scripts é enviado ao servidor configurado

Quando --llm está habilitado, o conteúdo dos scripts dos seus invowkfiles e módulos é enviado ao endpoint de API configurado. Para servidores locais (Ollama, LM Studio), os dados permanecem na sua máquina. Para APIs em nuvem, revise as políticas de tratamento de dados do seu provedor.

Integração com CI

Gate Básico de CI

# Falhar pipeline se houver achados altos/críticos
invowk audit --severity high

Saída JSON para Automação

# Full JSON output
invowk audit --format json

# Parse findings count
invowk audit --format json | jq '.summary.total'

# List finding titles
invowk audit --format json | jq '.findings[] | "[(.severity)] (.title)"'

# Check for compound threats
invowk audit --format json | jq '.compound_threats'

Exemplo com GitHub Actions

- name: Auditoria de segurança
  run: |
    invowk audit --severity high --format json > audit-results.json
    if [ $? -eq 1 ]; then
      echo "::error::Achados de segurança detectados"
      cat audit-results.json | jq '.findings[] | "[\(.severity)] \(.title)"'
      exit 1
    fi

Com LLM no CI

- name: Iniciar Ollama
  run: |
    curl -fsSL https://ollama.com/install.sh | sh
    ollama pull qwen2.5-coder:7b &
    wait

- name: Auditoria de segurança (com LLM)
  run: invowk audit --llm --severity high --format json

Início Rápido​

Como Funciona​

Alvos de Scan​

Checkers Integrados​

Script Checker​

Network Checker​

Environment Checker​

Lock File Checker​

Symlink Checker​

Module Metadata Checker​

Detecção de Ameaças Compostas​

Níveis de Severidade​

Flags​

Códigos de Saída​

Análise com LLM​

Configuração​

Servidores Compatíveis​

Flags do LLM​

Modelos Recomendados​

Auto-Detecção de Modelo​

Exemplos​

Como Funciona​

Integração com CI​

Gate Básico de CI​

Saída JSON para Automação​

Exemplo com GitHub Actions​

Com LLM no CI​

Início Rápido

Como Funciona

Alvos de Scan

Checkers Integrados

Script Checker

Network Checker

Environment Checker

Lock File Checker

Symlink Checker

Module Metadata Checker

Detecção de Ameaças Compostas

Níveis de Severidade

Flags

Códigos de Saída

Análise com LLM

Configuração

Servidores Compatíveis

Flags do LLM

Modelos Recomendados

Auto-Detecção de Modelo

Exemplos

Como Funciona

Integração com CI

Gate Básico de CI

Saída JSON para Automação

Exemplo com GitHub Actions

Com LLM no CI