Merge branch 'main' into dependabot/github_actions/github/codeql-action-4.36.2

Author: stacknil

.gitattributes

@@ -1,12 +1,15 @@
 * text=auto
+.gitattributes text eol=lf
 *.cpp text eol=lf
 *.hpp text eol=lf
 *.h text eol=lf
 *.md text eol=lf
 *.json text eol=lf
+*.toml text eol=lf
 *.yml text eol=lf
 *.yaml text eol=lf
 *.txt text eol=lf
 *.csv text eol=lf
+*.log text eol=lf
 CMakeLists.txt text eol=lf
 CMakePresets.json text eol=lf

.github/workflows/repo-sentinel.yml

@@ -0,0 +1,36 @@
+name: Repo Sentinel
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  repo-sentinel:
+    name: Repo Sentinel
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Set up Python
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1  # v6.3.0
+        with:
+          python-version: "3.14"
+
+      - name: Install repo-sentinel-lite
+        run: |
+          python -m venv "$RUNNER_TEMP/repo-sentinel-venv"
+          "$RUNNER_TEMP/repo-sentinel-venv/bin/python" -m pip install --upgrade pip
+          "$RUNNER_TEMP/repo-sentinel-venv/bin/python" -m pip install repo-sentinel-lite
+
+      - name: Run repository hygiene gate
+        run: |
+          "$RUNNER_TEMP/repo-sentinel-venv/bin/repo-sentinel" scan \
+            --fail-on-severity error \
+            --format text \
+            .

.reposentinel.toml

@@ -0,0 +1,22 @@
+# LogLens uses repo-sentinel-lite as a narrow hygiene gate:
+# required repository files plus accidental sensitive filenames.
+#
+# High-entropy content scanning is intentionally disabled here so fixture logs
+# and C++ build outputs do not affect this gate.
+max_text_file_size = 0
+entropy_threshold = 999.0
+
+ignore_globs = [
+  "build/**",
+  "build_manual*",
+  "out/**",
+  "report.md",
+  "report.json",
+  "*.exe",
+  "CMakeFiles",
+  "CMakeFiles/**",
+  "CMakeCache.txt",
+  "cmake_install.cmake",
+  "compile_commands.json",
+  "*.vcxproj.user",
+]

CHANGELOG.md

@@ -6,10 +6,7 @@ All notable user-visible changes should be recorded here.
 
 ### Added
 
-- Added sanitized golden `report.md` / `report.json` regression fixtures to lock report contracts.
-- Expanded parser coverage for `Accepted publickey` and selected `pam_faillock` / `pam_sss` variants.
-- Added compact host-level summaries for multi-host reports.
-- Added optional CSV export for findings and warnings when explicitly requested.
+- None yet.
 
 ### Changed
 
@@ -23,6 +20,47 @@ All notable user-visible changes should be recorded here.
 
 - None yet.
 
+## v0.5.0
+
+### Added
+
+- Stabilized the JSON report artifact contract as `loglens.report.v2` with
+  `schema_version` set to `2`.
+- Added finding explainability fields to JSON findings, including `rule_id`,
+  `subject_kind`, `subject`, `grouping_key`, `window_start`, `window_end`,
+  `threshold`, `observed_count`, `evidence_event_ids`, and `verdict_boundary`.
+- Added sanitized golden `report.md`, `report.json`, `findings.csv`, and
+  `warnings.csv` regression fixtures to lock report contracts.
+- Added a 150-line sanitized mixed auth corpus fixture covering Ubuntu /
+  Debian-style `auth.log`, RHEL-family `secure`-style syslog, unknown lines,
+  malformed source IPs, and blank-line handling.
+- Added a reviewer-facing parser coverage JSON artifact for the mixed auth
+  corpus.
+
+### Changed
+
+- Made parser coverage telemetry and finding explainability part of the
+  release-facing review path instead of internal-only implementation detail.
+
+### Fixed
+
+- None.
+
+### Docs
+
+- Added release notes for the v0.5 Evidence Explainability Release.
+- Added a release readiness checklist that maps v0.5 requirements to reviewer
+  evidence and stopping points.
+- Added a one-page incident-style case that traces raw SSH evidence through
+  normalized events and finding fields to a bounded conclusion.
+- Added a rule-by-rule false-positive taxonomy for NAT, bastion, internal scanner,
+  lab replay, scheduled admin task, and shared-account contexts.
+- Added forensic-style case-study coverage for Linux auth brute-force evidence
+  interpretation.
+- 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
 
 ### Added

README.md

