oceans2alaska/Samsara
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add local Windows Server inventory collection and validation; include core package

Browse Source
This commit is contained in:
Not Dave
2026-10-30 11:24:40 -07:00
parent 967b2bd46a
commit f65ade9fff
35 changed files with 2200 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/DEVELOPMENT.md
View File

@@ -35,3 +35,17 @@ Summary presentation is derived by analyzers/summary.py without altering assessm
## 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.
## Local Windows backend
`collectors/windows.py` implements supervised local execution; `powershell/Get-ServerInventory.ps1` dispatches independent section functions. Windows desktop detection routes through the verified CIM identity in the Windows backend, rather than inferring a Server edition from `platform.win32_ver()`. Explicit profiles are checked after the critical identity query and before other inventory work. No Windows module is executed on Linux.
The executable path comes from Windows GetSystemDirectoryW, with 64-bit Python required, never PATH/SystemRoot search. Argument lists use `-NoLogo -NoProfile -NonInteractive -File` with a trusted repository script and a fixed section enum. No shell, `-Command`, credential parameters, user-supplied command text, automatic elevation or execution-policy bypass. PSModulePath is limited to inbox modules. Native stdout is UTF-8 JSON; stderr/raw provider exceptions are excluded. Temporary stdout is bounded; each process is polled for cancellation/time/output limits and killed/reaped on exit paths. Provider services are not stopped or reconfigured.
Per-section default timeout is 45 seconds; overall budget is 300 seconds; per-section and accepted total inventory limits are 10 MiB. Timed-out/invalid sections are explicitly failed, remaining unattempted checks are not_collected when the overall budget expires, and successful observations survive. Cancellation rejects the new result and retains the previous UI assessment. The direct PowerShell `all` path emits the complete schema but has no Python timeout supervisor.
OS ProductType 2/3 plus build mapping gates Server 2016/2019/2022/2025. Workstation identities and unknown builds are rejected. A partial system check can be accepted only if the OS identity itself is verified; domain/IP failures remain explicit. Each section has start/end UTC timestamps, status, safe error codes/messages, access limitations and scope limitations. Complete means successful documented scope, not comprehensive dependency evidence. Non-elevated sensitive queries are conservatively partial. ACL-based silent filtering remains a manual verification concern.
`models/inventory.py` now owns the shared v1 validator and field allowlists. Metadata fields are additive and old demo/Linux results remain valid. Live Windows results are projected to safe fields; raw CIM instances are never serialized. Imported errors retain recognized categorical codes and timestamps but discard arbitrary diagnostic/permission text. Imports cannot assert the trusted local source label. Registry software covers both read-only machine uninstall views; services omit PathName; tasks emit safe action basenames and selected triggers rather than Arguments/XML; certificates never access private-key properties. Reports include all check statuses, timestamps and limitations.
Fixtures for all four Server releases live in tests/fixtures/windows. Python tests cover contract/identity/array handling, partial permission results, invalid output, process cancellation/reaping, timeouts, output bounds, secret-field exclusion, imports and the unchanged GUI/history/report flow. `tests/powershell/Test-Collectors.ps1` uses the native PowerShell AST parser and synthetic function/registry objects to test the scripts without querying the host; it runs automatically where PowerShell is present. This test is skipped in the current Linux environment. **No real Windows inventory has yet been produced here; do not mark the Windows milestone complete.** Use the README's explicit real-host validation command and review private reports before recording compatibility.

8
docs/IMPLEMENTATION_PLAN.md
View File

@@ -12,7 +12,7 @@ Samsara is a Windows Server and enterprise Linux retirement assessment tool. Des
- `samsara/models`: reserved for typed collection models.
- `samsara/assets`: labeled synthetic fixtures.
- `schemas`: versioned collection JSON contract.
- `powershell`: Windows collection requirements; scripts pending.
- `powershell`: Windows PowerShell 5.1 local inventory modules, shared safe-error helpers and JSON driver.
- `tests`: core, parsing, detection, worker, UI and export tests.
## Implemented
@@ -23,10 +23,14 @@ Linux collection provides read-only OS, service, timer calendar, system cron, TC
## Remaining phases
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.
1. Validate the implemented local Windows inventory on authorized Server hosts (2016/2019/2022/2025) before marking the milestone complete. Synthetic Windows contracts pass; native execution remains pending. 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.
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.
## Windows local collection milestone
Added independent read-only PowerShell modules and the local Python backend, without replacing the existing application. OS identity is accepted only for known Server build/product-type combinations. The existing QThread routes Windows auto-detect/profile choices to the backend and retains the same result, history and reporting flow. Python runs each fixed local section in a separate supervised PowerShell process, with cancellation, per-section/overall budgets, output bounds and cleanup. Per-check UTC timestamps, sanitized errors, scope and permission limitations extend schema v1 additively; old fixtures remain valid. The real-host validation tool produces full private evidence and a separate metadata-only summary for review. Remote Windows collection is not part of this milestone.

26
docs/PLATFORMS.md
View File

@@ -1,20 +1,20 @@
# Platform support
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.
Samsara targets retirement assessment of Windows Server 2016/2019/2022/2025 and enterprise Linux. Collector availability and tested platform support are different claims.
| 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 |
| Capability | Implementation | Verification |
| --- | --- | --- |
| Local Windows Server inventory | Windows PowerShell 5.1 modules plus supervised Python controller | Python contracts/fixtures/UI pass; native runtime and real-host acceptance pending |
| Local Linux inventory | Existing read-only RPM/dpkg, service, scheduler, TCP and mount collection | Local Linux smoke and automated regression tests pass; full distribution matrix pending |
| Local OS selection | Auto-detect and explicit profiles | Linux and Windows routing/profile tests pass; Windows Server identity verified by CIM/build/product type in collector |
| Offline reporting | v1 JSON import, HTML/JSON export, Summary, tabs, session history | Automated tests pass |
| Remote Windows/Linux collection | Not implemented | Separate follow-up phase |
| Qt desktop | Existing Linux/Windows UI code | Offscreen Linux tests; native Windows desktop verification pending |
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.
Windows Server builds: 14393=2016, 17763=2019, 20348=2022, 26100=2025. ProductType must be 2 (domain controller) or 3 (server). Workstations sharing a build number are rejected. Explicit selected profiles are checked against this verified identity. A failed critical OS identity check prevents acceptance of an assessment. Other sections may fail or be partial without losing successful observations.
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.
Use headless collection for Server Core and Server 2016. A collector target is not necessarily a supported Qt desktop: current Qt 6.12 lists Windows 10 1809+ and Windows 11 in its desktop support matrix. The Python headless path needs only existing 64-bit Python 3.11+ and jsonschema; the PowerShell-only driver needs Windows PowerShell 5.1. See [Qt requirements](https://doc.qt.io/qt-6/windows.html) and README instructions. No runtime is automatically installed on an assessed host.
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 checks require local CIM and inbox ServerManager, NetTCPIP, ScheduledTasks, Storage, SmbShare and certificate-provider access. Missing modules, denied scopes or policy restrictions are visible in check status. Least privilege is preferred; Domain Administrator is not a prerequisite. No elevation, remoting configuration or credential prompt is performed. Non-elevated sensitive sections are conservatively partial, and ACL filtering can remain invisible even when a query succeeds.
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.
Run `tools/validate_windows_host.py` on an explicitly authorized supported host before closing the Windows collection milestone. Record actual version, check states, errors and row counts; synthetic fixtures or mock-provider tests cannot substitute for this. Every release still needs native validation. Windows packaging, signing, constrained-language environments and remote transports remain follow-up work.