Skip to main content

​
How scanning works

When a scan runs, OpenWatch uses the Kensa compliance engine to connect to the target host over SSH, execute each rule’s check command, and return a pass/fail result with machine-verifiable evidence. 
Operator clicks "Run Scan" (or adaptive scheduler triggers)
        |
        v
Celery task queued (compliance_scanning queue)
        |
        v
Kensa retrieves SSH credentials from encrypted store
        |
        v
SSH connection to target host
        |
        v
338 YAML rules evaluated
        |
        v
Results stored in PostgreSQL (scan_findings table)
        |
        v
Posture snapshot updated, alerts generated if thresholds met
Key points:
  • No agent on targets. Kensa connects over SSH, runs commands, and disconnects.
  • One scan, many frameworks. A single scan produces results that map to CIS, STIG, NIST, PCI-DSS, and FedRAMP simultaneously.
  • Evidence captured. Each check records the command executed, the raw output, the expected value, and the actual value found.

​
Running a scan

​
From the UI

  1. Navigate to Hosts and select the host.
  2. Click Run Scan.
  3. Select a compliance framework (or leave blank to run all 338 rules).
  4. Click Start Scan.
The scan runs in the background. Results appear on the host’s compliance tab once complete (typically 1-5 minutes).

​
Automatic scanning

Most hosts are scanned automatically by the adaptive scheduler. See Adaptive scheduling below.

​
Reading scan results

After a scan completes, the results show on the host detail page under the Compliance tab.
ElementDescription
Compliance scorePercentage of rules passing (e.g., 85.0%)
Summary barPass, fail, error, and skipped counts
Severity breakdownCounts by critical, high, medium, low
Findings tableSortable, filterable list of all findings

​
Finding details

Click any finding to expand it:
FieldDescription
Rule IDKensa rule identifier (e.g., sshd-disable-root-login)
TitleHuman-readable description
Severitycritical, high, medium, or low
Statuspass, fail, error, or skipped
DetailExplanation of the check result
EvidenceCommand executed, expected value, actual value

​
Compliance posture

The compliance score is the percentage of evaluated rules that passed: 
compliance_score = (passed_rules / total_rules) * 100
Skipped rules are excluded from the total. The Dashboard shows aggregate scores across all hosts, per-host scores, trend charts, and framework breakdowns.

​
Historical posture

OpenWatch captures daily posture snapshots at 00:30 UTC. View historical posture from the host detail page under the Posture History tab.

​
Drift detection

Drift occurs when a rule’s status changes between two points in time. A rule that was passing and now fails is a regression. A rule that was failing and now passes is an improvement.

​
Viewing drift

  1. Navigate to the host detail page.
  2. Select the Drift tab.
  3. Choose a date range.
The drift view shows:
  • Score delta — how much the compliance score changed
  • Drift type — stable, minor, major, or improvement
  • Rules improved and rules regressed — counts with expandable lists
  • Timeline — when each drift event occurred

​
Field-level value drift

Enable Include value drift to see rules where the underlying configuration value changed even though the pass/fail status did not.

​
Responding to drift

  1. Review the regressed rules and their evidence.
  2. Investigate the root cause on the host (configuration change, package update).
  3. Remediate the finding, or create a compliance exception if the risk is accepted.

​
Adaptive scheduling

The compliance scheduler automatically scans hosts at intervals based on their compliance state.
Compliance StateScore RangeScan Interval
Compliant100%Every 24 hours
Mostly compliant80-99%Every 12 hours
Partial50-79%Every 6 hours
Low20-49%Every 2 hours
Critical< 20% or critical findingsEvery 1 hour
UnknownNever scannedImmediate
MaintenancePausedEvery 48 hours (max)

​
Maintenance mode

To pause scanning during planned maintenance:
  1. Go to the host detail page.
  2. Click Maintenance Mode.
  3. Set the duration (1-168 hours).
  4. Click Enable.
Maintenance mode expires automatically.

​
Force scan

Click Force Scan on the host detail page to trigger an immediate scan outside the normal schedule.

​
Alert management

Alerts are generated automatically when scan results meet configured thresholds.

​
Alert categories

CategoryAlert Types
ComplianceCritical finding, high finding, score drop, non-compliant, degrading trend
OperationalHost unreachable, scan failed, scheduler stopped, scan backlog
ExceptionException expiring, exception expired, exception requested
DriftConfiguration drift, unexpected remediation, mass drift

​
Alert lifecycle

Active --> Acknowledged --> Resolved
  • Active: Alert generated, requires attention.
  • Acknowledged: You are investigating.
  • Resolved: Issue is fixed or accepted.

​
Configuring thresholds

Navigate to Settings > Alert Thresholds:
SettingDefaultMeaning
Score drop threshold20 pointsAlert if score drops 20+ points in 24h
Non-compliant threshold80%Alert if score falls below 80%
Degrading trend scans3Alert after 3 consecutive declining scans
Max scan age48 hoursAlert if host not scanned in 48 hours
Exception expiry warning7 daysWarn 7 days before exception expires
Mass drift threshold10 hostsAlert if 10+ hosts drift simultaneously

​
Exporting for audits

​
Creating a saved query

  1. Navigate to Compliance > Audit Queries.
  2. Click New Query.
  3. Define filter criteria (severities, statuses, date range, hosts).
  4. Name the query and set visibility (private or shared).
  5. Click Save.

​
Generating an export

  1. From a saved query, click Export.
  2. Choose a format: CSV, JSON, or PDF.
  3. The export generates in the background. A download link appears when ready.
Exports include a SHA-256 checksum for integrity verification. Exports expire after 7 days by default.