Idea: optional advanced visibility layer in the customer portal, controlled by a per-organization flag

[fabicarvano]

Advanced visibility layer in the customer portal, controlled by a per-organization flag

Summary

Allow the administrator (MSSP) to enable, per organization, a more technical and granular level of visibility in the customer portal, always read-only. Off by default, with no impact on existing organizations and no new data collection.

Context and problem

An MSSP serves customers with very different levels of IT maturity:

• Low maturity: the customer has no technical staff and relies on the MSSP for everything. The current portal, operational and simple, serves this profile well.
• Higher maturity: the customer has an IT team, often a minimal one, that still relies on the MSSP for the contracted service. This profile needs more depth than the portal offers today.

For the second profile, the lack of depth creates two problems:

1. Fast decisions: the customer's IT manager needs more robust data to decide quickly, without opening a ticket or waiting for a report from the MSSP.
2. Minimal team without input: the customer's team needs some data to carry out strategic, or even operational, tasks that fall outside the scope of the contracted service. Without that data, they turn to the MSSP for one-off information, which creates unplanned work for the administrator and dependency for the customer.

Much of this information already exists in Breeze's technical console but does not reach the portal. Today the administrator has no way to offer it selectively. Exposing everything to everyone is not the goal of this solution: the goal is to deliver specific, granular information to each type of stakeholder.

This proposal lets the administrator adjust the depth of the portal to each customer's profile. It also becomes a service differentiator, without changing the contractual scope.

Proposal

1. Advanced portal flag: create a flag that, when enabled, unlocks new advanced-visibility routes for the organization, under a dedicated namespace such as /portal_advanced/... (name to be defined).
2. Behavior when disabled: the organization is denied access to these routes (403), and the advanced area is disabled in the portal frontend.
3. Behavior when enabled: the API delivers an advanced-visibility unlock key to the frontend, the same way it is already done for Documents, Lifecycle, etc.

Principles

• Read-only and additive: visibility only, never control or actions on assets from the portal. What the customer does with the information happens outside the portal, in their own tools, and the administrator's scope of responsibility remains intact.
• Opt-in by the administrator: no organization receives this layer without an explicit decision.
• Same authentication and tenant isolation as the rest of the portal.
• Reuse of the existing flag mechanism, with no parallel infrastructure.

Out of scope for this discussion

• Defining which data and views are part of the advanced layer.
• Route and UI design.
• Any action, remediation or configuration change from the portal.
• New agent-side data collection.

Open questions

1. A single advanced-visibility flag, or one flag per data family as they are added?

Next step

If the idea fits the project's direction, I will write a detailed plan with the proposed routes and the views that could be made available, as a spec under docs/superpowers/specs/portal/, following the existing conventions.

This feature would especially help MSSPs whose customers have internal IT staff or are managed by an IT manager who needs this information. It would help the tool evolve considerably, and I would like to take part in this development if it aligns with the project's direction.

[ToddHebebrand]

Thanks for this. The principles are the right ones: read-only, off by default, no new collection, and fail closed.

Where I'd take it: one flag per data family, not one "advanced" flag behind a separate /portal_advanced namespace. That's already how the portal works:

• Each surface has its own enable_* column on portal_branding (apps/api/src/db/schema/portal.ts).
• Those columns are listed in PORTAL_VISIBILITY_FLAG_KEYS (apps/api/src/services/portal/portalFlags.ts:11).
• Each route is gated with a 403 by createPortalFeatureGateStrict (apps/api/src/routes/portal/featureFlags.ts).
• The MSP turns each one on in the org's Portal settings.

Your #5861 work already set the pattern for a more sensitive tier: enableNetworkAlerts is its own flag and deliberately stays out of "Enable all". A single "advanced" switch would put data of very different sensitivity behind one toggle. An MSP couldn't give a customer patch detail without also handing over everything else in the bundle. A second namespace would also duplicate gates we already have.

