30-second answer
assess evaluates evidence and writes an assessment: a single document
carrying the findings, the evidence they were decided from, the versions that
decided them, and digests over all of it. The recipient runs
verify and establishes
that nothing moved, without having this engine and without trusting whoever
sent it.
m365-governance assess [-h] [--rules RULES] --evidence EVIDENCE
[--profile PROFILE] [--label LABEL]
[--created-at CREATED_AT] [--out OUT]How it differs from evaluate
Not the format. evaluate renders a report for you to read. An assessment is a
package for somebody else: it contains what it was decided from, so the
conclusion can be re-derived rather than believed.
Options
--label is what to call it, and the help text is explicit that it is
never used to identify anything. Renaming an assessment does not produce a
different one, because the identity comes from the content.
--created-at is the timestamp to record, as ISO 8601, defaulting to now.
Supply it to rebuild an assessment byte for byte.
That option exists because the clock is read at exactly one boundary and then passed as a value. An assessment whose digest moved because time passed would be unverifiable by construction.
--out is where to write it. Omit it to write to stdout. When you do
supply it, the assessment identifier and the path go to stderr, so a pipeline
redirecting stdout still shows a human which document was produced.
When it refuses
assess will not assemble a document whose manifest would say something the
evidence does not support:
refusing to assemble an assessment: <what did not line up>That is a sentence rather than a traceback, and it is a refusal rather than a finding. The alternative would be a signed document making a claim nobody can back.
Exit codes
0 written. 2 refused: no evidence documents were found, the evidence did
not match the schema, or the manifest could not be assembled honestly.