node-agent

NodeAgent

Real-time Kubernetes runtime security powered by eBPF

NodeAgent is a Kubernetes runtime security agent that uses eBPF (extended Berkeley Packet Filter) to detect and prevent threats in real-time. It's a core component of the Kubescape security platform, a CNCF incubating project.

NodeAgent monitors container behavior at the kernel level, learns normal application patterns, and alerts on anomalies and known attack techniques—all with minimal performance overhead.

🛡️ Why Use NodeAgent?

• Zero-Config Threat Detection: Automatically detects command injection, privilege escalation, crypto miners, and more
• Behavioral Learning: Learns your application's normal behavior and alerts on anomalies
• eBPF-Powered: Kernel-level visibility with minimal performance impact (~1-2% CPU overhead)
• Image-Based Gadgets: Modern, portable eBPF programs using Inspektor Gadget image format
• Cloud-Native: Built for Kubernetes, integrates with existing security workflows
• Open Source: Apache 2.0 licensed, CNCF incubating project

✨ Features

📖 Table of Contents

• Quick Start
• Installation
• Architecture
• Configuration
• Image-Based Gadgets
• Detection Rules
• Demos & Examples
• Troubleshooting
• Development
• Contributing
• License

🚀 Quick Start

Get NodeAgent running in your cluster in under 5 minutes:

# Add the Kubescape Helm repository
helm repo add kubescape https://kubescape.github.io/helm-charts/
helm repo update

# Install with runtime detection enabled
helm upgrade --install kubescape kubescape/kubescape-operator \
  -n kubescape --create-namespace \
  --set clusterName=$(kubectl config current-context) \
  --set capabilities.runtimeDetection=enable \
  --set alertCRD.installDefault=true

# Wait for node-agent pods to be ready
kubectl wait --for=condition=Ready pods -l app=node-agent -n kubescape --timeout=300s

# View alerts (after learning period completes)
kubectl logs -n kubescape -l app=node-agent -f

Test it out:

# After the learning period (~2 minutes by default), run:
kubectl exec -it <any-pod> -- sh -c "cat /etc/passwd"

# You should see an alert in the node-agent logs!

📦 Installation

Kubernetes (Recommended)

Deploy NodeAgent as part of the Kubescape operator:

helm repo add kubescape https://kubescape.github.io/helm-charts/
helm repo update

helm upgrade --install kubescape kubescape/kubescape-operator \
  -n kubescape --create-namespace \
  --set clusterName=$(kubectl config current-context) \
  --set capabilities.runtimeDetection=enable \
  --set capabilities.malwareDetection=enable \
  --set alertCRD.installDefault=true \
  --set alertCRD.scopeClustered=true

With AlertManager integration:

helm upgrade --install kubescape kubescape/kubescape-operator \
  -n kubescape --create-namespace \
  --set clusterName=$(kubectl config current-context) \
  --set capabilities.runtimeDetection=enable \
  --set nodeAgent.config.alertManagerExporterUrls=alertmanager-operated.monitoring.svc.cluster.local:9093

For full configuration options, see the Kubescape documentation.

Standalone (Development/Testing)

Build and run NodeAgent directly on a Linux host:

# Clone the repository
git clone https://github.com/kubescape/node-agent.git
cd node-agent

# Build the binary
CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o node-agent ./cmd/main.go

# Set required environment variables
export NODE_NAME=$(hostname)
export KUBECONFIG=~/.kube/config

# Run with root privileges (required for eBPF)
sudo ./node-agent

Docker

# Build the image
docker buildx build -t node-agent -f build/Dockerfile --load .

