From af7e3dcefcd76534db7b4961d6cf5850d168c524 Mon Sep 17 00:00:00 2001 From: Trevor Vaughan Date: Mon, 6 Jul 2026 14:07:55 -0400 Subject: [PATCH] docs: rewrite getting started guide with explicit OpenSCAP setup - Replace complyctl init as the primary setup path with a full complytime.yaml example (policy URL, target, profile variable) - Add dnf install command for openscap-scanner and scap-security-guide - Fix provider cp path (drop bin/ prefix to match release artifacts) - Document the profile variable and how to list available SSG profiles - Add datastream override for distros where auto-detection fails - Link to provider releases, source build instructions, and config docs - Use concrete policy ID (cis-fedora-l1-server) in all scan examples Fixes #65 Assisted-By: Claude Opus 4.6 Signed-off-by: Trevor Vaughan --- content/docs/getting-started/_index.md | 58 ++++++++++++++++++++------ 1 file changed, 46 insertions(+), 12 deletions(-) diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md index a6927db..5e8c7c5 100644 --- a/content/docs/getting-started/_index.md +++ b/content/docs/getting-started/_index.md @@ -3,7 +3,7 @@ title: "Getting Started" description: "Get started with ComplyTime in minutes." lead: "Get up and running with ComplyTime compliance automation tools." date: 2024-01-01T00:00:00+00:00 -lastmod: 2024-12-24T00:00:00+00:00 +lastmod: 2026-07-06T00:00:00+00:00 draft: false images: [] weight: 200 @@ -78,25 +78,59 @@ complyctl version Scanning providers are standalone executables placed in `~/.complytime/providers/`. The filename determines the evaluator ID (e.g. `complyctl-provider-openscap`). +Pre-built Linux binaries are available from the [complytime-providers releases](https://github.com/complytime/complytime-providers/releases/latest) page. To build from source, see the [complytime-providers README](https://github.com/complytime/complytime-providers#install). + +Install the provider: + ```bash mkdir -p ~/.complytime/providers -cp bin/complyctl-provider-openscap ~/.complytime/providers/ +cp complyctl-provider-openscap ~/.complytime/providers/ ``` For the OpenSCAP provider, also install the required system packages: -- `openscap-scanner` -- `scap-security-guide` +> For other operating systems see the [OpenSCAP Website](https://www.open-scap.org/download/) + +```bash +sudo dnf install -y openscap-scanner scap-security-guide +``` ### Your First Compliance Scan -**1. Initialize a workspace** +**1. Create a workspace config** + +Create `complytime.yaml` in your working directory. This example uses the [CIS Fedora L1 Server](https://quay.io/complytime/policies-cis-fedora-l1-server) policy with the OpenSCAP provider: + +```yaml +policies: + - url: quay.io/complytime/policies-cis-fedora-l1-server:latest + id: cis-fedora-l1-server + +targets: + - id: my-server + policies: + - cis-fedora-l1-server + variables: + profile: cis_server_l1 +``` + +The `profile` variable is required by the OpenSCAP provider — it selects which [SSG](https://www.open-scap.org/security-policies/scap-security-guide/) profile to evaluate. List available profiles on your system with: ```bash -complyctl init +oscap info /usr/share/xml/scap/ssg/content/ssg-fedora-ds.xml ``` -Creates a `complytime.yaml` workspace config. If one already exists, it validates and runs `get` automatically. +If the OpenSCAP provider cannot auto-detect the SCAP datastream for your distribution, set `datastream` explicitly: + +```yaml + variables: + profile: cis_server_l1 + datastream: /usr/share/xml/scap/ssg/content/ssg-cs10-ds.xml +``` + +See the [OpenSCAP provider configuration](https://github.com/complytime/complytime-providers/blob/main/cmd/openscap-provider/docs/configuration.md) for all target variables and available profiles. + +Alternatively, run `complyctl init` for interactive workspace setup. **2. Fetch policies** @@ -115,23 +149,23 @@ complyctl list **4. Generate assessment configuration** ```bash -complyctl generate --policy-id +complyctl generate --policy-id cis-fedora-l1-server ``` **5. Run the scan** ```bash # EvaluationLog (default) -complyctl scan --policy-id +complyctl scan --policy-id cis-fedora-l1-server # Markdown report -complyctl scan --policy-id --format pretty +complyctl scan --policy-id cis-fedora-l1-server --format pretty # OSCAL assessment-results -complyctl scan --policy-id --format oscal +complyctl scan --policy-id cis-fedora-l1-server --format oscal # SARIF -complyctl scan --policy-id --format sarif +complyctl scan --policy-id cis-fedora-l1-server --format sarif ``` Output is written to `./.complytime/scan/`.