# راهنمای ساختار و نگارش اسکریپت‌های ممیزی FAVA

> **مخزن:** `Domains/`  
> **مسیر تحویل:** `Auditing/FAVA/` (و در برخی دامنه‌ها root دامنه برای Windows Service)  
> **مخاطب:** تیم Hardening & Resilience — ICT Security Department of Isfahan Municipality  
> **نسخهٔ سند:** 1.0.0  
> **تاریخ:** ۱۴۰۵/۰۴/۰۷ (۲۰۲۶-۰۶-۲۷)  
> **جفت سند:** [`AUDIT_GUIDELINE_SCRATCH.md`](./AUDIT_GUIDELINE_SCRATCH.md)

---

## فهرست مطالب

1. [هدف و تعریف FAVA](#۱-هدف-و-تعریف-fava)
2. [نقشهٔ دامنه‌ها و موجودی canonical](#۲-نقشهٔ-دامنه‌ها-و-موجودی-canonical)
3. [ساختار پوشه‌ای و نام‌گذاری فایل](#۳-ساختار-پوشه‌ای-و-نام‌گذاری-فایل)
4. [الزامات هدر و metadata](#۴-الزامات-هدر-و-metadata)
5. [معماری داخلی اسکریپت](#۵-معماری-داخلی-اسکریپت)
6. [پارامترهای CLI و متغیرهای محیطی](#۶-پارامترهای-cli-و-متغیرهای-محیطی)
7. [پیاده‌سازی کنترل‌های CIS](#۷-پیاده‌سازی-کنترل‌های-cis)
8. [ثبت نتیجه — نقطهٔ واحد](#۸-ثبت-نتیجه--نقطهٔ-واحد)
9. [گزارش‌دهی و Schema JSON](#۹-گزارش‌دهی-و-schema-json)
10. [ماژول‌های Enterprise](#۱۰-ماژول‌های-enterprise)
11. [Hardent Orchestration](#۱۱-hardent-orchestration)
12. [کدهای خروج (Exit Codes)](#۱۲-کدهای-خروج-exit-codes)
13. [مسیرهای خروجی و آرشیو](#۱۳-مسیرهای-خروجی-و-آرشیو)
14. [امنیت اجرا و رفتار پیش‌فرض](#۱۴-امنیت-اجرا-و-رفتار-پیش‌فرض)
15. [الگو به تفکیک دامنه](#۱۵-الگو-به-تفکیک-دامنه)
16. [نسخه‌گذاری، آرشیو و deprecate](#۱۶-نسخه‌گذاری-آرشیو-و-deprecate)
17. [چک‌لیست تحویل FAVA](#۱۷-چک‌لیست-تحویل-fava)
18. [منابع و مراجع داخلی](#۱۸-منابع-و-مراجع-داخلی)

---

## ۱. هدف و تعریف FAVA

**FAVA** مسیر **تحویل عملیاتی (Production Canonical)** اسکریپت‌های ممیزی CIS در مخزن `Domains` است.

| ویژگی | الزام FAVA |
|-------|------------|
| **هدف** | اجرا روی دارایی‌های واقعی سازمان (سرور، ایستگاه، hypervisor، سرویس) |
| **شکل** | اسکریپت **تک‌فایل self-contained** — بدون وابستگی runtime به `_tools/` یا `source` خارجی |
| **تعامل** | **Non-interactive** — بدون `Read-Host`؛ مناسب Ansible/SCCM/cron/SSH |
| **گزارش** | **JSON-First** — TXT/CSV/HTML/Splunk از JSON تولید می‌شوند |
| **benchmark** | هر کنترل به **نسخهٔ مشخص CIS** متصل است |
| **هم‌ترازی** | semantics کنترل و exit code با اسکریپت **Hardening** جفت mirror شود |

**FAVA نیست:**
- محیط آزمایش معماری جدید → [`Scratch`](./AUDIT_GUIDELINE_SCRATCH.md)
- orchestration چندمرحله‌ای playbook → `Auditing/Hardent/` (فقط Ubuntu)

---

## ۲. نقشهٔ دامنه‌ها و موجودی canonical

```
Domains/
├── HyperVisor/Auditing/FAVA/
│   └── Esxi 8/VMware_ESXi_vCenter_Audit-V2.2.1.ps1    ← canonical ESXi 8
├── LinuxDebianOS/Auditing/FAVA/                         ← خالی (Ubuntu در Scratch)
├── LinuxRedhatOS/Auditing/FAVA/
│   └── CIS_Rocky9.x_Audit_v14.1.1.sh                    ← canonical Rocky 9
├── LinuxService/Auditing/FAVA/
│   ├── manifest.yaml
│   ├── lib/benchmark_guard.sh
│   ├── Apache/CIS-v2.1.0/CIS_Linux_Apache_Audit_v3.0.0.sh
│   ├── NGINX/CIS-v2.0.1/CIS_Linux_NGINX_Audit_v3.0.0.sh
│   ├── Docker/CIS-v1.8.0/CIS_Linux_Docker_Audit_v3.0.0.sh
│   ├── PostgreSQL/18/CIS_Linux_PostgreSQL_Audit_v3.0.0.sh
│   └── PostgreSQL/17/CIS_Linux_PostgreSQL17_Audit_v1.0.0.sh
├── WindowsOS/Auditing/FAVA/
│   ├── CIS_Audit_Windows_10-v1.0.0.ps1
│   ├── CIS_Audit_Windows_11-v1.0.0.ps1
│   └── CIS_Audit_Windows_Server_2022-v15.1.1.ps1
├── WindowsService/                                      ← root دامنه (بدون زیرپوشه FAVA)
│   ├── CIS_IIS_10_Benchmark_Audit_V5.3.1.ps1
│   └── CIS_SQL_Server_2022_Audit-v5.0.1.ps1
└── Infrastructure/Auditing/                             ← بدون پیاده‌سازی
```

| دامنه | فایل canonical | Benchmark CIS | Schema JSON | خطوط تقریبی |
|-------|----------------|---------------|-------------|-------------|
| HyperVisor | `VMware_ESXi_vCenter_Audit-V2.2.1.ps1` | ESXi 8 v1.1.0 (133) | 1.0.0 | ~۶۳۵۰ |
| WindowsOS Win10 | `CIS_Audit_Windows_10-v1.0.0.ps1` | Win10 Enterprise v4.0.0 | 1.0.0 unified | ~۱۶۸۰۰ |
| WindowsOS Win11 | `CIS_Audit_Windows_11-v1.0.0.ps1` | Win11 Enterprise v5.0.1 | 1.0.0 unified | ~۱۵۸۰۰ |
| WindowsOS Server | `CIS_Audit_Windows_Server_2022-v15.1.1.ps1` | Server 2022 v5.0.0 (482) | 1.0.0 unified | ~۱۱۰۰۰ |
| WindowsService IIS | `CIS_IIS_10_Benchmark_Audit_V5.3.1.ps1` | IIS 10 v1.2.1 (55) | 2.1.0 | ~۳۱۰۰ |
| WindowsService SQL | `CIS_SQL_Server_2022_Audit-v5.0.1.ps1` | SQL 2022 v1.2.0 | additive | ~۵k+ |
| LinuxRedhatOS | `CIS_Rocky9.x_Audit_v14.1.1.sh` | Rocky 9 v2.0.0 | 1.0.0 | ~۱۳۳۰۰ |
| LinuxService Apache | `CIS_Linux_Apache_Audit_v3.0.0.sh` | Apache 2.4 v2.1.0 | **3.0.0** | ~۴۳۰۰ |
| LinuxService NGINX | `CIS_Linux_NGINX_Audit_v3.0.0.sh` | NGINX v2.0.1 | **3.0.0** | ~۳۰۰۰ |
| LinuxService Docker | `CIS_Linux_Docker_Audit_v3.0.0.sh` | Docker v1.8.0 (118) | **3.0.0** | ~۵۵۰۰ |
| LinuxService PG18 | `CIS_Linux_PostgreSQL_Audit_v3.0.0.sh` | PostgreSQL 18 | **3.0.0** | ~۳۱۰۰ |
| LinuxService PG17 | `CIS_Linux_PostgreSQL17_Audit_v1.0.0.sh` | PostgreSQL 17 | 3.0.0 | fork PG18 |

---

## ۳. ساختار پوشه‌ای و نام‌گذاری فایل

### ۳.۱ قرارداد نام فایل

```
CIS_{Platform}_{Component}_Audit_v{ScriptVersion}.{ps1|sh}
```

| بخش | قانون | مثال |
|-----|-------|------|
| `Platform` | OS یا hypervisor | `Windows_10`, `Rocky9.x`, `Linux_Apache` |
| `Component` | اختیاری برای سرویس | `PostgreSQL`, `Docker` |
| `ScriptVersion` | **نسخهٔ داخلی اسکریپت** (semver) | `v14.1.1`, `v3.0.0` |
| پسوند | `.ps1` (Windows/ESXi) یا `.sh` (Linux) | |

**استثناها:**
- ESXi: `VMware_ESXi_vCenter_Audit-V2.2.1.ps1` (سنت قدیمی — نسخهٔ فایل = نسخهٔ داخلی)
- IIS/SQL: `CIS_IIS_10_Benchmark_Audit_V5.3.1.ps1`

### ۳.۲ Linux Service — محور benchmark

در `LinuxService/Auditing/FAVA/` محور اصلی **نسخهٔ CIS benchmark** است:

```
FAVA/
├── manifest.yaml              ← رجیستری canonical
├── lib/
│   └── benchmark_guard.sh     ← --strict preflight
├── Apache/
│   └── CIS-v2.1.0/            ← محور = CIS v2.1.0
│       ├── CIS_Linux_Apache_Audit_v3.0.0.sh
│       └── _archive/            ← semver قدیمی اسکریپت
└── PostgreSQL/
    └── 18/                    ← محور = major PostgreSQL
        └── CIS_Linux_PostgreSQL_Audit_v3.0.0.sh
```

### ۳.۳ تفکیک نسخهٔ اسکریپت از نسخهٔ benchmark

| مفهوم | محل | مثال |
|-------|-----|------|
| `script_version` | header + JSON `script_version` | `14.1.1` |
| `benchmark_version` | header + JSON `benchmark_version` | `CIS Rocky Linux 9 v2.0.0` |
| نام فایل | `v{ScriptVersion}` | `CIS_Rocky9.x_Audit_v14.1.1.sh` |

**هرگز** نسخهٔ benchmark را به‌جای نسخهٔ اسکریپت در نام فایل نگذارید (مگر سنت ثابت‌شدهٔ دامنه مثل ESXi).

---

## ۴. الزامات هدر و metadata

هر اسکریپت FAVA **باید** با بلوک هدر سازمانی شروع شود.

### ۴.۱ فیلدهای اجباری هدر

```
- نام اسکریپت و مسیر فایل
- سازمان: ICT Security Department of Isfahan Municipality
- تیم: Network Security Team / Hardening & Resilience Unit
- نویسنده: M.A.Fardani - Cybersecurity Specialist
- benchmark_version (نسخهٔ CIS)
- script_version (نسخهٔ داخلی)
- last_updated (تاریخ ISO)
- توضیح یک‌خطی: standalone / non-interactive / privilege requirement
```

### ۴.۲ بلوک‌های اجباری پس از هدر

| بلوک | محتوا |
|------|-------|
| `USAGE` | دستورات نمونه اجرا |
| `OPTIONS` / `PARAMETERS` | تمام پارامترهای CLI |
| `ENVIRONMENT VARIABLES` | متغیرهای محیطی |
| `VERSION HISTORY` / `CHANGELOG` | تاریخچهٔ تغییرات خط‌به‌خط |
| `SCRIPT_EXECUTION_GUIDE` | (PowerShell بزرگ) prerequisites، quick start |

### ۴.۳ قالب changelog

هر ورژن جدید **حداقل** شامل:
- تاریخ (ISO)
- دسته‌بندی تغییر: `fix` | `feat` | `docs` | `refactor`
- تأثیر روی کنترل‌ها (اگر ID مشخص است ذکر شود)
- تغییر schema (اگر breaking)

### ۴.۴ کامنت روی دستورات audit

از نسخه‌های اخیر (مثلاً ESXi V2.2.1، Rocky v14.1.1، Win10 v1.0.0):
- کامنت‌های **لاتین (انگلیسی)** روی بلوک‌های `cis_check_*` / `Check-*` / `LogResult`
- هدف: خوانایی برای automation review و تیم بین‌المللی

---

## ۵. معماری داخلی اسکریپت

### ۵.۱ الگوی کلی (همهٔ دامنه‌ها)

```
┌─────────────────────────────────────────────────────────┐
│ 01 — Header, param(), readonly constants                │
├─────────────────────────────────────────────────────────┤
│ 02 — CLI parse, output path init, colors                │
├─────────────────────────────────────────────────────────┤
│ 03 — Helper functions (timeout, json_escape, logging)   │
├─────────────────────────────────────────────────────────┤
│ 04 — Preflight (root/admin, deps, OS version, service)  │
├─────────────────────────────────────────────────────────┤
│ 05 — Enterprise modules (inventory, CVE, AV, …)       │
├─────────────────────────────────────────────────────────┤
│ 06 — Control catalog (embedded یا associative array)    │
├─────────────────────────────────────────────────────────┤
│ 07 — Check implementations (per chapter / per control)    │
├─────────────────────────────────────────────────────────┤
│ 08 — Main orchestration (profile filter, chapter loop)  │
├─────────────────────────────────────────────────────────┤
│ 09 — Report generation (JSON → TXT/CSV/HTML/Splunk)     │
├─────────────────────────────────────────────────────────┤
│ 10 — Archive, hash manifest, optional GPG/CMS signing   │
├─────────────────────────────────────────────────────────┤
│ 11 — Hardent markers (در صورت پشتیبانی)                 │
├─────────────────────────────────────────────────────────┤
│ 12 — Exit code + optional self-destruct                 │
└─────────────────────────────────────────────────────────┘
```

### ۵.۲ PowerShell — `#region` (Windows OS / ESXi)

```
#region Configuration_and_Globals
#region Helper_Functions
#region Enterprise_Modules
#region Audit_Check_Functions
#region Embedded_Catalogs          ← Windows 10/11
#region Chapter_01 .. Chapter_N
#region Main_Execution
#region Reporting_and_Export
```

**Windows 10/11 FAVA:** کاتالوگ embedded در `#region Embedded_Catalogs` — **بدون JSON خارجی در runtime**.

### ۵.۳ Bash — `#region` (Linux Service v3)

الگوی مرجع: `_shared/bash/cis-audit-framework.sh` (کپی regionها در اسکریپت — **source نکنید در production**)

```
#region 01_HEADER_METADATA
#region 02_CLI_AND_PARAMETERS
#region 04_GLOBAL_STATE
#region 05_FRAMEWORK_FUNCTIONS      ← register_finding, build_audit_json
#region 06_CONTROL_CATALOG           ← declare -A CIS_CONTROLS
#region 07_SERVICE_CONTEXT           ← detection Apache/NGINX/Docker/PG
#region 08_CHECK_IMPLEMENTATIONS
#region 09_ENTERPRISE_MODULES
#region 10_MAIN_EXECUTION
#region 11_REPORT_GENERATION
#region 12_FOOTER_DOCUMENTATION
```

### ۵.۴ Bash — Rocky FAVA (monolithic OS)

```
SECTION 0  — Shebang + shellcheck + header
SECTION 1  — Global constants (readonly)
SECTION 2  — Directory structure + colors
SECTION 3  — Core utilities (json_escape, output_result, timeout)
SECTION 4  — Enterprise modules
SECTION 5  — CIS chapter checks
SECTION 6  — Report generation (JSON-first HTML viewer)
SECTION 7  — Main execution + self-destruct
```

مرجع: `LinuxRedhatOS/Auditing/FAVA/RockyARCHITECTURE.md`

---

## ۶. پارامترهای CLI و متغیرهای محیطی

### ۶.۱ PowerShell — پارامترهای مشترک (الزام برای اسکریپت‌های جدید)

| پارامتر | نوع | پیش‌فرض | توضیح |
|---------|-----|---------|-------|
| `OutputPath` / `BasePath` | string | OS-specific | مسیر پایهٔ گزارش |
| `CISProfile` | enum | `L1` یا `All` | L1/L2/BL/NG/All |
| `NonInteractive` | switch | implicit | بدون prompt |
| `EmitHardentMarkers` | switch | `$true` | مارکرهای orchestration |
| `StrictExit` | switch | `$false` | exit غیرصفر در FAIL |
| `NoColor` | switch | `$false` | خروجی بدون رنگ |
| `NoAutoRun` | switch | `$false` | فقط تعریف توابع (CI) |
| `RetentionDays` | int | `90` | پاک‌سازی آرشیو |

**Windows 10/11 اضافی:**
- `MinPasswordLength`, `MaxDaysWithoutBackup`, `MaxInactivityDays`, `MaxScreenLockTimeout` — آستانه‌های CAM

**ESXi V2.2.1 اضافی:**
- `CISProfile` L1/L2/All
- `TreatWarningAsFail`, `NoAutoRun`
- اتصال اجباری vCenter/ESXi

**IIS V5.3.1:**
- `BasePath`, `Service`, `SplunkUser`
- `SelfDestruct` (پیش‌فرض ON), `KeepScript`
- `NonInteractive`, `Force`

**SQL v5.0.1:**
- `ConfigFile`, `IncludeRemediation`
- `SelfDestruct` پیش‌فرض **OFF** (حفظ شواهد forensic)

### ۶.۲ Bash — پارامترهای مشترک

| پارامتر / ENV | معادل PowerShell |
|---------------|------------------|
| `-o, --output DIR` | `OutputPath` |
| `--profile L1\|L2\|ALL` / `CIS_PROFILE` | `CISProfile` |
| `--no-color` / `NO_COLOR=1` | `NoColor` |
| `--verbose` / `VERBOSE=1` | verbose |
| `--strict` | `benchmark_guard` فعال |
| `--diff FILE` | مقایسه با baseline JSON |
| `--no-html` | بدون HTML |
| `SELF_DESTRUCT=0` | نگه‌داشتن اسکریپت |
| `DEBUG_MODE=1` | لاگ debug |
| `CREATE_ZIP=0` | بدون آرشیو |
| `SIGN_REPORTS=1` | امضای GPG |
| `COMMAND_TIMEOUT=N` | timeout دستورات (Rocky) |

**Rocky FAVA اضافی:**
- `--fast` — فقط CIS، بدون inventory گسترده
- `--parallel` — collectors موازی
- `--remediation` — تولید اسکریپت remediation (opt-in)

### ۶.۳ متغیرهای مسیر خروجی

| لایه | پیش‌فرض |
|------|---------|
| Windows / ESXi | `C:\Windows\Logs\CIS-Audit` |
| Linux OS (Rocky) | `/var/log/cis-audit` |
| Linux Service | `/var/log/cis-audit/{apache\|nginx\|docker\|postgresql}` |

زیرساخت استاندارد:
```
{base}/
├── reports/{hostname}_{ip}_{service}_{timestamp}/
│   ├── *.json
│   ├── *.txt
│   ├── *.csv
│   └── *.html
├── archives/
├── splunk/
└── metadata/
```

---

## ۷. پیاده‌سازی کنترل‌های CIS

### ۷.۱ استخراج از benchmark

برای هر کنترل ثبت کنید:

| فیلد | منبع |
|------|------|
| `id` | شمارهٔ CIS (مثلاً `1.1.2`) |
| `title` | عنوان recommendation |
| `level` | L1 / L2 |
| `chapter` | شماره و نام فصل |
| `assessment_type` | Automated / Manual (طبق تعریف CIS) |
| `expected` | مقدار مورد انتظار |
| `remediation` | دستور یا مرجع remediation |
| `severity` | Critical / High / Medium / Low |
| `mitre` | تکنیک ATT&CK (در صورت نگاشت) |
| `cis_v8` | CIS Controls v8 mapping |

### ۷.۲ کاتالوگ کنترل — Linux Service v3

```bash
declare -A CIS_CONTROLS
# فرمت: title|level|chapter_num|severity|mitre|cisv8|description
CIS_CONTROLS["1.2"]="Ensure the server is not a multi-use system|L1|1|Medium|T1190|4.1|Verify ..."
```

### ۷.۳ کاتالوگ embedded — Windows

کاتالوگ JSON در `#region Embedded_Catalogs`:
- Registry checks از OVAL/XCCDF
- Service checks از XCCDF Chapter 5
- ساخت در build-time از `Domains/_tools/` (نه runtime)

### ۷.۴ Multi-Source Verification (MSV)

برای کنترل‌های حساس، **حداقل دو منبع** تأیید کنید:

| لایه | منابع |
|------|-------|
| Windows | Registry `\Policies\` → SecEdit → non-Policies registry |
| Linux sysctl | runtime (`sysctl -n`) + فایل‌های `/etc/sysctl.d/` |
| SSH | `sshd -T` effective + فایل config |
| Rocky | Runtime + config + CIS cross-check + confidence score |

**Windows Policy Authority (Win10 v4):**

| اولویت | منبع | کاربرد |
|--------|------|--------|
| 1 | Registry `\Policies\` | GPO admin templates |
| 2 | SecEdit export | Account policies, user rights |
| 3 | Machine registry | خارج از GPO hive |

GPResult/RSoP فقط `SecondaryCheck` — **هرگز** PASS/FAIL را override نمی‌کند.

### ۷.۵ Profile filter

قبل از ثبت نتیجه، کنترل را با profile فیلتر کنید:

**PowerShell:** `Test-ProfileIncludesControl -ControlId $id`

**Bash (framework v3):**
```bash
case "${CIS_PROFILE:-ALL}" in
    L1) [[ "$level" == "L2" ]] && return 0 ;;
    L2) [[ "$level" == "L1" ]] && return 0 ;;
esac
```

### ۷.۶ وضعیت‌های مجاز (Status enum)

| Status | معنی | شمارش compliance |
|--------|------|------------------|
| `PASS` | مطابق انتظار | passed |
| `FAIL` | ناقض | failed |
| `WARN` | انحراف جزئی | warn (v3) |
| `SKIP` / `N/A` | غیرقابل اجرا | skip — **خارج از compliance** |
| `MANUAL` | نیاز به بررسی انسانی | manual — **خارج از compliance** |

### ۷.۷ SKIP شرطی — قوانین

SKIP فقط وقتی:
- سرویس/پکیج نصب نیست (و کنترل به آن وابسته است)
- نقش سیستم متفاوت است (DC vs workstation — `role_filter`)
- محیط container/WSL و کنترل نامربوط است
- profile mismatch (بدون ثبت در آمار)

**همیشه** دلیل SKIP را در `actual` یا `skip_reason` بنویسید.

### ۷.۸ جلوگیری از duplicate control ID

**Windows:** `$script:ExecutedCisIds` — inline checks بر embedded catalog اولویت دارند.

**Bash v3:** `register_finding` یک‌بار per ID در loop اصلی.

---

## ۸. ثبت نتیجه — نقطهٔ واحد

**هرگز** مستقیماً به فایل گزارش ننویسید. همیشه از تابع مرکزی استفاده کنید.

### ۸.۱ PowerShell — `LogResult`

```powershell
function LogResult {
    param (
        [string]$check_id,
        [string]$status,      # PASS | FAIL | N/A | MANUAL
        [string]$description,
        [string]$expected,
        [string]$actual,
        [string]$location
    )
    # 1. Profile filter
    # 2. Update counters + chapter stats
    # 3. Get severity + impact
    # 4. Append TXT, CSV, JSON buffer, Splunk
}
```

مسیر: `WindowsOS/Auditing/FAVA/CIS_Audit_Windows_10-v1.0.0.ps1` (~خط 10869)

### ۸.۲ Bash Rocky — `output_result`

```bash
output_result() {
    # id, status, expected, actual, remediation
    # → JSON finding object + TXT row + Splunk NDJSON
}
```

همراه با `json_escape()` برای تمام interpolationهای JSON.

### ۸.۳ Bash Linux Service v3 — `register_finding`

```bash
register_finding() {
    local id="$1" status="$2" actual="${3:-}" expected="${4:-}" remediation="${5:-}"
    local evidence_json="${6:-[]}"
    # normalize_status → update AUDIT_STATS → append to AUDIT_FINDINGS[]
}
```

مرجع: `_shared/bash/cis-audit-framework.sh`

### ۸.۴ فیلد evidence

در v3، آرایهٔ JSON شواهد:
```json
["sshd -T output: permitrootlogin no", "/etc/ssh/sshd_config: PermitRootLogin no"]
```

---

## ۹. گزارش‌دهی و Schema JSON

### ۹.۱ اصل JSON-First

```
اجرای چک‌ها → ساخت JSON کامل → derive TXT/CSV/HTML/Splunk
```

HTML **viewer خالص** — بدون منطق audit:
```html
<script id="audit-data" type="application/json">{...}</script>
```

### ۹.۲ نسخه‌های Schema موجود

| schema_version | دامنه‌ها |
|----------------|----------|
| `1.0.0` | Windows OS unified, Rocky FAVA, ESXi |
| `2.0.0` | Apache legacy (v2.0.x) |
| `2.1.0` | IIS V5.3 |
| `3.0.0` | Linux Service v3 — **هدف یکسان‌سازی** |

مرجع رسمی v3: `_shared/schemas/cis-audit-report-3.0.0.json`

### ۹.۳ ساختار JSON v3.0.0 (الزام Linux Service)

```json
{
  "schema_version": "3.0.0",
  "script_version": "3.0.0",
  "benchmark_version": "CIS Apache HTTP Server 2.4 v2.1.0",
  "benchmark_name": "CIS Apache HTTP Server 2.4 Benchmark",
  "layer": "SERVICE",
  "execution": {
    "started_at": "2026-06-27T10:00:00Z",
    "finished_at": "2026-06-27T10:05:00Z",
    "hostname": "web01",
    "ip_address": "10.0.0.5",
    "duration_seconds": 300,
    "auditor": "...",
    "user": "root"
  },
  "environment": {
    "os_family": "rhel",
    "os_name": "Rocky Linux",
    "service_version": "2.4.62"
  },
  "summary": {
    "total": 100,
    "passed": 85,
    "failed": 10,
    "warn": 0,
    "skip": 3,
    "manual": 2,
    "compliance_percent": 89,
    "weighted_compliance_percent": 82,
    "by_chapter": {},
    "by_severity": {}
  },
  "controls": [
    {
      "id": "1.2",
      "title": "...",
      "chapter": "Planning and Installation",
      "chapter_num": 1,
      "level": "L1",
      "status": "PASS",
      "severity": "Medium",
      "assessment_type": "Automated",
      "expected": "...",
      "actual": "...",
      "remediation": "...",
      "evidence": [],
      "mitre": "T1190",
      "cis_v8_control": "4.1"
    }
  ],
  "diff": null,
  "artifacts": {
    "txt": "/var/log/cis-audit/apache/reports/.../....txt",
    "json": "...",
    "html": "..."
  }
}
```

### ۹.۴ فرمت‌های خروجی اجباری

| فرمت | الزام | توضیح |
|------|-------|-------|
| JSON | **بله** | منبع حقیقت |
| TXT | **بله** | گزارش انسانی + executive summary |
| CSV | توصیه‌شده | import به Excel/SIEM |
| HTML | **بله** | viewer از embedded JSON |
| Splunk/NDJSON | توصیه‌شده | یک خط per control/event |
| ZIP/tar.gz archive | توصیه‌شده | تمام artifacts + hash manifest |

### ۹.۵ نام‌گذاری فایل گزارش

```
{hostname}_{ip}_{service_slug}_{YYYYMMDD_HHMMSS}.{ext}
```

مثال:
```
web01_10.0.0.5_cis_apache_20260627_143022.json
```

### ۹.۶ امتیازدهی (Scoring)

| متریک | فرمول |
|-------|-------|
| `compliance_percent` | `passed / (total - skip - manual) * 100` |
| `weighted_compliance_percent` | وزن: Critical=4, High=3, Medium=2, Low=1 |
| Executive risk score | `100 - weighted_compliance` با سقف per-category (ESXi/Ubuntu) |

### ۹.۷ یکپارچگی گزارش (Windows)

پس از نوشتن TXT، hash append کنید:
```
Report-SHA256: <sha256-hex>
```

HTML: checksum چندفایلی via `Calculate-AllReportHashes`.

### ۹.۸ لاگینگ ساختاریافته

```text
[{ISO8601}] [{LEVEL}] [{ScriptVersion}] [{ControlId}] {Message}
```

سطوح: `INFO`, `PASS`, `FAIL`, `WARN`, `MANUAL`, `ERROR`

**Splunk — فیلدهای اجباری:**
`control_id`, `status`, `benchmark_version`, `schema_version`, `host`, `layer`

---

## ۱۰. ماژول‌های Enterprise

فراتر از checklist CIS — **الزام در اسکریپت‌های OS و hypervisor**، **توصیه‌شده در Service**.

### ۱۰.۱ ماژول‌های استاندارد

| ماژول | تابع نمونه | خروجی JSON |
|-------|------------|------------|
| Antivirus detection | `audit_antivirus_comprehensive` | per-vendor cards |
| Patch/CVE management | `audit_security_patches_cve` | RHSA/CVE list |
| Network exposure | `audit_network_exposure` | open ports + risk |
| Persistence mechanisms | `audit_persistence_mechanisms` | cron/timers/services |
| Repository security | `audit_repository_security` | HTTPS/GPG status |
| Defensive tools | `Get-DefensiveToolsStatus` | Fail2Ban, AIDE, CrowdSec |
| User/session inventory | `Get-DetailedUserAudit` | last login, sessions |
| Resource monitoring | `Get-ResourceSnapshot` | CPU/RAM before/after |
| Virtualization detection | `Get-VirtualizationPlatform` | VM/hypervisor type |
| SELinux/AppArmor deep | `audit_selinux_deep` | MAC posture |

### ۱۰.۲ محل در JSON

Windows unified schema:
```json
"system_inventory": {
  "os": {},
  "firewall": {},
  "security_agents": {},
  "patch_management": {},
  "persistence": {}
}
```

Linux Service v3: بلوک `enterprise_modules` (در صورت پیاده‌سازی) یا enrichment در `environment`.

### ۱۰.۳ Disaster Recovery (ESXi)

هر کنترل automated: capture **مقدار فعلی** برای بازگردانی پس از hardening:
```json
"disaster_recovery": {
  "control_id": "3.1.1",
  "current_value": "...",
  "setting_path": "..."
}
```

---

## ۱۱. Hardent Orchestration

### ۱۱.۱ مارکر استاندارد (الزام برای اسکریپت‌های جدید Windows/ESXi)

```
###HARDENT_TASK_OUTPUT_BEGIN###
[Task Name: CIS Audit Summary]
[CIS Control: ALL]
... structured output ...
{Result:True|False}
###HARDENT_TASK_OUTPUT_END###
```

**PowerShell:**
```powershell
function Emit-HardentTaskOutput { ... }
# فعال با -EmitHardentMarkers (پیش‌فرض $true)
```

**پشتیبانی فعلی:**
- Windows 10/11 FAVA ✓
- ESXi V2.2.1 ✓
- Windows Server 2022 — **در انتظار** ✗
- IIS/SQL — **در انتظار** ✗
- Linux Service v3 — **در انتظار** ✗

### ۱۱.۲ پارامتر

```powershell
[switch]$EmitHardentMarkers = $true
```

برای CI خاموش کنید: `-EmitHardentMarkers:$false`

---

## ۱۲. کدهای خروج (Exit Codes)

### ۱۲.۱ Linux Service v3 (استاندارد `_shared`)

| کد | ثابت | معنی |
|----|------|------|
| 0 | `EXIT_SUCCESS` | همهٔ automatedها PASS |
| 1 | `EXIT_ERROR_GENERAL` | خطای عمومی |
| 2 | `EXIT_ERROR_SERVICE_NOT_FOUND` | سرویس نصب نیست |
| 3 | `EXIT_ERROR_PRIVILEGE` | نیاز به root |
| 4 | `EXIT_ERROR_CONFIG_NOT_FOUND` | فایل config یافت نشد |
| 5 | `EXIT_ERROR_DEPENDENCY` | وابستگی گم‌شده |
| 10 | `EXIT_COMPLIANCE_FAIL` | یک یا چند FAIL |
| 11 | `EXIT_COMPLIANCE_PARTIAL` | WARN/MANUAL باقی مانده |

```bash
framework_exit_code() {
    [[ ${AUDIT_STATS[failed]} -gt 0 ]] && echo 10
    [[ ${AUDIT_STATS[warn]} -gt 0 || ${AUDIT_STATS[manual]} -gt 0 ]] && echo 11
    echo 0
}
```

### ۱۲.۲ IIS V5.3.1

| کد | معنی |
|----|------|
| 0 | All controls passed |
| 1 | Controls failed |
| 2 | Runtime error |
| 3 | IIS not installed |
| 4 | Invalid configuration |
| 5 | Permission denied |
| 6 | Unsupported platform |
| 7 | User aborted |

### ۱۲.۳ Windows — StrictExit

```powershell
if ($StrictExit -and $script:FAILED_COUNT -gt 0) { exit 1 }
```

### ۱۲.۴ Rocky / Ubuntu

| کد | معنی |
|----|------|
| 0 | Success |
| 1 | Critical failure |
| 2 | Partial / error |
| 3 | Not root |

---

## ۱۳. مسیرهای خروجی و آرشیو

### ۱۳.۱ ساختار دایرکتوری گزارش

```
{BASE_PATH}/
└── {service_slug}/
    ├── reports/
    │   └── {hostname}_{ip}_{slug}_{timestamp}/
    │       ├── {basename}.json
    │       ├── {basename}.txt
    │       ├── {basename}.csv
    │       ├── {basename}.html
    │       └── {basename}.splunk.log
    ├── archives/
    │   └── {basename}.tar.gz   (یا .zip در Windows)
    ├── splunk/
    └── metadata/
        └── hashes.json
```

### ۱۳.۲ Hash manifest

```json
{
  "algorithm": "SHA256",
  "files": {
    "report.json": "abc123...",
    "report.html": "def456..."
  },
  "generated_at": "2026-06-27T10:05:00Z"
}
```

SHA256 **اجباری** — MD5 فقط legacy (deprecated).

### ۱۳.۳ Retention

پارامتر `RetentionDays` (پیش‌فرض 90): پاک‌سازی archives قدیمی‌تر در پایان اجرا.

---

## ۱۴. امنیت اجرا و رفتار پیش‌فرض

### ۱۴.۱ سطح دسترسی

| پلتفرم | الزام |
|--------|-------|
| Windows | `#Requires -RunAsAdministrator` + runtime assert |
| Linux OS/Service | `EUID=0` — exit `EXIT_ERROR_PRIVILEGE` |
| ESXi | PowerCLI + credentials vCenter/ESXi |

### ۴.۲ Non-Interactive

- بدون `Read-Host`
- `-NonInteractive` در PowerShell
- `DEBIAN_FRONTEND=noninteractive` در bash (در صورت apt)

### ۱۴.۳ Timeout Protection

```bash
run_with_timeout() { ... }   # Rocky
```
```powershell
Invoke-WithTimeout { ... }  # Windows
```

پیش‌فرض Rocky: `COMMAND_TIMEOUT=60`

### ۴.۴ Self-Destruct

| اسکریپت | پیش‌فرض | override |
|---------|---------|----------|
| Windows 10/11 | ON | `$env:SELF_DESTRUCT = "0"` |
| IIS V5.3.1 | ON | `-SelfDestruct:$false` / `-KeepScript` |
| SQL v5.0.1 | **OFF** | — |
| Rocky FAVA | env-controlled | `SELF_DESTRUCT=0` |
| Linux Service v3 | OFF | — |

### ۴.۵ Redaction

- License key ESXi: redact در گزارش
- رمزعبور: هرگز در `actual`/`evidence`
- PII: محدود به نیاز audit

### ۱۴.۶ `benchmark_guard` (Linux Service)

```bash
# lib/benchmark_guard.sh
cis_benchmark_guard   # با --strict → exit در mismatch نسخه
```

مثال: PostgreSQL major 17 روی host ولی benchmark 18 → WARN یا FAIL در strict mode.

---

## ۱۵. الگو به تفکیک دامنه

### ۱۵.۱ HyperVisor — ESXi V2.2.1

- PowerCLI اجباری؛ اتصال vCenter/ESXi در preflight
- کاتالوگ مرکزی ۱۳۳ کنترل CIS ESXi 8 v1.1.0
- `CISProfile` L1/L2/All
- `AssessmentStatus` per CIS Automated/Manual
- Executive Risk Engine (۸ دسته)
- Disaster Recovery capture
- خروجی: TXT/CSV/JSON/HTML/Splunk + CIS control matrix CSV

### ۱۵.۲ WindowsOS

**Win10/11 FAVA (monolith v1.0.0):**
- Embedded OVAL registry + service catalogs
- `Get-EffectivePolicyValue` authority model
- CAM IG1 — ۱۴ کنترل supplemental (Chapter 0)
- Chapters 1–19 inline + supplemental OVAL catalog
- `Emit-HardentTaskOutput`

**Server 2022 v15.1.1:**
- ۴۸۲ کنترل CIS v5.0.0
- Multi-source Registry+GPO+WMI
- **فاقد** Hardent markers (بدهی فنی)

### ۱۵.۳ WindowsService

**IIS:** مرجع schema 2.1.0 — `Test-AuditJsonSchema`, OWASP 2025, attack-chain risk

**SQL:** data-driven dispatch engine, STIG enrichment, `-IncludeRemediation` opt-in

### ۱۵.۴ LinuxRedhatOS — Rocky v14.1.1

- `output_result()` + `json_escape()` JSON-first
- `--fast` / `--parallel` performance modes
- HTML viewer از embedded JSON
- DNF/CVE، SELinux deep، auditd dashboard
- Splunk + remediation generator (`--remediation`)

### ۱۵.۵ LinuxService v3

- `register_finding()` از framework v3
- `manifest.yaml` رجیستری canonical
- `--help` → `show_controls_help()` لیست کاتالوگ
- `--diff` → regression detection vs baseline JSON
- `audit_qa.sh` برای QA قبل از تحویل

---

## ۱۶. نسخه‌گذاری، آرشیو و deprecate

### ۱۶.۱ bump نسخه

| نوع تغییر | bump |
|-----------|------|
| fix کنترل (بدون schema break) | PATCH: `14.1.1` → `14.1.2` |
| کنترل جدید / enterprise module | MINOR: `14.1.x` → `14.2.0` |
| schema breaking / معماری جدید | MAJOR: `14.x` → `15.0.0` |

### ۱۶.۲ آرشیو نسخهٔ قبلی

```
FAVA/{Service}/CIS-v{X}/_archive/CIS_Linux_{Service}_Audit_v{old}.sh
```

همراه با `README.md`:
```markdown
# DEPRECATED
Superseded by: ../CIS_Linux_Apache_Audit_v3.0.0.sh
Archived: 2026-06-07
Reason: schema 3.0.0 migration
```

### ۱۶.۳ promote از Scratch

فقط پس از تکمیل [چک‌لیست Scratch → FAVA](./AUDIT_GUIDELINE_SCRATCH.md#۹-چک‌لیست-promote-scratch--fava).

---

## ۱۷. چک‌لیست تحویل FAVA

### ۱۷.۱ ساختار و metadata

- [ ] نام فایل مطابق قرارداد `CIS_{Platform}_Audit_v{X}.{ext}`
- [ ] `script_version` در هدر = نسخهٔ فایل
- [ ] `benchmark_version` صحیح و مطابق PDF/XCCDF
- [ ] CHANGELOG ورژن جدید کامل
- [ ] USAGE + OPTIONS + ENV documented
- [ ] کامنت لاتین روی بلوک‌های audit

### ۱۷.۲ اجرا

- [ ] Non-interactive — بدون prompt
- [ ] Privilege check (root/admin) با exit code صحیح
- [ ] Preflight: OS version, service presence, dependencies
- [ ] Timeout روی دستورات کند
- [ ] `-NoAutoRun` / `--help` کار می‌کند

### ۱۷.۳ کنترل‌ها

- [ ] تمام control IDهای benchmark پوشش داده شده
- [ ] Profile filter (L1/L2) صحیح
- [ ] Automated/Manual مطابق CIS
- [ ] MSV برای کنترل‌های حساس
- [ ] SKIP با دلیل معتبر
- [ ] بدون duplicate ID در گزارش نهایی

### ۱۷.۴ گزارش

- [ ] JSON معتبر و کامل
- [ ] `schema_version` صحیح
- [ ] `compliance_percent` + `weighted_compliance_percent`
- [ ] HTML viewer از embedded JSON (بدون logic audit)
- [ ] TXT + CSV تولید می‌شود
- [ ] Splunk log با فیلدهای استاندارد
- [ ] نام فایل: hostname_ip_service_timestamp
- [ ] Archive + SHA256 manifest

### ۱۷.۵ Enterprise (در صورت applicable)

- [ ] Inventory modules اجرا و در JSON
- [ ] MITRE mapping روی کنترل‌های کلیدی
- [ ] Executive risk score (OS/hypervisor)

### ۱۷.۶ Automation

- [ ] Exit codes documented و تست‌شده
- [ ] `EmitHardentMarkers` (Windows/ESXi)
- [ ] `StrictExit` کار می‌کند
- [ ] `manifest.yaml` به‌روز (Linux Service)

### ۱۷.۷ امنیت

- [ ] بدون secret در گزارش
- [ ] Self-destruct behavior documented
- [ ] `benchmark_guard --strict` (Linux Service)

---

## ۱۸. منابع و مراجع داخلی

| سند / فایل | مسیر |
|------------|------|
| نقشه راه یکسان‌سازی | `Domains/AUDIT_UNIFICATION_ROADMAP.md` |
| Framework bash v3 | `Domains/_shared/bash/cis-audit-framework.sh` |
| Schema JSON v3 | `Domains/_shared/schemas/cis-audit-report-3.0.0.json` |
| manifest Linux Service | `LinuxService/Auditing/FAVA/manifest.yaml` |
| benchmark guard | `LinuxService/Auditing/FAVA/lib/benchmark_guard.sh` |
| Win10 architecture | `WindowsOS/Documents/Win10_AUDIT_ARCHITECTURE.md` |
| Win11 architecture | `WindowsOS/Documents/Win11_AUDIT_ARCHITECTURE.md` |
| Rocky architecture | `LinuxRedhatOS/Auditing/FAVA/RockyARCHITECTURE.md` |
| PostgreSQL guide | `LinuxService/Documents/PostgreSQL-Security-Audit-Guide.md` |
| راهنمای Scratch | `Documents/AUDIT_GUIDELINE_SCRATCH.md` |

---

*این سند مرجع ساختاری برای **تمام** نگارش‌های آینده در مسیر FAVA است. تغییرات معماری عمومی ابتدا در Scratch آزمایش و سپس به این سند و FAVA منعکس می‌شوند.*