# Run (requires privileged mode for eBPF)
docker run --privileged --pid=host --network=host \
  -v /sys:/sys:ro \
  -v /proc:/proc:ro \
  -e NODE_NAME=$(hostname) \
  node-agent

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Kubernetes Node                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                         NodeAgent Pod                                │   │
│  │                                                                      │   │
│  │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │   │
│  │  │  Tracer Manager  │  │  Rule Manager    │  │  Profile Manager │  │   │
│  │  │                  │  │                  │  │                  │  │   │
│  │  │ • Exec Tracer    │  │ • CEL Evaluator  │  │ • App Profiles   │  │   │
│  │  │ • Open Tracer    │  │ • Rule Bindings  │  │ • Network Neigh. │  │   │
│  │  │ • Network Tracer │  │ • Cooldown Mgmt  │  │ • Seccomp Gen.   │  │   │
│  │  │ • DNS Tracer     │  │                  │  │                  │  │   │
│  │  │ • + 15 more...   │  │                  │  │                  │  │   │
│  │  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘  │   │
│  │           │                     │                     │            │   │
│  │           └─────────────────────┼─────────────────────┘            │   │
│  │                                 │                                  │   │
│  │                    ┌────────────▼────────────┐                     │   │
│  │                    │   Ordered Event Queue   │                     │   │
│  │                    │   (Process Tree Aware)  │                     │   │
│  │                    └────────────┬────────────┘                     │   │
│  │                                 │                                  │   │
│  │           ┌─────────────────────┼─────────────────────┐            │   │
│  │           │                     │                     │            │   │
│  │  ┌────────▼─────────┐  ┌────────▼─────────┐  ┌────────▼─────────┐  │   │
│  │  │  HTTP Exporter   │  │ AlertMgr Export  │  │  Stdout Export   │  │   │
│  │  │  (Alert Bulking) │  │                  │  │                  │  │   │
│  │  └──────────────────┘  └──────────────────┘  └──────────────────┘  │   │
│  │                                                                      │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                        │
│                                    │ eBPF                                   │
│                                    ▼                                        │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │                           Linux Kernel                                │  │
│  │                                                                       │  │
│  │   ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │  │
│  │   │  exec   │ │  open   │ │ network │ │   dns   │ │  kmod   │ ...   │  │
│  │   │ probes  │ │ probes  │ │ probes  │ │ probes  │ │ probes  │       │  │
│  │   └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘       │  │
│  │                                                                       │  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│                                                                             │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                        │
│  │Container│  │Container│  │Container│  │Container│  ...                   │
│  │   A     │  │   B     │  │   C     │  │   D     │                        │
│  └─────────┘  └─────────┘  └─────────┘  └─────────┘                        │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Key Components

⚙️ Configuration

NodeAgent is configured through a JSON configuration file and environment variables.

Environment Variables

Configuration File

See docs/CONFIGURATION.md for the complete configuration reference.

Example minimal config:

{
  "applicationProfileServiceEnabled": true,
  "runtimeDetectionEnabled": true,
  "malwareDetectionEnabled": true,
  "networkServiceEnabled": true,
  "prometheusExporterEnabled": true
}

Feature Toggles

🔌 Image-Based Gadgets

NodeAgent uses Inspektor Gadget's image-based gadget format for portable, versioned eBPF programs.

Built-in Gadgets

Building Gadgets

# Build all Kubescape gadgets
make gadgets

# Build a specific gadget
make -C ./pkg/ebpf/gadgets/exec build IMAGE=exec TAG=latest

Third-Party Gadgets

NodeAgent supports registering custom third-party tracers. See the ThirdPartyTracers interface in pkg/containerwatcher/container_watcher_interface.go.

🔍 Detection Rules

NodeAgent uses CEL (Common Expression Language) for flexible rule definition. Rules are defined as Kubernetes Custom Resources.

Example Rule Binding

apiVersion: kubescape.io/v1
kind: RuntimeAlertRuleBinding
metadata:
  name: default-rules
spec:
  ruleset:
    - ruleName: "Unexpected Process Launched"
      ruleID: "R0001"
      severity: high
    - ruleName: "Crypto Mining Detected"
      ruleID: "R1001"
      severity: critical
  namespaceSelector:
    matchLabels:
      environment: production

Built-in Rule Categories

• Process Rules: Unexpected executables, shell spawning, script execution
• File Rules: Sensitive file access, file integrity violations
• Network Rules: Unexpected connections, DNS tunneling, data exfiltration
• Privilege Rules: Capability usage, privilege escalation attempts
• Crypto Rules: Mining activity detection via RandomX
• Container Rules: Escape attempts, namespace manipulation

For the full list of rules, see the Kubescape documentation.

🎮 Demos & Examples

We provide comprehensive demos showcasing NodeAgent's capabilities:

Available Demos

Running the Demo

# Follow the complete walkthrough
cat demo/README.md

# Or run individual demos:

