Contributing

Thank you for considering it. This standard gets better when people who run real tenants tell us where it is wrong.

You do not need to be a maintainer, an SME, or a security researcher to contribute. “This rating does not match what I see in production” is one of the most useful things you can say to us.

Ways to contribute

I want to…	Do this
Say a permission is rated wrong	Rating change request
Argue a factor or weight is wrong	Factor proposal
Report an error in the spec text	Errata
Rate a permission nobody has rated	Add a file to data/permissions/ — see below
Discuss something open-ended	GitHub Discussions
Ask a quick question	Discord

The one thing we ask

Bring evidence. Every rating in this dataset carries a rationale, and every change to one has to survive review by people who will ask why.

A good rating argument names the factor it is about, cites what the permission actually grants — Microsoft documentation, Graph API behaviour, observed telemetry — and explains the consequence. “Files.ReadWrite.All should be higher because it permits tenant-wide write to all SharePoint content, which is Exfiltration Potential 40, not 25” is reviewable. “This feels too low” is not, though it is a perfectly good way to start a discussion in Discord.

We would rather have a well-argued disagreement than silent consensus.

Rating a permission

Each permission is one YAML file in data/permissions/, named <scope>.<type>.yaml in lowercase — mail.send.delegated.yaml, files.readwrite.all.application.yaml. Many scopes exist as both a delegated and an application permission and carry very different risk, so each gets its own file. RSC variants add a .rsc suffix.

One permission per pull request. It keeps review focused and means an objection to one rating does not hold up ten others.

permission: Mail.Send
type: delegated              # delegated | application
api: microsoft-graph

factors:
  # Identity & Privilege Escalation
  privilegeDepth: none
  privilegeElevation: none
  impersonationCapability: delegated-send-as
  appRoleBundles: none
  # Access Surface & Blast Radius
  permissionType: delegated
  permissionOperation: send
  permissionBreadth: single-user
  accessPolicyModification: none
  userBreadth: one
  # Data Sensitivity & Leakage
  dataClassification: confidential
  exfiltrationPotential: send-as-delivery
  tokenPersistence: short-lived
  # Compliance & Trust Heuristics
  legacyApiRisk: modern

rationale: >-
  Send-as capability lets the application originate mail as the signed-in user,
  which obscures audit trails and is a well-documented phishing pivot. Reach is
  limited to the consenting user, so blast radius stays low.

references:
  - https://learn.microsoft.com/en-us/graph/permissions-reference#mailsend

Run npm run validate before you push. CI runs the same checks — it will tell you if a factor value is not one the model allows, and it computes the score for you, so you never hand-calculate a composite.

The allowed values for every factor live in data/model/. If the value you need does not exist, that is a factor proposal, not a rating change.

Changing the model

Changes to factors, weights, or tier thresholds affect every rating in the dataset, so they get more scrutiny — 14 days open and sign-off from two maintainers plus a spec editor.

Open a factor proposal first and let it be discussed before writing the pull request. Include what signal is missing or mis-weighted, what you propose instead, worked examples of permissions whose scores would move, and why the new scores are more defensible.

Pull requests

1. Fork, branch from main
2. Make the change — one logical change per pull request
3. Run npm run validate
4. Commit with DCO sign-off: git commit -s
5. Open the pull request and describe your reasoning

Review periods and approval thresholds are in GOVERNANCE.md. Do not be alarmed if a rating change sits for a week — that is the process working.

Developer Certificate of Origin

We use the DCO rather than a CLA. Sign off your commits with git commit -s, which appends:

Signed-off-by: Your Name <[email protected]>

This certifies you wrote the contribution or have the right to submit it. There is no copyright assignment: contributions are licensed CC BY 4.0 for specification and data, MIT for code, and you keep your copyright.

Local setup

npm install
npm run validate    # schema + model validation over all data files
npm run build       # produce release JSON in dist/
npm run site        # preview the site at localhost:4321

Requires Node 20 or later.

Conduct

All participation is governed by the Code of Conduct. Disagree with ideas as sharply as you like; treat people well.