The module lifecycle stage: Experimental

The module has requirements for installation

Before enabling the module, you need to allow the use of experimental modules in the deckhouse ModuleConfig. To do this, set the allowExperimentalModules parameter to true.

Why does the error Error: group criteria mismatch occur when importing a policy?

This means that the group criteria do not match between the source and the destination. Make sure the group configurations are identical on both sides.

What should I do if I see the error Error: cross-namespace policy creation denied?

This error indicates an attempt to create a policy across different namespaces. In such cases, use an object of type NvClusterSecurityRule.

Which groups can an NvSecurityRule name?

An NvSecurityRule names only the groups of its own namespace. The target and every ingress and egress group must have a domain criterion with the namespace of the rule, and no domain criterion may name another namespace. The name of every such group must end with .<NAMESPACE>, for example db-servers.production. Learned groups, such as nv.database.production, already have this suffix. Only the external, nodes and Workload:ingress groups need neither the criterion nor the suffix, and only in ingress and egress. A learned group, such as nv.database.production, must have the service criterion of its name. If an NvGroupDefinition exists for the name of a group, the group must have the criteria of that definition.

The NeuVector controller checks a rule after the Kubernetes API has accepted it, so kubectl apply reports the rule as created even when it breaks these conditions. The controller then deletes such a rule within seconds and records the reason in the NeuVector event Crd.Error and in its log: SecurityRule in nameSpace <NAMESPACE> cannot name group. The end of the message names the reason:

  • a domain criterion of the group selects namespaces other than <NAMESPACE>: the group covers another namespace;
  • the group has no criterion domain=<NAMESPACE>: add the criterion;
  • the group name must end with .<NAMESPACE>: rename the group;
  • a learned group needs the criterion service=<SERVICE>.<NAMESPACE>: add the criterion;
  • NvGroupDefinition <NAME> defines the group with other criteria: use the criteria of the definition or another name;
  • NvGroupDefinition <NAME> cannot be read: the controller failed to read the definition; apply the rule again;
  • the group belongs to no namespace: the target is external, nodes or Workload:ingress, which are allowed only as peers.

The controller also deletes such a rule that already exists when it starts. Put the rules between namespaces into an NvClusterSecurityRule instead.

Who controls the protection mode of the groups of a namespace?

The administrator of the namespace controls it: the holder of d8:namespace:admin or of the Admin access level in the ClusterAuthorizationRule model. The mode is set by the target.policymode field of NvSecurityRule: Discover, Monitor or Protect.

A group managed by an NvSecurityRule cannot be switched to another mode in the NeuVector console. The mode changes only when the NvSecurityRule itself is edited or deleted. Writing NvSecurityRule is therefore granted at the namespace administrator level, not to the manager.

The holder of d8:subsystem:security:viewer reads NvSecurityRule in every namespace. To find the groups taken out of Protect, run:

d8 k get nvsecurityrules -A -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,MODE:.spec.target.policymode'

The output lists the rules of every namespace with the protection mode of their groups.

How can I verify connectivity between NeuVector components?

Information about the state of components is displayed in the console, in the Assets → System components section.

Make sure that TLS certificates are correctly configured, valid and trusted. Command to request a certificate:

d8 k get -n d8-neuvector secret internal-tls -oyaml

What happens if a Persistent Volume (PV) is not configured?

Data will not be saved. In this case, you must manually export the configuration via the UI: Settings → Configuration.

What types of volumes are supported by NeuVector?

Any volume with the RWO (ReadWriteOnce) access mode is supported — the Controller runs as a single replica, so the volume is never mounted by more than one pod at a time.

How to change the user session timeout in NeuVector?

Go to the upper right corner of the NeuVector interface, open My Profile → Session timeout and specify the desired time in seconds. By default, the session ends after 5 minutes (300 seconds), the maximum value is 3600 seconds (1 hour).

How to check CVE database versions

To check the CVE database version, open the console and go to Assets → System components -> Scanner — the version information is displayed in this section.

How to run a one-off vulnerability scan with the NeuVector Scanner

The Deckhouse-built scanner image is republished under the tag extra/scanner:3 (see .gitlab-ci.yml job .cvedb_update). The tag is moving — it is overwritten by each scheduled (daily) CVE DB rebuild from the main branch, so it always carries a fresh CVE database. The scanner in the image follows the current main, not a particular module release: it can differ from the scanner that neuvector-scanner-pod runs in a cluster with a released module version.

