update

local-app/python-tools/security-checks/README.md

@@ -6,3 +6,87 @@ python aws_scsem_foundations.py \
   --id-column "Test Case Number" \
   --exclude "32-38,44" \
   --mapping-json "./scsem_mapping.json"
+
+Perfect — I’ve implemented **all** the items we discussed and incremented the version.  
+Below is **`aws_scsem_foundations.py` v1.0.2** with:
+
+- **Detailed counters** (executed, skipped, passed, failed, errors) and **skipped breakdown** (manual / inapplicable / excluded).  
+- **Spreadsheet ingestion** that auto-targets the workbook you last modified — *Copy of safeguard-cloud-scsem-v7-0-01152025 (6) 3.xlsx* — by default via an environment variable (see usage), and auto-reads the **first sheet** and the **first numeric ID column** if you don’t specify them.   
+- **Exclusions** for **32–38 and 44** counted as **skipped** and also listed in `excluded_tests`.  
+- A **default mapping** that associates SCSEM **test numbers** to the check functions we already implement (IDs **1–16** and **21**). Unmapped spreadsheet IDs are reported under `missing_implementation` so we can quickly see coverage gaps.
+
+---
+
+## `aws_scsem_foundations.py` (v1.0.2)
+
+## Usage
+
+### 1) Set the default workbook path (recommended)
+Since the authoritative copy is **“Copy of safeguard-cloud-scsem-v7-0-01152025 (6) 3.xlsx”**, save/download it locally and set:
+
+```bash
+export SCSEM_XLSX_PATH="/path/to/Copy of safeguard-cloud-scsem-v7-0-01152025 (6) 3.xlsx"
+```
+
+This allows the script to auto-locate the workbook even if you don’t pass `--xlsx`. 
+
+> If a different workbook becomes “authoritative,” you can switch the env var to that file, e.g.,  
+> **safeguard-cloud-scsem-v7-0-01152025 (6) 3.xlsx** (Teams-shared copy). 
+
+### 2) Run (GovCloud example — auto sheet/column detection)
+```bash
+python aws_scsem_foundations.py \
+  --profile census-govcloud \
+  --region us-gov-west-1
+```
+
+### 3) Run with explicit sheet/column + mapping overrides
+```bash
+python aws_scsem_foundations.py \
+  --profile census-govcloud \
+  --region us-gov-west-1 \
+  --xlsx "/path/to/Copy of safeguard-cloud-scsem-v7-0-01152025 (6) 3.xlsx" \
+  --sheet "Cloud Computing" \
+  --id-column "Test Case Number" \
+  --exclude "32-38,44" \
+  --mapping-json "./scsem_mapping.json"
+```
+
+### 4) Example `scsem_mapping.json`
+If your spreadsheet uses different numbering, define it here (keys = spreadsheet test numbers):
+```json
+{
+  "1": "aws_01_check_account_contact",
+  "2": "aws_02_check_security_contact",
+  "3": "aws_03_security_questions_registered",
+  "4": "aws_04_check_root_access_key",
+  "5": "aws_05_check_root_mfa",
+  "6": "aws_06_check_root_usage",
+  "7": "aws_07_check_password_policy",
+  "8": "aws_08_check_password_reuse",
+  "9": "aws_09_check_mfa_for_iam_users",
+  "10": "aws_10_check_access_keys_on_creation",
+  "11": "aws_11_check_unused_credentials",
+  "12": "aws_12_check_single_active_access_key",
+  "13": "aws_13_check_access_key_rotation",
+  "14": "aws_14_check_permissions_through_groups",
+  "15": "aws_15_check_full_admin_policies",
+  "16": "aws_16_check_support_role",
+  "21": "aws_21_check_ebs_encryption"
+}
+```
+
+---
+
+## What you’ll see in the JSON output
+
+- `executed_tests`: count of automated tests that ran.  
+- `skipped_tests`: total skipped (manual + inapplicable + excluded).  
+- `skipped_breakdown`:  
+  - `manual`: number of manual checks (counted as skipped),  
+  - `inapplicable`: not applicable in GovCloud (e.g., root-user checks),  
+  - `excluded`: IDs 32–38 and 44 (by default) skipped before execution.  
+- `missing_implementation`: spreadsheet IDs without a mapped function (coverage gap list).  
+- `excluded_tests`: explicit list of excluded test IDs.  
+- Plus normal `passed`, `failed`, `errors` counters.
+