Manuale d'uso di AccessScope

Questa guida spiega come usare uno strumento di diagnosi che trova i tentativi di attacco nei log di accesso di un server e mostra la riga di log che li dimostra. Prima viene spiegata la diagnosi dalla finestra, mentre l'uso da riga di comando è raccolto nel capitolo 8.

1. Che cos'è AccessScope

AccessScope è uno strumento di diagnosi che legge i log già prodotti dai server web e SSH e cerca tentativi di attacco. Ogni risultato viene mostrato insieme alla riga di log che lo dimostra. È adatto a chi gestisce un proprio server e vuole verificare se nei log sono rimasti accessi sospetti.

I log vengono solo letti. Non vengono modificati né cancellati, non viene bloccata alcuna comunicazione e non vengono elevati i privilegi. La diagnosi in sé non usa né un LLM né la rete.

Su Mac è inclusa nel DMG di RoamSwitch, mentre su Linux è inclusa nei pacchetti deb, rpm e tarball di RoamSwitch. È uno strumento indipendente da RoamSwitch e la licenza è Apache License 2.0. Per avviarla, su Mac si sceglie l'icona dell'app, mentre su Linux si sceglie «AccessScope» nell'elenco delle applicazioni.

File salvati

AccessScope salva automaticamente le impostazioni, l'elenco dei log trovati, le regole di esclusione e il registro del confronto con la volta precedente. Tutto viene collocato in ~/.config/accessscope/ con permessi di lettura e scrittura solo per l'utente stesso.

Aggiornamenti

Su Mac, la connessione a lafine.net avviene solo quando si preme «Verifica aggiornamenti» in «Aggiornamenti» nelle impostazioni. Non vengono inviate informazioni su questo computer né sui log, e il file scaricato viene installato dopo aver verificato la firma. Su Linux non c'è l'aggiornamento dentro l'app, quindi si aggiorna con l'aggiornamento dei pacchetti.

2. La prima diagnosi

1. Scegli i log. Il modo più semplice è «Cerca i log su questo computer». Cerca automaticamente i log di nginx, Apache, SSH e altri, e li elenca in «Log trovati su questo computer». Se sai già dove si trovano, usa «Scegli file» o «Scegli una cartella», oppure trascina file o cartelle sulla finestra.
2. Scegli il «Periodo». Il valore iniziale è «Ultimi 7 giorni» e si può cambiare in «Ultime 24 ore», «Ultimi 30 giorni» o «Tutti». Il periodo viene contato a partire da adesso, quindi per diagnosticare log vecchi scegli «Tutti».
3. Premi «Esegui diagnosi». Compare l'avanzamento con «Lettura dei log» e «Analisi in corso», e al termine si apre il risultato.

3. Log leggibili e dove cercarli

Il tipo di log viene riconosciuto automaticamente guardandone il contenuto. Anche i log ruotati e compressi con gzip vengono letti così come sono. Se si sceglie una cartella, vengono letti in blocco i file che sembrano log.

«Cerca i log su questo computer» controlla le posizioni standard e le posizioni dei log indicate dai file di configurazione del server web. Nell'elenco compare solo ciò di cui è stata verificata la leggibilità come log.

Container Docker

Se si seleziona «Controlla anche i container Docker», si possono includere anche i log di Docker di questo computer. Prima della diagnosi, la schermata di conferma mostra i comandi che verranno eseguiti e i container interessati, e i log vengono letti solo quando si preme «Accetta e diagnostica». È solo lettura e non vengono elevati i privilegi.

Cercare i log con un LLM (facoltativo)

Se non si trova nulla, con «Cerca anche con un LLM» si può chiedere a un LLM di cercare le posizioni. Gli vengono passati solo dati sull'ambiente, come il nome dei server in esecuzione e i nomi dei file in /var/log e simili, mai il contenuto dei file. I suggerimenti compaiono con la casella non selezionata, dopo aver verificato che si possono leggere. Per le impostazioni, vedi il capitolo 7.

4. Come leggere i risultati

Al termine della diagnosi, il risultato si può consultare in quattro schede.

Come leggere un rilevamento

I rilevamenti vengono mostrati con un nome, come «Tentativi di SQL injection», e hanno una gravità (Alta, Media, Bassa) e un'attendibilità. L'attendibilità indica fino a che punto si può affermare qualcosa solo con il log.

• Confermato è ciò che si può affermare solo con il log.
• Probabile indica un'alta probabilità che il tentativo ci sia stato.
• Ipotesi è ciò che non si può verificare solo con il log.

Aprendo «Righe di evidenza» si vedono così come sono le righe di log su cui si basa quel rilevamento. Di solito sono chiuse, quindi leggi prima il nome e il motivo, e apri solo quelle che ti sembrano interessanti.

Il rischio complessivo (da 0 a 100) è un indicatore ponderato in base a gravità e attendibilità. Non cresce solo perché i rilevamenti sono tanti, e se non c'è nemmeno un rilevamento di gravità alta non arriva a «Alto». Non è una probabilità, quindi consideralo solo come indicazione.

