What the installer does, phase by phase
Read it before you run it: it is a plain PowerShell script that calls az, and it stops for your confirmation after showing the plan. Every step is idempotent; re-run it any time to repair or extend an installation.
- Preflight
Azure CLI version, sign-in, tenant and subscription, global availability of the web app and Cosmos names, presence of the Defender API service principal, and a count of your onboarded devices to pick the tier.
Seconds, changes nothing - Plan
Lists exactly what will be created or reused, the roles with their reasons, the release version and its published SHA-256, and what will never exist. Then asks.
Your decision - Apply
Deploys the template, assigns Defender roles to the web app's managed identity through Microsoft Graph, creates the sign-in registration with a federated credential, switches App Service authentication on, downloads and verifies the release, deploys it.
6 to 9 minutes - Verify
Waits until the app reports the installed version, then writes an installation receipt (JSON: identity, roles, registration, release digest, scanner digest) next to the script for your records and support requests.
1 to 2 minutes
Verify it is alive
When the installer finishes, the console is at https://shorfall-contoso.azurewebsites.net/app. This page can read the instance's public health endpoint from your browser (nothing else is exposed without sign-in) and confirm the version, the identity mode and the scanner it ships.
Then sign in with a work account from your tenant. The first person to sign in becomes the administrator and sees a getting-started checklist that tracks the remaining steps live: registration, identity roles, scanner in the Live Response library, first inspections, colleagues.
Permissions, and who holds them
All roles are assigned to your web app's managed identity, in your tenant. No Shorfall service principal exists in your directory. Revoke any role under Microsoft Entra > Enterprise applications and access stops immediately.
| Permission | Stage | What it reads | Why |
|---|---|---|---|
| Machine.Read.All | read-only | Device inventory: names, OS, groups, tags, exposure level, device value | Fleet view, targeting, prioritization drivers |
| AdvancedQuery.Read.All | read-only | Advanced Hunting: software inventory, configuration checks, device-to-device connections, TLS sessions | Passive inventory, the dependency map, consumer verification |
| Vulnerability.Read.All | read-only | Defender Vulnerability Management data (certificate inventory when licensed) | Passive certificate posture where the tenant has the add-on |
| Machine.LiveResponse | inspections, optional | Runs the published read-only CryptoDiscovery.ps1 on devices you select | Device-level evidence Defender telemetry does not carry |
| Machine.ReadWrite.All | inspections, optional | Required by Microsoft to download Live Response results for an application identity | Result retrieval; nothing is written to devices |
| Library.Manage | inspections, optional | Lists and uploads files in your Live Response library | Keeps the published scanner current so inspections run the shipped version. Leave it out with -ManualScannerUpload and upload the scanner yourself |
Sign-in: the "Shorfall Console" registration requests only openid profile email. The scanner is read-only by construction: it enumerates and reports, it cannot modify registries, certificates, processes or TLS configuration. Its source and SHA-256 are published on the release feed. With Library.Manage, Shorfall uploads exactly those bytes to your Live Response library and logs each upload in the change feed; without it, you upload the file yourself. Either way every inspection records the hash of what actually ran.
What leaves an endpoint, and what never does
Leaves the endpoint, stays in your Cosmos DB
- Device names and Defender context
- Certificate metadata: subject, issuer, algorithm, key size, thumbprint, expiry, store, private-key flag
- Listener ports and process names
- TLS protocol, cipher-suite and key-exchange group configuration
- Crypto library and runtime versions
- Config file paths that pin certificates (never the values)
Never leaves
- Private keys or key material
- File contents
- Tokens, passwords, user data
- Anything from your installation to Shorfall the company: no telemetry, no licence check, no update ping
Outbound connections from the web app: login.microsoftonline.com, api.securitycenter.microsoft.com, your Cosmos DB endpoint, and only if you configure them, your ticket system and Azure Communication Services for the weekly digest.
What Shorfall the company sees
What you enter when you register (organisation, work email, tenant ID, optionally the size of the estate), the ordinary access log of this website and of the release feed (which files were downloaded, when, from which address; kept 30 days), and whatever you choose to send us, such as the support bundle. Nothing from inside your installation.
Updates, status, removal
You update when you decide. Each release is a package with a published SHA-256; the updater verifies the digest before deploying and waits for the app to report the new version. Status shows the roles the identity holds, the registration, sign-in callbacks, authentication and health, read-only. Removal lists what it deletes and asks you to type the app name. Run these from the folder that holds the scripts, signed in with az login. Bind a custom domain later? Re-run the installer once: it registers a sign-in callback for every hostname on the web app.
Release feed and notes: releases.json. The console shows its version under Settings; nothing checks for updates on your behalf.
Licensing
Community edition, free
For an organisation running Shorfall in its own tenant for its own estate. No feature caps, no device caps: passive posture, unlimited inspections, programs, verification, tickets, digests, reports and exports. Internal use only, no warranty, community support through the documentation and the support bundle. Registration (organisation, work email, tenant ID) issues the tenant-bound licence by email; the console asks for it on first sign-in.
Service Provider licence, paid
Required to operate Shorfall for other organisations: MSPs, MSSPs, auditors and consultancies. Priced per tenant under management, agreed directly. An optional support subscription is available to any organisation whose procurement requires a support contract.
Licences are tenant-bound files verified offline by the software (no call home). Community licences are issued on registration; request a Service Provider quote through the contact form.