✨ Overview

WinSecAudit v2 audits Windows 10/11 machines for common security misconfigurations, assigns a weighted risk score, enriches every finding with live CVE threat intelligence, and produces boardroom-ready reports in four formats. It's built as a plugin system — every check is a self-contained class auto-discovered at runtime, so extending the suite requires zero wiring.

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  39 CHECKS   │ ──▶ │   SCORING    │ ──▶ │  THREAT INTEL│ ──▶ │   REPORTS    │
│ (PowerShell) │     │  (weighted)  │     │ NVD+EPSS+KEV │     │ PDF/DOCX/CSV │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘

📚 Table of Contents

• 🚀 Quick Start
• ⚙️ Installation
• 🧰 Commands
• 🔍 Security Checks
• 🎛️ Profiles
• 📊 Scoring & Grading
• 🌐 Threat Intelligence
• 📄 Output Formats
• 🧪 Testing
• ⚠️ Known Limitations
• 📂 Project Structure
• 🤝 Contributing

🚀 Quick Start

# 1. Clone & install
git clone https://github.com/KavyaJain321/winsecaudit-v2.git
cd winsecaudit-v2
pip install -r requirements.txt

# 2. Run your first audit (open an elevated PowerShell first)
python winsecaudit.py scan

# 3. Export a beautiful PDF report
python winsecaudit.py report --format pdf

💡 Tip: The SQLite database and all caches are created automatically on first run inside data/. No setup scripts, no migrations.

⚙️ Installation

Requirements

Setup

git clone https://github.com/KavyaJain321/winsecaudit-v2.git
cd winsecaudit-v2
pip install -r requirements.txt

Optional

# Set your NVD API key to bump rate limit from 5 → 50 req/s
$env:NVD_API_KEY = "your-key-here"     # PowerShell
export NVD_API_KEY="your-key-here"     # Bash

🧰 Commands

WinSecAudit ships with 6 Typer-powered commands. Run python winsecaudit.py --help to see them all.

scan — Run the full audit

python winsecaudit.py scan [OPTIONS]

report — Generate a formatted report

python winsecaudit.py report [OPTIONS]

list — List saved scans

python winsecaudit.py list [--machine HOSTNAME] [--limit N]

drift — Compare two scans

python winsecaudit.py drift [--scan-a ID] [--scan-b ID]

