Manual de utilização do AccessScope

Este guia explica como usar uma ferramenta de diagnóstico que encontra tentativas de ataque nos registos de acesso de um servidor e mostra a linha de registo que as comprova. Primeiro explica-se o diagnóstico a partir da janela, e a utilização na linha de comandos está reunida no capítulo 8.

1. O que é o AccessScope

O AccessScope é uma ferramenta de diagnóstico que lê os registos que os servidores web e SSH já guardam e procura tentativas de ataque. Cada deteção é apresentada com a linha de registo que a comprova. É útil para quem gere o seu próprio servidor e quer verificar se ficaram acessos suspeitos nos registos.

Os registos são apenas lidos. Não são alterados nem apagados, não é bloqueada nenhuma comunicação e não são elevados privilégios. O diagnóstico em si não usa nenhum LLM nem a rede.

No Mac vem incluído no DMG do RoamSwitch e, no Linux, nos pacotes deb, rpm e tarball do RoamSwitch. É uma ferramenta independente do RoamSwitch e a licença é Apache License 2.0. Para a abrir, no Mac escolhe-se o ícone da aplicação e, no Linux, escolhe-se «AccessScope» na lista de aplicações.

Ficheiros guardados

O AccessScope guarda automaticamente as definições, a lista de registos encontrados, as regras de exclusão e o registo da comparação com a vez anterior. Tudo fica em ~/.config/accessscope/, com permissões de leitura e escrita apenas para o próprio utilizador.

Atualizações

No Mac, só se liga a lafine.net quando se carrega em «Procurar atualizações» em «Atualizações» nas definições. Não são enviadas informações deste computador nem dos registos, e o ficheiro transferido é instalado depois de verificada a assinatura. No Linux não há atualização dentro da aplicação, por isso atualiza-se com a atualização dos pacotes.

2. O primeiro diagnóstico

1. Escolha os registos. O mais simples é «Procurar registos neste computador». Procura automaticamente os registos do nginx, do Apache, do SSH e de outros, e coloca-os em «Registos encontrados neste computador». Se já souber onde estão, use «Escolher ficheiros» ou «Escolher uma pasta», ou arraste ficheiros ou pastas para cima da janela.
2. Escolha o «Período». O valor inicial é «Últimos 7 dias» e também pode mudar para «Últimas 24 horas», «Últimos 30 dias» ou «Tudo». O período conta-se a partir de agora, por isso, para diagnosticar registos antigos, escolha «Tudo».
3. Carregue em «Diagnosticar». Aparece o progresso com «A ler os registos» e «A analisar» e, no fim, abre-se o resultado.

3. Registos que se podem ler e onde procurá-los

O tipo de registo é reconhecido automaticamente através do seu conteúdo. Os registos rodados e comprimidos com gzip também são lidos tal como estão. Se escolher uma pasta, são lidos de uma vez os ficheiros que parecem registos.

«Procurar registos neste computador» verifica as localizações padrão e as localizações de registos indicadas pelos ficheiros de configuração do servidor web. Na lista só aparece o que foi comprovado como legível enquanto registo.

Contentores Docker

Se marcar «Verificar também os contentores Docker», também podem ser incluídos os registos do Docker deste computador. Antes do diagnóstico, o ecrã de confirmação mostra os comandos que serão executados e os contentores visados, e os registos só são lidos quando carregar em «Concordar e diagnosticar». É apenas leitura e não são elevados privilégios.

Procurar registos com um LLM (opcional)

Se não encontrar nada, com «Procurar também com um LLM» pode pedir-se a um LLM que procure as localizações. Só lhe são passados dados do ambiente, como o nome dos servidores em execução e os nomes de ficheiros em /var/log e semelhantes, nunca o conteúdo dos ficheiros. As sugestões aparecem com a caixa desmarcada, depois de verificado que podem ser lidas. Para as definições, veja o capítulo 7.

4. Como ler os resultados

Quando o diagnóstico termina, o resultado pode ser consultado em quatro separadores.

Como ler uma deteção

As deteções são apresentadas com um nome, como «Tentativas de injeção de SQL», e têm uma gravidade (Alta, Média, Baixa) e uma confiança. A confiança indica até onde se pode afirmar algo apenas com o registo.

• Confirmado é o que se pode afirmar apenas com o registo.
• Provável indica uma elevada probabilidade de a tentativa ter ocorrido.
• Hipótese é o que não se pode comprovar apenas com o registo.

Ao abrir «Linhas de evidência», veem-se tal como estão as linhas de registo em que essa deteção se baseia. Normalmente estão fechadas, por isso leia primeiro o nome e o motivo, e abra só as que lhe chamarem a atenção.

O risco global (de 0 a 100) é uma referência ponderada pela gravidade e pela confiança. Não cresce só porque há muitas deteções e, se não houver nenhuma deteção de gravidade alta, não chega a «Alto». Não é uma probabilidade, por isso encare-o apenas como orientação.

5. Reduzir o que se vê