5. Ridurre ciò che si vede

Regole di esclusione

I rilevamenti che si sa già che compariranno, come l'IP del proprio ufficio, il monitoraggio della disponibilità o le proprie scansioni di vulnerabilità, si possono togliere dal rapporto. I rilevamenti tolti non vengono scartati, ma ne viene conservato il numero insieme al motivo.

1. Nella scheda «Rilevamenti», premi «Escludi questo IP…» accanto all'IP del rilevamento.
2. Inserisci il motivo e premi «Aggiungi alle regole di esclusione». Il motivo resta nel rapporto.
3. Controlla il contenuto nella finestra di conferma e approvalo. Ha effetto dalla diagnosi successiva.

In «Regole di esclusione» nelle impostazioni compare l'elenco delle regole attive. È solo da consultare e qui non si può modificare. Le regole con condizioni dettagliate si scrivono in un file (suppress.toml) da collocare nella cartella delle impostazioni. Il modo di scriverlo è nel capitolo 8. I rilevamenti di gravità «Alta» non vengono tolti anche se esclusi e restano nel rapporto.

Confronto con la volta precedente

Se si diagnostica più volte di seguito la stessa combinazione di log, viene confrontata con il registro precedente e i rilevamenti comparsi per la prima volta ricevono il contrassegno «Nuova». Se nella scheda «Rilevamenti» si seleziona «Solo nuovi», si filtrano solo i nuovi. La prima volta sono tutti trattati come nuovi. Nel registro entrano solo l'impronta (hash) del rilevamento, il tipo, la gravità, il numero e l'ora, mai il testo dei log.

6. Esportare i risultati

Con i pulsanti nella parte alta della schermata dei risultati si possono portare fuori i risultati.

In «Esporta…» si può scegliere come formato della lista di blocco fail2ban-ip, nftables, ipset, nginx-deny, apache-require o csv. L'elenco dei rilevamenti si può esportare in CSV, SARIF o JSON.

Per la lista di blocco si può scegliere «Cosa includere» tra «predefinito», «più rigido» e «più ampio», e il numero di IP che verranno esportati viene mostrato prima del salvataggio. Gli IP dei crawler ufficiali e gli IP interessati dalle regole di esclusione non vengono mai inclusi.

7. Analisi con un LLM (facoltativa)

È una funzione che fa riassumere in un testo a un LLM il risultato della diagnosi. È disattivata per impostazione predefinita. Per usarla, in «Integrazione LLM» nelle impostazioni seleziona «Attiva l'analisi con un LLM», scegli il «LLM da usare» e premi «Salva». Si può scegliere tra claude, opencode, codex e agy, quelli il cui comando è installato sul computer.

Cosa viene inviato

• I log grezzi non vengono inviati. Vengono inviati le statistiche e i dati dei rilevamenti, e per ogni rilevamento al massimo 3 righe di log come evidenza (fino a 300 caratteri per riga).
• I segreti, come chiavi, token e password, e gli indirizzi email vengono oscurati prima dell'invio.
• Gli IP vengono passati in forma neutralizzata, come 203[.]0[.]113[.]9. Se si seleziona «Non inviare IP reali (usare pseudonimi)», vengono sostituiti da pseudonimi come ip-001.

Premendo «Mostra esattamente cosa verrà inviato» nella scheda «Analizza con LLM» si vede il testo completo che verrà inviato. Con questa azione non viene inviato nulla. L'invio avviene per la prima volta solo quando si preme «Analizza con LLM».

