ThiagoSoares
Voltar para o blog
DevSecOps•10 min•

SonarQube no Ubuntu: analisando qualidade e segurança do código

O que é o SonarQube, seus principais recursos e como executar a primeira análise de um projeto no Ubuntu.

Compartilhar artigo

WhatsAppTelegramFacebookXLinkedIn

O SonarQube é uma plataforma de análise estática de código. Ele lê o projeto sem precisar executar todas as suas funcionalidades e procura problemas relacionados a segurança, confiabilidade e manutenibilidade.

Na prática, gosto de pensar nele como uma revisão automatizada e repetível. Ele não substitui testes nem revisão humana, mas encontra padrões que facilmente passam despercebidos em uma pull request grande.

Neste artigo vou subir o SonarQube Community Build localmente com Docker no Ubuntu e analisar um projeto JavaScript ou TypeScript.

O que o SonarQube observa?

A análise gera issues e métricas sobre diferentes aspectos do projeto:

  • possíveis bugs e comportamentos pouco confiáveis;
  • vulnerabilidades e práticas inseguras;
  • Security Hotspots que precisam de revisão humana;
  • código duplicado;
  • complexidade ciclomática e cognitiva;
  • cobertura de testes importada de ferramentas externas;
  • tamanho e evolução da base de código;
  • dívida técnica e problemas de manutenção.

Uma issue não significa automaticamente que existe um bug real. O valor da ferramenta está em tornar o risco visível para que alguém decida se deve corrigir, aceitar ou ajustar a regra.

Recursos que mais uso

Quality Profiles

O Quality Profile é o conjunto de regras usado para analisar uma linguagem. O perfil padrão, chamado Sonar way, é um bom ponto de partida.

É possível ativar ou desativar regras, mas prefiro começar com o padrão e alterar apenas quando existe uma justificativa da equipe. Desligar regras só para deixar o painel verde esconde o problema em vez de resolvê-lo.

Quality Gates

O Quality Gate responde uma pergunta simples: este código está pronto para seguir adiante?

Ele avalia condições como novos problemas, cobertura, duplicação e revisão de Security Hotspots. O resultado final é aprovado ou reprovado e pode bloquear uma pipeline.

O Quality Gate padrão prioriza código novo. Isso é útil em sistemas antigos porque permite melhorar a qualidade aos poucos, sem exigir que toda a dívida técnica seja resolvida antes da primeira integração.

Security Hotspots

Um Security Hotspot marca um trecho sensível, como uso de criptografia, autenticação, cookies ou expressões regulares. Ele não afirma que o código está vulnerável: pede que alguém revise o contexto.

Depois da análise, o hotspot pode ser classificado como seguro, corrigido, reconhecido ou ainda pendente de revisão.

Integração com cobertura

O SonarQube não executa os testes. Jest, Vitest, JaCoCo e outras ferramentas geram o relatório de cobertura, e o scanner envia esses dados ao servidor.

Para projetos JavaScript e TypeScript, normalmente gero um arquivo LCOV:

code
npm test -- --coverage

Depois informo o arquivo coverage/lcov.info na configuração do projeto.

Preparando o Ubuntu

Para este ambiente local, precisamos de Docker e de um projeto com Node.js. Confirme se ambos estão disponíveis:

code
docker --version
node -v
npm -v

Se o Docker ainda não estiver instalado, use a instalação oficial do Docker Engine para Ubuntu. Evito copiar scripts aleatórios porque o repositório oficial recebe atualizações de segurança e facilita a manutenção.

Executando o SonarQube com Docker

Crie volumes para não perder dados, extensões e logs ao recriar o container:

code
docker volume create sonarqube_data
docker volume create sonarqube_extensions
docker volume create sonarqube_logs

Agora inicie o Community Build:

code
docker run -d \
  --name sonarqube \
  -p 9000:9000 \
  -e SONAR_ES_BOOTSTRAP_CHECKS_DISABLE=true \
  -v sonarqube_data:/opt/sonarqube/data \
  -v sonarqube_extensions:/opt/sonarqube/extensions \
  -v sonarqube_logs:/opt/sonarqube/logs \
  sonarqube:community

