Skip to content
BHIM KVH / Reference / v0.4.0

Architecture

How the monitor, privileged response helper, local evidence, HTTP controls, and optional integrations fit together.

Verified against the local 0.4.0 source. Examples target Linux with systemd; inspect your installed version with --help.

Core data flow

Observation & evidence

Local collection, persistence, and visibility

Collect observations: journald · SSH files, HTTP logs · procfs. Then bhim-agent.service: Unprivileged bhim user, Parse and correlate observations. Then Bounded event pipeline: Admission limits, Durable spool and retry. Then Persist local evidence: SQLite primary store, Category JSONL logs. Then Inspect and integrate: CLI queries, JSONL / CSV exports1Collect observationsjournald · SSH filesHTTP logs · procfs2bhim-agent.serviceUnprivileged bhim userParse and correlate observations3Bounded event pipelineAdmission limitsDurable spool and retry4Persist local evidenceSQLite primary storeCategory JSONL logs5Inspect and integrateCLI queriesJSONL / CSV exports

Scoped response

Explicit actions or configured automatic policy

Response requested: Operator command or, configured automatic response. Then Local Unix socket: Authenticated peer UID/GID, Bounded, typed requests. Then bhim-response.service: Privileged root executor, Protected configuration. Then Validate policy: Management allowlist, Permitted scope, ports, duration. Then Enforce on the host: BHIM-owned nftables table, INPUT hook · SSH / HTTP scopes1Response requestedOperator command orconfigured automatic response2Local Unix socketAuthenticated peer UID/GIDBounded, typed requests3bhim-response.servicePrivileged root executorProtected configuration4Validate policyManagement allowlistPermitted scope, ports, duration5Enforce on the hostBHIM-owned nftables tableINPUT hook · SSH / HTTP scopes
The monitor records evidence. The separate executor applies only authorised host actions.

Privilege separation

The monitor parses and persists observations without capabilities. The root helper reads protected policy at startup and permits narrowly typed actions. The optional BCC service is a separate privileged collector. State writable by the monitor is not a root-trusted policy source.

Evidence and persistence

SQLite at state_dir/events.sqlite3 is the primary event store. Collector state and events commit together; a bounded spool supports retry. Secondary logs include security, attacks, ssh, network, process, file-integrity, firewall, malware, vulnerability, health, rollback, and system categories. Logs rotate, and retention can remove old payloads.

HTTP and WAF layers

Post-request log observation, native Nginx inline rate limits, host INPUT nftables rules, and AWS edge IP-set updates are distinct controls. The split installer does not inject native HTTP server configuration. Forwarded clients cannot be enforced through the host firewall as if they were socket peers.

Configure inline limits and proxies

Containers and Kubernetes

The source includes Dockerfiles and a node-local Helm DaemonSet. State is hostPath-backed; host procfs uses /proc/1/net. Kubernetes API credentials and automatic host blocking are disabled in that profile. Optional BCC collection is separately privileged.

helm lint deploy/helm/bhim-protection
helm template bhim deploy/helm/bhim-protection
helm template bhim deploy/helm/bhim-protection --set ebpfEnabled=true

Target Linux validation

Run these only in an isolated, disposable Linux test environment with the documented prerequisites. They exercise real enforcement or resource pressure and are not routine production health commands.

sudo python3 scripts/linux_acceptance.py --binary target/release/bhim-protection
sudo /usr/bin/python3 scripts/ebpf_acceptance.py --binary target/release/bhim-protection
sudo python3 scripts/oom_acceptance.py --binary target/release/bhim-protection
sudo python3 scripts/source_recovery_acceptance.py --binary target/release/bhim-protection --mode journal
sudo python3 scripts/source_recovery_acceptance.py --binary target/release/bhim-protection --mode enospc
Need help with your environment? Contact BHIM ↗