System Diagnostic Tool

Ferramenta de diagnostico de sistema e rede para suporte tecnico e infraestrutura

Diagnose. Analyze. Act.

---

🧠 O Problema

No dia a dia de suporte tecnico, problemas comuns incluem:

Problema	Impacto
Maquina lenta	Queda de produtividade
Falha de conexao	Interrupcao de servicos
Servicos inacessiveis	Usuarios bloqueados
Falta de diagnostico claro	Tempo alto de resolucao

Muitas vezes, o diagnostico inicial e manual, repetitivo e sujeito a erro.

---

🚀 A Solucao

O System Diagnostic Tool automatiza a triagem inicial de problemas, coletando e analisando:

• estado do sistema
• conectividade de rede
• disponibilidade de servicos e portas
• arquivos de log informados pelo operador
• resumo de problemas detectados

Tudo com saida clara e acionavel.

---

⚙️ Como Funciona

Sistema -> Coleta de dados -> Analise -> Classificacao -> Relatorio -> CLI

Pipeline simples e focada em troubleshooting.

---

🔍 Funcionalidades

🖥️ System Diagnostics

• CPU usage
• Memory usage
• Disk usage
• Sistema operacional
• Arquitetura e processador

🌐 Network Diagnostics

• Hostname
• IP local
• Teste de DNS
• Teste de conectividade externa

🔌 Service Checks

• HTTP (80)
• HTTPS (443)
• RDP (3389)
• SSH (22)

📊 Analise

• Classificacao por severidade: OK, INFO, WARNING, CRITICAL, FAILED
• Destaque automatico de achados relevantes
• Status geral consolidado

🧾 Output

• Diagnostico no terminal
• Resumo com principais problemas
• Relatorio estruturado em JSON
• Analise opcional de logs com achados WARNING e CRITICAL

---

📈 Exemplo de Execucao

python main.py

Exemplo de saida:

System Diagnostic Tool v2.0.0

Hostname: DESKTOP-01

## System Information

OS: Windows 11
Architecture: AMD64
Processor: Intel64 Family

CPU Usage: 14% [OK]
Memory: 14.72GB / 16.00GB (92%) [CRITICAL]
Disk: 120.00GB free / 800.00GB (85%) [WARNING]

## Network Diagnostics

Local IP: 192.168.0.10
DNS Resolution: OK (google.com -> 142.250.79.14) [OK]
Connectivity: 8.8.8.8:53 -> OK [OK]
Connectivity: google.com:443 -> OK [OK]

## External Service Checks

google.com:80 -> OK [OK]
google.com:443 -> OK [OK]

## Local Service Checks

RDP (3389): NOT LISTENING [INFO]
SSH (22): NOT LISTENING [INFO]

## Log Analysis

Status: CRITICAL [CRITICAL]
Files analyzed: 1
Lines scanned: 500

Findings:
* logs/app.log:238 [CRITICAL] ERROR database connection failed

## Summary

Overall Status: CRITICAL

Key Findings:

* High memory usage
* High disk usage
* 1 critical log finding(s)

Report path: data/output/diagnostic_report.json

---

🧾 JSON Report

O sistema gera automaticamente um arquivo JSON em:

data/output/diagnostic_report.json

Exemplo:

{
  "hostname": "DESKTOP-01",
  "summary": {
    "overall_status": "WARNING",
    "key_findings": [
      "High disk usage"
    ]
  }
}

---

🖥️ Uso via CLI

Execucao padrao:

python main.py

Apenas resumo:

python main.py --summary-only

Sem gerar relatorio:

python main.py --no-report

Definir caminho do relatorio:

python main.py --output ./reports/host01.json

Personalizar dominio, timeout e alvos (as opcoes de alvo podem ser repetidas):

python main.py \
  --dns-domain intranet.example.com \
  --timeout 1.5 \
  --connectivity-target gateway.example.com:443 \
  --port-target localhost:22

Alvos IPv6 devem usar colchetes para separar o endereco da porta:

