Simplify scan results with readable summary and matched-event CSV

README.txt

@@ -52,32 +52,21 @@ and AES-ZIP are supported. Passwords are not saved in results.
 
 WHAT TO READ FIRST
 
-summary.json tells you what was processed and whether anything was incomplete.
-findings.jsonl contains selected events, original source/line references, matching
-rule details, extracted indicators and safe decoding steps with explanations.
-Each line is a separate JSON object. Explanations describe what command text
-could do; they do not establish that it ran successfully.
+SUMMARY.txt is the readable overview: status, counts, limitations and next steps.
+FINDINGS.csv contains only rule/indicator matches, explanations, source references
+and indicator statuses. A match is not proof of execution or compromise.
+IOCS.csv contains raw search candidates and defanged display values, not a blocklist.
 
-IOCS.csv contains exact values for SIEM searches and a separate defanged display
-value. Observed values are candidates, not an automatic blocklist.
-updates.jsonl contains update/version evidence. An installer command is not by
-itself proof of a completed patch. correlations.jsonl contains temporal candidates
-between log files on the same appliance, not proof of causation.
+Technical exports are grouped under details/: findings.jsonl (all selected events,
+including context/errors), summary.json, updates.jsonl, correlations.jsonl,
+coverage.json, input_manifest.json, configuration.json, indicator_hits.csv,
+file_hash_hits.json, preparation_manifest.json and evidence.sqlite.
+Prepared input copies remain in inputs/. Preparation-manifest paths are relative
+to the result root. Decoding details retain originals, transformations and errors.
 
-Other outputs support verification:
-    evidence.sqlite             On-disk event index
-    coverage.json               Per-file coverage and read/matching errors
-    input_manifest.json         Original relative paths and SHA-256 checksums
-    configuration.json          Effective rules, references and time assumptions
-    indicator_hits.csv          Matches against configured reference indicators
-    file_hash_hits.json         Reference matches against original file SHA-256
-    preparation_manifest.json   Preparation actions, groups and exclusions
-    inputs/                     Prepared inputs when automatic preparation runs
-
-URL/Base64 transformations retain the original value, transformation, parent
-step, decoded result or error, and checksum. Binary decoded content is displayed
-as hex and is not executed. Finding rule_details retain matching rule descriptions
-and source metadata; custom packs can provide their own explanations.
+FINDINGS.csv prefixes spreadsheet-sensitive text with an apostrophe; exact values
+remain in JSON. Authorized-test/context/reference hits are explicitly labelled.
+Direct engine.scan calls and failed/interrupted CLI scans retain flat exports.
 
 ADD YOUR OWN RULES OR IOCS
 
@@ -125,7 +114,9 @@ year overrides can be supplied using --time-config; see examples/time.json.
 LIMITS AND INCOMPLETE RESULTS
 
 Exit 0 means the configured processing completed, not that the appliance is clean.
-Exit 2 means an error or incomplete processing; inspect summary.json.
+Exit 2 means an error or incomplete processing; inspect SUMMARY.txt and
+details/summary.json. If the scan failed before presentation, inspect
+summary.json at the result root instead.
 Invalid decoding candidates may be ordinary text, not malicious payloads.
 Unknown text formats remain searchable, even if no timestamp is parsed.
 Proprietary binary logs require an appropriate external decoder.