Image path and registry credentials

The image is published only for the fe, ee, se-plus editions (the matrix in .gitlab-ci.yml); none of them are anonymous. Use the same credentials you use to install Deckhouse:

d8 k -n d8-system get secret deckhouse-registry \
  -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d > /tmp/d8-dockercfg.json
DOCKER_CONFIG=$(mktemp -d)
cp /tmp/d8-dockercfg.json "$DOCKER_CONFIG/config.json"
export DOCKER_CONFIG

(All docker/crane/skopeo commands below will reuse $DOCKER_CONFIG.)

The image path follows the standard layout <registry>/deckhouse/<edition>/modules/neuvector/extra/scanner:3, e.g.:

  • registry.deckhouse.io/deckhouse/fe/modules/neuvector/extra/scanner:3
  • registry.deckhouse.io/deckhouse/ee/modules/neuvector/extra/scanner:3
  • registry.deckhouse.io/deckhouse/se-plus/modules/neuvector/extra/scanner:3

If you need a reproducible reference (the floating tag will move on the next CVE DB rebuild), pin by digest:

crane digest registry.deckhouse.io/deckhouse/fe/modules/neuvector/extra/scanner:3
# -> sha256:...

…and then use …/extra/scanner@sha256:… in the examples below.

Scan an image already loaded in the local Docker daemon

IMAGE=registry.deckhouse.io/deckhouse/fe/modules/neuvector/extra/scanner:3
docker run --rm \
  -e SCANNER_REPOSITORY=ubuntu \
  -e SCANNER_TAG=22.04 \
  -e SCANNER_ON_DEMAND=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$HOME/neuvector-out:/var/neuvector" \
  "$IMAGE"

Scan an image directly from a remote registry (no local pull)

IMAGE=registry.deckhouse.io/deckhouse/fe/modules/neuvector/extra/scanner:3
docker run --rm \
  -e SCANNER_ON_DEMAND=true \
  -e SCANNER_REGISTRY=registry.example.com \
  -e SCANNER_REPOSITORY=myproject/service \
  -e SCANNER_TAG=1.2.3 \
  -e SCANNER_REGISTRY_USERNAME=myuser \
  -e SCANNER_REGISTRY_PASSWORD=mytoken \
  -v "$HOME/neuvector-out:/var/neuvector" \
  "$IMAGE"

Push the scan result into a running controller

Use the Ingress from controller.apiIngress or d8 k port-forward. The credentials must be those of a local NeuVector user with the scanner permission — OIDC-only users cannot be used here, because the standalone scanner authenticates against the controller’s REST API with username/password, not via Dex.

IMAGE=registry.deckhouse.io/deckhouse/fe/modules/neuvector/extra/scanner:3
docker run --rm \
  -e SCANNER_ON_DEMAND=true \
  -e SCANNER_REGISTRY=registry.example.com \
  -e SCANNER_REPOSITORY=myproject/service \
  -e SCANNER_TAG=1.2.3 \
  -e CLUSTER_JOIN_ADDR=neuvector-api.<publicDomainTemplate> \
  -e CLUSTER_JOIN_PORT=443 \
  -e SCANNER_CTRL_API_USERNAME=<api-user> \
  -e SCANNER_CTRL_API_PASSWORD=<api-password> \
  "$IMAGE"

What gets written

The scan report and the layer-by-layer breakdown are written under /var/neuvector inside the container — mount a host directory there to keep the artefacts after the run. Setting SCANNER_ON_DEMAND=true makes monitor start the scanner in standalone mode and exit after the scan completes (see monitor/monitor.c in neuvector/scanner). The full list of supported variables (SCANNER_REPOSITORY, SCANNER_TAG, SCANNER_REGISTRY, SCANNER_REGISTRY_USERNAME, SCANNER_REGISTRY_PASSWORD, SCANNER_ON_DEMAND, SCANNER_SCAN_LAYERS, SCANNER_DOCKER_URL, SCANNER_BASE_IMAGE, SCANNER_STANDALONE_TLS_VERIFICATION, CLUSTER_JOIN_ADDR, CLUSTER_JOIN_PORT, SCANNER_CTRL_API_USERNAME, SCANNER_CTRL_API_PASSWORD, PROXY_URL) matches upstream NeuVector — see the Parallel & Standalone Scanners docs for the full reference.