What the spec still needs is the data itself. Please name the families you have in mind, for example patch and vulnerability detail, software inventory, hardware, or network and SNMP detail. For each one, say what it shows and whether it's sensitive enough to sit outside "Enable all", as network alerts do. That list is what I'd review. The flag mechanics are already settled by the existing pattern.

On "specific stakeholders": portal users have no roles today. A portal_users row is a login attached to a contact, and every gate is per organization. So a customer's IT manager and their office staff see the same portal. Scoping depth by person would need portal roles, which is a separate design. I'd leave that out of this proposal and do it per organization first.

If you'd like to write it up, a spec PR under docs/superpowers/specs/portal/ works, alongside the existing portal visibility specs.

[fabicarvano]

Thanks Todd. Below is where the spec stands before I open the PR: the catalog with primary sources, the exact fields per family, what I found overlapping with the existing portal, and three points I need you to confirm. Everything traces to tables and endpoints that exist today. Nothing needs new agent-side collection.

Catalog

One flag per family, one PR per family, ordered from least to most sensitive. Each flag is a notNull default(false) column on portal_branding.

PR	Family	Flag (proposed)	In "Enable all"	Primary sources
1	Hardware health	enableHardwareHealth	Yes	device_hardware_health, device_hardware_components, device_hardware_events, device_disks, devices.batteryStatus
2	Hardware inventory	enableHardwareInventory	Yes	device_hardware, device_memory_modules, device_network, device_connections (aggregates only)
3	Performance	enablePerformance	Yes	metric_rollups, device_metrics (network volume and interfaceStats)
4	Software inventory	enableSoftwareInventory	Yes	software_inventory
5	Patch detail	enablePatchDetail	No	patches, device_patches
6	Vulnerability detail	enableVulnerabilityDetail	No	vulnerabilities, device_vulnerabilities, software_inventory

Sensitivity rule. Descriptive data about the asset goes inside "Enable all". Data that points at a weakness (patch gaps, vulnerabilities) stays outside, like enableNetworkAlerts. "Enable all" (enableAllVisibility() in OrgPortalSettingsEditor.tsx and PORTAL_VISIBILITY_FLAG_KEYS) turns on PRs 1 to 4 and leaves 5 and 6 alone.

Closed field lists. Every read model selects explicit columns, never select() on a source table, and a contract test per endpoint asserts that the excluded fields are absent. The lists below are the allowlists.

Fields per family

PR 1: Hardware health

• Include. Device level: overall health (ok, warning, critical, unknown), summary.counts, lastCollectedAt. Components (current rows only, stale = false): type (controller, virtual_disk, physical_disk, cache_battery, enclosure), name, model, health, state, sizeBytes, temperatureC, predictiveFailure, progressPercent (rebuild). Events: eventType, fromHealth, toHealth, occurredAt. File systems (device_disks): mountPoint, totalGb, usedGb, freeGb, usedPercent, health. Notebook battery (devices.batteryStatus): present, percent, chargingState, pluggedIn, timeRemainingMinutes, timeToFullMinutes, reportedAt.
• Exclude. bmc and collector component types, serial, firmware, attributes, source, alertExempt, all *Streak counters, sources, agentVersion, event detail, device_disks.device.
• Notes. cache_battery is the RAID controller cache battery, not the notebook battery. BatteryStatus has charge level and state only, with no wear or cycle count, so the portal cannot say a battery is degraded. There is no health signal for CPU or memory. Memory capacity is inventory (PR 2), usage is performance (PR 3).

PR 2: Hardware inventory

