Security report and doctor
The local security report brings integrity, configuration activity and control health into one place. It gives the operator a starting point: what needs attention, which evidence supports the finding, and which control to investigate next. Doctor provides a fresh terminal diagnosis when the question concerns the host's current state.
Both use protected local evidence and run with the privileges needed to read it. The saved reports remain on the host; reviewing them is an operator task. Notification delivery is not part of the current integration.
Choose the right view
| Situation | Action | Result |
|---|---|---|
| Routine review | Open the latest saved text report and check its timestamp. | Read the findings and source evidence already collected. |
| A recent change or an unusual finding needs investigation | Use the reporting manager's doctor action. | Collect a fresh diagnosis in the terminal while preserving saved report history and its checkpoint. |
| A fresh saved report is needed | Use the reporting manager's run action. | Publish a new JSON/text pair and advance the checkpoint used by the next report. |
doctor and run are actions of the project's reporting manager, used on the configured host after installation. Reading a saved report requires no new scan. Doctor is useful after maintenance or when investigating a finding; a manual report run is useful when a new retained observation is needed.
A systemd timer is configured for twice-daily reporting. The 24-hour window is the maximum look-back for evidence, rather than an instruction to run a command every 24 hours. Check the actual report timestamp and scheduling health before relying on a saved result. Timer installation and activation, together with an operator-started service execution, have been observed; automatic calendar execution and reboot persistence remain unverified.
Read a report and decide what to do
- Check the observation time and window. Establish whether the report covers the period of interest. For a change made after that report, use doctor to obtain a current observation.
- Read “Findings requiring review.” Start with critical and warning findings, then inspect the corresponding source section. Severity describes a finding; successful report generation describes the reporting process.
- Check collection errors and unknown evidence. An unavailable source needs attention before a quiet result can be interpreted as healthy.
- Follow the evidence to its owner. Compare changes with authorized maintenance, investigate unexplained activity, or diagnose the affected control.
| Observation | Useful next step |
|---|---|
| AIDE reports added, removed or changed entries | Compare the objects and attributes with the intended work. Follow the AIDE review process before approving a baseline. |
| Audit records a selected configuration operation | Inspect the path, time, result, executable and available login identity using the Linux Audit interpretation. |
| A required control is unhealthy or evidence is unknown | Inspect that control's service and collection evidence; establish the cause before changing its configuration. |
| CrowdSec evidence needs attention | Trace log acquisition, detection and firewall enforcement as distinct parts of the request path. |
| Exposure or SELinux findings appear | Compare the reported listeners, firewall policy or denials with the intended service boundary and recent changes. |
For example, after an authorized SSH configuration edit, doctor may report an AIDE difference while SSH remains healthy. Review the file and attributes against the intended edit, consult available Audit attribution if needed, then follow AIDE's explicit candidate approval process. This illustrative workflow connects a finding to a decision instead of treating every warning as a reason to restart services.
A healthy result means the collected sources met their configured checks during that observation. Its value depends on freshness, available evidence and each source's coverage. The maintenance workflow adds the component's functional checks and recovery context.
One view, distinct responsibilities
| Source | Evidence retained in the report |
|---|---|
| Control health | Selected service activity and enablement state, with completion results where applicable. |
| Linux Audit (auditd) | Collection health and selected configuration-change activity with available process and login attribution. |
| AIDE | A direct integrity-check outcome, change counts and a selected list of affected paths. |
| CrowdSec | Acquisition/parser counters, bouncer registration state and current Local API decision counts. |
| Host exposure | Runtime/permanent firewall-zone comparison and normalized listener groups. |
| SELinux | Enforcement state and grouped denial evidence from the observation window. |
| Maintenance | Clock synchronization, approximate retained Audit range, filesystem utilization and cache-only package-history evidence. |
Each source answers a different question. AIDE compares selected objects with approved state; Audit supplies activity evidence; CrowdSec counters describe detection and decision activity. Public reachability and packet blocking require checks on the actual traffic path. Reporting preserves those distinctions so the operator can choose the next investigation.
Report windows and outcomes
A normal run captures its end time before collection. The first report covers the preceding 24 hours; subsequent reports start at the previous successful report end, capped at the latest 24 hours. Times are represented in UTC. A longer gap produces an explicit truncation warning, and a checkpoint in the future is refused rather than silently adjusted.
Audit events are normalized into a start-inclusive, end-exclusive interval. This avoids deliberate overlap between successive reports, but events delivered late to Audit storage can still fall outside a later query. The checkpoint describes successful report progression; it does not prove that every transient event was retained or collected.
Findings have stable identifiers and informational, warning or critical severity. Missing or unrecognized source evidence is represented as unknown with a bounded collection error instead of being treated as a healthy zero. Command timeouts, output caps and report-size limits bound collection; exceeding a limit makes the affected evidence unavailable.
A successful process exit means the report was generated and published, even when it contains critical findings. Finding severity and execution success are separate outcomes. An execution or publication failure returns a failure status rather than claiming a trustworthy new report.
Protected publication
The reporting manager verifies the installed reporter and policy against reviewed identities and runs the trusted installed executable. The configured systemd service also executes the installed reporter. Manual runs and scheduled execution share lifecycle coordination, and the reporter uses a directory lock to serialize publication. Its latest JSON/text pair, checkpoint and history remain root-owned with restrictive permissions; up to 30 complete historical pairs are retained.
Each file is replaced atomically, but JSON, text and checkpoint publication require separate filesystem operations. Validation checks their agreement with the corresponding historical pair and refuses incomplete publication or pending recovery evidence. Caught failures attempt to restore the prior publication; interruption can still leave evidence that needs operator inspection. The implementation does not silently select or delete a damaged generation.
Raw command output is processed in memory. Persisted reports retain selected normalized fields rather than raw Audit records, command arguments, unrestricted journals, client addresses, credentials or monitored file contents. Normalized login identities and selected configuration paths can still be sensitive, so local reports remain protected operator evidence and are not public-site content.
Read-only doctor
Doctor runs the source collectors in memory and adds checks for loaded Audit rule coverage, recent CrowdSec bouncer API pulls, expected native input/forward enforcement-chain structure and bounded local alert summaries. Its observation window begins at the later of the current boot or 24 hours before diagnosis.
Doctor prints fresh diagnostic output while preserving the latest report, history and checkpoint. Repeated diagnosis therefore leaves the next saved report's starting point intact. Remediation and AIDE baseline approval remain deliberate actions through the owning control's workflow.
Native firewall structure shows whether the expected enforcement configuration is present. The controlled packet-path testing described under CrowdSec establishes observed blocking behavior. Retained alerts and grouped HTTP outcomes help explain activity within the collected evidence; incidents outside that coverage require other investigation.
Validated behavior
On-host manual runs established source collection, agreeing JSON/text output, complete historical pairs and checkpoint progression. State comparisons around read-only diagnosis confirmed that doctor left saved report state and history unchanged. Diagnosis also checked the intended Audit coverage, AIDE integrity results, CrowdSec evidence, exposure policy and SELinux state without changing their configuration.
An operator-started systemd service execution also produced an agreeing saved report, history and checkpoint under the configured service sandbox. These observations establish collection, diagnosis and publication for the exercised paths. Interpret each new report using its own timestamp, source health and findings.