Pular para conteúdo

Segurança

Autenticação

Mecanismo Detalhes (código: api/security.py, api/routers/auth.py)
Sessão JWT POST /api/v1/auth/login emite um access token HS256 com validade security.session_minutes (30 min, configurável na GUI) e um refresh token com QV_JWT_REFRESH_DAYS (7 dias). O refresh também é gravado no cookie qv_refresh (HttpOnly, SameSite=Strict, Secure em HTTPS, path=/api/v1/auth). Segredo de assinatura: QV_JWT_SECRET ou <data_dir>/jwt.secret gerado no primeiro boot
Tokens de API Authorization: Bearer qv_…, criados em Perfil › Tokens de API com validade de 30, 90 ou 365 dias ou sem expiração. Só o hash HMAC-SHA256 (chave mestra) é armazenado, e o token é mostrado uma única vez. Herda as permissões do usuário. Registra last_used
Tokens de coletor cabeçalho X-Collector-Token: qvc_…, também armazenado como hash. Válido apenas para os endpoints /api/v1/collector/* e /api/v1/ingest/*
Senhas locais Argon2 (argon2-cffi). Tamanho mínimo security.password_min_length (12). Troca obrigatória no primeiro login quando a senha foi gerada
Bloqueio após security.lockout_attempts (5) falhas, a conta fica bloqueada por security.lockout_minutes (15) e a API responde HTTP 423. Desbloqueio manual em Usuários ou com quantix reset-admin
Base local desligável com security.local_auth_enabled = false, só diretórios autenticam, exceto superadministradores locais (para não perder o acesso)

Diretórios (LDAP / Active Directory / FreeIPA)

Fluxo (api/ldap_auth.py):

  1. bind com a conta de serviço (bind_dn + senha cifrada);
  2. busca do usuário com o filtro configurado ({username} é escapado com escape_filter_chars). Mais de um resultado é tratado como erro;
  3. bind com o DN do usuário e a senha digitada (valida a senha);
  4. leitura de grupos (memberOf). No AD, com nested_groups, os grupos aninhados vêm de member:1.2.840.113556.1.4.1941:= (LDAP_MATCHING_RULE_IN_CHAIN);
  5. mapeamento grupo → papel (e tenant opcional) e, sem nenhum grupo mapeado, o default_role_id. Os papéis de origem directory são ressincronizados a cada login;
  6. provisionamento automático no primeiro login (auto_provision).

Segurança do transporte: ldaps (padrão, 636), starttls ou none. Com verify_tls, o certificado é validado (CA própria aceita em PEM no campo ca_cert). Vários servidores com failover em ordem; vários diretórios por prioridade. Exemplos em Diretórios.

Autorização (RBAC por tenant)

  • Permissões granulares (view, devices.manage, automation.approve…) agrupadas em papéis (lista). Os quatro papéis padrão (Administrador, Operador, Analista, Visualizador) são recriados no boot e não podem ser alterados nem excluídos.
  • Um papel é atribuído a um usuário globalmente (tenant vazio) ou restrito a um tenant. O Principal calcula, por permissão, a lista de tenants visíveis (None = todos).
  • Superadministrador (is_superadmin) tem acesso irrestrito. Somente superadministradores criam outros superadministradores, e a plataforma mantém pelo menos um ativo.
  • O escopo de tenant é aplicado nas listagens e consultas de inventário, métricas, achados, previsões, mudanças, dispositivos e nas ferramentas da IA. Veja as ressalvas em Multi-tenant.

Cifragem de segredos

Segredo Armazenamento
credenciais de dispositivos, senha de bind LDAP, segredos de canais de alerta (URLs de webhook Teams/Slack, cabeçalho Authorization, usuário/senha ServiceNow), variáveis do tipo secret (ai.api_key, notifications.smtp_password) Fernet (AES-128-CBC + HMAC-SHA256) com a chave mestra
tokens de API e de coletor HMAC-SHA256 com a chave mestra (apenas lookup, irreversível)
senhas de usuários locais Argon2

A chave mestra vem de QV_MASTER_KEY (gerada pelo make gen-env/Ansible/Helm) ou, se vazia, é gerada no primeiro boot em <QV_DATA_DIR>/master.key (0600).

Guarde a chave mestra fora do servidor

Sem a mesma chave, as credenciais cadastradas não podem ser decifradas (“chave mestra diferente”). O backup não inclui o .env. Trocar a chave depois da instalação inutiliza os segredos e invalida os tokens de API e de coletor.

Primeira execução e certificado

  • Token de instalação (QV_SETUP_TOKEN, qvs_ + 40 caracteres aleatórios): gerado pelo instalador no .env (0600). Enquanto a configuração inicial estiver pendente, as rotas /api/v1/setup/* exigem esse token no cabeçalho X-Setup-Token, comparado em tempo constante. Dez falhas em 15 minutos bloqueiam o IP (o X-Real-IP definido pelo nginx) por 15 minutos. O status público só informa quais etapas foram feitas; os detalhes exigem o token. Depois da conclusão, todas as rotas respondem 410, e o token deixa de ter efeito. O link entregue usa o fragmento (#token=), que não é enviado ao servidor nem aparece em logs de acesso.
  • Sem administrador pré-definido, ninguém consegue entrar antes da conclusão do assistente: a plataforma não cria conta com senha padrão. Depois da conclusão, o boot não recria o usuário QV_ADMIN_USERNAME enquanto houver um superadministrador ativo.
  • Certificado enviado pela GUI: validado com cryptography (correspondência chave/certificado, validade, RSA ≥ 2048, SAN) e gravado no volume quantix-tls, montado com escrita apenas na api e somente leitura no web. A chave é regravada sem senha (PKCS#8) porque o nginx precisa lê-la na inicialização. O volume entra no backup (quantix-tls.tgz).

Auditoria

Toda alteração administrativa grava em audit_log: usuário, ação, tipo e ID do objeto, detalhe JSON (sem segredos) e IP (X-Forwarded-For, definido pelo nginx). Também são auditados logins, falhas de login (com motivo e indicação de bloqueio), troca de senha, criação de token de API, atualização de achados, solicitações/aprovações/rejeições de automação e, com security.audit_reads, perguntas à IA. Retenção: retention.audit_days (730). A lista de ações está em Auditoria.

Segregação de funções na automação

  • Runbooks marcados com requires_approval criam execuções pending_approval.
  • O solicitante não pode aprovar a própria execução (HTTP 403), exceto superadministradores.
  • Runbooks de risco alto sempre exigem aprovação: a API recusa desativar a exigência.
  • Execuções disparadas por regras de alerta são registradas com requested_by = regra:<nome> e seguem a mesma exigência de aprovação.
  • Permissões separadas: automation.request, automation.approve e automation.manage.

Endurecimento da aplicação e dos containers

Camada Medida
nginx (frontend/nginx/security-headers.conf) CSP default-src 'self' com script-src 'self' + hash do script de tema, frame-ancestors 'none', object-src 'none'; HSTS (1 ano); X-Frame-Options DENY; nosniff; Referrer-Policy same-origin; Permissions-Policy restritiva; COOP/CORP same-origin
API X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Cache-Control: no-store; CORS sem origens externas; ValueError → HTTP 400 sem stack trace
SQL SQLAlchemy com parâmetros; no ClickHouse, tipos e métricas validados contra o catálogo e valores parametrizados
Containers de backend usuário não-root (UID 10001), read_only, cap_drop: ALL, no-new-privileges, tmpfs para /tmp, tini como PID 1
Rede (compose) bancos e barramento na rede internal (internal: true, sem rota externa); só o web publica portas
Kubernetes runAsNonRoot, readOnlyRootFilesystem, seccompProfile: RuntimeDefault, NetworkPolicy, Secret com helm.sh/resource-policy: keep
Documentação (/docs/) gerada sem scripts inline nem recursos externos (fontes do sistema, Mermaid local), compatível com a mesma CSP

Desde a 5.3.s

  • /metrics (Prometheus) só responde a redes privadas (allow/deny em default.conf).
  • O refresh token fica só no cookie HttpOnly; SameSite=Strict; a SPA não o guarda em localStorage.

Relatório de segurança 5.3.s

Revisão feita em outubro de 2026 sobre o código da 5.3.0. Referências: OWASP Top 10 2021, OWASP API Security Top 10 2023, OWASP ASVS 4.0 e CWE. Bases de vulnerabilidades: PyPI Advisory Database / OSV, GitHub Advisory Database, NVD, Debian Security Tracker e Alpine SecDB.

Método

Etapa Ferramenta / referência
Revisão manual do código (API, autenticação, RBAC, automação, coletor, integrações) OWASP ASVS 4.0, OWASP API Top 10
Análise estática do Python Bandit
Dependências do frontend npm audit (GitHub Advisory Database)
Dependências Python e pacotes das imagens Trivy 0.58 (NVD, GHSA, Debian, Alpine)
Runbooks Ansible ansible-playbook --syntax-check e testes com cargas maliciosas
Regressão 321 testes automatizados (unitários, plugins e integração com PostgreSQL, ClickHouse embutido e NATS)

Achados da revisão de código

Severidade Achado Referência Correção
Crítica Permissão de um tenant valia como permissão global na administração (usuários, papéis, configurações); quem administrava usuários podia se conceder acesso total A01, API5 · CWE-269, CWE-285 permissão global obrigatória; regras anti-escalonamento
Crítica Parâmetros de runbook e nomes vindos dos equipamentos eram interpretados como template pelo Ansible no worker de automação A03 · CWE-94, CWE-1336 parâmetros por lista branca; variáveis !unsafe; validação de host e usuário
Alta Token de coletor permitia obter dados de dispositivos de outros coletores e enviar métricas em nome deles API1 · CWE-639 dono do dispositivo verificado em status e ingestão
Alta Teste de conexão pelo servidor da API e destinos de integração alcançavam serviços internos e metadados de nuvem A10 · CWE-918 validação de destino (anti-SSRF); teste pelo servidor só para superadmin
Alta Credenciais e coletores de outro tenant podiam ser vinculados a um dispositivo API1 · CWE-639 checagem de tenant
Alta Tokens continuavam válidos após troca de senha, desativação ou logout A07 · CWE-613 token_version no JWT
Média Assistente de IA, aplicações e achados mostravam dados de outros tenants API1 · CWE-639 filtros por tenant
Média Segredo salvo era reenviado ao trocar o destino de canal, diretório ou integração CWE-522 troca de destino exige o segredo de novo
Média Refresh token em localStorage; access token aceito por cookie A07 · CWE-922 cookie HttpOnly; SameSite=Strict
Média Sem limite de taxa no login; tempo e mensagem revelavam contas existentes e bloqueadas A07 · CWE-307, CWE-204, CWE-208 10/min por IP; tempo constante; mensagem única
Média XML externo sem proteção (IBM Spectrum Virtualize); descompressão sem limite A05 · CWE-611, CWE-409 defusedxml; limite de 512 MiB
Média Falha do StartTLS seguia para o bind com a senha em claro CWE-319 conexão interrompida
Baixa Erros do provedor de IA e de canais exibidos ao usuário CWE-209 detalhe só no log
Baixa Expressão regular de regras de aplicação sem tempo limite CWE-1333 statement_timeout de 5 s
Baixa Restauração aceitava backup sem impressão digital da chave mestra CWE-345 recusado
Baixa Validação de destino deixava passar IP literal (exceção engolida) e IPv4 mapeado em IPv6 CWE-918 corrigido, com testes
Baixa /metrics aberto A05 · CWE-200 só redes privadas

Dependências e imagens (HIGH + CRITICAL)

Componente 5.3.0 5.3.s Observação
Frontend (npm audit) 9 pacotes (4 altas) 0 react-router, vite, echarts, esbuild, eslint
Imagem web (nginx/Alpine) 58 0 nginx 1.29 + apk upgrade (sem achados de qualquer severidade)
Bibliotecas Python 7 (1 crítica) 0 python-jose → PyJWT; msgpack, urllib3, setuptools; pip retirado da imagem
Pacotes Debian da imagem backend 78 (3 críticas) 54 (1 crítica) Debian 12 → 13; as 54 restantes não têm correção publicada pelo Debian
Bandit (alta) 3 0 MD5 marcado usedforsecurity=False; XML com defusedxml

Risco residual

  • As 54 vulnerabilidades restantes do sistema operacional da imagem backend estão marcadas como “affected” (sem versão corrigida) no Debian Security Tracker: util-linux, openssh-client, curl, systemd, ncurses, acl e perl. A mais grave, no openssh-client, afeta conexões SSH de saída usadas pelos runbooks; a imagem roda sem privilégios, sem shell interativo e com sistema de arquivos somente leitura. Reconstrua a imagem quando o Debian publicar as correções (apt-get upgrade já faz parte do build).
  • Os 20 avisos B608 do Bandit (SQL montado com texto) foram revisados: os valores são parâmetros e só identificadores internos validados entram no texto. B104 (escuta em 0.0.0.0) é esperado dentro do container.
  • Mapeamento de grupos LDAP aceita o nome curto do grupo (CN). Em diretórios onde usuários comuns criam grupos, use o DN completo no mapeamento.