• Include. device_hardware: manufacturer, model, cpuModel, cpuCores, cpuThreads, ramTotalMb, diskTotalGb, gpuModel, biosVersion. Memory per slot (device_memory_modules): slotIndex, locator, populated, capacityMb, memoryType, formFactor, speedMts, configuredSpeedMts. Network adapters (device_network): interfaceName, ipAddress, ipType, isPrimary. Connections (device_connections): counts by protocol and state only.
• Exclude. serialNumber (device and modules), partNumber, module manufacturer, mtlsCertSerialNumber, adapter macAddress and publicIp, IP history (device_ip_history), and from connections localAddr, localPort, remoteAddr, remotePort, pid, processName.
• Notes. device_network.public_ip is never written by the agent ingest, so it is always null. Local listening ports are left out on purpose, since they point at exposed services. osVersion is already in EnrichedPortalDevice and is not repeated.

PR 3: Performance

• Include. From metric_rollups, average and maximum per bucket: cpu_percent, ram_percent, ram_used_mb, disk_percent, disk_used_gb, disk_read_bps, disk_write_bps, bandwidth_in_bps, bandwidth_out_bps. From device_metrics: network volume (networkInBytes, networkOutBytes) summed per day, and interfaceStats per interface (name, speed, inBytesPerSec, outBytesPerSec, inErrors, outErrors). Ranges: 24h, 7d, 30d. Per device and aggregated per organization.
• Exclude. customMetrics, processCount, process samples, disk byte and op counters, and from interfaceStats the cumulative counters and packets (inBytes, outBytes, inPackets, outPackets).
• Retention. 24h reads the 5-minute buckets, 7d and 30d read the hourly buckets. Rollup retention defaults are 90 days (5 minutes), 548 days (hourly) and 1095 days (daily), and metricRollupMaintenance.ts enforces floors of 30, 365 and 730 days, so a 30-day view holds under any configuration.
• Network volume caveat. The agent sends networkInBytes as the delta since the previous sample, and the console sums it per bucket, so the portal does the same. Bytes are not in ROLLUP_METRIC_NAMES, and interfaceStats is a jsonb (up to 100 interfaces per sample) on the raw table. Both therefore depend on raw retention, which defaults to 30 days (DEVICE_METRICS_RETENTION_DAYS, clamped 1 to 365). When the requested range exceeds it, the response says so instead of presenting a partial total as complete. Adding bytes to the rollups is out of scope.

PR 4: Software inventory

• Include. name, version, vendor, installDate, lastSeen, per device and aggregated per organization.
• Exclude. installLocation, uninstallString, fileHash, hashAlgorithm, observationId, isManaged, catalogId.
• Notes. It reads software_inventory, which carries org_id. device_software has no org_id and is not used.

PR 5: Patch detail

• Include. patches: title, severity, version, kbArticleUrl. device_patches: status limited to pending, installed, failed, plus installedAt, installedVersion, availableVersion, lastCheckedAt.
• Exclude. missing and skipped statuses, lastError, failureCount, rollbackAvailable, scope, and everything about policies, approvals, jobs and rollback.
• Notes. missing is a tombstone, not a pending patch, so the read model reuses OUTSTANDING_DEVICE_PATCH_STATUSES for "pending". lastError is agent free text that can carry internal paths, and failed already tells the customer what matters.

PR 6: Vulnerability detail

• Include. cveId, severity, cvssScore, knownExploited (CISA KEV), device_vulnerabilities.status (open, patched, mitigated, accepted), riskScore, detectedAt, resolvedAt, and the affected software name and version via softwareInventoryId (nullable), read straight from software_inventory so it does not depend on PR 4's flag.
• Exclude. mitigationNote, acceptedBy, acceptedUntil, ticketId, resolvedObservationId, cvssVector, and matchConfidence as a field.
• Filter. matchConfidence is used as a filter: fuzzy matches are not returned, only authoritative and curated. How to treat a null confidence is settled in that PR after checking how the column is populated.
• Notes. accepted tells the customer the administrator chose to live with a finding. The status is shown, never the note or who accepted.

What the inventory found in the existing portal