@@ -7,11 +7,34 @@ C++20 defensive log analysis CLI for Linux authentication logs, with parser cove
 
 It parses `auth.log` / `secure`-style syslog input and `journalctl --output=short-full`-style input, normalizes authentication evidence, applies configurable rule-based detections, and emits deterministic Markdown and JSON reports, with optional CSV exports for findings and warnings.
 
+## Example Finding
+
+A compact finding summary is a bounded triage signal, not a compromise verdict
+or attribution:
+
+```json
+{
+  "rule_id": "brute_force",
+  "subject_kind": "source_ip",
+  "subject": "203.0.113.10",
+  "grouping_key": "source_ip",
+  "window_start": "2026-03-10 08:11:22",
+  "window_end": "2026-03-10 08:18:05",
+  "threshold": 5,
+  "observed_count": 5,
+  "evidence_event_ids": ["line:1", "line:2", "line:3", "line:4", "line:5"],
+  "verdict_boundary": "triage_signal_not_compromise_or_attribution"
+}
+```
+
 ## Project Status
 
 LogLens is an MVP / early release. The repository is stable enough for public review, local experimentation, and extension, but the parser and detection coverage are intentionally narrow.
 
-Reviewing the project quickly? Start with [`docs/reviewer-path.md`](./docs/reviewer-path.md) and [`docs/reviewer-brief.md`](./docs/reviewer-brief.md).
+Reviewing the project quickly? Start with [`docs/reviewer-path.md`](./docs/reviewer-path.md), [`docs/reviewer-brief.md`](./docs/reviewer-brief.md), and the [`v0.5 Evidence Explainability release note`](./docs/release-v0.5.0.md). The [`quality gates map`](./docs/quality-gates.md) links claims to tests and fixtures. For detection reasoning, follow the [`one-page incident-style case`](./docs/incident-style-case.md), then use the full [`Linux auth brute-force case study`](./docs/case-study-linux-auth-bruteforce.md), [`rule catalog`](./docs/rule-catalog.md), and [`false-positive taxonomy`](./docs/false-positive-taxonomy.md) for depth. For local scale expectations, see the [`performance envelope`](./docs/performance-envelope.md).
+
+For a shorter external review entry point focused on uncertainty handling, read
+[How LogLens Treats Parser Uncertainty as Evidence](./docs/case-study-parser-uncertainty-as-evidence.md).
 
 ## Why This Project Exists
 
@@ -38,7 +61,7 @@ LogLens includes two minimal GitHub Actions workflows:
 - `CI` builds and tests the project on `ubuntu-latest` and `windows-latest`
 - `CodeQL` runs GitHub code scanning for C/C++ on pushes, pull requests, and a weekly schedule
 
-Both workflows are intended to stay stable enough to require on pull requests to `main`. Regression coverage is backed by sanitized parser fixture matrices plus golden report-contract fixtures for `report.md`, `report.json`, and optional CSV outputs. Release-facing documentation is split across [`CHANGELOG.md`](./CHANGELOG.md), [`docs/release-process.md`](./docs/release-process.md), [`docs/release-v0.1.0.md`](./docs/release-v0.1.0.md), [`docs/release-v0.3.0.md`](./docs/release-v0.3.0.md), and the repository's GitHub release notes. The repository hardening note is in [`docs/repo-hardening.md`](./docs/repo-hardening.md), and vulnerability reporting guidance is in [`SECURITY.md`](./SECURITY.md).
+Both workflows are intended to stay stable enough to require on pull requests to `main`. Regression coverage is backed by sanitized parser fixture matrices plus golden report-contract fixtures for `report.md`, `report.json`, and optional CSV outputs. Release-facing documentation is split across [`CHANGELOG.md`](./CHANGELOG.md), [`docs/release-process.md`](./docs/release-process.md), [`docs/release-v0.1.0.md`](./docs/release-v0.1.0.md), [`docs/release-v0.3.0.md`](./docs/release-v0.3.0.md), [`docs/release-v0.5.0.md`](./docs/release-v0.5.0.md), and the repository's GitHub release notes. The repository hardening note is in [`docs/repo-hardening.md`](./docs/repo-hardening.md), and vulnerability reporting guidance is in [`SECURITY.md`](./SECURITY.md).
 
 ## Threat Model
 
@@ -66,7 +89,8 @@ LogLens currently parses and reports these additional auth patterns beyond the c
 - `Accepted keyboard-interactive/pam` SSH successes
 - `Failed publickey` SSH failures, which count toward SSH brute-force detection by default
 - `Failed keyboard-interactive/pam` and `maximum authentication attempts exceeded` SSH failures, which count toward SSH brute-force detection by default
-- `sshd`-owned `PAM: Authentication failure ...` lines, with invalid/illegal-user variants normalized to `ssh_invalid_user`
+- `input_userauth_request: invalid/illegal user ...` preauth SSH traces normalized to `ssh_invalid_user`
+- `sshd`-owned `PAM: Authentication failure ...` lines, including OpenSSH's optional leading `error:` marker, with invalid/illegal-user variants normalized to `ssh_invalid_user`
 - `sudo` command, password-failure, and sudoers policy-denial audit lines
 - `su` success and failure audit lines
 - `pam_unix(...:auth): authentication failure`
@@ -82,14 +106,19 @@ LogLens also tracks parser coverage telemetry for unsupported or malformed lines
 - `parsed_lines`
 - `unparsed_lines`
 - `parse_success_rate`
+- `failure_categories`
 - `top_unknown_patterns`
 
 Common unsupported-pattern buckets include `sshd_connection_closed_preauth`,
-`sshd_timeout_or_disconnection`, `sshd_negotiation_failure`, and
-`pam_unix_session_closed`. These buckets keep non-finding evidence reviewable
-without counting it as detector evidence.
+`sshd_timeout_or_disconnection`, `sshd_negotiation_failure`,
+`pam_faillock_account_locked`, and `pam_unix_session_closed`. These buckets keep
+non-finding evidence reviewable without counting it as detector evidence.
+Failure categories group unsupported lines into reviewer-facing parser boundary
+classes: `unknown_timestamp`, `unknown_program`,
+`known_program_unknown_message`, `malformed_source_ip`, and
+`unsupported_pam_variant`.
 
-For the parser behavior contract, supported modes, and fixture map, see [`docs/parser-contract.md`](./docs/parser-contract.md).
+For a compact raw-log-to-conclusion trace, see [`docs/incident-style-case.md`](./docs/incident-style-case.md). For rule-by-rule semantics and signal boundaries, see [`docs/rule-catalog.md`](./docs/rule-catalog.md). For benign-context hypotheses and the evidence needed to support them, see [`docs/false-positive-taxonomy.md`](./docs/false-positive-taxonomy.md). For a full forensic-style evidence walkthrough, see [`docs/case-study-linux-auth-bruteforce.md`](./docs/case-study-linux-auth-bruteforce.md). For the parser behavior contract, supported modes, and fixture map, see [`docs/parser-contract.md`](./docs/parser-contract.md). For the deliberately noisy parser-coverage sample, see [`docs/parser-coverage-notes.md`](./docs/parser-coverage-notes.md).
 
 LogLens does not currently detect:
 
@@ -107,6 +136,12 @@ cmake --build build
 ctest --test-dir build --output-on-failure
 ```
 
+For Visual Studio or other multi-config generators, pass the built configuration to CTest:
+
+```bash
+ctest --test-dir build -C Debug --output-on-failure
+```
+
 For fresh-machine setup and repeatable local presets, see [`docs/dev-setup.md`](./docs/dev-setup.md).
 
 ## Run
@@ -135,7 +170,7 @@ When you add `--csv`, LogLens also writes:
 The CSV schema is intentionally small and stable:
 
 - `findings.csv`: `rule`, `subject_kind`, `subject`, `event_count`, `window_start`, `window_end`, `usernames`, `summary`
-- `warnings.csv`: `kind`, `line_number`, `message`
+- `warnings.csv`: `kind`, `line_number`, `category`, `message`
 
 Without `--csv`, LogLens does not create, overwrite, or delete any existing CSV files in the output directory.
 
@@ -212,6 +247,8 @@ The config file schema is intentionally small and strict:
 
 This mapping lets LogLens normalize parsed events into detection signals before applying brute-force or multi-user rules. By default, `pam_auth_failure` is treated as lower-confidence attempt evidence and does not count as a terminal authentication failure unless the config explicitly upgrades it. The `ssh_failed_keyboard_interactive` and `ssh_max_auth_tries` mapping keys are optional in older configs and default to terminal failure evidence.
 
+The checked-in [`assets/sample_config.json`](./assets/sample_config.json) is tested as a runnable default-equivalent config fixture. If default detector thresholds or signal mappings change, update that file and the related tests together.
+
 Timestamp handling is now explicit:
 
 - `--mode syslog`, `--mode syslog-legacy`, or `input_mode: syslog_legacy` requires `--year` or `timestamp.assume_year`