🔐 Access Matrix Guide

⚠️ Warning: This documentation is a work in progress. Some sections may be incomplete, inaccurate, or subject to change.

This guide explains how to fill in the access matrices (authorization matrices) that Assets Guardian generates as empty Excel sheets. These matrices are the reference against which the audit command validates the accesses actually collected on your platforms: any access held by an employee that is not covered by the matrix raises a finding in the audit report.

🧭 How matrices work

🔄 Lifecycle

Generation: the first sync run creates one matrix sheet per audited plugin instance in the Excel workbook (paths.excel in config.yml, by default outputs/assets_guardian.xlsx). The sheet is created empty: a header row with example scope columns, and one row per profile found in employees.json.
Manual completion: you replace the example columns with your real scopes and fill in the authorized role for each (profile, scope) pair. This is the manual step described in this guide.
Preservation: on every subsequent sync, matrix sheets are preserved as-is (they are copied verbatim into the regenerated workbook, never overwritten).
Consumption: the audit command reads the matrices back from the same Excel file and evaluates the MATRIX-XXX rules against the collected accesses.

💡 Tip: paths.excel can be local: or remote: (SharePoint, via the Microsoft 365 plugin). In the remote case, the workbook is cached locally and re-downloaded whenever the SharePoint version changes, exactly like rules_config.yml and employees.json.

🏷️ Sheet naming

Each matrix sheet is named after its source plugin and instance:

Situation	Sheet name
Plugin instance with an `instance_id`	`<Source> (<instance_id>) Matrix` (e.g. `Gitlab (production) Matrix`)
Plugin instance without `instance_id`	`<Source> Matrix` (e.g. `Dolibarr Matrix`)

The audit command locates the sheet by this exact pattern (case-insensitive, instance-specific name first, then the generic name as fallback).

⚠️ Warning: Do not rename matrix sheets. A renamed sheet is silently ignored and the audit runs with an empty matrix.

📐 Sheet layout

The matrix is a pivot table: profiles as rows, scopes as columns, authorized roles in the cells.

Cell	Content	Rule
`A1`	Sheet title (e.g. `Gitlab Matrix`)	Ignored by the audit, but must stay non-empty.
`B1`, `C1`, …	Scope names (one column per audited resource)	Must exactly match the expected scope keys listed per plugin below.
`A2`, `A3`, …	Profile names (one row per profile)	Must exactly match the values of the `profiles` field in `employees.json` (comma-separated values are split and trimmed).
Other cells	The role/permission the profile is authorized to hold on that scope	An empty cell means “not authorized”. Accepted values depend on the plugin (see below).

Generated sheets are pre-filled with the example scope columns Group: Example1, Group: Example2, Instance and Project: Example: replace them with your real scopes.

⚠️ Warning: These example columns are identical for every plugin, they are not tailored to the source. A Dolibarr or Microsoft 365 sheet is therefore created with Instance and Project: Example columns that its rules never audit. Always replace the whole header row with the scope columns documented for that plugin below.

🎯 Matching rules

All lookups are exact string matches (case-sensitive): profile names, scope headers and role values must be spelled exactly as documented.
Employees are identified by email: matrix rules resolve a user’s profiles from employees.json through the email attached to the collected access. A user missing from employees.json has no profile, so none of their audited accesses can be authorized.
email and username in employees.json accept a single value or a list. Every value listed becomes a lookup key for the same profiles, which is how one employee holding several accounts (e.g. john.doe@company.com and jdoe@company.com) is matched. username is only used as a fallback, when the entry has no email at all.
When an employee has several profiles, an access is authorized as soon as one of the profiles allows it (for hierarchical GitLab roles, the most permissive profile wins).
Rows with an empty first cell are skipped, so blank separator rows are harmless. Extra profile rows that match no employee are ignored.

⚠️ Warning: Do not leave an empty header cell between two scope columns: it shifts the column/value alignment when the matrix is read back.

⚙️ Enabling the matrix rules

Matrix rules only run if they are declared in rules_config.yml under the source’s section:

gitlab:
  <<: *default_rules
  MATRIX-001:
    description: "Unauthorized GitLab instance administrator"
  MATRIX-002:
    description: "Unauthorized GitLab group/project access"

