What this documentation is

Every conclusion the engine produces is traceable back to collected evidence, explicit rules and published sources. If it cannot justify a conclusion, it does not make one.

What this manual is, and is not

Documentation owns how the product works: the manual, and the catalogue projected from the Engine. It is the only place on this site that does.

What does not belong here, and where each lives instead:

Start here

The journey below runs in the order somebody takes it: install it, see it work against packaged evidence with no tenant at all, then connect, collect, assess, inspect, compare and verify.

Begin with Install. The reference sections underneath explain each part in full, and a step links into them rather than restating them.

Getting started

The journey, in the order somebody takes it.

Install

  1. 01
    Install

    What do I actually need on this machine, and how do I know it worked?

See it work

  1. 01
    See it work

    I have installed it. What do I run, in what order, and what am I looking at?

Connect

  1. 01
    Connect

    Why does it insist on a client id, and what identity should I give it?

Collect

  1. 01
    Collect

    I have an app registration. How do I collect, and what do I get?

Assess

  1. 01
    Assess

    I have evidence. How do I get an answer, and what is that answer worth?

Inspect

  1. 01
    Inspect

    A report just landed on my desk. What am I looking at, from the top?

Compare

  1. 01
    Compare

    Something moved. Did the tenant change, or did the rule?

Verify

  1. 01
    Verify

    How do I establish that it holds, without their engine and without trusting them?

Capabilities

What the Engine can establish today, and what it cannot.

The capability map

  1. 01
    Capability map

    What can this product establish about a tenant today?

  2. 02
    What we can establish

    Which governance questions can this product answer defensibly today?

Coverage

  1. 01
    Coverage

    What has been proven against a real tenant, and what has not?

Core Concepts

The vocabulary every assessment and report uses.

Evidence chain

  1. 01
    What read-only gates prove

    If CI says the collector has no write path, what exactly has been established?

  2. 02
    Run, RunSet, Assessment

    What exactly is the verifiable unit a governance evaluation produces?

  3. 03
    Canonical JSON and digests

    How can the same document hash differently on two machines that both follow the JSON spec?

Provenance

  1. 01
    What provenance changes

    What must travel with a finding for it to be worth acting on?

  2. 02
    Fixture vs observation

    When a result is computed from example evidence, what stops it being presented as a real reading?

Coverage

  1. 01
    Incomplete evidence and lower bounds

    Can a partial count ever settle a governance question?

  2. 02
    Unknown vs invalid-evidence

    When a governance report says unknown, what exactly failed, and who fixes it?

  3. 03
    Set aside, not excluded

    What should a governance profile do with system lists it did not create?

  4. 04
    Outcome, severity, attention

    A rule failed with severity medium, so how urgent is it?

  5. 05
    The collection manifest

    The evidence folder has ten files. Is that all of them, or all that could be read?

Collectors

What each collector observes, and what it cannot see.

Entra ID

  1. 01
    conditional-access

    The Conditional Access policies, named locations and Security Defaults state of one tenant?

Overview

  1. 01
    Overview

    Something is going to run against my production tenant. What exactly does it do?

Across the tenant

  1. 01
    sites

    What sites exist, and how much of the tenant can this identity actually see?

  2. 02
    tenant-sharing

    What does the organisation permit, before any individual site is looked at?

About one site

  1. 01
    owners

    Who administers this site, and can the engine actually count them?

  2. 02
    sharing

    What can be shared from this site, and what link do users get by default?

  3. 03
    activity

    Is this site actually abandoned, or does a system process keep touching it?

  4. 04
    classification

    Does this site record what kind of content it holds, and is the label resolvable?

  5. 05
    modernity

    How is this site built, and what does the engine refuse to call classic?

Inside a site

  1. 01
    permissions

    Which lists break inheritance, and why is the expensive count off by default?

  2. 02
    spfx

    Which solutions in the app catalog are behind the version it holds?

  3. 03
    agents

    What Copilot agents live in this site, and what were they pointed at?

Rules

How a rule is written, what it must declare, and how it is tested.

Every rule

  1. 01
    Catalogue

    Which questions does this product ask, and on what authority?

  2. 02
    SPO-ACTIVITY-001

    What does SPO-ACTIVITY-001 decide, and on what authority?

  3. 03
    SPO-CLASS-001

    What does SPO-CLASS-001 decide, and on what authority?

  4. 04
    SPO-CLASS-002

    What does SPO-CLASS-002 decide, and on what authority?

  5. 05
    SPO-CLASS-003

    What does SPO-CLASS-003 decide, and on what authority?

  6. 06
    SPO-CLASS-004

    What does SPO-CLASS-004 decide, and on what authority?

  7. 07
    SPO-LIST-001

    What does SPO-LIST-001 decide, and on what authority?

  8. 08
    SPO-LIST-002

    What does SPO-LIST-002 decide, and on what authority?

  9. 09
    SPO-LIST-003

    What does SPO-LIST-003 decide, and on what authority?

  10. 10
    SPO-MODERN-001

    What does SPO-MODERN-001 decide, and on what authority?

  11. 11
    SPO-MODERN-003

    What does SPO-MODERN-003 decide, and on what authority?

  12. 12
    SPO-MODERN-004

    What does SPO-MODERN-004 decide, and on what authority?

  13. 13
    SPO-SHARE-001

    What does SPO-SHARE-001 decide, and on what authority?

  14. 14
    SPO-SHARE-002

    What does SPO-SHARE-002 decide, and on what authority?

  15. 15
    SPO-SHARE-003

    What does SPO-SHARE-003 decide, and on what authority?

  16. 16
    SPO-SHARE-004

    What does SPO-SHARE-004 decide, and on what authority?

  17. 17
    SPO-SHARE-005

    What does SPO-SHARE-005 decide, and on what authority?

  18. 18
    SPO-SITE-001

    What does SPO-SITE-001 decide, and on what authority?

  19. 19
    SPO-SITE-002

    What does SPO-SITE-002 decide, and on what authority?

  20. 20
    SPO-SITE-003

    What does SPO-SITE-003 decide, and on what authority?

  21. 21
    SPO-SPFX-001

    What does SPO-SPFX-001 decide, and on what authority?

