{"id":20447482,"url":"https://github.com/kubescape/node-agent","last_synced_at":"2026-04-03T09:01:50.585Z","repository":{"id":95595388,"uuid":"595477732","full_name":"kubescape/node-agent","owner":"kubescape","description":"Kubescape eBPF agent 🥷🏻","archived":false,"fork":false,"pushed_at":"2026-04-02T11:56:35.000Z","size":85238,"stargazers_count":31,"open_issues_count":19,"forks_count":12,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-03T01:41:26.010Z","etag":null,"topics":["ebpf","kubernetes","kubescape","security"],"latest_commit_sha":null,"homepage":"https://kubescape.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kubescape.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY-INSIGHTS.yml","support":null,"governance":"GOVERNANCE.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":"MAINTAINERS.md","copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-01-31T06:44:57.000Z","updated_at":"2026-04-02T11:56:37.000Z","dependencies_parsed_at":"2023-10-02T07:01:57.081Z","dependency_job_id":"6a433421-de55-427a-b38c-fdea528301fc","html_url":"https://github.com/kubescape/node-agent","commit_stats":null,"previous_names":["kubescape/node-agent"],"tags_count":241,"template":false,"template_full_name":null,"purl":"pkg:github/kubescape/node-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubescape%2Fnode-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubescape%2Fnode-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubescape%2Fnode-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubescape%2Fnode-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kubescape","download_url":"https://codeload.github.com/kubescape/node-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kubescape%2Fnode-agent/sbom","scorecard":{"id":466619,"data":{"date":"2025-08-19T12:35:45Z","repo":{"name":"github.com/kubescape/node-agent","commit":"7f1258f0de66ecedf8d7c0c2cd3e2d280d99d929"},"scorecard":{"version":"v5.0.0","commit":"ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4"},"score":6.2,"checks":[{"name":"Binary-Artifacts","score":0,"reason":"binaries present in source code","details":["Warn: binary detected: pkg/ebpf/gadgets/exit/tracer/exit_bpfel.o:1","Warn: binary detected: pkg/ebpf/gadgets/fork/tracer/fork_bpfel.o:1","Warn: binary detected: pkg/ebpf/gadgets/hardlink/tracer/hardlink_bpfel.o:1","Warn: binary detected: pkg/ebpf/gadgets/http/tracer/http_sniffer_bpfel.o:1","Warn: binary detected: pkg/ebpf/gadgets/iouring/tracer/iouring_63_bpfel.o:1","Warn: binary detected: pkg/ebpf/gadgets/iouring/tracer/iouring_bpfel.o:1","Warn: binary detected: pkg/ebpf/gadgets/ptrace/tracer/ptrace_bpfel.o:1","Warn: binary detected: pkg/ebpf/gadgets/randomx/tracer/randomx_bpf.o:1","Warn: binary detected: pkg/ebpf/gadgets/ssh/tracer/ssh_bpfel.o:1","Warn: binary detected: pkg/ebpf/gadgets/symlink/tracer/symlink_bpfel.o:1","Warn: binary detected: pkg/ebpf/gadgets/symlink/tracer/test/program:1"],"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#binary-artifacts"}},{"name":"Branch-Protection","score":6,"reason":"branch protection is not maximal on development and all release branches","details":["Info: 'allow deletion' disabled on branch 'main'","Info: 'force pushes' disabled on branch 'main'","Warn: 'branch protection settings apply to administrators' is disable on branch 'main'","Info: 'stale review dismissal' is required to merge on branch 'main'","Warn: required approving review count is 1 on branch 'main'","Warn: codeowners review is not required on branch 'main'","Info: 'last push approval' is required to merge on branch 'main'","Warn: no status checks found to merge onto branch 'main'","Info: PRs are required in order to make changes on branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#branch-protection"}},{"name":"CI-Tests","score":10,"reason":"21 out of 21 merged PRs checked by a CI test -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project runs tests before pull requests are merged.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#ci-tests"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#cii-best-practices"}},{"name":"Code-Review","score":8,"reason":"Found 16/20 approved changesets -- score normalized to 8","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#code-review"}},{"name":"Contributors","score":6,"reason":"project has 2 contributing companies or organizations -- score normalized to 6","details":["Info: armo contributor org/company found, armosec contributor org/company found, "],"documentation":{"short":"Determines if the project has a set of contributors from multiple organizations (e.g., companies).","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#contributors"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#dangerous-workflow"}},{"name":"Dependency-Update-Tool","score":10,"reason":"update tool detected","details":["Info: detected update tool: Dependabot: :0"],"documentation":{"short":"Determines if the project uses a dependency update tool.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#dependency-update-tool"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#license"}},{"name":"Maintained","score":10,"reason":"30 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#maintained"}},{"name":"Packaging","score":10,"reason":"packaging workflow detected","details":["Info: Project packages its releases by way of GitHub Actions.: .github/workflows/component-tests.yaml:11"],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#packaging"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: third-party GitHubAction not pinned by hash: .github/workflows/bypass.yaml:14: update your workflow using https://app.stepsecurity.io/secureworkflow/kubescape/node-agent/bypass.yaml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/component-tests.yaml:15: update your workflow using https://app.stepsecurity.io/secureworkflow/kubescape/node-agent/component-tests.yaml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/component-tests.yaml:17: update your workflow using https://app.stepsecurity.io/secureworkflow/kubescape/node-agent/component-tests.yaml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/component-tests.yaml:69: update your workflow using https://app.stepsecurity.io/secureworkflow/kubescape/node-agent/component-tests.yaml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/component-tests.yaml:105: update your workflow using https://app.stepsecurity.io/secureworkflow/kubescape/node-agent/component-tests.yaml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/pr-merged.yaml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/kubescape/node-agent/pr-merged.yaml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:35: update your workflow using https://app.stepsecurity.io/secureworkflow/kubescape/node-agent/scorecard.yml/main?enable=pin","Warn: third-party GitHubAction not pinned by hash: .github/workflows/scorecard.yml:40: update your workflow using https://app.stepsecurity.io/secureworkflow/kubescape/node-agent/scorecard.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:62: update your workflow using https://app.stepsecurity.io/secureworkflow/kubescape/node-agent/scorecard.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/scorecard.yml:70: update your workflow using https://app.stepsecurity.io/secureworkflow/kubescape/node-agent/scorecard.yml/main?enable=pin","Warn: containerImage not pinned by hash: build/Dockerfile:1","Warn: containerImage not pinned by hash: build/Dockerfile:12: pin your Docker image by updating gcr.io/distroless/static-debian12:latest to gcr.io/distroless/static-debian12:latest@sha256:2e114d20aa6371fd271f854aa3d6b2b7d2e70e797bb3ea44fb677afec60db22c","Warn: containerImage not pinned by hash: clamav/Dockerfile:3","Warn: containerImage not pinned by hash: clamav/Dockerfile:10","Warn: containerImage not pinned by hash: tests/images/malicious-app/Dockerfile:1","Warn: containerImage not pinned by hash: tests/images/malicious-app/Dockerfile:6: pin your Docker image by updating alpine:3.18 to alpine:3.18@sha256:de0eb0b3f2a47ba1eb89389859a9bd88b28e82f5826b6969ad604979713c2d4f","Warn: pipCommand not pinned by hash: clamav/create-filtered-clam-db.sh:18","Info:   0 out of   6 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   4 third-party GitHubAction dependencies pinned","Info:   0 out of   6 containerImage dependencies pinned","Info:   0 out of   1 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#pinned-dependencies"}},{"name":"SAST","score":8,"reason":"SAST tool is not run on all commits -- score normalized to 8","details":["Warn: 25 commits out of 30 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#sast"}},{"name":"Security-Policy","score":9,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Warn: One or no descriptive hints of disclosure, vulnerability, and/or timelines in security policy","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#security-policy"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#signed-releases"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Warn: no topLevel permission defined: .github/workflows/bypass.yaml:1","Warn: no topLevel permission defined: .github/workflows/component-tests.yaml:1","Warn: no topLevel permission defined: .github/workflows/pr-created.yaml:1","Warn: no topLevel permission defined: .github/workflows/pr-merged.yaml:1","Info: topLevel permissions set to 'read-all': .github/workflows/scorecard.yml:18","Info: no jobLevel write permissions found"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#token-permissions"}},{"name":"Vulnerabilities","score":7,"reason":"3 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: GO-2022-0635","Warn: Project is vulnerable to: GO-2022-0646","Warn: Project is vulnerable to: GO-2025-3460"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/ea7e27ed41b76ab879c862fa0ca4cc9c61764ee4/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-19T12:41:33.647Z","repository_id":95595388,"created_at":"2025-08-19T12:41:33.647Z","updated_at":"2025-08-19T12:41:33.647Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31344436,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T08:03:20.796Z","status":"ssl_error","status_checked_at":"2026-04-03T08:00:37.834Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ebpf","kubernetes","kubescape","security"],"created_at":"2024-11-15T10:27:17.558Z","updated_at":"2026-04-03T09:01:50.538Z","avatar_url":"https://github.com/kubescape.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# NodeAgent\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/cncf/artwork/master/projects/kubescape/icon/color/kubescape-icon-color.svg\" alt=\"Kubescape Logo\" width=\"150\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.cncf.io/projects/kubescape/\"\u003e\u003cimg src=\"https://img.shields.io/badge/CNCF-Incubating-blue?logo=cncf\" alt=\"CNCF Incubating\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/kubescape/node-agent/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/kubescape/node-agent\" alt=\"Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://golang.org/\"\u003e\u003cimg src=\"https://img.shields.io/github/go-mod/go-version/kubescape/node-agent\" alt=\"Go Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://securityscorecards.dev/viewer/?uri=github.com/kubescape/node-agent\"\u003e\u003cimg src=\"https://api.securityscorecards.dev/projects/github.com/kubescape/node-agent/badge\" alt=\"OpenSSF Scorecard\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://app.fossa.com/projects/git%2Bgithub.com%2Fkubescape%2Fsniffer?ref=badge_shield\u0026issueType=license\"\u003e\u003cimg src=\"https://app.fossa.com/api/projects/git%2Bgithub.com%2Fkubescape%2Fsniffer.svg?type=shield\u0026issueType=license\" alt=\"FOSSA Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/kubescape/node-agent/stargazers\"\u003e\u003cimg src=\"https://img.shields.io/github/stars/kubescape/node-agent?style=social\" alt=\"Stars\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cb\u003eReal-time Kubernetes runtime security powered by eBPF\u003c/b\u003e\n\u003c/p\u003e\n\n---\n\n**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](https://kubescape.io) security platform, a CNCF incubating project.\n\nNodeAgent monitors container behavior at the kernel level, learns normal application patterns, and alerts on anomalies and known attack techniques—all with minimal performance overhead.\n\n## 🛡️ Why Use NodeAgent?\n\n- **Zero-Config Threat Detection**: Automatically detects command injection, privilege escalation, crypto miners, and more\n- **Behavioral Learning**: Learns your application's normal behavior and alerts on anomalies\n- **eBPF-Powered**: Kernel-level visibility with minimal performance impact (~1-2% CPU overhead)\n- **Image-Based Gadgets**: Modern, portable eBPF programs using [Inspektor Gadget](https://www.inspektor-gadget.io/) image format\n- **Cloud-Native**: Built for Kubernetes, integrates with existing security workflows\n- **Open Source**: Apache 2.0 licensed, CNCF incubating project\n\n## ✨ Features\n\n| Category | Features |\n|----------|----------|\n| **Runtime Detection** | Unexpected process execution, shell spawning, privilege escalation, container escape attempts |\n| **Malware Scanning** | ClamAV-powered scanning for trojans, cryptominers, webshells, ransomware |\n| **Network Security** | DNS monitoring, network connection tracking, data exfiltration detection |\n| **Application Profiling** | Automatic baseline learning, seccomp profile generation |\n| **File Integrity** | Real-time file change monitoring (FIM) with fanotify backend |\n| **SBOM Generation** | Automatic Software Bill of Materials creation |\n| **Crypto Mining Detection** | RandomX instruction detection for cryptojacking |\n| **Attack Detection** | Fileless malware, eBPF program loading, kernel module insertion |\n\n## 📖 Table of Contents\n\n- [Quick Start](#-quick-start)\n- [Installation](#-installation)\n- [Architecture](#-architecture)\n- [Configuration](#-configuration)\n- [Image-Based Gadgets](#-image-based-gadgets)\n- [Detection Rules](#-detection-rules)\n- [Demos \u0026 Examples](#-demos--examples)\n- [Troubleshooting](#-troubleshooting)\n- [Development](#-development)\n- [Contributing](#-contributing)\n- [License](#-license)\n\n## 🚀 Quick Start\n\nGet NodeAgent running in your cluster in under 5 minutes:\n\n```bash\n# Add the Kubescape Helm repository\nhelm repo add kubescape https://kubescape.github.io/helm-charts/\nhelm repo update\n\n# Install with runtime detection enabled\nhelm upgrade --install kubescape kubescape/kubescape-operator \\\n  -n kubescape --create-namespace \\\n  --set clusterName=$(kubectl config current-context) \\\n  --set capabilities.runtimeDetection=enable \\\n  --set alertCRD.installDefault=true\n\n# Wait for node-agent pods to be ready\nkubectl wait --for=condition=Ready pods -l app=node-agent -n kubescape --timeout=300s\n\n# View alerts (after learning period completes)\nkubectl logs -n kubescape -l app=node-agent -f\n```\n\n**Test it out:**\n```bash\n# After the learning period (~2 minutes by default), run:\nkubectl exec -it \u003cany-pod\u003e -- sh -c \"cat /etc/passwd\"\n\n# You should see an alert in the node-agent logs!\n```\n\n## 📦 Installation\n\n### Kubernetes (Recommended)\n\nDeploy NodeAgent as part of the Kubescape operator:\n\n```bash\nhelm repo add kubescape https://kubescape.github.io/helm-charts/\nhelm repo update\n\nhelm upgrade --install kubescape kubescape/kubescape-operator \\\n  -n kubescape --create-namespace \\\n  --set clusterName=$(kubectl config current-context) \\\n  --set capabilities.runtimeDetection=enable \\\n  --set capabilities.malwareDetection=enable \\\n  --set alertCRD.installDefault=true \\\n  --set alertCRD.scopeClustered=true\n```\n\n**With AlertManager integration:**\n```bash\nhelm upgrade --install kubescape kubescape/kubescape-operator \\\n  -n kubescape --create-namespace \\\n  --set clusterName=$(kubectl config current-context) \\\n  --set capabilities.runtimeDetection=enable \\\n  --set nodeAgent.config.alertManagerExporterUrls=alertmanager-operated.monitoring.svc.cluster.local:9093\n```\n\nFor full configuration options, see the [Kubescape documentation](https://kubescape.io/docs/).\n\n### Standalone (Development/Testing)\n\nBuild and run NodeAgent directly on a Linux host:\n\n```bash\n# Clone the repository\ngit clone https://github.com/kubescape/node-agent.git\ncd node-agent\n\n# Build the binary\nCGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o node-agent ./cmd/main.go\n\n# Set required environment variables\nexport NODE_NAME=$(hostname)\nexport KUBECONFIG=~/.kube/config\n\n# Run with root privileges (required for eBPF)\nsudo ./node-agent\n```\n\n### Docker\n\n```bash\n# Build the image\ndocker buildx build -t node-agent -f build/Dockerfile --load .\n\n# Run (requires privileged mode for eBPF)\ndocker run --privileged --pid=host --network=host \\\n  -v /sys:/sys:ro \\\n  -v /proc:/proc:ro \\\n  -e NODE_NAME=$(hostname) \\\n  node-agent\n```\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                              Kubernetes Node                                 │\n├─────────────────────────────────────────────────────────────────────────────┤\n│                                                                             │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │                         NodeAgent Pod                                │   │\n│  │                                                                      │   │\n│  │  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────┐  │   │\n│  │  │  Tracer Manager  │  │  Rule Manager    │  │  Profile Manager │  │   │\n│  │  │                  │  │                  │  │                  │  │   │\n│  │  │ • Exec Tracer    │  │ • CEL Evaluator  │  │ • App Profiles   │  │   │\n│  │  │ • Open Tracer    │  │ • Rule Bindings  │  │ • Network Neigh. │  │   │\n│  │  │ • Network Tracer │  │ • Cooldown Mgmt  │  │ • Seccomp Gen.   │  │   │\n│  │  │ • DNS Tracer     │  │                  │  │                  │  │   │\n│  │  │ • + 15 more...   │  │                  │  │                  │  │   │\n│  │  └────────┬─────────┘  └────────┬─────────┘  └────────┬─────────┘  │   │\n│  │           │                     │                     │            │   │\n│  │           └─────────────────────┼─────────────────────┘            │   │\n│  │                                 │                                  │   │\n│  │                    ┌────────────▼────────────┐                     │   │\n│  │                    │   Ordered Event Queue   │                     │   │\n│  │                    │   (Process Tree Aware)  │                     │   │\n│  │                    └────────────┬────────────┘                     │   │\n│  │                                 │                                  │   │\n│  │           ┌─────────────────────┼─────────────────────┐            │   │\n│  │           │                     │                     │            │   │\n│  │  ┌────────▼─────────┐  ┌────────▼─────────┐  ┌────────▼─────────┐  │   │\n│  │  │  HTTP Exporter   │  │ AlertMgr Export  │  │  Stdout Export   │  │   │\n│  │  │  (Alert Bulking) │  │                  │  │                  │  │   │\n│  │  └──────────────────┘  └──────────────────┘  └──────────────────┘  │   │\n│  │                                                                      │   │\n│  └──────────────────────────────────────────────────────────────────────┘   │\n│                                    │                                        │\n│                                    │ eBPF                                   │\n│                                    ▼                                        │\n│  ┌──────────────────────────────────────────────────────────────────────┐  │\n│  │                           Linux Kernel                                │  │\n│  │                                                                       │  │\n│  │   ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐       │  │\n│  │   │  exec   │ │  open   │ │ network │ │   dns   │ │  kmod   │ ...   │  │\n│  │   │ probes  │ │ probes  │ │ probes  │ │ probes  │ │ probes  │       │  │\n│  │   └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘       │  │\n│  │                                                                       │  │\n│  └──────────────────────────────────────────────────────────────────────┘  │\n│                                                                             │\n│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐                        │\n│  │Container│  │Container│  │Container│  │Container│  ...                   │\n│  │   A     │  │   B     │  │   C     │  │   D     │                        │\n│  └─────────┘  └─────────┘  └─────────┘  └─────────┘                        │\n│                                                                             │\n└─────────────────────────────────────────────────────────────────────────────┘\n```\n\n### Key Components\n\n| Component | Description |\n|-----------|-------------|\n| **Tracer Manager** | Manages eBPF-based tracers for different syscalls and events |\n| **Rule Manager** | Evaluates security rules using CEL expressions |\n| **Profile Manager** | Learns and maintains application behavior profiles |\n| **Ordered Event Queue** | Ensures events are processed in correct order with process tree awareness |\n| **Alert Bulk Manager** | Batches alerts for efficient transmission |\n| **Malware Manager** | Coordinates ClamAV scanning for malware detection |\n| **SBOM Manager** | Generates Software Bill of Materials using Syft |\n\n## ⚙️ Configuration\n\nNodeAgent is configured through a JSON configuration file and environment variables.\n\n### Environment Variables\n\n| Variable | Description | Required | Default |\n|----------|-------------|----------|---------|\n| `NODE_NAME` | Kubernetes node name | Yes (in K8s) | - |\n| `POD_NAME` | Pod name | Yes (in K8s) | - |\n| `NAMESPACE_NAME` | Namespace | Yes (in K8s) | - |\n| `KUBECONFIG` | Path to kubeconfig | Standalone only | - |\n| `CONFIG_DIR` | Configuration directory | No | `/etc/config` |\n| `SKIP_KERNEL_VERSION_CHECK` | Skip kernel validation | No | - |\n| `ENABLE_PROFILER` | Enable pprof on port 6060 | No | - |\n| `OTEL_COLLECTOR_SVC` | OpenTelemetry collector address | No | - |\n| `PYROSCOPE_SERVER_SVC` | Pyroscope server address | No | - |\n\n### Configuration File\n\nSee [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for the complete configuration reference.\n\n**Example minimal config:**\n```json\n{\n  \"applicationProfileServiceEnabled\": true,\n  \"runtimeDetectionEnabled\": true,\n  \"malwareDetectionEnabled\": true,\n  \"networkServiceEnabled\": true,\n  \"prometheusExporterEnabled\": true\n}\n```\n\n### Feature Toggles\n\n| Feature | Config Key | Default | Description |\n|---------|------------|---------|-------------|\n| Application Profiling | `applicationProfileServiceEnabled` | `false` | Learn container behavior |\n| Runtime Detection | `runtimeDetectionEnabled` | `false` | Enable threat detection rules |\n| Malware Detection | `malwareDetectionEnabled` | `false` | ClamAV-based scanning |\n| Network Tracing | `networkServiceEnabled` | `false` | Track network connections |\n| SBOM Generation | `sbomGenerationEnabled` | `false` | Generate SBOMs |\n| File Integrity | `fimEnabled` | `false` | Monitor file changes |\n| Seccomp Profiles | `seccompServiceEnabled` | `false` | Generate seccomp profiles |\n| HTTP Detection | `httpDetectionEnabled` | `false` | Parse HTTP traffic |\n| Network Streaming | `networkStreamingEnabled` | `false` | Stream network events |\n\n## 🔌 Image-Based Gadgets\n\nNodeAgent uses [Inspektor Gadget's](https://www.inspektor-gadget.io/) image-based gadget format for portable, versioned eBPF programs.\n\n### Built-in Gadgets\n\n| Gadget | Event Type | Description |\n|--------|------------|-------------|\n| `exec` | `execve` | Process execution events |\n| `open` | `open` | File open operations |\n| `network` | `network` | Network connections |\n| `dns` | `dns` | DNS queries and responses |\n| `capabilities` | `capabilities` | Capability checks |\n| `seccomp` | `syscall` | System call monitoring |\n| `exit` | `exit` | Process termination |\n| `fork` | `fork` | Process creation |\n| `symlink` | `symlink` | Symbolic link operations |\n| `hardlink` | `hardlink` | Hard link operations |\n| `ptrace` | `ptrace` | Ptrace operations |\n| `kmod` | `kmod` | Kernel module loading |\n| `ssh` | `ssh` | SSH connection events |\n| `http` | `http` | HTTP request/response |\n| `randomx` | `randomx` | RandomX crypto instructions |\n| `iouring` | `iouring` | io_uring operations |\n| `unshare` | `unshare` | Namespace operations |\n| `bpf` | `bpf` | eBPF syscall monitoring |\n\n### Building Gadgets\n\n```bash\n# Build all Kubescape gadgets\nmake gadgets\n\n# Build a specific gadget\nmake -C ./pkg/ebpf/gadgets/exec build IMAGE=exec TAG=latest\n```\n\n### Third-Party Gadgets\n\nNodeAgent supports registering custom third-party tracers. See the `ThirdPartyTracers` interface in `pkg/containerwatcher/container_watcher_interface.go`.\n\n## 🔍 Detection Rules\n\nNodeAgent uses CEL (Common Expression Language) for flexible rule definition. Rules are defined as Kubernetes Custom Resources.\n\n### Example Rule Binding\n\n```yaml\napiVersion: kubescape.io/v1\nkind: RuntimeAlertRuleBinding\nmetadata:\n  name: default-rules\nspec:\n  ruleset:\n    - ruleName: \"Unexpected Process Launched\"\n      ruleID: \"R0001\"\n      severity: high\n    - ruleName: \"Crypto Mining Detected\"\n      ruleID: \"R1001\"\n      severity: critical\n  namespaceSelector:\n    matchLabels:\n      environment: production\n```\n\n### Built-in Rule Categories\n\n- **Process Rules**: Unexpected executables, shell spawning, script execution\n- **File Rules**: Sensitive file access, file integrity violations\n- **Network Rules**: Unexpected connections, DNS tunneling, data exfiltration\n- **Privilege Rules**: Capability usage, privilege escalation attempts\n- **Crypto Rules**: Mining activity detection via RandomX\n- **Container Rules**: Escape attempts, namespace manipulation\n\nFor the full list of rules, see the [Kubescape documentation](https://kubescape.io/docs/).\n\n## 🎮 Demos \u0026 Examples\n\nWe provide comprehensive demos showcasing NodeAgent's capabilities:\n\n### Available Demos\n\n| Demo | Description | Location |\n|------|-------------|----------|\n| **Web App Attack** | Command injection detection | `demo/general_attack/` |\n| **Fileless Malware** | Memory-only malware detection | `demo/fileless_exec/` |\n| **Malicious Image** | Image with embedded malware | `demo/malwares_image/` |\n| **Crypto Miner** | XMRig mining detection | `demo/miner/` |\n\n### Running the Demo\n\n```bash\n# Follow the complete walkthrough\ncat demo/README.md\n\n# Or run individual demos:\n\n# 1. Deploy vulnerable web app\n./demo/general_attack/webapp/setup.sh\n\n# 2. Attack it and watch NodeAgent detect:\n#    - Command injection\n#    - Service account token access\n#    - Kubernetes API access\n\n# 3. Deploy fileless malware\nkubectl apply -f demo/fileless_exec/kubernetes-manifest.yaml\n\n# 4. Deploy image with malware\nkubectl run malware-cryptominer --image=quay.io/petr_ruzicka/malware-cryptominer-container:2.0.2\n\n# 5. Check alerts\nkubectl logs -n kubescape -l app=node-agent -f\n```\n\nSee the full [Demo Guide](demo/README.md) for detailed instructions with screenshots.\n\n## 🔧 Troubleshooting\n\n### Common Issues\n\n#### NodeAgent pod not starting\n\n```bash\n# Check pod status\nkubectl get pods -n kubescape -l app=node-agent\n\n# Check logs\nkubectl logs -n kubescape -l app=node-agent --previous\n\n# Common causes:\n# - Kernel version too old (need 5.4+)\n# - Missing BTF support\n# - Insufficient privileges\n```\n\n#### No alerts being generated\n\n```bash\n# 1. Check if learning period is complete (default: 2 minutes)\nkubectl logs -n kubescape -l app=node-agent | grep \"learning\"\n\n# 2. Verify rule bindings are applied\nkubectl get runtimealertruleinding -A\n\n# 3. Check if the namespace is excluded\nkubectl get configmap -n kubescape kubescape-config -o yaml | grep excludeNamespaces\n```\n\n#### High CPU usage\n\n```bash\n# Check current configuration\nkubectl get configmap -n kubescape node-agent-config -o yaml\n\n# Tune these settings:\n# - workerPoolSize (default: 3000)\n# - eventBatchSize (default: 15000)\n# - Disable unused features\n```\n\n#### eBPF verification errors\n\n```bash\n# Check kernel version\nuname -r  # Should be 5.4+\n\n# Check BTF support\nls -la /sys/kernel/btf/vmlinux\n\n# Check if running in a supported environment\n# (Some minimal containers lack required mounts)\n```\n\n### Exit Codes\n\n| Code | Meaning |\n|------|---------|\n| `0` | Success |\n| `1` | General error |\n| `100` | runc not found |\n| `101` | Incompatible kernel |\n| `102` | macOS (unsupported) |\n\n### Getting Help\n\n1. Check the [Kubescape documentation](https://kubescape.io/docs/)\n2. Search [GitHub Issues](https://github.com/kubescape/node-agent/issues)\n3. Join the [CNCF Slack](https://cloud-native.slack.com/archives/C04EY3ZF9GE) (#kubescape channel)\n4. Email: support@armosec.io\n\n## 🛠️ Development\n\n### Prerequisites\n\n- Go 1.25+\n- Linux with kernel 5.4+ (for eBPF)\n- Docker (for building images)\n- kubectl \u0026 helm (for testing)\n- Root/sudo access (for running eBPF programs)\n\n### Building\n\n```bash\n# Clone the repository\ngit clone https://github.com/kubescape/node-agent.git\ncd node-agent\n\n# Build binary\nmake binary\n\n# Build Docker image\nmake docker-build\n\n# Build with gadgets\nmake docker-build  # Includes gadget building\n```\n\n### Running Tests\n\n```bash\n# Unit tests\ngo test ./...\n\n# With race detection\ngo test -race ./...\n\n# Integration tests (requires cluster)\ngo test ./tests/...\n```\n\n### Debugging\n\n**VS Code launch configuration:**\n```json\n{\n    \"version\": \"0.2.0\",\n    \"configurations\": [\n        {\n            \"name\": \"Launch NodeAgent\",\n            \"type\": \"go\",\n            \"request\": \"launch\",\n            \"mode\": \"auto\",\n            \"program\": \"${workspaceFolder}/cmd/main.go\",\n            \"env\": {\n                \"NODE_NAME\": \"\u003cnode-name\u003e\",\n                \"KUBECONFIG\": \"\u003cpath-to-kubeconfig\u003e\"\n            },\n            \"console\": \"integratedTerminal\",\n            \"asRoot\": true\n        }\n    ]\n}\n```\n\n**Enable profiling:**\n```bash\nexport ENABLE_PROFILER=true\nsudo ./node-agent\n# Then access http://localhost:6060/debug/pprof/\n```\n\n### Project Structure\n\n```\nnode-agent/\n├── cmd/                    # Main entry point\n├── pkg/\n│   ├── config/            # Configuration handling\n│   ├── containerwatcher/  # Container event monitoring\n│   │   └── v2/tracers/    # eBPF tracer implementations\n│   ├── ebpf/gadgets/      # Image-based eBPF gadgets\n│   ├── exporters/         # Alert exporters (HTTP, AlertManager, etc.)\n│   ├── malwaremanager/    # Malware detection with ClamAV\n│   ├── rulemanager/       # CEL-based rule evaluation\n│   ├── sbommanager/       # SBOM generation\n│   └── ...\n├── demo/                   # Demo applications and guides\n├── docs/                   # Additional documentation\n├── build/                  # Dockerfiles\n└── tests/                  # Integration tests\n```\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](https://github.com/kubescape/project-governance/blob/main/CONTRIBUTING.md).\n\n### Quick Links\n\n- [Code of Conduct](https://github.com/kubescape/project-governance/blob/main/CODE_OF_CONDUCT.md)\n- [Governance](https://github.com/kubescape/project-governance/blob/main/GOVERNANCE.md)\n- [Security Policy](https://github.com/kubescape/project-governance/blob/main/SECURITY.md)\n- [Maintainers](https://github.com/kubescape/project-governance/blob/main/MAINTAINERS.md)\n\n## 📄 License\n\nNodeAgent is licensed under the [Apache License 2.0](LICENSE).\n\n## 📚 Additional Resources\n\n- [Kubescape Documentation](https://kubescape.io/docs/)\n- [Alert Bulking Architecture](docs/ALERT_BULKING.md)\n- [Process Tree Optimization](docs/PROCESS_TREE_CHAIN_OPTIMIZATION.md)\n- [Configuration Reference](docs/CONFIGURATION.md)\n- [CNCF Kubescape Project](https://www.cncf.io/projects/kubescape/)\n\n## 📝 Changelog\n\nSee the [Releases](https://github.com/kubescape/node-agent/releases) page for version history and changelogs.\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ by the \u003ca href=\"https://github.com/kubescape\"\u003eKubescape\u003c/a\u003e community\n\u003c/p\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubescape%2Fnode-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkubescape%2Fnode-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkubescape%2Fnode-agent/lists"}