Advertisement
Open Source Projects by Phil Schwartz

Building a Python Heatmap for Failed Logins by IP

Raw SSH logs can bury useful patterns beneath thousands of rejected passwords. A compact visualisation can reveal when particular source addresses are active, whether failures arrive in short bursts and how their behaviour changes throughout the day.

The script developed here reads common Linux authentication formats, normalises IPv4 and IPv6 addresses, aggregates failures by IP and hour, and renders a heatmap with Matplotlib. It keeps the raw log separate from the image while exporting a CSV summary for further investigation, making it suitable for a small Linux server or an Australian hosting environment.

Choose the heatmap's scope

A heatmap needs clearly defined dimensions. This design places source IP addresses on the vertical axis and hours of the day on the horizontal axis. Each cell represents the number of failed authentication events attributed to that address during that hour, with darker cells indicating greater activity.

The visualisation measures temporal concentration rather than physical location. Mapping an address to Sydney, Melbourne or another city can be misleading because hosting providers, VPNs and carrier-grade NAT obscure the real origin. The hourly matrix is therefore better suited to identifying automated retries and determining when defensive action may be most effective.

Handle Australian time zones

Australia spans several time zones: Perth uses AWST, Adelaide uses ACST, Brisbane uses AEST, and Sydney and Melbourne usually observe AEDT during daylight saving time. Adelaide’s half-hour offset and the varying daylight saving rules make local-time reporting more complicated than simply labelling every log with “UTC+10”.

Keep the imported timestamps in UTC, then convert them to the time zone of the server being investigated. Python’s zoneinfo module handles these conversions and daylight saving transitions without relying on obsolete time-zone libraries.

from datetime import datetime
from zoneinfo import ZoneInfo

local_time = datetime.fromisoformat(timestamp).astimezone(
    ZoneInfo("Australia/Sydney")
)

The selected zone should be configurable rather than inferred from the analyst’s own computer. It should also appear in the chart title or accompanying CSV so that a later reader can interpret the hourly columns correctly.

Parse and normalise log events

On systemd-based Linux hosts, exporting the journal in ISO format provides reliable timestamps and avoids guessing the year when processing rotated files. Adjust the unit name if the server uses sshd.service rather than ssh.service.

journalctl -u ssh.service --since "7 days ago" \
  --utc --output=short-iso --no-pager > ssh-events.log

A regular expression can isolate the relevant fields from each event:

EVENT = re.compile(
    r"^(?P<time>\S+).*?\bFailed (?P<method>password|publickey) "
    r"for (?:invalid user )?(?P<user>\S+) from "
    r"(?P<ip>\S+) port (?P<port>\d+)"
)

Traditional /var/log/auth.log files require extra care because their timestamps omit the year and time zone. The script should not automatically attach the current year to every record, as that would corrupt data around New Year. Failed public-key attempts should also be counted separately because clients often offer a key before falling back to a password.

Aggregate failures by IP

After parsing, store each accepted event as a structured record containing its timestamp, source address, method and target username. Pandas can then convert the timestamps and build the matrix used by the visualisation.

frame = pd.DataFrame(records)
frame["time"] = pd.to_datetime(frame["time"], utc=True)
frame["hour"] = frame["time"].dt.tz_convert(zone).dt.hour

counts = pd.crosstab(frame["ip"], frame["hour"])
counts = counts.reindex(columns=range(24), fill_value=0)

Exact addresses provide the clearest operational view, but distributed attacks can create hundreds of rows. An optional mode can aggregate IPv4 addresses into /24 networks and IPv6 addresses into /64 networks, while retaining the original data separately. Counts should also be compared with successful logins from the same source before classifying an address as hostile.

Render the matrix

Matplotlib is sufficient to produce a static chart without a browser-based dashboard. A power-normalised colour scale makes small counts visible alongside large bursts, while viridis remains legible for most forms of colour vision deficiency.

import matplotlib.pyplot as plt
from matplotlib.colors import PowerNorm

values = chart.to_numpy()
norm = PowerNorm(gamma=0.5, vmin=0, vmax=max(1, values.max()))

fig, ax = plt.subplots(figsize=(14, max(3, len(chart) * 0.32)))
image = ax.imshow(values, aspect="auto", cmap="viridis", norm=norm)

ax.set_xticks(range(24))
ax.set_yticks(range(len(chart)), labels=chart.index)
ax.set_xlabel("Hour of day")
ax.set_ylabel("Source IP")
fig.colorbar(image, ax=ax, label="Failed attempts")
fig.tight_layout()
fig.savefig("failed-logins.png", dpi=180)

The PNG is useful for quick review, but the CSV should remain the authoritative output. If the graphic will be published externally, replace exact addresses with keyed hashes or network prefixes and keep the mapping between them and the original addresses restricted.

Use the findings defensively

The heatmap can distinguish a concentrated automated attack from ordinary password mistakes. Sustained activity across every hour suggests a scripted or distributed operation, while failures concentrated around Australian office hours may reflect users, shared services or mistyped credentials.

IP geolocation requires particular caution. Addresses hosted in Australian cloud regions such as AWS Sydney and Melbourne or Azure Australia East may appear local even when the operator is overseas. Shared corporate networks, university campuses and mobile carrier connections can also give many legitimate users a single public address. Blocking one such address could interrupt staff across an entire office.

Heatmap findings should inform rate limits, temporary firewall rules and alerts rather than trigger permanent bans automatically. DenyHosts can apply a separate SSH blocking policy, while the chart helps an administrator judge whether a threshold is reasonable. The Australian Cyber Security Centre’s guidance on multifactor authentication, patching, secure configuration and retained logs provides a useful foundation for any response.

Package the script for reuse

A reliable command-line interface should accept the log path, time zone, minimum display threshold, image path and CSV output path. Using Python 3.9 or later keeps zoneinfo available, while Pandas and Matplotlib can be installed through a small requirements.txt file.

python failed_login_heatmap.py ssh-events.log \
  --timezone Australia/Sydney --min-count 5 \
  --output failed-logins.png

The project should include synthetic test logs covering IPv4, IPv6, invalid users, daylight saving changes and malformed lines. Documentation can use DD/MM/YYYY dates and Australian English conventions such as “colour” and “licence”. Publishing the code under an MIT licence, with versioned releases and sample output, makes the utility suitable for open-source use.

This small analyser complements DenyHosts by revealing patterns before or alongside automated blocking. It also shares the diagnostic purpose of Scratchy and Kodos: turning dense operational data into a visual form that can be examined quickly and acted upon with context.