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 7 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 (7 integrados + LLM opcional)
  │   ├── Script Checker ──► achados de execução, travessia, ofuscação
  │   ├── Lua Checker ──► achados de execução, env e caminhos em virtual-lua
  │   ├── Network Checker ──► achados de execução e 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)

Lua Checker

Analisa scripts virtual-lua e configuração de runtime em busca de acesso ao host e uso indevido da ponte.

Detecta:

Referências a APIs Lua desabilitadas (os.execute, io.popen, package.loadlib, debug e helpers de carregamento direto de arquivos)
Leituras de ambiente sensível via os.getenv() ou pela ponte de ambiente Lua do Invowk
Entradas wildcard ou capazes de rede em allowed_binaries que permitem ao Lua invocar comandos amplos do host
Acesso completo ao sistema de arquivos virtual ou mapeamentos de caminhos amplos expostos às APIs de arquivo Lua

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, 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 e defaults não definidos de env_inherit_mode nos runtimes native/virtual-sh (ambos expõem 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)
Qualquer symlink em diretório de módulo, porque pacotes de módulo devem ser autocontidos
Alvos de symlink ilegíveis e caminhadas de diretório incompletas que deixam o scan com cobertura reduzida

Module Metadata Checker

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

Detecta:

Typosquatting: IDs de módulos similares a outro ID de módulo no scan atual (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
Módulos vendorizados ausentes de requires: Dependências presentes em invowk_modules/ sem uma declaração correspondente
Falhas de parsing do invowkfile do módulo: Arquivos de comando de módulo malformados que impedem auditoria do conteúdo de scripts
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 combinações específicas na mesma superfície de ataque. Quatro regras combinam checkers diferentes; a travessia de interpretador combina duas categorias do próprio checker de Script:

Ameaça Composta	Achados Obrigatórios	Severidade
Exfiltração de credenciais	Checker de Env + checker de Network	Crítica
Escape path + symlink	Checker de Script + checker de Symlink	Crítica
Exfiltração ofuscada	Script/`obfuscation` + Network/`exfiltration`	Crítica
Fraqueza na cadeia de confiança	Um código de confiança do grafo de dependências de Module Metadata + um código de integridade ausente, obsoleto ou divergente de Lock File	Alta
Travessia de interpretador	Script/`execution` + Script/`path-traversal`	Crítica

A regra de cadeia de confiança aceita apenas os códigos de metadados para fan-out amplo, dependências transitivas não declaradas ou módulos vendorizados ausentes de requires. No lado do lock file, aceita os códigos definidos para lock ausente, v1 legado, entrada ausente, módulo vendorizado não verificável ou divergência de content hash; achados não relacionados desses checkers não ativam a regra.

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 confirmado no ou acima do limiar de severidade; relatórios apenas com achados suprimidos saem com sucesso
`1`	Achados confirmados detectados; erros genéricos de validação de argumentos da CLI também usam o status 1 padrão do Cobra
`2`	Erro de scan de auditoria ou configuração

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 --llm-provider ou --llm. Isso envia conteúdo de scripts para uma ferramenta CLI local ou para uma API local/remota compatível com OpenAI. invowk audit sem flags nunca usa a configuração LLM global por conta própria; passe --llm para optar por um backend configurado.

:::info 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 com backend de API funciona com servidores compatíveis com OpenAI que oferecem chat completions e listagem de modelos. O Invowk sempre verifica o modelo configurado de um backend HTTP/API pelo endpoint /models antes de escanear; uma falha de listagem ou verificação encerra a auditoria com status 2. Provedores CLI de Claude, Codex e Gemini delegam o tratamento do modelo à ferramenta CLI. A configuração de API padrão usa o Ollama, o servidor LLM local mais popular:

# 1. Instalar Ollama com seu gerenciador de pacotes ou por https://ollama.com

# 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

Você pode configurar um backend global:

invowk config set llm.provider codex
invowk audit --llm

Veja Opções de Configuração para config de provider e API, incluindo llm.api.api_key_env para credenciais sem segredo bruto no arquivo.

Detecção de Provedor

Use --llm-provider para conectar o invowk por ferramentas locais ou credenciais de API em variáveis de ambiente:

# Auto-detectar: Ollama, APIs via env var, depois ferramentas CLI
invowk audit --llm-provider auto

# Provedores CLI usam o modelo padrão atual da ferramenta quando --llm-model é omitido
invowk audit --llm-provider claude
invowk audit --llm-provider codex
invowk audit --llm-provider gemini

# Override explícito de modelo para um provedor CLI
invowk audit --llm-provider codex --llm-model MODEL_NAME

# APIs cloud via env var exigem modelo explícito
OPENAI_API_KEY=sk-... invowk audit --llm-provider codex --llm-model MODEL_NAME

Quando ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY ou GOOGLE_API_KEY seleciona um provedor de API cloud, --llm-model é obrigatório. Provedores baseados em CLI delegam para os padrões do Claude Code, Codex CLI ou Gemini CLI, a menos que você passe --llm-model.

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-provider`	(vazio)	—	Auto-detectar ou usar `auto`, `claude`, `codex`, `gemini` ou `ollama`
`--llm`	`false`	—	Habilitar análise com LLM usando configuração ou API
`--llm-url`	`http://localhost:11434/v1`	`INVOWK_LLM_URL`	URL base da API
`--llm-model`	`qwen2.5-coder:7b` para API/Ollama; padrão da ferramenta para provedores CLI	`INVOWK_LLM_MODEL`	Nome do modelo; obrigatório para provedores de API cloud via env var
`--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

Para todo backend HTTP/API selecionado, o Invowk lista os modelos e verifica o modelo configurado antes de escanear. Se o endpoint falhar, a auditoria termina com status 2. Se o modelo não for encontrado, o Invowk 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 nonexistent-model
LLM model not found: "nonexistent-model" 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

# Configure once, then opt in per audit run
invowk config set llm.provider codex
invowk audit --llm

# Auto-detect best available provider (local Ollama, cloud env vars, then CLI tools)
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 pelo endpoint obrigatório de listagem se um backend HTTP/API possui o modelo configurado (com sugestões se não); provedores CLI delegam o tratamento do modelo à sua ferramenta
Resolve conteúdo de scripts inline e baseados em arquivo, depois filtra 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
Rejeita campos de achado malformados, como valores desconhecidos de severidade/categoria, em vez de tratar silenciosamente uma resposta ruim do LLM como limpa
Integra achados válidos no mesmo pipeline dos checkers integrados

Quando a análise LLM é solicitada explicitamente, falhas do checker LLM são erros fatais de varredura. Por exemplo, campos de achado LLM malformados, como valores desconhecidos de severidade ou categoria, fazem a auditoria falhar com código de saída 2 em vez de cair para resultados determinísticos parciais.

Achados do LLM participam da detecção de ameaças compostas pelo mesmo pipeline de correlação dos achados integrados. Eles podem contribuir para resultados Críticos quando uma regra nomeada também corresponde (por exemplo, acesso a variáveis de ambiente sensíveis junto com acesso de rede) ou quando condições genéricas de escalonamento são atendidas, como um achado de alta severidade junto com qualquer outro achado ou três categorias distintas na mesma superfície.

:::caution O conteúdo dos scripts é enviado ao backend LLM selecionado Tanto --llm quanto --llm-provider habilitam a análise do conteúdo dos scripts dos seus invowkfiles e módulos. Backends de API o recebem por HTTP; provedores CLI de Claude, Codex e Gemini o recebem pelo subprocesso da ferramenta selecionada e podem encaminhá-lo conforme o comportamento dessa ferramenta. Servidores de API locais mantêm o payload HTTP na sua máquina. Para APIs em nuvem e provedores CLI, revise as políticas de tratamento de dados do provedor e da ferramenta. :::

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

# Capture JSON output without masking audit's exit code 1 for findings
set +e
invowk audit --format json > audit-results.json
status=$?
set -e

# Parse findings count
jq '.summary.total' audit-results.json

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

# Check for compound threats
jq '.compound_threats' audit-results.json

exit "$status"

O DTO JSON inclui:

Campo	Descrição
`findings[]`	Achados confirmados no limiar de severidade ou acima dele
`compound_threats[]`	Achados confirmados do correlacionador no limiar de severidade ou acima dele
`suppressed_findings[]`	Achados suprimidos por regras de triagem
`suppressed_compound_threats[]`	Achados do correlacionador suprimidos
`diagnostics[]`	Diagnósticos do scanner que não são achados
`summary.total`	Contagem de achados e ameaças compostas confirmados no limiar de severidade ou acima dele
`summary.suppressed`	Contagem de achados suprimidos e ameaças compostas suprimidas no limiar de severidade ou acima dele
`summary.critical` / `high` / `medium` / `low` / `info`	Contagens de achados confirmados por severidade
`summary.modules_scanned`	Número de módulos verificados
`summary.invowkfiles_scanned`	Número de invowkfiles verificados
`summary.scripts_scanned`	Número de corpos de script verificados
`summary.duration_ms`	Duração do scan em milissegundos

Cada achado inclui code, severity, category, checker_name, title, description e recommendation, além de surface_id, surface_kind, file_path/line e campos de proveniência de escalação opcionais. Valores válidos de surface_kind são root_invowkfile, local_module, vendored_module e global_module.

Cada achado suprimido ou ameaça composta suprimida envolve a entrada original como finding e inclui os campos disposition, rule e rationale, que explicam por que a triagem a suprimiu.

Exemplo com GitHub Actions

- name: Auditoria de segurança
  run: |
    set +e
    invowk audit --severity high --format json > audit-results.json
    status=$?
    set -e

    if [ "$status" -eq 1 ]; then
      echo "::error::Achados de segurança detectados"
      jq -r '(.findings[]?, .compound_threats[]?) | "[\(.severity)] \(.title)"' audit-results.json
      exit 1
    elif [ "$status" -ne 0 ]; then
      cat audit-results.json
      exit "$status"
    fi

Com LLM no CI

- name: Iniciar Ollama
  run: |
    # Use uma imagem de runner ou etapa de setup que instale o Ollama explicitamente.
    ollama serve > ollama.log 2>&1 &
    sleep 2
    ollama pull qwen2.5-coder:7b

- 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​

Lua 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​

Detecção de Provedor​

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

Lua 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

Detecção de Provedor

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