dolibarr:
  <<: *default_rules
  MATRIX-001:
    description: "Unauthorized Dolibarr superadmin"
  MATRIX-002:
    description: "Unauthorized critical module access"

microsoft365:
  <<: *default_rules
  MATRIX-001:
    description: "Unauthorized Microsoft365 group access"

⚠️ Warning: name, description, and severity may all be overridden from the YAML. If severity is missing or empty, the rule logs a warning and falls back to its default value (see the per-plugin tables below).

🧩 Interpretation is plugin-specific

Matrix semantics are not implemented by the audit engine but by the MATRIX-XXX rules that each plugin registers for its own source. The engine only extracts a neutral (profile, scope) → cell value mapping from the sheet and hands it to those rules; everything else, which scope columns are recognized, how cell values are interpreted (hierarchical roles on GitLab, presence-based checks on Dolibarr, accepted admin values), lives in the plugin’s own rule implementations. In practice:

A shared rule ID does not mean a shared behavior: GitLab’s MATRIX-001 and Dolibarr’s MATRIX-001 are independent implementations. This is why the sheet layout and accepted values are documented per plugin below, and why they can differ freely from one plugin to another.
A plugin that ships no MATRIX rules cannot audit a matrix: declaring MATRIX-XXX in rules_config.yml for such a source logs an error and the rule is skipped, the sheet, even carefully filled in, is never read.
Supporting matrices in a new plugin therefore means implementing its own MATRIX rules; the conventions described in this guide do not transfer automatically to other sources.

🦊 GitLab matrix

Sheet: Gitlab Matrix or Gitlab (<instance_id>) Matrix.

🗂️ Scope columns

Column header	Audited by	What it covers
`Instance`	`MATRIX-001` (default severity: DANGER)	Instance-wide administrator flag.
`Group: <group name>`	`MATRIX-002` (default severity: DANGER)	Membership role on the GitLab group `<group name>`.
`Project: <project name>`	`MATRIX-002` (default severity: DANGER)	Membership role on the GitLab project `<project name>`.

<group name> / <project name> is the display name of the group or project as shown in GitLab (the API name field, not the URL path). The prefix is capitalized and followed by a colon and a single space: Group: Backend, Project: Website.

🔤 Accepted cell values

Instance column: authorizes the instance administrator flag:

Value	Meaning
`Administrator`	The profile may be a GitLab instance administrator.
`Administrator*`	Same effect; the trailing `*` is an annotation convention (e.g. admin granted with conditions) and is treated identically by the engine.
(empty or any other value)	Not authorized: every instance administrator with this profile is flagged.

Group: … / Project: … columns: the maximum role the profile may hold, using GitLab’s role hierarchy:

Value	GitLab access level
`Guest`	10
`Reporter`	20
`Developer`	30
`Maintainer`	40
`Owner`	50

The comparison is hierarchical: a cell containing Developer authorizes Guest, Reporter and Developer, but a user holding Maintainer or Owner on that scope is flagged. Spelling must be exact, any other value is treated as below Guest and flags every membership.

⚖️ Evaluation semantics

Only groups/projects that appear as a column in the matrix are audited: a group or project absent from the matrix is not checked at all.
The Instance check applies to all collected instance administrators, whether or not the Instance column exists (no column means nobody is authorized).
For a user with several profiles, the highest authorized level across their profiles is used.

📝 Example

Gitlab Matrix	Instance	Group: Backend	Group: Infra	Project: Website
R&D		Developer		Maintainer
R&D / DevOps		Maintainer	Owner
Exploitation / Information technology (IT)	Administrator		Maintainer
Support				Reporter

With this matrix, a Support employee owning the Website project raises a MATRIX-002 finding (Reporter max), and any instance administrator outside the IT profile raises a MATRIX-001 finding.

💼 Dolibarr matrix

Sheet: Dolibarr Matrix or Dolibarr (<instance_id>) Matrix.

🗂️ Scope columns

Column header	Audited by	What it covers
`Dolibarr`	`MATRIX-001` (default severity: CRITICAL)	The Dolibarr superadmin flag (`admin = 1` on the user).
`banque`	`MATRIX-002` (default severity: DANGER)	Rights on the Bank module.
`facture`	`MATRIX-002` (default severity: DANGER)	Rights on the Invoicing module.
`societe`	`MATRIX-002` (default severity: DANGER)	Rights on the Third parties module.
`user`	`MATRIX-002` (default severity: DANGER)	Rights on the Users module.

