Get started

Setup guide

Everything you need before the first run — the container runtime, the app registration, permissions, roles and network access — and how to upgrade or remove the app later.

How it fits together

Detection Rule Health is a single container. You open it in your browser at http://localhost:5180. When you sign in, your browser goes to Microsoft Entra ID and comes back to the container with an authorization code; the container exchanges it for tokens and keeps them in memory. From then on the container calls Microsoft Graph, Azure Resource Manager and Log Analytics on your behalf and writes the results to a volume on your computer.

your browser ──▶ http://localhost:5180 ──▶ container (rulehealth)
     │                                         │
     └─▶ sign-in: login.microsoftonline.com     ├─▶ Microsoft Graph
                                                ├─▶ Azure Resource Manager
                                                ├─▶ Log Analytics
                                                └─▶ volume drh-data (/data)

There is no Cerberus service in between and no Cerberus app registration. You sign in either with an app registration you create yourself (recommended) or with Microsoft’s own public apps (quick start): see choose how to sign in.

Requirements

Container runtime

Any OCI-compatible runtime works. Pick what your organisation allows:

Check your organisation’s policy before installing a container runtime on a managed device.

Start the container

docker run -d --name detectionrulehealth \
  -p 127.0.0.1:5180:5180 -v drh-data:/data \
  --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
  --restart unless-stopped \
  ghcr.io/cerberus-cyber-consulting/detectionrulehealth:beta

What each part does:

Or with Docker Compose, using the compose.yaml from the repository, which sets the same options:

docker compose up -d

Podman (rootless) works with the same command; for Compose use podman compose up -d.

Choose how to sign in

You choose per tenant in the setup wizard. Both use the same browser sign-in (authorization code with PKCE), both are read-only, and in both tokens stay in memory only: neither uses the Azure CLI, PowerShell modules or a token cache on disk.

Quick start, consent. The security permissions (CustomDetection.Read.All, ThreatHunting.Read.All, SecurityIncident.Read.All, SecurityAlert.Read.All) need admin consent for Microsoft Graph Command Line Tools, by a Global, Privileged Role, Cloud Application or Application Administrator. In the wizard that administrator uses Sign in and consent; Microsoft shows the consent prompt. Consent on behalf of your organization creates a tenant-wide grant on Graph Command Line Tools: from then on everyone’s Connect-MgGraph in your tenant can get these read permissions (still limited by each user’s own roles). Only tick it if that is acceptable; otherwise create your own app registration. Do not use the Grant admin consent button on the Graph Command Line Tools enterprise application for this: it can replace permissions others already rely on. Azure PowerShell needs no extra consent.

Quick start, what Microsoft says. Microsoft builds its own apps for its own tools; when another tool uses their app IDs, Microsoft’s guidance is to “move to another app ID they register”. The quick start therefore only works within what Microsoft allows these apps, may stop working when Microsoft changes them, and is subject to your Conditional Access policies (a policy on Windows Azure Service Management API also covers the Azure PowerShell sign-in and Log Analytics). Your sign-in logs show sign-ins to both Microsoft apps from a browser; tell your SOC if they watch for that. Your own app registration is the supported way.

Create the app registration

For the recommended sign-in option. The app signs in with an app registration you create in your own tenant. It is a public client: no secret, no certificate. It only asks for delegated, read-only permissions, so it can never do more than the signed-in user may do.

Option A: script (Azure CLI)

Requires PowerShell 7 and the Azure CLI. The script uses the Azure CLI only to call Microsoft Graph with your sign-in, and looks up every permission by name.

az login --tenant <your-tenant>.onmicrosoft.com
pwsh ./New-DrhAppRegistration.ps1 -RestrictToAssignedUsers

Download: tools/New-DrhAppRegistration.ps1. Read it before you run it.

Option B: Microsoft Entra admin center

1. Go to Entra ID → App registrations → New registration. Name: Detection Rule Health. Supported account types: Accounts in this organizational directory only. Leave Redirect URI empty and select Register.

2. Copy the Application (client) ID and Directory (tenant) ID from the Overview page. You enter both in the setup wizard.

3. Authentication → Add a platform → Mobile and desktop applications. Under Custom redirect URIs enter http://localhost:5180/auth/callback and select Configure. Leave Allow public client flows on No.

4. API permissions → Add a permission, choose Delegated permissions each time, and add:

   • Microsoft Graph: CustomDetection.Read.All, ThreatHunting.Read.All, SecurityIncident.Read.All, SecurityAlert.Read.All
   • Azure Service Management (under Microsoft APIs): user_impersonation
   • Log Analytics API (under APIs my organization uses, search “Log Analytics API”): Data.Read

   You can remove the default User.Read permission; it is not used.

5. Select Grant admin consent for <your tenant> (or ask an administrator) and confirm that every permission shows Granted.

6. Recommended: Enterprise applications → Detection Rule Health → Properties → Assignment required = Yes, then add the users or groups that may use the app under Users and groups.

Permissions

At sign-in the app also requests openid, profile and offline_access (your name, and a refresh token that stays in memory). Every request is read-only.

Roles for users

Delegated permissions never exceed what the signed-in user may do. The user also needs:

A user with only one of the two works too: the app collects what it can and tells you which part it could not read and why.

Network access

The container needs outbound HTTPS (443) to these hosts. Nothing else.

Behind a proxy, pass it to the container: -e HTTPS_PROXY=http://proxy.example:8080. If your organisation inspects TLS, see troubleshooting.

Configuration

Set with -e NAME=value on docker run or under environment: in compose.yaml.

The port (5180), data folder (/data) and listen address are fixed in the image.

Upgrade

The app shows a notice when a newer release exists. It never updates itself.

docker pull ghcr.io/cerberus-cyber-consulting/detectionrulehealth:beta
docker rm -f detectionrulehealth
# run the same docker run command as before; your data stays in the drh-data volume

With Compose: docker compose pull && docker compose up -d. Release notes: GitHub Releases.

Verify the image

Release images are built by GitHub Actions in the public repository, signed with Sigstore (keyless) and published with SBOM and build provenance. To check that an image really came from this repository’s release workflow, with the GitHub CLI:

gh attestation verify oci://ghcr.io/cerberus-cyber-consulting/detectionrulehealth:beta \
  -R Cerberus-Cyber-Consulting/DetectionRuleHealth

Remove

docker rm -f detectionrulehealth      # the app
docker volume rm drh-data             # all collected data

Then remove the app’s access to your tenant:

• Own app registration: delete it in Microsoft Entra ID (App registrations → Detection Rule Health → Delete).
• Microsoft’s apps (quick start): remove the permissions you consented to from the Microsoft Graph Command Line Tools enterprise application (Enterprise applications → Microsoft Graph Command Line Tools → Permissions). Other Graph PowerShell users in your tenant may rely on them, so check first.