The rule model

  1. 01
    Anatomy of a rule

    I am reading a rule file. What is every field for, and which ones may not be left out?

  2. 02
    basis

    Is this finding a defect, or a departure from advice? The rule has to say which.

Writing and checking

  1. 01
    Validation layers

    What does `validate` actually check, and why is it four layers rather than one schema?

  2. 02
    Lifecycle

    A source moved, or a number changed. What happens to the rule, and to the findings it already produced?

  3. 03
    Profiles

    How do I run a subset of the rules without editing them?

CLI

Every command the executable registers, from the executable.

Overview

  1. 01
    Overview

    What shape does this executable have, and what can I rely on across all of it?

Collecting evidence

  1. 01
    collect

    How do I reach a tenant and write down what was actually there?

  2. 02
    stats

    Before I read any conclusion, how much did the collector actually see?

  3. 03
    connect

    Can this app registration reach this tenant, and as whom?

Evaluating

  1. 01
    evaluate

    How do I run the rules against evidence and get a report I can read?

  2. 02
    assess

    How do I produce a result somebody else can check without trusting me?

  3. 03
    explain

    The report says unknown. What does that actually commit to?

Reporting and comparing

  1. 01
    report

    How do I re-render a stored result without evaluating anything again?

  2. 02
    diff

    Two assessments, months apart. What actually changed, and what does the difference not prove?

Working with rules

  1. 01
    list-rules

    What rules will run, and what kind of claim does each of them make?

  2. 02
    show-rule

    What does this one rule actually establish, and what does it leave open?

  3. 03
    validate

    Before anybody runs these rules, are they well formed?

Checking the installation

  1. 01
    doctor

    Something is not working. What is wrong with this installation?

Handing work over

  1. 01
    verify

    An assessment arrived from somebody else. How do I check it without their engine?

  2. 02
    contracts

    How does another system consume this engine's output without depending on this engine?

Reports

What a report says, outcome by outcome and bound by bound.

  1. 01
    Outcomes

    The report says unknown on two rules. Is that a pass, a failure, or something else?

  2. 02
    Coverage and bounds

    The report gives me a count. Is it the real count?

Architecture

How the parts fit, and what the trust model rests on.

  1. 01
    The shape

    What are the parts, which way does data flow, and what is each part forbidden to do?

  2. 02
    Trust model

    Why should anybody believe a conclusion this engine produced?

Contributing

How to propose a rule, a collector or a correction.

  1. 01
    Proposing a rule

    I want to add a check. What has to be true before it is merged?

  2. 02
    Licence and sign-off

    What am I agreeing to by contributing, and what will CI refuse?

Contracts

Every versioned document the Engine publishes, and what each is for.

  1. 01
    Overview

    Which versioned documents can I build against?

  2. 02
    assessment 2.0.0

    What does the assessment 2.0.0 contract carry?

  3. 03
    assessment 3.0.0

    What does the assessment 3.0.0 contract carry?

  4. 04
    assessment 4.0.0

    What does the assessment 4.0.0 contract carry?

  5. 05
    capability-manifest 1.0.0

    What does the capability-manifest 1.0.0 contract carry?

  6. 06
    collection 1.0.0

    What does the collection 1.0.0 contract carry?

  7. 07
    comparison 2.0.0

    What does the comparison 2.0.0 contract carry?

  8. 08
    comparison 3.0.0

    What does the comparison 3.0.0 contract carry?

  9. 09
    connection 1.0.0

    What does the connection 1.0.0 contract carry?

  10. 10
    evidence 1.2.0

    What does the evidence 1.2.0 contract carry?

  11. 11
    evidence 2.0.0

    What does the evidence 2.0.0 contract carry?

  12. 12
    evidence 3.0.0

    What does the evidence 3.0.0 contract carry?

  13. 13
    migration-read 1.0.0

    What does the migration-read 1.0.0 contract carry?

  14. 14
    migration-verification 1.0.0

    What does the migration-verification 1.0.0 contract carry?

  15. 15
    rule 1.0.0

    What does the rule 1.0.0 contract carry?

  16. 16
    run-set 2.0.0

    What does the run-set 2.0.0 contract carry?

  17. 17
    run-set 3.0.0

    What does the run-set 3.0.0 contract carry?

  18. 18
    run-set 4.0.0

    What does the run-set 4.0.0 contract carry?

  19. 19
    run 2.0.0

    What does the run 2.0.0 contract carry?

  20. 20
    run 3.0.0

    What does the run 3.0.0 contract carry?

  21. 21
    run 4.0.0

    What does the run 4.0.0 contract carry?

Reference

Exit codes, profiles and the things you look up rather than read.

  1. 01
    Exit codes

    My pipeline got a non-zero exit. Does that mean the tenant is wrong, or that the engine refused?

Documentation roadmap

Part of the product, and listed before it is written. A reader deciding whether to adopt an open source tool is entitled to know what the manual does not cover yet.

    Design principles

    The engine exists to make governance conclusions that can be inspected. Each of these is checkable against its output.

    • Evidence is collected read only.
    • Every finding names the rule that produced it.
    • Unknown is a result, not a failure.
    • A bound is never presented as an exact value.
    • Documented limits, documented guidance and conventions stay distinct.
    • Every conclusion is reproducible from the evidence that produced it.

    Send us a message

    Email

    Contact