ge-aerospace/shopdb-flask
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Gate endpoint UI refresh on fresh telemetry and land endpoint agent

Browse Source 
A command reaching 'succeeded' only proves the agent ran the action, not that it posted a new telemetry snapshot. Reloading panels on command success alone re-rendered stale service/process rows, so a stopped process could still show running right after Refresh Status.

Add a lightweight telemetrymeta probe exposing lastreportedat and gate both the header Refresh Status action and inline row Start/Stop on that stamp advancing past a pre-action baseline. Polling is bounded so an offline or idle agent never hangs the button, and messaging distinguishes a confirmed refresh from a queued one.

Bring the .NET endpoint agent source (service, tray, installer) into the repo so Cameron can merge and test, with an agent/.gitignore keeping bin/obj/publish out. Includes the DncMain launch-path fix, tray single-file host env scrub, and best-effort file logger.
This commit is contained in:
benjamin.baker
2026-08-28 15:07:20 -04:00
parent c001657582
commit af133372b4
46 changed files with 4593 additions and 128 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
plugins/endpoints/api/routes.py
View File

@@ -11,7 +11,7 @@ import time
from datetime import datetime, timedelta, timezone
from flask import Blueprint, request, current_app
from flask_jwt_extended import jwt_required, current_user
from flask_jwt_extended import current_user
from shopdb.api import (
db, Asset, Setting, success_response, error_response, paginated_response,
@@ -21,7 +21,7 @@ from shopdb.api import (
)
from ..models import EndpointState, EndpointEvent, EndpointCommand
from ..commands import COMMAND_ALLOWLIST, is_allowed_action, ALLOWED_ACTIONS_FOR, row_actions_for, requires_target, action_targetkind
from ..commands import COMMAND_ALLOWLIST, is_allowed_action, ALLOWED_ACTIONS_FOR, row_actions_for, requires_target, action_targetkind, elevated_permission_for
from ..eventcatalog import CRITICAL_EVENT_IDS, event_severity, event_title
endpoints_bp = Blueprint('endpoints', __name__)
@@ -56,7 +56,6 @@ def _format_uptime(seconds):
# =============================================================================
@endpoints_bp.route('/', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def list_endpoints():
"""List reported endpoint states.
@@ -91,7 +90,6 @@ def list_endpoints():
@endpoints_bp.route('/<int:asset_id>', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def get_endpoint(asset_id: int):
"""Get the current state for one endpoint by asset id."""
@@ -108,7 +106,6 @@ def get_endpoint(asset_id: int):
@endpoints_bp.route('/<int:asset_id>/events', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def list_endpoint_events(asset_id: int):
"""List curated Windows events for one endpoint, newest first."""
@@ -136,7 +133,6 @@ def list_endpoint_events(asset_id: int):
# =============================================================================
@endpoints_bp.route('/asset/<int:asset_id>/status', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def panel_status(asset_id: int):
"""Keyvalue panel: the endpoint's current status snapshot.
@@ -168,8 +164,25 @@ def panel_status(asset_id: int):
return success_response({'fields': fields})
@endpoints_bp.route('/asset/<int:asset_id>/telemetrymeta', methods=['GET'])
@require_permission('endpoints.view')
def panel_telemetry_meta(asset_id: int):
"""Lightweight freshness probe for the panels.
Returns just the endpoint's lastreportedat so the WebUI can tell whether a
genuinely new telemetry snapshot has landed after it forces a collect. The
UI captures this before enqueuing collect_now (or a row Start/Stop), then
polls until the stamp advances - a command reaching 'succeeded' only means
the agent ran it, not that it has yet posted the fresh services snapshot, so
gating the refresh on this timestamp is what avoids re-rendering stale rows.
"""
state = EndpointState.query.filter_by(assetid=asset_id).first()
stamp = (state.lastreportedat.isoformat() + 'Z'
if state and state.lastreportedat else None)
return success_response({'lastreportedat': stamp})
@endpoints_bp.route('/asset/<int:asset_id>/services', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def panel_services(asset_id: int):
"""List panel: monitored services/processes with a run-state badge per row.
@@ -199,6 +212,7 @@ def panel_services(asset_id: int):
running = raw in ('running', 'started', 'up', 'ok', 'active')
row = {
'name': name,
'kind': (kind or '').lower() or None,
'statelabel': 'Running' if running else (raw.title() or 'Unknown'),
'statecolor': 'green' if running else ('red' if raw else 'gray'),
}
@@ -217,7 +231,6 @@ def panel_services(asset_id: int):
@endpoints_bp.route('/asset/<int:asset_id>/recentevents', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def panel_recent_events(asset_id: int):
"""List panel: the endpoint's most recent curated events, newest first.
@@ -241,7 +254,6 @@ def panel_recent_events(asset_id: int):
@endpoints_bp.route('/asset/<int:asset_id>/interfaces', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def panel_interfaces(asset_id: int):
"""Table panel: every hardware NIC the agent last reported.
@@ -287,7 +299,6 @@ def panel_interfaces(asset_id: int):
# =============================================================================
@endpoints_bp.route('/dashboard/summary', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def dashboard_summary():
"""High-level fleet counts for the endpoints dashboard."""
@@ -315,7 +326,6 @@ def dashboard_summary():
@endpoints_bp.route('/dashboard/quiet', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def dashboard_quiet():
"""Endpoints that reported before, then went quiet past the window.
@@ -351,7 +361,6 @@ def dashboard_quiet():
@endpoints_bp.route('/dashboard/stability', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def dashboard_stability():
"""Endpoints with recent crash/shutdown/corruption events.
@@ -441,7 +450,6 @@ def _agentkey_status_payload():
@endpoints_bp.route('/agentkey', methods=['GET'])
@jwt_required()
@require_role('admin')
def get_agentkey():
"""Report the endpoint agent key state (no secret)."""
@@ -449,7 +457,6 @@ def get_agentkey():
@endpoints_bp.route('/agentkey/regenerate', methods=['POST'])
@jwt_required()
@require_role('admin')
def regenerate_agentkey():
"""Mint a fresh endpoint agent key, revoking any previous one.
@@ -480,7 +487,6 @@ def regenerate_agentkey():
@endpoints_bp.route('/agentkey', methods=['DELETE'])
@jwt_required()
@require_role('admin')
def revoke_agentkey():
"""Revoke the endpoint agent key: stop all managed-token endpoint traffic.
@@ -534,7 +540,6 @@ def _resolve_asset_for_hostname(hostname):
@endpoints_bp.route('/<int:asset_id>/commands', methods=['GET'])
@jwt_required()
@require_permission('endpoints.view')
def list_endpoint_commands(asset_id: int):
"""Recent commands for one endpoint, newest first (operator view)."""
@@ -547,7 +552,6 @@ def list_endpoint_commands(asset_id: int):
@endpoints_bp.route('/<int:asset_id>/commands', methods=['POST'])
@jwt_required()
@require_permission('endpoints.command')
def enqueue_endpoint_command(asset_id: int):
"""Queue an allowlisted command for one endpoint.
@@ -562,6 +566,16 @@ def enqueue_endpoint_command(asset_id: int):
return error_response(ErrorCodes.VALIDATION_ERROR,
f'Unknown or disallowed action: {action!r}')
# Destructive actions (for example system_restart) demand a stricter grant
# ON TOP OF endpoints.command, so a remote reboot cannot ride the routine
# toggle permission.
elevated = elevated_permission_for(action)
if elevated and not current_user.haspermission(elevated):
return error_response(
ErrorCodes.FORBIDDEN,
f'Action {action!r} requires the {elevated} permission',
http_code=403)
if action not in ALLOWED_ACTIONS_FOR(assetid=asset_id):
return error_response(
ErrorCodes.VALIDATION_ERROR,

21
plugins/endpoints/commands.py
View File

@@ -69,9 +69,30 @@ COMMAND_ALLOWLIST = {
'label': 'Check MTConnect',
'description': 'Report whether the MTConnect UDC agent is running.',
},
'system_restart': {
'label': 'Restart computer',
'description': 'Restart the endpoint computer immediately.',
},
'collect_now': {
'label': 'Collect now',
'description': 'Force the endpoint agent to report fresh telemetry off-cadence.',
},
}
# Actions that demand a permission stricter than the base endpoints.command.
# The enqueue route requires the caller to ALSO hold the mapped permission, so a
# destructive action (a remote reboot) is a heavier grant than a routine toggle.
ELEVATED_ACTION_PERMISSIONS = {
'system_restart': 'endpoints.restart',
}
def elevated_permission_for(action):
"""The extra permission an action requires, or None for routine actions."""
return ELEVATED_ACTION_PERMISSIONS.get(action)
# Maps a monitored services/processes row to the start/stop/status actions that
# control it, so the services panel can render an inline toggle on exactly the
# rows that have a registered command action. The key is the agent-reported

53
plugins/endpoints/plugin.py
View File

@@ -108,6 +108,11 @@ class EndpointsPlugin(BasePlugin):
# shop-floor PC is a heavier grant than reading its telemetry.
('endpoints.command',
'Send allowlisted commands to endpoint agents', 'endpoints'),
# Elevated grant for destructive endpoint actions (system_restart).
# Required IN ADDITION to endpoints.command by the enqueue route, so a
# remote reboot is a strictly heavier grant than a routine toggle.
('endpoints.restart',
'Restart endpoint computers (destructive)', 'endpoints'),
# Collector service scope for the endpoint agent. A managed token
# scoped to ONLY this authorizes the endpoints collector and nothing
# else, so rotating/revoking it stops endpoint-agent traffic without
@@ -181,6 +186,8 @@ class EndpointsPlugin(BasePlugin):
'icon': 'activity',
'route': '/endpoints',
'position': 16,
'permission': 'endpoints.view',
'section': 'fleet',
},
]
@@ -192,11 +199,13 @@ class EndpointsPlugin(BasePlugin):
def get_asset_panels(self) -> List[Dict]:
"""Per-PC detail panels, computer assets only.
Three panels feeding the generic renderer: the current status snapshot
(keyvalue), monitored services with a run-state badge (list), and the
most recent curated events (list). Each is a single-asset indexed read,
so the cost is the same profile as the warranty/backups panels. Panels
hide themselves when their endpoint returns nothing.
Panels feeding the generic renderer: the current status snapshot
(keyvalue), monitored services and processes split into two list cards
that share one services snapshot (filtered by kind), the most recent
curated events (list), and the network interfaces (table). Each is a
single-asset indexed read, so the cost is the same profile as the
warranty/backups panels. Panels hide themselves when their endpoint
returns nothing.
"""
return [
{
@@ -209,12 +218,13 @@ class EndpointsPlugin(BasePlugin):
'position': 10,
},
{
'id': 'endpoints-services',
'title': 'Services and processes',
'id': 'endpoints-tracked-services',
'title': 'Tracked Services',
'assettypes': ['computer'],
'endpoint': '/api/endpoints/asset/{assetid}/services',
'render': 'list',
'collapsible': True,
'filter': {'key': 'kind', 'equals': 'service'},
'status': {
'key': 'statecolor',
'levels': {
@@ -233,6 +243,32 @@ class EndpointsPlugin(BasePlugin):
'empty': 'No monitored services reported.',
'position': 12,
},
{
'id': 'endpoints-tracked-processes',
'title': 'Tracked Processes',
'assettypes': ['computer'],
'endpoint': '/api/endpoints/asset/{assetid}/services',
'render': 'list',
'collapsible': True,
'filter': {'key': 'kind', 'equals': 'process'},
'status': {
'key': 'statecolor',
'levels': {
'green': 'ok',
'yellow': 'warning',
'red': 'critical',
},
},
'map': {
'title': 'name',
'badge': {'label': 'statelabel', 'color': 'statecolor'},
'action': 'action',
},
'commandendpoint': '/api/endpoints/{assetid}/commands',
'permission': 'endpoints.command',
'empty': 'No monitored processes reported.',
'position': 13,
},
{
'id': 'endpoints-events',
'title': 'Recent events',
@@ -263,7 +299,8 @@ class EndpointsPlugin(BasePlugin):
],
},
'empty': 'No recent events.',
'position': 14,
'collapsedDefault': True,
'position': 90,
},
{
'id': 'endpoints-interfaces',

83
plugins/endpoints/tests/test_plugin.py
View File

@@ -9,6 +9,10 @@ from flask import Blueprint
from plugins.endpoints.plugin import EndpointsPlugin, CURATED_EVENT_IDS
from plugins.endpoints.eventcatalog import EVENT_CATALOG, CRITICAL_EVENT_IDS
from plugins.endpoints.commands import (
COMMAND_ALLOWLIST, is_allowed_action, elevated_permission_for,
requires_target,
)
def test_endpoints_plugin_meta_is_valid():
@@ -65,11 +69,41 @@ def test_endpoints_asset_panels_are_computer_scoped():
"""Every asset panel targets computer assets only, with an endpoint."""
plugin = EndpointsPlugin()
panels = plugin.get_asset_panels()
assert len(panels) == 3
assert len(panels) == 5
for panel in panels:
assert panel['assettypes'] == ['computer']
assert panel['endpoint'].startswith('/api/endpoints/asset/{assetid}')
assert panel['render'] in ('keyvalue', 'list')
assert panel['render'] in ('keyvalue', 'list', 'table')
def test_services_and_processes_are_split_into_two_filtered_cards():
"""The single services card is now two cards filtered by row kind, both
reading the same services snapshot so a future top-20 collector is just
another filtered panel over the same feed."""
plugin = EndpointsPlugin()
panels = {p['id']: p for p in plugin.get_asset_panels()}
services = panels['endpoints-tracked-services']
processes = panels['endpoints-tracked-processes']
assert services['title'] == 'Tracked Services'
assert processes['title'] == 'Tracked Processes'
assert services['filter'] == {'key': 'kind', 'equals': 'service'}
assert processes['filter'] == {'key': 'kind', 'equals': 'process'}
# Both slice one endpoint feed.
assert services['endpoint'] == processes['endpoint']
assert services['endpoint'].endswith('/services')
# Command wiring carries over to both cards.
assert services['permission'] == 'endpoints.command'
assert processes['permission'] == 'endpoints.command'
def test_recent_events_card_is_last_and_starts_collapsed():
"""Events is the lowest-priority card: forced to the bottom of the column
and collapsed by default."""
plugin = EndpointsPlugin()
panels = plugin.get_asset_panels()
events = next(p for p in panels if p['id'] == 'endpoints-events')
assert events['collapsedDefault'] is True
assert events['position'] == max(p['position'] for p in panels)
def test_endpoints_dashboard_widgets_declared():
@@ -90,3 +124,48 @@ def test_endpoints_navigation_item_points_at_fleet_view():
items = plugin.get_navigation_items()
routes = {item['route'] for item in items}
assert '/endpoints' in routes
def test_system_restart_is_allowlisted_and_policy_selectable():
"""Restart is a real allowlisted action, so the policy builder (which
reads COMMAND_ALLOWLIST) surfaces it as a selectable action."""
assert is_allowed_action('system_restart')
assert 'system_restart' in COMMAND_ALLOWLIST
assert COMMAND_ALLOWLIST['system_restart']['label'] == 'Restart computer'
def test_system_restart_requires_the_elevated_restart_permission():
"""Restart maps to endpoints.restart so the enqueue route can demand a
heavier grant than the routine endpoints.command toggle. Routine actions
carry no elevated requirement."""
assert elevated_permission_for('system_restart') == 'endpoints.restart'
assert elevated_permission_for('mtconnect_start') is None
def test_endpoints_declares_the_restart_permission():
"""The dedicated restart permission is declared for role-grid seeding."""
plugin = EndpointsPlugin()
permissions = {name for name, *_ in plugin.get_permissions()}
assert 'endpoints.restart' in permissions
assert 'endpoints.command' in permissions
def test_collect_now_is_allowlisted_targetless_and_routine():
"""collect_now forces an off-cadence telemetry report. It is allowlisted so
the enqueue route accepts it, carries no wire target (fixed action), and
needs no elevated grant beyond endpoints.command."""
assert is_allowed_action('collect_now')
assert 'collect_now' in COMMAND_ALLOWLIST
assert not requires_target('collect_now')
assert elevated_permission_for('collect_now') is None
def test_telemetrymeta_route_is_registered_for_freshness_gating():
"""The WebUI gates panel refreshes on lastreportedat advancing, so the
lightweight freshness probe must be exposed on the plugin blueprint."""
from flask import Flask
application = Flask(__name__)
application.register_blueprint(EndpointsPlugin().get_blueprint())
rules = {rule.rule for rule in application.url_map.iter_rules()}
assert any(rule.endswith('/asset/<int:asset_id>/telemetrymeta') for rule in rules)