Documentation
Run the scanner from your terminal
Install the scanner, run your first check and configure it for regular use. The docs/ guides cover monitoring, CI, deployment and the checks behind each finding.
Quick start
One check, without installing anything
uvx --from check-opencloud-security check-opencloud-security \
--host opencloud.example.com --check-hardeningOr use the published container. It runs the same plugin and returns the same Nagios/Icinga exit code:
docker run --rm --entrypoint check-opencloud-security \
okxo/opencloud-scanner:latest --host opencloud.example.com \
--check-hardeningThe plugin talks directly to the instance. It does not send the address to this website or to a remote verdict service.
The one-liner
One command, nothing installed
Run the scanner on your own machine to keep the scan under your control and avoid this service’s rate limits. The commands below use the same scanner as this website.
docker run --rm --entrypoint check-opencloud-security \
okxo/opencloud-scanner:latest --host opencloud.example.comThe command prints the grade, release support status, matching advisories and failed checks. Its Nagios exit code lets you use it in monitoring, scripts, CI or cron jobs. The scan runs in the container and connects directly to your instance.
As JSON
The whole result document
docker run --rm --entrypoint check-opencloud-scanner \
okxo/opencloud-scanner:latest scan opencloud.example.comEvery number on a result page comes out of this document, including the addresses block behind the Resolved to line - the IPv4 and IPv6 the name pointed at while the scan ran.
Your own network
The instances this site will not scan
docker run --rm --network host --entrypoint check-opencloud-security \
okxo/opencloud-scanner:latest --host opencloud.internal.example.comRun the command-line scanner from a machine that can reach your internal instance. It supports private addresses and internal DNS names. Public scanning services restrict these targets to prevent requests into their own internal networks.
No Docker?
Without a container
uvx --from check-opencloud-security check-opencloud-security \
--host opencloud.example.comThe scanner is also available from PyPI. Use uv to run it on demand or pipx to install it in an isolated Python environment.
Two entry points
The verdict and the result document
check-opencloud-security
The monitoring plugin: one alert line, performance data and the standard exit codes OK, WARNING, CRITICAL and UNKNOWN.
check-opencloud-security \
--host opencloud.example.com \
--release-track production \
--check-hardeningcheck-opencloud-scanner
The scanner library as a CLI: the complete JSON result document for a script, a pipeline or an ad-hoc investigation.
check-opencloud-scanner scan \
opencloud.example.com | jq \
'.rating, .ratingExplanation'The everyday flags
Useful options
-H, --host- Hostname, IP or URL; comma-separated for several instances.
--check-hardening- Include missing hardening measures and security headers.
--release-trackrolling,production,ltsorauto.--ignore-hardening- Accept one finding without erasing its evidence; repeatable and wildcard capable.
--debug- Explain where the rating started and what held it down.
--insecure- Skip certificate verification for an instance you control.
--warning / --critical- Choose the rating thresholds that map to monitoring states.
--format- Print Nagios output or Prometheus text.
--baseline / --warn-on-new- Alert only on findings that are new or worse than the last run.
--webhook-url- Notify another system when the configured state is reached.
check-opencloud-security --help is the installed manual. The complete option table includes every default and its COS_ environment variable.
One direction
Configuration and precedence
Settings may come from a YAML or JSON file, the environment or the command line. The order is always:
- CLI flagthe explicit answer for this run
- Environment
COS_*, useful in containers and services - Configuration filethe durable operator defaults
- Built-in defaultthe safe answer when nothing was specified
Let the wizard write the first file:
check-opencloud-security --configureA file ending in .json is JSON; every other suffix is YAML. Secrets may live in separate files rather than on the command line.
Regular checks
Monitoring, automation and several instances
- Nagios or Icinga: use the plugin output directly. The most severe status triggered by the configured thresholds determines the exit code.
- Multiple instances: pass a comma-separated list of hosts. Use a separate configuration file for each instance that needs different settings.
- Prometheus: run
--format=prometheusfor a single export, or serve metrics with the built-in exporter using--prometheus-listen-port. - CI: run the same command in a pipeline; the status code makes a failed policy fail the job without a wrapper.
- Scheduled checks: systemd, cron, Kubernetes and the Ansible role all use the same CLI and configuration flow.
From the repository
Full operator guides
Every source document has its own HTML page here, generated from the repository Markdown and checked for drift in CI.
- What OpenCloud is OpenCloud’s architecture, release tracks and what an external security scan can assess.
- Running OpenCloud in a secure infrastructure Put OpenCloud behind Keycloak, Authentik or Authelia, enable and ship the audit log, firewall the debug ports, and monitor it continuously.
- Putting an identity provider in front of OpenCloud, step by step Three complete tutorials - Keycloak, Authentik and Authelia - from nothing to a working OpenID Connect sign-in, with the four OpenCloud clients they all need.
- OpenCloud Security Scanner CLI option reference Every command-line flag, its default, and the environment variable that sets the same thing.
- The check-opencloud-scanner command Print the raw OpenCloud scan result, compare two saved results, explain a finding, refresh reference data and run the scan service.
- OpenCloud Security Scanner CLI reference Install, configure, rate, and automate the OpenCloud Security Scanner CLI.
- Installing the OpenCloud Security Scanner plugin Install with pipx, uv, pip or Docker, keep it current, and wire it into Icinga2 or Nagios.
- OpenCloud Security Scanner worked examples Copy-and-paste invocations for release tracks, waivers, private instances, thresholds and notifications.
- What the OpenCloud Security Scanner reads, and what it does not Every endpoint read, every additional check and its severity, and the questions a scan from outside cannot answer.
- OpenCloud release tracks, end of life and update recommendations Why the same version can be current on one track and dead on another, and what --release-track changes.
- Keep the OpenCloud release schedule and advisories current Refresh the release schedule and advisory database with signature verification, without waiting for a package upgrade.
- OpenCloud hardening measures, one by one What each hardening identifier means, which OpenCloud setting changes it, and how to waive one.
- Secrets in the OpenCloud Security Scanner configuration Resolve credentials from Docker secrets, files, the environment or a command instead of writing them down.
- Report only what changed between OpenCloud scans Use --baseline and --warn-on-new to alert on new or worse findings rather than the same one every run.
- Run the OpenCloud scanner as a local HTTP service Share one cached scan result between consumers with check-opencloud-scanner serve.
- OpenCloud Security Scanner library and JSON CLI Use the OpenCloud Security Scanner library, JSON result document, and direct CLI.
- Run the OpenCloud Security Scanner with Docker Run OpenCloud security scans in Docker, including JSON output and private networks.
- Schedule OpenCloud security scans with systemd and cron Run the OpenCloud Security Scanner on a schedule without a monitoring server.
- Scan a fleet with the OpenCloud Security Scanner Scan multiple OpenCloud instances with per-instance configuration and visible waivers.
- OpenCloud security checks in CI pipelines Run the OpenCloud Security Scanner in GitHub Actions and GitLab CI.
- OpenCloud security metrics for Prometheus and Grafana Expose OpenCloud Security Scanner metrics, dashboards, and alerting rules.
- Run the OpenCloud Security Scanner on Kubernetes Deploy scheduled scans, metrics, and the self-hosted web service on Kubernetes.
- OpenCloud Security Scanner for AI agents and MCP Connect agents to the OpenCloud Security Scanner task-level MCP tools.
- Deploy the OpenCloud Security Scanner with Ansible Deploy the native OpenCloud security check or its container with Ansible.
- Protect OpenCloud Security Scanner MCP with Authentik Protect the scanner's agent endpoint with a self-hosted OAuth provider.
- OpenCloud Security Scanner in Icinga Director Import OpenCloud security check commands, fields, and apply rules into Icinga Director.
- OpenCloud Security Scanner in Checkmk Run the OpenCloud security check as a Checkmk active check on the server, or as a local check on an agent host.
- Reverse proxy the OpenCloud Security Scanner Configure scanner reverse-proxy headers for nginx, Apache, Caddy, Traefik, and HAProxy.
- OpenCloud security scanner webhook recipes Connect OpenCloud security results to alerting systems and test them safely.
- Deploy the OpenCloud Security Scanner web service Deploy, configure, and operate the OpenCloud security scan browser, API, and worker stack.
- Redis behind the OpenCloud Security Scanner web service Secure, size, and operate the Redis instance that queues OpenCloud security scans.
- Machine-readable OpenCloud scan output: JSON, SARIF and JUnit Compare --format json, sarif and junit and wire each into a CI pipeline or dashboard.
- Content-Security-Policy checks explained What the OpenCloud Security Scanner's two CSP checks look for, and why unsafe-inline fails.
- TLS and certificate checks explained Every TLS and certificate check the OpenCloud Security Scanner runs, and why each one matters.
- Why OpenCloud still answers /status.php The PHP-era compatibility endpoint OpenCloud still serves, its hardcoded fields, and what this scanner reads from it.
- Cookie attribute checks explained The Secure, HttpOnly and SameSite checks the OpenCloud Security Scanner runs against observed cookies.
- Authentication checks explained How the OpenCloud Security Scanner tests protected endpoints, HTTP Basic auth, demo accounts and password policy.
- Public link sharing checks explained The password and expiration checks the OpenCloud Security Scanner runs against public share links.
- Exposed path and debug endpoint checks explained The deployment files, debug endpoints and ports the OpenCloud Security Scanner checks are not publicly reachable.
- Iframe embedding checks explained The origin-restriction checks the OpenCloud Security Scanner runs against embedding OpenCloud's web client in an iframe.
- Version and lifecycle disclosure checks explained How the OpenCloud Security Scanner checks that a version was determined at all, and whether it leaks in a header or webfinger.
- Troubleshoot the OpenCloud Security Scanner Resolve OpenCloud security scan errors and interpret the exit-code reference.