Skip to content

Adding a check

1. Ensure the capability exists

If the check depends on a licensed feature, add or reuse an entry in catalog/capabilities.yaml.

2. Create YAML

Path: checks/<workload>/<id>.yaml

id: id-example
title: Short technical title
# Required: plain language for SMB owners / novice admins
customer_title: Everyday wording without product jargon
customer_summary: >
  What this means for the business, in one or two sentences.
customer_next_step: >
  A concrete action they can ask IT to take.
description: >
  What paid capability should be realized, and what gap looks like.
workload: identity   # identity | defender | sentinel | purview | endpoint | exchange | collaboration | teams | power_platform | power_bi | intune | azure | general
required_capabilities:
  - entra_id_p2
severity: high       # critical | high | medium | low | info
value_impact: high   # high | medium | low
# Required when enabled: true (loader rejects the check if any are missing)
impact: high         # high | medium | low
effort: hours        # minutes | hours | half_day | days
blast_radius: all_users  # admin | all_users | devices | data
pack: identity       # identity | email | endpoint | collaboration | power-platform | power-bi | starter
exposure_class: none # none | elevated | exposed
collector: graph_example
remediation: >
  Concrete next steps for an admin or consultant.
references:
  - https://learn.microsoft.com/...
enabled: true
tier: activation   # activation | hygiene — required when enabled

Customer-facing fields appear first in the HTML/Markdown report. Technical titles and product names stay available in the collapsible technical section.

The hygiene pack is frozen. New hygiene checks are accepted only when they map an existing SCuBA baseline row that has no local check, or when they fix a false result. Activation checks need the justification in step 5.

3. Collector (optional in early PRs)

If logic is more than metadata, implement a collector and wire it in the engine. Until then, licensed checks may return skipped.

4. Test

  • licenselens checks shows your check
  • pytest passes
  • Prefer fixtures over live tenants in CI

5. PR

Describe:

  • Which SKU/plan unlocks the capability
  • What “gap” means operationally
  • Why MSPs/consultants care (security and/or value)