################
Process Auditing
################

Process Auditing provides live process-execution visibility on Linux agents using
eBPF, then matches that telemetry against bundled (and optional custom) detection
scenarios on the hub manager.

It is **detect-only** process visibility. It is not File Integrity Monitoring
(FIM / whodata) and not hub **Audit Logging** (administrative Event Search under
``atomicorp-audit``).

Overview
========

- **Collect** — Agent eBPF exec telemetry (``<runtime_telemetry>`` / ``exec.bpf.o``)
- **Filter** — Hub merges shipped, user, and scenario ignore rules into agent conf
- **Detect** — Manager rules under parents **65301** (``process_exec``) and **65302**
  (``shell_pipeline``); bundled scenarios **100501–100512**
- **Explain** — Asset Management → Policy → **Process Auditing** scenario gallery

Prerequisites
=============

- Linux **ossec-hids-agent 5.0.0+** with ``lib/exec.bpf.o`` installed
- Kernel **5.8+** with BTF (typical RHEL/Rocky 9+, recent Ubuntu)
- Hub **awpd 7.1.3+** and **awp-web 7.1.2+** for the Process Auditing UI
- Current **Atomicorp HIDS Rules** feed (includes ASL runtime parents and scenarios)

Enable Process Auditing
=======================

1. Open **Asset Management** and select an agent group (or Global where applicable).
2. Open **Policy** → **Process Auditing**.
3. Set process exec collection to **yes** and save.

When Process Auditing is first enabled for a group, the hub seeds catalog scenario
defaults (all bundled scenarios on) into ``runtime-scenarios.json`` and applies
them to manager ``rules.json`` so the UI and detection rules stay aligned.

Browsing scenarios does not require collection to be on; enabling a scenario that
needs telemetry will turn collection on when applied.

Detection scenarios
===================

Bundled scenarios (**100501–100512**) explain a common attack path: what to look
for, which telemetry fields matter, how the rule matches, and how to find alerts
in Event Search.

- List rows show MITRE techniques, why the scenario matters, and best-effort 24h
  match counts.
- Open a scenario for ATT&CK links and **Search events for rule {id}**.
- Most scenarios parent on **65301** (``process_exec``). Scenario **100502**
  (curl/wget shell pipeline) parents on **65302** (``shell_pipeline``).

What toggles do
===============

Scenario toggles arm or disarm the corresponding manager rule IDs via the hub.

.. note::

   Manager rule enablement is the **union across all agent groups**. Disabling a
   scenario in one group does not disable the rule if another group still enables
   it.

Enabling some scenarios may force ``exec=yes`` and can set a Kubernetes profile /
``containers_only`` when the catalog suggests it.

Filter rules
============

Filter rules control which exec events the agent emits. The hub merges:

- User-defined Process Auditing filters
- Suggested ignores from enabled scenarios

into each group's agent ``<runtime_telemetry>`` configuration on the next OSSEC
scan / agent conf push.

Custom scenarios
================

Operators can define custom scenarios in the ID pool **100550–100599** (fifty IDs
fleet-wide). Custom rules are written under the manager custom rules path and
parent on **65301** unless you author otherwise.

Verification
============

1. Confirm agents in the group are **5.0.0+** and online.
2. Confirm HIDS rules loaded (``ossec-logtest -t`` on the hub manager succeeds;
   rules **65301** / **100501+** present under ``/var/ossec/etc/rules.d``).
3. Generate a matching exec (for example a benign ``/tmp`` binary for **100506**).
4. Open **Event Search** filtered by the scenario rule id.

24h scenario stats in the UI are best-effort from recent alerts, not a full
historical database.

Troubleshooting
===============

=============================  =================================================
Symptom                        Likely cause / check
=============================  =================================================
No exec telemetry              Agent version < 5.0, missing BPF object, or kernel
                               without BTF; confirm ``<runtime_telemetry><exec>yes``
No scenario matches            HIDS rules feed not applied; ``ossec-logtest -t``
Toggle on but quiet            Another group may still control union enablement;
                               or collection still off on the agent
UI shows scenarios on, no      Older hub without seed-on-enable; toggle a scenario
alerts                         or re-save Process Auditing after upgrading awpd
=============================  =================================================

See also
========

- :doc:`agent-management` — Asset Management / FIM and related policy
- HIDS rules feed documentation under Rules → HIDS
