NeuVector is a distributed container security platform that provides real-time runtime protection, network policy enforcement, vulnerability scanning, and compliance checking for containerized environments. This document provides a high-level overview of NeuVector's architecture, component organization, and core subsystems.
For specific subsystem details:
NeuVector uses a distributed multi-tier architecture consisting of:
Sources: monitor/monitor.c96-145 agent/agent.go1-100 agent/engine.go1-100 controller/controller.go1-100 share/cluster
Each node runs a three-tier stack where each tier has distinct responsibilities:
Sources: monitor/monitor.c138-145 monitor/monitor.c241-428 agent/agent.go256-300 agent/engine.go1-50 agent/probe/probe.go1-50 dp/ctrl.c1-50 dp/dpi/dpi_policy.c1-50
The Controller cluster provides centralized management, policy distribution, and scan orchestration:
Sources: controller/controller.go214-300 controller/grpc.go1-50 controller/cache/policy.go1-50 controller/cache/connect.go1-150 controller/kv controller/resource
The following diagram shows how data flows through the system from packet capture to policy enforcement and event reporting:
Sources: dp/dpi/dpi_packet.c agent/probe/process.go1058-1179 agent/timer.go1-100 agent/policy/network.go1-100 agent/cluster.go180-250 controller/grpc.go100-200 controller/cache/connect.go100-300
Policies flow from definition through validation, storage, distribution, and enforcement:
Sources: controller/rest/policy.go controller/cache/policy.go1-50 controller/resource/admission.go controller/opa agent/system.go365-407 agent/policy/network.go1-100 dp/dpi/dpi_policy.c127-177 agent/probe/process.go770-847 agent/group_profile.go1-50
NeuVector deeply integrates with Kubernetes through multiple mechanisms:
Sources: controller/resource controller/nvk8sapi/neuvectorcrd controller/resource/admission.go controller/resource/workload.go share/migration
| Subsystem | Primary Components | Key Functions | Storage |
|---|---|---|---|
| Process Supervision | monitor/monitor.c | fork_exec(), heartbeat monitoring | Shared memory dp_mnt_shm_t |
| Network Policy | agent/policy/network.go, dp/dpi/dpi_policy.c | pe.CalculatePolicy(), dpi_policy_check() | KV: share.CLUSPolicyRule |
| Container Lifecycle | agent/engine.go | programPorts(), changeContainerWire() | gInfo.activeContainers |
| Process Monitoring | agent/probe/process.go | handleProcFork(), handleProcExec() | pidProcMap, procHistoryMap |
| Connection Tracking | agent/timer.go, dp/dpi/dpi_log.c | aggregateAndReportConnections() | connectionMap, threatLogCache |
| Vulnerability Scanning | controller/scan/, controller/grpc.go | ScanService.ScannerRegister() | KV: share.CLUSScanReport |
| Policy Distribution | controller/cache/policy.go | systemConfigPolicyVersion() | KV: versioned slots |
| Admission Control | controller/resource/admission.go | webhookValidate() | OPA Rego policies |
| Network Graph | controller/cache/connect.go | wlGraph.Merge() | graphMutex, wlGraph |
| CRD Processing | controller/nvk8sapi/neuvectorcrd | nvcrd.StartWatch(), async queue | crdqueue |
Sources: monitor/monitor.c138-145 agent/policy/network.go1-100 agent/engine.go1-100 agent/probe/process.go1-100 agent/timer.go1-100 controller/scan controller/grpc.go1-100 controller/cache/policy.go1-100 controller/resource/admission.go controller/cache/connect.go1-150 controller/nvk8sapi/neuvectorcrd
NeuVector components communicate through multiple channels optimized for different use cases:
| Protocol | Port | Purpose | Implementation | Compression |
|---|---|---|---|---|
| gRPC | 18400 | Agent → Controller reporting | share.ControllerService, controller/grpc.go | gzip >1200 bytes |
| gRPC | Agent-specific | Controller → Agent control | share.EnforcerCapService, agent/rpc.go | gzip >1200 bytes |
| REST | 10443 | Management API | controller/rest/, Gin framework | JSON |
| REST | 11443 | Federation sync | controller/fed.go | JSON |
| Webhook | 20443 | Kubernetes admission | controller/resource/admission.go | JSON |
| Webhook | 30443 | CRD validation | controller/nvk8sapi/neuvectorcrd | JSON |
| Unix Socket | /tmp/dp_listen.sock | Agent ↔ DP control | dp/ctrl.c, agent/dp/dp.go | Binary |
| Shared Memory | /dev/shm/dp_mnt | Monitor ↔ DP heartbeat | monitor/monitor.c:191-215 | Binary struct |
| Serf Gossip | 7946 (default) | Cluster membership | share/cluster | Serf protocol |
| Consul/etcd | 8500/2379 | Distributed KV store | share/cluster | Raft consensus |
Sources: controller/grpc.go1-100 agent/rpc.go controller/rest controller/fed.go controller/resource/admission.go dp/ctrl.c1-100 agent/dp/dp.go1-100 monitor/monitor.c191-215 share/cluster
The system initializes in a coordinated sequence to ensure proper startup:
Sources: monitor/monitor.c429-750 monitor/monitor.c191-215 agent/agent.go256-600 controller/controller.go214-700 agent/cluster.go99-125 agent/system.go48-59
Configuration flows from user input through controllers to enforcement points, with state maintained in multiple layers:
| Layer | Storage | Scope | Update Mechanism | Example Keys |
|---|---|---|---|---|
| User Config | Cluster KV | Global | REST API, CRDs | share.CLUSPolicyKey(), share.CLUSGroupKey() |
| Computed Policy | Cluster KV (versioned) | Per-node | Recalculation engine | share.CLUSRecalPolicyIPRulesKey() with version |
| Controller Cache | In-memory | Controller-local | KV watch handlers | policyCache.ruleMap, wlGraph |
| Agent Cache | In-memory | Agent-local | gRPC push, KV watch | gInfo.containerConfig, grpProfileCacheMap |
| DP Policy | In-memory (RCU) | Per-DP thread | Binary protocol | g_ep_map, dpi_policy_hdl_t |
| Process State | In-memory | Agent-local | Event-driven | pidProcMap, containerMap |
| Workload Metadata | Cluster KV | Global | Agent reports | share.CLUSWorkloadKey() |
| Event Logs | Cluster KV (queued) | Global | Async append | share.CLUSControllerEventLogKey() |
Sources: controller/cache/policy.go26-44 agent/system.go310-407 agent/engine.go88-161 agent/group_profile.go22-33 dp/dpi/dpi_policy.c34-130 agent/probe/process.go25-120
NeuVector supports multiple deployment configurations:
| Mode | Components | Use Case | Initialization |
|---|---|---|---|
| Enforcer | Monitor + Agent + DP | Worker node enforcement | monitor.c:g_mode = MODE_AGENT |
| Controller | Monitor + Controller | Management plane | monitor.c:g_mode = MODE_CTRL |
| All-in-One | Monitor + Controller + Agent + DP | Single-node or dev | monitor.c:g_mode = MODE_CTRL_AGENT |
| Scanner | Scanner only | Standalone scanning | monitor.c:g_mode = MODE_SCANNER |
Each mode is determined by the MODE_* environment variable parsed in monitor/monitor.c429-520 and affects which processes are spawned via fork_exec() in monitor/monitor.c241-428
Sources: monitor/monitor.c96-111 monitor/monitor.c241-520 agent/agent.go276 controller/controller.go246
NeuVector's architecture achieves runtime container security through:
The modular design allows components to operate independently while maintaining coordinated security enforcement across the cluster.
Refresh this wiki