refactor: move diagnostic runtime to typst
Win Diagnostics CI All diagnostic checks passed.
Beffroi/win-diagnostics/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-09-16 01:20:03 +02:00
parent 00a7e8122c
commit e1ae8bb5df
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
13 changed files with 211 additions and 130 deletions

View File

@ -186,7 +186,7 @@ integration interface.
## Development principles
Production collection and analysis must not require Python. Use PowerShell for
native Windows collection, shell and jq for portable offline processing, and
native Windows collection, shell and Typst for portable offline processing, and
Make for the public interface. Python may exist only in `tests/`, must run
through a uv-managed virtual environment, and must not be called by production.

View File

@ -2,8 +2,8 @@
## Pass 5 — Runtime without Python
- [x] WD5.1 Port offline normalization and rule analysis to shell and jq with identical deterministic fixtures.
- [x] WD5.2 Port diagnostic validation and evidence verification to shell and jq.
- [x] WD5.1 Port offline normalization and rule analysis to shell and Typst with identical deterministic fixtures.
- [x] WD5.2 Port diagnostic validation and evidence verification to shell and Typst.
- [x] WD5.3 Provide Make targets for collection, analysis, validation, and uv-managed tests.
- [x] WD5.4 Remove production Python files and prove tests are the only Python consumers.

2
Jenkinsfile vendored
View File

@ -22,7 +22,7 @@ pipeline {
conclusion: 'SUCCESS',
name: 'Win Diagnostics CI',
summary: 'All diagnostic checks passed.',
text: 'Contracts, evidence integrity, fixtures, rules, watchlists, and the shell/jq runtime passed.',
text: 'Contracts, evidence integrity, fixtures, rules, watchlists, and the shell/Typst runtime passed.',
title: 'Win Diagnostics CI passed'
)
echo '✅ Win Diagnostics CI passed.'

View File

@ -14,9 +14,9 @@ as `unanalysed`. It does not render reports or PDFs.
## Requirements
Runtime analysis requires Bash, jq, and standard Unix utilities. The component
has no dependency on Reportist, Beffroi
Reports, or the integration workspace.
Runtime analysis requires Bash, Typst 0.15 or newer, and standard Unix
utilities. The component has no dependency on Reportist, Beffroi Reports, or
the integration workspace.
## Analyse a capture

View File

@ -15,7 +15,7 @@ make test
The suite covers diagnostic contract validation, evidence hashes and JSON
Pointers, supported capture schemas, collection limitations, deterministic
analysis, event grouping, the complete rule catalog, watchlist gates, standalone
operation, and the production shell/jq runtime.
operation, and the production shell/Typst runtime.
## Rule maintenance
@ -36,4 +36,4 @@ When changing a rule:
`schemas/diagnostic.schema.json` is a public interface. Preserve compatibility
for existing consumers or introduce a new schema version with documented
mapping. Keep test-only Python support code under `tests/`; production analysis
and validation remain shell/jq based.
and validation remain shell/Typst based.

View File

