tls-attacker/tls-scannerScanner automatizado de configuração de servidor e cliente TLS para pentesters e pesquisadores. Avalia suites de cifras, versões de protocolo e diretrizes de segurança com profundidade de varredura personalizável e saída legível por máquina.
# TLS-Scanner
[](https://hydrogen.cloud.nds.rub.de/job/TLS-Scanner/)
O TLS-Scanner é uma ferramenta para auxiliar pentesters e pesquisadores de segurança na avaliação de configurações de servidores e clientes TLS.
**Atenção:** *O TLS-Scanner é uma ferramenta de pesquisa destinada a desenvolvedores de TLS, pentesters, administradores e pesquisadores. Não há interface gráfica. Está na primeira versão e pode conter alguns bugs.*
# Compilação
Para compilar e usar o TLS-Scanner, você precisa executar:
```bash
$ cd TLS-Scanner
$ git submodule update --init --recursive
$ mvn clean package
```
Alternativamente, se você estiver com pressa, pode pular os testes usando:
```bash
$ mvn clean package -DskipTests=true
```
Se você quiser usar o TLS-Scanner como uma biblioteca, precisa instalá-lo com o seguinte comando:
```bash
$ mvn clean install
```
# Execução
Para executar o TLS-Scanner, você precisa executar um dos arquivos jar na pasta apps/.
Eles podem ser obtidos compilando o aplicativo você mesmo ou
[baixando os arquivos jar lançados no GitHub](https://github.com/tls-attacker/TLS-Scanner/releases).
```bash
$ java -jar apps/TLS-Server-Scanner.jar -connect localhost:4433
```
O TLS-Scanner avaliará o servidor especificado (aqui `localhost` na porta `4433`) e, no final, imprimirá um relatório.
O relatório usa cores para transmitir a gravidade dos achados:
- Verde: Um bom resultado.
- Amarelo: Um aviso, que pode ser um problema potencial.
- Fundo Amarelo: Resultados em que o scanner não tem certeza se o alvo é vulnerável.
- Vermelho: Um problema grave, que deve ser corrigido.
- Cor padrão (dependendo do seu terminal, provavelmente preto ou branco): Um resultado neutro, que não é nem bom nem ruim. Isso inclui resultados informativos.
- Azul: O scanner não conseguiu escanear o servidor para este teste específico. Isso provavelmente se deve a um pré-requisito para este teste não ser suportado.
- Roxo: O scanner encontrou um erro ao escanear o servidor para este teste específico. Isso pode ser resultado de um bug no scanner, mas também devido ao servidor não suportar um recurso necessário.
- Ciano: Usado para estruturar o relatório (cabeçalhos, ...).
## Parâmetros Importantes
Você deve especificar um host que deseja escanear com o parâmetro -connect.
Se você quiser melhorar o desempenho do scan, pode usar o parâmetro `-threads` para aumentar o número de threads utilizadas.
Outro parâmetro importante por razões de desempenho é o parâmetro `-scanDetail`, que pode ser usado para configurar quão detalhado você deseja escanear. Os valores possíveis, variando de rápido a muito detalhado, são: QUICK, NORMAL, DETAILED, ALL.
O detalhe da saída pode ser configurado com o parâmetro `-reportDetail`. Para ver mais detalhes sobre as Diretrizes, use `-reportDetail ALL`.
Por padrão, os resultados são escritos apenas no console. Se você quiser ter uma saída legível por máquina, pode usar `-outputFile output.json` para gravar automaticamente os resultados em um arquivo JSON.
## Casos de Uso
Os parâmetros mais importantes a alterar são `-scanDetail` e `-reportDetail`. A seguir, explicamos alguns casos de uso para esses parâmetros.
### Scan Padrão
Na maioria dos casos, nossas configurações padrão de parâmetros são suficientes. Isso realiza um scan com ambos os níveis de detalhe definidos como `NORMAL`.
### Scan Rápido
Se você quiser realizar um scan rápido e obter uma visão geral rápida do seu sistema, recomendamos usar ambos os níveis de detalhe definidos como `QUICK`. Isso limita a extensão de algumas sondagens executadas para reduzir o tempo de execução e limita o detalhe do relatório para não incluir informações muito detalhadas e técnicas.
### Scan Detalhado
Se você quiser avaliar totalmente seu sistema e executar tudo o que temos, recomendamos usar ambos os níveis de detalhe definidos como `ALL`. Isso executa todas as sondagens existentes completamente e imprime informações muito detalhadas para análise e avaliação adicionais.
## Perfis de Scan
Em vez de (ou além de) definir parâmetros como `-scanDetail` individualmente, você pode agrupar
quais sondagens executar e quais desses parâmetros usar em um perfil de scan JSON reutilizável com
o parâmetro `-profile <path/to/profile.json>`. Ele está disponível tanto em `TlsServerScanner` quanto em
`TlsClientScanner`.
Um perfil é um arquivo JSON com:
- `inheritedFromProfiles`: caminhos para outros perfis dos quais combinar sondagens, resolvidos relativamente ao
diretório do arquivo de perfil que os declara (um caminho absoluto é usado como está).
- `probes`: as sondagens a executar, como um mapa do nome totalmente qualificado de uma classe enum `ProbeType`
para a lista de seus nomes de constantes a executar. Isso agrupa sondagens por tipo em vez de repetir o
tipo para cada sondagem individual, enquanto um único perfil ainda pode combinar livremente sondagens de
diferentes implementações de `ProbeType`, por exemplo `TlsProbeType` e `QuicProbeType`. Cada lista por tipo
também aceita `"*"` (todas as constantes desse tipo) e `"!CONSTANT_NAME"` (remover uma constante
previamente adicionada por nome ou por `"*"`), processados em ordem — veja `Everything.json` e
`demo.json` em [`scan-profiles/`](https://github.com/tls-attacker/tls-scanner/blob/main/scan-profiles) para exemplos.
- `settings` (opcional): substituições para parâmetros como `-scanDetail`, `-reportDetail`,
`-postAnalysisDetail`, `-noColor`, `-outputFile`, `-probeTimeout`, `-parallelProbes` e
`-threads`. Qualquer campo omitido mantém seu padrão normal (ou o que foi passado na linha de comando).
**Diferentemente de `probes`, `settings` não são herdados** — apenas as configurações declaradas diretamente no
perfil para o qual você aponta `-profile` se aplicam, mesmo que ele herde sondagens de outros perfis.
Apenas as sondagens resolvidas a partir do perfil ativo (e tudo o que ele herda) são executadas;
todo o resto é ignorado.
Exemplo, combinando as sondagens de um perfil base com as suas próprias e ajustando o detalhe do scan:
`base.json`:
```json
{
"probes": {
"de.rub.nds.tlsscanner.core.constants.TlsProbeType": ["PROTOCOL_VERSION", "CIPHER_SUITE"]
}
}
```
`quic.json` (no mesmo diretório que `base.json`):
```json
{
"inheritedFromProfiles": ["base.json"],
"settings": {
"scanDetail": "QUICK"
},
"probes": {
"de.rub.nds.tlsscanner.core.constants.QuicProbeType": ["SUPPORTED_VERSIONS"]
}
}
```
```bash
$ java -jar apps/TLS-Server-Scanner.jar -connect localhost:4433 -profile quic.json
```
Isso executa `PROTOCOL_VERSION`, `CIPHER_SUITE` e `SUPPORTED_VERSIONS` com `-scanDetail QUICK`.
Para ver todas as sondagens disponíveis para um scanner (sem se conectar a um alvo), use `-listProbes`.
Ele as imprime agrupadas por classe `ProbeType` na sintaxe JSON exata que o campo `probes` de um perfil
espera, para que você possa copiar e colar diretamente em um perfil:
```bash
$ java -jar apps/TLS-Server-Scanner.jar -listProbes
{
"de.rub.nds.tlsscanner.core.constants.TlsProbeType" : [ "ALPN", "ESNI", "CERTIFICATE", ... ],
"de.rub.nds.tlsscanner.core.constants.QuicProbeType" : [ "SUPPORTED_VERSIONS", ... ]
}
```
## Todos os Parâmetros
Para obter informações detalhadas sobre todos os parâmetros possíveis, use o parâmetro `-help` ou execute o jar sem nenhum parâmetro definido.
# Docker
Fornecemos imagens docker pré-construídas para facilitar o uso do TLS-Server-Scanner.
```bash
$ docker run -it --network host ghcr.io/tls-attacker/tlsscanner -connect localhost:4433
```
A imagem foi feita para ser usada para escaneamento de servidores, mas também contém os outros arquivos jar.
Eles podem ser acessados alterando o entrypoint.
```bash
$ docker run -it --network host --entrypoint java ghcr.io/tls-attacker/tlsscanner -jar TLS-Client-Scanner.jar
```
Também fornecemos um Dockerfile para você construir o contêiner por conta própria:
```bash
$ docker build . -t tlsscanner
$ docker run -t tlsscanner
```
**Atenção:** *Não estou de forma alguma familiarizado com as melhores práticas do Docker. Se você souber como melhorar o Dockerfile,
sinta-se à vontade para enviar um pull request*
# Sistema de Requisitos
As sondagens (TLS) às vezes têm pré-requisitos necessários para executar essa sondagem específica. O sistema de requisitos permite definir conjuntos de tais requisitos que devem ser atendidos para que a sondagem seja executada.
Cada requisito oferece uma função `evaluate` que retorna um valor booleano indicando se o requisito foi cumprido.
Os requisitos podem ser concatenados de várias maneiras usando operações lógicas bem conhecidas. Cada requisito oferece os métodos de instância `and`, `or`, `not` e `xor`
para encadear múltiplos requisitos. As seguintes sondagens estão atualmente implementadas e podem ser usadas prontas para uso:
- `FulfilledRequirement` - Sempre avalia como `true`, útil para indicar nenhum requisito.
- `UnfulfillableRequirement` - Sempre avalia como `false`, impede a execução de sondagens.
- `ProbeRequirement` - Avalia como `true` se a(s) sondagem(ns) especificada(s) foi(ram) executada(s).
- `PropertyRequirement` - Avalia como `true` se as propriedades analisadas especificadas tiverem um valor predefinido. O valor pode ser fornecido como parâmetro do construtor ou pode-se usar `PropertyTrueRequirement` e `PropertyFalseRequirement` como atalho para `TestResults.TRUE` e `TestResults.FALSE`.
- `PropertyComparatorRequirement` - Avalia como `true` se o resultado da coleção de uma propriedade analisada for menor, igual ou maior que um valor constante.
- `ProtocolRequirement` - Avalia como `true` se certas versões de protocolo forem suportadas.
- `ExtensionRequirement` - Avalia como `true` se certas extensões forem suportadas pelo par remoto.
- `OptionsRequirement` - Avalia como `true` se flags adicionais de cli estiverem definidas. Atualmente usado em algumas sondagens de cliente (ALPN, SNI, retomada de sessão).
- `WorkingConfigRequirement` - Avalia como `true` se uma configuração funcional foi encontrada.
Além desses requisitos predefinidos, também é possível estender a classe `Requirement` anonimamente dentro do método `getRequirements`. Se nada for necessário, você pode retornar um `FulfilledRequirement` que sempre avalia como true.
Exemplos de como usar requisitos podem ser encontrados nos pacotes `probe` do `tls-client-scanner` e `tls-server-scanner`.
```java
@Override
public Requirement<ClientReport> getRequirements() {
return new ProbeRequirement<ClientReport>(TlsProbeType.CIPHER_SUITE)
.and(new PropertyTrueRequirement<>(TlsAnalyzedProperty.SUPPORTS_DHE));
}
```