From 5e1e6adac4d1c56725ccc427472cbfa20a5938c3 Mon Sep 17 00:00:00 2001 From: TPOALOS <351316698+TPOALOS@users.noreply.github.com> Date: Sun, 8 Nov 2026 01:46:07 +0300 Subject: [PATCH] Add JSON, ISO timestamps, subnet grouping, --ignore, packaging and CI (v1.1.0) --- .github/workflows/tests.yml | 30 ++++++++ CHANGELOG.md | 14 ++++ README.md | 12 ++- authlog_summary.py | 132 +++++++++++++++++++++++++++++---- pyproject.toml | 29 ++++++++ test_authlog_summary.py | 142 ++++++++++++++++++++++++++++++++++++ 6 files changed, 344 insertions(+), 15 deletions(-) create mode 100644 .github/workflows/tests.yml create mode 100644 CHANGELOG.md create mode 100644 pyproject.toml diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..2bacbe6 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,30 @@ +name: tests + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + test: + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, macos-latest] + python-version: ["3.10", "3.12", "3.13"] + include: + - os: macos-latest + python-version: "3.9" + steps: + - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4 + with: + persist-credentials: false + - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5 + with: + python-version: ${{ matrix.python-version }} + - name: Unit tests + run: python -m unittest -v diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..0c010b1 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,14 @@ +# Changelog + +## 1.1.0 + +- `--json` output +- ISO-8601 timestamps (rsyslog high precision, `journalctl -o short-iso`) +- `--by-subnet` groups failures by /24 or /64 to expose distributed attacks +- `--ignore IP_OR_CIDR` leaves your own hosts out +- Reports successful root logins, password logins and pre-auth drops +- Installable with pip (`authlog-summary` command), CI on Linux and macOS + +## 1.0.0 + +Initial release. diff --git a/README.md b/README.md index ef7f61c..a5044e2 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,9 @@ Read-only and standard library only. It reports; it never blocks anything. - Most targeted usernames - Failures by hour of day - IPs that **logged in successfully after failing** (worth investigating) +- Successful **root** logins and how many logins used a password instead of a key +- Pre-auth drops (`Connection closed by invalid user ... [preauth]`) per IP +- With `--by-subnet`: failures grouped by /24 (IPv4) or /64 (IPv6), which exposes attacks spread over many addresses - With `--suggest`: IPs over the threshold, one per line, for *your* review before adding them to a firewall or fail2ban list @@ -18,12 +21,19 @@ Read-only and standard library only. It reports; it never blocks anything. python3 authlog_summary.py /var/log/auth.log python3 authlog_summary.py /var/log/auth.log --threshold 10 --suggest zcat /var/log/auth.log.2.gz | python3 authlog_summary.py - +python3 authlog_summary.py /var/log/auth.log --by-subnet --ignore 192.0.2.0/24 --ignore 2001:db8::1 +python3 authlog_summary.py /var/log/auth.log --json +journalctl -u ssh -o short-iso | python3 authlog_summary.py - +# or: pip install git+https://github.com/TPOALOS/authlog-summary && authlog-summary /var/log/auth.log ``` +`--ignore` leaves your own addresses or networks (monitoring, jump hosts) out of every count. + Exit codes: `0` nothing over threshold, `1` suspicious IPs found, `2` unreadable file. Recognized sshd messages: `Failed password|publickey|keyboard-interactive`, -`Invalid user`, and `Accepted ...`. IPv4 and IPv6 sources are supported. +`Invalid user`, `Accepted ...` and pre-auth `Connection closed` / `Disconnected` lines. Classic syslog timestamps +and ISO-8601 ones (rsyslog high precision, `journalctl -o short-iso`) are understood. IPv4 and IPv6 sources are supported. ## Tests diff --git a/authlog_summary.py b/authlog_summary.py index 09d8617..6031d63 100644 --- a/authlog_summary.py +++ b/authlog_summary.py @@ -9,20 +9,54 @@ """ import argparse import collections +import ipaddress +import json import re import sys -__version__ = "1.0.0" +__version__ = "1.1.0" TS = re.compile(r"^[A-Z][a-z]{2}\s+\d+\s+(\d{2}):\d{2}:\d{2}\s") +TS_ISO = re.compile(r"^\d{4}-\d{2}-\d{2}[T ](\d{2}):\d{2}:\d{2}") # rsyslog high-precision / journalctl -o short-iso FAILED = re.compile(r"sshd\[\d+\]: Failed (?:password|publickey|keyboard-interactive/pam) " r"for (?:invalid user )?(\S+) from (\S+) port \d+") INVALID = re.compile(r"sshd\[\d+\]: Invalid user (\S*) from (\S+)") -ACCEPTED = re.compile(r"sshd\[\d+\]: Accepted \S+ for (\S+) from (\S+) port \d+") +ACCEPTED = re.compile(r"sshd\[\d+\]: Accepted (\S+) for (\S+) from (\S+) port \d+") +PREAUTH = re.compile(r"sshd\[\d+\]: (?:Connection closed by|Disconnected from) (?:authenticating user|invalid user) " + r"(\S+) (\S+) port \d+ \[preauth\]") -def analyze(lines): - """Return a stats dict from an iterable of log lines.""" +def parse_ignores(items): + """CIDR/IP strings -> networks. Raises ValueError on a bad entry.""" + return [ipaddress.ip_network(i, strict=False) for i in items] + + +def is_ignored(ip, nets): + if not nets: + return False + try: + addr = ipaddress.ip_address(ip) + except ValueError: + return False + return any(addr.version == n.version and addr in n for n in nets) + + +def subnet_of(ip): + """/24 for IPv4, /64 for IPv6; the input itself when it is not an IP address.""" + try: + addr = ipaddress.ip_address(ip) + except ValueError: + return ip + return str(ipaddress.ip_network("%s/%d" % (addr, 24 if addr.version == 4 else 64), strict=False)) + + +def hour_of(line): + m = TS.match(line) or TS_ISO.match(line) + return int(m.group(1)) if m else None + + +def analyze(lines, ignore=()): + """Return a stats dict from an iterable of log lines (``ignore``: networks to leave out).""" fails = collections.Counter() users_by_ip = collections.defaultdict(set) user_targets = collections.Counter() @@ -30,32 +64,47 @@ def analyze(lines): first_fail_seen = set() success_after_fail = {} successes = 0 + root_logins, password_logins, preauth = [], 0, collections.Counter() for line in lines: m = FAILED.search(line) if m: user, ip = m.groups() + if is_ignored(ip, ignore): + continue fails[ip] += 1 users_by_ip[ip].add(user) user_targets[user] += 1 first_fail_seen.add(ip) - t = TS.match(line) - if t: - by_hour[int(t.group(1))] += 1 + hour = hour_of(line) + if hour is not None: + by_hour[hour] += 1 continue m = ACCEPTED.search(line) if m: - user, ip = m.groups() + method, user, ip = m.groups() + if is_ignored(ip, ignore): + continue successes += 1 + if method == "password": + password_logins += 1 + if user == "root": + root_logins.append(ip) if ip in first_fail_seen: success_after_fail[ip] = user continue # "Invalid user" lines duplicate Failed lines; only used to count users seen. m = INVALID.search(line) if m and m.group(1): - users_by_ip[m.group(2)].add(m.group(1)) + if not is_ignored(m.group(2), ignore): + users_by_ip[m.group(2)].add(m.group(1)) + continue + m = PREAUTH.search(line) + if m and not is_ignored(m.group(2), ignore): + preauth[m.group(2)] += 1 return {"fails": fails, "users_by_ip": users_by_ip, "user_targets": user_targets, "by_hour": by_hour, "success_after_fail": success_after_fail, - "successes": successes} + "successes": successes, "root_logins": root_logins, "password_logins": password_logins, + "preauth_drops": preauth} def suspicious(stats, threshold): @@ -63,7 +112,36 @@ def suspicious(stats, threshold): return [(ip, n) for ip, n in stats["fails"].most_common() if n >= threshold] -def render(stats, threshold, top=10): +def by_subnet(stats): + """Failures grouped by /24 (IPv4) or /64 (IPv6), with the number of distinct addresses.""" + groups = collections.defaultdict(lambda: [0, set()]) + for ip, n in stats["fails"].items(): + g = groups[subnet_of(ip)] + g[0] += n + g[1].add(ip) + return sorted(((net, n, len(ips)) for net, (n, ips) in groups.items()), key=lambda r: (-r[1], r[0])) + + +def to_json(stats, threshold, subnets=False): + data = { + "failed_logins": sum(stats["fails"].values()), + "successful_logins": stats["successes"], + "threshold": threshold, + "ips": [{"ip": ip, "failures": n, "usernames_tried": len(stats["users_by_ip"][ip]), + "over_threshold": n >= threshold} for ip, n in stats["fails"].most_common()], + "usernames": [{"user": u, "failures": n} for u, n in stats["user_targets"].most_common()], + "failures_by_hour": {"%02d" % h: n for h, n in sorted(stats["by_hour"].items())}, + "success_after_fail": [{"ip": ip, "user": u} for ip, u in sorted(stats["success_after_fail"].items())], + "root_logins": sorted(set(stats["root_logins"])), + "password_logins": stats["password_logins"], + "preauth_drops": dict(stats["preauth_drops"].most_common()), + } + if subnets: + data["subnets"] = [{"subnet": net, "failures": n, "addresses": k} for net, n, k in by_subnet(stats)] + return data + + +def render(stats, threshold, top=10, subnets=False): out = ["Failed logins: %d from %d IP(s); successful logins: %d" % ( sum(stats["fails"].values()), len(stats["fails"]), stats["successes"])] out.append("\nTop source IPs (failures, distinct usernames tried):") @@ -79,6 +157,16 @@ def render(stats, threshold, top=10): for h in sorted(stats["by_hour"]): bar = "#" * max(1, round(30 * stats["by_hour"][h] / peak)) out.append(" %02d %-30s %d" % (h, bar, stats["by_hour"][h])) + if subnets: + out.append("\nFailures by subnet (/24 IPv4, /64 IPv6):") + for net, n, k in by_subnet(stats)[:top]: + out.append(" %-40s %5d %4d address(es)" % (net, n, k)) + if stats["root_logins"]: + out.append("\nSuccessful root logins (investigate):") + for ip in sorted(set(stats["root_logins"])): + out.append(" from %s" % ip) + if stats["password_logins"]: + out.append("\nSuccessful password (not key) logins: %d" % stats["password_logins"]) if stats["success_after_fail"]: out.append("\nSuccessful login from an IP that previously failed (investigate):") for ip, user in sorted(stats["success_after_fail"].items()): @@ -93,19 +181,35 @@ def main(argv=None): help="failures per IP to flag (default 5)") ap.add_argument("--suggest", action="store_true", help="print flagged IPs one per line for your blocklist review") + ap.add_argument("--json", action="store_true", help="machine-readable output") + ap.add_argument("--by-subnet", action="store_true", + help="also group failures by /24 (IPv4) or /64 (IPv6) to expose distributed attacks") + ap.add_argument("--ignore", action="append", default=[], metavar="IP_OR_CIDR", + help="leave this address or network out (your own hosts, monitoring); repeatable") ap.add_argument("--version", action="version", version=__version__) args = ap.parse_args(argv) + try: + ignore = parse_ignores(args.ignore) + except ValueError as exc: + print("authlog-summary: bad --ignore value: %s" % exc, file=sys.stderr) + return 2 try: if args.logfile == "-": - stats = analyze(sys.stdin) + stats = analyze(sys.stdin, ignore) else: with open(args.logfile, errors="replace") as fh: - stats = analyze(fh) + stats = analyze(fh, ignore) except OSError as exc: print("authlog-summary: %s" % exc, file=sys.stderr) return 2 flagged = suspicious(stats, args.threshold) - print(render(stats, args.threshold)) + if args.json: + data = to_json(stats, args.threshold, args.by_subnet) + if args.suggest: + data["suggested_blocklist_candidates"] = [ip for ip, _ in flagged] + print(json.dumps(data, indent=2)) + return 1 if flagged else 0 + print(render(stats, args.threshold, subnets=args.by_subnet)) if args.suggest and flagged: print("\nCandidate IPs for blocklist (review before use):") for ip, _ in flagged: diff --git a/pyproject.toml b/pyproject.toml new file mode 100644 index 0000000..722452a --- /dev/null +++ b/pyproject.toml @@ -0,0 +1,29 @@ +[build-system] +requires = ["setuptools>=61"] +build-backend = "setuptools.build_meta" + +[project] +name = "authlog-summary" +version = "1.1.0" +description = "Read-only SSH auth log summarizer: failed logins per IP and subnet, root and password logins, JSON output (stdlib-only Python)." +readme = "README.md" +requires-python = ">=3.9" +license = {text = "MIT"} +authors = [{name = "TPOALOS"}] +keywords = ["ssh", "log-analysis", "brute-force", "sysadmin"] +classifiers = [ + "Environment :: Console", + "Intended Audience :: Developers", + "License :: OSI Approved :: MIT License", + "Programming Language :: Python :: 3", + "Topic :: Security", +] + +[project.urls] +Homepage = "https://github.com/TPOALOS/authlog-summary" + +[project.scripts] +authlog-summary = "authlog_summary:main" + +[tool.setuptools] +py-modules = ["authlog_summary"] diff --git a/test_authlog_summary.py b/test_authlog_summary.py index 4a57365..376df90 100644 --- a/test_authlog_summary.py +++ b/test_authlog_summary.py @@ -1,3 +1,6 @@ +import contextlib +import io +import json import os import tempfile import unittest @@ -76,5 +79,144 @@ def test_exit_codes(self): self.assertEqual(als.main(["/nonexistent/auth.log"]), 2) +def iso_fail(ip, user="root", hour="03", style="T"): + return "2026-11-07%s%s:12:01.123456+03:00 host sshd[101]: Failed password for %s from %s port 5000 ssh2" % ( + style, hour, user, ip) + + +def accept_with(method, ip, user): + return "Nov 7 09:00:00 host sshd[102]: Accepted %s for %s from %s port 6000 ssh2" % (method, user, ip) + + +def preauth(ip, user="admin", kind="Connection closed by invalid user"): + return "Nov 7 09:00:00 host sshd[103]: %s %s %s port 7000 [preauth]" % (kind, user, ip) + + +def run_main(*argv, stdin=None): + out, err = io.StringIO(), io.StringIO() + with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err): + code = als.main(list(argv)) + return code, out.getvalue(), err.getvalue() + + +class TimestampTests(unittest.TestCase): + def test_iso_timestamps_give_hours(self): + s = als.analyze([iso_fail(BAD, hour="03"), iso_fail(BAD, hour="14", style=" ")]) + self.assertEqual(dict(s["by_hour"]), {3: 1, 14: 1}) + + def test_classic_syslog_still_works(self): + self.assertEqual(dict(als.analyze([fail(BAD, hour="07")])["by_hour"]), {7: 1}) + + def test_line_without_timestamp_counts_but_has_no_hour(self): + s = als.analyze(["host sshd[1]: Failed password for root from %s port 1 ssh2" % BAD]) + self.assertEqual((s["fails"][BAD], dict(s["by_hour"])), (1, {})) + + +class NewSignalTests(unittest.TestCase): + def test_root_login_and_password_login(self): + s = als.analyze([accept_with("password", OK, "root"), accept_with("publickey", OK, "alice")]) + self.assertEqual(s["root_logins"], [OK]) + self.assertEqual((s["password_logins"], s["successes"]), (1, 2)) + + def test_preauth_drops(self): + s = als.analyze([preauth(BAD), preauth(BAD, kind="Disconnected from invalid user"), + preauth(OK, kind="Connection closed by authenticating user")]) + self.assertEqual(dict(s["preauth_drops"]), {BAD: 2, OK: 1}) + + def test_preauth_does_not_count_as_failed_login(self): + self.assertEqual(sum(als.analyze([preauth(BAD)])["fails"].values()), 0) + + def test_render_mentions_root_logins(self): + text = als.render(als.analyze([accept_with("password", OK, "root")]), 5) + self.assertIn("root logins", text) + self.assertIn("password (not key) logins: 1", text) + + +class IgnoreTests(unittest.TestCase): + def test_parse(self): + nets = als.parse_ignores(["203.0.113.7", "198.51.100.0/24", "2001:db8::/32"]) + self.assertEqual(len(nets), 3) + with self.assertRaises(ValueError): + als.parse_ignores(["not-an-ip"]) + + def test_is_ignored(self): + nets = als.parse_ignores(["198.51.100.0/24", "2001:db8::/32"]) + self.assertTrue(als.is_ignored("198.51.100.99", nets)) + self.assertTrue(als.is_ignored("2001:db8::5", nets)) + self.assertFalse(als.is_ignored("203.0.113.7", nets)) + self.assertFalse(als.is_ignored("garbage", nets)) + self.assertFalse(als.is_ignored(BAD, [])) + + def test_ignored_hosts_excluded_everywhere(self): + nets = als.parse_ignores([OK]) + s = als.analyze([fail(OK)] * 9 + [accept_with("password", OK, "root"), preauth(OK)] + [fail(BAD)], nets) + self.assertEqual(set(s["fails"]), {BAD}) + self.assertEqual((s["successes"], s["root_logins"], dict(s["preauth_drops"])), (0, [], {})) + + def test_cli_ignore_changes_exit_code(self): + with tempfile.TemporaryDirectory() as d: + p = os.path.join(d, "auth.log") + with open(p, "w") as fh: + fh.write("\n".join([fail(BAD)] * 6)) + self.assertEqual(run_main(p)[0], 1) + self.assertEqual(run_main(p, "--ignore", "203.0.113.0/24")[0], 0) + code, _, err = run_main(p, "--ignore", "nope") + self.assertEqual(code, 2) + self.assertIn("--ignore", err) + + +class SubnetTests(unittest.TestCase): + def test_subnet_of(self): + self.assertEqual(als.subnet_of("203.0.113.77"), "203.0.113.0/24") + self.assertEqual(als.subnet_of("2001:db8:1:2:3:4:5:6"), "2001:db8:1:2::/64") + self.assertEqual(als.subnet_of("weird-host"), "weird-host") + + def test_distributed_attack_visible_by_subnet(self): + lines = [] + for last in range(1, 7): + lines += [fail("203.0.113.%d" % last)] * 2 # no single IP reaches the threshold + s = als.analyze(lines) + self.assertEqual(als.suspicious(s, 5), []) + self.assertEqual(als.by_subnet(s), [("203.0.113.0/24", 12, 6)]) + self.assertIn("203.0.113.0/24", als.render(s, 5, subnets=True)) + self.assertNotIn("Failures by subnet", als.render(s, 5)) + + +class JsonTests(unittest.TestCase): + def setUp(self): + self._t = tempfile.TemporaryDirectory() + self.path = os.path.join(self._t.name, "auth.log") + lines = [fail(BAD)] * 6 + [accept_with("password", BAD, "root"), accept_with("publickey", OK, "alice")] + with open(self.path, "w") as fh: + fh.write("\n".join(lines)) + + def tearDown(self): + self._t.cleanup() + + def test_json_structure(self): + code, out, _ = run_main(self.path, "--json", "--suggest", "--by-subnet") + data = json.loads(out) + self.assertEqual(code, 1) + self.assertEqual(data["failed_logins"], 6) + self.assertEqual(data["ips"][0], {"ip": BAD, "failures": 6, "usernames_tried": 1, "over_threshold": True}) + self.assertEqual(data["root_logins"], [BAD]) + self.assertEqual(data["success_after_fail"], [{"ip": BAD, "user": "root"}]) + self.assertEqual(data["suggested_blocklist_candidates"], [BAD]) + self.assertEqual(data["subnets"][0]["subnet"], "203.0.113.0/24") + self.assertEqual(data["failures_by_hour"], {"03": 6}) + + def test_json_without_optional_sections(self): + _, out, _ = run_main(self.path, "--json") + data = json.loads(out) + self.assertNotIn("subnets", data) + self.assertNotIn("suggested_blocklist_candidates", data) + + def test_json_exit_codes_match_text(self): + self.assertEqual(run_main(self.path, "--json", "-t", "100")[0], 0) + + def test_missing_file(self): + self.assertEqual(run_main(os.path.join(self._t.name, "nope"))[0], 2) + + if __name__ == "__main__": unittest.main()