ACCESSSCOPE · Última atualização 2026-10-28

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.

AmbienteO que se pode usar
Mac (macOS 12 ou posterior)Aplicação com janelas e comandos
Versão cliente do LinuxAplicação com janelas e comandos
Pacote Server Edition do LinuxApenas comandos

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 modo mais simples é «Procurar registos deste dispositivo». Encontra automaticamente registos de nginx, Apache, SSH, etc., e lista-os em «Registos encontrados neste dispositivo». Se souber a localização, escolha com «Escolher ficheiros» ou «Escolher pasta», ou largue ficheiros ou pastas sobre a 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.
Apenas leitura
Os ficheiros de registo não são alterados. Se um registo não puder ser lido por falta de permissões, não são elevados privilégios para o ler, mas é indicado que não foi possível lê-lo.

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.

TipoO que se pode ler
Servidor webRegistos de Apache, nginx, Caddy, Traefik, HAProxy, AWS ALB e CloudFront, Cloudflare Logpush, Envoy e Istio, e Google Cloud (balanceadores de carga, etc.). Os registos da nuvem são primeiro transferidos e depois escolhidos com «Escolher ficheiros»
SSH e autenticaçãosshd, sudo, su e PAM. No Linux leem-se o auth.log e o secure e também o journald. No Mac lê-se o registo unificado do macOS
Registos do anfitrião (opcional)Os registos de execução do RoamSwitch Server e o registo de auditoria do Linux (/var/log/audit/audit.log). Por si sós, não criam deteções. Se, nos 5 segundos seguintes a um pedido de ataque Web, uma conta do lado do servidor web iniciar uma shell ou semelhante, a confiança dessa deteção aumenta. A pesquisa automática não os encontra; escolha o ficheiro
Outrosfail2ban, correio (Postfix, Dovecot), bases de dados (registos de erros do MySQL e do MariaDB, registo geral do MySQL, registo do MariaDB Audit Plugin, PostgreSQL) e registos de contentores Docker, Kubernetes e Podman (a pesquisa automática não encontra os registos do Kubernetes e do Podman; escolha um ficheiro ou uma pasta)

«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.

SeparadorO que se vê
PainelRisco global (Nenhum, Baixo, Médio, Alto), número de deteções por gravidade e por categoria, evolução ao longo do tempo, e os IP e caminhos com mais pedidos
DeteçõesLista das deteções encontradas. Pode filtrar-se por gravidade e pesquisar por título
Registos de entradaQue registos foram lidos e quantas linhas. Os registos que não foi possível ler e o motivo
Analisar com LLMFaz com que um LLM redija o texto do relatório (capítulo 7)

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.

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.

Um 200 de HTTP não é sinal de que o ataque teve êxito
Um servidor exposto à Internet é analisado o dia todo, e os sites estáticos devolvem 200 mesmo a pedidos que parecem ataques. O AccessScope compara o tamanho das respostas 2xx a pedidos que parecem ataques com o das respostas normais do mesmo caminho. Se forem iguais, mostra «o payload foi provavelmente ignorado» e não aumenta a gravidade. Só trata como «suspeita de efeito» as respostas diferentes do normal, e mesmo assim deixa a confiança em «Hipótese».

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.

O que não foi examinado

O resultado do diagnóstico aplica-se apenas ao âmbito dos registos que foi possível ler. Só quando algo foi ignorado, o relatório inclui uma breve nota de «âmbito não visto», e o mesmo conteúdo aparece também em «Registos de entrada» no ecrã. Quando todos os registos foram lidos até ao fim, não se acrescenta nada.

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.

BotãoO que faz
Guardar relatório (Markdown)Guarda o relatório do diagnóstico num ficheiro Markdown
Copiar resumoCopia o resumo para a área de transferência
Exportar…Exporta uma lista de bloqueio (lista de IP), a lista de deteções ou um rascunho de web_guard.conf para o RoamSwitch Server

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. «Rascunho de web_guard.conf», em «RoamSwitch», escreve um rascunho do ficheiro de configuração do RoamSwitch Server. Todas as linhas sugeridas são comentários; só têm efeito as linhas a que, depois de verificadas, se retire o «# ».

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.

Apenas se exporta, não se aplica nada
O AccessScope limita-se a exportar ficheiros. Não altera a configuração da firewall nem bloqueia comunicações. A lista de IP baseia-se apenas nos registos. Atrás de um NAT ou de uma CDN, muitas pessoas partilham um único IP, e os IP também podem ser falsificados. Verifique sempre o conteúdo antes de o aplicar.

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

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». Com a investigação passo a passo, vê-se apenas a primeira ronda. O que é enviado nas seguintes depende das consultas do LLM e não pode ser mostrado antecipadamente.

Fica fora de «Zero Telemetry»
Se for ativada e se executar a análise, o resumo e as linhas de registo como evidência são enviados para um serviço externo através do comando do LLM escolhido. O destino é determinado pela configuração do próprio comando. A explicação de «Zero Telemetry» do RoamSwitch não inclui esta funcionalidade. Se ficar desativada, o conteúdo dos registos lidos no diagnóstico não sai do computador.

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.

No Mac, se a aplicação estiver na pasta Aplicações, o comando está em /Applications/AccessScope.app/Contents/MacOS/accessscope. Para o chamar pelo nome curto, execute o seguinte no Terminal. Depois, basta accessscope.

