Rename application to Samsara and add assessment summary, detailed tabs and local Linux inventory
This commit is contained in:
@@ -1,29 +1,37 @@
|
||||
# Development guide
|
||||
# Developer guide
|
||||
|
||||
Run commands from the repository root. Use a Python 3.11+ virtual environment and requirements.txt. Start with `python -m server_buddy.main`. Assets are resolved relative to the module, independent of the user's working directory; tests use repository-relative schema/fixture paths.
|
||||
Use Python 3.11+ and requirements.txt. Run `python -m samsara.main` from the repository root. The desktop requires a Qt-capable graphical session; tests run offscreen.
|
||||
|
||||
## Phase 1 behavior
|
||||
## UI and orchestration
|
||||
|
||||
Qt widgets stay on the GUI thread. CollectionJob loads the bundled JSON in a QThread and delivers stage/result/error signals. Analyze and import buttons are disabled until the worker finishes; closing an active job is deferred to avoid destroying a running thread. Demo loading is finite local I/O; production timeout/cancellation and process lifecycle management are Phase 3 requirements. No subprocesses are launched in Phase 1.
|
||||
Analyze is the default page. Source and OS selection are visible together; Auto-detect is the default. The OS selector is disabled for saved inventories and fixed synthetic samples because their OS is recorded in the input. Windows and RHEL version profiles are explicit user intent, not promises of live collector availability.
|
||||
|
||||
Tables use Qt proxy filtering across all columns with native numeric sorting. Session history records repeated fixture loads without changing fixture timestamps. Dashboard counts unique hostnames from fixture/import history, while history counts runs. High-risk findings refer to the current assessment. Two OS-specific fixtures supply the demo; user input cannot relabel synthetic evidence as a live server assessment.
|
||||
`CollectionJob` runs detection and collection outside the GUI thread, then delivers stage, result or failure signals. OS mismatches and unsupported collectors preserve the previous result. Cancellation uses QThread interruption and the Linux runner's polling callback. All source/profile controls are locked while collecting. Closing an active worker is deferred to avoid destroying a running thread.
|
||||
|
||||
Risk rules live in analyzers/assessment.py. Each finding contains classification, evidence, severity and points. Score is the sum capped at 100: 0 informational, 1–29 low, 30–59 medium, 60–89 high, 90–100 critical. These preliminary rules are demonstration logic, not a validated production risk model. Severity is an individual finding's severity, while overall risk is the aggregate. Observation limits always contribute uncertainty.
|
||||
Results are initially empty. Successful assessments create session history records; choosing one restores its inventory and derived assessment. Reports always use the displayed assessment. Successful analysis opens the dedicated Summary page. Its first tab shows retirement risk, OS/version, a capped list of workload software hints and enabled scheduled work. Comprehensive tabs lazily load searchable inventory and evidence tables. The same compact summary is included in HTML reports; all inventory remains exported. Scrollable pages and fixed-size form cards preserve legibility at smaller window sizes.
|
||||
|
||||
Collection JSON uses schemas/inventory-v1.schema.json. Export JSON wraps the collection as inventory_result and includes the derived assessment. Do not treat the report wrapper as collection JSON. Live collection must enforce the schema at the boundary and tighten field schemas as PowerShell contracts are implemented. Never replace failed checks with synthetic values.
|
||||
## OS detection
|
||||
|
||||
## Verification in this development environment
|
||||
`core/detection.py` reads local platform metadata and `/etc/os-release`, recognizes RHEL-related families and validates explicit major-version profiles. It does not resolve names or contact remote systems. Other Linux distributions may use Auto-detect. Windows desktop build numbers are not treated as Windows Server edition evidence. Saved inventories use their metadata and skip local OS detection.
|
||||
|
||||
Python 3.12.3 is available. `python3 -m unittest discover -s tests -v`: four tests passed; schema and Qt smoke tests skipped because jsonschema and PySide6 are absent. An isolated installation under /tmp failed due to package server DNS/network resolution. GUI launch and visual appearance have not been verified here. Run the documented tests after installing dependencies on Linux Mint; also test a Windows desktop before distribution.
|
||||
## Linux backend
|
||||
|
||||
No PowerShell collection scripts or production collector exist yet, so there is no real PowerShell output to validate. Phase 1 requires no remote accounts, remoting configuration, or administrative privilege.
|
||||
`collectors/linux.py` executes fixed arguments from system binary directories with a restricted environment, no shell or user hostname, suppressed command diagnostics and no sudo. Commands are polled for cancellation, an eight-second limit and 10 MiB output bound, then killed/reaped on failure. Overall command collection is limited to approximately 60 seconds. Reads are limited to local OS/proc metadata; remote mounts are not traversed. The headless CLI uses only the standard library and creates new output files exclusively.
|
||||
|
||||
## Follow-up verification
|
||||
Report source is included in locally collected server metadata. Import removes that field and treats source assertions as unverified. Inventory import validates schemas/inventory-v1.schema.json, caps size, strips diagnostic strings and command fields, and recalculates assessment results. Tighten field definitions alongside future production collector contracts.
|
||||
|
||||
After dependencies were installed in the project virtual environment: `.venv/bin/python -m unittest discover -s tests -v` passed all 12 tests, including two offscreen Qt tests, schema validation, Linux inventory import/NFS evidence, sensitive-field exclusion and startup diagnostics. Source compilation passed. Normal X11 startup is blocked by the confirmed missing `libxcb-cursor.so.0`; the launcher prints Mint installation instructions. Windows execution and real RHEL collection remain untested/unimplemented as described in PLATFORMS.md.
|
||||
## Analysis
|
||||
|
||||
## Local Linux collector
|
||||
Each finding has classification, supporting evidence, severity and points. Score is capped at 100: 0 informational, 1–29 low, 30–59 medium, 60–89 high, 90–100 critical. This is demonstration heuristic logic, not a validated production risk model. Known Linux application service names receive potential-dependency findings; other running services remain unknown rather than all being classified as application workloads. Incomplete checks and observation limits always require review.
|
||||
|
||||
`collectors/linux.py` executes fixed argument lists from system binary directories with a restricted environment, no shell or user hostname, DEVNULL stderr and no sudo. Each process is polled for cancellation, an eight-second time limit and a 10 MiB output limit; the process is killed and reaped on interruption/failure. Overall collection is bounded to approximately 60 seconds for command execution. Local /proc and /etc/os-release reads do not access mounted remote filesystems. There is no arbitrary command UI. Collection source is included in server metadata; JSON import strips that source field and treats imported evidence as unverified. GUI workers retain the previous assessment on cancellation. New local checks intentionally return partial/missing statuses rather than asserting full coverage.
|
||||
## Verification
|
||||
|
||||
Verification: 21 unit/UI tests passed, plus a real local read-only smoke collection validated against the JSON schema with HTML/JSON generation. Tests use both RPM and dpkg fixtures, check service/IPv6 parsing and unknown-service classification, command timeout/reaping, cancellation, and source labels. Real RHEL and Windows execution is still pending.
|
||||
Run `python -m unittest discover -s tests -v`. Coverage includes profiles/detection, synthetic isolation, real-source labels, RPM/dpkg parsing, IPv4/IPv6, missing commands, cancellation/timeouts, no automatic assessments, history restoration, imports, UI selection and HTML escaping/export. Offscreen snapshots can verify geometry at standard and smaller resolutions; they do not replace native desktop testing.
|
||||
|
||||
A local Linux smoke collection has passed schema validation and HTML/JSON generation in the restricted development environment. Systemd/interface restrictions were recorded as failed checks. Real Windows and RHEL release validation, remote transports and packaging are still pending. Never replace missing checks with samples.
|
||||
|
||||
Summary presentation is derived by analyzers/summary.py without altering assessment scores. Higher numbers mean more retirement concerns. OS version uses explicit os_version or an OS-name version hint, never the kernel/build as a fallback. Software name rules omit obvious library/development/documentation packages; a running service without a matching package can still be highlighted. Unknown schedules and missing checks remain explicit. Linux scheduler metadata includes system timer calendars/next-run data and bounded readable /etc/crontab and /etc/cron.d entries. Cron command arguments, inline code and environment assignments never enter the collected data; safe script/executable names identify work. User crontabs, anacron, periodic-script contents and execution history remain outside coverage.
|
||||
|
||||
## Application branding
|
||||
|
||||
The supplied Samsara JPEG is bundled unchanged as `samsara/assets/samsara-logo.jpg`. `ui/branding.py` provides the shared Qt application/window icon and Windows taskbar application identity. The sidebar uses the same asset. Future packaged builds must include this asset; the original `App Logo` folder is not required at runtime. Icon loading was checked at 16–256 pixel sizes and the sidebar preview was reviewed offscreen. Native desktop/taskbar appearance still needs platform verification.
|
||||
|
||||
@@ -1,24 +1,32 @@
|
||||
# Implementation plan
|
||||
# Architecture and implementation plan
|
||||
|
||||
Repository inspection: empty project directory with reserved environment directories; no existing application or repository instructions.
|
||||
Samsara is a Windows Server and enterprise Linux retirement assessment tool. Desktop OS and assessed OS are independent.
|
||||
|
||||
1. **Phase 1 (implemented):** offline PySide6 dashboard, six navigation pages, ten inventory tabs, hostname validation, background demo loading, searchable/sortable tables, session history, explicit execution selection, synthetic fixture, local demo exports and preliminary evidence/risk presentation.
|
||||
2. **Phase 2:** independent read-only PowerShell modules for system/roles, services, TCP/processes, scheduled tasks, registry software, volumes/shares and public certificate metadata. Versioned JSON envelope with per-check statuses. Optional AD enrichment interface; no AD requirement.
|
||||
3. **Phase 3:** Windows execution-host collector using existing authorized Invoke-Command sessions. Resolve trusted script paths; pass validated hostname as an argument to a fixed script via subprocess argument lists (never shell=True). Enforce timeouts, cancellation, process cleanup, bounded output and schema validation. Linux remains offline. No remoting setup.
|
||||
4. **Phase 4:** expand transparent weighted rules, role/process mappings, service account and inbound connection correlation; distinguish observed activity from potential dependencies and unknown evidence. Review critical infrastructure role rules before live use.
|
||||
5. **Phase 5:** production reports, redaction of sensitive service/task arguments, failed-check visibility, export validation and report metadata. Existing Phase 1 exports contain synthetic records only.
|
||||
6. **Phase 6:** collector contract tests, PowerShell validation on Windows, failure/timeout tests, Windows packaging and signed release guidance.
|
||||
## Project structure
|
||||
|
||||
## Structure and boundaries
|
||||
- `samsara/ui`: Qt interface and background collection worker.
|
||||
- `samsara/core`: hostname validation, OS detection and profile matching.
|
||||
- `samsara/collectors`: offline fixtures, schema-validated JSON intake and local Linux collector.
|
||||
- `samsara/analyzers`: evidence classification and transparent heuristic scoring.
|
||||
- `samsara/reporting`: local HTML/JSON export.
|
||||
- `samsara/models`: reserved for typed collection models.
|
||||
- `samsara/assets`: labeled synthetic fixtures.
|
||||
- `schemas`: versioned collection JSON contract.
|
||||
- `powershell`: Windows collection requirements; scripts pending.
|
||||
- `tests`: core, parsing, detection, worker, UI and export tests.
|
||||
|
||||
`server_buddy/ui`: Qt views and background worker. `core`: input validation and future orchestration. `collectors`: platform-specific collection backends. `models`: future typed schema adapters. `analyzers`: evidence and heuristic rules. `reporting`: local exports. `assets`: bundled offline fixture. `powershell`: future Windows-only scripts. `schemas`: collection contract. `tests`: fixture, core and optional Qt tests.
|
||||
## Implemented
|
||||
|
||||
History is session-only; timestamps are original fixture timestamps. No SQLite or remote collection in Phase 1. A missing check never means a negative result. Synthetic demo is bound to a reserved example.test hostname and documentation-only IP addresses. Export pipeline must gain production redaction before any live collection is enabled.
|
||||
The simplified UI starts on Analyze with This computer and Auto-detect selected. History, Reports and Settings are secondary pages. No fabricated assessment is inserted at startup. Local collection detects the OS and uses the Linux backend where available. Version mismatches and unsupported Windows collection fail explicitly. Saved inventories and synthetic samples have separate source choices. A dedicated Summary destination opens after collection, with retirement risk, OS/version, important software and scheduled work; comprehensive Networking, Software, Tasks, Dependencies and other tabs expose evidence. Reports can be saved immediately after an assessment; session history reopens previous results.
|
||||
|
||||
## Scope expansion: Linux targets and desktop startup
|
||||
Linux collection provides read-only OS, service, timer calendar, system cron, TCP, package and mount observations. Missing evidence is represented by check status, never by synthetic substitution. Commands have cancellation, time/output limits and cleanup. See README for exact omissions.
|
||||
|
||||
The target scope now includes Windows Server 2016 onward and RHEL-based Linux, with either Windows or Mint as the reporting desktop. Added a RHEL synthetic dataset, target selector, background schema-validated JSON intake, OS-neutral report labels, NFS/Samba dependency rules, and a pre-Qt diagnostic for the missing Mint xcb cursor library. Live collection remains outside the current Phase 1 implementation. See PLATFORMS.md for transport boundaries, Linux inventory mappings and the required test matrix.
|
||||
## Remaining phases
|
||||
|
||||
## Local Linux testing implementation
|
||||
1. Independent Windows inventory scripts for system/roles, services, TCP/processes, tasks, registry software, storage/shares and public certificate metadata. Do not use Win32_Product. Optional AD enrichment must not become a prerequisite.
|
||||
2. Authorized Windows execution-host remoting and Linux SSH transport, explicit targets/authentication, host verification, bounded output, timeouts and cancellation. No infrastructure configuration.
|
||||
3. Expand Linux inventory for user schedulers and remaining cron/anacron coverage, identities, share exports, disk usage and application-specific public certificates with least-privilege access.
|
||||
4. Validate OS-specific application/critical infrastructure rules, observed versus inferred relationships and historical/manual verification workflows. No automatic retirement approval.
|
||||
5. Production schemas, redaction, Windows/RHEL platform testing, packaging and signed releases.
|
||||
|
||||
Added real read-only local collection for Mint and RPM-based Linux, a direct Analyze This Linux PC action, Settings mode, cancellation, command time/output bounds and headless JSON export. Real local results have distinct banners/history/report labels. Missing service identities, user/cron tasks, share exports, disk capacity, role correlation and certificate checks remain explicit. Both package formats are covered by parser tests; full RHEL and Windows validation remains pending. No remote transport is enabled.
|
||||
The original empty repository had no existing application or project instructions. All current collection is local or offline; no enterprise targets are contacted in development.
|
||||
|
||||
@@ -1,34 +1,20 @@
|
||||
# Platform support and collection plan
|
||||
# Platform support
|
||||
|
||||
## Current functionality
|
||||
Samsara targets retirement assessment of Windows Server 2016, 2019, 2022 and 2025, RHEL 7 (legacy)/8/9/10, and compatible enterprise Linux distributions. OS profiles express the intended assessment target, not a tested support guarantee for live collection.
|
||||
|
||||
| Desktop | Windows inventory reporting | RHEL-based inventory reporting | Live collection |
|
||||
| --- | --- | --- | --- |
|
||||
| Linux Mint, Python 3.11+ | Synthetic demo and schema-validated local JSON import | Synthetic demo and schema-validated local JSON import | Local read-only Linux collector on Linux; no remote collection |
|
||||
| Windows 10/11, Python 3.11+ | Same application code; Windows desktop testing pending | Same application code; Windows desktop testing pending | Not implemented |
|
||||
| Capability | Current availability |
|
||||
| --- | --- |
|
||||
| Local Linux collection | Implemented; RPM and dpkg inventory paths |
|
||||
| OS auto-detection | Local OS identification; Linux distribution family and major version checks |
|
||||
| Saved inventory analysis | Windows/Linux v1 JSON, with OS supplied by inventory metadata |
|
||||
| Windows live collection | Not implemented |
|
||||
| Remote SSH/PowerShell collection | Not implemented |
|
||||
| Desktop | Python 3.11+ with Qt on Linux and Windows; Windows execution validation pending |
|
||||
|
||||
**Update:** Local Linux Mint/RHEL-based collection is now implemented via `collectors/linux.py`, with direct GUI and headless CLI entry points. It uses RPM on hosts where RPM is available and dpkg on Mint. Mint-like package parsing and mocked RPM output are tested; real RHEL release validation remains pending. See README for exact coverage and missing checks. Windows live collection remains unimplemented.
|
||||
Auto-detection reads local OS metadata without remote name resolution or probing. Explicit RHEL selections check family and major version. Other Linux distributions can use Auto-detect for local testing. Windows identification does not infer a Server edition from a desktop kernel number. Unsupported live collectors return an explicit error while keeping prior results.
|
||||
|
||||
Qt is a desktop dependency, not a dependency to install on assessed servers. Headless RHEL servers will produce JSON through a separate collector and do not need PySide6. Reporting does not require Windows administrative modules on Linux.
|
||||
The local collector uses fixed read-only system commands and records partial or failed checks for unsupported commands, permissions and missing evidence. Test each RHEL/distribution release before relying on production output. Containers may restrict systemd, interfaces, processes and mount namespaces.
|
||||
|
||||
## Target collection support
|
||||
Future Windows collection must use existing authorized remoting from a Windows execution host, compatible with Windows PowerShell 5.1. Windows administration modules must not be run natively on Linux. Future Linux remote collection must use existing authorized SSH with host-key verification. Neither transport should enable services, install an agent or escalate privileges automatically.
|
||||
|
||||
Windows targets: Windows Server 2016 onward. Use read-only PowerShell compatible with Windows PowerShell 5.1 from an existing authorized Windows execution host. Linux Mint can import that execution host's JSON. A future transport to a Windows execution host must be explicit and authenticated; never run Windows administration modules natively on Linux. Feature availability and permissions vary, so every module reports complete/partial/failed/not_collected separately. Test each supported Windows Server release before claiming collection compatibility.
|
||||
|
||||
RHEL-based targets: RHEL and compatible distributions, initially validate supported enterprise 8/9/10 families individually; older versions require explicit compatibility testing. The offline local collector can run on the Linux execution host and export JSON for manual transfer. Future remote collection will use existing authorized SSH. No agent installation, automatic SSH enablement, privilege escalation or remote configuration. Windows desktop SSH support must be checked at runtime. Offline JSON remains the common fallback.
|
||||
|
||||
Linux inventory requirements:
|
||||
|
||||
- `/etc/os-release`, kernel, boot time, addresses, interfaces and directory integration evidence.
|
||||
- systemd services with state, unit path and execution identity; no secret-bearing environment or command arguments.
|
||||
- `ss` TCP observations, with unprivileged process attribution explicitly marked incomplete where necessary.
|
||||
- system and accessible user timers, cron/anacron schedules; inaccessible accounts and application schedulers remain missing evidence.
|
||||
- RPM package inventory; never install or alter packages.
|
||||
- mounts, local/remote filesystems, free space, NFS exports and Samba shares. Distinguish remote mounts from exported storage and avoid reading protected configuration secrets.
|
||||
- Configured public certificate metadata from explicit locations. Linux has no single Windows-style machine certificate store; do not claim full certificate coverage or inspect private keys.
|
||||
|
||||
Common analysis must distinguish observations, inferred workloads and unknowns. Windows roles and Linux package/service workload hints are not equivalent evidence. NFS, Samba and SMB exports all require dependency review; listing a share does not prove active consumers. Account and critical infrastructure rule mappings need OS-specific coverage before production deployment.
|
||||
|
||||
## Validation remaining
|
||||
|
||||
Windows GUI and collection tests; Windows Server release matrix; RHEL/compatible distribution matrix; SSH authentication and host-key checks; PowerShell transport; timeout/cancellation and output bounds; incomplete permissions; production field redaction; signed packaging. No real enterprise server is contacted during development without an explicit target and authorization.
|
||||
Required production validation includes Windows desktop/server release testing, RHEL/distribution testing, incomplete permissions, process lifecycle behavior, schema contracts, report redaction, packaging and signing. Linux inventory coverage and current omissions are documented in README.md.
|
||||
|
||||
Reference in New Issue
Block a user