python main.py --port-target "[::1]:22"

Por padrao, python main.py ja procura logs automaticamente em logs/ e data/logs/. Para analisar um arquivo especifico:

python main.py --log-file ./logs/app.log --log-lines 1000

Mais de um arquivo pode ser informado repetindo a opcao:

python main.py --log-file ./logs/app.log --log-file ./logs/service.log

Os valores padrao ficam centralizados em config.py, facilitando a adaptacao a redes corporativas sem alterar os modulos de coleta. As verificacoes TCP usam no maximo oito workers por padrao, evitando a criacao de uma thread para cada alvo quando listas maiores sao fornecidas.

RDP e SSH locais sao tratados como servicos opcionais por padrao. Se essas portas nao estiverem escutando, o resultado e INFO e nao afeta negativamente o Overall Status. Para ambientes onde esses servicos devem estar ativos, altere expected_services em config.py:

expected_services = {
    "rdp": True,
    "ssh": True,
}

---

🧠 Diagnostico Inteligente

A ferramenta interpreta os dados coletados e gera insights objetivos:

• uso elevado de memoria -> possivel lentidao
• disco com alta ocupacao -> risco de falhas e indisponibilidade
• DNS falhando -> problema de resolucao
• portas fechadas -> servico indisponivel

---

🏗️ Arquitetura

diagnostic_tool/
|-- app/
|   |-- logs/
|   |-- models/
|   |-- network/
|   |-- ports/
|   |-- reporting/
|   `-- system/
|-- data/
|   `-- output/
|-- reports/
|-- main.py
|-- config.py
`-- requirements.txt

---

Como Executar

Pre-requisitos: Python 3.10+

python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
python main.py

No Linux ou macOS, ative o ambiente com:

source .venv/bin/activate

Para desenvolvimento e validacao:

pip install -r requirements-dev.txt
python -m pytest
python -m ruff check .
python -m mypy

Os diagnosticos usam concorrencia limitada para evitar que varios timeouts de rede sejam somados sequencialmente. Relatorios gerados podem conter hostname, enderecos IP e detalhes do ambiente; por isso, os arquivos JSON de saida nao sao versionados por padrao.

Falhas parciais na coleta de CPU, memoria ou disco recebem status FAILED em vez de serem interpretadas como uso de 0% com status OK. O relatorio JSON preserva essas falhas em system_information.collection_errors, organizadas pelo nome do componente.

A analise de logs roda automaticamente para arquivos .log encontrados em logs/ e data/logs/. Quando nenhum arquivo e encontrado, a execucao segue sem achados de log. Quando arquivos sao informados ou descobertos automaticamente, achados criticos nos logs elevam o status geral para CRITICAL; avisos ou falhas de leitura elevam o status geral para WARNING.

O workflow de integracao continua executa testes em Python 3.10, 3.12 e 3.13, alem de validar lint com Ruff, tipos com Mypy e compilacao dos arquivos Python.

---

⚠️ Limitacoes

• Nao substitui ferramentas corporativas de observabilidade
• Nao analisa logs ou processos avancados
• Nao realiza varredura completa de portas
• Focado em triagem inicial

---

🗺️ Roadmap

Versao	Foco	Status
v1.0	Diagnostico completo (system + network + ports)	✅ Concluido
v1.1	Refinamentos e melhorias de saida	✅ Concluido
v1.2.0	Relatorio JSON, CLI configuravel, testes e qualidade	✅ Concluido
v2.0.0	Integracao com logs	✅ Concluido
v2.1	Suporte a monitoramento continuo	💡 Futuro

---

Objetivo do Projeto

Projeto desenvolvido para demonstrar:

• troubleshooting em ambientes reais
• diagnostico de sistema e rede
• automacao de tarefas de suporte
• boas praticas de arquitetura em Python

---

👨‍💻Desenvolvido por Jefferson Ferreira.

---

_{System Diagnostic Tool - 2026}