Skip to content
Falak Neo
Getting started

Quickstart

Deploy a Falak Neo sensor on a Linux host or a Kubernetes cluster and see your first OCSF events in about five minutes.

This guide gets one sensor reporting into a core instance. By the end you will have OCSF events flowing and at least one detection firing, because we deliberately trigger one at the end.

What you need

A Linux host with kernel 5.8 or newer, root or CAP_BPF + CAP_PERFMON, and outbound TCP 443 to your core endpoint. Kernel 5.15+ with BTF is strongly recommended — see Kernel requirements.

Create an enrollment token

In the console, open Settings → Enrollment and create a token. Scope it with labels you will want to filter on later — cluster, environment, tier — because those labels are stamped onto every sensor enrolled with it.

export FALAK_ENROLLMENT_TOKEN="fnt_9d31…"
export FALAK_CORE="ingest.eu.falakneo.example:443"

The token is a one-time (or N-time) credential. It is exchanged for a durable agent identity on first contact and is never used again by that sensor.

Install the sensor

Kubernetes — one DaemonSet, no sidecars, no admission webhook:

helm upgrade --install falak-neo-minion \
  oci://registry.falakneo.example/charts/minion \
  --namespace falak-system --create-namespace \
  --set core.endpoint=$FALAK_CORE \
  --set enrollment.token=$FALAK_ENROLLMENT_TOKEN

Bare metal or VM — a single systemd unit:

curl -fsSL https://get.falakneo.example/install.sh | \
  sudo FALAK_CORE=$FALAK_CORE FALAK_TOKEN=$FALAK_ENROLLMENT_TOKEN sh

The installer verifies the release signature before it writes anything. If you would rather not pipe a script to a shell — a reasonable instinct on a security tool — the self-hosting guide covers the package and container install paths.

Confirm enrollment

sudo systemctl status falak-neo-minion
sudo falakctl status
agent_uid    9f2c1ab4-7e30-4d18-a5c9-0b7e4f6a2d91
tenant       northwind
core         ingest.eu.falakneo.example:443  (mTLS, cert expires in 89d)
config       generation 41, applied 3s ago
probes       9 attached, 0 failed, 0 disabled
events       1,284 emitted · 0 dropped · 12 batches sent

Nine attached probes is a healthy sensor. A failed probe is a visibility gap rather than a warning — the detections that depend on it stop firing silently — so investigate before moving on. Probe reference explains what each one feeds.

Watch the events

falakctl events tail --class 1007 --limit 5

You should see OCSF 1007 Process Activity documents within a second or two. Every one is a valid OCSF v1.3 document: this is the wire format, not a rendering of it.

{
  "class_uid": 1007,
  "class_name": "Process Activity",
  "activity_id": 1,
  "type_uid": 100701,
  "severity_id": 1,
  "time": 1763458204119,
  "process": {
    "pid": 41290,
    "name": "curl",
    "cmd_line": "curl -s https://api.internal/healthz",
    "file": { "path": "/usr/bin/curl", "hashes": { "sha256": "9c2f…" } }
  },
  "device": {
    "hostname": "ip-10-40-118-14.eu-central-1.compute.internal",
    "k8s": { "namespace": "payments", "pod_name": "ledger-writer-7f9c…" }
  }
}

Trigger a detection

Fileless execution is the fastest way to prove the sensor is watching the kernel rather than reading a log. On a non-production host:

# Copies /bin/echo into an anonymous memfd and executes it.
# Harmless, and it should raise a critical finding within seconds.
python3 - <<'EOF'
import ctypes, os
libc = ctypes.CDLL("libc.so.6", use_errno=True)
fd = libc.memfd_create(b"payload", 0)
with open("/bin/echo","rb") as f: os.write(fd, f.read())
os.execv(f"/proc/self/fd/{fd}", ["memfd:payload", "falak-neo test"])
EOF

Open Alerts in the console. Within a few seconds you should see Fileless execution from an anonymous memory file descriptor, mapped to T1620 Reflective Code Loading, with the process ancestry and the exec_from_memfd flag on the exec event.

Nothing fired?

Check that the sched_process_exec probe is attached (falakctl status) and that the rule is enabled in Detection rules. If the sensor is on a kernel without BTF, see Kernel requirements.

What next

Something wrong or missing? Edit this page