• enableSecurity already covers most of the console's Security screen. GET /portal/security/overview returns score, band, score history, weekly threat events per source (native, SentinelOne, Huntress) and vulnerabilities.openBySeverity, kevCount and lastDetectedAt. GET /portal/security/devices returns per-device protection, antivirus products, real-time protection, definitions age, encryption, firewall and pending critical patches. So I am not adding a security family, and PR 6 does not repeat those aggregates.
• enableNetworkVisibility is already inside "Enable all" (PORTAL_VISIBILITY_FLAG_KEYS and enableAllVisibility()), so there is nothing to move there.
• EnrichedPortalDevice already exposes hostname, OS, status, last seen, protection, encryption, last backup and warranty end. The new families do not repeat these, and the per-device families do not require enableDevices: each has its own flag.

Per-family checklist (existing pattern, no new mechanism)

1. Migration (checked by check:migrations) and column in db/schema/portal.ts, plus the column in the portal_branding entry of tenantExportPolicyRegistry.ts. The table exists, so no new tenancy, RLS or cascade entry.
2. The key in PORTAL_VISIBILITY_FLAG_KEYS, or outside it with the same comment enableNetworkAlerts carries.
3. Defaults and types in routes/orgPortalSettings.ts.
4. STRICT_PORTAL_FEATURES entry and a createPortalFeatureGateStrict('<flag>') line in routes/portal/index.ts. Disabled means 403 with the family's code, fail closed for a missing row, false or null.
5. The flag in the select of the authenticated GET /portal/branding.
6. Toggle in OrgPortalSettingsEditor.tsx and labels in the locale files.
7. Read model, route and colocated *.test.ts: gate (missing row, false, null, true), tenancy, contract on the allowlist, "Enable all" behavior, and the migration leaving every existing organization at false.

Two optional suggestions, opened last and only if you like them

A. SNMP advanced option. It enriches the Network Visibility asset rows with an optional snmp block, present only when its own flag is on (outside "Enable all") and enableNetworkVisibility is on, and omitted, never null-filled, otherwise. Like activeAlertCount?, it follows the pattern already on NetworkAssetRowDto.

• Fields. polling { isActive, lastPolledAt, lastStatus }, uptimeSeconds, interfaces (ifOperStatus, ifDescr, in and out rate from the hardware counters), printer supplies as a percentage, and page count.
• Allowlist. Standard MIB objects only: sysUpTime, ifOperStatus, ifDescr, ifHCInOctets and ifHCOutOctets (falling back to ifInOctets and ifOutOctets), prtMarkerSuppliesDescription, prtMarkerSuppliesLevel, prtMarkerSuppliesMaxCapacity, prtMarkerLifeCount. Matching is on COALESCE(base_oid, oid), since walked columns store the instance in oid. The exact OIDs are fixed in that PR against the built-in snmp_templates.
• Data safety. snmp_devices mixes credentials with harmless columns, so the query selects only assetId, isActive, lastPolled and lastStatus. community, authPassword, privPassword, username, the protocols, ipAddress, port, pollingInterval, the error and backoff fields, and snmp_metrics.name never leave the API. Tests seed credentials and non-allowlisted OIDs and assert they never appear.
• Value. It is the most effort for the least value in the plan, and a value only appears if the asset's template polls that OID. I would only do it if you see demand from customers with many SNMP-managed assets.

B. Security posture in the default overview. It adds to GET /portal/security/overview, under enableSecurity and with no new flag, fields from security_posture_org_snapshots: per-control scores (patchCompliance, encryption, avHealth, firewall, passwordPolicy, osCurrency, adminExposure), devices per risk level and topIssues. It leaves out openPortsScore, factorDetails, per-device recommendations, and the raw local-admin and encryption details. The change is additive, but it changes the default portal for every organization with security visible and touches the shared types and DTO tests. That departs from one flag per family, so I am leaving it to you.

If you prefer to skip either, they drop out with no effect on PRs 1 to 6.

Three points to confirm

