diff --git a/docs/public/images/compliance/cis-report-example.png b/docs/public/images/compliance/cis-report-example.png new file mode 100644 index 0000000..09e4b54 Binary files /dev/null and b/docs/public/images/compliance/cis-report-example.png differ diff --git a/docs/src/components/Layout.jsx b/docs/src/components/Layout.jsx index 9649853..5854044 100644 --- a/docs/src/components/Layout.jsx +++ b/docs/src/components/Layout.jsx @@ -30,6 +30,8 @@ const navigation = [ {title: 'Custom Validation Rules', href: '/docs/custom-validation-rules'}, {title: 'External Data', href: '/docs/external-data'}, {title: 'Alerting', href: '/docs/alerting'}, + {title: 'Compliance Reporting', href: '/docs/compliance-reporting'}, + {title: 'Compliance Annotations', href: '/docs/compliance-annotations'}, ], }, // { diff --git a/docs/src/pages/docs/architecture-guide.md b/docs/src/pages/docs/architecture-guide.md index 9c19c33..169d7a8 100644 --- a/docs/src/pages/docs/architecture-guide.md +++ b/docs/src/pages/docs/architecture-guide.md @@ -23,3 +23,13 @@ The `netchecks` image is based on the [python:3.12-slim-bookworm](https://hub.do [Kyverno's PolicyReporter](https://kyverno.github.io/policy-reporter/) is optionally installed alongside Netchecks to provide a convenient way to expose metrics, view the results, and generate notifications. + +## Compliance Reporting + +For organizations that need to map active network test results to compliance framework controls, +the [netchecks-compliance](/docs/compliance-reporting) add-on reads +`PolicyReport` results and `NetworkAssertion` annotations to generate audit-ready compliance +reports (PDF/HTML/JSON) for frameworks including PCI-DSS v4.0, SOC 2, and CIS Kubernetes Benchmark. + +See the [compliance annotations](/docs/compliance-annotations) documentation for details on +annotating your NetworkAssertions with control IDs. diff --git a/docs/src/pages/docs/compliance-annotations.md b/docs/src/pages/docs/compliance-annotations.md new file mode 100644 index 0000000..e1ed522 --- /dev/null +++ b/docs/src/pages/docs/compliance-annotations.md @@ -0,0 +1,104 @@ +--- +title: Compliance annotations +description: Annotate NetworkAssertions with compliance framework control IDs for audit-ready reporting. +--- + +# Compliance Annotations + +Netchecks supports compliance annotations on `NetworkAssertion` resources. These annotations map +your active network tests to specific compliance framework controls, enabling automated generation +of audit-ready compliance reports via [netchecks-compliance](/docs/compliance-reporting). + +## Supported Annotations + +| Annotation | Description | Example | +|---|---|---| +| `netchecks.io/controls` | Comma-separated list of compliance control IDs | `"pci-dss-v4/1.3.2, soc2/CC6.6"` | +| `netchecks.io/description` | Human-readable description of what this assertion verifies | `"Verify CDE egress is restricted"` | +| `netchecks.io/severity` | Risk severity: `critical`, `high`, `medium`, `low` | `"critical"` | + +## Supported Frameworks + +| Framework | Control IDs | License | +|---|---|---| +| CIS Kubernetes Benchmark | `cis-k8s/5.3.1`, `cis-k8s/5.3.2` | Free | +| PCI-DSS v4.0 | `pci-dss-v4/1.2.1`, `pci-dss-v4/1.3.2`, `pci-dss-v4/11.3.4`, `pci-dss-v4/11.3.4.1` | Pro | +| SOC 2 Type II | `soc2/CC6.6`, `soc2/CC6.7`, `soc2/CC7.1` | Pro | + +## Example + +```yaml +apiVersion: netchecks.io/v1 +kind: NetworkAssertion +metadata: + name: cde-isolation-egress + namespace: payments + annotations: + netchecks.io/controls: "pci-dss-v4/1.3.2, pci-dss-v4/11.3.4" + netchecks.io/description: > + Verify CDE namespace cannot reach external networks except + whitelisted payment processor endpoints. + netchecks.io/severity: critical +spec: + schedule: "*/30 * * * *" + rules: + - name: block-egress-to-internet + type: tcp + host: example.com + port: 443 + expected: fail + validate: + message: CDE pods must not reach arbitrary external hosts + - name: allow-payment-processor + type: http + url: https://api.stripe.com/v1/health + expected: pass + validate: + message: CDE pods must be able to reach payment processor +``` + +## How It Works + +1. **Annotate** your `NetworkAssertion` resources with `netchecks.io/controls` to map tests to + compliance framework controls. +2. The netchecks operator runs the tests as usual, producing `PolicyReport` resources. +3. The **netchecks-compliance** tool reads both the `NetworkAssertion` annotations and `PolicyReport` + results, then maps them to framework controls. +4. A compliance report is generated in PDF, HTML, or JSON format showing per-control pass/fail + status backed by active test evidence. + +## Control Mapping Logic + +- A control is **PASS** if all associated NetworkAssertion test results pass. +- A control is **FAIL** if any associated test result fails. +- A control is **NOT_ASSESSED** if no NetworkAssertions are mapped to it. + +Multiple NetworkAssertions can map to the same control — all results are aggregated. + +## Generating Reports + +Install the [netchecks-compliance](/docs/compliance-reporting) CLI: + +```bash +pip install netchecks-compliance +``` + +Generate a report: + +```bash +# Free CIS report (no license required) +netchecks-compliance report \ + --framework cis-k8s \ + --format pdf \ + --output cis-report.pdf + +# PCI-DSS report (requires Pro license) +netchecks-compliance report \ + --framework pci-dss-v4 \ + --namespace payments \ + --format pdf \ + --output pci-report.pdf \ + --license license.jwt \ + --organization "Acme Corp" \ + --environment "Production" +``` diff --git a/docs/src/pages/docs/compliance-reporting.md b/docs/src/pages/docs/compliance-reporting.md new file mode 100644 index 0000000..7044837 --- /dev/null +++ b/docs/src/pages/docs/compliance-reporting.md @@ -0,0 +1,94 @@ +--- +title: Compliance Reporting +description: Generate audit-ready compliance reports from netchecks test results. +--- + +# Compliance Reporting + +**netchecks-compliance** is a paid add-on that takes netchecks `PolicyReport` results and produces +compliance reports mapped to specific framework controls. The output is evidence an auditor can +directly reference in a SOC 2 Type 2 report or PCI-DSS ROC. + +## The Problem + +Organizations running Kubernetes need to prove their network security controls actually work — not +just that policies exist. Every KSPM tool checks whether `NetworkPolicy` objects exist and are +correctly configured. None of them verify that traffic is actually blocked in practice. + +Netchecks fills the testing gap — it actively sends traffic and validates results. **netchecks-compliance** +bridges those test results to auditor-ready compliance evidence. + +## Supported Frameworks + +| Framework | Key Controls | Tier | +|---|---|---| +| **CIS Kubernetes Benchmark** | 5.3.1, 5.3.2 | Community (Free) | +| **PCI-DSS v4.0** | 1.2.1, 1.3.2, 11.3.4, 11.3.4.1 | Pro | +| **SOC 2 Type II** | CC6.6, CC6.7, CC7.1 | Pro | + +## Output Formats + +| Format | Use Case | +|---|---| +| **PDF** | Hand to auditor. Print-ready. Primary deliverable. | +| **HTML** | Self-contained single-file. View in browser. Share internally. | +| **JSON** | GRC platform integration (Vanta, Drata, Secureframe). | + +## How It Works + +1. **Annotate** your `NetworkAssertion` resources with [compliance annotations](/docs/compliance-annotations) + to map tests to compliance framework controls. +2. The netchecks operator runs the tests as usual, producing `PolicyReport` resources. +3. **netchecks-compliance** reads both the `NetworkAssertion` annotations and `PolicyReport` results, + maps them to framework controls, and generates a compliance report. + +Reports include: +- **Executive summary** — overall compliance posture (X/Y controls passing), critical findings +- **Per-control detail** — control ID, description, status (PASS/FAIL/NOT_ASSESSED), evidence count, + last tested timestamp, mapped NetworkAssertions, finding details +- **Attestation footer** — tool version, SHA-256 integrity hash, automation statement + +## Example Report + +![CIS Kubernetes Benchmark Compliance Report](/images/compliance/cis-report-example.png) + +## Quick Start + +```bash +pip install netchecks-compliance + +# Free CIS report (no license required) +netchecks-compliance report \ + --framework cis-k8s \ + --format pdf \ + --output cis-report.pdf + +# PCI-DSS report (requires Pro license) +netchecks-compliance report \ + --framework pci-dss-v4 \ + --namespace payments \ + --format pdf \ + --output pci-report.pdf \ + --license license.jwt \ + --organization "Acme Corp" \ + --environment "Production" + +# List available frameworks and controls +netchecks-compliance frameworks +``` + +## Pricing + +| Tier | What's Included | +|---|---| +| **Community (Free)** | CIS Kubernetes Benchmark reports. PDF + HTML + JSON output. CLI generation. | +| **Pro ($99/month or $999/year)** | All frameworks. PDF + HTML + JSON. Up to 5 clusters. | +| **Enterprise (custom)** | Unlimited clusters. Custom frameworks. OSCAL output. | + +Contact [brian@hardbyte.nz](mailto:brian@hardbyte.nz) for Enterprise licenses. + +## Next Steps + +- [Compliance Annotations](/docs/compliance-annotations) — how to annotate your NetworkAssertions +- [Example manifests](https://github.com/hardbyte/netchecks/tree/main/operator/examples/compliance) — PCI-DSS, SOC 2, and CIS example NetworkAssertions +- [Architecture Guide](/docs/architecture-guide) — how netchecks works end-to-end diff --git a/operator/charts/netchecks/Chart.yaml b/operator/charts/netchecks/Chart.yaml index 5ca85ba..c305ead 100644 --- a/operator/charts/netchecks/Chart.yaml +++ b/operator/charts/netchecks/Chart.yaml @@ -6,13 +6,13 @@ icon: https://raw.githubusercontent.com/hardbyte/netchecks/main/.github/logo.png # This is the chart version. This version number should be incremented each time you make changes # to the chart and its templates, including the app version. # Versions are expected to follow Semantic Versioning (https://semver.org/) -version: 0.1.20 +version: 0.1.21 # This is the version number of the application being deployed. This version number should be # incremented each time you make changes to the application. Versions are not expected to # follow Semantic Versioning. They should reflect the version the application is using. # It is recommended to use it with quotes. -appVersion: "0.6.0" +appVersion: "0.7.0" sources: - https://github.com/hardbyte/netchecks maintainers: @@ -23,25 +23,19 @@ annotations: # https://artifacthub.io/docs/topics/annotations/helm/ artifacthub.io/changes: | - kind: added - description: Support to update Probes on operator update. - - kind: fixed - description: Fixed issue where PolicyReport was owned by the probe Pod. + description: TCP probe type for raw TCP connectivity checks. links: - - name: GitHub Issue - url: https://github.com/hardbyte/netchecks/issues/91 + - name: Pull Request + url: https://github.com/hardbyte/netchecks/pull/315 - kind: added - description: Updated versions, added K8s Events on probe run. - - kind: added - description: Support for CEL templated variables, injecting context from ConfigMaps and Secrets. + description: Compliance annotations for mapping NetworkAssertions to framework controls (PCI-DSS, SOC 2, CIS). links: - - name: GitHub Issue - url: https://github.com/hardbyte/netchecks/issues/33 - - name: Inject Context PR - url: https://github.com/hardbyte/netchecks/pull/34 - - name: Context from Secrets PR - url: https://github.com/hardbyte/netchecks/pull/37 + - name: Pull Request + url: https://github.com/hardbyte/netchecks/pull/314 + - kind: added + description: Cilium TCP egress restriction example and E2E test. - kind: added - description: Updated documentation, support multiple architectures. + description: Compliance reporting documentation and example NetworkAssertions. artifacthub.io/category: security artifacthub.io/operator: "true" artifacthub.io/prerelease: "false" diff --git a/operator/examples/compliance/cis-default-deny.yaml b/operator/examples/compliance/cis-default-deny.yaml new file mode 100644 index 0000000..224458d --- /dev/null +++ b/operator/examples/compliance/cis-default-deny.yaml @@ -0,0 +1,27 @@ +apiVersion: netchecks.io/v1 +kind: NetworkAssertion +metadata: + name: default-deny-enforcement + namespace: default + annotations: + netchecks.io/controls: "cis-k8s/5.3.1, cis-k8s/5.3.2" + netchecks.io/description: > + Verify default-deny NetworkPolicy is enforced in the default + namespace. CIS Kubernetes Benchmark 5.3.2 requires a default + deny-all NetworkPolicy for each namespace. + netchecks.io/severity: medium +spec: + schedule: "@hourly" + rules: + - name: egress-blocked + type: http + url: https://example.com + expected: fail + validate: + message: Default deny should block egress to the internet + - name: cross-namespace-blocked + type: http + url: http://api.production:8080 + expected: fail + validate: + message: Default deny should block cross-namespace traffic diff --git a/operator/examples/compliance/pci-dss-cde-isolation.yaml b/operator/examples/compliance/pci-dss-cde-isolation.yaml new file mode 100644 index 0000000..191088b --- /dev/null +++ b/operator/examples/compliance/pci-dss-cde-isolation.yaml @@ -0,0 +1,49 @@ +apiVersion: netchecks.io/v1 +kind: NetworkAssertion +metadata: + name: cde-isolation-egress + namespace: payments + annotations: + netchecks.io/controls: "pci-dss-v4/1.3.2, pci-dss-v4/11.3.4" + netchecks.io/description: > + Verify CDE namespace cannot reach external networks except + whitelisted payment processor endpoints. PCI-DSS v4.0 requires + that outbound CDE traffic is restricted and segmentation is + actively tested. + netchecks.io/severity: critical +spec: + schedule: "*/30 * * * *" + rules: + - name: block-egress-to-internet + type: http + url: https://example.com + expected: fail + validate: + message: CDE pods must not reach arbitrary external hosts + - name: allow-payment-processor + type: http + url: https://api.stripe.com/v1/health + expected: pass + validate: + message: CDE pods must be able to reach payment processor +--- +apiVersion: netchecks.io/v1 +kind: NetworkAssertion +metadata: + name: cde-isolation-ingress + namespace: payments + annotations: + netchecks.io/controls: "pci-dss-v4/1.2.1, pci-dss-v4/11.3.4" + netchecks.io/description: > + Verify only authorized services can reach the CDE namespace. + Unauthorized ingress to the CDE must be blocked. + netchecks.io/severity: critical +spec: + schedule: "*/30 * * * *" + rules: + - name: block-ingress-from-public + type: http + url: http://cde-service.payments:8080 + expected: fail + validate: + message: Public namespace pods should not reach CDE services diff --git a/operator/pyproject.toml b/operator/pyproject.toml index 4723753..07aaf95 100644 --- a/operator/pyproject.toml +++ b/operator/pyproject.toml @@ -1,6 +1,6 @@ [tool.poetry] name = "netcheck-operator" -version = "0.6.0" +version = "0.7.0" description = "Netcheck is a cloud native tool for specifying and regularly checking assertions about network conditions. Organisations use netcheck to proactively verify whether security controls are working as intended, alerting them to misconfiguration and potential threats." authors = ["Brian Thorne "] readme = "README.md" diff --git a/pyproject.toml b/pyproject.toml index 236e4fd..378e42c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,6 +1,6 @@ [project] name = "netcheck" -version = "0.6.0" +version = "0.7.0" description = "Netchecks is a cloud native tool for specifying and regularly checking assertions about network conditions. Use netchecks to proactively verify whether security controls are working as intended, alerting on misconfiguration." readme = "README.md" authors = [