Solução de Problemas

Esta página cobre os problemas mais comuns encontrados ao usar o Elven Assessment e como resolvê-los.

"Token inválido" ao tentar entrar

Causa: O token fornecido está incorreto, expirado ou houve um caractere extra copiado (espaço, quebra de linha).

Solução: 1. Copie o token novamente da fonte original, garantindo que não há espaços antes ou depois. 2. Cole diretamente no campo — não use autocompletar. 3. Se o problema persistir, solicite ao administrador que verifique o valor da variável AUTH_TOKEN no servidor.

"Usuário ou senha incorretos" (modo RBAC)

Causa: Credenciais erradas ou o usuário não existe.

Solução: 1. Verifique maiúsculas e minúsculas — o campo de usuário é case-sensitive. 2. Confirme com o administrador se sua conta existe na variável AUTH_USERS. 3. Se esqueceu a senha, peça ao administrador para redefinir.

Causa: Cookie de sessão corrompido ou incompatível com uma nova versão da plataforma.

Solução: 1. Abra o DevTools do navegador (F12 → Application → Cookies). 2. Remova todos os cookies do domínio da plataforma. 3. Recarregue a página e tente fazer login novamente. 4. Se o problema persistir em todos os usuários, o administrador deve verificar se SESSION_SECRET mudou (o que invalida todas as sessões existentes).

Problemas durante o assessment

Assessment falha imediatamente com "Credenciais inválidas"

AWS: 1. Verifique se o Role ARN está correto (formato: arn:aws:iam::123456789012:role/NomeDaRole). 2. Se estiver usando External ID, certifique-se de que o valor é exatamente igual ao configurado na Trust Policy da IAM Role. 3. Verifique se a Trust Policy permite que a conta da plataforma (sts:AssumeRole) assuma a role. 4. Teste manualmente:

aws sts assume-role --role-arn "arn:aws:iam::CONTA:role/ROLE" --role-session-name "teste" --external-id "SEU_EXTERNAL_ID"

GCP: 1. Certifique-se de que o arquivo JSON da Service Account está completo e não corrompido. 2. Verifique se a Service Account tem os papéis necessários no projeto. 3. Confirme que as APIs necessárias estão habilitadas no projeto GCP.

Azure: 1. Verifique se o Tenant ID, Client ID e Client Secret estão corretos. 2. Confirme que o Client Secret não expirou (verifique no Azure Portal → App Registration → Certificados e segredos). 3. Verifique se o App Registration tem o papel Reader na subscription.

Assessment falha com "Permission Denied" em serviços específicos

Causa: A IAM Role ou Service Account não tem permissões para acessar determinados serviços.

Solução: 1. Verifique na página de progresso quais serviços falharam com erro de permissão. 2. Consulte a política IAM recomendada no guia do provedor (AWS, GCP, Azure). 3. Adicione as permissões faltantes à Role/Service Account e execute o assessment novamente. 4. Se não puder adicionar as permissões, exclua os serviços problemáticos da seleção de serviços e reexecute.

Assessment travado na etapa de progresso

Causa: O assessment pode estar aguardando resposta de APIs lentas ou ter encontrado um timeout interno.

Solução: 1. Aguarde pelo menos 30 minutos — assessments de contas grandes podem demorar. 2. Verifique se há mensagem de erro em algum serviço na página de progresso. 3. Se o progresso não avançou em mais de 30 minutos, o assessment pode estar preso. Nesse caso: - Feche a página e reabra o Histórico — o assessment pode ter concluído. - Se aparecer como "Em andamento" no histórico por mais de 1 hora sem progresso, contacte o suporte. 4. O administrador pode verificar os logs do servidor:

docker-compose logs -f elven-assessment | grep "assessment"

Problemas com resultados

Nenhum finding aparece — score 100

Causa: Pode ser que o escopo selecionado (regiões, serviços) não tenha recursos para analisar, ou as permissões não permitiram acessar nenhum serviço.

Verificações: 1. Confirme que a conta AWS realmente tem recursos nas regiões selecionadas. 2. Verifique a aba de progresso (se ainda disponível) ou os logs para ver se algum serviço retornou erro de permissão. 3. Tente executar um novo assessment com apenas os serviços que você sabe que têm recursos (ex.: EC2 se você tem instâncias).

Score 100 sem findings

Um score de 100 com 0 findings geralmente indica problema de configuração de escopo ou permissões, não que o ambiente está perfeito.

Score muito diferente do esperado

Causa: O questionário organizacional pode não ter sido respondido, ou respostas incorretas foram fornecidas.

Solução: 1. Verifique se o questionário foi respondido (aba Org. Assessment). 2. Se não foi respondido, o score reflete apenas a análise técnica, o que pode ser significativamente diferente do score com o questionário. 3. Responda ou edite o questionário e observe a mudança no score.

Problemas de exportação

Download do Excel falha ou arquivo está corrompido

Causa: Timeout durante a geração do arquivo (assessments muito grandes) ou problema de cache do navegador.

Solução: 1. Aguarde que o assessment esteja 100% concluído antes de exportar (verifique o banner de progresso). 2. Tente novamente — a primeira tentativa às vezes gera timeout enquanto o arquivo é criado; a segunda tentativa usa o cache. 3. Tente em um navegador diferente. 4. Se o problema persistir, o administrador pode aumentar o timeout de geração de relatórios:

REPORT_GENERATION_TIMEOUT_SECONDS=120  # padrão: 60

PDF do sumário executivo em branco