1. createPortalFeatureGateStrict looks typed on flags derived from PORTAL_VISIBILITY_FLAG_KEYS. For PRs 5 and 6 I would add a second list (for example PORTAL_SENSITIVE_FLAG_KEYS) instead of widening that type, so those flags never join "Enable all". OK?
2. Since this has several waves, should I register it with the feature lifecycle (a parent issue and one wave per family)?
3. Are the flag names fine? They follow the enable* pattern, and I am happy to rename them.

If the direction works, I will open the spec PR under docs/superpowers/specs/portal/ (spec only, no code), then PR 1 as the pilot for the flag mechanics.

[ToddHebebrand]

This is the list I asked for. The catalog lines up with the schema, the field allowlists are careful, and the sensitivity rule (describing the asset goes in "Enable all", pointing at a weakness stays out) is the right one. Answers first, then four things to fix in the spec.

1. A separate list for the sensitive tier: yes, but your premise needs one correction. "Enable all" is not derived from PORTAL_VISIBILITY_FLAG_KEYS. It's a hand-written literal in enableAllVisibility() (apps/web/src/components/settings/OrgPortalSettingsEditor.tsx:191). It already differs from the API list: it sets enableDevices, which isn't in the list. The API list drives two things: the strict-gate types (apps/api/src/routes/portal/featureFlags.ts:10, :83, :118) and the PATCH requested/current handling (apps/api/src/routes/orgPortalSettings.ts:224-245). So leaving a flag out of the API list does not keep it out of "Enable all". Today that rule exists only in comments (apps/api/src/db/schema/portal.ts:60-63). Go ahead with PORTAL_SENSITIVE_FLAG_KEYS in services/portal/portalFlags.ts, and do three things with it:

• Move enableNetworkAlerts into it, so the list covers the whole tier and not just your two new flags.
• Widen createPortalFeatureGateStrict and STRICT_PORTAL_FEATURES to StrictPortalVisibilityFlag | PortalSensitiveFlag.
• Add a test to OrgPortalSettingsEditor.test.tsx that clicks "Enable all" and asserts every sensitive flag is still false. Nothing tests this today, and that test is what actually enforces the tier.

2. Feature lifecycle: yes, but you don't need to set it up. It's maintainer tooling. Once the spec PR merges, we'll create the parent issue and one wave sub-issue per family. Then each family PR just needs Closes #<wave> in its body.

3. Flag names: fine, with one exception. I'd rename enablePerformance to enablePerformanceMetrics. Every other name says what data it unlocks, and "performance" alone doesn't. Keep the rest.

Four corrections for the spec:

• Patch severity (PR 5). patches.severity is only set by a trusted catalog match. Agent-reported severity lives on device_patches.reported_severity. The effective value is COALESCE of the two, via EFFECTIVE_PATCH_SEVERITY_SQL (apps/api/src/services/patchSeverityOverlay.ts:23; see the comment at apps/api/src/db/schema/patches.ts:217-224). If you read patches.severity alone, most agent-reported patches will show no severity. Use the overlay.
• Null matchConfidence (PR 6). You don't need to wait for that PR to settle this. A null confidence is the OS-vulnerability path: CVEs matched by OS build, not by software product (apps/api/src/services/vulnerabilityCorrelation.ts:663). Those are precise matches, so keep them. Separately, the existing overview's openBySeverity and kevCount count every open row regardless of confidence (apps/api/src/services/portal/securityReadModel.ts:213-274). If PR 6 drops fuzzy matches, the detail list won't add up to the overview totals the customer sees next to it. Use the same population in both: either filter both or neither. I'd lean toward filtering both, but say which in the spec.
• Checklist gaps. updatePortalSettingsSchema (packages/shared/src/validators/portal.ts:93) is .strict(), so a new key fails with a 400 until it's added there. The portal app's branding type (apps/portal/src/lib/api.ts, around line 784) and the page/nav gating need the flag too, along with the PortalSettings type in the editor. Add both to step 6.
• Small citation fix. The rollup retention floors and defaults live in apps/api/src/services/metricRollupRetention.ts:22-32, not metricRollupMaintenance.ts. The numbers you quoted are right.

