Port Scanner

Scanner TCP concorrente em Python, desenvolvido como projeto de portfólio de cibersegurança. A ferramenta verifica portas de um host, identifica nomes convencionais de serviços e gera relatórios no terminal e em JSON.

Estado: v1.0.0 com funcionalidades congeladas. O foco atual é estabilidade, documentação e correções.

Resultado verificado

• 57 testes automatizados aprovados;
• lint aprovado com Ruff;
• portas abertas e fechadas validadas com listeners locais;
• concorrência limitada e resultados mantidos em ordem;
• execução inteiramente reproduzível em loopback.

Funcionalidades

• porta única, listas, intervalos e combinações;
• conexões TCP com timeout configurável;
• concorrência limitada entre 1 e 256 workers;
• resultados ordenados;
• identificação básica de serviços TCP;
• relatório JSON versionado e gravado atomicamente;
• códigos de saída para automação;
• testes unitários e de integração exclusivamente locais.

Requisitos

• Python 3.11 ou superior;
• pytest e Ruff apenas para desenvolvimento.

Instalação

git clone https://github.com/guuszz/port-scanner.git
cd port-scanner
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Após a instalação, o comando portscanner fica disponível no ambiente virtual.

Uso

portscanner scan 127.0.0.1 --ports 20-100
portscanner scan localhost --ports 22,80,443 --timeout 0.3 --workers 25
portscanner scan 127.0.0.1 --ports 8000-8100 --json resultado.json

Também é possível executar sem instalar o entry point:

$env:PYTHONPATH = "src"
python -m portscanner scan 127.0.0.1 --ports 20-100 --timeout 0.5 --workers 50

Formatos aceitos por --ports:

• porta única: 443;
• lista: 22,80,443;
• intervalo: 8000-8100;
• combinação: 22,80,443,8000-8100.

Exemplo de saída:

Target: 127.0.0.1
80/tcp  open  http
443/tcp  open  https
Scanned: 101 ports in 0.42s
JSON: C:\caminho\resultado.json

Relatório JSON

O relatório inclui versão do schema, alvo, horário UTC, duração, total verificado, portas abertas e erros:

{
  "schema_version": 1,
  "target": "127.0.0.1",
  "scanned_at": "2026-08-20T12:30:00Z",
  "duration_ms": 42.5,
  "ports_scanned": 2,
  "open_ports": [
    {
      "port": 80,
      "protocol": "tcp",
      "status": "open",
      "latency_ms": 1.25,
      "service": "http"
    }
  ],
  "errors": []
}

Desenvolvimento e testes

python -m pytest -q
python -m ruff check .

Os testes de integração criam listeners temporários em 127.0.0.1; a suíte não depende da internet nem de serviços externos.

API Python

from portscanner import ScanStatus, scan_port

result = scan_port("127.0.0.1", 8080, timeout=0.5)
if result.status is ScanStatus.OPEN:
    print(result.port, result.service)

Arquitetura e limitações

Consulte docs/architecture.md para o fluxo interno, decisões técnicas e limitações. O roadmap original está em PLANO.md.

Use a ferramenta somente em hosts e ambientes nos quais a varredura esteja prevista pelas regras do laboratório ou da organização.

Status da versão

A versão 1.0.0 está congelada. Consulte CHANGELOG.md, SECURITY.md e docs/verification.md.

Licença

MIT