first commit

README.md

@@ -1,2 +1,156 @@
-# comi-audit-secu
+# comi-audit-hardeningkitty
 
+Read-only WAPT audit of Windows security configurations using the upstream
+[HardeningKitty / windows_hardening](https://github.com/0x6d69636b/windows_hardening)
+module. This is a **WAPT package SOURCE**, not a signed and deployable `.wapt` file.
+
+## How it works
+
+1. On the WAPT packaging workstation, `update_package()` (or
+   `python tools/vendor_assets.py`) downloads **pinned commit**
+   `acf9ecee3d044a9337df7aad80e730cbd746e8de` from GitHub over HTTPS.
+   It creates `vendor/` containing the official PowerShell module, the MIT
+   license, all finding lists, the upstream signed finding-list manifest and a
+   reproducible local SHA-256 manifest. It does not download a floating `master`.
+2. You review the upstream files, **build and sign** the WAPT package as usual.
+   The signed package is deployed from your WAPT repository. Windows clients do
+   not access GitHub and do not require PowerShell Gallery.
+3. `install()` checks SHA-256 of all vendored files, copies them to a locked
+   directory under `%ProgramData%\Comitari\Audit-HardeningKitty` and creates a
+   separate private reports directory.
+4. The package `audit()` launches 64-bit Windows PowerShell 5.1 under the WAPT
+   service account. It calls `Invoke-HardeningKitty` with **`-Mode Audit` only**,
+   then evaluates the official CSV report. There is no remediation code.
+5. `audit()` compares the report to the source finding list. Missing/skipped
+   checks are recorded as unknown and make the status `ERROR` (never false OK).
+   The full report and PowerShell log stay on the audited workstation.
+6. WAPT gets an `OK`, `WARNING`, or `ERROR` status. WAPT Enterprise also gets
+   metrics and findings through `write_audit_data_if_changed()` in section
+   `HardeningKitty`; when that function is unavailable, the audit status and
+   local reports still work.
+
+## Prepare, build, sign, deploy
+
+Extract this source archive into your WAPT development directory as
+`comi-audit-hardeningkitty`. On a packaging workstation with Python 3 and
+Internet access:
+
+```powershell
+cd C:\waptdev\comi-audit-hardeningkitty
+py -3 tools\vendor_assets.py --dest vendor
+py -3 -m unittest discover -s tests -v
+```
+
+Alternatively, use **update-package** in the WAPT IDE; `setup.py` exposes
+`update_package()` for the same operation. The vendor script can also accept
+`--archive C:\path\to\github-commit.zip --archive-sha256 <SHA256>` to prepare
+from an explicitly checked local archive.
+
+Review `vendor/`, then build, sign and upload the package from the WAPT Console
+using your standard certificate. **Do not sign/build before populating
+`vendor/`**. You cannot deploy this source ZIP directly as a WAPT package.
+
+Assign the package to Windows machines. `audit_schedule: 1w` in `WAPT/control`
+requests weekly checks after installation; edit to `1d` for daily checks if
+appropriate for your fleet. Force an audit on a test host with:
+
+```cmd
+wapt-get audit -f
+```
+
+## Baseline selection
+
+`audit_config.json` defaults to `"profile": "auto"` and `"source": "GPO"`.
+The PowerShell wrapper detects Windows using CIM and reads `DisplayVersion` /
+Windows build. It deliberately refuses unsupported systems, rather than silently
+selecting an incorrect benchmark:
+
+| Target | Benchmark selection |
+| --- | --- |
+| Windows 11 21H2 to 26H2 | Matching Microsoft Security Baseline (machine) |
+| Windows 10 20H2, 21H1, 21H2, 22H2 | Matching Microsoft Security Baseline (machine) |
+| Windows Server 2012 R2, 2016, 2019 | Latest available CIS benchmark in pinned snapshot (machine) |
+| Windows Server 2022 | Microsoft Security Baseline 2022, DC/member |
+| Windows Server 2025 | Microsoft Security Baseline 2025, DC/member |
+
+For a vendor-agnostic research baseline, set `"profile": "community"` to use
+`finding_list_0x6d69636b_machine.csv`. You may also specify the exact name of
+any bundled `finding_list_*_machine.csv`, e.g.
+`"finding_list_cis_microsoft_windows_11_enterprise_25h2_machine.csv"`.
+Windows user profiles are **not** audited: WAPT normally runs as LocalSystem,
+and checking `*_user.csv` would give misleading results for the logged-in user.
+The wrapper rejects them. An Intune policy source can be selected with
+`"source": "Intune"`, but it still uses an OS-compatible finding list; test
+this mode before rollout, since not all controls expose an Intune mapping.
+
+## Severity mapping
+
+| Situation | WAPT audit status |
+| --- | --- |
+| No failed/skipped checks | `OK` |
+| Low/Medium baseline deviation | `WARNING` |
+| High baseline deviation | `ERROR` |
+| Missing/skipped checks, empty/malformed report, missing upstream asset, unsupported OS, timeout | `ERROR` |
+
+The severity is **upstream policy severity**, not a CVSS score. You can change
+`error_on_high` to `false` to map High deviations to `WARNING`, or `warn_on_low`
+to `false` to ignore low-severity deviations for the aggregate status. Missing
+or indeterminate checks always produce `ERROR`.
+
+## Audit data and locations
+
+WAPT Enterprise section: `HardeningKitty`. Keys include `status`, `benchmark`,
+`os_build`, `source`, `upstream_commit`, `passed`, `high`, `medium`, `low`,
+`unknown`, `executed`, `expected`, `skipped`, `total`, `compliant_percent`,
+`last_run_utc`, `last_error` and 16 stable JSON shards (`findings_00` ... `findings_15`).
+All 16 shards are written, even when empty, avoiding stale findings from prior
+runs. Shard entries contain ID, name, category, severity and test result.
+`publish_current_values` defaults to `false` to avoid exposing local security
+configuration details in WAPT audit-data. Enable only if policy allows it.
+
+Local reports (restricted to SYSTEM/Administrators):
+
+```text
+C:\ProgramData\Comitari\Audit-HardeningKitty-Reports\run-YYYYMMDD-HHMMSS-XXXXXXXX\
+    hardeningkitty.csv
+    powershell.log
+    host.json
+    summary.json
+```
+
+`retain_audit_runs` defaults to 8. `uninstall()` removes the engine but retains
+historical reports for traceability. WAPT Enterprise may show the last values
+for each changed metric with a 120-day retention (`max_count` varies by metric).
+The raw CSV can contain sensitive host configuration and never leaves the
+machine unless explicitly exported by the administrator.
+
+## Operational considerations
+
+- **No Windows hardening is applied.** The package never executes HailMary,
+  GPO, registry changes or remediation. The upstream Audit mode may create and
+  delete transient files needed to inspect local policy.
+- Test on one Windows 10 and Windows 11 workstation (and representative server
+  versions) before fleet deployment. The upstream README warns that some checks
+  may be inaccurate on non-English systems.
+- Test memory, CPU and duration against your fleet. Default timeout is 900
+  seconds; increase `timeout_seconds` for slow hosts if necessary.
+- Windows PowerShell 5.1 and sufficient machine-level privileges are required.
+  The wrapper requests process-local execution-policy Bypass; WDAC/CLM/AppLocker
+  may still block unsigned PowerShell modules. Adapt the signing strategy to
+  your enterprise policy rather than disabling those protections.
+- Pinning and file hashing ensure reproducibility and post-packaging integrity,
+  but you must still review external executable PowerShell code before trusting
+  it. The MIT upstream LICENSE is included with the actual WAPT payload.
+- Mismatches to a benchmark do **not** automatically imply a vulnerability or
+  justify remediation: validate the expected value against business use and
+  any domain/Intune GPO before taking action.
+
+## Validation status
+
+The Python parser, status mapping, coverage detection, privacy defaults,
+local manifest verification and offline archive extraction have unit tests
+under `tests/`. A real PowerShell audit on a Windows machine and an end-to-end
+WAPT signed install must still be validated in your environment.
+
+Upstream: https://github.com/0x6d69636b/windows_hardening
+WAPT documentation: https://www.wapt.fr/en/doc-2.7/wapt-create-packages-code.html