Two sensitivity notes for the spec:

• Portal users have no roles. Turning on PR 5 or PR 6 shows the per-host missing-patch and CVE/KEV map to every portal login in that org, office staff included. Keeping those flags out of "Enable all" is right. The toggle description in the editor should say plainly who will see it.
• For PR 2 adapter IPs, skip tunnel and overlay interfaces (WireGuard, Tailscale, ZeroTier, and the like), or leave the address out for them. On managed machines those adapters often carry the MSP's own management-network addressing, which shouldn't appear in a customer view. Customer LAN addresses are fine.

For every per-device route, take the org from portalAuth and never from the request. The tenancy test should forge a device id from another org and expect a 404.

On the two optional suggestions: I'd hold A (SNMP) until a customer asks for it. You've already called it the most effort for the least value, and the network page you built covers polling status at the overview level. On B: no to folding it into enableSecurity. That would change what every org with security enabled already sees, without the MSP doing anything, which is exactly what one flag per family is meant to prevent. If posture detail is worth doing, it gets its own flag. topIssues is open jsonb, so it would need an explicit field allowlist like your other families.

Settings placement checks out. The flags live per org on portal_branding, they're edited in one place (OrgPortalSettingsEditor), and there's no partner-level default to keep in sync. Each family PR touches a *Settings* component, so please include the home, level, and count line from the PR template.

Go ahead with the spec PR under docs/superpowers/specs/portal/, then PR 1 as the pilot.

Status: direction approved. Spec PR next.

[fabicarvano]

Spec PR is up: #7642

It covers the six read-only families (hardware health, hardware inventory, performance, software inventory, patch detail, vulnerability detail), one flag per family, in wave order, with the changes from your review:

• "Enable all" described as the hand-written enableAllVisibility() literal, plus a new PORTAL_SENSITIVE_FLAG_KEYS (including enableNetworkAlerts) and an editor test that clicking "Enable all" leaves every sensitive flag false
• enablePerformance renamed to enablePerformanceMetrics
• patch detail uses the effective severity overlay
• vulnerability detail has no confidence filter, same population as the overview counts
• the .strict() settings schema, /portal/branding select, portal app types and the export-policy registry are in the per-family checklist
• SNMP option on hold, security posture not proposed as designed

Two points need your call, both listed in section 13: whether the strict gate type should include only the 403-gated sensitive flags (enableNetworkAlerts has no 403 gate), and whether wave 2 connections should also expose local listening ports (currently out).

The only red check is the ai-workspace image scan (libexpat1 HIGH findings in the base image), unrelated to this docs-only change. CI Success is green.

[ToddHebebrand]

The feature is registered: #7730 is the parent, with one wave per family in spec order.

• W01 W01: Hardware health (enableHardwareHealth) + PORTAL_SENSITIVE_FLAG_KEYS / Enable-all guard #7731: Hardware health, plus PORTAL_SENSITIVE_FLAG_KEYS and the "Enable all" test
• W02 W02: Hardware inventory (enableHardwareInventory) #7732: Hardware inventory
• W03 W03: Performance metrics (enablePerformanceMetrics) #7733: Performance metrics
• W04 W04: Software inventory (enableSoftwareInventory) #7734: Software inventory
• W05 W05: Patch detail (enablePatchDetail, sensitive) #7735: Patch detail (sensitive)
• W06 W06: Vulnerability detail (enableVulnerabilityDetail, sensitive) #7736: Vulnerability detail (sensitive)

On your process question: yes, the merged spec serves as the plan, and there's no separate plan doc to write first. Open one PR per wave with Closes #<wave issue> in the body so the wave closes when it merges. Each PR that touches OrgPortalSettingsEditor.tsx carries the settings block from the PR template. The spec follow-up nits are in #7670, which is queued.