• Il contenuto dei log può essere scritto da un attaccante. AccessScope segnala come rilevamento le stringhe che sembrano istruzioni per un'IA e mostra l'output del LLM come una citazione di cui non fidarsi. Un LLM può anche interpretare un rilevamento come più grave di quanto sia, quindi verifica le conclusioni con le righe di log che le dimostrano.
• Con claude e opencode, AccessScope li avvia con gli strumenti (esecuzione di comandi e lettura di file) disattivati. Con codex e agy non è possibile disattivare gli strumenti, quindi bisogna selezionare la conferma che compare nelle impostazioni. L'analisi con LLM può essere usata anche come root, ma l'LLM gira allora con i privilegi di root; si consiglia un utente senza privilegi (le impostazioni mostrano una nota finché l'app gira come root).

8. Uso da riga di comando

In ambienti con soli comandi, come Server Edition, o quando si vuole eseguire periodicamente con cron, si usa il comando accessscope. È lo stesso motore della finestra, quindi i rilevamenti trovati sono gli stessi.

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

Eseguirlo ogni giorno con cron

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

Mostra solo i rilevamenti che non c'erano nell'esecuzione precedente, e termina con il codice di uscita 3 solo quando i rilevamenti nuovi sono di gravità media o superiore. La diagnosi senza --llm funziona anche come root.

Come si scrive suppress.toml

Le regole di esclusione si scrivono in ~/.config/accessscope/suppress.toml. Se il file esiste, viene letto 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"]

• Una regola si applica alle richieste che corrispondono a tutti i campi scritti. reason è obbligatorio e compare in tutti i rapporti. Le regole oltre il loro expires non vengono applicate.
• I rilevamenti di gravità «Alta» non vengono tolti se la regola non contiene allow_high = true.
• Lo User-Agent e il percorso sono valori che il client può scrivere. Una regola che non includa l'IP e si limiti a questi non può togliere rilevamenti di attacchi, di autenticazione, di web shell e simili.

9. Cosa non può fare

• Si vede solo ciò che è rimasto nei log. Non si conoscono il corpo delle richieste, il contenuto delle risposte, lo stato interno dell'applicazione né il periodo perso con la rotazione dei log. L'assenza di rilevamenti non dimostra che sia tutto sicuro.
• Un rilevamento significa che «c'è stato un tentativo» e non è la prova che sia riuscito. Lo User-Agent è un'autodichiarazione e può essere falsificato.
• Le catene che attraversano più log si basano solo sul fatto che l'indirizzo è lo stesso. Dietro un NAT o un proxy, persone senza relazione appaiono con lo stesso indirizzo. Gli indirizzi interni (un reverse proxy o un gateway Docker) rappresentano molti client insieme, quindi non entrano in una catena. Una catena senza segni di riuscita riceve la gravità «bassa».
• «Accessi da un'origine insolita» significa che l'origine è insolita per quel log, e non è detto che sia fraudolento. «Scostamenti dal solito» indica soltanto un cambiamento e non è detto che sia un attacco.
• I log di AWS ALB e CloudFront sono stati provati con righe create secondo le definizioni della documentazione AWS, e non con output reali di AWS.

10. Se qualcosa non funziona

Compare in «Log non leggibili al momento»

È ciò che viene mostrato quando mancano i permessi. AccessScope non eleva i privilegi per leggere. Risolvi con una delle opzioni seguenti.

• Per i log in file, avvia con un utente che abbia i permessi, oppure scegli una copia del log con «Scegli file».
• Per journald su Linux, avvia come root oppure con un utente dei gruppi adm, systemd-journal o wheel.
• Per il log unificato di macOS, avvia con un utente del gruppo admin.

Compare «Non sono stati trovati log diagnosticabili»

Il motivo viene mostrato in una frase. Per esempio compare «Non ci sono log di server web (Apache, nginx e così via)». Su Mac, quando non ci sono registrazioni SSH, compare «L'accesso remoto (SSH) potrebbe essere disattivato». Con «Scegli file», «Cerca con un LLM» e «Indica un'altra posizione», che compaiono sullo schermo, si può provare il passo successivo. Per sapere dove si è cercato, apri «Risultato dettagliato della ricerca», che è chiuso.

Compare «Non è stato possibile leggere i log di Docker»

Può essere una di queste cause, Docker non è in esecuzione, Docker non si trova, mancano i permessi oppure Docker ha restituito un errore. Se mancano i permessi, avvia AccessScope con un utente che può usare Docker. AccessScope non rilegge elevando i privilegi, né chiede o consiglia di entrare nel gruppo docker, perché i permessi del gruppo docker equivalgono a quelli di root sull'host.

Compare «Non è stato possibile leggerlo come log»

È ciò che viene mostrato quando non è stato possibile analizzare nemmeno una riga del file scelto. Quel file non rientra nella diagnosi e non viene inviato da nessuna parte. Verifica se è un tipo di log supportato e sceglilo di nuovo.

Non si può premere «Analizza con LLM»

Vicino al pulsante compare il motivo. Se compare «L'integrazione LLM è disattivata», attivala nelle impostazioni. Se compare «Nessun LLM selezionato», sceglilo nelle impostazioni. Non si può usare nemmeno se è stato avviato come root o se il comando del LLM da usare non è installato sul computer.

L'origine degli accessi è sempre l'IP del proxy

Nei log dietro un reverse proxy o una CDN, l'origine dell'accesso può essere l'IP del proxy. Con il valore iniziale «Automatico», l'IP del client viene ricavato da X-Forwarded-For solo per le righe la cui origine registrata è un indirizzo interno, come un reverse proxy o un gateway Docker. Le righe arrivate direttamente dall'esterno mantengono l'origine registrata. Poiché l'intestazione può essere falsificata, un IP ricavato in questo modo non viene mai trattato come crawler verificato. Per disattivarlo, scegli «Non usare» in «Analisi» nelle impostazioni. Si può anche scegliere il primo indirizzo da destra che non sia un proxy fidato, oppure l'indirizzo più a sinistra; poiché il client può riscrivere questo valore, usali solo dietro un intermediario fidato che gestisci tu. Ha effetto dalla diagnosi successiva.