From 9fc6f5f8a76e808d83fcbcadc6292bae9d04752a Mon Sep 17 00:00:00 2001 From: Oliver Kieselbach Date: Tue, 10 Mar 2026 13:34:27 +0100 Subject: [PATCH] architecture docs updated --- ARCHITECTURE.md | 75 ++++++++---- src/Web/autopilot-monitor-web/README.md | 152 ++---------------------- 2 files changed, 61 insertions(+), 166 deletions(-) diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index 9eedd232..e3d1ab6e 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -56,6 +56,7 @@ Device (Agent) ──NDJSON+gzip──► Azure Functions ──► Azure Table | Component | Technology | Purpose | |-----------|------------|---------| | **Agent** | .NET Framework 4.8 (Windows) | Runs on devices during enrollment, collects telemetry | +| **SummaryDialog** | .NET Framework 4.8 (WPF) | Post-enrollment summary UI (outcome, app timeline, auto-close) | | **Backend** | Azure Functions .NET 8 (Isolated Worker) | REST API, event processing, rule engine, storage | | **Web** | Next.js 15 + TypeScript + React 18 | Dashboard, settings, analytics, real-time UI | | **Shared** | .NET Standard 2.0 | DTOs, models, enums, constants shared between Agent & Backend | @@ -89,7 +90,8 @@ AutopilotMonitor.sln │ ├── Shared/AutopilotMonitor.Shared/ (netstandard2.0) │ ├── Agent/ │ │ ├── AutopilotMonitor.Agent/ (net48, Exe – entry point) -│ │ └── AutopilotMonitor.Agent.Core/ (net48, Lib – core logic) +│ │ ├── AutopilotMonitor.Agent.Core/ (net48, Lib – core logic) +│ │ └── AutopilotMonitor.SummaryDialog/ (net48, WPF – enrollment summary UI) │ ├── Backend/ │ │ ├── AutopilotMonitor.Functions/ (net8.0, Azure Functions v4) │ │ └── AutopilotMonitor.Functions.Tests/ (net8.0, xUnit) @@ -108,6 +110,7 @@ AutopilotMonitor.sln **Project References:** ``` Shared ◄── Agent.Core ◄── Agent + ◄── SummaryDialog Shared ◄── Functions ◄── Functions.Tests Web (independent – communicates via REST + SignalR) ``` @@ -160,6 +163,7 @@ Monitoring/ ├── Analyzers/ Security checks (LocalAdminAnalyzer) ├── Collectors/ Data collectors (ESP, Hello, Performance, GatherRules, Diagnostics) ├── Core/ Orchestration (MonitoringService, EventSpool, SessionPersistence) +├── Interop/ P/Invoke declarations (process creation, registry change notifications) ├── Network/ API client, emergency reporter, geo-location, network metrics ├── Replay/ Log replay for testing/simulation └── Tracking/ Enrollment state machine, IME parser, script tracking @@ -206,7 +210,7 @@ Monitoring/ - **Monitoring:** Application Insights with sampling - **Entry Point:** `src/Backend/AutopilotMonitor.Functions/Program.cs` -### Endpoints (~60 Functions) +### Endpoints (~61 Functions) **Agent-to-Cloud (device auth via cert/bootstrap):** @@ -218,6 +222,13 @@ Monitoring/ | `/agent/upload-url` | POST | Get short-lived SAS URL for diagnostics | | `/agent/error` | POST | Report agent errors | +**Version Management:** + +| Route | Method | Purpose | +|-------|--------|---------| +| `/versions/block` | POST | Add version block/kill rule | +| `/versions/blocked` | GET | List active version block rules | + **Bootstrap (pre-MDM auth):** | Route | Method | Purpose | @@ -241,7 +252,8 @@ Monitoring/ | **Devices** | `POST /devices/block`, `DELETE /devices/block/{serial}`, `GET /devices/blocked` | | **Reports** | `POST /sessions/{id}/report`, `GET /galactic/session-reports` | | **Metrics** | `GET /metrics/usage`, `GET /metrics/app`, `GET /metrics/geographic`, `GET /stats/platform` | -| **Galactic** | `/galactic/metrics/*`, `/galactic/audit/logs`, `/galactic/session-reports` | +| **Galactic** | `/galactic/metrics/*`, `/galactic/audit/logs`, `/galactic/session-reports`, `/galactic/notifications` (CRUD + dismiss) | +| **Progress** | `GET /progress/sessions`, `GET /progress/sessions/{id}/events` | | **SignalR** | `POST /realtime/negotiate`, `POST /realtime/groups/join`, `POST /realtime/groups/leave` | | **Health** | `GET /health`, `GET /health/detailed` | @@ -263,6 +275,11 @@ Monitoring/ | `BlockedDeviceService` | Device block/kill signal management | | `SessionReportService` | Report ZIP generation + Blob upload | | `GraphTokenService` | MS Graph token acquisition for Autopilot device validation | +| `BlockedVersionService` | Version-based block/kill rules with wildcard and ceiling patterns | +| `GalacticNotificationService` | Persistent in-app notifications for Galactic Admins (survives page reloads) | +| `HealthCheckService` | Health checks for Storage, Processing, and Agent binary availability | +| `PreviewWhitelistService` | Private Preview tenant whitelist with 5-min cache | +| `ResendEmailService` | Transactional emails via Resend.com for Preview notifications | ### Event Processing Pipeline @@ -332,6 +349,14 @@ Agent POST /api/agent/ingest (NDJSON+gzip) | `/audit` | Audit log viewer | Yes | Tenant Admin | | `/health-check` | Backend health status | Yes | Galactic Admin | | `/geographic-performance` | Geo map of deployments | Yes | Galactic Admin | +| `/progress` | Real-time enrollment progress tracking | Yes | Tenant Admin | +| `/preview` | Private Preview waitlist/approval page | Yes | Unapproved tenants | +| `/changelog` | Platform change log & known issues | Public | — | +| `/roadmap` | Planned features & current focus areas | Public | — | +| `/about` | Platform introduction & quick links | Public | — | +| `/privacy` | Privacy policy & data handling | Public | — | +| `/terms` | Terms of use & legal disclaimers | Public | — | +| `/go/[code]` | Bootstrap script generator (validates code → returns PS1) | Public | — | | `/docs/[section]` | Documentation | Public | — | ### State Management @@ -399,12 +424,12 @@ React Context API (no Redux/Zustand): ## Data Model -### Azure Table Storage (21 Tables) +### Azure Table Storage (23 Tables) | Table | PartitionKey | RowKey | Purpose | |-------|-------------|--------|---------| | `Sessions` | TenantId | SessionId | Enrollment sessions | -| `EnrollmentEvents` | TenantId | Timestamp_EventId | Individual events | +| `Events` | SessionId | Timestamp_Sequence | Individual events | | `AdminConfiguration` | "GlobalConfig" | "config" | Platform-wide settings | | `TenantConfiguration` | TenantId | "config" | Per-tenant settings | | `GatherRules` | TenantId | RuleId | Data collection rules | @@ -424,6 +449,8 @@ React Context API (no Redux/Zustand): | `UserActivity` | TenantId | UserId | User login tracking | | `RuleStates` | TenantId | RuleId | Rule enable/disable state | | `PreviewConfig` | "Preview" | "config" | Preview feature config | +| `BlockedVersions` | "BlockedVersions" | Pattern | Version block/kill rules (wildcards, ceilings) | +| `GalacticNotifications` | "GalacticNotifications" | InvertedTicks_Id | Persistent in-app notifications for Galactic Admins | ### Azure Blob Storage @@ -636,7 +663,7 @@ AdminConfiguration (global, single row in Azure Table) │ Bootstrap token enablement │ └──► AgentConfigResponse (delivered to agent via /api/agent/config) - │ ConfigVersion (currently 14) + │ ConfigVersion (currently 16) │ CollectorConfiguration (nested) │ AnalyzerConfiguration (nested) │ GatherRules[] (merged built-in + tenant) @@ -738,21 +765,25 @@ cd rules && node scripts/combine.js ### Agent CLI Arguments ``` ---install Deploy via Scheduled Task (Intune package) ---run-gather-rules One-shot data collection, then exit ---console Enable console output ---cert-thumbprint {thumb} Override cert search ---tenant-id {id} Override registry tenant ---api-url {url} Override API endpoint ---bootstrap-token {token} Pre-MDM bootstrap auth ---ime-log-path {path} Override IME log folder ---replay-log-dir {path} Enable log replay mode ---replay-speed-factor {n} Compression factor (default 50) ---no-auth Disable cert auth ---no-cleanup Disable self-destruct ---reboot-on-complete Trigger reboot after enrollment ---new-session Start fresh session ---keep-logfile Preserve logs after cleanup +--install Deploy via Scheduled Task (Intune package) +--run-gather-rules One-shot data collection, then exit +--console Enable console output +--cert-thumbprint {thumb} Override cert search +--tenant-id {id} Override registry tenant +--api-url {url} Override API endpoint (alias: --backend-api) +--bootstrap-token {token} Pre-MDM bootstrap auth +--ime-log-path {path} Override IME log folder +--ime-match-log {path} Write matched IME log lines to file (debug) +--replay-log-dir {path} Enable log replay mode +--replay-speed-factor {n} Compression factor (default 50) +--no-auth Disable cert auth +--no-cleanup Disable self-destruct +--reboot-on-complete Trigger reboot after enrollment +--new-session Start fresh session +--keep-logfile Preserve logs after cleanup +--await-enrollment Wait for MDM certificate before starting +--await-enrollment-timeout {min} MDM cert wait timeout (default 480min) +--disable-geolocation Skip geo-location detection ``` ### Key Design Conventions @@ -760,7 +791,7 @@ cd rules && node scripts/combine.js | Convention | Details | |------------|---------| | Agent endpoint security | All agent endpoints use `req.ValidateSecurityAsync()` from `SecurityValidationExtensions.cs` | -| ConfigVersion | Tracks agent capability level (currently 14 = script execution tracking) | +| ConfigVersion | Tracks agent capability level (currently 16 = trace events for decision auditing) | | Phase progression | Forward-only: DeviceSetup(1) → AccountSetup(2), no backward transitions | | Phase isolation | App IDs seen in earlier phases are ignored in later phases (IME tracker) | | Completion throttling | Max 1 `completion_check` event per source per minute | diff --git a/src/Web/autopilot-monitor-web/README.md b/src/Web/autopilot-monitor-web/README.md index bfa8b6e8..4d29cdac 100644 --- a/src/Web/autopilot-monitor-web/README.md +++ b/src/Web/autopilot-monitor-web/README.md @@ -1,155 +1,19 @@ -# Autopilot Monitor Web UI +# Autopilot Monitor Web -This is the web dashboard for Autopilot Monitor, built with Next.js, React, and Tailwind CSS. +Web dashboard for Autopilot Monitor, built with Next.js, React, and Tailwind CSS. -## Prerequisites - -- Node.js 18+ and npm (or yarn/pnpm) -- Backend API running (Azure Functions) - -## Getting Started - -### 1. Install Dependencies +## Setup ```bash npm install -# or -yarn install -# or -pnpm install -``` - -### 2. Configure Environment - -Copy the environment template and configure your API endpoint: - -```bash cp .env.local.template .env.local -``` - -Edit `.env.local` and set your backend API URL: - -```env -NEXT_PUBLIC_API_BASE_URL=http://localhost:7071 -``` - -### 3. Run Development Server - -```bash npm run dev -# or -yarn dev -# or -pnpm dev ``` -Open [http://localhost:3000](http://localhost:3000) in your browser. +Configure `NEXT_PUBLIC_API_BASE_URL` in `.env.local` to point to the backend API. -## Project Structure +## Scripts -``` -autopilot-monitor-web/ -├── app/ # Next.js App Router -│ ├── layout.tsx # Root layout -│ ├── page.tsx # Home page (dashboard) -│ └── globals.css # Global styles -├── components/ # React components -├── lib/ # Utility functions and API clients -├── public/ # Static assets -├── .env.local.template # Environment variables template -├── next.config.ts # Next.js configuration -├── tailwind.config.ts # Tailwind CSS configuration -└── package.json # Dependencies and scripts -``` - -## Phase 1 Features - -The current Phase 1 implementation includes: - -- ✅ Basic dashboard layout -- ✅ Stats cards placeholder -- ✅ Responsive design with Tailwind CSS -- ⏳ API integration (to be implemented) -- ⏳ Real-time session monitoring (to be implemented) -- ⏳ Session detail view (to be implemented) - -## Development - -### Available Scripts - -- `npm run dev` - Start development server -- `npm run build` - Build for production -- `npm run start` - Start production server -- `npm run lint` - Run ESLint - -### Adding New Features - -1. **API Integration** - - Create API client in `lib/api.ts` - - Use React hooks for data fetching - - Consider using SWR or React Query for caching - -2. **New Pages** - - Add routes in `app/` directory - - Create `page.tsx` for the route - - Add navigation links - -3. **Components** - - Reusable components go in `components/` - - Use TypeScript for type safety - - Style with Tailwind CSS utility classes - -## Deployment - -### Azure Static Web Apps - -1. Create a Static Web App in Azure Portal -2. Connect your GitHub repository -3. Set build configuration: - - **App location**: `/src/Web/autopilot-monitor-web` - - **API location**: (leave empty, using separate Functions app) - - **Output location**: `out` (or leave default) - -4. Configure environment variables in Azure: - - `NEXT_PUBLIC_API_BASE_URL`: Your Azure Functions URL - -### Build for Production - -```bash -npm run build -``` - -The output will be in the `.next` directory (or `out` if using static export). - -## Troubleshooting - -### Port already in use - -If port 3000 is already in use: - -```bash -PORT=3001 npm run dev -``` - -### API connection errors - -1. Verify the backend is running -2. Check `.env.local` has correct API URL -3. Check browser console for CORS errors -4. Verify Azure Functions is accessible - -### Build errors - -1. Delete `.next` and `node_modules` -2. Run `npm install` again -3. Run `npm run build` - -## Next Steps (Future Phases) - -- [ ] Implement real-time updates with SignalR -- [ ] Add session detail pages -- [ ] Create troubleshooting wizard -- [ ] Add fleet analytics dashboard -- [ ] Implement user authentication (Azure AD) -- [ ] Add dark mode toggle -- [ ] Create mobile-responsive design improvements +- `npm run dev` - Development server +- `npm run build` - Production build +- `npm run lint` - Linting