@ -6,7 +6,7 @@ examples, not a migrated collector or analysis engine.
## Install and validate independently
Bash and jq are required at runtime. From a standalone component checkout:
Bash and Typst 0.15 or newer are required at runtime. From a standalone component checkout:
```bash
make validate INPUT=examples/diagnostic.json

View File

@ -2,7 +2,7 @@
## Install and verify
Runtime analysis requires Bash, jq, and standard Unix utilities. Python and uv
Runtime analysis requires Bash, Typst 0.15 or newer, and standard Unix utilities. Python and uv
are used only for tests. Reportist,
beffroi-reports, the integration workspace, and legacy sources are not runtime
dependencies.

View File

@ -1,92 +0,0 @@
def slug: tostring | gsub("[^A-Za-z0-9._:-]+"; "-") | gsub("^-|-$"; "") | ascii_downcase | if . == "" then "unknown" else . end;
def timestamp: type == "string" and test("^[0-9]{4}-[0-9]{2}-[0-9]{2}T.*(Z|[+-][0-9]{2}:[0-9]{2})$");
def epoch:
capture("^(?<date>[0-9]{4}-[0-9]{2}-[0-9]{2})T(?<time>[0-9]{2}:[0-9]{2}:[0-9]{2})(?:\\.[0-9]+)?(?<zone>Z|[+-][0-9]{2}:[0-9]{2})$") as $p |
(($p.date+"T"+$p.time+"Z")|fromdateiso8601) as $base |
if $p.zone=="Z" then $base else ($p.zone|capture("(?<sign>[+-])(?<hour>[0-9]{2}):(?<minute>[0-9]{2})")) as $z |
$base - ((if $z.sign=="+" then 1 else -1 end)*(($z.hour|tonumber)*3600+($z.minute|tonumber)*60)) end;
def ptr($parts): "/" + ($parts | map(tostring | gsub("~";"~0") | gsub("/";"~1")) | join("/"));
def normalize_section:
if type != "object" then {status:"unavailable",record_count:null,truncated:false,reason:"Legacy section is not an object."}
else . as $s | ($s.status // null) as $source |
(if ["ok","skipped","unavailable"] | index($source) then $source else "unavailable" end) as $status |
{status:$status,
record_count:(if ($s.count|type)=="number" and $s.count >= 0 and ($s.count|floor)==$s.count then $s.count elif ($s.data|type)=="array" then ($s.data|length) else null end),
truncated:($s.truncated // false | if . then true else false end)} +
(if $status == "ok" then {} else {reason:(if ($s.error|type)=="string" and ($s.error|test("\\S")) then $s.error elif ["skipped","unavailable"]|index($source) then "Legacy capture marked section \($status) without a reason." else "Legacy capture used unsupported section status: \($source)." end)} end)
end;
def rule_for($rules;$provider;$id): first($rules[] | select(.provider == $provider and (.event_id|tostring)==($id|tostring))) // null;
def event_sig($provider;$id;$time;$message): [$provider,($id|tostring),($time|tostring|sub("\\.[0-9]+Z$";"Z")),($message//""|tostring|gsub("\\s+";" "))] | @json;
def add_event($section;$index;$event;$time_field;$provider_field;$id_field):
($event[$provider_field] // "Unknown provider" | tostring) as $provider |
($event[$id_field] // "unknown") as $id |
{id:"event-\($section|slug)-\($index+1)",section:$section,source_pointer:ptr(["sections",$section,"data",$index]),value:$event,
_provider:$provider,_event_id:$id,_signature:event_sig($provider;$id;$event[$time_field];$event.Message)} +
(if ($event[$time_field]|timestamp) then {observed_at:$event[$time_field]} else {} end);
def watch_matches($capture;$matcher):
($capture.sections[$matcher.section] // null) as $section |
if ($section|type)!="object" or $section.status != "ok" or ($section.data|type)!="array" then [] else
[$section.data | to_entries[] | select((.value|type)=="object") |
. as $entry | ($entry.value[$matcher.field] // "" | tostring | gsub("^\"|\"$";"") | gsub("\\\\";"/")) as $raw |
(if $matcher.basename then ($raw|split("/")|last) else $raw end) as $identity |
select([$matcher.values[]|tostring|ascii_downcase] | index(($identity|tostring|ascii_downcase))) |
select(($matcher.versions // null)==null or (($matcher.versions|index($entry.value[$matcher.version_field // "DriverVersion"]|tostring)) != null)) |
select(($matcher.enabled_only // false)|not or ([2,"Enabled","enabled"]|index($entry.value.State) != null)) |
{section:$matcher.section,index:$entry.key,item:$entry.value}]
end;
($rules[0]) as $rules | ($watchlist[0]) as $watchlist | . as $capture |
($capture.schema_version) as $version |
if (($version|type)!="number" or ([$version]|inside([1,2])|not)) then error("unsupported legacy capture schema version")
elif ($capture.sections|type)!="object" then error("legacy capture requires an object at /sections")
elif ($capture.generated_at|timestamp|not) then error("/generated_at: expected a timezone-qualified ISO timestamp")
elif ($reference_time|timestamp|not) then error("--reference-time: expected a timezone-qualified ISO timestamp")
else
($capture.sections | with_entries(.value |= normalize_section)) as $sections |
(if ($sections|length)>0 and all($sections[]; .status=="ok" and (.truncated|not)) then "complete" else "partial" end) as $collection_status |
(if $version==1 then ["recent_system_errors","recent_application_errors"] else ["recent_system_events","recent_application_events"] end) as $event_sections |
(reduce $event_sections[] as $name ([];
. + [($capture.sections[$name].data // [] | to_entries[] | select((.value|type)=="object") | add_event($name;.key;.value;"TimeCreated";"ProviderName";"Id"))]
)) as $primary |
(reduce (($capture.sections.reliability_records.data // []) | to_entries[]) as $entry
({items:$primary,signatures:($primary|map(._signature))};
($entry.value.SourceName // "Unknown provider"|tostring) as $provider |
($entry.value.EventIdentifier // "unknown") as $id |
(rule_for($rules;$provider;$id)) as $rule |
(event_sig($provider;$id;$entry.value.TimeGenerated;$entry.value.Message)) as $sig |
if $rule != null and (["warning","critical"]|index($rule.severity)) and (.signatures|index($sig)|not) then
.items += [add_event("reliability_records";$entry.key;$entry.value;"TimeGenerated";"SourceName";"EventIdentifier")] | .signatures += [$sig]
else . end
).items) as $events |
(reduce $events[] as $event ([];
($event._provider+"\u0000"+($event._event_id|tostring)) as $key |
if any(.[]; .key==$key) then map(if .key==$key then .evidence += [$event.id] else . end)
else . + [{key:$key,provider:$event._provider,event_id:$event._event_id,evidence:[$event.id]}] end
)) as $groups |
([$groups[] | . as $group | (rule_for($rules;.provider;.event_id)) as $rule |
if $rule == null then {id:"event-\(.provider|slug)-\(.event_id|slug)",severity:"unanalysed",confidence:0,title:"Unanalysed event: \(.provider) / \(.event_id)",description:"The event is preserved for review; no migrated technical rule matches it.",evidence}
else {id:"event-\(.provider|slug)-\(.event_id|slug)",severity:$rule.severity,confidence:(if $collection_status=="complete" then $rule.confidence else ([50,$rule.confidence]|min) end),title:"\(.provider) event \(.event_id)",description:$rule.description,evidence} +
(if ($rule.fading//false) then
([.evidence[] as $id | $events[] | select(.id==$id and .observed_at) | .observed_at | epoch] | max // null) as $latest |
if $latest==null then {relevance_weight:1} else (($reference_time|epoch)-$latest)/86400|floor as $age |
{relevance_weight:(if $age<=7 then 1 elif $age>=90 then 0.5 else (1-0.5*($age-7)/83)*1000000|round/1000000 end),age_days:([$age,0]|max)} end
else {} end)
end]) as $event_findings |
(reduce $watchlist[] as $entry ({observations:$events,findings:$event_findings};
([$entry.match[] | watch_matches($capture;.)[]]) as $matches |
([$entry.requires[]? | watch_matches($capture;.)]) as $requirements |
(if $entry.events then [.observations[] | select((.value.ProviderName//"")==$entry.events.provider and ($entry.events.ids|map(tostring)|index(.value.Id|tostring))) | .id] else [] end) as $event_evidence |
if ($matches|length)==0 or any($requirements[];length==0) or ($entry.events and (($event_evidence|length)<$entry.events.minimum)) then .
else ([$matches[], $requirements[][]] | unique_by([.section,.index])) as $all |
reduce $all[] as $match (.;
("watch-\($entry.id|slug)-\($match.section|slug)-\($match.index+1)") as $id |
if any(.observations[];.id==$id) then . else .observations += [{id:$id,section:$match.section,source_pointer:ptr(["sections",$match.section,"data",$match.index]),value:$match.item}] end) |
.findings += [{id:"watchlist-\($entry.id)",severity:"warning",confidence:(if $collection_status=="complete" then 85 else 50 end),title:$entry.title,description:$entry.description,evidence:(([$all[]|"watch-\($entry.id|slug)-\(.section|slug)-\(.index+1)"]+$event_evidence)|unique)}]
end
)) as $analysed |
{schema_version:1,metadata:{producer:{name:"win-diagnostics",version:$producer_version},collected_at:$capture.generated_at,analysis_reference_time:$reference_time,source:{artifact:$artifact,schema_version:$version,sha256:$artifact_hash}},
system:({host:($capture.host//{})}+(if ($capture.summary|type)=="object" then {legacy_summary:$capture.summary} else {} end)),
collection:{mode:($capture.mode//"Full"),status:$collection_status,sections:$sections},
observations:[$analysed.observations[]|del(._provider,._event_id,._signature)],findings:$analysed.findings,
warnings:([$capture.warnings[]?|tostring|select(test("\\S"))]+(if $collection_status!="complete" then ["Legacy capture collection is incomplete; finding confidence is capped at 50."] else [] end)+["Migrated analyser supports \($rules|length) event rules and \($watchlist|length) candidate watchlist entries; unmatched events remain unanalysed."])}
end

View File

@ -14,10 +14,12 @@ output_parent=$(dirname "$output"); mkdir -p "$output_parent"; output=$(cd "$out
[[ "$input" != "$output" ]] || fail "input and output paths must differ"
[[ ! -e "$output" || "$force" == true ]] || fail "$output: output exists; use --force to replace it"
artifact=${input#"$evidence_root/"}; hash=$(sha256_file "$input")
temporary=$(mktemp "$(dirname "$output")/.${output##*/}.XXXXXXXX"); trap 'rm -f "$temporary"' EXIT
jq --arg artifact "$artifact" --arg artifact_hash "$hash" --arg reference_time "$reference_time" --arg producer_version "$producer_version" \
--slurpfile rules "$root/rules/event-rules.json" --slurpfile watchlist "$root/rules/watchlist.json" \
-f "$root/tools/analyse.jq" "$input" >"$temporary" || fail "analysis failed"
temporary=$(mktemp "$(dirname "$output")/.${output##*/}.XXXXXXXX")
stage=$(mktemp -d "${TMPDIR:-/tmp}/win-diagnostics.XXXXXXXX"); trap 'rm -f "$temporary"; rm -rf "$stage"' EXIT
cp "$input" "$stage/capture.json"; cp "$root/rules/event-rules.json" "$stage/event-rules.json"; cp "$root/rules/watchlist.json" "$stage/watchlist.json"; cp "$root/tools/analyse.typ" "$stage/analyse.typ"
typst query --root "$stage" --input capture=capture.json --input rules=event-rules.json --input watchlist=watchlist.json \
--input "artifact=$artifact" --input "artifact-hash=$hash" --input "reference-time=$reference_time" --input "producer-version=$producer_version" \
"$stage/analyse.typ" '<diagnostic>' --field value --one >"$temporary" 2>/dev/null || fail "analysis failed"
"$root/tools/validate.sh" "$temporary" --evidence-root "$evidence_root" || fail "generated diagnostic is invalid"
if [[ "$force" == true ]]; then mv -f "$temporary" "$output"; else ln "$temporary" "$output"; fi
echo "Wrote validated diagnostic v1: $output"

148
tools/analyse.typ Normal file
View File

@ -0,0 +1,148 @@
#let capture = json(sys.inputs.at("capture"))
#let rules = json(sys.inputs.at("rules"))
#let watchlist = json(sys.inputs.at("watchlist"))
#let get(data, key, default: none) = data.at(key, default: default)
#let text(value) = if value == none { "" } else { str(value) }
#let slug(value) = { let out = lower(str(value).replace(regex("[^A-Za-z0-9._:-]+"), "-").trim("-")); if out == "" { "unknown" } else { out } }
#let timestamp(value) = type(value) == str and value.match(regex("^[0-9]{4}-[0-9]{2}-[0-9]{2}T.*(Z|[+-][0-9]{2}:[0-9]{2})$")) != none
#let pointer(parts) = "/" + parts.map(value => str(value).replace("~", "~0").replace("/", "~1")).join("/")
#let rule-for(provider, id) = rules.find(rule => rule.provider == provider and str(rule.event_id) == str(id))
#let normalize-section(section) = {
if type(section) != dictionary { return (status: "unavailable", record_count: none, truncated: false, reason: "Legacy section is not an object.") }
let source = get(section, "status")
let status = if source in ("ok", "skipped", "unavailable") { source } else { "unavailable" }
let count = get(section, "count")
if type(count) != int or count < 0 { let data = get(section, "data"); count = if type(data) == array { data.len() } else { none } }
let truncated = get(section, "truncated", default: false)
let result = (status: status, record_count: count, truncated: if type(truncated) == bool { truncated } else { false })
if status != "ok" {
let reason = get(section, "error")
if type(reason) != str or reason.match(regex("\\S")) == none {
reason = if source in ("skipped", "unavailable") { "Legacy capture marked section " + status + " without a reason." } else { "Legacy capture used unsupported section status: " + str(source) + "." }
}
result.insert("reason", reason)
}
result
}
#let event-signature(provider, id, time, message) = json.encode((provider, text(id), text(time).replace(regex("\\.[0-9]+Z$"), "Z"), text(message).replace(regex("\\s+"), " ")))
#let add-event(section, index, event, time-field, provider-field, id-field) = {
let provider = str(get(event, provider-field, default: "Unknown provider")); let id = get(event, id-field, default: "unknown")
let item = (id: "event-" + slug(section) + "-" + str(index + 1), section: section, source_pointer: pointer(("sections", section, "data", index)), value: event,
_provider: provider, _event_id: id, _signature: event-signature(provider, id, get(event, time-field), get(event, "Message", default: "")))
if timestamp(get(event, time-field)) { item.insert("observed_at", get(event, time-field)) }
item
}
#let watch-matches(matcher) = {
let section = get(capture.sections, matcher.section)
if type(section) != dictionary or get(section, "status") != "ok" or type(get(section, "data")) != array { return () }
let matches = ()
for pair in section.data.enumerate() {
let item = pair.last()
if type(item) == dictionary {
let raw = text(get(item, matcher.field, default: "")).trim("\"").replace("\\", "/")
let identity = if get(matcher, "basename", default: false) { raw.split("/").last() } else { raw }
let accepted = matcher.values.map(value => lower(str(value))).contains(lower(identity))
let versions = get(matcher, "versions")
let version-ok = versions == none or versions.contains(text(get(item, get(matcher, "version_field", default: "DriverVersion"), default: "")))
let enabled-ok = not get(matcher, "enabled_only", default: false) or get(item, "State") in (2, "Enabled", "enabled")
if accepted and version-ok and enabled-ok { matches.push((section: matcher.section, index: pair.first(), item: item)) }
}
}
matches
}
#let version = get(capture, "schema_version")
#assert(type(version) == int and version in (1, 2), message: "unsupported legacy capture schema version")
#assert(type(get(capture, "sections")) == dictionary, message: "legacy capture requires an object at /sections")
#assert(timestamp(get(capture, "generated_at")), message: "/generated_at requires a timezone-qualified timestamp")
#assert(timestamp(sys.inputs.at("reference-time")), message: "--reference-time requires a timezone-qualified timestamp")
#let sections = (:)
#for pair in capture.sections.pairs() { sections.insert(pair.first(), normalize-section(pair.last())) }
#let complete = sections.len() > 0 and sections.values().all(section => section.status == "ok" and not section.truncated)
#let collection-status = if complete { "complete" } else { "partial" }
#let selected = if version == 1 { ("recent_system_errors", "recent_application_errors") } else { ("recent_system_events", "recent_application_events") }
#let observations = ()
#for name in selected {
let section = get(capture.sections, name)
if type(section) == dictionary and type(get(section, "data")) == array {
for pair in section.data.enumerate() { if type(pair.last()) == dictionary { observations.push(add-event(name, pair.first(), pair.last(), "TimeCreated", "ProviderName", "Id")) } }
}
}
#let signatures = observations.map(item => item._signature)
#let reliability = get(capture.sections, "reliability_records")
#if type(reliability) == dictionary and type(get(reliability, "data")) == array {
for pair in reliability.data.enumerate() {
let record = pair.last()
if type(record) == dictionary {
let provider = str(get(record, "SourceName", default: "Unknown provider")); let id = get(record, "EventIdentifier", default: "unknown")
let rule = rule-for(provider, id); let signature = event-signature(provider, id, get(record, "TimeGenerated"), get(record, "Message", default: ""))
if rule != none and rule.severity in ("warning", "critical") and not signatures.contains(signature) {
observations.push(add-event("reliability_records", pair.first(), record, "TimeGenerated", "SourceName", "EventIdentifier")); signatures.push(signature)
}
}
}
}
#let groups = (:)
#for event in observations {
let key = json.encode((event._provider, str(event._event_id)))
let evidence = get(groups, key, default: (provider: event._provider, event_id: event._event_id, evidence: ()))
evidence.evidence.push(event.id); groups.insert(key, evidence)
}
#let findings = ()
#for group in groups.values() {
let rule = rule-for(group.provider, group.event_id)
if rule == none {
findings.push((id: "event-" + slug(group.provider) + "-" + slug(group.event_id), severity: "unanalysed", confidence: 0,
title: "Unanalysed event: " + group.provider + " / " + str(group.event_id), description: "The event is preserved for review; no migrated technical rule matches it.", evidence: group.evidence))
} else {
let confidence = if complete { rule.confidence } else { calc.min(50, rule.confidence) }
let finding = (id: "event-" + slug(group.provider) + "-" + slug(group.event_id), severity: rule.severity, confidence: confidence,
title: group.provider + " event " + str(group.event_id), description: rule.description, evidence: group.evidence)
if get(rule, "fading", default: false) { finding.insert("relevance_weight", 1.0) }
findings.push(finding)
}
}
#for entry in watchlist {
let matches = (); for matcher in entry.match { matches += watch-matches(matcher) }
let requirements = (); for matcher in get(entry, "requires", default: ()) { requirements.push(watch-matches(matcher)) }
let event-gate = get(entry, "events"); let event-evidence = ()
if event-gate != none { event-evidence = observations.filter(item => str(get(item.value, "ProviderName", default: "")) == event-gate.provider and event-gate.ids.map(str).contains(str(get(item.value, "Id", default: "")))).map(item => item.id) }
if matches.len() > 0 and requirements.all(group => group.len() > 0) and (event-gate == none or event-evidence.len() >= event-gate.minimum) {
let evidence = ()
for item in matches + requirements.join() {
let id = "watch-" + slug(entry.id) + "-" + slug(item.section) + "-" + str(item.index + 1)
if not observations.any(observation => observation.id == id) { observations.push((id: id, section: item.section, source_pointer: pointer(("sections", item.section, "data", item.index)), value: item.item)) }
if not evidence.contains(id) { evidence.push(id) }
}
for id in event-evidence { if not evidence.contains(id) { evidence.push(id) } }
findings.push((id: "watchlist-" + entry.id, severity: "warning", confidence: if complete { 85 } else { 50 }, title: entry.title, description: entry.description, evidence: evidence))
}
}
#let warnings = get(capture, "warnings", default: ()).map(str).filter(item => item.match(regex("\\S")) != none)
#if not complete { warnings.push("Legacy capture collection is incomplete; finding confidence is capped at 50.") }
#warnings.push("Migrated analyser supports " + str(rules.len()) + " event rules and " + str(watchlist.len()) + " candidate watchlist entries; unmatched events remain unanalysed.")
#let clean-observations = observations.map(item => {
let clean = item
let _ = clean.remove("_provider", default: none)
let _ = clean.remove("_event_id", default: none)
let _ = clean.remove("_signature", default: none)
clean
})
#let system = (host: get(capture, "host", default: (:)))
#if type(get(capture, "summary")) == dictionary { system.insert("legacy_summary", capture.summary) }
#let result = (
schema_version: 1,
metadata: (producer: (name: "win-diagnostics", version: sys.inputs.at("producer-version")), collected_at: capture.generated_at,
analysis_reference_time: sys.inputs.at("reference-time"), source: (artifact: sys.inputs.at("artifact"), schema_version: version, sha256: sys.inputs.at("artifact-hash"))),
system: system,
collection: (mode: get(capture, "mode", default: "Full"), status: collection-status, sections: sections),
observations: clean-observations,
findings: findings,
warnings: warnings,
)
#metadata(result) <diagnostic>

View File

@ -2,30 +2,21 @@
set -euo pipefail
usage(){ echo "Usage: $0 INPUT [--evidence-root DIR]" >&2; exit 2; }; fail(){ echo "error: $*" >&2; exit 1; }
sha256_file(){ if command -v sha256sum >/dev/null 2>&1; then sha256sum "$1"|awk '{print $1}'; elif command -v sha256 >/dev/null 2>&1; then sha256 -q "$1"; else openssl dgst -sha256 "$1"|awk '{print $NF}'; fi; }
json_string(){ local value=$1; [[ "$value" == \"*\" ]]||fail "Typst returned a non-string value"; value=${value:1:${#value}-2}; [[ "$value" != *\\* && "$value" != *\"* ]]||fail "unsupported escaped path"; printf '%s' "$value"; }
input=${1:-}; [[ -n "$input" ]]||usage; shift; evidence_root=
while (($#)); do case $1 in --evidence-root) evidence_root=$2;shift 2;;*) usage;;esac; done
jq -e '
type=="object" and .schema_version==1 and (.metadata|type)=="object" and
(.metadata.producer.name|type)=="string" and (.metadata.producer.version|type)=="string" and
(.metadata.source.artifact|type)=="string" and (.metadata.source.sha256|test("^[a-f0-9]{64}$")) and
(.collection.sections|type)=="object" and (.observations|type)=="array" and (.findings|type)=="array" and
(([.observations[].id]|length)==([.observations[].id]|unique|length)) and
(([.findings[].id]|length)==([.findings[].id]|unique|length)) and
([.observations[].section] - ([.collection.sections|keys[]]))==[] and
(([.observations[].id]) as $ids | all(.findings[].evidence[]?; $ids|index(.)!=null)) and
(if .collection.status=="complete" then (.collection.sections|length)>0 and all(.collection.sections[];.status=="ok" and (.truncated|not)) else true end)
' "$input" >/dev/null || fail "invalid diagnostic v1: $input"
while (($#)); do case $1 in --evidence-root) (($#>=2))||usage; evidence_root=$2;shift 2;;*) usage;;esac; done
root=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd -P); input=$(realpath "$input")
stage=$(mktemp -d "${TMPDIR:-/tmp}/diagnostic-validate.XXXXXXXX"); trap 'rm -rf "$stage"' EXIT
cp "$input" "$stage/diagnostic.json"; cp "$root/tools/validate.typ" "$stage/validate.typ"
typst query --root "$stage" --input diagnostic=diagnostic.json "$stage/validate.typ" '<validated>' --one >/dev/null 2>&1||fail "invalid diagnostic v1: $input"
if [[ -n "$evidence_root" ]]; then
artifact=$(jq -r '.metadata.source.artifact' "$input")
[[ "$artifact" != /* && "$artifact" != *..* && "$artifact" != *\\* ]] || fail "source artifact escapes evidence root"
source=$(realpath "$evidence_root/$artifact"); root=$(realpath "$evidence_root")
[[ "$source" == "$root"/* && -f "$source" ]] || fail "source artifact escapes evidence root"
expected=$(jq -r '.metadata.source.sha256' "$input"); actual=$(sha256_file "$source")
[[ "$actual" == "$expected" ]] || fail "evidence checksum differs"
jq -e --slurpfile raw "$source" '
$raw[0] as $raw | all(.observations[]; . as $observation |
(.source_pointer|split("/")[1:]|map(gsub("~1";"/")|gsub("~0";"~")|if test("^[0-9]+$") then tonumber else . end)) as $path |
(try (($raw|getpath($path)) == $observation.value) catch false))
' "$input" >/dev/null || fail "observation differs from referenced raw evidence"
artifact=$(json_string "$(typst query --root "$stage" --input diagnostic=diagnostic.json "$stage/validate.typ" '<source>' --field value --one 2>/dev/null)")
expected=$(json_string "$(typst query --root "$stage" --input diagnostic=diagnostic.json "$stage/validate.typ" '<hash>' --field value --one 2>/dev/null)")
[[ "$artifact" != /* && "$artifact" != *..* ]]||fail "source artifact escapes evidence root"
source=$(realpath "$evidence_root/$artifact"); evidence_base=$(realpath "$evidence_root")
[[ "$source" == "$evidence_base"/* && -f "$source" ]]||fail "source artifact escapes evidence root"
[[ $(sha256_file "$source") == "$expected" ]]||fail "evidence checksum differs"
cp "$source" "$stage/raw.json"; cp "$root/tools/verify-evidence.typ" "$stage/verify-evidence.typ"
typst query --root "$stage" --input diagnostic=diagnostic.json --input raw=raw.json "$stage/verify-evidence.typ" '<verified>' --one >/dev/null 2>&1||fail "observation differs from referenced raw evidence"
fi
echo "Valid diagnostic v1: $input"

17
tools/validate.typ Normal file
View File

@ -0,0 +1,17 @@
#let diagnostic = json(sys.inputs.at("diagnostic"))
#assert(type(diagnostic) == dictionary and diagnostic.at("schema_version", default: none) == 1, message: "invalid diagnostic schema")
#assert(type(diagnostic.at("metadata", default: none)) == dictionary, message: "missing metadata")
#assert(type(diagnostic.at("collection", default: none)) == dictionary and type(diagnostic.collection.sections) == dictionary, message: "invalid collection")
#assert(type(diagnostic.at("observations", default: none)) == array and type(diagnostic.at("findings", default: none)) == array, message: "invalid observations or findings")
#let ids = diagnostic.observations.map(item => item.id)
#assert(ids.dedup().len() == ids.len(), message: "duplicate observation ID")
#let finding-ids = diagnostic.findings.map(item => item.id)
#assert(finding-ids.dedup().len() == finding-ids.len(), message: "duplicate finding ID")
#assert(diagnostic.observations.all(item => item.section in diagnostic.collection.sections), message: "unknown collection section")
#assert(diagnostic.findings.all(item => item.evidence.all(id => id in ids)), message: "unknown observation evidence")
#if diagnostic.collection.status == "complete" {
assert(diagnostic.collection.sections.len() > 0 and diagnostic.collection.sections.values().all(section => section.status == "ok" and not section.truncated), message: "invalid complete collection")
}
#metadata(diagnostic.metadata.source.artifact) <source>
#metadata(diagnostic.metadata.source.sha256) <hash>
#metadata(true) <validated>

15
tools/verify-evidence.typ Normal file
View File

@ -0,0 +1,15 @@
#let diagnostic = json(sys.inputs.at("diagnostic"))
#let raw = json(sys.inputs.at("raw"))
#assert(raw.at("schema_version", default: none) == diagnostic.metadata.source.schema_version, message: "capture version differs")
#let resolve(pointer) = {
let value = raw
for encoded in pointer.split("/").slice(1) {
let token = encoded.replace("~1", "/").replace("~0", "~")
value = if type(value) == array { value.at(int(token)) } else { value.at(token) }
}
value
}
#for observation in diagnostic.observations {
assert(resolve(observation.source_pointer) == observation.value, message: "observation differs from referenced raw evidence")
}
#metadata(true) <verified>