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):
- bind com a conta de serviço (
bind_dn+ senha cifrada); - busca do usuário com o filtro configurado (
{username}é escapado comescape_filter_chars). Mais de um resultado é tratado como erro; - bind com o DN do usuário e a senha digitada (valida a senha);
- leitura de grupos (
memberOf). No AD, comnested_groups, os grupos aninhados vêm demember:1.2.840.113556.1.4.1941:=(LDAP_MATCHING_RULE_IN_CHAIN); - mapeamento grupo → papel (e tenant opcional) e, sem nenhum grupo mapeado, o
default_role_id. Os papéis de origemdirectorysão ressincronizados a cada login; - 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
Principalcalcula, 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çalhoX-Setup-Token, comparado em tempo constante. Dez falhas em 15 minutos bloqueiam o IP (oX-Real-IPdefinido 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_USERNAMEenquanto houver um superadministrador ativo. - Certificado enviado pela GUI: validado com
cryptography(correspondência chave/certificado, validade, RSA ≥ 2048, SAN) e gravado no volumequantix-tls, montado com escrita apenas naapie somente leitura noweb. 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_approvalcriam execuçõespending_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.approveeautomation.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/denyemdefault.conf).- O refresh token fica só no cookie
HttpOnly; SameSite=Strict; a SPA não o guarda emlocalStorage.
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 upgradejá 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.