AccessScope User Manual

This manual explains how to use a diagnosis tool that finds attack attempts in your server access logs and shows the log lines behind each finding. It covers the steps in the app first, and chapter 8 collects how to use the command line.

1. About AccessScope

AccessScope reads the logs that your web server or SSH server already keeps and looks for attack attempts. Every finding is shown together with the log lines it is based on. It suits people who run their own servers and want to check whether suspicious requests are left in the logs.

AccessScope only reads your logs. It never changes or deletes them, never blocks traffic, and never raises privileges. The diagnosis itself uses neither an LLM nor the network.

On Mac, AccessScope is included in the RoamSwitch DMG. On Linux, it is included in the RoamSwitch deb, rpm and tarball. It is a separate tool from RoamSwitch and is licensed under the Apache License 2.0. To start it, choose the app icon on Mac, or choose 'AccessScope' in the app list on Linux.

Saved files

AccessScope saves your settings, the list of logs it found, your suppression rules and the record used to compare with the previous run. All of them are placed under ~/.config/accessscope/ with permissions that only you can read and write.

Updates

On Mac, AccessScope connects to lafine.net only when you press 'Check for updates' under 'Updates' in Settings. It sends no information about your machine or your logs, and it verifies the signature of a downloaded file before installing it. Linux has no in-app update, so you update through your package manager.

2. Your First Diagnosis

1. Choose your logs. The easiest way is 'Find logs on this machine'. It looks for nginx, Apache, SSH and other logs automatically and lists them under 'Logs found on this machine'. If you already know where a log is, pick it with 'Choose files' or 'Choose a folder', or drop the file or folder onto the window.
2. Choose the 'Period'. The default is 'Last 7 days', and you can change it to 'Last 24 hours', 'Last 30 days' or 'All'. The period is counted back from now, so choose 'All' when you want to diagnose old logs.
3. Press 'Run diagnosis'. Progress appears as 'Reading logs' and 'Analyzing', and the results open when it finishes.

3. Supported Logs and Where to Find Them

AccessScope detects the type of a log from its contents. Rotated logs compressed with gzip can be read as they are. If you choose a folder, it reads all the files in it that look like logs.

'Find logs on this machine' checks the standard locations and the log locations that your web server configuration files point to. Only files confirmed to be readable as logs are listed.

Docker containers

If you tick 'Also check Docker containers', the Docker logs on this machine are included too. Before the diagnosis, the confirmation screen shows the commands that will run and the target containers, and AccessScope reads them only after you press 'Agree and diagnose'. It only reads and never raises privileges.

Searching for logs with an LLM (optional)

If nothing is found, you can ask an LLM to look for the locations with 'Also search with an LLM'. Only facts about the environment are passed, such as the names of running servers and the names of files in places like /var/log. The contents of the files are not passed. Suggestions appear with their checkboxes cleared, after AccessScope has confirmed that they can be read. See chapter 7 for the settings.

4. Reading the Results

When the diagnosis finishes, you can check the results in four tabs.

How to read a finding

A finding is shown by name, such as 'SQL injection attempts', and has a severity (High, Medium, Low) and a confidence. Confidence tells you how much can be said from the logs alone.

• Confirmed means something the logs alone can show.
• Likely means the attempt probably happened.
• Hypothesis means something the logs alone cannot confirm.

Open the 'Evidence lines' to see, exactly as they are, the log lines that a finding is based on. They are closed by default, so read the name and the reason first and open only the ones you are curious about.

The overall risk (0 to 100) is a guide weighted by severity and confidence. It does not grow just because there are many findings, and it never becomes 'High' unless there is at least one High severity finding. It is not a probability, so please treat it only as a guide.

5. Reducing What You Have to Review

Suppression rules

Findings that you already know will appear, such as your office IP, uptime monitoring or your own vulnerability scans, can be removed from the report. Removed findings are not thrown away. Their counts are kept together with the reason.

1. In the 'Findings' tab, press 'Exclude this IP...' next to the IP of a finding.
2. Enter a reason and press 'Add to suppression rules'. The reason is kept in the report.
3. Check the details in the confirmation dialog and approve. The rule takes effect from the next diagnosis.

'Suppression rules' in Settings lists the rules that are currently active. It is for viewing only, and you cannot edit rules there. Rules with detailed conditions go in a file in the settings folder (suppress.toml), and chapter 8 explains how to write it. Findings with a High severity are not removed even if they match a rule, and they stay in the report.

Comparison with the previous run

When you diagnose the same combination of logs repeatedly, AccessScope compares with the previous record and marks newly appeared findings as 'New'. Tick 'New only' in the 'Findings' tab to show only the new ones. On the first run, every finding is treated as new. The record contains only the fingerprint (hash) of each finding, its type, severity, count and time, and never the text of your logs.

6. Exporting Results

The buttons at the top of the results screen let you take the results out of the app.

With 'Export…' you can choose fail2ban-ip, nftables, ipset, nginx-deny, apache-require or csv as the blocklist format. The list of findings can be exported as CSV, SARIF or JSON.

For a blocklist you can choose 'What to include' from 'default', 'stricter' and 'wider', and the number of IPs to be exported is shown before you save. IPs of official crawlers and IPs covered by suppression rules are never included.

7. Analysis with an LLM (Optional)

