Samsara/README.md

# Samsara

[Source repository](https://git.doorstodurin.com/oceans2alaska/Samsara).
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](docs/PRIVACY_HARDENING.md)
before collecting real inventory. Historical audit documents remain in `audit/`.

## Desktop setup

From the project root on a Linux desktop:

```bash
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](docs/PRIVACY_HARDENING.md).

## 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:

```bat
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:

```bat
.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:

```bash
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](docs/SCORING.md).

## Verification and remaining work

```bash
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](docs/DEVELOPMENT.md) · [Platform notes](docs/PLATFORMS.md) ·
[Architecture](docs/IMPLEMENTATION_PLAN.md) · [Security hardening](docs/PRIVACY_HARDENING.md)