diff --git a/CHANGELOG.md b/CHANGELOG.md index 6e5f598..96dcc47 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -28,6 +28,19 @@ ## [Unreleased] +### Documentation + +- Lead the README and documentation site with release downloads, edition + selection, and a first saved baseline without CLI, admin access, or Azure. + Keep advanced packaging and contributor references available without making + them prerequisites; clarify unsigned-download risks and report terminology. +- Require the **Microsoft.OSConfig PowerShell module 1.4.10+** on the machine + creating Machine Configuration packages, separately from PowerShell 7 and + GuestConfiguration. Centralize Audit-first packaging, reject missing/older + modules before MOF version resolution, preserve exact-version binding and + immutable ZIP/hash guidance, and label the 1.4.3 patch helper historical. + This does not claim that all upstream baseline issues are resolved. + ### Security - Update DOMPurify to 3.4.16, Axios to 1.20.0, ip-address to 10.7.2, diff --git a/INSTALL.md b/INSTALL.md index 804af2c..7dade40 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,5 +1,12 @@ # Installing ConfigForge and the OSConfig CLI +Start by installing the desktop app. **Stop after the first-baseline +walkthrough if you only want to author or review baselines.** The CLI and +Machine Configuration packaging tools are optional, separate workflows. + +> ConfigForge is experimental, community-maintained, and not an officially +> supported Microsoft product. It is not intended for production use. + ConfigForge has two editions: - **Full edition** — Windows + Linux from the `main` branch. Authoring works without the CLI; Deploy, Audit, and Revert require `oscfg`. @@ -20,6 +27,53 @@ work without `oscfg`. This is Editor mode, and it is the default on first launch. In the Full edition, the Welcome dialog and footer health pill surface CLI state so you can switch to device operations after installing the CLI. +## Install the desktop app + +1. Open the [ConfigForge releases](https://github.com/Azure/ConfigForge/releases) + page. Choose **Full v0.3.103** for Windows/Linux x64 or + **Author mac-v0.3.101-author.1** for Apple Silicon macOS. Expand **Assets** + and download the appropriate installer/archive and published checksum + manifest. Source-code archives are for contributors, not app installers. +2. Compare the download's SHA-256 with its entry in the release checksum + manifest. For example, in PowerShell, replace the filename below with your + downloaded asset: + + ```powershell + Get-FileHash -LiteralPath '.\downloaded-installer.exe' -Algorithm SHA256 + ``` + + On Linux use `sha256sum `; on macOS use + `shasum -a 256 `. Stop if the checksum differs. +3. Follow your organization's software policy before installing an unsigned + app. Windows users can run the installer or extract the portable archive. + Linux users should choose the package format for their distribution, or + extract the portable archive. For macOS, see [Author edition](#macos-author-edition). +4. Open ConfigForge without elevation for authoring. If the Welcome dialog + appears, choose **Author baselines anywhere**, then follow + [Your first baseline](./docs/src/quick-start/first-manifest.md). + +**Unsigned-download warning:** these artifacts have no code-signing identity; +macOS builds are also not notarized. A checksum confirms integrity relative to +the published file, not that the app is safe. Do not disable operating-system +security protections globally. If Windows SmartScreen blocks the installer, +review its source and checksum and obtain approval before using any per-file +override. On managed devices, ask your administrator rather than bypassing +policy. Building from reviewed source is an alternative, not a safety guarantee. + +## Optional local device operations + +The following CLI setup is only for the Full edition's **Deploy**, device +**Audit**, and **Revert**. Test on a disposable machine that matches the +baseline's target OS. Registration alone does not apply a baseline. + +For **creating Azure Machine Configuration packages**, use the separate +[packaging guide](./docs/src/user-guide/machine-configuration.md): it requires +PowerShell 7, the GuestConfiguration toolkit, and the **Microsoft.OSConfig +PowerShell module 1.4.10 or later** on the packaging machine. +`Install-Module -Name Microsoft.OSConfig -MinimumVersion 1.4.10` installs that +module; `winget install Microsoft.OSConfig` below installs the **CLI**, not +the PowerShell packaging prerequisite. + --- ## Upstream source @@ -114,9 +168,10 @@ the app into Deploy-capable mode without restarting. 4. ConfigForge will auto-detect the binary on next launch (or click Recheck in the app). -Deploy/Audit operations require root (or sudo) for the same reasons they do -on Windows. The in-app health pill will surface "admin required" when -unprivileged. +Deploy/Revert require root or equivalent privileges. Audit permissions depend +on the resource being read; protected settings may also require elevation. +An unread setting is not evidence of compliance. This is separate from +Machine Configuration package testing, which requires a privileged session. --- @@ -132,19 +187,23 @@ prerelease on the [Azure/ConfigForge releases](https://github.com/Azure/ConfigForge/releases) page. Users can also build the tagged source from the repository. -The app is unsigned and not notarized. Copy **ConfigForge Author.app** to -`/Applications`, then clear the browser-added quarantine attribute once: +The app is unsigned and not notarized. Verify its release checksum before +opening the DMG and copying **ConfigForge Author.app** to `/Applications`. +Gatekeeper may block it. Prefer your organization's approved per-app process +(for example, **System Settings → Privacy & Security → Open Anyway**, when +available and permitted). -```bash -xattr -cr "/Applications/ConfigForge Author.app" -``` - -If that command reports a permission error, use: +Only if you have verified the download, accept the unsigned-app risk, and +your policy permits it, remove the quarantine attribute from this app alone: ```bash -sudo xattr -rd com.apple.quarantine "/Applications/ConfigForge Author.app" +xattr -rd com.apple.quarantine "/Applications/ConfigForge Author.app" ``` +This removes a Gatekeeper quarantine check; it does not sign or notarize the +app. Do not clear all attributes, disable Gatekeeper globally, or escalate a +permission failure just to bypass policy. Ask your administrator if blocked. + The Author edition supports baseline authoring, validation, import, Diff, Benchmark Mapping, history, rationale, and Audit Pack PDF/Markdown export. It does not expose device Deploy, Audit, Enforce, Revert, elevation, device diff --git a/README.md b/README.md index 3e929a1..6f78593 100644 --- a/README.md +++ b/README.md @@ -1,298 +1,226 @@ # ConfigForge -> ⚠️ **Disclaimer:** This tool is provided as-is without Microsoft support. This is an experimental project to help customers accelerate their use of security baselines while helping IT architects validate desired configurations. ConfigForge is **not** an officially supported Microsoft product. **Not intended for production use** — for experimentation, learning, and community contributions only. **Use at your own risk.** - -**Cross-platform OSConfig security baseline authoring desktop app.** Electron 42 + React 18 + FluentUI v9 + Vite. Windows + Linux use the full build from `main`; macOS uses the author-only flavor from `mac-author-build`. Author, validate, compare, and export on every supported edition. Device deploy and audit are Full-edition features that use the native [`oscfg`](https://github.com/microsoft/osconfig/tree/main/docs/cli) CLI on Windows or Linux. - -> The `oscfg` binary is **not** bundled. Editor, Microsoft Baselines, Diff, Benchmark Mapping, and Audit Pack PDF/Markdown export all work without it, including in the macOS Author edition. Deploy, device Audit, and Revert require the Full edition and the CLI. See [`INSTALL.md`](./INSTALL.md) for platform-by-platform install steps. - -The current Windows/Linux release is `v0.3.103`. The current macOS Author -release is `mac-v0.3.101-author.1`; both are published as prereleases. The -package versions are `0.3.103` for the Full edition and `0.3.101-author.1` -for the macOS Author edition. - -## Export to Azure Machine Configuration - -Use this supported path to deploy a ConfigForge baseline through Azure Policy: - -`ConfigForge baseline → MOF → resolved MOF → Machine Configuration ZIP → Azure Storage → generated policy JSON → policy definition → assignment` - -1. Open **Baseline Detail**, select **Export**, and save the baseline as - **MOF (`.mof`)**. -2. On a PowerShell 7 packaging machine, install `GuestConfiguration`, - `Microsoft.OSConfig`, and the required `Az` modules. -3. Resolve the exported MOF's portable `ModuleVersion = "0.0.0"` placeholder - to the newest `Microsoft.OSConfig` version installed on that machine: - - ```powershell - $Module = Get-Module -ListAvailable Microsoft.OSConfig | - Sort-Object Version -Descending | - Select-Object -First 1 - (Get-Content .\Baseline.mof -Raw).Replace( - 'ModuleVersion = "0.0.0";', - "ModuleVersion = `"$($Module.Version)`";" - ) | Set-Content .\Baseline.resolved.mof -Encoding utf8 - ``` - -4. Create and test an Audit package: - - ```powershell - $Package = New-GuestConfigurationPackage ` - -Name ConfigForgeBaseline_1_0_0 ` - -Configuration .\Baseline.resolved.mof ` - -Type Audit ` - -Path .\package ` - -Force - - Get-GuestConfigurationPackageComplianceStatus -Path $Package.Path - ``` - -5. Upload the ZIP with `Set-AzStorageBlobContent`, create a read-only package - URI, then run `New-GuestConfigurationPolicy -Mode Audit`. -6. Publish the returned JSON with `New-AzPolicyDefinition` and assign it with - `New-AzPolicyAssignment`. Azure VMs also need the built-in Machine - Configuration prerequisite initiative. - -Use a unique package name/version and do not modify the ZIP after generating -the policy because the definition includes its content hash. Audit is the -documented default while Microsoft.OSConfig 1.3.11 retains its upstream -remediation serialization defect. +**Create, compare, and share OSConfig security baselines—before changing a device.** +Start with a Microsoft baseline or your own settings, review them visually, and +export a baseline or review report. No CLI, administrator access, or Azure +subscription is needed for authoring. + +> **Experimental, community-maintained, and provided as-is.** ConfigForge is +> not an officially supported Microsoft product and is **not intended for +> production use**. Use it for learning and evaluation at your own risk. +> [Support boundaries](./SUPPORT.md) + +**[Download releases](https://github.com/Azure/ConfigForge/releases)** · +**[Documentation](https://azure.github.io/ConfigForge/)** · +**[First baseline walkthrough](./docs/src/quick-start/first-manifest.md)** + +## Download the right edition + +| Your computer | Download | What you can do | +| --- | --- | --- | +| Windows or Linux (x64) | **Full** — [v0.3.103](https://github.com/Azure/ConfigForge/releases/tag/v0.3.103) | Author, validate, compare, and export. Optional local Deploy, Audit, and Revert require the separately installed `oscfg` CLI. | +| macOS on Apple Silicon (M1 or later) | **Author** — [mac-v0.3.101-author.1](https://github.com/Azure/ConfigForge/releases/tag/mac-v0.3.101-author.1) | The same authoring and review workflows, including Audit Pack export; no device operations. ARM64 only—not Intel or universal. | + +Both releases are **prereleases**. Full-edition package versions are `0.3.103`; +the macOS Author package version is `0.3.101-author.1`. + +**Downloads are unsigned; macOS builds are also not notarized.** Download only +from this repository's release page, compare the asset's SHA-256 with the +published checksum, and follow your organization's software policy. +Checksums check file integrity, not publisher identity or safety. Do not +disable SmartScreen or Gatekeeper globally. See [installation and download +warnings](./INSTALL.md#install-the-desktop-app) before opening an installer. +Building from reviewed source is another option, not a safety guarantee. + +## Create your first baseline + +A **baseline** is a set of desired settings. A **manifest** is the YAML or JSON +document that describes those settings. **Register** means save a baseline to +your ConfigForge workspace—not apply it to a device. + +1. Install and open the edition for your computer. If the Welcome dialog + appears, choose **Author baselines anywhere**. +2. Open **Microsoft Baselines**, choose a baseline to explore, and select + **Use as Template**. +3. Give your copy a unique name, review its settings in **Visual** or **Code**, + and select **Register Baseline**. +4. Open it from **My Baselines** and choose **Export → YAML** to save a portable + copy. + +**Success:** your baseline appears in My Baselines and you have an exported +`.osc.yaml` file. You have not deployed or audited anything. A Full-edition +**Editor mode, CLI not installed** indicator is expected and does not block +this workflow. + +For screenshots, alternative starting points, and a small YAML example, follow +[Your first baseline](./docs/src/quick-start/first-manifest.md). + +![Microsoft Baselines: choose a template to create your own baseline](./docs/images/screenshots/library.png) + +## Choose what to do next + +| Your goal | Guide | Extra requirements | +| --- | --- | --- | +| Edit settings or import YAML, JSON, CSV, or XLSX | [Baseline editor](./docs/src/user-guide/manifest-editor.md) | None for authoring | +| Compare two baselines or a matrix of up to ten | [Diff](./docs/src/user-guide/matrix-diff.md) | None | +| Map settings to a benchmark | [Benchmark Mapping](./docs/src/user-guide/cis-compliance.md) | Your own legally licensed benchmark data; CIS data is not bundled | +| Record why settings changed | [Rationale](./docs/src/user-guide/rationale.md) and [history](./docs/src/user-guide/history-snapshots.md) | None | +| Export a PDF or Markdown review report | [Audit Pack](./docs/src/user-guide/audit-pack.md) | Uses available saved data; does not run a device Audit | +| Evaluate a local lab device | [Authoring vs deploying](./docs/src/quick-start/authoring-vs-deploying.md) | Full edition, matching Windows/Linux host, CLI, and appropriate privileges | +| Evaluate a baseline through Azure Policy | [Machine Configuration](./docs/src/user-guide/machine-configuration.md) | Separate packaging environment and Azure permissions | + +**Benchmark coverage is not proof of device compliance.** A mapped setting +does not establish that its value is correct or that a device uses it. An +**Audit Pack** is an exported report; **Audit** checks a device through `oscfg`. +Missing or old device results must not be presented as a current audit. ## What it looks like -Left rail order is **Dashboard, My Baselines, Microsoft Baselines, Export Readiness, Diff, Benchmark Mapping, Settings**. +Screenshots illustrate the workflows; exact layout varies by release and +edition. Device controls shown in Full-edition screenshots are absent on macOS. -### Microsoft Baselines: start from a curated catalog +
+Explore the editor, comparison, and report screenshots -Browse pre-built security baselines (Windows Server 2016/2019/2022/2025, -member, domain controller, and workgroup; Microsoft Defender; LAPS; Secured -Core; and Linux Security Baseline) and click **Use as Template** to fork one -into your own baseline. +### Microsoft Baselines: start from a curated catalog -![Microsoft Baselines: pre-built security baselines you can fork into your own baseline](./docs/images/screenshots/library.png) +Browse Windows Server role baselines, Defender, LAPS, Secured Core, and the +Linux Security Baseline. **Use as Template** creates your own editable copy. ### Dashboard: system health + quick actions -See the resolved `oscfg` version, admin status, server type, and OS version at a glance. Three quick-action buttons (New Baseline, Browse Microsoft Baselines, Compare Baselines) jump straight into authoring or compliance. +Start a baseline, browse Microsoft Baselines, or compare existing work. +The Full edition also surfaces CLI and device health. -![Dashboard: system health, registered-baseline count, quick actions, and recent activity](./docs/images/screenshots/home.png) +![Dashboard and quick actions](./docs/images/screenshots/home.png) ### My Baselines: localized catalog and persistent workspaces -Search and filter the localized administration table, see real Date Modified -values in the local calendar, open multiple baselines in persistent tabs, and -compare selected baselines. Unsaved edits are protected before a tab closes or -navigation leaves the workspace. +Search and filter baselines, open persistent tabs, and compare selected items. +Unsaved-edit prompts help protect work when closing a tab or navigating away. ### Baseline editor: author and export an Audit Pack -YAML / JSON / Visual editing includes live validation, version history, CIS -cross-reference, and one-click Audit Pack PDF/Markdown export. Each baseline -remembers its Code or Visual view. Read-only Code view explains how to enter -editing, and unsaved changes are protected when a baseline tab closes or -navigation leaves the editor. The Full edition also exposes CLI-gated device -deploy/audit controls; the macOS Author edition does not. +Review Code or Visual views, edit settings, and export your work. -![Baseline editor: YAML/JSON/Visual tabs, deploy + audit, history, and Audit Pack button](./docs/images/screenshots/manifest-detail.png) +![Baseline editor in the Full edition](./docs/images/screenshots/manifest-detail.png) ### Visual spreadsheet: edit settings in place -Switch to **Visual** mode and click **Edit** to work directly in grouped setting -tables. Edit cells, add known Windows or Linux setting types, add blank rows, -or select rows for deletion. Test wrappers and Group children remain bound to -their original YAML structure, typed values remain typed, and QWord integers -retain full precision. On current `main`, Tab commits and moves right, Enter -moves down through nested values, final Enter appends and focuses a new value, -and invalid drafts retain focus. PR #77 carries that PR #76 behavior on the -current macOS branch. +Edit cells, add supported setting types, or remove selected rows. Nested +Test/Group structure, typed values, and exact QWord integers are preserved. -![Visual spreadsheet with inline setting editing](./docs/images/screenshots/visual-builder.png) +![Visual spreadsheet editing](./docs/images/screenshots/visual-builder.png) ### Audit pack: the auditor deliverable -One click on **Audit Pack** opens a download surface with PDF + Markdown -buttons, an inline PDF preview, and a sidebar showing exactly what's in the -pack (baseline header, compliance report, version history, rationale log, and -analysis provenance labels). This authoring/export workflow is available in both the -Full and macOS Author editions; it does not perform a device audit. +Export PDF or Markdown from saved baseline, history, and available review data. +No device audit is performed when generating the report. -![Audit pack download page: PDF + Markdown buttons, inline preview, what's-included sidebar](./docs/images/screenshots/audit-pack.png) +![Audit Pack download and preview](./docs/images/screenshots/audit-pack.png) ### Create a new baseline: choose from five starting points -Create a blank Windows or Linux baseline, start from a starter template, -choose a Microsoft Baseline in place, load from a public URL, or import a local -`.osc.yaml`, `.json`, `.csv`, or binary `.xlsx` file. The validated import path -converts supported spreadsheet data into editable OSConfig settings. +Start a custom Windows/Linux baseline, choose a template, import a baseline +file, import a spreadsheet, or load a public URL. -![Register new baseline: import/paste/build with platform-aware validation](./docs/images/screenshots/new-manifest.png) +![New baseline starting points](./docs/images/screenshots/new-manifest.png) ### Compare baselines: Pairwise, CIS, Matrix -The Diff page has **Pairwise**, **CIS**, and **Matrix** views. Starting a -comparison with exactly two selected baselines preselects them in Pairwise. -Starting with three through ten selected baselines preselects them in Matrix. -Pairwise shows source and setting changes; Matrix aligns equivalent rules -across multiple baselines. +Two selected baselines open Pairwise; three through ten open Matrix. +The CIS view requires user-supplied benchmark data. -![Compare baselines: pairwise diff with diff stats, AI insights, and Setting Changes panel](./docs/images/screenshots/diff.png) +![Pairwise comparison](./docs/images/screenshots/diff.png) ### Benchmark Mapping: bring-your-own benchmark data -Drop CIS Azure Policy JSON or XCCDF+OVAL XML files onto the **Benchmark Mapping** page (no benchmarks are bundled — CIS licensing). The page auto-detects platform and shows per-file status indicators with Re-check / Open folder actions. CIS data powers the inline cross-reference drawer in the editor, the compliance scoring on every baseline, and the bulk CIS Diff tab. +Use the data folder shown in **Benchmark Mapping**, then re-check the catalog. +See the [data setup guide](./docs/src/user-guide/cis-compliance.md). -![Benchmark Mapping page: per-file detection status with Re-check + Open folder actions](./docs/images/screenshots/cis-mapping.png) +![Benchmark data detection](./docs/images/screenshots/cis-mapping.png) ### CIS Diff: bulk compliance scoring -The Diff page includes a **CIS Diff** tab that scores any baseline against any user-supplied CIS benchmark. Big compliance % hero metric ("X of Y CIS rules covered"), filterable setting table with red ✕ / green ✓ status icons (click the Status column to sort), per-row source badge (Azure Policy vs XCCDF), and a "Missing from CIS" filter to surface unmapped rules. - -![CIS Diff tab: compliance hero metric + sortable setting coverage table](./docs/images/screenshots/cis-diff.png) +The percentage measures unique benchmark rules covered by matching settings, +not device compliance or certification. -## Quick start: run from source +![CIS coverage table](./docs/images/screenshots/cis-diff.png) -```powershell -# Requires Node 22.12+ LTS or Node 24 LTS. -# .nvmrc and .node-version select the default Node 22 toolchain. -git clone https://github.com/Azure/ConfigForge.git -cd ConfigForge -git checkout main -node --version # must report v22.12+ or v24.x -npm ci -npm run desktop:dev # Windows + Linux full flavor +
-# On an Apple Silicon Mac, use the author flavor instead: -git checkout mac-author-build -node --version # must report v22.12+ or v24.x -npm ci -npm run dev:author -w @configforge/desktop -``` +## Optional: install the OSConfig CLI for Deploy / Audit -Both development commands run Vite (renderer) + Electron with hot-reload. -Source builds reject unsupported Node.js releases before Vite starts. If -dependencies were installed with an unsupported release, switch to Node 22 or -24, delete `node_modules`, run `npm ci`, and retry the development command. +The native [`oscfg`](https://github.com/microsoft/osconfig/tree/main/docs/cli) +CLI is **not bundled**. It is separate from the PowerShell modules used for +Machine Configuration packaging. The targeted CLI is `oscfg 1.3.9-preview11`; +see [INSTALL.md](./INSTALL.md#optional-local-device-operations) for setup. -### Optional: install the OSConfig CLI for Deploy / Audit +Start with Audit on a disposable, matching-platform device. Enforce changes +settings; Revert is not a substitute for a machine backup. On Windows, the +preview CLI requires elevation even for Audit. Authoring does not. -The editor, library, diff, compare, CIS mapping, import/export, and audit-pack PDF features all work without the CLI. To enable Deploy / Audit / Revert against a real Windows or Linux machine, install OSConfig separately: - -- **All platforms:** see [`INSTALL.md`](./INSTALL.md) for platform-by-platform steps. -- **Upstream:** https://github.com/microsoft/osconfig -- **Current target:** `oscfg 1.3.9-preview11` +## Export to Azure Machine Configuration -After install, click the amber **Editor mode, CLI not installed** pill in the footer (or the **Recheck** button in Settings) to flip the app into Deploy-capable mode without restarting. On Windows the CLI currently requires running ConfigForge from an **elevated PowerShell**. +This is an **advanced, optional workflow**, not a prerequisite for using the +app: -## Building installers +`ConfigForge baseline → MOF → resolved MOF → Machine Configuration ZIP → Azure Storage → generated policy JSON → policy definition → assignment` -```powershell -# Windows: NSIS .exe + portable zip (~113 MB / ~149 MB) -npm run desktop:dist:win +On the **packaging machine**, `New-GuestConfigurationPackage` needs the +**Microsoft.OSConfig PowerShell module version 1.4.10 or later** to bundle the +OSConfig DSC resource. Install it with +`Install-Module -Name Microsoft.OSConfig -MinimumVersion 1.4.10`. +This is a **module version**, not a PowerShell runtime version. PowerShell 7 +and the separate **GuestConfiguration** packaging toolkit are also required. + +The [complete Machine Configuration guide](./docs/src/user-guide/machine-configuration.md) +checks for a qualifying installed module, binds the exported +`ModuleVersion = "0.0.0"` placeholder to that exact version, and creates an +Audit-first package. Keep each ZIP and its URI immutable after policy +generation: the policy contains the package hash. Test the baseline and +module combination; the minimum version is not a claim that every OSConfig +issue is resolved. [Module release](https://www.powershellgallery.com/packages/Microsoft.OSConfig/1.4.10) -# Linux: portable tar.gz from any host (~140 MB) -npm run desktop:dist:linux -``` +## Quick start: run from source -Full Linux installer matrix (AppImage + deb + rpm) needs a Linux build host. `release.yml` uses `ubuntu-latest` for that. See [`apps/desktop/PACKAGING.md`](./apps/desktop/PACKAGING.md) for the full build matrix and the post-build smoke checklist. +Source builds are optional. Follow [Build from source](./docs/src/quick-start/install-run.md#build-from-source-optional) +for the separate Full and macOS Author commands and the supported Node +toolchain. You do not need Node.js to run a downloaded desktop build. -The macOS Author DMG targets Apple Silicon (`arm64`) and is built from -`mac-author-build` with `npm run dist:mac:author -w @configforge/desktop`. It -is ARM64-only, unsigned, and not notarized. It does not support Intel Macs and -is not a universal binary. +## Building installers -> **Builds are unsigned.** This project holds no code-signing credentials, so installers are unsigned by design — Windows SmartScreen and macOS Gatekeeper will warn. The trust path is building from source (above); you can optionally self-sign your own local build via [`apps/desktop/scripts/generate-dev-cert.ps1`](./apps/desktop/scripts/generate-dev-cert.ps1). +See [desktop packaging](./apps/desktop/PACKAGING.md) for platform-specific +commands, build-host requirements, and smoke checks. Full Linux installer +builds require Linux; macOS Author builds require Apple Silicon. ## Repo layout -| Path | What | -|---|---| -| `apps/desktop/**` | The Electron app: renderer (React + FluentUI v9 + Vite), main process, preload bridge, electron-builder config | -| `apps/desktop/src/pages//` | Each lighthouse page lives in its own directory with `index.tsx` (composition), `state/` (custom hooks + their tests), `components/` (memoised sub-components), and optional `helpers.tsx`. Pattern landed during the Phase A-E renderer-page split | -| `packages/core/**` | Platform-neutral core: manifests, history, audit-pack, oscfg wrapper, analysis provenance labeling (`circular-guard`, `provenance`; local heuristic, advisory). Imported as `@configforge/core` from the desktop app | -| `resources/oscfg/**` | **Dev-only convenience drop** for contributors who bring their own `oscfg` binary. Never shipped to users; the installer carries no Microsoft-owned binaries | -| `public/_baselines/**` | Curated baseline manifests (Windows Server, Defender, LAPS, Secured Core, Linux SFF, etc.), bundled into installers | -| `docs/**` | mdbook documentation site (separate from the app) | -| `scripts/**` | Postinstall + helper scripts (oscfg chmod, dev-cert generator, screenshot capture, etc.) | -| `.github/workflows/**` | `pr-check.yml` (lint + vitest + Playwright Electron smoke), `release.yml` (Full-edition tagged releases), `release-mac.yml` (explicit-tag macOS Author draft assets), and `docs.yml` (mdBook site) | +The desktop app uses Electron, React, Fluent UI, and Vite. Its shared core +lives in `packages/core`; the documentation site lives in `docs`. +See the [system overview](./docs/src/architecture/system-overview.md) and +[module map](./docs/src/architecture/module-map.md) for developer details. ## Documentation -- **[`apps/desktop/DESIGN.md`](./apps/desktop/DESIGN.md)**: the Fluent v2 design system contract (principles, signature experiences, tokens, reviewer checklist). -- **[`apps/desktop/PACKAGING.md`](./apps/desktop/PACKAGING.md)**: installer build workflow, cross-platform matrix, smoke checklists, troubleshooting. Builds are unsigned (optional local self-sign helper included). -- **[`apps/desktop/CI.md`](./apps/desktop/CI.md)**: GitHub Actions workflows (PR check + release pipeline), supply-chain hardening (`npm audit` gate, CycloneDX SBOM, `npx --no-install` tooling pin), trigger scope, release-cutting walkthrough. -- **[`SUPPORT.md`](./SUPPORT.md)** and **[`SECURITY.md`](./SECURITY.md)**: best-effort support boundaries and private vulnerability reporting. -- **[`apps/desktop/src/design/PLATFORM.md`](./apps/desktop/src/design/PLATFORM.md)**: platform-specific UX rules (Windows Mica + custom titlebar, Linux native frame, etc.). -- **[`CHANGELOG.md`](./CHANGELOG.md)**: per-release notes. The current macOS - Author tagged source is `mac-v0.3.97-author.1`; its matching release is a - draft and unpublished. -- **[`docs/src/SUMMARY.md`](./docs/src/SUMMARY.md)**: documentation source for - Quick Start, User Guide, Architecture, API Reference, and Operations. The - `docs` workflow builds this into an mdBook site and deploys it to the - `gh-pages` branch at . +- [Documentation site](https://azure.github.io/ConfigForge/) and [source navigation](./docs/src/SUMMARY.md). +- [Troubleshooting](./docs/src/operations/troubleshooting.md), [support](./SUPPORT.md), and [privacy](./PRIVACY.md). +- Developer references: [design contract](./apps/desktop/DESIGN.md), + [platform UX](./apps/desktop/src/design/PLATFORM.md), [packaging](./apps/desktop/PACKAGING.md), + and [CI/release workflow](./apps/desktop/CI.md). ## Contributing -- Read [`AGENTS.md`](./AGENTS.md), the canonical guide for AI agents, also a useful summary for humans. -- Pre-PR bar: - ```powershell - npm ci - npm run lint # 0 errors; `warn`-level max-lines flags are tracked-but-not-blocking - npm test # vitest full suite - npm run desktop:build # core + renderer + electron main; must succeed cleanly - ``` - Smoke-test on Windows from elevated PowerShell if you touched `apps/desktop/electron/**` or `packages/core/src/oscfg/**`. -- To regenerate the screenshots above: run `npm ci`, build the desktop app once (`npm run desktop:build`), then run `node scripts/capture-screenshots.mjs`. The repository's existing Playwright dependency launches the bundled Electron app, navigates each page, and writes PNGs to `docs/images/screenshots/`. -- See [`CONTRIBUTING.md`](./CONTRIBUTING.md) and [`AGENTS.md`](./AGENTS.md) - for ownership, active-branch, review, release, and cherry-pick guidance. -- Optional: `npm run format` (Prettier) and `npm run format:check`. Prettier was added in v0.2.1 with no mass-format run. Adopt incrementally on files you touch. +See [CONTRIBUTING.md](./CONTRIBUTING.md) and [AGENTS.md](./AGENTS.md) +for ownership, active-branch, review, release, and cherry-pick guidance. +Report reproducible bugs through [GitHub Issues](https://github.com/Azure/ConfigForge/issues); +include the edition, version, OS, and a minimal non-sensitive example. ## Release history (high-level) -| Version | Highlights | -|---|---| -| **0.3.103** (current Windows/Linux release) | Makes all 12 Windows Server role baselines enforceable with OSConfig 1.4.3 and validates exact-count Audit plus fully compliant ApplyAndAutoCorrect on native Azure VMs | -| **0.3.102** (prior Windows/Linux release) | Fixes pre-deploy Audit with OSConfig 1.4.3 so single-resource CSP, Registry, Test, and User Rights reads are evaluated instead of reported as indeterminate | -| **0.3.101** (prior Windows/Linux release) | Clears the remaining GitHub security alerts with patched DOMPurify, fast-uri, ip-address, React Router, and Undici releases | -| **0.3.100** (prior Windows/Linux release) | Updates js-yaml to the patched 4.3.1 release for `GHSA-5p4m-2wfm-xmqj` | -| **0.3.99** (prior Windows/Linux release) | Verifies Enforce results, preserves exact QWords, keeps Revert safe, repairs WS2022 readability, and adds Machine Configuration Set compatibility | -| **0.3.98** (prior Windows/Linux release) | Adds complete Machine Configuration deployment documentation and removes stale/internal public-doc guidance | -| **0.3.101-author.1** (current macOS prerelease) | Ports the author-safe baseline, lossless data, Machine Configuration packaging, build, and security fixes | -| **0.3.98-author.1** (prior macOS prerelease) | Ports the public documentation and Machine Configuration guidance to macOS Author | -| **0.3.97** (prior Windows/Linux draft) | Preserves authoritative CLI reasons for expression-backed Test resources and adds detailed templates to all WS2025 controls | -| **0.3.97-author.1** (prior macOS draft) | Ports the same detailed audit-reason behavior to the author-only macOS line | -| **0.3.96** (prior Windows/Linux draft) | Preserves all 320/321/296 WS2025 controls while fixing Registry/CSP contracts and CEL compliance, and hardens Machine Configuration MOF export in PR #104 | -| **0.3.96-author.1** (prior macOS draft) | Ports the same WS2025 authoring and global MOF export fixes to the author-only macOS line in PR #105 | -| **0.3.95** (prior Windows/Linux draft) | Replaces unreliable native hover titles with FluentUI tooltips on My Baselines status cells (keyboard accessible, ARIA-exposed multiline details) in PR #100; corrects documentation architecture and release-state drift in PR #97 | -| **0.3.94** (prior Full edition) | Excludes CIS benchmark source data from public installers, publishes the public licensing/privacy/support/security policy surface, patches dev-only `brace-expansion` 5.x, and refreshes nine README screenshots with synthetic benchmark content in PR #89 | -| **0.3.94-author.1** (prior macOS draft) | Carries the public-source packaging, policy, privacy, security, and nine synthetic screenshot updates into the author-only Apple Silicon edition without adding device operations | -| **0.3.93-author.2** (historical macOS source milestone; no current tag or release) | Ports the standalone Windows Server 2025 audit repairs, corrected CIS aliases, Source-link cleanup, and policy-identity fixes through PR #83/#84. Historical workflow evidence is superseded by the current `mac-v0.3.101-author.1` prerelease metadata. | -| **0.3.93-author.1** (historical macOS source milestone; no current tag or release) | Restored complete macOS authoring parity and nested Enter/Tab editing through PRs #75, #76, and #77. Historical workflow evidence is superseded by the current `mac-v0.3.101-author.1` prerelease metadata. | -| **0.3.93** (prior Full edition) | Adds nested Enter/Tab editing and repairs standalone Windows Server 2025 audits, CIS mapping, and Matrix Diff policy identity handling | -| **0.3.92** | Patches the desktop updater, AppImage packager, PostCSS processor, and archive toolchain against newly disclosed vulnerabilities | -| **0.3.91** | Shows stacked Test schema rules in Visual mode and enforces supported constraints on newly edited values | -| **0.3.90** | Prevents Baseline Detail footer collisions and keeps long multi-value Visual rows inside their table columns | -| **0.3.89** | Completes Baseline Detail spreadsheet authoring, typed multi-value editing, accessible Add settings, deterministic history, and all current Dependabot fixes | -| **0.3.88** | Completes the July Loop revisions with pill tabs, sortable and left-aligned baseline data, reliable status tooltips, and safe one-click Undo | -| **0.3.87** | Removes the local `ImpersonateClient` manifest override while retaining minimum-version handling for oscfg 1.3.9 or newer | -| **0.3.86** | Current OSConfig-compatible `ImpersonateClient` YAML and minimum-version handling for oscfg 1.3.9 or newer | -| **0.3.85** | My Baselines rows stay behind the opaque sticky column header while scrolling | -| **0.3.84** | Export options are limited to YAML, JSON, MOF, and CSV; all remaining high-severity development dependency advisories are cleared | -| **0.3.83** | Development dependency security refresh: `tar` 7.5.20 and `axios` 1.18.1; no runtime feature changes | -| **0.3.82** | Baseline document identity, view-only Visual feedback, top/bottom Add setting actions, and Matrix baseline search | -| **0.3.81** | Footer actions retain labels and reflow into balanced compact rows across Electron resolutions | -| **0.3.80** | First-class OSConfig CSV imports, a responsive no-scroll Baseline Detail footer, and correct Save → Skip navigation after compliance deep links | -| **0.3.79** | Search compliance reports, filter by Compliant / Non-compliant / Could not read, and sort by status | -| **0.3.78** | Correct baseline platform icons and Monaco warning styling; persist compliance reports and move them into a large centered dialog | -| **0.3.77** | Completed Loop design pass: five-source baseline wizard with in-place Microsoft template selection, real XLSX import, visible Date Modified values, per-baseline Code/Visual memory, and Save/Discard/Cancel close protection | -| **0.3.76** | Cognitive Walkthrough polish: Pairwise Diff for two selections, shared Code/Visual Undo, a device-compliance drawer, final-cell Enter row creation, faster OSConfig recheck, corrected platform/status presentation, and streamlined onboarding/Benchmark Mapping | -| **0.3.62 – 0.3.68** | Rebrand **ConfigForge Spark → ConfigForge**; vocabulary refresh (**Manifests → My Baselines**, **Library → Microsoft Baselines**, **Validation → Export Readiness**, **CIS Mapping → Benchmark Mapping**, *resource* → *setting*, **OSConfig vNext → Gen 2**); unsigned OSS release pipeline with `SHA256SUMS` + SBOM verification; MOF export targets the `Microsoft.OSConfig` module; Monaco overflow-widget dropdown root-cause fix; "Could not read" compliance bucket on baseline cards | -| **0.3.54 – 0.3.61** | Localization rollout (FR / DE / ES) — five extraction waves, machine-translation + review tooling, `Intl` date/number/relative-time formatters, and length/overflow visual QA | -| **0.3.45 – 0.3.53** | Benchmark (CIS) Mapping subtitle + Diff › CIS tab; real History change summaries + auto-scroll Compare; CIS fuzzy-matching tightening; Group resources expand inline in Visual Builder; Diff "Select baseline" dropdown stability (Monaco overflow fix) | -| **0.3.27 – 0.3.36** | CIS matcher quality pass (CSP UserRights, alias table, XCCDF fuzzy fallback, 36/36 mappable UserRights match WS2025 CIS); 100x cis.status() perf fix; 3-second warmup deferral eliminates manifest-open regression; ResourceChangesPanel and Resource-level diff stats; AI summary numbers consistent across panels | -| **0.3.14 – 0.3.26** | CIS Mapping page (Azure Policy JSON + XCCDF/OVAL XML auto-detect), CIS cross-reference drawer in the manifest editor, CIS Diff tab on the Diff page, settings store with history retention, deploy recovery banner, breadcrumb navigation | -| **0.2.1** | Phase A-E renderer-page split; 15/15 security audit findings closed; typed main-process logger with secret redaction; Prettier config; CSV-import schema fix | -| **0.2.0** | Bring-your-own-CLI: removed bundled `oscfg` binary, added Welcome dialog + CliRequiredModal, well-known-paths binary resolver, MSIX fallback. Legal scaffolding (LICENSE / NOTICE / SECURITY / THIRDPARTYNOTICES) for OSS readiness | -| **0.1.x** | Initial Electron migration in 10 phases (Next.js to Electron + React Router + FluentUI v9 + Vite). See git log on `main` for per-phase commits | +See [CHANGELOG.md](./CHANGELOG.md) for detailed historical validation and +[the documentation changelog](./docs/src/changelog.md) for a shorter summary. +Past module-version validation records are not current packaging prerequisites. ## Code of Conduct @@ -300,7 +228,9 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope ## Security -To report a security vulnerability, please follow the instructions in [SECURITY.md](./SECURITY.md). **Do not** file security issues as public GitHub issues. ConfigForge does not collect telemetry; see [PRIVACY.md](./PRIVACY.md). +To report a security vulnerability, follow [SECURITY.md](./SECURITY.md). +**Do not** file security issues as public GitHub issues. ConfigForge does not +collect telemetry; see [PRIVACY.md](./PRIVACY.md). ## License diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 518a0a4..01ac338 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -1,62 +1,53 @@ # Summary -[Introduction](./introduction.md) +[Start here](./introduction.md) -# Quick Start +# Get started -- [Install & run](./quick-start/install-run.md) -- [Your first manifest](./quick-start/first-manifest.md) -- [Authoring vs deploying](./quick-start/authoring-vs-deploying.md) +- [Download, install, and open](./quick-start/install-run.md) +- [Your first baseline](./quick-start/first-manifest.md) +- [Authoring vs device operations](./quick-start/authoring-vs-deploying.md) -# User Guide +# Author and review -- [Manifest editor](./user-guide/manifest-editor.md) -- [Azure Machine Configuration deployment](./user-guide/machine-configuration.md) -- [Diff: pairwise + master matrix](./user-guide/matrix-diff.md) -- [CIS cross-reference & compliance](./user-guide/cis-compliance.md) -- [Rationale & change-author capture](./user-guide/rationale.md) -- [Audit-pack (PDF + Markdown)](./user-guide/audit-pack.md) -- [Analysis provenance](./user-guide/analysis-provenance.md) -- [History, snapshots, retention](./user-guide/history-snapshots.md) +- [Baseline editor and export](./user-guide/manifest-editor.md) +- [Compare baselines](./user-guide/matrix-diff.md) +- [Benchmark Mapping and coverage](./user-guide/cis-compliance.md) +- [Record why settings changed](./user-guide/rationale.md) +- [History and snapshots](./user-guide/history-snapshots.md) +- [Export an Audit Pack report](./user-guide/audit-pack.md) +- [Understand analysis provenance](./user-guide/analysis-provenance.md) -# Architecture +# Advanced workflows and help -- [System overview](./architecture/system-overview.md) -- [Module map](./architecture/module-map.md) -- [Registration semantics](./architecture/registration-semantics.md) -- [Mixed-platform classification](./architecture/mixed-platform.md) -- [`oscfg` CLI contract](./architecture/oscfg-cli.md) -- [Diagrams](./architecture/diagrams.md) - -# API Reference - -- [Baselines](./api-reference/manifests.md) -- [Deploy & health](./api-reference/deploy-health.md) -- [Diff](./api-reference/diff.md) -- [Compliance](./api-reference/compliance.md) -- [History, import & export](./api-reference/history-import-export.md) -- [Audit pack](./api-reference/audit-pack.md) -- [Rationale](./api-reference/rationale.md) - -# Operations - -- [CI on Linux + Windows](./operations/ci.md) -- [Smoke testing on Windows](./operations/smoke-testing.md) -- [Filing upstream bugs](./operations/upstream-bugs.md) +- [Package for Azure Machine Configuration](./user-guide/machine-configuration.md) - [Troubleshooting](./operations/troubleshooting.md) - -# Contributing - -- [`AGENTS.md` (canonical guide)](./contributing/agents-md.md) -- [Coding conventions](./contributing/conventions.md) -- [Testing expectations](./contributing/testing.md) -- [Adding a new oscfg type](./contributing/adding-oscfg-types.md) - -# Reference - -- [Manifest schema (oscfg 1.3.9-preview11)](./reference/manifest-schema.md) -- [Registered types](./reference/registered-types.md) +- [Report a reproducible CLI issue](./operations/upstream-bugs.md) - [Glossary](./reference/glossary.md) +- [Manifest schema](./reference/manifest-schema.md) +- [Registered resource types](./reference/registered-types.md) + +# For contributors + +- [Architecture overview](./architecture/system-overview.md) + - [Module map](./architecture/module-map.md) + - [Registration semantics](./architecture/registration-semantics.md) + - [Mixed-platform classification](./architecture/mixed-platform.md) + - [`oscfg` CLI contract](./architecture/oscfg-cli.md) + - [Diagrams](./architecture/diagrams.md) +- [API: Baselines](./api-reference/manifests.md) + - [Deploy and health](./api-reference/deploy-health.md) + - [Diff](./api-reference/diff.md) + - [Compliance](./api-reference/compliance.md) + - [History, import, and export](./api-reference/history-import-export.md) + - [Audit Pack](./api-reference/audit-pack.md) + - [Rationale](./api-reference/rationale.md) +- [Contributor guide (`AGENTS.md`)](./contributing/agents-md.md) + - [Coding conventions](./contributing/conventions.md) + - [Testing expectations](./contributing/testing.md) + - [Adding an oscfg type](./contributing/adding-oscfg-types.md) + - [CI on Linux and Windows](./operations/ci.md) + - [Smoke testing on Windows](./operations/smoke-testing.md) --- diff --git a/docs/src/changelog.md b/docs/src/changelog.md index 295f0cb..409d9fe 100644 --- a/docs/src/changelog.md +++ b/docs/src/changelog.md @@ -6,6 +6,17 @@ foundational work by theme. ## Unreleased +- **Clearer getting started:** Download the correct Full or Apple Silicon + Author edition, save a first baseline without CLI/admin/Azure prerequisites, + and choose optional comparison, reporting, device, or packaging workflows. + Keep technical references available under contributor navigation and explain + unsigned-download risks, Audit Pack vs device Audit, and benchmark coverage. +- **Machine Configuration prerequisites:** Package with the **Microsoft.OSConfig + PowerShell module 1.4.10+**, separate from the PowerShell 7 runtime and + GuestConfiguration toolkit. The canonical Audit-first guide rejects missing + or older modules before resolving the MOF, keeps exact-version/immutable-ZIP + requirements, and excludes the historical 1.4.3 patch from current guidance. + The minimum version is not a statement that all upstream issues are fixed. - **Dependency security:** Update DOMPurify, Axios, ip-address, every supported brace-expansion and Undici line, and concurrently to patched releases. Also patch sharp, fast-uri, joi, and source-map-js diff --git a/docs/src/introduction.md b/docs/src/introduction.md index ffaf9f0..61bf3c1 100644 --- a/docs/src/introduction.md +++ b/docs/src/introduction.md @@ -1,164 +1,113 @@ # Introduction -> ⚠️ **Microsoft community-maintained project.** ConfigForge is **not** an -> officially supported Microsoft product and is **not intended for production -> use**. Use it for experimentation, learning, and community contributions at -> your own risk. - ## What is ConfigForge? -**ConfigForge is a security-baseline authoring tool for the OSConfig ecosystem.** It gives Windows and Linux security engineers a fast, visual way to write, validate, deploy, audit, version, and export the YAML manifests that the [`oscfg`](https://github.com/microsoft/osconfig/tree/main/docs/cli) command-line tool consumes - without hand-editing files in a text editor or memorizing the schema. - -The app is an **Electron 42 + React 18 + FluentUI v9 + Vite desktop -application** with two editions: +ConfigForge is a desktop app for creating, reviewing, and sharing OSConfig +security baselines. Start from a Microsoft template or your own settings, +compare changes, and export your work before deciding whether to test it on a +device. -- **Full edition** (`main` branch) - Windows + Linux with deploy, elevation, health probe, and audit-results storage. -- **Author edition** (`mac-author-build` branch) - ARM64 Apple Silicon macOS - authoring with editor, Microsoft Baselines, Diff, validation, Benchmark - Mapping, history, rationale, and Audit Pack export. Device-operation - namespaces (`health`, `deploy`, `deployRecovery`, `revert`, `auditResults`, - and elevation methods under `system`) are intentionally omitted. Authors - deploy later from the Full edition on Windows or Linux. +> **Experimental and community-maintained.** ConfigForge is not an officially +> supported Microsoft product and is **not intended for production use**. +> It is provided as-is for learning and evaluation, at your own risk. -The current Windows/Linux release is `v0.3.103`. The current macOS Author -release is `mac-v0.3.101-author.1`; both are published as prereleases. The -package versions are `0.3.103` for the Full edition and `0.3.101-author.1` -for the macOS Author edition. - -If you've ever maintained a security baseline by editing GPO templates, exporting Defender for Endpoint settings to a spreadsheet, or copy-pasting between half a dozen runbooks - this app is for you. +**Start here:** [Install the app](./quick-start/install-run.md) → +[Create your first baseline](./quick-start/first-manifest.md). +You do not need a CLI, administrator access, or an Azure subscription to +complete this authoring walkthrough. ## What problem does it solve? -Authoring a security baseline today is **slow, brittle, and lonely**: - -- The source of truth lives in PDFs, spreadsheets, GPO Templates, or - internal wikis - not in a single artifact a tool can validate. -- Comparing two baselines (your draft vs. CIS, your draft vs. last - quarter's, two regional variants of the same standard) means hours - of manual diffing in Excel. -- When auditors ask "why did this value change?" the answer lives in - someone's email or in a Slack thread that scrolled away. -- Exporting to the half-dozen formats different teams want (Intune, - Azure Policy, Excel, Markdown) is a copy-paste exercise that - drifts the moment any of them is edited. -- Every baseline author hits the same wall: the tooling assumes you - already know the answer, instead of helping you find it. - -## What does ConfigForge do? - -The sidebar exposes **Dashboard**, **My Baselines**, **Microsoft Baselines**, -**Export Readiness**, **Diff**, **Benchmark Mapping**, and **Settings**. - -The app is built around six core workflows, each of which closes one -of the gaps above. - -### 1. Author and validate manifests in a structured editor - -A Monaco-based YAML editor with live schema validation, type-aware -hints for every OSConfig resource type, and a side panel that surfaces -the currently-selected resource's CIS rule cross-reference (when CIS -data is available locally). - -→ See [User Guide → Manifest editor](./user-guide/manifest-editor.md). - -### 2. Compare baselines and explain the deltas - -Pairwise diff for two manifests, plus an N-way **master-matrix** that -puts up to 10 baselines side-by-side as columns and shows which ones -agree and which ones differ on every setting. generated narrative -explanations describe *why* each delta matters in plain English. Excel -export with conditional formatting for the auditor's offline review. +Keep desired settings in one editable baseline rather than reconciling +separate spreadsheets and handwritten change notes. ConfigForge helps you +compare drafts, record why values changed, and share a review report. +It does not certify a baseline or prove that a device is compliant. -→ See [User Guide → Matrix diff](./user-guide/matrix-diff.md). +### Three terms to know -### 3. Capture change rationale as you author +- **Baseline:** your set of desired security settings. +- **Manifest:** the YAML or JSON document describing a baseline. +- **Register:** save a baseline in My Baselines. Registration does not deploy + settings or create an Azure resource. -Every value change in the editor prompts a one-line "Why?" capture. -Author identity is resolved automatically (git config → OS user). Every -snapshot in the version history carries the author and the rationale, -so the audit trail is built as a side-effect of normal authoring - not -as a separate after-the-fact exercise. +See the [glossary](./reference/glossary.md) when you need more terminology. -→ See [User Guide → Rationale](./user-guide/rationale.md). - -### 4. Generate the auditor's deliverable in one click - -A PDF audit-pack assembles the manifest, the version history (with -authors and rationale), and the compliance scorecard against any -user-supplied CIS benchmark into a single document ready to attach to a -compliance review. +## What does ConfigForge do? -→ See [User Guide → Audit pack](./user-guide/audit-pack.md). +Choose the next task you need; the advanced sections are optional. -### 5. Benchmark Mapping and status tracking +| Task | Start here | What to expect | +| --- | --- | --- | +| Create or edit a baseline | [Baseline editor](./user-guide/manifest-editor.md) | Code/Visual editing, validation, and YAML/JSON/MOF/CSV export | +| Compare drafts | [Diff](./user-guide/matrix-diff.md) | Pairwise comparison or a matrix of up to ten baselines | +| Review benchmark coverage | [Benchmark Mapping](./user-guide/cis-compliance.md) | Matches against your own licensed data; no CIS data is bundled | +| Explain changes | [Rationale](./user-guide/rationale.md) and [history](./user-guide/history-snapshots.md) | Saved change reasons and snapshots | +| Share review material | [Audit Pack](./user-guide/audit-pack.md) | PDF or Markdown from available saved data; not a new device audit | +| Check a local lab device | [Authoring vs deploying](./quick-start/authoring-vs-deploying.md) | Optional CLI-based Audit, Deploy, and Revert in the Full edition | +| Evaluate through Azure Policy | [Machine Configuration](./user-guide/machine-configuration.md) | Separate packaging, testing, hosting, and policy-assignment workflow | + +The sidebar uses **Dashboard**, **My Baselines**, **Microsoft Baselines**, +**Export Readiness**, **Diff**, **Benchmark Mapping**, and **Settings**. +Export Readiness concerns baseline validation; it is not a device-compliance +result. -The Benchmark Mapping page shows which benchmark data files are detected on -disk, with per-file status indicators. Users add Azure Policy JSON or -XCCDF/OVAL files to the resolved data directory; the page provides Re-check -and Open folder actions. Benchmark data powers the editor cross-reference and -the Diff page's CIS tab for full-baseline coverage scoring. +**Keep the results distinct:** benchmark coverage identifies matching rules, +not necessarily matching values. Device Audit checks a machine. Audit Pack +exports a report and only includes device results when saved results exist. +Review their timestamps, scope, and any unread or unavailable settings. -### 6. CIS Diff - bulk coverage analysis +## Supported platforms -The Diff page includes a CIS Diff tab that annotates the N-way matrix with CIS rule coverage. Each matrix row shows whether the setting maps to a CIS benchmark rule, its severity, and match status. Powered by a bulk-lookup IPC that avoids per-row round trips. +| Your computer | Edition | Start with | +| --- | --- | --- | +| Windows (x64) | **Full** | Authoring without extra tools; local device operations need `oscfg` and elevation | +| Linux (x64) | **Full** | Authoring; live device operations additionally need a compatible CLI/host and permissions | +| macOS on Apple Silicon (M1 or later) | **Author** | Authoring, Diff, Benchmark Mapping, history, rationale, and Audit Pack export; no device operations | + +The current Windows/Linux release is +[v0.3.103](https://github.com/Azure/ConfigForge/releases/tag/v0.3.103). +The current macOS Author release is +[mac-v0.3.101-author.1](https://github.com/Azure/ConfigForge/releases/tag/mac-v0.3.101-author.1). +Both are prereleases and unsigned; macOS is not notarized. Intel Macs and +universal binaries are not supported. Read the +[download and installation guidance](./quick-start/install-run.md) first. ## Who is this for? -| Audience | Start here | -| --- | --- | -| **Microsoft Baseline Author / Consultant** writing or maintaining a custom security baseline | [Quick Start → Install & run](./quick-start/install-run.md) | -| **Security or compliance auditor** reviewing someone else's baseline | [User Guide → Benchmark Mapping](./user-guide/cis-compliance.md), [Diff](./user-guide/matrix-diff.md), and [Audit pack](./user-guide/audit-pack.md) | -| **Integrator / SI / VAR** deploying baselines to customer environments | [Quick Start → Authoring vs. deploying](./quick-start/authoring-vs-deploying.md) | -| **Engineer extending the codebase** | [Architecture → System overview](./architecture/system-overview.md) and [Contributing](./contributing/agents-md.md) | -| **AI agent (Copilot, Claude, Cursor)** | [`AGENTS.md`](https://github.com/Azure/ConfigForge/blob/main/AGENTS.md) at the repo root | +- **Baseline authors:** begin with [Your first baseline](./quick-start/first-manifest.md). +- **Reviewers:** compare drafts and inspect an [Audit Pack](./user-guide/audit-pack.md), + keeping benchmark coverage separate from device evidence. +- **Lab operators:** read [Authoring vs deploying](./quick-start/authoring-vs-deploying.md) + before using device operations. +- **Contributors:** the [system overview](./architecture/system-overview.md), + [module map](./architecture/module-map.md), and [contribution guide](./contributing/agents-md.md) + cover implementation details. ## How it fits in the OSConfig ecosystem -ConfigForge is a **front-end** for the upstream `oscfg` CLI. The -app does not replace the CLI, the OSConfig agent, or the schemas - it -shells out to `oscfg` for every actual deploy / audit / get operation. - -```text -┌──────────────────────────────────────┐ -│ ConfigForge UI (this app) │ ← author, validate, diff, audit-pack -└──────────────────────────────────────┘ - │ - ▼ spawns -┌──────────────────────────────────────┐ -│ oscfg CLI (Microsoft, preview) │ ← apply, get, namespace operations -└──────────────────────────────────────┘ - │ - ▼ -┌──────────────────────────────────────┐ -│ OSConfig agent + native OS APIs │ ← actually applies the configuration -└──────────────────────────────────────┘ -``` - -The current upstream CLI version targeted is **`oscfg 1.3.9-preview11`**. - -## Supported platforms - -| Platform | Edition | Status | -| --- | --- | --- | -| **Windows 11 / Windows Server 2016-2025** | Full | Author, validate, deploy, audit, diff, export. Deploy/audit require an elevated shell with `oscfg` installed. | -| **Linux (Ubuntu 22.04+)** | Full | Build is verified in CI; live deploy/audit requires a host with `oscfg` installed. | -| **macOS on Apple Silicon (M1 or later)** | Author | ARM64-only authoring, validation, Microsoft Baselines, Diff, Benchmark Mapping, history, rationale, and Audit Pack export. Device operations are intentionally absent. Intel Macs and universal binaries are not supported. | +The app authors baselines. For optional local operations, the Full edition +calls the native `oscfg` CLI, which is installed separately. The targeted CLI +is `oscfg 1.3.9-preview11`; CLI compatibility is separate from package tooling. -> ConfigForge normalizes authoring differences across platforms; -> deploy and audit remain platform-gated by the local `oscfg` CLI. +For Azure Machine Configuration, export a MOF and move to a packaging machine +with **PowerShell 7**, **GuestConfiguration**, and the **Microsoft.OSConfig +PowerShell module 1.4.10 or later**. Version **1.4.10** refers to the module, +not the PowerShell runtime. Follow the +[packaging prerequisites](./user-guide/machine-configuration.md#prerequisites); +these tools are not required to author in ConfigForge. ## Repository -Source lives at -[github.com/Azure/ConfigForge](https://github.com/Azure/ConfigForge). Active -development happens on **`main`** (Windows/Linux full build) and -**`mac-author-build`** (macOS Author). Shared changes land on `main` first and -are ported through focused commits; the flavor branches are not cross-merged. - -> **Tip:** This documentation is generated from the `docs/` folder of the repository at every push to `main`. To suggest an edit, click the pencil icon at the top of any page - it links straight to the source markdown on GitHub. +Source and documentation live at +[Azure/ConfigForge](https://github.com/Azure/ConfigForge). The active branches +are `main` for Windows/Linux Full and `mac-author-build` for macOS Author. +The documentation site's edit link opens the corresponding Markdown source. ## Maintainer -Maintained by the community. Use -[GitHub Issues](https://github.com/Azure/ConfigForge/issues) for bug reports -and feature discussions. +Community-maintained by [@ABMFST](https://github.com/ABMFST). Use +[GitHub Issues](https://github.com/Azure/ConfigForge/issues) for reproducible +bugs and feature discussions. Read the +[support boundaries](https://github.com/Azure/ConfigForge/blob/main/SUPPORT.md) +and report vulnerabilities privately through +[SECURITY.md](https://github.com/Azure/ConfigForge/blob/main/SECURITY.md). diff --git a/docs/src/operations/ci.md b/docs/src/operations/ci.md index 5189460..0eec2db 100644 --- a/docs/src/operations/ci.md +++ b/docs/src/operations/ci.md @@ -13,7 +13,7 @@ ConfigForge uses GitHub Actions from `.github/workflows/`. The product is an Ele The Win/Linux Release workflow intentionally ignores hyphen-suffix tags (`!v*-*`). macOS Author releases use separate tags such as -`mac-v0.3.98-author.1`; dispatch the protected `main` workflow definition +`mac-v0.3.101-author.1`; dispatch the protected `main` workflow definition manually and let its checkout step select the immutable macOS tag. ## What `pr-check.yml` runs @@ -35,8 +35,8 @@ files; main PR #76 then passed its full suite plus 32 focused nested-navigation tests. Mac port PR #77 passed 79 focused tests and two isolated Playwright scenarios. Historical `0.3.93-author.1` and `0.3.93-author.2` validation records are superseded; their tags and releases no longer exist. The current -macOS Author tagged source is `mac-v0.3.98-author.1`, with an unpublished -draft release. Use its current GitHub checks and release metadata as the +macOS Author release is `mac-v0.3.101-author.1`, published as a prerelease. +Use its current GitHub checks and release metadata as the authority rather than pinning a workflow run in this document. Caching covers npm, Electron binaries, electron-builder, and Playwright browser downloads. Concurrency cancels stale PR runs on the same branch. @@ -58,7 +58,12 @@ Each platform job: 9. Uploads installers, checksums, and SBOMs to a draft GitHub Release. 10. Stashes the same artifacts on the workflow run for short-term recovery. -Release artifacts are **unsigned** by design — there is no code signing in CI. On Windows, SmartScreen warns until a binary builds reputation; on macOS, Gatekeeper requires `xattr -cr`. The trust path is building from source; optional local self-signing is described in `apps/desktop/scripts/generate-dev-cert.ps1`. +Release artifacts are **unsigned** by design; macOS builds are not notarized. +There is no code signing in CI. Follow the +[download-verification and per-app warning guidance](https://github.com/Azure/ConfigForge/blob/main/INSTALL.md#install-the-desktop-app), +not a blanket security bypass. Building from reviewed source is an alternative, +not a safety guarantee; the optional local self-sign helper is described in +the [packaging guide](https://github.com/Azure/ConfigForge/blob/main/apps/desktop/PACKAGING.md). ## What `release-mac.yml` runs diff --git a/docs/src/operations/troubleshooting.md b/docs/src/operations/troubleshooting.md index 9ef32cf..7f6b1be 100644 --- a/docs/src/operations/troubleshooting.md +++ b/docs/src/operations/troubleshooting.md @@ -1,7 +1,23 @@ # Troubleshooting -A grab-bag of error messages and fixes. Listed in roughly the -order new users encounter them. +Start with the section matching your symptom. Authoring does not require the +CLI, elevation, or Azure. + +## Download is blocked + +Releases are unsigned, and macOS builds are not notarized. Verify the download +source and SHA-256 checksum, then follow your organization's approved process. +Do not disable operating-system protections globally. See +[installation and download warnings](https://github.com/Azure/ConfigForge/blob/main/INSTALL.md#install-the-desktop-app). + +## Machine Configuration package creation fails + +Use **PowerShell 7**, **GuestConfiguration**, and the **Microsoft.OSConfig +PowerShell module 1.4.10 or later** on the packaging machine. The CLI installed +with winget does not satisfy the module requirement. Resolve the MOF's `0.0.0` +placeholder to an exact qualifying installed module version before packaging. +Follow the [packaging checks and troubleshooting](../user-guide/machine-configuration.md#troubleshooting); +do not apply the historical 1.4.3 patch to 1.4.10+ packages. ## "`oscfg` binary not found" @@ -10,10 +26,13 @@ installed**) even after install. Settings → System Health reports `oscfg.path: null` and Deploy / Audit / Revert open the `` install dialog. +If you only want to author, compare, or export, this is a normal Full-edition +state and needs no fix. macOS Author intentionally has no CLI/device controls. + Causes & fixes: 1. No `OSCFG_BIN`, no `oscfg` on `$PATH`, no install in a well-known - location. Follow [INSTALL.md](../../../INSTALL.md) for the + location. Follow [INSTALL.md](https://github.com/Azure/ConfigForge/blob/main/INSTALL.md) for the platform-specific install path (Windows: `winget install Microsoft.OSConfig`; Linux: the latest release tarball into `/usr/local/bin/`). Click **Recheck** in Settings → System Health @@ -53,8 +72,9 @@ whitelist for the targeted `oscfg` build. The whitelist lives at [`packages/core/src/oscfg/registered-types.ts`](https://github.com/Azure/ConfigForge/blob/main/packages/core/src/oscfg/registered-types.ts) keyed by `OSCFG_CLI_VERSION`. -Fix: this is intentional graceful degradation - the rest of the -manifest still applies. When upstream adds a new type, re-probe with +Fix: registration permits authoring with a warning; it does not guarantee +successful or safe deployment. Check the target CLI's provider support before +using device operations. For contributors, when upstream adds a new type, re-probe with `scripts/probe-types.ps1` and add it to the whitelist + bump `OSCFG_CLI_VERSION`. See [Contributing → Adding a new oscfg type](../contributing/adding-oscfg-types.md). diff --git a/docs/src/quick-start/authoring-vs-deploying.md b/docs/src/quick-start/authoring-vs-deploying.md index 70bee62..ac3873c 100644 --- a/docs/src/quick-start/authoring-vs-deploying.md +++ b/docs/src/quick-start/authoring-vs-deploying.md @@ -1,96 +1,92 @@ # Authoring vs deploying -ConfigForge draws a sharp line between *authoring a manifest* -(safe, platform-agnostic, no CLI required) and *deploying it* (the -Full-edition operations that touch the live OS, and the only ones that -need the `oscfg` CLI installed). The macOS Author edition is for -authoring-only workflows. It includes Diff and Audit Pack export but omits -device deploy, audit, enforce, revert, elevation, and CLI-health surfaces. -Mixing the two was the single biggest design defect of the pre-`unified` -editions, and unmixing them is what lets you safely author Linux -manifests on a Windows laptop - even with no CLI at all. +**Registering or saving a baseline does not apply it.** Start with authoring +in either edition. Only move to device operations when you deliberately want +to evaluate or change a lab machine. + +The macOS Author edition includes authoring, Diff, Benchmark Mapping, +history, rationale, and Audit Pack export. It has no device Deploy, Audit, +Enforce, Revert, elevation, or CLI-health controls. ## The split -| Phase | IPC channel | What happens | Privileges | CLI required? | Platform-checked? | -| --- | --- | --- | --- | --- | --- | -| **Author / register** | `cfs:manifests:register` | Schema validation, source-YAML persisted, summary computed. **Never** spawns `oscfg`. | None | No | Soft warning only | -| **Deploy** | `cfs:deploy:run` (`mode=enforce`) | `oscfg apply` against the live system. | Admin/root | Yes | **Hard gate** - `'mixed'` rejected | -| **Audit** | `cfs:deploy:run` (`mode=audit`) | `oscfg get resource` - read-only check. | None on Linux; admin on Windows (preview-CLI bug) | Yes | Hard gate | -| **Revert** | `cfs.revert.apply` / `cfs:revert:apply` | Re-applies a prior snapshot, or deletes the namespace. | Admin/root | Yes | Hard gate | +| Action | What it does | What you need | +| --- | --- | --- | +| **Author / Register / Save** | Validates structure and saves a baseline in your local workspace; does not apply settings | Either edition; no CLI, admin access, or Azure | +| **Diff / Benchmark Mapping** | Compares baseline content or maps settings to supplied rules | Either edition; your own licensed data for benchmark mapping | +| **Audit Pack** | Exports a PDF/Markdown report from available saved data; does not run an Audit | Either edition; no CLI at export time | +| **Audit** | Checks settings on the local device without intentionally applying desired values | Full edition, matching host, `oscfg`; admin on Windows, appropriate read permissions on Linux | +| **Deploy / Enforce** | Applies desired settings to the local device and checks the result | Full edition, matching host, `oscfg`, admin/root, and a recovery plan | +| **Revert** | Reapplies an available pre-deploy snapshot, or removes enforcement/registration when no usable snapshot exists | Full edition and CLI/privilege/platform requirements; not a complete machine restore | + +Schema validation and benchmark coverage are **not** proof of device +compliance. A device result may also be incomplete: inspect settings marked +unread or indeterminate rather than counting them as compliant. ## CLI presence is surfaced everywhere -v0.2.0 introduced the bring-your-own-CLI contract. The state is -surfaced in three places so you never wonder which mode you are in: - -- **Welcome dialog** on first launch offers two cards: *Author only* - (Editor mode, no CLI) and *Author + deploy* (opens the install - dialog if the CLI is missing). -- **Footer health pill** reads 🟢 **OSConfig CLI v…** when installed, - 🟠 **Editor mode, CLI not installed** otherwise. Clicking the - amber pill opens the install dialog. -- **Settings → System Health** shows the resolved binary path, - source (`env` / `installed` / `path` / `msix` / `bundled`), and - admin status. A **Recheck** button re-runs the probe without - restarting the app. - -When the CLI is missing, Deploy / Audit / Revert preflight in -`packages/core/src/handlers/` throws `cliRequiredError()` (status -412, code `'CLI_REQUIRED'`), and the renderer routes that envelope -through `` instead of a generic error toast. +In the **Full edition**: + +- The Welcome dialog offers **Author baselines anywhere** or + **Author + deploy on this machine**. +- The footer shows **Editor mode, CLI not installed** when the CLI is absent. + This is a normal authoring state; clicking it opens installation guidance. +- **Settings → System Health** shows detected CLI information. + **Recheck** refreshes it after installation. + +The native `oscfg` CLI is not bundled. Install it only for local device +operations, using [INSTALL.md](https://github.com/Azure/ConfigForge/blob/main/INSTALL.md#optional-local-device-operations). +This CLI is separate from the Microsoft.OSConfig PowerShell module used for +Machine Configuration packaging. ## Why this matters -Before the unified refactor, registering a Linux manifest from a -Windows machine would fail at register time with `Unsupported -resource type` or platform-mismatch errors. Authors couldn't draft a -baseline for a different OS than their workstation. Now register is -**platform-agnostic**: any well-formed manifest is accepted, the -detected platform is recorded, and a soft warning fires when the -host doesn't match - never a block. +You can author Windows baselines on a Mac or Linux computer, and Linux +baselines on Windows. Authoring does not need a matching target machine. +Deploy/Audit require a compatible local Windows/Linux host. A baseline that +mixes platform-specific Windows and Linux settings cannot be deployed as one +unit. -Hard gates only fire when you ask the system to *do* something to -the live host (deploy, audit, revert) - and those gates require the -CLI to be installed in the first place. +ConfigForge is experimental and not intended for production use. Before +changing a lab device, review every setting, take a machine backup or snapshot, +and have a recovery path. Applying security settings can affect access, +networking, and workloads. ## Soft warnings vs hard errors -- **Hard error** - the manifest is malformed (missing `resources:`, - wrong shape, invalid Group/Test wrapper). Refused at register - time. -- **Soft warning** - registered successfully but worth flagging: - - manifest platform doesn't match host; - - manifest is `'mixed'` (Windows + Linux types in one document); - - manifest uses a type unknown to this host's `oscfg` install - (only surfaced when the manifest *targets* this host, so - cross-platform drafts don't spam false positives). - -See [Architecture → Registration semantics](../architecture/registration-semantics.md) -for the full state machine, and -[Architecture → Mixed-platform classification](../architecture/mixed-platform.md) -for how `'mixed'` is detected. +- **Hard error:** malformed content, such as a missing `resources:` array or + an invalid nested wrapper. Correct it before registering. +- **Soft warning:** registration succeeded, but the target differs from this + computer, the baseline mixes platforms, or a type is unknown to the + targeted CLI. Review it before any device operation. + +A soft warning permits drafting; it does not promise that the remaining +settings will apply safely. Developer details remain in +[registration semantics](../architecture/registration-semantics.md) and +[platform classification](../architecture/mixed-platform.md). ## Practical example -You're a security engineer on a Windows workstation drafting a -baseline for a Linux fleet (no `oscfg` installed yet - that's fine): - -1. Paste the Linux YAML into the editor. -2. **Register** - succeeds, with a `warnings[]` entry: *"Manifest - targets `linux`, host is `windows` - deploy from a Linux - machine."* -3. The manifest now lives in `~/.configforge/manifests/.json`. - In either edition, you can run [Diff](../user-guide/matrix-diff.md), score - it against [CIS](../user-guide/cis-compliance.md), and export an - [audit-pack](../user-guide/audit-pack.md) - none of which need `oscfg`. -4. **Deploy** is rejected on the Windows machine (`'CLI_REQUIRED'` - if the CLI isn't installed; `'mixed'`/platform-mismatch if it - is). Install the target device's OSConfig CLI from - , then move - the registration JSON + source YAML to a Linux box (or re-register - there) to deploy. - -> **Tip:** Snapshots and history work in the authoring phase too - -> nothing about [version history](../user-guide/history-snapshots.md) -> needs `oscfg` or the OS to match. +To draft a Linux baseline on Windows or macOS: + +1. Select **Microsoft Baselines → Linux Security Baseline → Use as Template**. +2. Review and **Register Baseline**. A host/target warning does not mean a + device has been changed. +3. Use Diff, history, rationale, and Audit Pack while reviewing the draft. +4. Export YAML and import it into the Full edition on a disposable Linux + machine when you are ready for device evaluation. +5. Install the CLI there, run **Audit** first, and inspect unread settings and + noncompliance. Only choose **Enforce** after reviewing the intended changes + and recovery plan. + +## Azure Machine Configuration is a separate path + +For Azure Policy evaluation, export **MOF** and follow +[Deploy through Azure Machine Configuration](../user-guide/machine-configuration.md). +Package creation requires **PowerShell 7**, the **GuestConfiguration** toolkit, +and the **Microsoft.OSConfig PowerShell module 1.4.10 or later** on the +packaging machine. Version 1.4.10 refers to the module, not the runtime. + +The guide binds the MOF to an exact installed module version, creates an +Audit-first ZIP, tests it, and then covers hosting and policy assignment. +None of those steps is required for authoring or Audit Pack export. diff --git a/docs/src/quick-start/first-manifest.md b/docs/src/quick-start/first-manifest.md index 95dd406..248cd8c 100644 --- a/docs/src/quick-start/first-manifest.md +++ b/docs/src/quick-start/first-manifest.md @@ -1,15 +1,64 @@ -# Your first manifest +# Your first baseline -Once `npm run desktop:dev` has opened the ConfigForge window -(or you're running an installed build), register a tiny manifest -end-to-end so you can confirm the round-trip works before authoring -anything real. No CLI install required - registration works in -Editor mode. +**Goal:** save your own baseline in My Baselines and export a YAML copy. +Nothing in this walkthrough deploys settings or audits a device. +Use either edition of the [installed app](./install-run.md); no CLI, +administrator access, or Azure subscription is required. -## Minimal Windows manifest +A **baseline** is a set of desired settings. A **manifest** is the YAML or JSON +document describing them. **Register** means save it in ConfigForge. -Save this as `hello.osc.yaml` (or just paste it directly into the -editor - you don't have to write it to disk first): +## Start from a Microsoft baseline + +1. Open ConfigForge. If the Welcome dialog appears, choose **Author baselines + anywhere**. +2. Open **Microsoft Baselines** in the sidebar. +3. Choose a baseline to explore and select **Use as Template**. This opens an + editable copy; you are not changing the bundled template. +4. Give the copy a unique name, such as `my-first-baseline`. +5. Review its settings in **Visual** or **Code**. You can save the unchanged + copy first; you do not need to edit a security setting to complete this step. + +![Microsoft Baselines catalog](https://raw.githubusercontent.com/Azure/ConfigForge/main/docs/images/screenshots/library.png) + +## Register + +1. Select **Register Baseline**. +2. Confirm the success message, then open **My Baselines** and find your copy. +3. Open the baseline and select **Export → YAML**. +4. Save the `.osc.yaml` file. Keep it for review or import into another + ConfigForge workspace. + +**Success:** your copy appears in My Baselines and the exported file contains +a `resources:` list. Registration is local; it does not apply settings or +publish to Azure. **Not audited** is expected for a new baseline. + +If registration reports a schema error, correct it before continuing. A +platform-mismatch or unsupported-type warning means the draft needs review +before device use—not that the baseline has been tested. + +## Try one edit + +Open your saved copy, select **Edit**, and use **Visual** to change a value. +Select **Save** and record a short reason if prompted. Use **History** to +review changes and **Export** to save the updated baseline. +See the [editor guide](../user-guide/manifest-editor.md) for typed values, +keyboard navigation, and Code mode. + +![Visual baseline editor](https://raw.githubusercontent.com/Azure/ConfigForge/main/docs/images/screenshots/visual-builder.png) + +## Other starting points + +In **My Baselines**, select **Create new baseline**. The setup page offers a +custom Windows/Linux baseline, a library template, a baseline file, a settings +spreadsheet, or a public URL. **Create baseline** opens the editor for review +before registration. + +### Minimal Windows manifest + +For a small example instead of a full template, choose **Create my own +baseline**, select Windows, and select **Create baseline**. Give it the name +`hello`, switch to Code/YAML, and replace the starter content with: ```yaml resources: @@ -22,87 +71,48 @@ resources: value: "1" ``` -> **Tip:** YAML is two-space-indented; tabs are rejected by the -> parser. The `resources:` key must be a **top-level array**, not a -> string or map. `Microsoft.Windows/Registry` resources must declare -> all three of `keyPath`, `valueName`, and `valueType`. See -> [Reference → Manifest schema](../reference/manifest-schema.md) for -> the full grammar. +Register and export it as above. This is an **authoring example**, not a +recommended security control. Applying it later would change the registry. +YAML uses spaces, not tabs; `resources:` must be a top-level array. -## Minimal Linux manifest +### Minimal Linux manifest -```yaml -resources: - - name: hello-cfs-osconfig - type: Microsoft.OSConfig/Test - properties: - resource: SshdConfig - expression: "PermitRootLogin == 'no'" - compliance: equal -``` - -## Register - -In the UI: - -1. Open **My Baselines** in the sidebar, then click **Register New**. -2. Paste your YAML, upload a `.osc.yaml` / `.json` / `.csv` file, or - edit settings directly in the Visual spreadsheet. -3. Pick the target platform (Windows or Linux). The editor's - validation adjusts accordingly. -4. Click **Register Baseline**. - -You should see a success banner and the manifest in the list. If -you're authoring a Windows manifest on Linux (or vice versa), you'll -get a soft `warnings[]` entry instead of a hard error - that's by -design (see [Architecture → Registration semantics](../architecture/registration-semantics.md)). - -To open the editor afterwards: **My Baselines → click the baseline row**. -The detail/editor view loads with Code / Visual modes, -version history, and the **Audit Pack** button in both editions. The Full -edition also shows device deploy/audit controls gated on CLI presence. +For Linux, choose **Create my own baseline → Linux** and review the generated +starter in Code or Visual. Alternatively, use the bundled **Linux Security +Baseline** through **Microsoft Baselines → Use as Template**. +Treat starter values as examples, not a deployment recommendation. +You can author Linux settings on Windows or macOS without a Linux device. ## Confirm via CLI (optional) -If you have the OSConfig CLI installed and want to cross-check what -ConfigForge wrote into the namespace, open an elevated PowerShell -(or `sudo` shell on Linux): +A registered baseline is saved in **ConfigForge**, not automatically in an +`oscfg` namespace. `oscfg get namespace` is therefore not a check that this +authoring walkthrough succeeded. Confirm the saved baseline in My Baselines +and its exported YAML instead. -```text -$ oscfg get namespace -hello - -$ oscfg get resource -n hello -hello-cfs-registry Microsoft.Windows/Registry ... -``` - -> **Note:** `oscfg` doesn't always emit machine-readable output in -> the preview build. ConfigForge wraps the CLI to scrub the -> telemetry preamble and surface only the payload - see -> [Architecture → `oscfg` CLI contract](../architecture/oscfg-cli.md). +For a separate local lab evaluation, follow +[Authoring vs deploying](./authoring-vs-deploying.md). ## Inspect the on-disk state +For a baseline registered as `hello`, ConfigForge stores: + ```text ~/.configforge/manifests/ ├── hello.json ← registration metadata -└── hello.source.yaml ← lossless source manifest +└── hello.source.yaml ← source manifest ``` -The `.json` file holds the platform-detection result, resource -summary, and any soft warnings. The `.source.yaml` is the YAML you -posted; it's what the Export action returns and what the -[Audit-pack](../user-guide/audit-pack.md) embeds. +Prefer **Export → YAML** for moving a baseline to another computer, then import +it there. Do not copy live registration metadata to simulate a deployment. ## Next steps -- Try the [editor](../user-guide/manifest-editor.md) to build a - manifest from a form rather than YAML. -- Compare manifests on the [Diff page](../user-guide/matrix-diff.md): - Pairwise, CIS Diff, or Matrix. -- Score a manifest against a CIS benchmark using - [Benchmark Mapping](../user-guide/cis-compliance.md) (requires - user-supplied CIS data files - see that page for setup). -- Install the OSConfig CLI from the - [OSConfig CLI docs](https://github.com/microsoft/osconfig/tree/main/docs/cli) - to light up Deploy / Audit / Revert in the Full edition. +- [Compare baselines](../user-guide/matrix-diff.md) without extra tools. +- Add your own licensed data for [Benchmark Mapping](../user-guide/cis-compliance.md). + Coverage is not proof of device compliance. +- Export an [Audit Pack](../user-guide/audit-pack.md) for review. It does not + run a device audit. +- Only when you need a lab evaluation, choose [local device + operations](./authoring-vs-deploying.md) or [Azure Machine + Configuration packaging](../user-guide/machine-configuration.md). diff --git a/docs/src/quick-start/install-run.md b/docs/src/quick-start/install-run.md index 5171d68..f830ecc 100644 --- a/docs/src/quick-start/install-run.md +++ b/docs/src/quick-start/install-run.md @@ -1,116 +1,131 @@ # Install & run -ConfigForge is an Electron 42 + React 18 + FluentUI v9 + Vite desktop app. The -**Full** edition runs on Windows and Linux and includes authoring plus -CLI-gated device deploy/audit/revert. The **Author** edition is an ARM64-only -Apple Silicon macOS build. It includes authoring, Microsoft Baselines, Diff, -Benchmark Mapping, history, rationale, and Audit Pack export while omitting -device operations. The native `oscfg` CLI is **not bundled** and is **not -required** for authoring in either edition. - -The current Windows/Linux release is `v0.3.103`. The current macOS Author -release is `mac-v0.3.101-author.1`; both are published as prereleases. The -package versions are `0.3.103` for the Full edition and `0.3.101-author.1` -for the macOS Author edition. +Download the desktop app to start authoring. **You do not need Node.js, the +OSConfig CLI, PowerShell modules, administrator access, or an Azure subscription +to author baselines.** Installing software may still require approval on a +managed computer. + +> ConfigForge is experimental, community-maintained, provided as-is, and not +> intended for production use. It is not an officially supported Microsoft +> product. ## Prerequisites -| Requirement | Notes | -| --- | --- | -| **Node.js 22 LTS** | The repo pins Node 22 via `.nvmrc`. Run `nvm use` (or upgrade your Node) so `node --version` reports `v22`. | -| **`oscfg` CLI binary** *(optional)* | Only needed for Deploy / Audit / Revert in the Full edition. Install separately from the [OSConfig CLI docs](https://github.com/microsoft/osconfig/tree/main/docs/cli). | -| **Admin / root** *(optional)* | Required on Windows for *every* CLI operation (preview-CLI bug - see [Operations → Filing upstream bugs](../operations/upstream-bugs.md)). On Linux, only `oscfg apply` needs `sudo`. | +| Your computer | Edition and download | Capabilities | +| --- | --- | --- | +| Windows/Linux x64 | [Full v0.3.103](https://github.com/Azure/ConfigForge/releases/tag/v0.3.103) | Authoring and review; optional CLI-based local device operations | +| macOS, Apple Silicon (M1 or later) | [Author mac-v0.3.101-author.1](https://github.com/Azure/ConfigForge/releases/tag/mac-v0.3.101-author.1) | Authoring and review, including Audit Pack export; no device operations | -## Get the code +Both are prereleases. macOS is ARM64-only: Intel Macs and universal binaries +are not supported. -```bash -git clone https://github.com/Azure/ConfigForge.git -cd ConfigForge -``` +## Download and install -> **Note:** `main` is the active Windows/Linux Full-edition line. On an Apple -> Silicon Mac (M1 or later), users can build the -> `mac-v0.3.98-author.1` tagged source while the matching release remains -> unpublished. Intel Macs and universal binaries are not supported. -> macOS release builds are unsigned by design. Clear quarantine after -> copying the app into Applications: -> -> ```bash -> xattr -cr "/Applications/ConfigForge Author.app" -> ``` +1. Open the release for your edition and expand **Assets**. +2. Download the installer or portable archive for your OS and the release's + checksum manifest. Do not choose the source-code archive unless you plan + to build the app. +3. Verify the asset's SHA-256 against the published checksum and follow the + platform-specific [installation instructions](https://github.com/Azure/ConfigForge/blob/main/INSTALL.md#install-the-desktop-app). +4. Open ConfigForge normally. Authoring does not require elevation. -## Install dependencies +**Downloads are unsigned; macOS builds are not notarized.** Checksum matching +does not establish publisher identity or safety. Review warnings, use only +approved per-file exceptions, and do not disable SmartScreen or Gatekeeper +globally. On managed computers, ask your administrator if blocked. +The [installation guide](https://github.com/Azure/ConfigForge/blob/main/INSTALL.md) +explains the risks and platform-specific options. -```bash -npm ci -``` +## Verify -Use `npm ci` (not `npm install`) for a clean, lockfile-faithful -install. The `postinstall` script runs `scripts/chmod-oscfg.js`, -which marks any developer-supplied `oscfg` binary under -`resources/oscfg/linux-x64/` executable (no-op on Windows and when -no binary is present - most users don't drop one in). +1. If the Welcome dialog appears, choose **Author baselines anywhere**. +2. Open **Microsoft Baselines** and confirm the catalog appears. +3. Follow [Your first baseline](./first-manifest.md) to register and export + a copy. -## Run +In the Full edition, **Editor mode, CLI not installed** is a valid state—not +an installation failure. You can ignore it while authoring. macOS Author +intentionally omits CLI-health and device-operation controls. -```bash -npm run desktop:dev -``` +## Optional tools -This runs Vite (renderer) + Electron in parallel with hot-reload and -opens the ConfigForge window. There is **no browser URL** - -the UI lives entirely in the Electron window. `npm run dev` is not a -script; the Next.js host was retired in Phase 10. +- **Local device Audit/Deploy/Revert:** Full edition, a matching Windows/Linux + host, and the separately installed `oscfg` CLI. Windows CLI operations + require elevation. See [Authoring vs deploying](./authoring-vs-deploying.md). +- **Azure Machine Configuration packaging:** PowerShell 7, GuestConfiguration, + and the **Microsoft.OSConfig PowerShell module 1.4.10 or later** on the + packaging machine. Version 1.4.10 is **not** the PowerShell runtime version. + See the [complete packaging guide](../user-guide/machine-configuration.md). +- **Benchmark Mapping:** your own legally licensed benchmark data. + See [data setup](../user-guide/cis-compliance.md). -> **Warning:** On Windows, **launch from an elevated PowerShell** if -> you plan to exercise Deploy or Audit. The preview `oscfg` CLI opens -> its log file in a protected directory on every invocation, -> including read-only audits, so a non-admin run fails at the first -> CLI call. Editor-mode flows (author, diff, import/export, -> audit-pack PDF) work fine without elevation. +## Updating -## Verify +Read the [release notes](../changelog.md), back up your workspace at +`~/.configforge/`, and install the new release for the **same edition**. +Recheck the release checksum and unsigned-download guidance. +The workspace holds baselines, history, rationale, and available audit results. +See [privacy and local storage](https://github.com/Azure/ConfigForge/blob/main/PRIVACY.md). -In the running app: +## Build from source (optional) -1. Look at the footer health pill. It should read either - 🟢 **OSConfig CLI v…** (CLI installed) or - 🟠 **Editor mode, CLI not installed** (default first-run state). - Both are valid; only the second blocks Deploy. -2. Open **Settings → System Health** for the resolved CLI path, - source (`env` / `installed` / `path` / `msix` / `bundled`), and - admin status. Click **Recheck** if you just installed the CLI. -3. Open **My Baselines → Register New** and paste the - [first-manifest example](./first-manifest.md). It should register - with zero errors. +For contributors or readers choosing to build reviewed source. These commands +are **not** needed for the downloaded app. -If the System Health panel says `binary not found`, install the CLI from -the [OSConfig CLI docs](https://github.com/microsoft/osconfig/tree/main/docs/cli), -or set `$env:OSCFG_BIN` / `$OSCFG_BIN` to point at a local copy and -click **Recheck**. +### Get the code -## Build a desktop installer +Use Node **22.12+ LTS** or **24 LTS** and Git. `.nvmrc` and `.node-version` +select the default Node 22 toolchain. -```bash -npm run desktop:build # core + renderer + electron main -npm run desktop:dist # full installer (Win or Linux per host) +```powershell +git clone https://github.com/Azure/ConfigForge.git +cd ConfigForge ``` -See [`apps/desktop/PACKAGING.md`](../../../apps/desktop/PACKAGING.md) -for the cross-platform build matrix and unsigned-build trust guidance. +### Install dependencies -## Updating +Choose the correct branch **before** restoring dependencies: + +```powershell +# Windows or Linux Full edition +git checkout main +node --version +npm ci +``` -The repo is plain `git pull`-able: +For Apple Silicon macOS: ```bash -git pull +git checkout mac-author-build +node --version npm ci +``` + +The version check must report Node 22.12+ or 24.x. Use `npm ci` for a +lockfile-faithful install. If dependencies were installed under an unsupported +Node release, switch to the supported toolchain, remove `node_modules`, and +run `npm ci` again. + +### Run + +Windows/Linux Full: + +```powershell npm run desktop:dev ``` -No database, no migration step. Runtime state lives in -`~/.configforge/` (manifests, history, rationale, audit-results); it -is backwards-compatible across releases. Core authoring and analysis work -offline. Supported update checks and user-requested public URL imports use the -network as described in [`PRIVACY.md`](../../../PRIVACY.md). +Apple Silicon macOS Author: + +```bash +npm run dev:author -w @configforge/desktop +``` + +These commands open Electron with hot reload; there is no browser URL. +Launch without elevation for authoring. For contributor setup and validation, +see [CONTRIBUTING.md](https://github.com/Azure/ConfigForge/blob/main/CONTRIBUTING.md). + +## Build a desktop installer + +See [desktop packaging](https://github.com/Azure/ConfigForge/blob/main/apps/desktop/PACKAGING.md) +for Windows/Linux and macOS Author commands, build-host requirements, and smoke +checks. A source build remains unsigned unless you arrange your own signing. diff --git a/docs/src/reference/glossary.md b/docs/src/reference/glossary.md index e442ec2..d776512 100644 --- a/docs/src/reference/glossary.md +++ b/docs/src/reference/glossary.md @@ -16,11 +16,26 @@ baselines before the CLI catches up - it just isn't called ## Audit-pack -A single self-contained document (PDF or Markdown) per manifest, -bundling header / compliance scorecard / version history / -rationale log / analysis provenance. The auditor deliverable. See +A PDF or Markdown review report per baseline, built from available saved +metadata, comparison results, device results, history, and rationale. +Exporting it does **not** run a device Audit. Missing data is omitted; live +analysis provenance is not currently persisted, so its citations are absent +from normal UI-generated reports. See [User Guide → Audit-pack](../user-guide/audit-pack.md). +## Audit + +A local device check through the `oscfg` CLI in the Full edition. Distinct +from authoring validation, benchmark coverage, and Audit Pack export. Inspect +the result timestamp and unread/indeterminate settings before using it as +evidence. + +## Baseline + +A set of desired configuration settings. ConfigForge stores and edits it as +a [manifest](#manifest). A baseline is not a statement that a device currently +has those settings. + ## BYO-CLI "Bring-your-own-CLI." The v0.2.0 shift: the `oscfg` binary is **no @@ -41,8 +56,10 @@ Center for Internet Security - publishes the ConfigForge **does not redistribute** CIS Benchmark content (license restrictions). The cross-reference and compliance features work when a user drops their own legally licensed catalog files into -`public/_baselines/cis/_data/`. The app resolves the CIS data directory path at runtime; the Benchmark Mapping page shows the resolved location for each install type. The UI gracefully hides every CIS -surface when those files are absent. See +the data directory shown on Benchmark Mapping. The app resolves that directory +for your installation. The UI hides the data-dependent CIS drawer and Diff +tab when those files are absent. The Benchmark +Mapping setup page remains visible. See [User Guide → CIS compliance](../user-guide/cis-compliance.md). ## Benchmark Mapping @@ -51,11 +68,16 @@ The sidebar page (route `/cis`) for benchmark-data ingestion and status. It show ## CIS Diff -A tab on the Diff page that annotates matrix-diff rows with CIS rule coverage. Powered by `cfs:cis:bulk-lookup` IPC. Shows which settings in the comparison matrix map to CIS benchmark rules and their severity. Requires CIS data to be present (see [Benchmark Mapping](#benchmark-mapping)). +A tab on the Diff page that compares one baseline with a supplied benchmark. +It shows covered/missing benchmark rules and matched settings; it is separate +from Matrix (N-way). Requires CIS data (see [Benchmark Mapping](#benchmark-mapping)). ## Azure Policy CIS JSON -The JSON format exported from the Azure portal containing CIS benchmark rule mappings for guest configuration policies. ConfigForge ingests these files on the Benchmark Mapping page alongside XCCDF files. Each JSON carries a `settingsReference[]` array that maps policy settings to CIS rule IDs. +A supported JSON settings catalog with a `settingsReference[]` array mapping +policy settings to benchmark rules. It is not an arbitrary Azure Policy +definition or assignment export. ConfigForge reads it alongside XCCDF data +from the Benchmark Mapping folder. ## Change summary @@ -101,6 +123,9 @@ Diff page's CIS Diff tab uses `cfs.cis.bulkLookup`, where compliance is unique CIS benchmark rules covered / total benchmark rules, with XCCDF and Azure Policy CIS matching. +These are baseline-comparison/coverage measures, not device audits or +certification. Matching a rule does not by itself prove its value agrees. + ## Cross-platform manifest A manifest with no platform-specific resource types - typically @@ -153,8 +178,8 @@ this host is windows" warning. ## Manifest -The YAML/JSON document describing what to apply. The unit of -registration. See +The YAML/JSON document describing a baseline's desired settings. Registering +the document saves it locally; it does not apply the settings. See [Reference → Manifest schema](./manifest-schema.md). ## Master matrix @@ -177,11 +202,26 @@ uses the same word. ## oscfg -The native upstream CLI. Replaces the `Microsoft.OSConfig` -PowerShell module that older editions used. ConfigForge **never** -calls the PowerShell module - only the binary. Targeted version: -`oscfg 1.3.9-preview11`. Since v0.2.0 the binary is no longer -bundled (see [BYO-CLI](#byo-cli)). +The native upstream CLI used by the Full edition for local device operations. +Targeted version: `oscfg 1.3.9-preview11`. The binary is not bundled (see +[BYO-CLI](#byo-cli)). It is not the PowerShell resource module or the +GuestConfiguration packaging toolkit. + +## Microsoft.OSConfig PowerShell module + +Supplies the OSConfig DSC resource for Azure Machine Configuration packages. +**Version 1.4.10 or later is required on the packaging machine** when creating +a package from a ConfigForge-exported MOF. This is a module version, not a +PowerShell runtime version. The app itself does not need this module for +authoring or its CLI-based local operations. + +## GuestConfiguration + +The separate PowerShell toolkit providing `New-GuestConfigurationPackage`, +package testing, and policy generation. It runs in the required +**PowerShell 7** environment and bundles the exact Microsoft.OSConfig module +version referenced by the resolved MOF. See +[Machine Configuration packaging](../user-guide/machine-configuration.md). ## Phase A→E page split diff --git a/docs/src/user-guide/audit-pack.md b/docs/src/user-guide/audit-pack.md index 1de937d..d282e09 100644 --- a/docs/src/user-guide/audit-pack.md +++ b/docs/src/user-guide/audit-pack.md @@ -1,78 +1,48 @@ # Audit-pack (PDF + Markdown) -> **v0.3.48:** the audit-pack works without OSConfig installed in the -> Full edition. It -> reads from the manifest store, history, rationale log, and -> persisted device-audit snapshots, none of which require the CLI to -> be present at generation time. (If you haven't run an Audit yet, the -> Device-Audit section is simply omitted from the pack; install -> OSConfig and run an audit to populate it.) -> -> Both the PDF and the Markdown emitter pass user-supplied and -> generated content through the -> [`packages/core/src/markdown/escape.ts`](https://github.com/Azure/ConfigForge/blob/main/packages/core/src/markdown/escape.ts) -> guard (CF-SEC-005 / CF-SEC-006), so HTML / Markdown injection -> embedded in a manifest name, rationale entry, or generated suggestion is -> rendered as literal text. - -The audit-pack is the auditor deliverable: a single self-contained -document per manifest that answers *what's deployed?*, *how does it -score?*, and *who changed what?*. If persisted analysis provenance is added -later, citations can render too; today live analysis provenance is not stored -per manifest. +Use **Audit Pack** to export a baseline review report as PDF or Markdown. +It is available in **both Full and macOS Author editions**, without the +OSConfig CLI, packaging modules, or Azure. + +**An Audit Pack is not a device Audit.** It assembles available saved baseline +metadata, review results, history, and rationale. It does not inspect a +machine, apply settings, or establish current compliance. If no saved device +audit exists, that section is omitted; macOS Author cannot run device audits. +Benchmark coverage likewise does not prove device compliance. ## Generate In the UI: -1. Open any manifest's detail view. -2. Click **Audit Pack** (top-right action bar). Lands on the - `audit-pack` sub-page for that manifest. -3. Choose **PDF** (primary) or **Markdown** (secondary). A live PDF +1. Open a saved baseline from **My Baselines**. +2. Select **Audit Pack** to open the report page. +3. Choose **Download PDF** or **Download Markdown**. A PDF preview renders inline. -The PDF and Markdown forms are served by the same `cfs:audit-pack:get` -IPC handler (and `cfs:audit-pack:save` for the file-system "Save as…" -flow). PDFs come back as `application/pdf`; Markdown as -`text/markdown; charset=utf-8`. +Before sharing, check which sections are present, the baseline identity, and +any device-result timestamps. Report unavailable or stale evidence explicitly. +Export **YAML** separately if the recipient also needs the baseline source. +Review names, rationale, and device details for sensitive information. ## What's in it (PDF) -The PDF builder lives in -[`packages/core/src/audit-pack/`](https://github.com/Azure/ConfigForge/blob/main/packages/core/src/audit-pack/index.ts). -The PDF is assembled in this fixed order: +Sections appear only when their input is available: | # | Section | Source data | Behaviour without source | -| - | --- | --- | --- | +| --- | --- | --- | --- | | 1 | **Title page** | manifest name, OS, last-applied / last-audited timestamps | always present | | 2a | **Device-audit snapshot** (v0.1.6) | last persisted `auditResults` run for this manifest (audit or enforce) | section omitted when no audit has been run | | 2b | **Compliance scorecard** | `ComplianceReport` (only when a local CIS comparison is requested) | section omitted when no comparison is requested | | 3 | **Version history** | history snapshots + author/rationale | author/rationale columns render `(none)` if absent; max 50 rows | | 4 | **Rationale log** | `~/.configforge/rationale/.jsonl` (loaded by `tryLoadRationale` in `audit-pack/rationale-loader.ts`) | section omitted if log empty; otherwise newest-first with timestamp + author + resource + reason (skipped entries appear with a `(rationale skipped)` sentinel) | -| 5 | **Analysis provenance citations** | analysis `Provenance` bundle | section omitted. See "Known gaps" below | +| 5 | **Analysis provenance citations** | analysis `Provenance` bundle | section omitted. See the known-gap note below | | – | **Footer** | generation timestamp, page numbers | always present | -> **Note:** The audit-pack is intentionally forward-compatible. If a -> manifest was authored before rationale capture existed, the -> version-history table omits the author/rationale columns rather -> than rendering empty cells. Each section is wrapped in a -> `safeSection` guard. A render failure in one section drops a -> "(section unavailable)" line and the rest of the document still -> emits. -> -> **⚠ Known gap, analysis provenance:** The PDF builder accepts a -> `provenance` input, but there is **no per-manifest provenance -> store**. The type layer + helpers ship in -> `@configforge/core/ai/provenance` (`decorateWithProvenance`, -> `dedupeSources`, `computeCitationCoverage`). Provenance is -> attached to live analysis results inside the analyzer, but never -> persisted to disk. The audit-pack handler's `tryLoadProvenance` -> therefore always returns `undefined` and the **Citations** section -> is omitted from every audit pack today. Wiring this up requires (a) -> deciding the storage shape, (b) hooking the analyzer to append on -> each analysis result, (c) hooking the manifest editor's "accept -> suggestion" flow to persist alongside the manifest snapshot. Until -> then the Citations section will not render. +> **Known gap: analysis provenance.** Live analysis provenance is not stored +> per baseline, so normal UI-generated Audit Packs omit the Citations section. +> Do not describe the report as a complete cited evidence record. +> A report can also contain a "(section unavailable)" message if a section +> could not render; review the output, not just whether a file downloaded. ## What's in it (Markdown) @@ -85,10 +55,18 @@ Markdown output (CF-SEC-005 / 006). ## Implementation notes +These details are for contributors; they are not required to export a report. + - The builder uses `pdfkit` for PDF output. - The artifact handler returns PDF bytes or Markdown text through the same `cfs:audit-pack:get` / `cfs:audit-pack:save` IPC surface. - Fonts: built-in Helvetica + Helvetica-Bold to avoid font-bundling. +- PDF and Markdown output escape user-supplied/generated text through + [`escape.ts`](https://github.com/Azure/ConfigForge/blob/main/packages/core/src/markdown/escape.ts). +- The handler can accept provenance, but `tryLoadProvenance` returns + `undefined` until a per-baseline provenance store is implemented. See + [analysis provenance](./analysis-provenance.md) and the + [API reference](../api-reference/audit-pack.md). ## Customizing @@ -106,12 +84,13 @@ The audit-pack is intentionally opinionated. Two practical knobs: A quick "is this really a PDF?" check on a saved file: ```powershell -Get-Content audit-pack.pdf -TotalCount 1 -Encoding Byte | ForEach-Object { '{0:X2}' -f $_ } -# 25 50 44 46 ... → %PDF- +[System.IO.File]::ReadAllBytes((Resolve-Path '.\audit-pack.pdf').Path)[0..3] | + ForEach-Object { '{0:X2}' -f $_ } +# 25 50 44 46 → %PDF ``` -The first four bytes are always the magic `%PDF-`; tests assert -this rather than parse the binary. +These four bytes spell `%PDF`. This is only a file-format check, not +validation that the report is complete or that a device is compliant. ## See also diff --git a/docs/src/user-guide/cis-compliance.md b/docs/src/user-guide/cis-compliance.md index 0d13d01..2695c6a 100644 --- a/docs/src/user-guide/cis-compliance.md +++ b/docs/src/user-guide/cis-compliance.md @@ -1,18 +1,22 @@ # Benchmark Mapping with CIS data -> ⚠️ **Important:** ConfigForge **does not bundle CIS Benchmark -> data**. The Center for Internet Security licenses CIS Benchmarks -> under terms incompatible with redistributing derived YAML / JSON / -> XCCDF artifacts in a public open-source repository. This page -> describes local/offline features that are **disabled by default** -> for data-dependent surfaces until you, the user, supply your own -> legally licensed copy of the data files locally. +Benchmark Mapping helps you find which benchmark rules correspond to the +settings in your baseline. It is an optional review tool available in both +editions; you can author and compare baselines without setting it up. + +> **Bring your own data.** ConfigForge does not bundle CIS Benchmark data. +> Supply a legally licensed copy and follow its redistribution terms. > > The editor cross-reference drawer and Diff page **CIS Diff** tab are > hidden until supported CIS data is present. The **Benchmark Mapping** > sidebar page remains visible so users can see the resolved data > folder and setup guidance. No OSConfig CLI is required. +**Coverage is not device compliance.** A rule match does not prove that the +configured value meets the benchmark, that a machine has that value, or that +the baseline is certified. Review mappings and values, and use device Audit +separately when you need a machine-state check. + ## What this feature does (when enabled) Two related but distinct features sit on top of CIS Benchmark data: @@ -40,17 +44,17 @@ it resolves under the app's public assets as `_baselines/cis/_data`. ### 1. Azure Policy CIS baseline JSON (primary, recommended) -This is the simplest and recommended path for most users. +If you already have a supported CIS settings catalog in Azure Policy JSON +format, use it directly: -1. Open the Azure portal. -2. Navigate to **Azure Policy > Machine Configuration > CIS**. -3. Download the CIS baseline JSON for your target OS. -4. Drop the downloaded JSON file into `_baselines/cis/_data` (or the - exact folder shown on the Benchmark Mapping page in the app). -5. Click **Re-check catalog** on the Benchmark Mapping page. +1. Confirm the file contains a `settingsReference` array of benchmark + settings for the OS you want to compare. An arbitrary policy definition or + assignment JSON is not a benchmark catalog. +2. Copy the JSON into the exact folder shown on **Benchmark Mapping**. +3. Select **Re-check catalog** and inspect the detected file/platform status. -The app parses the Azure Policy structure automatically. No manual -conversion is needed. +This route does not require signing in to Azure. JSON catalogs may represent +only a subset of a benchmark; coverage is relative to the data you supply. ### 2. XCCDF + OVAL XML (alternative) @@ -68,7 +72,7 @@ mapping table at startup. ### 3. Legacy OSConfig pipeline JSON (advanced) -This is the internal `cis-mappings.json` format used by earlier +This is the legacy `cis-mappings.json` format used by earlier versions of ConfigForge and the OSConfig [`mc/CIS`](https://github.com/microsoft/osconfig/tree/main/mc/CIS) scripts. It remains supported for backward compatibility. @@ -120,9 +124,9 @@ fails, the engine checks whether the resource is a recognized type: The drawer marks property-mapping matches with a verification pill so the author knows to review them. -> **Note:** A high-confidence match means the names/identity agree. It -> does **not** assert the *values* agree. That is what CIS Diff coverage -> is for. +> **Note:** A high-confidence match means the names/identity agree. Neither +> that match nor the CIS Diff coverage percentage proves that the *values* +> agree. Review the desired values and the benchmark's requirements separately. ## CIS Diff coverage report @@ -146,8 +150,8 @@ The main score is computed strictly: - `coverage = covered CIS rules / total benchmark rules * 100`. > **Tip:** `coverage == 100` means every supplied CIS rule has at least -> one matching resource. It does *not* mean your manifest is identical -> to the CIS baseline; extra hardening remains allowed. +> one matching resource. It does not mean the values are correct, that the +> manifest is identical to the benchmark, or that any device is compliant. ### When CIS data is not available @@ -165,15 +169,17 @@ badges and can switch to a Missing-from-CIS view that lists missing benchmark ru Audit Pack export supports both PDF and Markdown. Both formats include manifest metadata and can include compliance, device-audit, history, rationale, and citations when those inputs are available. Open -**Manifest > Audit Pack** and choose **Download PDF** or **Download -Markdown**, or trigger the audit-pack IPC channel with `format: 'pdf'` -or `format: 'markdown'`. +the baseline's **Audit Pack** and choose **Download PDF** or **Download +Markdown**. Generating this report does not run a device Audit. Today analysis provenance is not persisted per manifest, so the citations/provenance section is omitted in normal UI-generated audit packs. Both formats omit the CIS section gracefully when CIS data isn't available. See [Audit-pack](./audit-pack.md). +
+Developer reference: performance and data-dependent controls + ## Performance (when data is present) - Strict-match cross-reference: single `Map` lookup per resource. @@ -192,6 +198,8 @@ available. See [Audit-pack](./audit-pack.md). | `cfs.cis.lookup()` | Returns `{ name, match: null }` when data absent | | `cfs.cis.bulkLookup()` | Returns benchmark coverage data for the Diff page's CIS Diff tab; errors clearly when a selected benchmark file is unavailable | +
+ ## See also - [API Reference > Compliance](../api-reference/compliance.md) diff --git a/docs/src/user-guide/machine-configuration.md b/docs/src/user-guide/machine-configuration.md index f56be66..115865b 100644 --- a/docs/src/user-guide/machine-configuration.md +++ b/docs/src/user-guide/machine-configuration.md @@ -3,6 +3,11 @@ Use Azure Machine Configuration when you want Azure Policy to evaluate a ConfigForge baseline on Azure virtual machines or Azure Arc-enabled servers. +This is an **advanced, optional workflow**. To create and share a baseline +without Azure, start with [Your first baseline](../quick-start/first-manifest.md). +The app exports a MOF; the remaining packaging and Azure steps happen outside +ConfigForge. + The deployment path is: `ConfigForge baseline → MOF → resolved MOF → Machine Configuration ZIP → Azure Storage → policy JSON → Azure Policy definition → policy assignment` @@ -10,61 +15,100 @@ The deployment path is: ConfigForge exports the compiled MOF. You do not need to author a separate DSC configuration. -> ConfigForge is an experimental community tool. Test every package and policy -> on a disposable machine before assigning it broadly. +> ConfigForge is experimental, community-maintained, not officially supported +> by Microsoft, and not intended for production use. Test every package and +> policy on a disposable machine. Azure Machine Configuration's support status +> does not make ConfigForge or a custom baseline an officially supported product. ## Supported behavior | Package or policy mode | Purpose | Current guidance | | ---------------------------------------------------- | ---------------------------------------------- | --------------------------------------------------------------------------- | | `Audit` | Report compliance without changing the machine | Recommended default | -| `AuditAndSet` package + `ApplyAndMonitor` policy | Apply once during remediation, then monitor | Build with ConfigForge's package helper and validate on a disposable machine | -| `AuditAndSet` package + `ApplyAndAutoCorrect` policy | Reapply whenever drift is detected | Build with ConfigForge's package helper and validate on a disposable machine | +| `AuditAndSet` package + `ApplyAndMonitor` policy | Apply during remediation, then monitor drift without automatically correcting it | Advanced: validate the exact baseline/module combination before choosing this mode | +| `AuditAndSet` package + `ApplyAndAutoCorrect` policy | Reapply whenever drift is detected | Advanced: validate remediation and recovery on a disposable machine first | -Microsoft.OSConfig 1.4.3 audits ConfigForge packages successfully, but its -PowerShell DSC resource has an upstream `Set()` serialization defect. -ConfigForge's package helper applies a compatibility patch to the package copy -for `AuditAndSet`; the globally installed module remains unchanged. +This walkthrough uses **Audit**. A successful export or package build is not +evidence that every setting can be read or safely enforced. ## Prerequisites -Use PowerShell 7: +### Packaging machine + +Use a Windows or Ubuntu packaging environment with **PowerShell 7**: - Windows: PowerShell 7.1.3 or later. -- Linux: PowerShell 7.2.4 or later. +- Ubuntu 20+: PowerShell 7.2.4 or later. - Local Machine Configuration package testing is not supported on macOS. - Export the MOF on macOS, then move it to a supported packaging machine. + Export the MOF in macOS Author, then move it to a Windows/Ubuntu packaging + and test machine appropriate for the target baseline. -Install the packaging and Azure modules: +The [Microsoft Learn environment guide](https://learn.microsoft.com/azure/governance/machine-configuration/how-to/develop-custom-package/1-set-up-authoring-environment) +defines the runtime and toolkit requirements. These are separate components: -```powershell -Set-PSRepository -Name PSGallery -InstallationPolicy Trusted +| Component | Role | +| --- | --- | +| **PowerShell 7** | Runtime in which you run the packaging commands | +| **GuestConfiguration** | Toolkit providing `New-GuestConfigurationPackage`, package testing, and policy generation | +| **Microsoft.OSConfig PowerShell module 1.4.10 or later** | ConfigForge packaging prerequisite: supplies the OSConfig DSC resource that `New-GuestConfigurationPackage` bundles into the ZIP | +| **Az modules** | Azure authentication, Storage, policy definitions, and assignments | -Install-Module GuestConfiguration -Scope CurrentUser -Force -Install-Module Microsoft.OSConfig -Scope CurrentUser -Force +**1.4.10 is the Microsoft.OSConfig module version, not a PowerShell runtime +version or an `oscfg` CLI version.** The module must be installed and visible +in `$env:PSModulePath` on the machine **creating** the package. Installing the +CLI with winget does not satisfy this requirement. Neither module is required +for ordinary ConfigForge authoring. -Install-Module Az.Accounts -Scope CurrentUser -Force -Install-Module Az.Storage -Scope CurrentUser -Force -Install-Module Az.Resources -Scope CurrentUser -Force -Install-Module Az.PolicyInsights -Scope CurrentUser -Force +Install the packaging modules in PowerShell 7 using PowerShellGet: + +```powershell +Install-Module -Name GuestConfiguration -Scope CurrentUser -Repository PSGallery +Install-Module -Name Microsoft.OSConfig -MinimumVersion 1.4.10 -Scope CurrentUser -Repository PSGallery +Import-Module GuestConfiguration +Get-Command -Module GuestConfiguration ``` -Confirm which Microsoft.OSConfig version packaging will use: +Review any repository trust prompt according to your organization's policy; +you do not need to mark the whole Gallery trusted. Packaging itself does not +require elevation. Local package **testing** does. + +GuestConfiguration installs required Az dependencies; Microsoft Learn lists +Azure PowerShell 5.9.0 or later. For the publishing steps below, ensure +`Az.Accounts`, `Az.Storage`, `Az.Resources`, and `Az.PolicyInsights` are available +in that session. Follow your organization's approved installation process if +they are missing. + +Complete Learn's platform-specific **PSDesiredStateConfiguration** setup as +part of preparing the environment; it is separate from the Microsoft.OSConfig +resource module. ConfigForge already exports a compiled MOF, so you can skip +writing and compiling a separate DSC configuration for this walkthrough. + +List qualifying resource-module versions: ```powershell -Get-Module -ListAvailable Microsoft.OSConfig | +Get-Module -ListAvailable -Name Microsoft.OSConfig | + Where-Object { $_.Version -ge [version]'1.4.10' } | Sort-Object Version -Descending | Select-Object Name, Version, ModuleBase ``` +The [1.4.10 Gallery release](https://www.powershellgallery.com/packages/Microsoft.OSConfig/1.4.10) +is available. The **1.4.10+ minimum is the current ConfigForge packaging +requirement**, not a claim that all upstream baseline or remediation issues +are resolved. Validate the exact installed module and baseline you package; +historical validation against 1.4.3 does not replace this prerequisite. + +### Azure targets (needed only when assigning the policy) + Target machines need: -- Azure VM Guest Configuration extension 1.26.24 or later, or Azure Arc agent - 1.10.0 or later. +- The Machine Configuration extension for Azure VMs, or Azure Connected + Machine agent for Arc-enabled servers. Applying configurations requires + extension 1.26.24+ or Arc agent 1.10.0+. - A system-assigned managed identity when required by the selected policy. - The built-in initiative **Deploy prerequisites to enable machine configuration policies on virtual machines** assigned at or above the target - scope. + Azure VM scope. Arc-enabled servers have a separate onboarding path. ## 1. Export the MOF from ConfigForge @@ -73,7 +117,10 @@ Target machines need: 3. Select **MOF (`.mof`)**. 4. Save the file in a versioned working folder. -Example: +The examples below use a **Windows baseline on a Windows packaging/test +machine**. For Linux content, use a compatible Ubuntu environment, Linux +baseline/resources, an appropriate working directory, and `Platform = 'Linux'` +when generating the policy. Do not test Windows resources on a Linux host. ```powershell $WorkingDirectory = 'C:\ConfigForge\MachineConfiguration' @@ -81,7 +128,9 @@ $MofPath = Join-Path $WorkingDirectory 'ContosoSecurityBaseline.mof' $PackageName = 'ContosoSecurityBaseline_1_0_0' New-Item -ItemType Directory -Path $WorkingDirectory -Force | Out-Null -Test-Path $MofPath +if (-not (Test-Path -LiteralPath $MofPath -PathType Leaf)) { + throw "Export the baseline MOF to $MofPath before continuing." +} ``` Use a unique package name for every baseline release. Reusing package names or @@ -99,24 +148,34 @@ ModuleVersion = "0.0.0"; `0.0.0` is a portable placeholder so the same exported MOF can move between customer environments. Machine Configuration runtime requires the exact module version bundled into the ZIP, so resolve the placeholder on a packaging -copy before running `New-GuestConfigurationPackage`. +copy before running `New-GuestConfigurationPackage`. Select the newest installed +version that meets the **1.4.10 minimum**, and fail before editing the MOF if +none is available. Keep the selected module installed until packaging finishes. ```powershell -$InstalledOSConfig = Get-Module -ListAvailable Microsoft.OSConfig | +$InstalledOSConfig = Get-Module -ListAvailable -Name Microsoft.OSConfig | + Where-Object { $_.Version -ge [version]'1.4.10' } | Sort-Object Version -Descending | Select-Object -First 1 if (-not $InstalledOSConfig) { - throw 'Microsoft.OSConfig is not installed.' + throw 'Microsoft.OSConfig 1.4.10 or later is required on the packaging machine.' } $ResolvedMofPath = Join-Path $WorkingDirectory ` 'ContosoSecurityBaseline.resolved.mof' -(Get-Content $MofPath -Raw).Replace( +$MofContent = Get-Content -LiteralPath $MofPath -Raw -ErrorAction Stop +if (-not $MofContent.Contains('ModuleVersion = "0.0.0";')) { + throw 'Expected a fresh ConfigForge export with ModuleVersion = "0.0.0"; re-export the MOF.' +} + +$MofContent.Replace( 'ModuleVersion = "0.0.0";', "ModuleVersion = `"$($InstalledOSConfig.Version)`";" -) | Set-Content $ResolvedMofPath -Encoding utf8 +) | Set-Content -LiteralPath $ResolvedMofPath -Encoding utf8 -ErrorAction Stop + +$InstalledOSConfig | Select-Object Name, Version, ModuleBase ``` Confirm that every OSConfig instance was resolved: @@ -125,34 +184,29 @@ Confirm that every OSConfig instance was resolved: Select-String -Path $ResolvedMofPath -Pattern 'ModuleVersion' ``` -Do not replace `ModuleName = "Microsoft.OSConfig"`. +Do not replace `ModuleName = "Microsoft.OSConfig"` or leave a version range +in the MOF. It must name the **exact installed version**, not simply the +minimum. Record that version with the baseline and package release so you can +reproduce and diagnose the package later. ## 3. Create the package -Create packages through ConfigForge's package helper: +Create an Audit package with the **GuestConfiguration** cmdlet: ```powershell -$Package = & .\scripts\new-machine-configuration-package.ps1 ` +$Package = New-GuestConfigurationPackage ` -Name $PackageName ` -Configuration $ResolvedMofPath ` -Type Audit ` - -Path $WorkingDirectory ` - -Version 1.0.0 + -Path $WorkingDirectory $PackagePath = $Package.Path Get-Item $PackagePath ``` -For enforcement, use `-Type AuditAndSet`. The helper patches the package copy -of Microsoft.OSConfig's DSC `Set()` boundary so Registry properties are passed -to `oscfg` as compressed JSON. Microsoft.OSConfig 1.4.3 otherwise converts the -property object to a PowerShell hashtable string such as `@{keyPath=...}`, -which the Registry provider rejects as missing `keyPath`. - -The helper does not modify the globally installed PowerShell module. It fails -closed if either expected wrapper copy is missing or no longer matches the -known vulnerable/fixed implementation. Remove this compatibility patch after -an upstream Microsoft.OSConfig release includes the JSON serialization fix. +The source baseline, exact module version, and package name together identify +what you are testing. Use a new name/version for changed content; do not +overwrite a published ZIP. The ZIP contains: @@ -160,7 +214,21 @@ The ZIP contains: - Guest Configuration runtime metadata. - The installed Microsoft.OSConfig module. -Keep the uncompressed package below 100 MB. +Do not include secrets or confidential content. Keep the uncompressed package +below 100 MB. + +### Historical 1.4.3 compatibility helper + +The repository retains +[`scripts/new-machine-configuration-package.ps1`](https://github.com/Azure/ConfigForge/blob/main/scripts/new-machine-configuration-package.ps1) +and its tests for the historical Microsoft.OSConfig **1.4.3** `Set()` +serialization workaround. It patched the packaged wrapper copies, not the +globally installed module. + +**Do not apply that old patch to 1.4.10+ packages.** It is not part of this +current packaging walkthrough and is not evidence that a newer module needs +the same workaround. If a new package fails, capture the exact module version +and non-sensitive error details, then investigate rather than modifying the ZIP. ## 4. Test the package locally @@ -178,14 +246,26 @@ baseline. For example, the ConfigForge Windows Server 2025 Workgroup Member baseline produces 296 resource results. -For an `AuditAndSet` package, test remediation only on a disposable machine: +Inspect unread/error results as well as the total count. A completed command +alone is not a passing audit. Preserve the report alongside the exact package +and module version. These instructions are not a live-test record for your +environment or for every 1.4.10+ module/baseline combination. + +**Optional enforcement evaluation:** only after reviewing the baseline and +Audit results, create a separate package with `-Type AuditAndSet`. The next +command **changes the local machine**. Use a disposable matching-platform +machine with a recovery plan; do not run it on your authoring workstation. +Set the following path to your separately created `AuditAndSet` ZIP (not the +Audit package from step 3): ```powershell +$EnforcementPackagePath = '' + Start-GuestConfigurationPackageRemediation ` - -Path $PackagePath ` + -Path $EnforcementPackagePath ` -Verbose -Get-GuestConfigurationPackageComplianceStatus -Path $PackagePath +Get-GuestConfigurationPackageComplianceStatus -Path $EnforcementPackagePath ``` ## 5. Optional: sign the package @@ -253,12 +333,17 @@ if (-not (Get-AzStorageContainer ` $BlobName = Split-Path $PackagePath -Leaf +if (Get-AzStorageBlob -Container $ContainerName -Blob $BlobName ` + -Context $StorageContext -ErrorAction SilentlyContinue) { + throw 'This blob name already exists. Use a new package name/version; do not overwrite it.' +} + Set-AzStorageBlobContent ` -Container $ContainerName ` -File $PackagePath ` -Blob $BlobName ` -Context $StorageContext ` - -Force | Out-Null + -ErrorAction Stop | Out-Null $StartTime = (Get-Date).AddMinutes(-5) $ExpiryTime = $StartTime.AddYears(1) @@ -332,7 +417,7 @@ The definition appears under **Azure Policy > Definitions**. ## 9. Assign the policy -Assign the prerequisite initiative first: +For Azure VMs, assign the prerequisite initiative first: **Deploy prerequisites to enable machine configuration policies on virtual machines** @@ -374,10 +459,10 @@ show NonCompliant while the guest assignment is still Pending. | Symptom | Resolution | | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | | `Publish-GuestConfigurationPackage` is not recognized | Upload with `Set-AzStorageBlobContent`. | -| `Microsoft.OSConfig` cannot be found | Install it in the PowerShell 7 module path and recreate the ZIP. | -| More than one Microsoft.OSConfig version is installed | The resolution step selects the newest version. Remove older copies if you require a different deterministic version. | +| No qualifying `Microsoft.OSConfig` module is found | Install **1.4.10 or later** in the packaging session's PowerShell 7 module path, then rerun resolution and create a new ZIP. Installing the CLI is not sufficient. | +| More than one Microsoft.OSConfig version is installed | Resolution selects the newest installed version **at least 1.4.10**. Record it and verify that exact version is bundled; older copies do not satisfy the minimum. | | Runtime says module version `0.0.0` does not exist | Package the resolved MOF, not the portable exported MOF. | -| Deployment reports `missing field keyPath` with properties like `{"@{keyPath": ...}` | Recreate the `AuditAndSet` ZIP with `scripts/new-machine-configuration-package.ps1`; vanilla Microsoft.OSConfig 1.4.3 packages retain the upstream DSC serialization defect. | +| Deployment reports `missing field keyPath` with properties like `{"@{keyPath": ...}` | Check the module version inside the ZIP and the exported properties. Rebuild old packages using the current prerequisite, resolve the MOF, and retest. Do not apply the historical 1.4.3 patch to 1.4.10+; report remaining failures with a minimal non-sensitive reproduction. | | Local compliance fails with access errors | Run PowerShell 7 elevated or through `sudo`. | | Package download returns HTTP 403 | Renew the SAS URI or correct Storage Blob Data Reader access. | | The extension rejects the package hash | Upload a new ZIP and regenerate the policy. Do not alter the existing ZIP. | @@ -386,6 +471,8 @@ show NonCompliant while the guest assignment is still Pending. ## Microsoft Learn references +- [Microsoft.OSConfig 1.4.10 on PowerShell Gallery](https://www.powershellgallery.com/packages/Microsoft.OSConfig/1.4.10) — module availability; the minimum above is ConfigForge guidance. +- [Install-Module parameters (PowerShellGet)](https://learn.microsoft.com/powershell/module/powershellget/install-module?view=powershellget-2.x) — `-MinimumVersion` selects that version or later. - [Develop a custom Machine Configuration package](https://learn.microsoft.com/azure/governance/machine-configuration/how-to/develop-custom-package/overview) - [Set up the authoring environment](https://learn.microsoft.com/azure/governance/machine-configuration/how-to/develop-custom-package/1-set-up-authoring-environment) - [Create the package](https://learn.microsoft.com/azure/governance/machine-configuration/how-to/develop-custom-package/2-create-package) diff --git a/docs/src/user-guide/manifest-editor.md b/docs/src/user-guide/manifest-editor.md index dcb5506..53d396f 100644 --- a/docs/src/user-guide/manifest-editor.md +++ b/docs/src/user-guide/manifest-editor.md @@ -1,22 +1,18 @@ # Manifest editor -> **v0.3.48:** the editor itself does **not** require the OSConfig CLI. -> Authoring, validation, history, CIS cross-reference, rationale, and -> the audit-pack PDF all work without it. Only the **Deploy**, -> **Audit**, and **Revert** actions are CLI-gated. Clicking those -> while OSConfig is missing opens the shared `CliRequiredModal` with -> an Install link + Recheck button rather than failing with a raw -> spawn error. The footer health pill (🟢 / 🟠 / 🔴 / ⚪) surfaces -> the current CLI install state at all times. - -The manifest editor is the primary authoring surface. It accepts raw -YAML or editable Visual spreadsheet changes, validates as you type, -and persists to `~/.configforge/manifests/.source.yaml` on save. +Use the baseline editor to review settings, make changes, and export your +work. A **manifest** is the YAML/JSON document behind a baseline. +Authoring works in both editions without the OSConfig CLI, administrator +access, or Azure. + +New here? Complete [Your first baseline](../quick-start/first-manifest.md) +before exploring packaging or device controls. ## Open -- New baseline: **My Baselines → Register New** in the side nav. -- Existing baseline: **My Baselines → click any namespace** in the list, +- New baseline: **My Baselines → Create new baseline**, choose a starting + point, then **Create baseline** to review before registering. +- Existing baseline: **My Baselines → open a baseline** in the list, then **Edit**. ## What it does @@ -26,17 +22,15 @@ and persists to `~/.configforge/manifests/.source.yaml` on save. when the source can be parsed. - Resource-type pickers populated from [`registered-types.ts`](https://github.com/Azure/ConfigForge/blob/main/packages/core/src/oscfg/registered-types.ts). - Aspirational types (in baselines but not yet supported by the target - CLI) show with a warning chip. + Types unknown to the targeted CLI show a warning; this does not prevent + drafting but needs investigation before device use. - A CIS rule cross-reference drawer. When CIS data is available locally (see [Benchmark Mapping](./cis-compliance.md) for how to enable), the drawer shows the matching rule's ID, severity, and GPO path next to the resource at the cursor. Matches are resolved from Azure Policy JSON or XCCDF+OVAL data (not only the legacy - `cis-mappings.json` file). v0.3.46 tightened fuzzy matching from - substring matching to exact-word-set matching with a higher threshold, - which reduces over-matching; property-mapping fallback still appears - with lower confidence. + `cis-mappings.json` file). Fuzzy matches and lower-confidence fallbacks + need human review. A match is not proof that values or device state comply. The drawer is **hidden entirely** when CIS data is not present (the `useCisAvailable()` hook short-circuits the render). - The "Why?" rationale modal. See [Rationale](./rationale.md). @@ -60,15 +54,12 @@ Add settings, row selection, delete, and keyboard navigation. Tab saves and moves right. Enter saves and moves down. Shift+Enter remains a newline for structured values. -> **v0.2.1 import fix:** CSV / TSV / XLSX / JSON security-definition -> imports now emit `Microsoft.Windows/Registry` resources with all -> three schema-required properties (`keyPath`, `valueName`, -> `valueType`). Before v0.2.1 the import omitted `valueType` (and the -> JSON path also dropped `valueName`), so the schema validator flagged -> every imported row as invalid the moment the editor opened it. The -> importer now infers `valueType` from `expectedValue` via -> `inferRegistryValueType()`: DWORD-range integers → `REG_DWORD`, larger -> exact integers → `REG_QWORD`, and other values → `REG_SZ`. +Each baseline remembers its Code or Visual view. Nested Test/Group settings +retain their source structure, values retain their types, and large QWord +integers retain precision. Import supported YAML/JSON or CSV/TSV/XLSX settings +through **Create new baseline**, then review the converted content before +saving. An arbitrary report spreadsheet is not necessarily an importable +baseline. ## Resource wrappers @@ -77,7 +68,7 @@ Two resource types are _wrappers_ that nest other resources: | Wrapper | Behaviour | | -------------------------- | ---------------------------------------------------------------------------------- | | `Microsoft.OSConfig/Group` | A logical group; nested resources are validated recursively. | -| `Microsoft.OSConfig/Test` | An assertion. Wraps a single resource and adds an `expression`/`compliance` field. | +| `Microsoft.OSConfig/Test` | An assertion around a single nested resource, with its test expression/schema. | The platform validator (`packages/core/src/platform.ts`) walks both wrappers recursively, so a Linux resource hidden inside a @@ -114,73 +105,30 @@ not exposed by the current Manifest Editor UI. ### Machine Configuration package route -To reach Azure Policy / Machine Configuration through a package, export -**MOF (`.mof`)**, then hand the `.mof` to the -[`GuestConfiguration`](https://learn.microsoft.com/azure/governance/machine-configuration/how-to-create-package) -PowerShell module (Azure Machine Configuration) to turn it into a -package and a policy definition. - -**Prerequisites (one-time, on the packaging machine - PowerShell 7, -run as Administrator):** the exported MOF declares the OSConfig DSC -resource, so `New-GuestConfigurationPackage` needs both modules -installed to bundle it into the package: - -```powershell -Install-Module GuestConfiguration -Scope AllUsers -Force -# The exported MOF carries a portable 0.0.0 placeholder. Resolve it to -# the newest module installed on the packaging machine before packaging. -Install-Module Microsoft.OSConfig -Scope AllUsers -Repository PSGallery -Force -``` +For Azure Policy evaluation, export **MOF (`.mof`)** and follow the +[complete Machine Configuration workflow](./machine-configuration.md). +Packaging, testing, Storage upload, and policy assignment happen outside the +editor. -Then build and publish: - -```powershell -$InstalledOSConfig = Get-Module -ListAvailable Microsoft.OSConfig | - Sort-Object Version -Descending | - Select-Object -First 1 -$ResolvedMof = '.\MySecurityBaseline.resolved.mof' -(Get-Content '.\MySecurityBaseline.mof' -Raw).Replace( - 'ModuleVersion = "0.0.0";', - "ModuleVersion = `"$($InstalledOSConfig.Version)`";" -) | Set-Content $ResolvedMof -Encoding utf8 - -# MOF to Machine Configuration package (.zip) -New-GuestConfigurationPackage ` - -Name MySecurityBaseline ` - -Configuration $ResolvedMof ` - -Type Audit ` - -Path .\package - -# Upload the returned ZIP to Azure Storage with Set-AzStorageBlobContent, -# then pass its read-only URI to the policy generator. -New-GuestConfigurationPolicy ` - -PolicyId ` - -ContentUri ` - -DisplayName 'My Security Baseline' ` - -Path .\policy ` - -Platform Windows ` - -PolicyVersion 1.0.0 ` - -Mode Audit -``` +On the **packaging machine**, `New-GuestConfigurationPackage` requires the +**Microsoft.OSConfig PowerShell module 1.4.10 or later**, alongside the separate +**GuestConfiguration** toolkit and **PowerShell 7** runtime. Version 1.4.10 +refers to the module, not PowerShell. The install command is +`Install-Module -Name Microsoft.OSConfig -MinimumVersion 1.4.10`. + +The exported `ModuleVersion = "0.0.0"` is a portable placeholder. The +[version-resolution step](./machine-configuration.md#2-resolve-the-microsoftosconfig-module-version) +selects an installed version at or above 1.4.10 and fails if none is available +before replacing the placeholder. The MOF must bind to that exact bundled +version. Keep the resulting ZIP immutable after policy generation because the +policy contains its hash. + +Start with **Audit** and validate the exact baseline/module combination. +The minimum version is not a blanket assurance that upstream issues are +resolved. Do not apply historical 1.4.3 package patches to 1.4.10+. -Then assign the generated definition in Azure Policy. Use this route -when you want to own the packaging and publishing step - custom -storage, your own GUIDs/versioning, or package signing. - -See [Deploy through Azure Machine Configuration](./machine-configuration.md) -for the complete package, Storage, Azure Policy, assignment, verification, and -troubleshooting workflow. - -> The exported MOF uses `ModuleVersion = "0.0.0"` as a portable placeholder. -> Resolve it to the packaging machine's installed version as shown above; -> Machine Configuration runtime requires the exact bundled version. If the module isn't installed, -> `New-GuestConfigurationPackage` fails with _"Failed to find a module -> with the name 'Microsoft.OSConfig'."_ -> -> Microsoft.OSConfig 1.3.11 can audit these packages, but its PowerShell -> resource has an upstream `Set()` serialization defect. The example therefore -> defaults to Audit. Use `AuditAndSet` plus an Apply mode only with a newer -> module that contains the fix. +For a review document instead of a deployable package, use +[Audit Pack](./audit-pack.md). It needs none of these packaging tools. ## What changes don't trigger a save @@ -195,7 +143,7 @@ troubleshooting workflow. | ------------------------------------------------ | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `resources is required` | Top-level YAML doesn't have a `resources:` array. | Wrap your resources under `resources:`. | | `invalid Group/Test wrapper` | A `Microsoft.OSConfig/Group` or `Microsoft.OSConfig/Test` has no nested array. | Add `resources:` (Group) or `resource:` (Test) inside. | -| `Unsupported resource type` | The target CLI doesn't know this type, it's not in the registered whitelist. | Soft warning only; the rest of the manifest still applies. | +| `Unsupported resource type` | The type is not in the targeted CLI's registered list. | A soft warning permits authoring, not guaranteed deployment. Review provider support before device use. | | `mixed-platform manifest` | Your YAML has both Windows and Linux resource types. | Split it. `'mixed'` is rejected at deploy time. | | `CLI not installed` (on Deploy / Audit / Revert) | OSConfig isn't on this machine. | The dialog's **Install** button opens the [OSConfig CLI docs](https://github.com/microsoft/osconfig/tree/main/docs/cli); **Recheck** auto-dismisses once the resolver finds it. | diff --git a/docs/src/user-guide/matrix-diff.md b/docs/src/user-guide/matrix-diff.md index 84b6fc2..fbc6933 100644 --- a/docs/src/user-guide/matrix-diff.md +++ b/docs/src/user-guide/matrix-diff.md @@ -1,26 +1,23 @@ # Diff: Pairwise + CIS + Matrix -> **v0.3.48:** Diff is a pure-renderer feature - no OSConfig CLI -> required. Pairwise and Matrix modes load source YAML from the -> manifest store and compute deltas in-process, so they work in -> Editor mode (amber footer pill) exactly as they do with the CLI -> installed. The CIS tab also runs locally against user-supplied CIS -> data. +Compare baseline content before deciding what to change. Diff works in both +editions without the OSConfig CLI, administrator access, or Azure. It does not +inspect or modify a device. ConfigForge's **Diff** page has three tabs: - **Pairwise** - classic A vs B comparison from registered manifests or pasted/uploaded YAML. The Compare button auto-scrolls to the results once the diff renders. -- **CIS Diff** - industry-aligned coverage scoring against a selected +- **CIS Diff** - benchmark-rule coverage against a selected CIS baseline. It appears when CIS data is loaded and its Compare button auto-scrolls to the score/results. - **Matrix (N-way)** - pick 2-10 manifests, see a side-by-side table with each row a setting and each column a baseline. -The matrix mode is the one auditors and consultants asked for: the -research showed that pairwise compare doesn't scale past three -baselines. +**Coverage is not device compliance.** A matching rule does not establish that +values meet the benchmark or that a device uses them. See +[Benchmark Mapping](./cis-compliance.md) for interpretation and data setup. ## Open @@ -34,6 +31,9 @@ baselines. ## How rows are merged +
+Technical matching rules and historical fixes + The matrix builder lives in [`packages/core/src/diff/matrix.ts`](https://github.com/Azure/ConfigForge/blob/main/packages/core/src/diff/matrix.ts). It keys rows by a stable composite of @@ -71,6 +71,8 @@ merges the same setting across baselines. > The matrix builder is unaffected; its keying already covers these > cases. +
+ ## Row status Each row gets one of three statuses: diff --git a/scripts/customer-docs.test.mjs b/scripts/customer-docs.test.mjs new file mode 100644 index 0000000..49aef54 --- /dev/null +++ b/scripts/customer-docs.test.mjs @@ -0,0 +1,75 @@ +// Copyright (c) Microsoft Corporation. All rights reserved. +// Licensed under the MIT License. + +import { readFile } from 'node:fs/promises'; +import { describe, expect, it } from 'vitest'; + +const read = (file) => readFile(new URL(`../${file}`, import.meta.url), 'utf8'); +const packagingGuide = 'docs/src/user-guide/machine-configuration.md'; + +describe('customer documentation contracts', () => { + it('leads with downloads and authoring before optional packaging', async () => { + const readme = await read('README.md'); + const download = readme.indexOf('## Download the right edition'); + const firstBaseline = readme.indexOf('## Create your first baseline'); + const packaging = readme.indexOf('## Export to Azure Machine Configuration'); + + expect(download).toBeGreaterThanOrEqual(0); + expect(firstBaseline).toBeGreaterThan(download); + expect(packaging).toBeGreaterThan(firstBaseline); + expect(readme).toContain('not intended for'); + expect(readme).toContain('production use'); + expect(readme).toContain('not an officially supported Microsoft product'); + expect(readme).toContain('https://github.com/Azure/ConfigForge/releases/tag/v0.3.103'); + expect(readme).toContain('https://github.com/Azure/ConfigForge/releases/tag/mac-v0.3.101-author.1'); + expect(readme).not.toContain('mac-v0.3.97-author.1'); + }); + + it('states the resource-module minimum on each current packaging entry point', async () => { + const files = [ + 'README.md', + 'INSTALL.md', + 'docs/src/introduction.md', + 'docs/src/quick-start/install-run.md', + 'docs/src/quick-start/authoring-vs-deploying.md', + 'docs/src/user-guide/manifest-editor.md', + packagingGuide, + 'docs/src/operations/troubleshooting.md', + 'docs/src/reference/glossary.md', + ]; + for (const file of files) { + const text = await read(file); + expect(text, file).toContain('Microsoft.OSConfig'); + expect(text, file).toContain('1.4.10'); + expect(text, file).toContain('PowerShell 7'); + expect(text, file).not.toContain('1.3.11'); + } + }); + + it('fails before MOF replacement when no qualifying installed module exists', async () => { + const guide = await read(packagingGuide); + const resolution = guide.match(/```powershell\s+(\$InstalledOSConfig[\s\S]*?)```/)?.[1]; + expect(resolution).toBeDefined(); + expect(resolution).toContain("Where-Object { $_.Version -ge [version]'1.4.10' }"); + expect(resolution).toContain('Sort-Object Version -Descending'); + expect(resolution).toContain('Select-Object -First 1'); + expect(resolution).toMatch(/if \(-not \$InstalledOSConfig\) \{\s+throw /); + expect(resolution.indexOf('throw ')).toBeLessThan(resolution.indexOf('$MofContent.Replace(')); + expect(resolution).toContain('ModuleVersion = "0.0.0";'); + expect(resolution).toContain('$($InstalledOSConfig.Version)'); + expect(guide).toContain('Install-Module -Name Microsoft.OSConfig -MinimumVersion 1.4.10'); + }); + + it('keeps current packages Audit-first without applying the historical helper', async () => { + const guide = await read(packagingGuide); + const blocks = [...guide.matchAll(/```powershell\s+([\s\S]*?)```/g)].map((match) => match[1]); + const create = blocks.find((block) => block.includes('$Package = New-GuestConfigurationPackage')); + expect(create).toContain('-Type Audit'); + expect(create).not.toContain('AuditAndSet'); + expect(blocks.join('\n')).not.toContain('new-machine-configuration-package.ps1'); + expect(guide).toContain('Do not apply that old patch to 1.4.10+ packages.'); + expect(guide).toContain('Do not modify the ZIP after this step.'); + expect(guide).toContain('The policy contains the package hash.'); + expect(guide).not.toContain('Set-PSRepository'); + }); +});