Regras de exclusão

As deteções que já se sabe que vão aparecer, como o IP do próprio escritório, a monitorização de disponibilidade ou as análises de vulnerabilidades próprias, podem ser retiradas do relatório. As deteções retiradas não são descartadas, mas o seu número é mantido juntamente com o motivo.

1. No separador «Deteções», carregue em «Excluir este IP…» junto ao IP da deteção.
2. Escreva o motivo e carregue em «Adicionar às regras de exclusão». O motivo fica no relatório.
3. Verifique o conteúdo na caixa de diálogo de confirmação e aprove-o. Produz efeito a partir do diagnóstico seguinte.

Em «Regras de exclusão» nas definições aparece a lista das regras ativas. É apenas para consulta e aqui não se pode editar. As regras com condições detalhadas escrevem-se num ficheiro (suppress.toml) colocado na pasta das definições. A forma de o escrever está no capítulo 8. As deteções de gravidade «Alta» não são retiradas mesmo que excluídas e permanecem no relatório.

Comparação com a vez anterior

Se se diagnosticar várias vezes seguidas a mesma combinação de registos, é comparada com o registo anterior e as deteções que aparecem pela primeira vez recebem a marca «Nova». Se marcar «Só novas» no separador «Deteções», filtram-se apenas as novas. Na primeira vez, todas são tratadas como novas. No registo entram apenas a impressão digital (hash) da deteção, o tipo, a gravidade, o número e a hora, nunca o texto dos registos.

6. Exportar os resultados

Com os botões na parte superior do ecrã de resultados é possível retirar os resultados.

Em «Exportar…» pode escolher-se como formato da lista de bloqueio fail2ban-ip, nftables, ipset, nginx-deny, apache-require ou csv. A lista de deteções pode ser exportada em CSV, SARIF ou JSON.

Na lista de bloqueio pode escolher-se «O que incluir» entre «predefinição», «mais rigoroso» e «mais amplo», e o número de IP que serão exportados é mostrado antes de guardar. Os IP dos rastreadores oficiais e os IP abrangidos pelas regras de exclusão nunca são incluídos.

7. Análise com um LLM (opcional)

É uma funcionalidade que faz com que um LLM resuma em texto o resultado do diagnóstico. Está desativada por predefinição. Para a usar, em «Integração com LLM» nas definições marque «Ativar a análise com um LLM», escolha o «LLM a utilizar» e carregue em «Guardar». Pode escolher-se entre claude, opencode, codex e agy, os que tiverem o comando instalado no computador.

O que é enviado

• Os registos em bruto não são enviados. São enviados as estatísticas e os dados das deteções e, por cada deteção, no máximo 3 linhas de registo como evidência (até 300 caracteres por linha).
• Os segredos, como chaves, tokens e palavras-passe, e os endereços de correio eletrónico são ocultados antes do envio.
• Os IP são entregues de forma neutralizada, como 203[.]0[.]113[.]9. Se marcar «Não enviar IP reais (usar pseudónimos)», são substituídos por pseudónimos como ip-001.

Ao carregar em «Mostrar exatamente o que será enviado» no separador «Analisar com LLM», vê-se o texto completo que será enviado. Com esta ação não se envia nada. Só se envia pela primeira vez quando se carrega em «Analisar com LLM».

• O conteúdo dos registos pode ser escrito por um atacante. O AccessScope comunica como deteção as cadeias de texto que parecem instruções para uma IA e mostra o resultado do LLM como uma citação em que não se confia. Um LLM também pode interpretar uma deteção como mais grave do que é, por isso confirme as conclusões com as linhas de registo que as comprovam.
• Com claude e opencode, o AccessScope inicia-os com as ferramentas (execução de comandos e leitura de ficheiros) desativadas. Com codex e agy não é possível desativar as ferramentas, por isso é preciso marcar a confirmação que aparece nas definições. A análise por LLM também pode ser usada como root, mas o LLM corre então com os privilégios de root; recomenda-se um utilizador sem privilégios (as definições mostram uma nota enquanto a aplicação corre como root).

8. Utilização a partir da linha de comandos

Em ambientes apenas com comandos, como o Server Edition, ou quando se quer executar periodicamente com o cron, usa-se o comando accessscope. É o mesmo motor da janela, por isso as deteções encontradas são as mesmas.

accessscope discover
accessscope scan --auto --since 7d --report report.md
accessscope scan /var/log/nginx/access.log /var/log/auth.log

Executar todos os dias com o cron

accessscope scan --auto --since 24h --since-last --new-only --fail-on medium

Mostra apenas as deteções que não existiam na execução anterior e termina com o código de saída 3 somente quando as deteções novas são de gravidade média ou superior. O diagnóstico sem --llm também funciona como root.

Como se escreve o suppress.toml

As regras de exclusão escrevem-se em ~/.config/accessscope/suppress.toml. Se o ficheiro existir, é lido automaticamente.

[[rule]]
reason  = "office"
ip      = ["203.0.113.0/28"]
expires = 2027-03-31

