Configuration

Enabling NeuVector

To enable the module, use the web interface or the following command:

d8 platform module enable neuvector

Authentication

NeuVector module is integrated with the Deckhouse Kubernetes Platform user-authn module via Dex. The user-authn module must be enabled — without it, the controller does not start.

The default built-in NeuVector admin user is disabled at the controller level (the controller is started with -no_def_admin), so the upstream-default admin/admin credentials cannot be used. All sign-in flows go through Dex:

• Cluster groups configured in the user-authn DexProvider are forwarded to NeuVector via the OIDC groups claim.
• Use auth.allowedUserEmails / auth.allowedUserGroups to gate who can complete Dex login.
• Use auth.defaultRole and auth.groupRoleMapping to assign NeuVector roles to authenticated users.

If a local NeuVector user is needed for break-glass scenarios, create it through the NeuVector UI or REST API after the first OIDC sign-in.

Controller REST API access

To expose the NeuVector controller REST API on port 10443 outside the cluster, enable controller.apiIngress.enable. The Ingress is published on https://neuvector-api.<publicDomainTemplate>/ and proxies to the controller. Authentication is handled by NeuVector itself: obtain a token via POST /v1/auth and pass it as X-Auth-Token on subsequent requests. Optionally restrict access by client IP through controller.apiIngress.whitelistSourceRanges.

Forwarding Deckhouse security events

NeuVector can display platform security events — Falco detections, Dex login attempts, KubeVirt audit records, and containerd integrity failures — in its own UI next to enforcer events. Events flow through the standard NeuVector pipeline (UI, syslog, webhook).

A sidecar, se-bridge, always runs in each controller pod to accept events from LogShipper and write them to NeuVector’s internal KV store. Forwarding itself is controlled by the seBridgeEnabled setting in the loki module. While the setting is off, the sidecar idles and consumes no traffic.

Supported sources: falco, dex, virtualization-audit, containerd-integrity. Each lands in the semantically correct tab of NeuVector UI (Events / Security Events / Admission).

The integration is safe for response rules: a controller patch disables the Quarantine action for events with AgentID=se-bridge, so wildcard rules do not fire on external events.

Syslog and webhook forwarding

Events from se-bridge flow through NeuVector’s standard forwarders.

• Syslog. The default configuration includes categories Event, Runtime (which expands to Violation, Threat, Incident), and Audit, so all three channels used by the bridge are forwarded out of the box. If categories have been trimmed manually in the NeuVector UI, make sure the ones carrying external events are still enabled.
• Webhook. The default webhook category list is empty, so external events are not pushed to webhooks until categories are explicitly enabled in the NeuVector configuration (System Configuration → Webhooks). This is stock NeuVector behaviour, unrelated to the bridge.

Delivery reliability

Delivery to NeuVector does not carry a formal at-least-once guarantee. If the NeuVector controller or the se-bridge sidecar is unreachable, LogShipper holds unprocessed events in its per-node disk buffer. The default buffer is on the order of 256 MB; during a sustained hundreds-of-events-per-second stream a multi-tens-of-minutes controller outage can fill the buffer and some events may be lost for NeuVector.

Loki ingestion is not affected — each destination has its own independent buffer.

To reduce the risk of loss, watch the vector_buffer_byte_size metric from the log-shipper module and alert on sustained approach to the buffer limit. If you need to increase the buffer, configure the buffer field on the corresponding ClusterLogDestination — see the LogShipper documentation.

Requirements

To the Deckhouse version: 1.74 and above.

Parameters

Schema version: 1

