[Change] JSON list schema 1.1: scanner/host blocks, renames, quar_enabled, sig_version parity

rfxn · rfxn · commit 417e558968c0 · 2026-04-19T10:13:13.000-05:00
[New] _lmd_render_json_list top-level scanner {name, version,
      sig_version} and host {hostname, host_id} blocks mirror the
      per-scan JSON schema so consumers can parse invariants once
      instead of per-entry.
[Change] active[]/stopped[] field renames for per-scan JSON parity:
         hashtype → hash_type, hits → total_hits, elapsed →
         elapsed_seconds. Schema is unreleased (v2.x) so no deprecation
         shim needed.
[New] active[]/stopped[] add quarantine_enabled (boolean) from
      scan.meta; total_cleaned + total_quarantined emitted as null
      (not 0) to signal "not yet determined" mid-scan.
[New] stopped[] adds engine + sig_version for parity with active[].
[New] reports[] adds sig_version + quarantine_enabled; null for
      pre-bump 9-field index rows and legacy plaintext sessions.
[Change] scan.meta schema: new quarantine_enabled field written by
         _lifecycle_write_meta from global \$quarantine_hits; parser
         case added to _lifecycle_read_meta.
[Change] session.index schema bumped 9→11 fields (sig_version +
         quarantine_enabled as fields 10/11). _session_index_append
         variadic on trailing args (9-arg calls default to "-" / "0").
         _session_index_rebuild emits 11 fields from TSV headers.
         JSON and text readers tolerate old 8/9-field rows via the
         existing backward-compat shim.
[New] tests/31-json-report.bats: 9 new cases (38-46) for scanner/
      host blocks, schema-1.1 renames, quarantine_enabled boolean,
      null post-scan counters, sig_version parity, 9-field
      backward-compat.
[Change] tests/40-session-index.bats: append test updated for 11-field
         schema; new test covers default fields 10/11 when caller
         omits them.
diff --git a/CHANGELOG b/CHANGELOG
@@ -137,6 +137,23 @@ v2.0.1 | Mar 25 2026:
          elapsed_seconds, null when inputs missing); field ordering normalized
          across all three arrays (identity → process → location → time →
          config → metrics)
+[Change] --json-report list schema 1.1: top-level scanner block ({name, version,
+         sig_version}) and host block ({hostname, host_id}) mirror per-scan
+         JSON schema; field renames for parity with per-scan JSON — hashtype
+         → hash_type, hits → total_hits, elapsed → elapsed_seconds; active[]/
+         stopped[] add quarantine_enabled (boolean, from scan.meta) and null
+         total_cleaned/total_quarantined (post-scan actions not yet determined
+         mid-scan); stopped[] adds engine + sig_version parity with active[];
+         reports[] adds sig_version + quarantine_enabled (null for pre-bump
+         rows and legacy plaintext sessions)
+[Change] scan.meta: new quarantine_enabled field written by _lifecycle_write_meta
+         from $quarantine_hits; _lifecycle_read_meta parses into
+         _meta_quarantine_enabled
+[Change] session.index schema bumped 9→11 fields (sig_version + quarantine_enabled
+         appended as fields 10 + 11); _session_index_append accepts 11 args
+         (9-arg calls default fields 10-11 to "-" and "0"); _session_index_rebuild
+         emits 11 fields from TSV session headers; readers tolerate old 8/9-field
+         rows via existing backward-compat shim
 [Change] lmd_lifecycle.sh: remove dead stage_started meta-schema parser case
          and initializer (no code ever wrote stage_started to any meta file)
 [Change] lmd_scan.sh, lmd_quarantine.sh: remove unused local variables (_total
diff --git a/CHANGELOG.RELEASE b/CHANGELOG.RELEASE
@@ -137,6 +137,23 @@ v2.0.1 | Mar 25 2026:
          elapsed_seconds, null when inputs missing); field ordering normalized
          across all three arrays (identity → process → location → time →
          config → metrics)
