diff --git a/CHANGELOG.md b/CHANGELOG.md index 1538995..195519e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,7 +23,9 @@ All notable user-visible changes should be recorded here. ### Docs -- None yet. +- Expanded the parser conformance matrix with explicit Ubuntu / Debian + `auth.log`, RHEL-family `secure`, `journalctl --output=short-full`, `sshd`, + `sudo`, `pam_unix`, `pam_faillock`, and `pam_sss` style coverage. ## v0.4.0 diff --git a/docs/parser-conformance-matrix.md b/docs/parser-conformance-matrix.md index a827330..10e6e02 100644 --- a/docs/parser-conformance-matrix.md +++ b/docs/parser-conformance-matrix.md @@ -18,10 +18,38 @@ The parser contract is intentionally conservative: | `syslog_legacy` | `Mar 10 09:00:01 example-host program[pid]: message` | Requires `--year` or `timestamp.assume_year`; the supplied year is injected into the parsed timestamp | `input_mode = syslog_legacy`, `assume_year = `, `timezone_present = false` | [`assets/parser_fixture_matrix_syslog.log`](../assets/parser_fixture_matrix_syslog.log) | | `journalctl_short_full` | `Tue 2026-03-10 09:00:01 UTC example-host program[pid]: message` | Uses the embedded date and supported timezone token; supported tokens are `UTC`, `GMT`, `Z`, `+HHMM`, and `+HH:MM` style offsets | `input_mode = journalctl_short_full`, no assumed year, `timezone_present = true` | [`assets/parser_fixture_matrix_journalctl_short_full.log`](../assets/parser_fixture_matrix_journalctl_short_full.log) | +## Source Style Matrix + +These source labels describe common Linux log locations and command output +styles. They are not distro-detection claims. LogLens chooses a parser mode +from the line header shape, then applies the same authentication message +classifier to the message body. + +| Source style | Typical source | Parser mode | Header contract | Supported message families | Primary fixtures | +| --- | --- | --- | --- | --- | --- | +| Ubuntu / Debian `auth.log` style | `/var/log/auth.log` lines collected offline | `syslog_legacy` | BSD syslog-style timestamp without a year, followed by hostname and `program[pid]: message`; caller supplies the year | `sshd`, `sudo`, `su`, `pam_unix`, selected `pam_faillock`, selected `pam_sss` | [`assets/parser_fixture_matrix_syslog.log`](../assets/parser_fixture_matrix_syslog.log), [`assets/parser_auth_families_syslog.log`](../assets/parser_auth_families_syslog.log) | +| RHEL-family `secure` style | `/var/log/secure` lines collected offline | `syslog_legacy` | Same syslog header contract as Ubuntu / Debian `auth.log`; LogLens does not branch on distro name | `sshd`, `sudo`, `su`, `pam_unix`, selected `pam_faillock`, selected `pam_sss` | [`assets/parser_fixture_matrix_syslog.log`](../assets/parser_fixture_matrix_syslog.log), [`assets/parser_auth_families_syslog.log`](../assets/parser_auth_families_syslog.log) | +| `journalctl` short-full style | `journalctl --output=short-full` output collected offline | `journalctl_short_full` | Weekday, full date, time, timezone token, hostname, and `program[pid]: message`; embedded year is used | Same message families as `syslog_legacy` after the header is parsed | [`assets/parser_fixture_matrix_journalctl_short_full.log`](../assets/parser_fixture_matrix_journalctl_short_full.log), [`assets/parser_auth_families_journalctl_short_full.log`](../assets/parser_auth_families_journalctl_short_full.log) | + After the header is parsed, both input formats use the same authentication message classifier. A supported message should therefore normalize to the same event type in both formats. +## Program And PAM Family Style Matrix + +This matrix lists the supported program and PAM-family styles at the message +classifier layer. "Supported" means fixture-backed selected variants, not full +coverage of every distro or PAM module wording. + +| Style family | Program or tag shape | Supported variants | Expected normalized events | Unsupported boundary | +| --- | --- | --- | --- | --- | +| `sshd` | `sshd[pid]: message` or `sshd: message` | Failed password, failed password for invalid/illegal user, failed none for invalid/illegal user, direct invalid/illegal user, `input_userauth_request` invalid/illegal user, accepted password, accepted publickey, accepted keyboard-interactive/pam, failed publickey, failed keyboard-interactive/pam, maximum-authentication-attempts exceeded, and `sshd`-owned `PAM: Authentication failure` lines | `ssh_failed_password`, `ssh_invalid_user`, `ssh_accepted_password`, `ssh_accepted_publickey`, `ssh_accepted_keyboard_interactive`, `ssh_failed_publickey`, `ssh_failed_keyboard_interactive`, `ssh_max_auth_tries`, `pam_auth_failure` | Preauth close/reset, timeout/disconnection, negotiation failure, and other unsupported `sshd` messages remain parser warnings such as `sshd_connection_closed_preauth`, `sshd_timeout_or_disconnection`, `sshd_negotiation_failure`, or `sshd_other` | +| `sudo` | `sudo[pid]: : ...` or `sudo: : ...` | Command audit lines with `COMMAND=`, incorrect-password audit lines, user-not-in-sudoers denials, and command-not-allowed denials | `sudo_command`, `sudo_auth_failure`, `sudo_policy_denied` | Other well-formed sudo-like messages remain `sudo_other` parser warnings and do not count as sudo burst evidence | +| `su` | `su[pid]: message` or `su: message` | `FAILED SU (to ) on ` and `Successful su for by ` | `su_auth_failure`, `session_opened` | Other well-formed `su` messages remain `su_other` parser warnings | +| `pam_unix` | `pam_unix(:auth): ...` or `pam_unix(:session): ...` | Auth failures carrying `authentication failure` plus selected session-opened lines such as sudo/su session opens | `pam_auth_failure`, `session_opened` | Session-closed and other unsupported `pam_unix` messages remain `pam_unix_session_closed` or `pam_unix_other` parser warnings | +| `pam_faillock` | `pam_faillock(:auth): ...` | Selected auth failure variants: `Consecutive login failures for user ... from ` and `Authentication failure for user ... from ` | `pam_auth_failure` | Account-lock telemetry, auth-success telemetry, and other unmodeled variants remain `pam_faillock_account_locked`, `pam_faillock_authsucc`, or `pam_faillock_other` warnings | +| `pam_sss` | `pam_sss(:auth): ...` | Selected SSSD auth failure variant: `received for user : 7 (Authentication failure)` | `pam_auth_failure` | Unknown-user, auth-info-unavailable, and other unmodeled variants remain `pam_sss_unknown_user`, `pam_sss_authinfo_unavail`, or `pam_sss_other` warnings | + ## Supported Event Matrix | Evidence family | Supported message shape | Input formats | Expected normalized event | Field notes |