• settings

  object
  • settings.auth

    object

    Options related to authentication or authorization in the application.

    Default: {}

    • settings.auth.allowedUserEmails

      array of strings

      An array of emails of users that are allowed to authenticate via Dex.

      Used only if the user-authn module is enabled. Forwarded to the spec.allowedEmails field of the DexClient resource.

    • settings.auth.allowedUserGroups

      array of strings

      An array of user groups that are allowed to authenticate via Dex.

      Used only if the user-authn module is enabled. Forwarded to the spec.allowedGroups field of the DexClient resource.

      Caution! Note that you must add those groups to the appropriate field in the DexProvider config.

    • settings.auth.defaultRole

      string

      NeuVector role assigned to OIDC-authenticated users when no groupRoleMapping entry matches.

      Built-in roles: admin, reader, ciops, none, fedAdmin, fedReader. A custom role name is also accepted if the role is defined in NeuVector via a roleinitcfg.yaml ConfigMap.

      Notes:

      • none means no role is granted; unmapped users will not be able to log in.
      • fedAdmin / fedReader are only meaningful on a federation master cluster.
      • ciops is intended for CI/CD bots that push scan results, not for human admins.

      Default: admin

      Examples:

      defaultRole: admin
      

      defaultRole: reader
      

      defaultRole: ciops
      

      defaultRole: none
      

      defaultRole: fedAdmin
      

      defaultRole: fedReader
      

    • settings.auth.groupRoleMapping

      array of objects

      Maps IdP groups (taken from the OIDC groups claim) to NeuVector roles. Order matters: the first matching entry wins (NeuVector semantics). Independent from auth.allowedUserGroups — that one gates Dex login, this one assigns the in-product role afterwards.

      Default: []

      Example:

      groupRoleMapping:
      - globalRole: admin
        group: neuvector-admins
      - globalRole: none
        group: developers
        roleDomains:
          admin:
          - dev-team-a
          - dev-team-b
          reader:
          - staging
      

      • settings.auth.groupRoleMapping.globalRole

        string

        Cluster-wide NeuVector role granted to members of the group.

        Built-in roles: admin, reader, ciops, none, fedAdmin, fedReader. Any custom role name defined via roleinitcfg.yaml is also accepted.

        Leave empty (or set to none) when only namespace-scoped roles are intended via roleDomains. fedAdmin / fedReader are valid only on a federation master cluster.

        Examples:

        globalRole: admin
        

        globalRole: reader
        

        globalRole: ciops
        

        globalRole: none
        

        globalRole: fedAdmin
        

        globalRole: fedReader
        

      • settings.auth.groupRoleMapping.group

        string

        IdP group name to match against the groups claim.
      • settings.auth.groupRoleMapping.roleDomains

        object

        Namespace-scoped role overrides as a map: NeuVector role name -> list of namespaces. Example: {admin: [staging], reader: [prod, default]}.
  • settings.controller

    object

    Configuration for the NeuVector controller component.

    The controller manages policies, orchestrates enforcement, and provides the REST API.

    • settings.controller.apiIngress

      object

      Optional Ingress that exposes the NeuVector controller REST API (port 10443) outside the cluster.

      The Ingress is created on a separate hostname neuvector-api.<publicDomainTemplate> and forwards requests to the controller’s REST API. Authentication is handled by NeuVector itself (token via /v1/auth).

      Default: {}

      • settings.controller.apiIngress.enable

        boolean

        Enable the controller REST API Ingress.

        Default: false

      • settings.controller.apiIngress.whitelistSourceRanges

        array of strings

        An array of CIDRs that are allowed to access the controller REST API.

        Example:

        whitelistSourceRanges:
        - 1.1.1.1/32
        

    • settings.controller.nodeSelector

      object

      The same as in the pods’ spec.nodeSelector parameter in Kubernetes.

      If the parameter is omitted, it will be determined automatically.

      Example:

      disktype: ssd
      

    • settings.controller.storageClass

      The name of StorageClass that will be used to store the module’s data.

      If the value is not specified, the StorageClass will be used according to the global storageClass parameter setting.

      The global storageClass parameter is only considered when the module is enabled. Changing the global storageClass parameter while the module is enabled will not trigger disk re-provisioning.

      Warning. Specifying a value different from the one currently used (in the existing PVC) will result in disk re-provisioning and all data will be deleted.

      If false is specified, emptyDir will be forced to be used.

      Examples:

      storageClass: false
      

      storageClass: nfs-storage-class
      

    • settings.controller.tolerations

      array of objects

      The same as in the Pods’ spec.tolerations parameter in Kubernetes.

      If the parameter is omitted or false, it will be determined automatically.

      • settings.controller.tolerations.effect

        string
      • settings.controller.tolerations.key

        string
      • settings.controller.tolerations.operator

        string
      • settings.controller.tolerations.tolerationSeconds

        integer
      • settings.controller.tolerations.value

        string