+[Change] --json-report list schema 1.1: top-level scanner block ({name, version,
+         sig_version}) and host block ({hostname, host_id}) mirror per-scan
+         JSON schema; field renames for parity with per-scan JSON — hashtype
+         → hash_type, hits → total_hits, elapsed → elapsed_seconds; active[]/
+         stopped[] add quarantine_enabled (boolean, from scan.meta) and null
+         total_cleaned/total_quarantined (post-scan actions not yet determined
+         mid-scan); stopped[] adds engine + sig_version parity with active[];
+         reports[] adds sig_version + quarantine_enabled (null for pre-bump
+         rows and legacy plaintext sessions)
+[Change] scan.meta: new quarantine_enabled field written by _lifecycle_write_meta
+         from $quarantine_hits; _lifecycle_read_meta parses into
+         _meta_quarantine_enabled
+[Change] session.index schema bumped 9→11 fields (sig_version + quarantine_enabled
+         appended as fields 10 + 11); _session_index_append accepts 11 args
+         (9-arg calls default fields 10-11 to "-" and "0"); _session_index_rebuild
+         emits 11 fields from TSV session headers; readers tolerate old 8/9-field
+         rows via existing backward-compat shim
 [Change] lmd_lifecycle.sh: remove dead stage_started meta-schema parser case
          and initializer (no code ever wrote stage_started to any meta file)
 [Change] lmd_scan.sh, lmd_quarantine.sh: remove unused local variables (_total
diff --git a/files/internals/lmd_alert.sh b/files/internals/lmd_alert.sh
@@ -703,7 +703,27 @@ _lmd_render_json_legacy() {
 # _lmd_render_json_list — render all session reports as JSON array (index-first, legacy fallback)
 # shellcheck disable=SC2154
 _lmd_render_json_list() {
-	printf '{\n  "version": "1.0",\n  "type": "report_list",\n  "active": ['
+	# Top-level scanner + host blocks mirror per-scan JSON schema (see
+	# _lmd_render_json at line 449). Single source of truth for invariants
+	# that consumers would otherwise duplicate per-entry.
+	local _jl_hostname _jl_hostid _jl_scanner_ver _jl_sigs_ver
+	_jl_hostname=$(hostname)
+	_jl_hostname=$(_json_escape_string "${_jl_hostname:--}")
+	_jl_hostid="${hostid:--}"
+	[ "$_jl_hostid" = "-" ] && _jl_hostid="null" || _jl_hostid="\"$_jl_hostid\""
+	_jl_scanner_ver="${lmd_version:--}"
+	[ "$_jl_scanner_ver" = "-" ] && _jl_scanner_ver="null" || _jl_scanner_ver="\"$_jl_scanner_ver\""
+	# Installed sig version (what this LMD would scan with if a new scan started
+	# now); per-entry sig_version remains the version active at that scan's time.
+	if [ -f "$sigdir/maldet.sigs.ver" ]; then
+		IFS= read -r _jl_sigs_ver < "$sigdir/maldet.sigs.ver"
+	fi
+	[ -z "${_jl_sigs_ver:-}" ] && _jl_sigs_ver="null" || _jl_sigs_ver="\"$_jl_sigs_ver\""
+	printf '{\n  "version": "1.1",\n  "type": "report_list",\n'
+	printf '  "scanner": {"name": "Linux Malware Detect", "version": %s, "sig_version": %s},\n' \
+		"$_jl_scanner_ver" "$_jl_sigs_ver"
+	printf '  "host": {"hostname": "%s", "host_id": %s},\n' "$_jl_hostname" "$_jl_hostid"
+	printf '  "active": ['
 
 	# Enumerate active scans for the "active" array
 	local _first_active=1 _jl_meta_file _jl_scanid _jl_state
@@ -738,12 +758,16 @@ _lmd_render_json_list() {
 				local _jl_workers="${_meta_workers:-0}"; [ "$_jl_workers" = "-" ] && _jl_workers=0
 				local _jl_prog_pos="${_meta_progress_pos:-0}"; [ "$_jl_prog_pos" = "-" ] && _jl_prog_pos=0
 				local _jl_prog_total="${_meta_progress_total:-0}"; [ "$_jl_prog_total" = "-" ] && _jl_prog_total=0
-				local _jl_eta
+				local _jl_eta _jl_quar_bool
 				_jl_eta=$(_lifecycle_compute_eta "${_meta_engine:-}" "$_jl_elapsed" "$_jl_prog_pos" "$_jl_prog_total")
-				printf '\n    {"scan_id": "%s", "state": "%s", "pid": %s, "ppid": %s, "path": "%s", "started": "%s", "started_epoch": %s, "elapsed": %s, "engine": "%s", "hashtype": "%s", "workers": %s, "sig_version": "%s", "total_files": %s, "hits": %s, "eta": %s, "progress": {"position": %s, "total": %s}}' \
+				# quarantine_enabled: boolean matching per-scan JSON jbool() convention
+				if [ "${_meta_quarantine_enabled:-0}" = "1" ]; then _jl_quar_bool="true"; else _jl_quar_bool="false"; fi
+				# total_cleaned/total_quarantined are post-scan actions; emit null to
+				# signal "not yet determined" (not zero, which implies "no action taken")
+				printf '\n    {"scan_id": "%s", "state": "%s", "pid": %s, "ppid": %s, "path": "%s", "started": "%s", "started_epoch": %s, "elapsed_seconds": %s, "engine": "%s", "hash_type": "%s", "workers": %s, "sig_version": "%s", "quarantine_enabled": %s, "total_files": %s, "total_hits": %s, "total_cleaned": null, "total_quarantined": null, "eta": %s, "progress": {"position": %s, "total": %s}}' \
 					"$_jl_scanid" "$_jl_state" "$_jl_pid" "$_jl_ppid" "$_jl_path" \
 					"$_jl_started_hr" "$_jl_started_ep" "$_jl_elapsed" \
-					"$_jl_engine" "$_jl_hashtype" "$_jl_workers" "$_jl_sig" \
+					"$_jl_engine" "$_jl_hashtype" "$_jl_workers" "$_jl_sig" "$_jl_quar_bool" \
 					"$_jl_files" "$_jl_hits" \
 					"$_jl_eta" "$_jl_prog_pos" "$_jl_prog_total"
 				;;
@@ -763,11 +787,13 @@ _lmd_render_json_list() {
 			_lifecycle_read_meta "$_jl_stopped_sid" || continue
 			[ "$_first_stopped" != "1" ] && printf ","
 			_first_stopped=0
-			local _jl_sp _jl_sstage _jl_shr _jl_shashtype
+			local _jl_sp _jl_sstage _jl_shr _jl_shashtype _jl_sengine _jl_ssig
 			_jl_sp=$(_json_escape_string "$_meta_path")
 			_jl_sstage=$(_json_escape_string "${_meta_stage:--}")
 			_jl_shr=$(_json_escape_string "${_meta_stopped_hr:-unknown}")
 			_jl_shashtype=$(_json_escape_string "${_meta_hashtype:--}")
+			_jl_sengine=$(_json_escape_string "${_meta_engine:--}")
+			_jl_ssig=$(_json_escape_string "${_meta_sig_version:--}")
 			local _jl_sstarted_hr _jl_sstarted_ep _jl_sstopped_ep
 			_jl_sstarted_hr=$(_json_escape_string "${_meta_started_hr:--}")
 			_jl_sstarted_ep="${_meta_started:-0}"
@@ -779,11 +805,13 @@ _lmd_render_json_list() {
 			local _jl_shits="${_meta_hits:-0}"; [ "$_jl_shits" = "-" ] && _jl_shits=0
 			local _jl_selapsed="${_meta_elapsed:-0}"; [ "$_jl_selapsed" = "-" ] && _jl_selapsed=0
 			local _jl_sworkers="${_meta_workers:-0}"; [ "$_jl_sworkers" = "-" ] && _jl_sworkers=0
-			printf '\n    {"scan_id": "%s", "stage": "%s", "ppid": %s, "path": "%s", "started": "%s", "started_epoch": %s, "stopped_hr": "%s", "stopped_epoch": %s, "elapsed": %s, "hashtype": "%s", "workers": %s, "total_files": %s, "hits": %s}' \
+			local _jl_squar_bool
+			if [ "${_meta_quarantine_enabled:-0}" = "1" ]; then _jl_squar_bool="true"; else _jl_squar_bool="false"; fi
+			printf '\n    {"scan_id": "%s", "stage": "%s", "ppid": %s, "path": "%s", "started": "%s", "started_epoch": %s, "stopped_hr": "%s", "stopped_epoch": %s, "elapsed_seconds": %s, "engine": "%s", "hash_type": "%s", "workers": %s, "sig_version": "%s", "quarantine_enabled": %s, "total_files": %s, "total_hits": %s, "total_cleaned": null, "total_quarantined": null}' \
 				"$_jl_stopped_sid" "$_jl_sstage" "$_jl_sppid" "$_jl_sp" \
 				"$_jl_sstarted_hr" "$_jl_sstarted_ep" \
 				"$_jl_shr" "$_jl_sstopped_ep" "$_jl_selapsed" \
-				"$_jl_shashtype" "$_jl_sworkers" \
+				"$_jl_sengine" "$_jl_shashtype" "$_jl_sworkers" "$_jl_ssig" "$_jl_squar_bool" \
 				"$_jl_sfiles" "$_jl_shits"
 		fi
 	done
@@ -812,8 +840,12 @@ _lmd_render_json_list() {
 	if [ -f "$_index_file" ]; then
 		local _ix_scanid _ix_epoch _ix_started_hr _ix_elapsed
 		local _ix_tot_files _ix_tot_hits _ix_tot_cl _ix_tot_quar _ix_path
+		local _ix_sig_version _ix_quar_enabled
+		# Schema v1 is 9 fields; v1.1 appends sig_version + quarantine_enabled.
+		# Missing trailing fields read as empty — handled per-field below.
 		while IFS=$'\t' read -r _ix_scanid _ix_epoch _ix_started_hr _ix_elapsed \
-				_ix_tot_files _ix_tot_hits _ix_tot_cl _ix_tot_quar _ix_path; do
+				_ix_tot_files _ix_tot_hits _ix_tot_cl _ix_tot_quar _ix_path \
+				_ix_sig_version _ix_quar_enabled; do
 			case "$_ix_scanid" in "#"*|"") continue ;; esac
 			# Backward compat: old 8-field index has path in field 8 (no quar field)
 			if [ -z "$_ix_path" ] && [ -n "$_ix_tot_quar" ]; then
@@ -846,6 +878,21 @@ _lmd_render_json_list() {
 				fi
 				if [ "$_ix_elapsed" = "-" ]; then printf '"elapsed_seconds": null, '
 				else printf '"elapsed_seconds": %s, ' "$_ix_elapsed"; fi
+				# sig_version / quarantine_enabled — v1.1 fields; null when absent
+				# (pre-bump entries or rebuilds from TSVs lacking the data)
+				if [ -z "$_ix_sig_version" ] || [ "$_ix_sig_version" = "-" ]; then
+					printf '"sig_version": null, '
+				else
+					_json_escape_var "$_ix_sig_version"
+					printf '"sig_version": "%s", ' "$_JSON_ESC_OUT"
+				fi
+				if [ -z "$_ix_quar_enabled" ] || [ "$_ix_quar_enabled" = "-" ]; then
+					printf '"quarantine_enabled": null, '
+				elif [ "$_ix_quar_enabled" = "1" ]; then
+					printf '"quarantine_enabled": true, '
+				else
+					printf '"quarantine_enabled": false, '
+				fi
 				if [ "$_ix_tot_files" = "-" ]; then printf '"total_files": null, '
 				else printf '"total_files": %s, ' "$_ix_tot_files"; fi
 				if [ "$_ix_tot_hits" = "-" ]; then printf '"total_hits": null, '
@@ -901,6 +948,10 @@ _lmd_render_json_list() {
 			fi
 			if [ -z "$scan_et" ]; then printf '"elapsed_seconds": null, '
 			else printf '"elapsed_seconds": %s, ' "$scan_et"; fi
+			# sig_version / quarantine_enabled not recoverable from plaintext
+			# session headers — legacy format predates both. Null is honest.
+			printf '"sig_version": null, '
+			printf '"quarantine_enabled": null, '
 			if [ -z "$tot_files" ]; then printf '"total_files": null, '
 			else printf '"total_files": %s, ' "$tot_files"; fi
 			if [ -z "$tot_hits" ]; then printf '"total_hits": null, '
diff --git a/files/internals/lmd_lifecycle.sh b/files/internals/lmd_lifecycle.sh
@@ -27,7 +27,7 @@ _lifecycle_write_meta() {
 	local _options="$1"
 	local _meta_file="$sessdir/scan.meta.$_scanid"
 	local _tmp_file="$_meta_file.tmp"
-	local _started _started_hr _sig_ver
+	local _started _started_hr _sig_ver _quar_enabled
 
 	_started=$(command date +%s)
 	_started_hr=$(command date "+%b %d %Y %H:%M:%S %z")
@@ -39,6 +39,7 @@ _lifecycle_write_meta() {
 		_sig_ver="unknown"
 	fi
 	[ -z "$_sig_ver" ] && _sig_ver="unknown"
+	_quar_enabled="${quarantine_hits:-0}"
 
 	# ns_pid: namespace PID used for temp file grouping ($$ — always the
 	# top-level shell PID, even in background forks).  Separate from pid
@@ -58,6 +59,7 @@ hashtype=$_hashtype
 stages=$_stages
 sig_version=$_sig_ver
 options=$_options
+quarantine_enabled=$_quar_enabled
 state=running
 EOF
 
@@ -98,6 +100,7 @@ _lifecycle_read_meta() {
 	_meta_stages=""
 	_meta_sig_version=""
 	_meta_options=""
+	_meta_quarantine_enabled=""
 	_meta_state=""
 	_meta_stage=""
 	_meta_progress_pos=""
@@ -127,6 +130,7 @@ _lifecycle_read_meta() {
 			stages)          _meta_stages="$_value" ;;
 			sig_version)     _meta_sig_version="$_value" ;;
 			options)         _meta_options="$_value" ;;
+			quarantine_enabled) _meta_quarantine_enabled="$_value" ;;
 			state)           _meta_state="$_value" ;;
 			stage)           _meta_stage="$_value" ;;
 			progress_pos)    _meta_progress_pos="$_value" ;;
@@ -513,22 +517,27 @@ _lifecycle_render_tsv_active() {
 	return 0
 }
 
-# _session_index_append scanid epoch started_hr elapsed total_files total_hits total_cleaned total_quarantined path — append to session.index
+# _session_index_append scanid epoch started_hr elapsed total_files total_hits total_cleaned total_quarantined path sig_version quarantine_enabled — append to session.index
+# Schema v1 fields 1-9 are legacy; fields 10-11 added for JSON schema 1.1 consumer parity.
+# Readers MUST tolerate missing trailing fields (old entries, pre-bump rebuilds).
 _session_index_append() {
 	local _scanid="$1" _epoch="$2" _started_hr="$3" _elapsed="$4"
 	local _total_files="$5" _total_hits="$6" _total_cleaned="$7"
 	local _total_quar="$8" _path="$9"
+	shift 9
+	local _sig_version="${1:--}" _quar_enabled="${2:-0}"
 	local _index_file="$sessdir/session.index"
 
 	if [ ! -f "$_index_file" ]; then
 		printf '#LMD_INDEX:v1\n' > "$_index_file"
 	fi
 
 	# Atomic append (< PIPE_BUF)
-	printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+	printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
 		"$_scanid" "$_epoch" "$_started_hr" "$_elapsed" \
 		"$_total_files" "$_total_hits" "$_total_cleaned" \
-		"$_total_quar" "$_path" >> "$_index_file"
+		"$_total_quar" "$_path" \
+		"$_sig_version" "$_quar_enabled" >> "$_index_file"
 }
 
 # _session_index_rebuild — rebuild session.index from session.tsv.* (flock-gated, atomic .tmp+mv)
@@ -537,9 +546,10 @@ _session_index_rebuild() {
 	local _tmp_file="$_index_file.tmp"
 	local _tsv_file _rid
 	local _r_scanid _r_started_hr _r_elapsed _r_tot_files _r_tot_hits _r_tot_cl _r_path _r_epoch
+	local _r_sig_ver _r_quar
 	# Throwaway variables for TSV fields we do not use
 	local _r_fmt _r_alert_type _r_hostname _r_days _r_end_hr _r_fl_et
-	local _r_scanner_ver _r_sig_ver _r_hashtype _r_engine _r_quar _r_hostid
+	local _r_scanner_ver _r_hashtype _r_engine _r_hostid
 
 	# Flock to prevent concurrent rebuilds
 	(
@@ -563,10 +573,11 @@ _session_index_rebuild() {
 			# Count quarantined hits: lines where field 3 (quarpath) is non-empty and not "-"
 			local _r_tot_quar
 			_r_tot_quar=$(awk -F'\t' '!/^#/ && $3 != "" && $3 != "-" { n++ } END { print n+0 }' "$_tsv_file")
-			printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
+			printf '%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\t%s\n' \
 				"$_r_scanid" "$_r_epoch" "$_r_started_hr" "${_r_elapsed:--}" \
 				"${_r_tot_files:--}" "${_r_tot_hits:--}" "${_r_tot_cl:--}" \
 				"$_r_tot_quar" "${_r_path:--}" \
+				"${_r_sig_ver:--}" "${_r_quar:-0}" \
 				>> "$_tmp_file"
 		done
 
diff --git a/files/internals/lmd_session.sh b/files/internals/lmd_session.sh
@@ -336,8 +336,12 @@ view_report() {
 			# Fast path: read completed scans from session.index (O(1) vs O(n) per-file)
 			local _ix_scanid _ix_epoch _ix_started_hr _ix_elapsed
 			local _ix_tot_files _ix_tot_hits _ix_tot_cl _ix_tot_quar _ix_path
+			# v1.1 trailing fields read-through (unused by text renderer but
+			# named so they don't spill into _ix_path on newer 11-field rows)
+			local _ix_sig_version _ix_quar_enabled
 			while IFS=$'\t' read -r _ix_scanid _ix_epoch _ix_started_hr _ix_elapsed \
-					_ix_tot_files _ix_tot_hits _ix_tot_cl _ix_tot_quar _ix_path; do
+					_ix_tot_files _ix_tot_hits _ix_tot_cl _ix_tot_quar _ix_path \
+					_ix_sig_version _ix_quar_enabled; do
 				# Skip header and empty lines
 				case "$_ix_scanid" in "#"*|"") continue ;; esac
 				# Backward compat: old 8-field index has path in field 8 (no quar field)
@@ -700,10 +704,17 @@ _scan_finalize_session() {
 	local _tot_quar
 	_tot_quar=$(awk -F'\t' '!/^#/ && $3 != "" && $3 != "-" { n++ } END { print n+0 }' "$nsess_hits")
 
+	# Resolve sig_version + quarantine_enabled for v1.1 index schema (fields 10-11).
+	# sig_version: prefer runtime $sig_version; fall back to on-disk sigs.ver sentinel.
+	local _idx_sig_ver _idx_quar_en
+	_idx_sig_ver="${sig_version:-$(cat "$sigdir/maldet.sigs.ver" 2>/dev/null || echo "-")}"  # safe: sigs.ver may be absent on fresh install
+	_idx_quar_en="${quarantine_hits:-0}"
+
 	# Append to session index (non-hook scans only)
 	_session_index_append "$_sid" "${scan_start:-0}" \
 		"${scan_start_hr:--}" "${scan_et:--}" \
-		"${tot_files:--}" "${tot_hits:--}" "${tot_cl:--}" "$_tot_quar" "${hrspath:--}"
+		"${tot_files:--}" "${tot_hits:--}" "${tot_cl:--}" "$_tot_quar" "${hrspath:--}" \
+		"$_idx_sig_ver" "$_idx_quar_en"
 
 	# Remove in-flight scan_session — all data now in nsess_hits
 	command rm -f "$scan_session"
diff --git a/tests/31-json-report.bats b/tests/31-json-report.bats
diff --git a/tests/40-session-index.bats b/tests/40-session-index.bats
