Samsara/README.md

Samsara

Source repository. Windows Server and Red Hat Enterprise Linux retirement assessment using Python 3.11+ and PySide6. Inventory, dependency evidence and heuristic retirement risk remain separate from historical usage validation and administrator retirement approval.

Privacy hardening is implemented, but production approval is pending. This is not a HIPAA compliance or PHI-free attestation. Read privacy controls, configuration and acceptance gates before collecting real inventory. Historical audit documents remain in audit/.

Desktop setup

From the project root on a Linux desktop:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python -m samsara.main

On Windows, use py -3 -m venv .venv, then .venv\Scripts\python.exe -m pip install -r requirements.txt and .venv\Scripts\python.exe -m samsara.main.

Desktop dependencies are pinned to PySide6_Essentials (Qt Core/Gui/Widgets) and jsonschema; WebEngine, PDF and Qt Addons are not required. The existing development environment still includes the former umbrella packages; requirements changes do not uninstall them. constraints-tested-linux.txt records observed versions, not a complete platform/hash lock or vulnerability clearance. Obtain packages using approved provisioning; installation normally requires external downloads.

Linux desktop compatibility includes Mint. Debian-based desktops may need python3-venv libegl1 libopengl0 libxcb-cursor0 libxkbcommon-x11-0 through their package manager. Run the GUI in a graphical desktop session.

Assessment workflow

1. Choose Analyze → This computer → Auto-detect → Analyze to assess the execution host. Explicit profiles include Server 2016/2019/2022/2025 and RHEL 7 (legacy), 8/9/10 or compatible distributions. A selected profile must match the host.
2. Review Summary: OS/version, known software families, scheduled-work state, retirement risk, evidence coverage and confidence. A low score is not clearance.
3. Use searchable/sortable detailed tabs: Networking, Software, Tasks, Dependencies, Services, Storage & shares, Roles, Certificates, Risk findings, Collection checks and System. Omitted fields and missing scopes require manual verification.
4. Save minimized HTML or JSON directly inside the configured private local report directory. New filenames only. HTML creates no raw inventory sidecar.
5. History retains up to ten minimized assessments in the session by default. Clear session assessments releases application references; it does not securely erase memory or delete exports.

Saved inventory file imports bounded local JSON and recomputes the assessment. Source claims and old findings are not trusted. Legacy input enters memory before filtering: do not intentionally import known patient-bearing files to redact them. Windows Server sample and RHEL sample are clearly synthetic; they never scan another host or populate history automatically.

Privacy defaults and local output

privacy_policy.json under samsara/assets/ is an administrator-reviewed deployment configuration. Defaults omit host/domain/account identities, custom free-text names, certificate identities and all paths. A finite catalogue retains recognizable application families. States, PIDs, ports, numeric IPs, OS versions, capacities and counts remain useful, but are still confidential infrastructure metadata.

Only exact, explicitly approved local share roots can be retained. Approval of one root never authorizes child paths or filenames. No file contents are inspected. There is no automatic patient-name detector or guarantee that infrastructure metadata cannot contain PHI before projection.

Set report_directory to an approved local directory. Linux creates a missing root with mode 0700 and files with 0600; existing broadly readable roots are rejected. Windows requires a provisioned protected directory ACL and checks child ACLs before writing. Common remote paths, symlinks and reparse points are rejected. Cloud sync, backups, unusual storage backends and OS incidental writes require separate review. See the configuration and Windows directory setup instructions.

Local Windows Server collection

The code targets the Server 2016, 2019, 2022 and 2025 release builds. Actual Windows inventory, revised PowerShell queries and Windows output ACLs have not been validated on a Windows execution host in this environment. Synthetic Python tests are not Windows compatibility certification. Do not deploy to production until authorized lab validation and CHS review are complete.

Run locally using an existing authorized account and 64-bit Python 3.11+. A Windows 10/11 reporting desktop does not remotely scan servers in this phase. No WinRM/SSH configuration, service restart, agent installation, saved credentials or automatic elevation is performed. Do not use Domain Administrator by default. Permission failures and incomplete scopes remain visible; provider ACL filtering may be silent. Follow normal application-control/script-signing policy; no execution-policy bypass.

The GUI runs collection in a background worker. Each PowerShell section has a 45-second limit, an overall 300-second budget and bounded output. Stdout remains in bounded memory instead of an inventory temporary file; stderr is discarded. Cancellation/timeouts terminate and reap the owned child process.

For headless Server/Core collection, install only the headless requirements through approved provisioning. Keep samsara/, powershell/ and schemas/ together. After configuring and provisioning C:\SamsaraReports as described above:

