04 / REPEATABLE INVESTIGATION TOOLS · LESSON 16

Publish reproducible reports

Stage a stable report and summary, replacing earlier results only after required input checks.

16 min · learn at your pace

Reproducibility is a feature

Two runs over the same evidence and policy should produce the same report. Avoid adding the current wall-clock time to a deterministic report; record collection and analysis metadata separately when needed. Set a stable locale and sort using explicitly selected fields.

This exercise receives already validated, unique findings. It publishes them in timestamp, event ID and reason order, and counts total findings and distinct affected users. Counts must be derived from the data, not inferred from the last row or copied from an earlier run.

Stage, then publish

Create a private temporary directory with a portable mktemp -d template. Register an EXIT trap immediately, then generate complete files there. Only after successful generation should you move the known reports to the output directory. This avoids exposing a half-written report during ordinary processing failures.

Moving several files one after another is not a transactional publication of the whole directory. A production system needing that guarantee would publish a versioned directory or manifest pointer. Here the contract is narrower: missing required input must preserve the previous reports, and successful reruns must replace them. Never clean up using a broad wildcard against evidence; remove only the temporary directory you created.

Try an example.sh
awk -F '\t' 'NR>1 {users[$3]=1;n++} END {for(u in users) distinct++;printf "findings=%d users=%d\n",n,distinct}' selected.tsv
YOUR TURN

Put it into practice.

Accept an optional output directory argument, default reports. selected.tsv is required and has validated unique id<TAB>timestamp<TAB>user<TAB>reason rows. Write findings.tsv with the same header, sorted by timestamp, then ID, then reason in LC_ALL=C order. Write summary.txt with findings=N and users=N on separate lines, counting distinct users. Missing input exits nonzero with Missing selected evidence on stderr without changing previous reports. Successful repeated runs replace reports and leave selected.tsv unchanged; paths may contain spaces.

See an explained solution
One way to solve it.sh
export LC_ALL=C
out=${1:-reports}
[ -f selected.tsv ] || { printf 'Missing selected evidence\n' >&2; exit 1; }
tmp=$(mktemp -d "${TMPDIR:-/tmp}/rocks-report.XXXXXX") || exit 1
trap 'rm -rf "$tmp"' EXIT
printf 'id\ttimestamp\tuser\treason\n' > "$tmp/findings.tsv"
awk 'NR>1' selected.tsv | sort -t $'\t' -k2,2 -k1,1 -k4,4 >> "$tmp/findings.tsv" || exit 1
awk -F '\t' 'NR>1 {n++;u[$3]=1} END {for(k in u) count++;printf "findings=%d\nusers=%d\n",n,count}' selected.tsv > "$tmp/summary.txt" || exit 1
mkdir -p "$out" || exit 1
mv "$tmp/findings.tsv" "$out/findings.tsv" || exit 1
mv "$tmp/summary.txt" "$out/summary.txt"

The script checks prerequisites first and writes complete reports in a private temporary directory. Explicit sorting and derived counts make repeated runs stable; the EXIT trap removes temporary work on both success and failure.