This feature has an LLM write up the diagnosis results as text. It is off by default. To use it, tick 'Enable analysis with an LLM' under 'LLM integration' in Settings, choose the 'LLM to use' and press 'Save'. You can choose from claude, opencode, codex and agy, limited to those whose command is installed on the machine.

What is sent

• Raw logs are not sent. What is sent is the statistics, the facts of each finding, and up to 3 evidence log lines per finding (up to 300 characters per line).
• Secrets such as keys, tokens and passwords, and email addresses, are masked before sending.
• IPs are passed in a defanged form such as 203[.]0[.]113[.]9. If you tick 'Do not send real IPs (use pseudonyms)', they are replaced with pseudonyms such as ip-001.

Press 'Show exactly what will be sent' in the 'Analyze with LLM' tab to see the whole text that will be sent. This does not send anything. Data is sent for the first time when you press 'Analyze with LLM'.

• The contents of a log can be written by an attacker. AccessScope reports strings that look like instructions to an AI as findings, and it shows LLM output as untrusted quotation. An LLM may also read a finding as more serious than it really is, so confirm any conclusion against the evidence log lines.
• For claude and opencode, AccessScope starts them with their tools (running commands and reading files) disabled. codex and agy cannot have their tools disabled, so you need to tick the confirmation shown in Settings. LLM analysis can be used as root too, but the LLM then runs with root's rights, so an unprivileged user is recommended (a note is shown in Settings while the app runs as root).

8. Using the Command Line

In a command-only environment such as the Server Edition, or when you want to run it regularly with cron, use the accessscope command. It uses the same engine as the app, so it finds the same findings.

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

Running it daily with cron

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

It shows only the findings that were not in the previous run, and ends with exit code 3 only when a new finding is Medium or higher. A diagnosis without --llm also works as root.

How to write suppress.toml

Write suppression rules in ~/.config/accessscope/suppress.toml. If this file exists, it is read automatically.

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

• A rule applies to requests that match every item written in it. reason is required and appears in every report. A rule past its expires date is not applied.
• A finding with a High severity is not removed unless the rule has allow_high = true.
• The User-Agent and the path are values that a client can write. A rule that uses only those, without an IP, cannot remove findings such as attacks, authentication and web shells.

9. What AccessScope Cannot Do

• AccessScope can see only the facts that remain in the logs. It cannot know the request body, the contents of responses, the internal state of an application, or periods that were rotated away. No findings does not prove that you are safe.
• A finding means that an attempt happened, and it is not evidence that the attempt succeeded. A User-Agent is self-reported and can be spoofed.
• A chain that spans several logs is based only on the fact that the address is the same. Behind NAT or a proxy, unrelated people can look like the same address. Internal addresses (a reverse proxy or a Docker gateway) stand for many clients at once, so they are not put into a chain. A chain with no sign of success gets the low severity.
• 'Logins from an unfamiliar source' means unfamiliar to that log, and it is not necessarily unauthorized. 'Changes from the usual' only shows a change, and it is not necessarily an attack.
• AWS ALB and CloudFront logs were tested with lines built from the AWS documentation, and have not been tested with real AWS output.

10. Troubleshooting

It appears under 'Logs that cannot be read right now'

This is shown when permissions are missing. AccessScope does not raise privileges to read logs. Please deal with it in one of the following ways.

• For file logs, start AccessScope as a user with permission, or copy the log and choose the copy with 'Choose files'.
• For journald on Linux, start it as root or as a user in the adm, systemd-journal or wheel group.
• For the macOS unified log, start it as a user in the admin group.

'No logs that can be diagnosed were found' appears

The reason is shown as a sentence, for example 'There are no web server logs (Apache, nginx and so on)'. On Mac, when there are no SSH records, it shows 'Remote Login (SSH) may be switched off'. You can try the next step with 'Choose files', 'Search with an LLM' or 'Choose another location' shown on the screen. To see where AccessScope looked, open the closed 'Detailed search results'.

'The Docker logs could not be read' appears

This means one of the following: Docker is not running, Docker was not found, there is no permission, or Docker returned an error. When there is no permission, start AccessScope as a user who can use Docker. AccessScope does not read again with raised privileges, and it does not ask you or advise you to join the docker group, because docker group permission is equivalent to root on the host.

'Not readable as a log' appears

This is shown when not a single line could be parsed from the file you chose. That file is not diagnosed and is not sent anywhere. Check whether it is a supported type of log, and choose again.

'Analyze with LLM' cannot be pressed

The reason appears near the button. If it says 'LLM integration is off', turn it on in Settings. If it says 'No LLM is selected', choose one in Settings. It also cannot be used when you are running as root, or when the command of the LLM you want to use is not installed on the machine.

All the access sources are proxy IPs

In logs behind a reverse proxy or a CDN, the access source can become the IP of the proxy. With the default 'Automatic', the client IP is taken from X-Forwarded-For only for lines whose recorded source is an internal address, such as a reverse proxy or a Docker gateway. Lines that came directly from outside keep the recorded source. Because the header can be forged, an IP decided this way is never treated as a verified crawler. To turn this off, choose 'Do not use' under 'Analysis' in Settings. You can also choose to use the first address from the right that is not a trusted proxy, or the leftmost address; clients can rewrite this value, so use these only behind a relay you manage and trust. It takes effect from the next diagnosis.