Skip to main content

Console onboarding (/setup)

The Setup page in the management console takes a new tenant from an empty management database to a test event that Bower has found in Microsoft Sentinel, without the CLI. It is part of the existing console: same sign-in, same roles, same audit trail. Progress is computed from server state, so the wizard can be left and resumed by anyone, and every step can be run again.

The Help checklist shows the same server progress and links to each step, including in the simplified view.

Steps​

#StepDone whenWhat Bower checks
1Sign inYou are signed inYour name and the Bower app roles in your token. Only Bower.Administrator can change setup.
2Connect Entra appsThe API trusts your tenant and a collector has registeredProduction sign-in (not development mode), the tenant and audience the API validates, and that at least one collector has signed in with the Bower.Collector app role. Bower cannot read your app registrations; compare them with deploy/entra/*.json.
3Choose where events goA Log Analytics workspace ID is savedFormat of the workspace ID, workspace resource ID, data collection rule (DCR) resource ID and table. Check the rule and table reads the deployed DCR and table read-only and runs the same drift checks as bower doctor / bower dcr diff. Download DCR template returns the same ARM template as bower dcr generate.
4Approve the first collectorAt least one collector is approved or activePending and approved collectors. Approval stays on the Approvals page with a reason and approver role; the wizard never approves anything.
5Choose what the test provesA probe profile is savedgeneric (the canary through POST /v1/events) or a signed pack parser with a repo-owned fixture (parser:linux-ssh-gateway:0).
6Send a test eventThe collector accepted the latest test eventThe latest run's collector response.
7See proof it arrivedThe latest run is verifiedOnly a Log Analytics query that returned the exact test event.

Each step shows a plain-English "why this matters" line, its checks, and a suggested fix for every check that is not passing. A viewer, operator or approver sees the same progress read-only.

Canary proof semantics​

The test event reuses Bower.Evidence.EvidenceRunner unchanged, exactly as bower evidence run does (see evidence bundles):

  • The generic profile sends the collector_canary envelope; parser profiles send the trusted synthetic fixture through the signed parser intake and record the probe object.
  • Collector acceptance is never shown as delivery. Step 6 can be done while step 7 is not.
  • Step 7 is done only when the bundle mode is verified: the destination query returned the exact event id (and, for parser probes, the expected event type and the policy hash the collector reported).
  • Without a verifier identity the run is simulated. The console labels it Simulated and says it is not proof of delivery.
  • The signed bundle (metadata only) can be downloaded from step 7 and checked with bower evidence verify.

Outcome codes are the evidence outcomes (verified, accepted-not-verified, collector-permission-denied, destination-row-missing, …) plus codes for failures outside the bundle: collector-unreachable, verifier-credential-unavailable, accepted-not-checked (the collector accepted the event, then the verifier could not sign in, so Sentinel was never queried; the event id is kept), canary-token-unreadable, signing-key-unreadable and interrupted (the service restarted mid-run). The API maps each code to a fixed message and fix. Raw Azure or framework error text stays on the server.

Server configuration​

The canary runs on the management API host. Configure it there (environment variables use __ for :); nothing secret is sent to or stored in the browser.

SettingRequiredMeaning
Bower:Setup:Canary:CollectorUrlyesCollector base URL, http or https.
Bower:Setup:Canary:IngestTokenFileyesFile holding an ingest token for the canary producer (at most 4 KiB). Read for each run; never returned, logged or stored.
Bower:Setup:Canary:Credentialfor proofRead-only verifier identity: managed-identity, workload-identity, environment or azure-cli. Without it every run is simulated and the DCR check is unavailable.
Bower:Setup:Canary:ClientIdnoUser-assigned managed identity client ID.
Bower:Setup:Canary:SigningKeyFilenoECDSA P-256 private key PEM that signs bundles. Unsigned bundles say so.
Bower:Setup:Canary:TimeoutMinutesnoHow long to wait for the event in Sentinel: 1–60, default 15.

Give the canary token its own producer ID in BOWER_INGEST_TOKENS_FILE, scoped (BOWER_PRODUCER_SCOPES_FILE) to the application BowerEvidence / production for the generic profile, and to the probe pack's identity for parser profiles. The verifier identity needs only Log Analytics Reader on the workspace (and Reader on the DCR and table for the rule check). Keep it separate from the ingest identity.

Local and end-to-end testing​

With development authentication (never in production) every request has all roles. The X-Bower-Development-Roles header narrows a request to the listed roles (for example Bower.Viewer); it can only remove roles. The Playwright journey uses it for the read-only viewer check. With BOWER_E2E_CANARY=1, Playwright starts a loopback stub collector (e2e/stub-collector.mjs, port 4399, token e2e-canary-token) and expects the API to be started with Bower:Setup:Canary:CollectorUrl=http://127.0.0.1:4399/ and a token file holding that token. No verifier is configured, so the journey ends at a run labelled Simulated, not proof.

API​

All endpoints are under /api/setup and enforced by the API (UI role checks only guide the interface). Every state change writes a management_audit row.

Method and pathPolicyAudit action
GET /api/setupView—
POST /api/setup/destinationAdministersetup.destination-set
POST /api/setup/destination/checkAdministersetup.destination-checked
GET /api/setup/dcr-templateView—
POST /api/setup/probe-profileAdministersetup.probe-profile-set
POST /api/setup/canaryAdministersetup.canary-requested (the administrator), then setup.canary-verified, setup.canary-failed, setup.canary-simulated or setup.canary-interrupted with actor bower.setup and the requester in initiatedByObjectId / initiatedByName
GET /api/setup/canary/runs/{id}/bundleView—

The console polls every 5 seconds while a run is in progress. A failed poll keeps the last progress on screen with a polite warning and retries with backoff (10, 20, 40, at most 60 seconds). Finished runs and step changes are announced in a polite live region. The latest run is the last one started (insertion order), whatever its timestamp.

POST /api/setup/canary answers 202 with the run, or 409 with a fixed message when a run is already in progress, a prerequisite step is missing, or the server is not configured. One run at a time. Runs left in progress by a restart are marked interrupted at start-up.

Design note​

Scope. Issue #97: the seven steps above, server-side progress, re-runnable steps, validation with fixes, canary proof through the existing evidence runner. Reusable console primitives for later guided views (#98 to #107) are described in DESIGN.md.

Non-goals. No Azure resource creation (the DCR template is a download you deploy yourself). No secrets in the browser. No approvals or four-eyes bypass: the collector step links to Approvals. No automatic or scheduled canaries: a run starts only when an administrator presses Send test event. No raw event values: the API returns run metadata only.

Invariants touched. "Never claim Sentinel delivery without destination query validation" (step 7 depends only on mode == verified); "simulated evidence must say simulated"; "never log secrets" (the token is read from a file per run; only exception type names are logged); "use least privilege" (read-only verifier, dedicated canary producer). Delivery, acknowledgement and queue state are untouched: the canary is a normal producer event through the collector.

New trust boundary. The management API now optionally holds a canary ingest token and a read-only Azure identity. Both are opt-in server configuration, used only by Administrator-triggered, audited runs, and never exposed through the API. See threat model.

Failure modes. Collector unreachable, refused token or scope, parser inactive, policy rejection, verifier credential missing, query permission denied, row not found before the timeout, wrong event, configuration mismatch, restart mid-run. Each maps to a fixed message and fix; the step shows "Needs attention".

Bounds. One run at a time; poll timeout 1–60 minutes; 30-second HTTP timeout per request; token file at most 4 KiB; workspace, DCR and table identifiers validated against strict patterns before any Azure call; at most 5 collector names listed.

Tests. API (SetupApiTests): RBAC for every endpoint, validation messages, audit rows, prerequisites, one run at a time, verified only with a destination row, simulated without a verifier, collector and transport failures mapped without raw detail, parser probe outcomes, DCR checks, interrupted runs. Console (vitest): guided primitives (stepper semantics, focus, non-colour status) and the setup page (read-only viewers, saving, simulated versus verified). Playwright journey in e2e/management.spec.ts.

After setup: keep an eye on your machines​

Open Collectors for each machine's plain-language state, suggested fix, site filter and reported source and destination details. See Check your collectors. A healthy check-in is separate from the destination proof in step 7.

After the collector is connected, use Sources to generate settings and request another person's approval. Add a security source explains installation, signed downloads and the heartbeat check.

Use Privacy profiles → Edit with forms to change how fields are protected, review the generated configuration and request approval. See Change privacy actions with forms.

Viewers start with Home, Alerts and Reports. A simpler view of Bower explains the per-user technical-page toggle and read-only access.