Module column headers use the technical Dolibarr module names in lowercase (banque, facture, societe, user). These four modules are the ones declared critical in the plugin (CRITICAL_MODULES); other Dolibarr modules are not audited by matrix rules.

🔤 Accepted cell values

Dolibarr column: authorizes the superadmin flag:

Value	Meaning
`Administrateur` / `Administrator`	The profile may be a Dolibarr superadmin.
`Administrateur*`	Same effect, `*` being the same annotation convention as for GitLab.
(empty or any other value)	Not authorized: every superadmin with this profile is flagged.

Critical module columns — presence-based check: any non-empty value authorizes the profile to hold rights on that module; the value itself is not interpreted. By convention, write the highest permission granted (e.g. lire, creer, modifier, supprimer) so the matrix stays readable for reviewers.

⚖️ Evaluation semantics

Critical modules are always audited: any user holding a right on banque, facture, societe or user (including sub-permissions such as banque.modifier or user.self.password) whose profiles have no entry for that module is flagged.
One authorized profile is enough for the access to be considered legitimate.

📝 Example

Dolibarr Matrix	Dolibarr	banque	facture	societe	user
Direction	Administrateur	modifier	modifier	creer	lire
Administratif / Finance		modifier	modifier	lire
Commerce & Marketing / Commerce			creer	creer
Exploitation / Information technology (IT)	Administrateur*				supprimer

☁️ Microsoft 365 matrix

Sheet: Microsoft365 Matrix or Microsoft365 (<instance_id>) Matrix.

🗂️ Scope columns

Column header	Audited by	What it covers
`Group: <group name>`	`MATRIX-001` (default severity: DANGER)	Membership in the Microsoft 365 / Azure AD group `<group name>`.

<group name> is the display name of the group as shown in Microsoft 365 / Azure AD. The prefix is capitalized and followed by a colon and a single space: Group: Finance.

💡 Tip: Unlike GitLab and Dolibarr, the Microsoft 365 plugin currently ships a single matrix rule (MATRIX-001): there is no MATRIX-002.

🔤 Accepted cell values

Group: … columns — presence-based check: any non-empty value authorizes the profile to be a member of that group; the value itself is not interpreted. By convention, write a short note (e.g. oui, membre) so the matrix stays readable for reviewers.

⚖️ Evaluation semantics

Only groups that appear as a column in the matrix are audited: a group absent from the matrix is not checked at all (same behavior as GitLab groups/projects).
One authorized profile is enough for the access to be considered legitimate.

📝 Example

Microsoft365 Matrix	Group: Finance	Group: IT-Admins
Direction	oui
Administratif / Finance	oui
Exploitation / Information technology (IT)		oui

With this matrix, any member of the IT-Admins group whose profiles are not IT raises a MATRIX-001 finding.

✅ Filling checklist

Run sync once so the empty matrix sheets are generated with your profiles pre-filled from employees.json.
Replace the example scope columns with your real scopes (exact names, see per-plugin tables above).
Fill in one cell per authorized (profile, scope) pair; leave every unauthorized combination empty.
Make sure the source’s matrix rules are declared in rules_config.yml (MATRIX-001 and MATRIX-002 for GitLab and Dolibarr, MATRIX-001 only for Microsoft 365).
Run audit and review the MATRIX-XXX findings: each one is either an access to revoke or a missing authorization to add to the matrix.

💡 Tip: An entirely empty matrix is a valid starting point: the first audit will then flag every superadmin/instance administrator and every right on Dolibarr critical modules, which gives you the complete list of accesses to arbitrate. (GitLab groups/projects and Microsoft 365 groups are the exception: they are only audited once their column exists in the matrix.)

⚠️ Warning: The matrix is read from the workbook referenced by paths.excel in config.yml. If you archive or move the Excel file, the next audit runs against an empty matrix and the findings become meaningless.

⚠️ Warning: The same silent failure happens if paths.excel contains the DATE placeholder and audit runs on a different day than the sync that produced the workbook: audit looks for today’s filename, does not find it, and evaluates every matrix rule against an empty matrix. Run both commands on the same day, or drop DATE from paths.excel.