py -3 -m venv .venv
.venv\Scripts\python.exe -m pip install -r requirements-headless.txt
.venv\Scripts\python.exe -m samsara.collectors.windows --output C:\SamsaraReports\windows-inventory.json

Use a new filename. Copy minimized output only through an organization-approved transfer process; Samsara provides no remote transport. GUI compatibility is separate from collector compatibility: use headless collection if the Qt version cannot run on the server OS or no graphical desktop is present.

Section	Default scope	Omitted or unverified
System	Fixed OS family/release/build, boot, literal IPs, adapter labels, domain-joined flag	Domain/host identity unless exact hostname approved; no AD enrichment
Roles	Installed identifiers/state	Free-text names; installation does not prove use
Services	Canonical families/opaque labels, states, startup, PID	Accounts, descriptions, executable paths/arguments
Network	TCP endpoints, state, PID, canonical process family	Snapshot direction/history may be unknown; no UDP/application content
Tasks	Opaque identity, maintenance category, state and inferred enabled state	Actions, commands, principals, trigger details and history; partial scope
Software	Canonical or approved names and numeric versions from machine registry	Publisher, dates, uninstall commands, per-user/portable software
Storage/shares	Fixed local drive metadata, capacities, configured shares and exact approved roots	Labels, child paths, filenames, contents, open-file/session activity; partial scope
Certificates	Not collected by default	Certificate identities/extensions/objects and private keys are not queried

Check timestamps/status/errors are recorded. complete describes the documented query scope, not complete retirement evidence. Privacy omissions lower confidence and trigger review; they do not add workload risk points.

Required lab validation, using the configured private directory and new output names:

.venv\Scripts\python.exe -m unittest discover -s tests -v
.venv\Scripts\python.exe tools\validate_windows_host.py --output-dir C:\SamsaraReports

The second command runs real local Windows collection, writes minimized windows-assessment.json, windows-assessment.html and validation-summary.json, and prints categorical validation status. It refuses existing files and arbitrary output directories. Review results privately. Repeat under intended least privilege and separately authorized elevation, using separate provisioned directories/policy. All four Server releases still require real-host acceptance evidence.

The direct PowerShell driver remains available, but is not supervised by Python's output/time limits or private-file writer. Do not use shell redirection or arbitrary file writes as a substitute for the protected CLI workflow.

Linux collection

Local Linux collection observes OS/version/boot, literal addresses, loaded systemd service/timer state, TCP metadata, RPM/dpkg packages and mount metadata. It does not access mounted remote filesystems. Missing commands/access produce failed checks. Default cron files and detailed timer properties are no longer read: schedule timing, commands, user schedulers and execution history need an approved separate review. Certificates, share exports/consumers and directory integration are uncollected.

For the default application-local private reports root:

python3 -m samsara.collectors.linux --output reports/linux-inventory.json

The root's parent must exist; output is minimized and files are exclusive/private. Use a configured approved absolute directory for deployment. Collection never uses sudo or changes remote settings. Native utilities and OS logging/caching behavior still require operational review; read-only queries do not mean data cannot disclose sensitive information.

Retirement scoring

Scoring model v2 uses the maximum grouped workload score (0–100), never unrestricted inventory totals. Routine Windows services/features, administrative shares, Steam/browser client traffic, unknown connections and collection failures do not receive automatic workload points. Known application PID/listener/client evidence can support a workload finding; no activity does not prove a host unused.

Coverage/confidence are independent from risk. Historical usage validation, business ownership and administrator approval are always required. Settings loads a bounded data-only scoring JSON; numeric policy values and exact rationale are preserved. Policy display names are canonicalized to avoid free-text disclosure. See scoring details.

Verification and remaining work

QT_QPA_PLATFORM=offscreen .venv/bin/python -m unittest discover -s tests -v

Synthetic tests cover identifying canaries in every major free-text path, stale findings/marker bypasses, exact-root approval, private/exclusive writes, invalid schemas/timestamps, process output limits/cancellation, UI/history, report escaping and the seven retirement scenarios. Native PowerShell tests are explicitly skipped if no runtime is available. No production collector, package installation/update or external advisory lookup was performed during hardening.

Outstanding: native Windows lab validation and ACL/race testing, least-privilege validation, platform/hash locks, native-component SBOM, authorized vulnerability scan, signed distribution, approved storage/egress/retention controls and CHS security/privacy approval. These prevent a claim of production readiness or HIPAA compliance. The old bundle/reports are not automatically updated or scrubbed.

Developer guide · Platform notes · Architecture · Security hardening