v0.3.0: 408-to-Security Bridge

v0.3.0 Release Notes

Title

408-to-Security Bridge

Summary

systems-foundations now has four small, deterministic Linux/systems foundations mini-labs. This release adds the permission and process evidence paths and connects the process diff artifact to the existing telemetry-lab event contract without adding a fifth mini-lab.

The release remains local-file based and reviewable:

• permission state becomes normalized evidence and a Markdown drift report
• saved procfs and ss context become process snapshots, socket links, a diff, and a report
• process_diff.json can be adapted into telemetry-lab-compatible JSONL events

Included In v0.3.0

• projects/linux-permission-observe
• notes/408-to-linux-security.md
• projects/linux-process-observe
• notes/process-evidence-schema.md
• the stacknil.system-evidence.v1 evidence envelope
• the linux-process-observe adapt command
• adapter golden output and malformed-input coverage

Adapter Contract

The adapter reads an existing process_diff.json and writes one JSON object per line with the required telemetry-lab fields:

system-evidence diff	telemetry-lab event
observed_at	timestamp
process added/removed/modified	event_type=process_added/process_removed/process_modified
socket-link added/removed	event_type=socket_link_added/socket_link_removed
process_id	source
executable or formatted socket endpoint	target
added/removed/modified	status
snapshot comparison observation semantics	metadata.time_semantics=snapshot_diff_observed_at
adapter mapping contract	metadata.adapter_contract=stacknil.system-evidence.telemetry.v1

Each event includes deterministic metadata with the source evidence schema and the versioned adapter mapping contract, plus source, host, record type, identity, record index, and field changes. An unlinked socket uses a deterministic host_id:pid:<pid> source fallback when a PID is available.

metadata.time_semantics is snapshot_diff_observed_at. The event timestamp
is the diff observation time, not an inferred process-start, process-exit, or
socket-occurrence time. A window containing several adapter rows therefore
represents evidence deltas observed in one snapshot comparison; it does not
prove that those system activities happened together.

Run the bridge with:

python -m linux_process_observe adapt \
  --input output/diff/process_diff.json \
  --output output/diff/telemetry_events.jsonl

The output can be supplied as input_path to telemetry-lab's existing window workflow. That downstream repository owns its window, deduplication, and investigation demo artifacts; this release does not duplicate those workflows or change their schemas.

Validation Status

• All four mini-lab pytest suites pass locally.
• linux-process-observe covers adapter golden output, malformed diff records, unlinked socket source fallback, and CLI error reporting.
• The adapter output satisfies telemetry-lab's required timestamp, event_type, source, target, and status event fields.

Non-Goals

• no fifth mini-lab
• no live procfs crawling or real-time monitoring
• no /proc/net/tcp parsing, pcap, raw sockets, or packet sockets
• no auditd parser
• no database, network service, web UI, cloud dependency, or EDR agent behavior

v0.2.0: Second Credible Mini-Lab

v0.2.0 Release Notes

Title

Second Credible Mini-Lab

Summary

systems-foundations adds a second focused mini-lab: projects/linux-socket-observe.

This release packages a narrow workflow for reviewing local Linux networking state from saved command-output snapshots:

• build one normalized JSON snapshot from ss plus selected iproute2 outputs
• compare two snapshots deterministically
• generate a Markdown diff report for added, removed, and changed state
• keep the workflow local-file-based and reviewable

Included in v0.2.0

• support for ss text input
• support for ip -j addr show
• support for ip -j link show
• support for ip -j neigh show
• optional support for ip -s -s link show
• one normalized snapshot artifact with sockets, interfaces, addresses, and neighbors
• CLI workflow for snapshot and diff
• golden regression coverage for baseline and changed snapshots
• malformed input coverage for ss parsing and ip -j link show parsing

Validation Snapshot

• python -m pytest -q currently passes in projects/linux-socket-observe
• current tests cover parser basics for ss text and iproute2 JSON inputs
• current tests cover golden snapshot regression for both baseline and changed fixtures
• current tests cover snapshot diff basics for added, removed, and changed state
• current tests cover CLI smoke behavior and bounded error reporting for malformed inputs

Not in Scope

• /proc/net/tcp
• pcap parsing
• live monitoring
• raw sockets or packet sockets
• network namespaces
• ip monitor

Notes

• The snapshot schema remains intentionally small and currently centers on sockets, interfaces, addresses, and neighbors
• interfaces[].stats is only populated when ip -s -s link show input is provided
• The current diff report is meant for state comparison, not traffic inspection or packet forensics

v0.1.0: First Credible Mini-Lab

v0.1.0 Release Notes

Title

First Credible Mini-Lab

Summary

systems-foundations now has its first focused mini-lab: projects/linux-auth-observe.

This release packages a narrow, tested workflow for Linux auth evidence review:

• normalize supported journald and auth syslog fixtures into JSONL
• filter normalized rows by user, IP, and service
• generate a Markdown summary report
• optionally emit structured parse failures as JSONL during normalization

Included in v0.1.0

• support for exported journald JSON lines
• support for Ubuntu or Debian auth.log
• support for RHEL or CentOS secure
• normalized JSONL output with preserved raw evidence
• CLI workflow for normalize, filter, and summary
• pytest coverage for parsing, CLI behavior, summary generation, golden regression, and syslog year rollover

Validation Snapshot

• pytest -q passes in the current repository state
• current tests cover all three supported fixture families
• current tests cover Dec 31 -> Jan 1 syslog rollover behavior
• current tests cover optional --error-output generation for malformed lines

Not in Scope

• audit.log
• real-time monitoring or tailing
• databases or storage backends
• packaging or publishing workflows

Notes

• Syslog timestamps are yearless and timezone-less in the source files, so v0.1.0 documents and tests the current year inference and rollover rules explicitly
• _PID is preserved as contextual metadata when present, not as a standalone identity guarantee