Merge branch 'main' into dependabot/github_actions/actions/checkout-7.0.0

Author: stacknil

.gitattributes

@@ -5,6 +5,7 @@
 *.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

.github/workflows/codeql.yml

@@ -23,7 +23,7 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@7211b7c8077ea37d8641b6271f6a365a22a5fbfa  # v4.36.0
+        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e  # v4.36.2
         with:
           languages: c-cpp
 
@@ -34,4 +34,4 @@ jobs:
         run: cmake --build build --config Release
 
       - name: Analyze
-        uses: github/codeql-action/analyze@7211b7c8077ea37d8641b6271f6a365a22a5fbfa  # v4.36.0
+        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e  # v4.36.2

.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,11 +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.
-- Added `schema` and `schema_version` fields to `report.json` so downstream tooling can identify the report artifact contract.
-- 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
 
@@ -24,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

@@ -9,25 +9,32 @@ It parses `auth.log` / `secure`-style syslog input and `journalctl --output=shor
 
 ## Example Finding
 
-A compact finding summary is a bounded triage signal, not attribution:
+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": "198.51.100.23",
-  "window": "10m",
+  "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": 8,
-  "verdict_boundary": "triage_signal_not_attribution"
+  "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), [`docs/reviewer-brief.md`](./docs/reviewer-brief.md), and the [`quality gates map`](./docs/quality-gates.md). For detection reasoning, read the forensic-style [`Linux auth brute-force case study`](./docs/case-study-linux-auth-bruteforce.md) and the [`rule catalog`](./docs/rule-catalog.md). For local scale expectations, see the [`performance envelope`](./docs/performance-envelope.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
 
@@ -54,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
 
@@ -111,7 +118,7 @@ classes: `unknown_timestamp`, `unknown_program`,
 `known_program_unknown_message`, `malformed_source_ip`, and
 `unsupported_pam_variant`.
 
-For rule-by-rule semantics and signal boundaries, see [`docs/rule-catalog.md`](./docs/rule-catalog.md). For a 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).
+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: