Skip to main content

Configuration Reference

Guardimesh configuration is split into two layers:

  1. Web Console (Remote Config) — Settings managed through the UI that are pushed to scanners automatically
  2. Helm Values / Environment Variables — Settings applied at install time via the Helm chart

Console settings take precedence over Helm values for overlapping options (namespace skips, scan modes, feature flags).

Web Console Settings​

These are configured at Scan Configuration in the web console and polled by scanners every 5 minutes.

Scan Modes​

SettingDescriptionDefault
Active scanningScan new containers automatically when pods are createdEnabled
Scheduled scanningPeriodically re-scan existing containersDisabled

Active and scheduled scanning can both be enabled simultaneously.

Schedule Settings​

SettingDescriptionDefault
Scan schedulePer-day time slots (Mon–Sun, HH:MM) for scheduled scans—
Minimum container ageNumber of days a container must be running before it is eligible for scheduled re-scan1

Namespace Filtering​

SettingDescriptionExample
Skip namespacesExact namespace names to exclude from scanningkube-system, guardimesh-system
Skip namespace prefixesNamespace prefixes to excludeopenshift-

Detection Features​

SettingTier RequiredDescriptionDefault
Real-time file monitoring (fanotify)Startup+Continuously monitor container writable layers for new file writesDisabled
Scan deduplication TTLAllMinutes between repeated scans of the same container triggered by pod events5 min

Signature Databases​

CategoryDatabases
Officialmain, daily, bytecode
Guardimeshguardimesh-custom
Unofficial (opt-in)Sanesecurity, SecuriteInfo, MalwarePatrol

Toggle individual databases on or off from the console. The puller sidecar will download only enabled databases.

Custom Signatures (Team / Enterprise)​

Upload custom ClamAV signature files via the Custom Signatures page:

TierMax databasesMax size per database
Team102 MB
EnterpriseUnlimited5 MB

Supported formats: .hsb, .sfp, .db, .ldb (Enterprise only for .ldb)

Helm Chart Values​

Set these at install time with --set or a custom values.yaml.

Required​

ValueDescription
apiKeyGuardimesh SaaS API key (from the web console API Keys page)

Namespace​

ValueDefaultDescription
namespaceguardimesh-systemNamespace for all Guardimesh resources
createNamespacefalseWhether the chart creates the namespace (use --create-namespace instead)
createApiKeySecrettrueSet false if you manage the Secret externally (e.g., Vault, ExternalSecrets)

Operator​

ValueDefaultDescription
operator.replicaCount1Operator replica count
operator.image.repositoryquay.io/guardimesh/guardimesh-operatorOperator image
operator.image.tagChart appVersionOperator image tag
operator.image.pullPolicyIfNotPresentImage pull policy
operator.imagePullSecrets[]Image pull secrets for private registries
operator.resources.requests.cpu10mCPU request
operator.resources.requests.memory64MiMemory request
operator.resources.limits.cpu500mCPU limit
operator.resources.limits.memory128MiMemory limit
operator.nodeSelector{}Node selector for operator pod
operator.tolerations[]Tolerations for operator pod
operator.affinity{}Affinity rules for operator pod
operator.leaderElecttrueEnable leader election (for HA)
operator.serviceAccount.nameguardimesh-operatorServiceAccount name
operator.serviceAccount.annotations{}SA annotations (e.g., for IRSA/Workload Identity)

Scanner​

ValueDefaultDescription
scanner.enabledtrueDeploy the GuardimeshScanner CR
scanner.nameguardimeshscannerCR name
scanner.clusterID""Identifier for this cluster in scan results

Scanner — SaaS Connection​

ValueDefaultDescription
scanner.saas.backendURLhttps://api.guardimesh.ioBackend API endpoint
scanner.saas.storageURL""Signature storage URL (defaults to backendURL)
scanner.saas.freshclamMirrorURL""ClamAV mirror URL (defaults to database.clamav.net)
scanner.saas.apiKeySecretguardimesh-api-keyName of the Secret containing the API key
scanner.saas.tls.skipVerifyfalseSkip TLS certificate verification (not recommended for production)
scanner.saas.tls.caSecret""Secret containing a custom CA certificate

Scanner — Scan Behavior​

ValueDefaultDescription
scanner.scanner.enabledtrueEnable the scanner DaemonSet
scanner.scanner.activeScantrueScan new pods on creation
scanner.scanner.scheduledScanfalseEnable periodic re-scanning
scanner.scanner.skipNamespaceskube-system,guardimesh-systemNamespaces to skip (comma-separated)
scanner.scanner.skipNamespacePrefixesopenshift-Namespace prefixes to skip
scanner.scanner.signatureUpdateInterval43200Seconds between signature update checks (12 hours)
scanner.scanner.antivirusMaxThreads1ClamAV scanning threads

Scanner — Images​

ValueDefaultDescription
scanner.scanner.image"" (CRD default)Scanner container image
scanner.scanner.antivirusImage"" (CRD default)ClamAV container image
scanner.scanner.inspectorImage"" (CRD default)Inspector container image
scanner.scanner.pullerImage"" (CRD default)Puller sidecar image
scanner.scanner.imagePullPolicy"" (CRD default)Image pull policy
scanner.scanner.imagePullSecrets[]Pull secrets for private registries

Scanner — Scheduling​

ValueDefaultDescription
scanner.scanner.resources{}Scanner container resources (requests/limits)
scanner.scanner.antivirusResources{}Antivirus container resources
scanner.scanner.nodeSelector{}Node selector for scanner pods
scanner.scanner.tolerations[{effect: NoSchedule, operator: Exists}]Tolerations (defaults to schedule on all nodes)
scanner.scanner.affinity{}Affinity rules
scanner.scanner.serviceAccountName""Custom ServiceAccount name

Scanner — Advanced​

ValueDefaultDescription
scanner.scanner.extraEnv[]Additional environment variables injected into the scanner container
scanner.license.acceptTermstrueAccept the Guardimesh license terms
scanner.license.modeonlineLicense mode (online for SaaS, local for air-gap)

Scanner Environment Variables​

These can be set via scanner.scanner.extraEnv in the Helm chart or directly in custom manifests. Most are overridden by remote config when CONFIG_URL is set.

Core​

VariableDefaultDescription
API_KEY—API key for authentication (usually from Secret)
API_KEY_FILE—Path to file containing API key (alternative to API_KEY)
CLAM_LOG_URL—URL for scan result ingest endpoint
POD_LOG_URL—URL for pod log ingest endpoint
CONFIG_URL—Base URL for remote config polling
CONFIG_POLL_INTERVAL300Seconds between remote config polls (minimum: 30)
CLUSTER_ID—Cluster identifier included in all results

Scan Behavior​

VariableDefaultDescription
ACTIVE_SCAN—Enable active pod scanning (true/false)
SCHEDULED_SCAN—Enable scheduled scanning (true/false)
SCHEDULED_SCAN_DAY—Day for scheduled scans
MIN_CON_DAY—Minimum container age in days for scheduled scans
SCAN_MODEruntimeScan mode
SKIP_NAMESPACES—Comma-separated namespace exclusions
SKIP_NAMESPACE_PREFIXES—Comma-separated prefix exclusions
HOST_SCAN_DIRS—Additional host directories to scan
SCAN_DEDUP_TTL300Seconds between repeat scans of same container

Detection Features​

VariableDefaultDescription
FANOTIFY_ENABLEDfalseEnable real-time file monitoring (overridden by tier-based remote config)
FANOTIFY_DEBOUNCE_SEC2Seconds to debounce fanotify events
DRIFT_DETECT_ENABLEDtrueEnable executable drift detection
MEMFD_SCAN_ENABLEDtrueEnable memfd fileless payload scanning
MEMFD_MAX_SIZE_BYTES52428800Maximum memfd size to scan (50 MB)
OBFSCAN_ENABLED—Enable obfuscation scanner sidecar
OBFSCAN_SOCKET—Path to obfuscation scanner socket

Runtime​

VariableDefaultDescription
CLAM_SOCKET/clam/clamd.sockPath to ClamAV Unix socket
INFO_SOCKET—Path to inspector info socket
HEALTH_PORT8086Port for Kubernetes probes (/healthz, /readyz, /startupz)
LOG_LEVELinfoLogging level (debug, info, warn, error)
RETRY_BUFFER_SIZE1000In-memory buffer for failed result sends

Kubernetes Metadata (set automatically by the DaemonSet)​

VariableDescription
CUR_NODE_NAMENode name (from spec.nodeName)
CUR_POD_NAMEPod name (from metadata.name)
CUR_POD_NAMESPACEPod namespace (from metadata.namespace)

Configuration Precedence​

When CONFIG_URL is set (the default SaaS path), remote config from the web console takes precedence:

Web Console settings (remote config)
  ↓ overrides
Helm values / environment variables
  ↓ overrides
Built-in defaults

Specifically, remote config overrides:

  • SKIP_NAMESPACES and SKIP_NAMESPACE_PREFIXES
  • SCAN_DEDUP_TTL
  • FANOTIFY_ENABLED (also gated by subscription tier on the backend)

Settings that are not overridden by remote config:

  • CLUSTER_ID, LOG_LEVEL, HEALTH_PORT
  • DRIFT_DETECT_ENABLED, MEMFD_SCAN_ENABLED
  • Resource limits, tolerations, node selectors

Example: Custom Values File​

apiKey: "gm_live_abc123..."

scanner:
  clusterID: "production-us-east-1"
  saas:
    tls:
      skipVerify: false
  scanner:
    activeScan: true
    scheduledScan: true
    skipNamespaces: "kube-system,guardimesh-system,monitoring"
    skipNamespacePrefixes: "openshift-,istio-"
    resources:
      requests:
        memory: "1Gi"
        cpu: "500m"
      limits:
        memory: "2Gi"
        cpu: "2000m"
    antivirusResources:
      requests:
        memory: "2Gi"
      limits:
        memory: "4Gi"
    tolerations:
      - effect: NoSchedule
        operator: Exists
      - key: "dedicated"
        operator: "Equal"
        value: "security"
        effect: "NoSchedule"
    extraEnv:
      - name: LOG_LEVEL
        value: "debug"
      - name: MEMFD_MAX_SIZE_BYTES
        value: "104857600"

Install with:

helm install guardimesh-operator \
  oci://quay.io/guardimesh/guardimesh-operator \
  --namespace guardimesh-system \
  --create-namespace \
  -f custom-values.yaml

Next Steps​