A variável SONAR_ES_BOOTSTRAP_CHECKS_DISABLE simplifica este laboratório local. Ela não é uma configuração indicada para produção.

Veja o andamento da inicialização:

code
docker logs -f sonarqube

Quando o servidor estiver pronto, abra http://localhost:9000. O primeiro acesso usa:

code
usuário: admin
senha: admin

O SonarQube solicitará uma nova senha imediatamente.

Para parar e iniciar o ambiente depois:

code
docker stop sonarqube
docker start sonarqube

Por que isso ainda não é uma instalação de produção?

O container único é ótimo para estudo, mas uma instalação compartilhada precisa de mais cuidado:

  • PostgreSQL externo e com backup;
  • volumes persistentes bem definidos;
  • limites de memória e parâmetros do kernel;
  • HTTPS por meio de proxy reverso;
  • autenticação e permissões;
  • atualização planejada e observabilidade.

Para aprender e testar a análise local, o container isolado é suficiente.

Criando o projeto e o token

No painel do SonarQube:

  1. escolha Create Project → Local Project;
  2. informe um nome e uma chave única;
  3. mantenha o Quality Gate padrão;
  4. gere um token para a análise.

O token funciona como senha. Não coloque seu valor em sonar-project.properties, no Git ou em uma imagem Docker.

No terminal, deixe-o apenas na sessão atual:

code
export SONAR_TOKEN="cole-o-token-aqui"

Configurando um projeto TypeScript

Na raiz do projeto, crie sonar-project.properties:

code
sonar.projectKey=minha-api
sonar.projectName=Minha API
sonar.sources=src
sonar.tests=src
sonar.test.inclusions=src/**/*.spec.ts,src/**/*.test.ts
sonar.exclusions=node_modules/**,dist/**,coverage/**
sonar.javascript.lcov.reportPaths=coverage/lcov.info
sonar.sourceEncoding=UTF-8

A chave precisa ser igual à cadastrada no servidor. Adapte as pastas e os padrões de teste à estrutura real do projeto.

Se houver cobertura, gere o relatório antes da análise:

code
npm test -- --coverage

O scanner para NPM pode ser executado com npx, sem instalação global:

code
npx @sonar/scan \
  -Dsonar.host.url=http://localhost:9000 \
  -Dsonar.token=$SONAR_TOKEN

No fim, o terminal mostra se a análise foi enviada. Volte ao navegador para consultar issues, métricas e o Quality Gate.

Como ler o primeiro resultado

Minha ordem costuma ser:

  1. verificar se o Quality Gate passou;
  2. revisar vulnerabilidades e Security Hotspots;
  3. tratar problemas novos de confiabilidade;
  4. olhar duplicações e complexidade;
  5. confirmar se a cobertura foi importada corretamente.

Não tento resolver tudo de uma vez. Primeiro separo problemas reais, falsos positivos e decisões arquiteturais. Depois priorizo aquilo que oferece risco ou deixa o código novo mais difícil de manter.

Usando na pipeline

Depois que a execução local funciona, o próximo passo é colocar o scanner no CI. O token deve entrar como secret da plataforma, nunca como texto no arquivo da pipeline.

A sequência básica é:

code
instalar dependências
executar testes e gerar cobertura
executar o scanner
consultar o Quality Gate

Em uma equipe, o maior ganho aparece quando o Quality Gate participa da decisão de merge. Um painel que ninguém consulta vira apenas mais uma ferramenta ligada.

Comandos úteis

code
docker ps --filter name=sonarqube
docker logs --tail 100 sonarqube
docker restart sonarqube
docker stop sonarqube
docker start sonarqube

Se o servidor não iniciar, os logs do container são sempre o primeiro lugar que consulto.

Fechamento

O SonarQube funciona melhor como uma conversa contínua sobre qualidade, não como uma auditoria feita na véspera do deploy. Começar localmente ajuda a entender regras, métricas e Quality Gates antes de transformar a análise em uma etapa obrigatória.

A ferramenta aponta onde olhar; a equipe ainda precisa entender o contexto e decidir o que fazer. Quando essa responsabilidade fica clara, o painel deixa de ser uma coleção de números e passa a apoiar decisões reais sobre o código.

Referências