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.
| Ambiente | O que se pode usar |
|---|---|
| Mac (macOS 12 ou posterior) | Aplicação com janelas e comandos |
| Versão cliente do Linux | Aplicação com janelas e comandos |
| Pacote Server Edition do Linux | Apenas 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
- 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.
- 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».
- 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.
| Tipo | O que se pode ler |
|---|---|
| Servidor web | Registos 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ção | sshd, 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 |
| Outros | fail2ban, 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.
| Separador | O que se vê |
|---|---|
| Painel | Risco 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ções | Lista das deteções encontradas. Pode filtrar-se por gravidade e pesquisar por título |
| Registos de entrada | Que registos foram lidos e quantas linhas. Os registos que não foi possível ler e o motivo |
| Analisar com LLM | Faz 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.
- 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.
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.
- O que se conta: registos que não puderam ser lidos, não foram encontrados ou não tinham nenhum formato reconhecido; registos sem entradas no período escolhido; registos lidos apenas em parte devido ao limite de tamanho (
--max-mb); saídas de journald, do registo unificado do macOS e dedocker logsque terminaram antes do fim (tempo esgotado, limite de leitura ou falha do comando); linhas de um registo web que não puderam ser analisadas (a partir de 10 linhas e de 5 %); linhas com UTF-8 inválido; e ficheiros não lidos porque um diretório tinha mais de 500 candidatos (os mais antigos são descartados primeiro). - Como se escreve «sem deteções»: quando uma parte da entrada não pôde ser examinada, lê-se «Não há deteções na parte examinada» com a indicação de que uma parte não foi examinada. Não haver deteções não prova que esteja tudo seguro.
- As exportações incluem o mesmo:
coverageem JSON, linhas comstate=coverageem CSV e notificaçõescoverageem SARIF. Também faz parte do resumo entregue a um LLM.
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.
- No separador «Deteções», carregue em «Excluir este IP…» junto ao IP da deteção.
- Escreva o motivo e carregue em «Adicionar às regras de exclusão». O motivo fica no relatório.
- 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ão | O que faz |
|---|---|
| Guardar relatório (Markdown) | Guarda o relatório do diagnóstico num ficheiro Markdown |
| Copiar resumo | Copia 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.
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). Com a investigação passo a passo, a resposta a uma consulta pode incluir até 14 linhas de registo como evidência por deteção.
- 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 comoip-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». 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.
- 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).
- Os endereços IP, domínios, números CVE e hashes que o LLM escreve são comparados com o que ele recebeu (resumo e linhas de evidência). Um valor que não aparece nesse material consta na secção do LLM do relatório e no ecrã em «Valores que não constam do material recolhido», como possível invenção. Só se comparam cadeias de texto; o LLM não é consultado.
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ção | O que faz |
|---|---|
--auto | Procura registos nas localizações padrão e noutras, e diagnostica-os. Com --since 7d pode restringir-se o período |
--report FILE | Escreve um relatório em Markdown |
--format json|csv|sarif|brief-json | Altera 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|low | Se existirem deteções dessa gravidade ou superior, termina com o código de saída 3 |
--fail-on-partial | Termina com o código de saída 4 quando há partes que não puderam ser verificadas, como registos ilegíveis |
--since-last、--new-only | Compara com a vez anterior e mostra apenas as deteções novas |
--llm NAME、--show-prompt | Faz 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|cron | Mostra 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-investigate | Usa-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 |
--notify | Usa-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 check | Verifica 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"]
- 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 seuexpiresnã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.
- Foram testados com resultados reais: Envoy (incluindo o formato do Istio), Google Cloud Run, o CRI do containerd, o registo geral do MySQL, o registo do MariaDB Audit Plugin, os registos de execução do anfitrião e o registo de auditoria do Linux (Ubuntu e AlmaLinux). Os registos do AWS ALB, CloudFront, Cloudflare, dos balanceadores de carga do Google Cloud e do Podman foram testados apenas com linhas criadas segundo a documentação de cada fornecedor, e não com resultados reais.
- Os registos de execução do anfitrião não têm IP. Ligam-se a um ataque Web apenas pelos 5 segundos que o seguem, por isso um processo alheio no mesmo momento pode ser emparelhado. Se os relógios do registo Web e dos registos do anfitrião não coincidirem, perde-se um emparelhamento ou liga-se outro evento.
- Uma suspeita de túnel HTTP (web_tunnel_suspect) não pode ser confirmada, porque o registo não contém o corpo dos pedidos. O webhook de um serviço de pagamento tem o mesmo aspeto. As deteções de reconhecimento de API e de ficheiros estáticos são sempre de gravidade baixa e nunca entram numa lista de bloqueio, porque rastreadores, monitorização e testes de intrusão têm o mesmo aspeto.
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»
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.