Initial commit

README.md

@@ -1,3 +1,110 @@
-# E8-CAT
+# E8-CAT – Essential Eight Compliance Assessment Tool
 
-Essential Eight compliance assessment tool
+`E8-CAT` is a lightweight PowerShell-based compliance scanner, similar in spirit to CIS-CAT, designed to check Windows workstations and servers against the [ACSC Essential Eight](https://www.cyber.gov.au/acsc/view-all-content/essential-eight) hardening strategies.  
+
+This build includes rules for **Maturity Levels 1–3** and can report on all levels in a single run.
+
+---
+
+## Features
+- **Profiles:** Run checks for a specific level (`ML1`, `ML2`, `ML3`) or all at once (`All`).  
+- **All-level mode:** With `-Profile All`, the scanner evaluates ML1–3 in one pass and reports per-level results and scores.  
+- **Per-rule applicability:** Rules know their minimum level. If they don’t apply to a level, they’re marked **N/A**.  
+- **Evidence-based:** Each rule outputs evidence showing registry values, feature state, or script results.  
+- **Skip logic:** If a product isn’t installed (e.g., Chrome, Edge, Firefox, IE on Win11), the rule reports **SKIPPED**.  
+- **Cross-scope checks:** Registry policies are checked under both **HKLM** and **HKCU**.  
+- **Output formats:** JSON, CSV, and HTML reports saved under `.\out\`.  
+- **PowerShell 5.1 compatible:** Works on standard Windows builds (no modern operators like `??`).
+
+---
+
+## Usage
+```powershell
+Set-ExecutionPolicy Bypass -Scope Process -Force
+
+# Navigate into the E8-CAT folder
+Set-Location .\E8-CAT
+
+# Run all levels in one pass
+.\E8-CAT.ps1 -Profile All
+
+# Run a specific maturity level
+.\E8-CAT.ps1 -Profile ML1
+.\E8-CAT.ps1 -Profile ML2
+.\E8-CAT.ps1 -Profile ML3
+```
+
+---
+
+## Outputs
+Results are written to `.\out` with timestamped filenames:
+- **CSV** – Easy import into Excel or SIEM tools  
+- **JSON** – Machine-readable for pipelines and dashboards  
+- **HTML** – Human-friendly report with tables and score summaries
+
+Example output files:
+```
+.\out\E8CAT-ML1-20250902-153936.csv
+.\out\E8CAT-ML1-20250902-153936.json
+.\out\E8CAT-ML1-20250902-153936.html
+```
+
+---
+
+## Rule Coverage
+Rules are organised by strategy:
+
+- **RM – Restrict Macros:**  
+  - Office macro settings (Word/Excel/PowerPoint/Outlook, Office 15.0 & 16.0)  
+  - Block macros from the Internet  
+  - Macro runtime AV scanning  
+  - Trusted Publisher enforcement (ML3)
+
+- **AH – Application Hardening:**  
+  - Internet Explorer 11 feature disabled (skips on Win11)  
+  - Java browser plugin absent  
+  - Microsoft Edge SmartScreen + download restrictions  
+  - Chrome SafeBrowsing, download restrictions, extension blocklist  
+  - Firefox enterprise policy presence  
+  - Windows SmartScreen (multiple policy keys)
+
+- **AC – Application Control:**  
+  - AppLocker policy present and enforced (not AuditOnly)  
+  - Windows Defender Application Control (WDAC) policy present  
+  - Software Restriction Policies present
+
+- **RA – Restrict Admin Privileges:**  
+  - Built-in Administrator account disabled  
+  - UAC (EnableLUA) enabled  
+  - Local Administrator Password Solution (LAPS) policy present (Windows or legacy)
+
+---
+
+## Rule Semantics
+Rules are defined in `.\rules\*.json`. Each rule specifies:
+- `id`, `title`, `strategy`, `type`, `script` (or registry/command parameters)  
+- `minLevel` (ML1, ML2, ML3)
+
+**Return values in rules:**
+- `$true` → **PASS**  
+- `$false` → **FAIL**  
+- `$null` → **SKIPPED**
+
+---
+
+## Profiles
+Profiles are stored under `.\profiles\ml1.json`, `ml2.json`, `ml3.json`. They contain the rule IDs included at each level.  
+When running `-Profile All`, these profiles are ignored and all rules are checked, with results shown for each level.
+
+---
+
+## Example Run
+```powershell
+PS C:\E8-CAT> .\E8-CAT.ps1 -Profile All
+E8-CAT ML1 score: 78.9% (PASS=15 / FAIL=4 / Total=19)
+E8-CAT ML2 score: 65.0% (PASS=13 / FAIL=7 / Total=20)
+E8-CAT ML3 score: 42.9% (PASS=9 / FAIL=12 / Total=21)
+Saved: .\out\E8CAT-All-20250902-161413.json
+Saved: .\out\E8CAT-All-20250902-161413.csv
+Saved: .\out\E8CAT-All-20250902-161413.html
+```