# 1. Deploy vulnerable web app
./demo/general_attack/webapp/setup.sh

# 2. Attack it and watch NodeAgent detect:
#    - Command injection
#    - Service account token access
#    - Kubernetes API access

# 3. Deploy fileless malware
kubectl apply -f demo/fileless_exec/kubernetes-manifest.yaml

# 4. Deploy image with malware
kubectl run malware-cryptominer --image=quay.io/petr_ruzicka/malware-cryptominer-container:2.0.2

# 5. Check alerts
kubectl logs -n kubescape -l app=node-agent -f

See the full Demo Guide for detailed instructions with screenshots.

🔧 Troubleshooting

Common Issues

NodeAgent pod not starting

# Check pod status
kubectl get pods -n kubescape -l app=node-agent

# Check logs
kubectl logs -n kubescape -l app=node-agent --previous

# Common causes:
# - Kernel version too old (need 5.4+)
# - Missing BTF support
# - Insufficient privileges

No alerts being generated

# 1. Check if learning period is complete (default: 2 minutes)
kubectl logs -n kubescape -l app=node-agent | grep "learning"

# 2. Verify rule bindings are applied
kubectl get runtimealertruleinding -A

# 3. Check if the namespace is excluded
kubectl get configmap -n kubescape kubescape-config -o yaml | grep excludeNamespaces

High CPU usage

# Check current configuration
kubectl get configmap -n kubescape node-agent-config -o yaml

# Tune these settings:
# - workerPoolSize (default: 3000)
# - eventBatchSize (default: 15000)
# - Disable unused features

eBPF verification errors

# Check kernel version
uname -r  # Should be 5.4+

# Check BTF support
ls -la /sys/kernel/btf/vmlinux

# Check if running in a supported environment
# (Some minimal containers lack required mounts)

Exit Codes

Getting Help

1. Check the Kubescape documentation
2. Search GitHub Issues
3. Join the CNCF Slack (#kubescape channel)
4. Email: support@armosec.io

🛠️ Development

Prerequisites

• Go 1.25+
• Linux with kernel 5.4+ (for eBPF)
• Docker (for building images)
• kubectl & helm (for testing)
• Root/sudo access (for running eBPF programs)

Building

# Clone the repository
git clone https://github.com/kubescape/node-agent.git
cd node-agent

# Build binary
make binary

# Build Docker image
make docker-build

# Build with gadgets
make docker-build  # Includes gadget building

Running Tests

# Unit tests
go test ./...

# With race detection
go test -race ./...

# Integration tests (requires cluster)
go test ./tests/...

Debugging

VS Code launch configuration:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Launch NodeAgent",
            "type": "go",
            "request": "launch",
            "mode": "auto",
            "program": "${workspaceFolder}/cmd/main.go",
            "env": {
                "NODE_NAME": "<node-name>",
                "KUBECONFIG": "<path-to-kubeconfig>"
            },
            "console": "integratedTerminal",
            "asRoot": true
        }
    ]
}

Enable profiling:

export ENABLE_PROFILER=true
sudo ./node-agent
# Then access http://localhost:6060/debug/pprof/

Project Structure

node-agent/
├── cmd/                    # Main entry point
├── pkg/
│   ├── config/            # Configuration handling
│   ├── containerwatcher/  # Container event monitoring
│   │   └── v2/tracers/    # eBPF tracer implementations
│   ├── ebpf/gadgets/      # Image-based eBPF gadgets
│   ├── exporters/         # Alert exporters (HTTP, AlertManager, etc.)
│   ├── malwaremanager/    # Malware detection with ClamAV
│   ├── rulemanager/       # CEL-based rule evaluation
│   ├── sbommanager/       # SBOM generation
│   └── ...
├── demo/                   # Demo applications and guides
├── docs/                   # Additional documentation
├── build/                  # Dockerfiles
└── tests/                  # Integration tests

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

Quick Links

• Code of Conduct
• Governance
• Security Policy
• Maintainers

📄 License

NodeAgent is licensed under the Apache License 2.0.

📚 Additional Resources

• Kubescape Documentation
• Alert Bulking Architecture
• Process Tree Optimization
• Configuration Reference
• CNCF Kubescape Project

📝 Changelog

See the Releases page for version history and changelogs.

Made with ❤️ by the Kubescape community