Defaults to comparing the two most recent scans. Under the hood, drift emulates a FULL OUTER JOIN with two LEFT JOINs + UNION ALL (SQLite doesn't support full outer joins natively).

fix — List or apply remediations

python winsecaudit.py fix --list                      # show all remediable checks
python winsecaudit.py fix --check "Check Name"        # apply the fix

dashboard — Launch the FastAPI read-only dashboard

python winsecaudit.py dashboard
# Opens http://localhost:8080

🔍 Security Checks

39 checks across 8 categories, all auto-discovered via CheckRegistry.discover():

Each check emits an immutable CheckResult with CVE IDs, MITRE ATT&CK technique, CIS benchmark ID, severity, weight, and a ready-to-run remediation command.

🎛️ Profiles

Profiles live in profiles/*.yaml and control three levers:

Bundled Profiles

📊 Scoring & Grading

score = (earned_weight / max_possible_weight) × 100

Edge case: if every check is skipped → score = 100.0

Grade Bands

🌐 Threat Intelligence

Every CVE associated with a failed check is enriched from three sources:

Caches live in data/cve_map.json and data/cisa_kev_cache.json. Enrichment degrades gracefully — a 429 from NVD does not crash the scan; affected CVEs simply ship without TI metadata.

📄 Output Formats

🧪 Testing

python tests/smoke_test.py

10 standalone tests cover: imports, check discovery, profile loading, scoring math, grade thresholds, DB round-trip, profile relaxation, TI offline cache, CLI entry point, and the full pipeline. No pytest required — exits 0 on success.

WinSecAudit v2 — Smoke Tests
========================================
  PASS  01 Import health
  PASS  02 Check discovery
  PASS  03 Profile loading
  PASS  04 Scoring correctness
  PASS  05 Grade thresholds
  PASS  06 DB round-trip
  PASS  07 Profile relaxation
  PASS  08 TI cache offline-safe
  PASS  09 CLI entry point
  PASS  10 Full pipeline
========================================
Results: 10/10 passed

⚠️ Known Limitations

• 🔒 Elevation required — Most PowerShell checks call secedit, auditpol, or protected registry paths. Run from an elevated terminal.
• 🪟 Windows-only checks — All checks are PowerShell/Windows-specific. The DB, scoring engine, and exporters are cross-platform.
• 📉 NVD rate limit — Without an API key, NVD allows 5 req/s. Set NVD_API_KEY to raise this to 50 req/s.
• 📥 CISA KEV download — First scan of the day downloads ~5 MB from cisa.gov. Subsequent scans within 24 h use the cache.

📂 Project Structure

winsecaudit-v2/
├── winsecaudit.py          # Entry point — forces UTF-8 stdout/stderr on Windows
├── requirements.txt
│
├── checks/                 # 🔍 Security check plugins (auto-discovered)
│   ├── base.py             #    BaseCheck, CheckResult, CheckRegistry
│   ├── auth/               #    Authentication (6)
│   ├── access/             #    Access control (5)
│   ├── network/            #    Network (6)
│   ├── services/           #    Services (5)
│   ├── kernel/             #    Kernel/hardware (4)
│   ├── system/             #    System config (5)
│   ├── logging/            #    Audit & logging (4)
│   └── credentials/        #    Credential protection (4)
│
├── engine/                 # ⚙️ Core orchestration
│   ├── runner.py           #    Parallel check execution
│   ├── scorer.py           #    Weighted scoring
│   ├── comparator.py       #    Profile loading & adjustment
│   ├── risk.py             #    Grade assignment & priority
│   └── threat_intel.py     #    NVD / EPSS / CISA KEV pipeline
│
├── db/                     # 💾 Persistence
│   ├── database.py         #    SQLAlchemy Core layer
│   └── schema.sql          #    Reference DDL
│
├── cli/                    # 🧰 CLI surface
│   ├── main.py             #    Typer commands
│   └── output.py           #    Rich rendering
│
├── dashboard/              # 🌐 FastAPI read-only dashboard
│   ├── app.py
│   ├── models.py
│   └── static/index.html
│
├── exporters/              # 📄 Report generators
│   ├── pdf.py              #    reportlab Platypus
│   ├── docx_export.py      #    python-docx
│   └── csv_export.py       #    csv module
│
├── profiles/               # 🎛️ YAML profiles
│   ├── basic.yaml
│   └── hardened.yaml
│
├── data/                   # 🗃️ Runtime data (gitignored)
└── tests/
    └── smoke_test.py       # ✅ 10 standalone smoke tests

🤝 Contributing

Adding a new check is a three-step affair:

1. Create a file under the appropriate checks/<category>/ directory.
2. Subclass BaseCheck and set the class attributes (name, category, weight, severity, cve_ids, mitre_technique, cis_id, remediation_cmd, remediation_supported).
3. Implement run() -> CheckResult. That's it — CheckRegistry.discover() picks it up on the next scan.

from checks.base import BaseCheck, CheckResult, CheckStatus, Severity, run_powershell

class MyNewCheck(BaseCheck):
    name = "My New Check"
    category = "System"
    weight = 5
    severity = Severity.HIGH
    remediation_cmd = "Set-ItemProperty ..."
    remediation_supported = True

    def run(self) -> CheckResult:
        value = run_powershell("Get-Something")
        return CheckResult(
            check_name=self.name,
            category=self.category,
            status=CheckStatus.PASS if value == "expected" else CheckStatus.FAIL,
            system_value=value,
            expected_value="expected",
            severity=self.severity,
            weight=self.weight,
            cve_ids=(),
            mitre_technique="",
            cis_id="",
            remediation_cmd=self.remediation_cmd,
            remediation_supported=self.remediation_supported,
        )