Causa: Problema com o renderizador de PDF ou falta de dados no sumário.

Solução: 1. Verifique se o assessment está com status "Completo" (todos os 4 passos no banner). 2. Tente usar a Apresentação Interativa e depois o "Exportar para PDF" dentro dela — usa um caminho de renderização diferente. 3. Em ambientes self-hosted, certifique-se de que o serviço de renderização está rodando:

docker-compose ps  # verifique se o container está Up

Problemas com agendamentos

Slack webhook não está enviando notificações

Verificações: 1. Teste o webhook manualmente:

curl -X POST -H 'Content-type: application/json' \
  --data '{"text":"Teste de webhook Elven Assessment"}' \
  'https://hooks.slack.com/services/SEU/WEBHOOK/AQUI'

Se retornar ok, o webhook está funcionando. 2. Verifique se o canal do Slack ainda existe e o bot tem acesso a ele. 3. Confirme que o webhook no agendamento está salvo corretamente (edite o agendamento e salve novamente). 4. Verifique os logs do servidor após a execução do agendamento para ver o status do envio:

docker-compose logs elven-assessment | grep "webhook"

Agendamento executa mas não encontra findings novos

Causa: O ambiente não mudou desde a última execução ou o "drift webhook" está configurado para enviar apenas quando há novos findings.

Esclarecimento: - A notificação padrão é sempre enviada (com o score e delta), independentemente de haver findings novos. - O drift webhook só é chamado quando há findings novos ou resolvidos desde a última execução. - Se nenhuma notificação chegou, verifique se o agendamento está ativo (toggle verde na lista de agendamentos) e se a execução aparece no histórico.

Problemas com código-fonte

Docker não disponível — modo fallback

Sintoma: Banner amarelo nos resultados indicando "Executado em modo fallback — análise incompleta".

Causa: O Docker não está disponível no servidor onde a plataforma está instalada.

Solução (self-hosted): 1. Instale o Docker no servidor:

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $(whoami)

2. Certifique-se de que o usuário que roda a plataforma tem acesso ao socket Docker:

ls -la /var/run/docker.sock

3. Se estiver rodando em Kubernetes, verifique se o pod tem acesso ao Docker daemon (DinD ou socket mounting). 4. Reinicie a plataforma e execute um novo assessment de código-fonte.

Assessment de código-fonte falha com "Repository not found" ou "Authentication failed"

Causa: Token inválido, repositório inexistente ou sem acesso.

Verificações: 1. Teste o acesso ao repositório manualmente:

# GitHub — substitua <TOKEN> pelo seu PAT
curl -H "Authorization: Bearer <TOKEN>" \
  https://api.github.com/repos/ORG/REPO

Deve retornar as informações do repositório, não um erro 404 ou 401. 2. Verifique se o PAT tem o escopo repo (GitHub) ou read_repository (GitLab). 3. Confirme se o repositório é privado e o token tem acesso — repositórios privados de organizações podem requerer que o token seja autorizado via SSO da organização.

Banco de dados — Collector

Collector: conexão recusada ao banco de dados

Causa: Problema de conectividade de rede, configuração de firewall, ou credenciais incorretas.

Diagnóstico passo a passo:

Verifique conectividade básica:

nc -zv meu-postgres.internal 5432
# Deve retornar "Connection to meu-postgres.internal 5432 port [tcp/postgresql] succeeded!"

Verifique se as credenciais estão corretas testando conexão direta:

# PostgreSQL
psql -h meu-postgres.internal -p 5432 -U elven_collector -d postgres -c "SELECT version();"

# MySQL
mysql -h meu-mysql.internal -P 3306 -u elven_collector -p -e "SELECT VERSION();"

Para PostgreSQL, verifique o pg_hba.conf para garantir que o host de onde o coletor roda tem permissão:
```
# Linha que deve existir no pg_hba.conf:
host    all    elven_collector    10.0.0.0/8    md5
```
Verifique regras de security group / firewall que possam estar bloqueando a porta.

Mensagens de erro comuns

Mensagem de erro	Causa	Solução
`AssumeRoleError: AccessDenied`	External ID incorreto ou Trust Policy mal configurada	Revise a Trust Policy da IAM Role
`CredentialsError: NoCredentialProviders`	Método Instance Profile sem role associada	Associe uma IAM Role à instância/pod
`ResourceNotFoundException: CloudTrail`	CloudTrail não habilitado na conta	O finding é legítimo — habilite o CloudTrail
`RateLimitExceeded` (GCP)	Quota de API excedida	Aguarde e tente novamente; solicite aumento de quota
`ClientAuthenticationError` (Azure)	Client Secret expirado	Crie um novo Client Secret no Azure AD
`invalid_client` (Azure)	Client ID ou Tenant ID incorreto	Verifique os valores no App Registration
`Bundle validation failed` (DB Collector)	Arquivo bundle.json corrompido	Execute o coletor novamente e gere um novo bundle

Onde buscar ajuda

Se o problema não estiver coberto nesta página:

Logs do servidor — Sempre colete os logs antes de contatar o suporte:

docker-compose logs --tail=200 elven-assessment > logs-assessment.txt

Suporte Elven Works — Envie um e-mail para suporte@elvenworks.com.br com:
Descrição detalhada do problema
Versão da plataforma (visível em Configurações → Sobre)
Logs relevantes (com informações sensíveis removidas)
Provedor e tipo de assessment afetado
Documentação técnica — Para administradores, consulte docs/self-hosted.md no repositório do projeto para configurações avançadas.