[[rule]]
reason      = "uptime monitor"
ua_prefix   = ["Mozilla/5.0 (compatible; UptimeRobot"]
path_prefix = ["/healthz"]

• Uma regra aplica-se aos pedidos que coincidem com todos os campos escritos. reason é obrigatório e aparece em todos os relatórios. As regras que passaram o seu expires não são aplicadas.
• As deteções de gravidade «Alta» não são retiradas se a regra não tiver allow_high = true.
• O User-Agent e o caminho são valores que o cliente pode escrever. Uma regra que não inclua o IP e se limite a estes não pode retirar deteções de ataques, de autenticação, de web shells e semelhantes.

9. O que não consegue fazer

• Só se vê o que ficou nos registos. Não se conhece o corpo dos pedidos, o conteúdo das respostas, o estado interno da aplicação nem o período perdido com a rotação dos registos. A ausência de deteções não prova que esteja tudo seguro.
• Uma deteção significa que «houve uma tentativa» e não é prova de que tenha tido êxito. O User-Agent é uma autodeclaração e pode ser falsificado.
• As cadeias que abrangem vários registos baseiam-se apenas no facto de o endereço ser o mesmo. Atrás de um NAT ou de um proxy, pessoas sem relação aparecem com o mesmo endereço. Os endereços internos (um proxy inverso ou um gateway do Docker) representam muitos clientes ao mesmo tempo, por isso não entram numa cadeia. Uma cadeia sem sinais de sucesso recebe a gravidade «baixa».
• «Inícios de sessão a partir de uma origem pouco habitual» significa que a origem é pouco habitual para esse registo, e não tem de ser fraudulento. «Desvios em relação ao habitual» indica apenas uma mudança e não tem de ser um ataque.
• Os registos do AWS ALB e do CloudFront foram testados com linhas criadas segundo as definições da documentação da AWS, e não com resultados reais da AWS.

10. Se algo não funcionar

Aparece em «Registos que não podem ser lidos neste momento»

É o que se mostra quando faltam permissões. O AccessScope não eleva privilégios para ler. Resolva com uma das opções seguintes.

• Para os registos em ficheiros, inicie com um utilizador que tenha permissões ou escolha uma cópia do registo com «Escolher ficheiros».
• Para o journald no Linux, inicie como root ou com um utilizador dos grupos adm, systemd-journal ou wheel.
• Para o registo unificado do macOS, inicie com um utilizador do grupo admin.

Aparece «Não foram encontrados registos diagnosticáveis»

O motivo é mostrado numa frase. Por exemplo, aparece «Não existem registos de servidor web (Apache, nginx, etc.)». No Mac, quando não há registos de SSH, aparece «O início de sessão remoto (SSH) pode estar desativado». Com «Escolher ficheiros», «Procurar com um LLM» e «Indicar outra localização», que aparecem no ecrã, pode tentar-se o passo seguinte. Para saber onde se procurou, abra «Resultado detalhado da pesquisa», que está fechado.

Aparece «Não foi possível ler os registos do Docker»

É uma destas causas. O Docker não está em execução, o Docker não é encontrado, faltam permissões ou o Docker devolveu um erro. Se faltarem permissões, inicie o AccessScope com um utilizador que possa usar o Docker. O AccessScope não volta a ler elevando privilégios, nem pede nem recomenda a adesão ao grupo docker, porque as permissões do grupo docker equivalem às de root no anfitrião.

Aparece «Não foi possível lê-lo como registo»

É o que se mostra quando não foi possível analisar nem uma única linha do ficheiro escolhido. Esse ficheiro não entra no diagnóstico e não é enviado para lado nenhum. Verifique se é um tipo de registo compatível e escolha-o de novo.

Não é possível carregar em «Analisar com LLM»

Junto ao botão aparece o motivo. Se aparecer «A integração com LLM está desativada», ative-a nas definições. Se aparecer «Nenhum LLM selecionado», escolha-o nas definições. Também não se pode usar se foi iniciado como root ou se o comando do LLM a utilizar não estiver instalado no computador.

A origem dos acessos é sempre o IP do proxy

Em registos que estão atrás de um proxy inverso ou de uma CDN, a origem do acesso pode ser o IP do proxy. Com o valor inicial «Automático», o IP do cliente é obtido a partir de X-Forwarded-For apenas nas linhas cuja origem registada é um endereço interno, como um proxy inverso ou um gateway do Docker. As linhas que chegaram diretamente do exterior mantêm a origem registada. Como o cabeçalho pode ser falsificado, um IP obtido assim nunca é tratado como rastreador verificado. Para desativar, escolha «Não usar» em «Análise» nas definições. Também se pode escolher o primeiro endereço a partir da direita que não seja um proxy de confiança, ou o endereço mais à esquerda; como o cliente pode reescrever este valor, use-os apenas atrás de um intermediário de confiança que o utilizador gira. Produz efeito a partir do diagnóstico seguinte.