Skip to content

Compare journald JSON and auth.log normalization for equivalent synthetic auth events #5

Description

@stacknil

Context / observed surface

projects/linux-auth-observe supports exported journalctl --output=json records and distro auth syslog inputs, including Ubuntu/Debian auth.log. Both source adapters emit the fixed NormalizedEvent JSONL shape and route supported message content through the shared event classifier, while retaining source metadata.

Existing fixtures and golden outputs exercise the source families separately. This issue asks for a paired, evidence-driven comparison of a very small set of equivalent synthetic authentication events entering through:

  • journald JSON (journal_json / collector="journald"); and
  • auth.log-style syslog (syslog_auth / collector="auth.log").

Choose one or two currently supported authentication message families. Keep the semantic event and available metadata equivalent as far as the two envelopes allow, then trace:

source envelope and timestamp parsing -> classify_event -> NormalizedEvent JSONL -> filter / summary behavior

Relevant starting points include:

  • projects/linux-auth-observe/README.md
  • projects/linux-auth-observe/src/linux_auth_observe/models.py
  • projects/linux-auth-observe/src/linux_auth_observe/parsers/common.py
  • projects/linux-auth-observe/src/linux_auth_observe/parsers/journal_json.py
  • projects/linux-auth-observe/src/linux_auth_observe/parsers/syslog_auth.py
  • projects/linux-auth-observe/tests/test_normalize.py and the checked-in fixtures/golden JSONL
  • notes/auth-event-schema.md and notes/journald-syslog-basics.md

Do not assume that valid cross-source normalization requires byte-identical output.

Diagnostic question

Determine which observed differences are:

A. legitimate source-specific differences;
B. documentation or contract ambiguity; or
C. an actual normalization defect.

Please include a compact comparison table:

Field / behavior journald JSON source auth.log source Expected contract class Evidence

Useful contract classes may include:

  • normalized invariant;
  • source-specific provenance;
  • optional or unknown;
  • potential contract drift.

Derive the classification from current repository evidence rather than assuming every field belongs in the same class.

Evidence required

Provide the synthetic inputs, exact normalization commands or focused parser calls, and resulting JSONL or downstream observations. Answer:

  • What is the normalized cross-source invariant?
  • What information is intentionally source-specific?
  • Which observed differences are supported by the current contract?
  • Are equivalent events normalized consistently enough for the current filter and summary consumers?
  • What behavior must remain unchanged?
  • What evidence, if any, makes a repository change necessary?

Cite exact code, tests, fixture rows, golden outputs, and documentation. Preserve uncertainty where the current contract does not decide a field.

Change threshold

Post the comparison evidence and classification in this issue before opening a PR.

A PR is justified only if the investigation identifies a concrete missing regression, documentation ambiguity, or contract violation. If a behavioral defect is claimed and a PR later follows, include a focused red -> green regression where practical: demonstrate the failure against the relevant base behavior and the same test passing after the proposed fix.

Do not turn the investigation into a broad parser redesign.

Behavior that must remain unchanged

State explicitly which timestamp, batch-error, schema, filtering, summary, and evidence-traceability behaviors are outside any proposed correction. Do not erase source provenance such as the collector/parser identity or preserved raw evidence merely to force equality.

Boundaries

  • Synthetic fixtures only.
  • No real usernames, addresses, host identifiers, credentials, machine screenshots, or private paths.
  • No live system collection requirement.
  • No broad parser rewrite.
  • No expansion into SIEM or detection functionality.
  • Do not add a new input family as part of this investigation.
  • Keep the mini-lab deterministic, local-file-based, and reviewable.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    help wantedExtra attention is needed

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions