feat(docs): malware protection guide (#149)

This commit is contained in:
Julian Sommer
2026-04-17 11:17:16 +10:00
committed by GitHub
parent 883fac980c
commit 6f58a3f190
25 changed files with 323 additions and 1298 deletions
File diff suppressed because it is too large Load Diff
@@ -39,7 +39,7 @@ Spinifex maps AWS VPC concepts directly to OVN constructs:
## Network Path
<p align="center">
<img src="../../.github/assets/diagrams/vpc-network-path.svg" alt="VPC logical topology — WAN, br-wan, VPC logical router, subnets, ENIs" width="900">
<img src="../../../.github/assets/diagrams/vpc-network-path.svg" alt="VPC logical topology — WAN, br-wan, VPC logical router, subnets, ENIs" width="900">
</p>
Cross-host traffic uses **Geneve tunnels** (UDP 6081) over the management/overlay
@@ -58,7 +58,7 @@ same VPC (even across subnets and hosts via the overlay). They cannot reach the
internet or be reached from the WAN.
<p align="center">
<img src="../../.github/assets/diagrams/vpc-private-subnet-flow.svg" alt="Private subnet — instance hits router, no default route, packet dropped" width="900">
<img src="../../../.github/assets/diagrams/vpc-private-subnet-flow.svg" alt="Private subnet — instance hits router, no default route, packet dropped" width="900">
</p>
If the VPC has an IGW attached, private subnet instances CAN reach the internet
@@ -71,7 +71,7 @@ Instances get both a private IP and a public IP. The public IP is a 1:1 NAT
managed by OVN — the instance OS only sees its private IP.
<p align="center">
<img src="../../.github/assets/diagrams/vpc-public-subnet-flow.svg" alt="Public subnet — outbound SNAT and inbound DNAT between private and public IPs" width="900">
<img src="../../../.github/assets/diagrams/vpc-public-subnet-flow.svg" alt="Public subnet — outbound SNAT and inbound DNAT between private and public IPs" width="900">
</p>
**Requirements for a public subnet:**
@@ -162,7 +162,7 @@ Regardless of whether IPs come from a static range or DHCP, the OVN behavior
is identical:
<p align="center">
<img src="../../.github/assets/diagrams/vpc-dhcp-conversations.svg" alt="Two independent DHCP conversations — host-to-router and VM-to-OVN" width="900">
<img src="../../../.github/assets/diagrams/vpc-dhcp-conversations.svg" alt="Two independent DHCP conversations — host-to-router and VM-to-OVN" width="900">
</p>
### Choosing Static vs DHCP
@@ -252,7 +252,7 @@ The connection between them is logical, not physical — OVN's `localnet` port t
maps the logical external switch to `br-wan` via `ovn-bridge-mappings`.
<p align="center">
<img src="../../.github/assets/diagrams/vpc-datapath-localnet.svg" alt="Data path — VM TAP through br-int, OVN pipeline, localnet, br-wan, WAN" width="900">
<img src="../../../.github/assets/diagrams/vpc-datapath-localnet.svg" alt="Data path — VM TAP through br-int, OVN pipeline, localnet, br-wan, WAN" width="900">
</p>
## Bridge Modes
@@ -267,7 +267,7 @@ The WAN NIC is added directly to `br-wan` as an OVS port. OVS sees all
traffic on the wire — any MAC, any protocol. No filtering, no workarounds.
<p align="center">
<img src="../../.github/assets/diagrams/vpc-direct-bridge.svg" alt="Direct bridge mode — dedicated WAN NIC added directly to br-wan" width="900">
<img src="../../../.github/assets/diagrams/vpc-direct-bridge.svg" alt="Direct bridge mode — dedicated WAN NIC added directly to br-wan" width="900">
</p>
**Use when:** The host has a NIC dedicated to external/WAN traffic that is NOT
@@ -293,7 +293,7 @@ macvlan is added to br-wan. The host keeps its IP on the original NIC —
SSH stays up.
<p align="center">
<img src="../../.github/assets/diagrams/vpc-macvlan.svg" alt="Macvlan mode — WAN NIC shared between host traffic and macvlan child on br-wan" width="900">
<img src="../../../.github/assets/diagrams/vpc-macvlan.svg" alt="Macvlan mode — WAN NIC shared between host traffic and macvlan child on br-wan" width="900">
</p>
**Use when:** The WAN NIC is the same NIC used for SSH. Single-NIC homelabs,
@@ -397,7 +397,7 @@ ip link show spx-ext-eth0
## Network Flow Diagram
<p align="center">
<img src="../../.github/assets/diagrams/vpc-host-flow.svg" alt="Bare-metal host — br-int overlay, br-wan WAN bridge with macvlan, OVN NAT pipeline" width="900">
<img src="../../../.github/assets/diagrams/vpc-host-flow.svg" alt="Bare-metal host — br-int overlay, br-wan WAN bridge with macvlan, OVN NAT pipeline" width="900">
</p>
## Configuration Reference
@@ -408,7 +408,7 @@ levels: cluster-wide mode, IP pool definitions, and per-node NIC settings.
## Configuration Levels
<p align="center">
<img src="../../.github/assets/diagrams/vpc-config-layers.svg" alt="spinifex.toml configuration layers — cluster mode, IP pools, per-node NIC" width="900">
<img src="../../../.github/assets/diagrams/vpc-config-layers.svg" alt="spinifex.toml configuration layers — cluster mode, IP pools, per-node NIC" width="900">
</p>
## Cluster-Wide: external_mode
+314
View File
@@ -0,0 +1,314 @@
---
title: "Malware Protection"
description: "Operator guide for host-based malware protection, file integrity monitoring, and AV scanning on Spinifex nodes"
category: "Security"
sections:
- overview
tags:
- security
- compliance
- cmmc
- malware
- antivirus
- file integrity
resources:
- title: "Spinifex Repository"
url: "https://github.com/mulgadc/spinifex"
- title: "NIST SP 800-171 Rev 3"
url: "https://csrc.nist.gov/pubs/sp/800/171/r3/final"
- title: "CMMC Level 1 Self-Assessment Guide v2.0"
url: "https://dodcio.defense.gov/CMMC/Documentation"
- title: "ClamAV Documentation"
url: "https://docs.clamav.net"
- title: "AIDE — Advanced Intrusion Detection Environment"
url: "https://aide.github.io"
- title: "Wazuh Documentation"
url: "https://documentation.wazuh.com"
---
# Malware Protection
> Operator guide for host-based malware protection, file integrity monitoring, and AV scanning on Spinifex nodes
## Table of Contents
- [Overview](#overview)
- [CMMC Practices Covered](#cmmc-practices-covered)
- [Approach](#approach)
- [1. Designated Locations](#1-designated-locations-sil1-3142-a)
- [2. Update Requirements](#2-update-requirements-sil1-3144)
- [3. Scan Schedule](#3-scan-schedule-sil1-3145)
- [4. Reference Configurations](#4-reference-configurations)
- [5. Operator Checklist](#5-operator-checklist)
- [6. Related Documents](#6-related-documents)
---
## Overview
**Audience:** Operators deploying Spinifex into environments subject to CMMC Level 1 (or organisations that otherwise require host-based malware protection).
**Scope:** The Spinifex nodes themselves — the Linux hosts running `spinifex-daemon`, `spinifex-awsgw`, `spinifex-nats`, `spinifex-predastore`, `spinifex-viperblock`, `spinifex-vpcd` and the OVN control plane. Guest VMs launched on the platform are the responsibility of the workload owner and are out of scope.
## CMMC Practices Covered
This guide captures the operator-side controls required to meet three CMMC Level 1 practices that Spinifex itself cannot enforce — they depend on host-based tooling chosen and operated by the deployment team.
| Practice | Title | Objective |
|----------|-------|-----------|
| SI.L1-3.14.2 | Malicious Code Protection | [a] Designated locations for malicious code protection are identified. [b] Protection from malicious code at designated locations is provided. |
| SI.L1-3.14.4 | Update Malicious Code Protection | [a] Malicious code protection mechanisms are updated when new releases are available. |
| SI.L1-3.14.5 | System & File Scanning | [a] Periodic scans of the information system are defined. [b] Periodic scans of the information system are performed. [c] Real-time scans of files from external sources are defined and performed as files are downloaded, opened, or executed. |
## Approach
Spinifex does not bundle or mandate a specific anti-malware product. Operators will typically have an existing endpoint security standard (CrowdStrike Falcon, Microsoft Defender for Linux, Wazuh, ClamAV, Sophos, ESET, etc.). This guide:
1. Names the Spinifex components and filesystem paths that must be included in scan and integrity-monitoring coverage (the "designated locations").
2. Specifies update and scan cadence required to meet SI.L1-3.14.4 and SI.L1-3.14.5.
3. Provides reference configurations for open-source stacks (ClamAV for AV, AIDE for file integrity, Wazuh for centralised monitoring) as a known-good baseline. Operators running a commercial EDR should map these locations and cadences into their existing product.
## 1. Designated Locations (SI.L1-3.14.2 [a])
All Spinifex nodes must include the following in their malware protection scope. Paths assume the production install layout (`/etc/spinifex` exists); development layouts under `$HOME/spinifex` are not supported for compliance deployments.
### 1.1 Executable binaries
| Path | Contents |
|------|----------|
| `/usr/local/bin/spx` | Spinifex CLI and service entry point (`spx service <name> start`). |
| `/usr/local/bin/predastore` | Predastore S3 server binary. |
| `/usr/local/bin/viperblock` | Viperblock NBD block storage binary. |
| `/usr/local/bin/nats-server` | Bundled NATS server. |
| `/usr/local/bin/ovn-*`, `/usr/local/bin/ovs-*` | OVN / OVS control-plane and datapath binaries. |
| `/usr/local/share/ca-certificates/spinifex-ca.crt` | Cluster CA cert installed into the system trust store. |
### 1.2 Configuration and secrets
| Path | Contents |
|------|----------|
| `/etc/spinifex/` | Cluster config directory: `spinifex.toml`, `predastore.toml`, `nats.conf`. |
| `/etc/spinifex/ca.pem`, `/etc/spinifex/ca.key` | Cluster root CA certificate and private key (leader only). |
| `/etc/spinifex/node.crt`, `/etc/spinifex/node.key` | Per-node TLS certificate and key. |
| `/etc/spinifex/master.key` | Master encryption key that wraps per-volume DEKs and IAM secrets. **Highest-value artifact on the node.** |
| `/etc/spinifex/systemd.env` | Service environment file (shared by all `spinifex-*.service` units). |
### 1.3 Service units and privilege configuration
| Path | Contents |
|------|----------|
| `/etc/systemd/system/spinifex-*.service` | Unit files for daemon, awsgw, nats, predastore, viperblock, vpcd, spinifex-ui. |
| `/etc/sudoers`, `/etc/sudoers.d/` | Any drop-ins granting privileges to service accounts. |
| `/etc/ssh/sshd_config`, `/etc/ssh/sshd_config.d/` | Host SSH daemon configuration. |
### 1.4 Runtime and data locations
| Path | Purpose | Notes |
|------|---------|-------|
| `/var/lib/spinifex/spinifex/` | Daemon state, local bead/catalogue metadata. | Include in scan scope; exclude large, high-churn subtrees from real-time AV if performance requires (document the exclusion). |
| `/var/lib/spinifex/predastore/` | Local Predastore S3 backing data (chunks, metadata). | See exclusion note below. |
| `/var/lib/spinifex/viperblock/` | Local Viperblock WAL and chunk data for EBS volumes. | See exclusion note below. |
| `/var/lib/spinifex/nats/` | NATS JetStream data. | See exclusion note below. |
| `/var/lib/spinifex/awsgw/` | AWS gateway state. | Include in scan scope. |
| `/var/lib/spinifex/vpcd/` | VPC daemon state. | Include in scan scope. |
| `/run/spinifex/`, `/run/spinifex/nbd/` | Runtime sockets and PID files. | Integrity monitoring not meaningful (transient); exclude from AIDE. |
| `/var/log/spinifex/` | Service logs. | Scan for malicious content indicators; do not block on writes. |
**Performance exclusions.** Viperblock WAL, Predastore chunks, and NATS JetStream files are large, high-churn, block-level storage that contains customer VM data. Real-time on-access AV scanning of these paths is both a significant performance cost and a confused-deputy problem (the daemon, not the operator, is the writer). Recommendation: cover these paths with **periodic scheduled scans** (SI.L1-3.14.5 [b]) but exclude them from real-time on-access hooks. Record the exclusion and its justification in the system security plan.
### 1.5 External file ingest — real-time scan required (SI.L1-3.14.5 [c])
The following are "files from external sources" within the meaning of 3.14.5 [c] and **must** be scanned at ingest, before Spinifex consumes them:
| Ingest point | What lands here | How it reaches the node |
|--------------|-----------------|-------------------------|
| VM image catalogue downloads | Debian / Ubuntu / Alpine / Rocky cloud images pulled by `processImage()` in `utils/images.go`. | Spinifex downloads over HTTPS and verifies the catalogue SHA checksum. Operators layer AV on top: scan the downloaded image file before it is registered. |
| `ImportImage` / user-uploaded AMIs | Operator- or tenant-supplied VMDK/VHD/RAW images. | Uploaded to Predastore and registered via the EC2 API. |
| Cloud-init user-data | Base64 payloads attached to instances. | Passed via `RunInstances`; written to the CIDATA seed ISO before boot. |
| ISO / media attached to instances | Arbitrary ISO images attached as CD-ROM to VMs. | Uploaded to Predastore. |
Spinifex does not currently invoke an AV scanner on these ingest paths in-process. Until that integration exists, operators must either (a) use an on-access AV hook (ClamAV `clamonacc`, EDR file-write monitor) that sees Predastore writes, or (b) run a pre-ingest workflow that scans artifacts before they are uploaded to Spinifex.
## 2. Update Requirements (SI.L1-3.14.4)
Malicious code protection mechanisms must be updated when new releases are available. For signature-based AV this means signature feeds; for EDR products it means agent version pins. Apply to every node.
| Component | Cadence | Mechanism |
|-----------|---------|-----------|
| AV signatures (ClamAV `freshclam`, commercial EDR cloud feeds) | At least every 4 hours; real-time if the vendor supports it. | Systemd timer for `freshclam` (see §4.1); EDR agents typically self-update. |
| AV engine / agent version | Within 7 days of vendor release for non-critical; within 48 hours for vendor-marked critical. | OS package manager or vendor deployment pipeline; align with the flaw-remediation SLAs in `docs/security/flaw-remediation-policy.md`. |
| File-integrity baseline (AIDE) | Re-baseline on every Spinifex upgrade or config change. | Re-run `aide --init` as part of the upgrade runbook; commit the resulting hash to the change record. |
Evidence: the system security plan must record (a) which product is deployed, (b) how updates are delivered, and (c) a sample of update-success log entries from the last 30 days.
## 3. Scan Schedule (SI.L1-3.14.5)
### 3.1 Periodic scans (objectives [a], [b])
| Target | Frequency | Type |
|--------|-----------|------|
| Designated locations §1.1–§1.3 (binaries, config, secrets, unit files) | Daily | Full AV scan + AIDE integrity check. |
| Runtime data under `/var/lib/spinifex/*` (§1.4) | Weekly | Full AV scan. |
| Whole root filesystem | Monthly | Full AV scan. |
### 3.2 Real-time scans (objective [c])
| Trigger | Action |
|---------|--------|
| Write to the external-ingest paths in §1.5 | AV scan before the file is considered available. A positive detection must fail the ingest and emit a structured log line to `/var/log/spinifex/` and the operator's SIEM. |
| Execution of a binary in `/usr/local/bin/` or `/usr/local/share/` | On-access AV check (ClamAV `clamonacc` or EDR equivalent). |
### 3.3 Logging
All scan runs — scheduled and real-time — must produce a log entry that includes scanner name, version, signature version, target, outcome, and duration. Forward to the same log collection used for Spinifex service logs (see `docs/security/network-connections.md` for permitted external endpoints).
## 4. Reference Configurations
The configurations below are reference baselines. They are known to meet the CMMC L1 objectives on a standard Debian 12 Spinifex node; they are not the only valid implementation. Operators running a commercial EDR should treat §1 and §3 as the contract and configure their chosen product to match.
### 4.1 ClamAV (signature-based AV)
Install:
```bash
apt-get install -y clamav clamav-daemon clamav-freshclam clamonacc
```
Signature updates — drop-in `/etc/systemd/system/clamav-freshclam.timer.d/spinifex.conf`:
```ini
[Timer]
OnCalendar=*-*-* 00,04,08,12,16,20:00:00
Persistent=true
```
Enable and start:
```bash
systemctl enable --now clamav-freshclam.timer clamav-daemon.service clamav-clamonacc.service
```
On-access scanning — `/etc/clamav/clamd.conf` additions:
```
OnAccessIncludePath /usr/local/bin
OnAccessIncludePath /etc/spinifex
OnAccessIncludePath /etc/systemd/system
OnAccessPreventionAction clamd-block
OnAccessExcludeUname root
OnAccessExcludePath /var/lib/spinifex/viperblock
OnAccessExcludePath /var/lib/spinifex/predastore
OnAccessExcludePath /var/lib/spinifex/nats
```
Scheduled scans — `/etc/systemd/system/spinifex-clamav-scan.service`:
```ini
[Unit]
Description=Spinifex scheduled AV scan
After=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/bin/clamdscan --fdpass --multiscan \
/usr/local/bin /etc/spinifex /etc/systemd/system \
/var/lib/spinifex/awsgw /var/lib/spinifex/vpcd \
/var/lib/spinifex/spinifex /var/log/spinifex
StandardOutput=append:/var/log/spinifex/clamav-scheduled.log
StandardError=append:/var/log/spinifex/clamav-scheduled.log
```
Paired timer `spinifex-clamav-scan.timer`:
```ini
[Unit]
Description=Daily Spinifex AV scan
[Timer]
OnCalendar=*-*-* 03:15:00
Persistent=true
[Install]
WantedBy=timers.target
```
For the weekly `/var/lib/spinifex/*` data scan and the monthly root scan, add two additional timer/service pairs with `OnCalendar=weekly` / `OnCalendar=monthly` and the appropriate scan targets.
### 4.2 AIDE (file integrity monitoring)
Install:
```bash
apt-get install -y aide aide-common
```
Policy — `/etc/aide/aide.conf.d/90_spinifex`:
```
# Binaries — any change is suspicious
/usr/local/bin/spx f+p+u+g+s+m+c+sha256
/usr/local/bin/predastore f+p+u+g+s+m+c+sha256
/usr/local/bin/viperblock f+p+u+g+s+m+c+sha256
/usr/local/bin/nats-server f+p+u+g+s+m+c+sha256
# Config and secrets
/etc/spinifex f+p+u+g+s+m+c+sha256
/etc/systemd/system/spinifex-.*\.service$ f+p+u+g+s+m+c+sha256
# CA trust store
/usr/local/share/ca-certificates/spinifex-ca.crt f+p+u+g+s+m+c+sha256
# Exclude high-churn runtime data (covered by scheduled AV instead)
!/var/lib/spinifex/viperblock
!/var/lib/spinifex/predastore
!/var/lib/spinifex/nats
!/var/log/spinifex
!/run/spinifex
```
Baseline:
```bash
aideinit
mv /var/lib/aide/aide.db.new /var/lib/aide/aide.db
```
Daily check — a systemd timer invoking `aide --check`. Non-zero exit must alert. Re-baseline after every Spinifex upgrade (`make reinstall`, package upgrade, config change) and record the new hash.
### 4.3 Wazuh (centralised AV + FIM + alerting)
For multi-node clusters, a Wazuh agent on each Spinifex node feeding a central Wazuh manager is the simplest way to discharge 3.14.2 / 3.14.4 / 3.14.5 with consolidated evidence.
Key agent configuration (`/var/ossec/etc/ossec.conf` fragments):
```xml
<syscheck>
<frequency>43200</frequency> <!-- 12h FIM baseline -->
<directories check_all="yes" realtime="yes">/etc/spinifex</directories>
<directories check_all="yes" realtime="yes">/usr/local/bin</directories>
<directories check_all="yes" realtime="yes">/etc/systemd/system</directories>
<ignore>/var/lib/spinifex/viperblock</ignore>
<ignore>/var/lib/spinifex/predastore</ignore>
<ignore>/var/lib/spinifex/nats</ignore>
<ignore>/run/spinifex</ignore>
</syscheck>
<rootcheck>
<frequency>3600</frequency>
</rootcheck>
```
Pair with the Wazuh ClamAV integration (or a commercial AV module) for signature-based detection, and use the Wazuh manager's rule engine to alert on signature updates failing (SI.L1-3.14.4 evidence) and on scheduled-scan failures (SI.L1-3.14.5 evidence).
## 5. Operator Checklist
Use this list to confirm a node meets the three CMMC practices before the node is admitted to a production cluster:
- [ ] Host AV product installed, running, and reporting to a central console or log sink.
- [ ] Signature update timer/job running; last successful update within the cadence in §2.
- [ ] AV and file-integrity policy covers every path in §1.1–§1.4, with documented exclusions for §1.4 high-churn paths.
- [ ] External-ingest paths in §1.5 have real-time scanning in place (either at the Predastore write layer or in the operator's upload workflow).
- [ ] Daily, weekly, and monthly scheduled scans defined per §3.1 and visible in recent run history.
- [ ] Scan and update logs forwarded to the same SIEM / log collector used for Spinifex service logs.
- [ ] AIDE (or equivalent FIM) baseline exists; re-baseline step is part of the Spinifex upgrade runbook.
- [ ] System security plan documents the deployed product, update mechanism, scan cadence, and exclusions.