Skip to content

Frequently Asked Questions

General

What is OpenSCM?

OpenSCM is a self-hosted, privacy-first security compliance platform built in Rust. It allows you to define security tests, group them into policies, deploy them to your infrastructure, and generate formal compliance reports — all without raw system data ever leaving your network.

Is OpenSCM free to use?

The client agent (scmclient) is licensed under Apache 2.0 — completely free with no restrictions.

The server (scmserver) is licensed under FSL-1.1-ALv2 — free to use, self-host, and inspect. The license converts to Apache 2.0 two years after each release.

What operating systems are supported?

Currently Linux and Windows on x86_64, ARM64, and RISC-V 64. macOS and FreeBSD support is coming soon.

Do I need an internet connection to run OpenSCM?

No. OpenSCM is fully self-hosted. The server and agents communicate only with each other on your network. No data is sent to external servers.

How is OpenSCM different from other compliance tools?

Most compliance tools collect raw system data — file contents, logs, user lists — and send it to a central server. OpenSCM agents execute all checks locally and only report PASS, FAIL, or NA. Your system data never leaves your network.

Installation & Setup

What are the server requirements?

OpenSCM server is a single binary with no external dependencies. It runs comfortably on a small VM or even a Raspberry Pi. Minimum recommended:

  • 1 CPU core
  • 512MB RAM
  • 1GB disk space (more for large deployments with many reports)
Do I need a database server?

No. OpenSCM uses SQLite embedded in the server binary. No PostgreSQL, MySQL, or any other database server is required.

Do I need a web server like Nginx?

Not for basic operation — OpenSCM serves its own web interface. However for production deployments we strongly recommend running behind a reverse proxy (Nginx or Caddy) for TLS termination and HTTPS support.

How do I enable HTTPS?

Place a reverse proxy in front of OpenSCM. Example with Caddy:

# Caddyfile
openscm.yourdomain.com {
    reverse_proxy localhost:8000
}

Caddy handles automatic TLS certificate issuance. See the Configuration guide for details.

The agent installed but doesn't appear in the dashboard

Check the following:

  1. Verify the url in scmclient.config points to your server correctly
  2. Ensure the server is reachable from the agent's network
  3. Check agent logs: sudo journalctl -u scmclient -f
  4. Confirm the server port (default 8000) is not blocked by a firewall
I forgot the admin password. How do I reset it?

Currently password reset requires direct database access. Connect to the SQLite database and update the password hash:

sqlite3 /var/lib/openscm/scm.db

Then update the admin user with a new bcrypt hash. This will be improved in a future release with a CLI reset command.

Agents & Systems

How does an agent register with the server?

On first start the agent generates a unique Ed25519 keypair locally and sends a registration request (ID 0) to the server with its public key and system metadata. The system appears as Pending in the dashboard until an administrator approves it.

What happens if I delete an agent's key files?

The agent loses its identity and automatically initiates a new registration request. It will appear as a new Pending system and require re-approval by an administrator. The previous system entry and its compliance history remain in the database under the old identity.

Can one agent connect to multiple servers?

Yes. The agent maintains a separate keypair per server URL, stored as files named with a hash of the server URL. Each server relationship is completely independent.

How often does the agent check in?

The default heartbeat interval is 300 seconds (5 minutes). This can be configured in scmclient.config:

[client]
heartbeat = "300"

A random jitter of 0–9 seconds is automatically added to prevent thundering herd problems in large deployments.

Does the agent need root/administrator privileges?

For most compliance checks — file permissions, package lists, process status — the agent needs elevated privileges to read system state accurately. Running as root on Linux or as a service with Administrator privileges on Windows is recommended.

Tests & Policies

What is the difference between a test and a policy?

A test is a single compliance check — one thing to verify on a system. A policy is a collection of tests bundled together and assigned to system groups. Tests are reusable — the same test can appear in multiple policies.

How many conditions can a test have?

Each test supports up to 5 conditions combined with either ALL (every condition must pass) or ANY (at least one must pass) logic.

What does NA mean in test results?

NA (Not Applicable) means the test was skipped because it does not apply to that system. NA results are excluded from the compliance score calculation.

Can I assign a system to multiple groups?

Yes. A system can belong to multiple groups simultaneously. It will participate in the policies assigned to all of its groups.

Can the same test be in multiple policies?

Yes. Tests are defined once in the test library and can be included in as many policies as needed.

What happens to compliance scores when I add a new test to a policy?

The score will update after the next policy run. Systems that have not yet been scanned for the new test will not have a result for it until the next heartbeat cycle.

Reports

Are reports saved automatically?

No. Reports must be saved manually. After running a policy and viewing the live results, click Save to History to archive the snapshot.

The scheduler automates policy scans but not report saving.

Can I export reports?

Yes — reports can be exported as PDF from both the live policy report view and the saved reports archive.

Can I delete a saved report?

Yes, but deletion is permanent and cannot be undone. Export a PDF copy before deleting if you may need the record for future audits.

Security

Is communication between the agent and server encrypted?

All payloads are cryptographically signed with Ed25519 keys — ensuring authenticity and tamper-proofing. Transport confidentiality is provided by TLS via your reverse proxy. The server should always be placed behind a reverse proxy with HTTPS enabled in production.

What data does the agent send to the server?

The agent sends:

  • Registration: hostname, IP address, OS, architecture, agent version, public key
  • Heartbeat: system metadata updates, compliance test results (PASS/FAIL/NA only)

Raw file contents, log entries, user data, and system configuration details are never transmitted.

How do I report a security vulnerability?

Please do not open a public GitHub issue for security vulnerabilities. Report them responsibly to security@openscm.io. We respond within 48 hours.

Troubleshooting

The dashboard shows no compliance data after running a policy

Check the following:

  1. Confirm the system is Active (not Pending) in the Systems list
  2. Verify the system is assigned to a group that is linked to the policy
  3. Check the agent logs for errors: sudo journalctl -u scmclient -f
  4. Wait for the next heartbeat cycle — results are not instant
Compliance score shows -1 or Not Scanned

The policy has never been run. Click the Run button on the policy card to execute the first scan, or configure a schedule to run it automatically.

The agent shows as Active but no tests are running

Verify that:

  1. The system is assigned to at least one system group
  2. That system group is assigned to at least one policy
  3. The policy contains at least one test
How do I view server logs? 
sudo journalctl -u scmserver -f

Get-EventLog -LogName Application -Source OpenSCMServer -Newest 50