sudo mkdir -p /usr/local/bin
sudo ln -sf /Applications/AccessScope.app/Contents/MacOS/accessscope /usr/local/bin/accessscope
accessscope discover
accessscope scan --auto --since 7d --report report.md
accessscope scan /var/log/nginx/access.log /var/log/auth.log
OpçãoO que faz
--autoProcura registos nas localizações padrão e noutras, e diagnostica-os. Com --since 7d pode restringir-se o período
--report FILEEscreve um relatório em Markdown
--format json|csv|sarif|brief-jsonAltera o formato da saída padrão. brief-json é um pequeno JSON de forma fixa para outras ferramentas (as linhas de evidência já vêm mascaradas, no máximo 40 deteções)
--export-blocklist FORMAT[:FILE]Exporta uma lista de bloqueio
--export-roamswitch FILE|-Escreve um rascunho de web_guard.conf para o RoamSwitch Server. Todas as linhas sugeridas são comentários e nada é aplicado
--fail-on high|medium|lowSe existirem deteções dessa gravidade ou superior, termina com o código de saída 3
--fail-on-partialTermina com o código de saída 4 quando há partes que não puderam ser verificadas, como registos ilegíveis
--since-last、--new-onlyCompara com a vez anterior e mostra apenas as deteções novas
--llm NAME、--show-promptFaz com que um LLM analise. --show-prompt mostra o texto completo que seria enviado e termina (não se envia nada)
--print-schedule=systemd|launchd|cronMostra um exemplo de execução agendada (systemd, launchd ou cron). Não escreve nenhum ficheiro nem regista nada. --interval-min define o intervalo (de 1 a 1440 minutos)
--llm-investigateUsa-se com --llm. Antes de redigir o relatório, o LLM pode fazer até 6 consultas só de leitura sobre os resultados do diagnóstico (o LLM é chamado em cada ronda). Os ficheiros de registo não são lidos de novo e os registos em bruto não são entregues
--notifyUsa-se com --fail-on ou --fail-on-partial. Quando o código de saída é 3 ou 4, mostra uma notificação no ambiente de trabalho que contém apenas números (osascript no Mac, notify-send no Linux)
accessscope suppress checkVerifica como está escrito suppress.toml e lista as regras que expiram em 7 dias ou que já expiraram. Não altera nenhum ficheiro
--what-if-suppress "ip=198.51.100.7"Mostra que deteções desapareceriam ou diminuiriam se adicionasse essa regra. Nenhum ficheiro é alterado (chaves como ip, ua, path e kind)
accessscope fleet a.json b.json ...Reúne a saída de scan --format json de vários anfitriões. Mostra as origens de ataque vistas em mais de um anfitrião, uma lista de bloqueio unificada e o que cada anfitrião pôde examinar (não estabelece ligações)

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 estavam na execução anterior e termina com o código de saída 3 apenas quando uma nova deteção tem gravidade média ou superior. O diagnóstico também funciona como root quando se indica --llm. accessscope --print-schedule=cron (ou systemd, launchd) imprime um exemplo desta configuração.

A avaliação de --fail-on abrange apenas o que foi possível ler. Quando há partes que não puderam ser verificadas, como registos ilegíveis, e não há deteções, o código de saída continua a ser 0 e é emitido um aviso no erro padrão. Para obter o código de saída 4 neste caso, acrescente --fail-on-partial. Se também houver deteções que cumpram a condição, é 3.

Os códigos de saída são: 0 sem problemas, 1 nenhum registo legível ou não foi possível gravar, 2 erro de utilização, 3 cumpriu --fail-on, 4 há partes que não puderam ser verificadas com --fail-on-partial, 5 falha na análise de --llm. Quando se cumprem dois ou mais, vale o número menor.

Quando a análise de --llm falha, isso é indicado no relatório (uma linha no Markdown e na saída do terminal, llm.failed no JSON) e o código de saída é 5.

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"]

9. O que não consegue fazer

Sobre os números de precisão
Em medições com dados de teste próprios, foram detetados 1136 de 1142 ataques (cerca de 99,5%), e nenhum dos 396 casos de comunicações normais gerou uma deteção de gravidade média ou superior. Os dados de teste não são uma amostra do tráfego de servidores reais, por isso estes números não garantem a precisão num servidor real.

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.

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»

O motivo aparece junto ao botão. Se indicar “A integração com LLM está desativada”, ative-a nas Definições. Se indicar “Nenhum LLM selecionado”, escolha um nas Definições. Também não pode ser usada quando o comando do LLM que pretende utilizar não está instalado na máquina.

A origem dos acessos é sempre o IP do proxy

Nos registos atrás de um proxy inverso ou de uma CDN, a origem do acesso pode ser o IP do proxy. O valor predefinido «Automático» determina o IP do cliente a partir de X-Forwarded-For apenas nas linhas cuja origem de ligação é um endereço interno. Como pode ser forjado, este IP não é tratado como um rastreador verificado. Em «Análise», nas definições, pode escolher também «Não usar» ou outros métodos, mas use os outros métodos apenas atrás de um retransmissor de confiança que administre por si.

← Página do produto AccessScope Ir para o manual do RoamSwitch para Mac →