Hooks

Two kinds of hooks add what the agent does not know about: report hooks run a site check with every report, and hook uploads send a file some other tool makes.

Report hooks

Every executable file in /etc/drra/report.d runs once per report, one at a time, stopped after [hooks] timeout_seconds (60). A hook prints lines in the DRSM plugin format (INFO - , WARNING - , ERROR - , METRIC, DETAIL and free text) and exits 0 OK, 1 WARNING, 2 ERROR or 3 UNKNOWN. Its name is the file name without .sh. The report gets them in one section:

HOOKS:
hook=drcm exit=0 secs=1 timed_out=0 truncated=0
| INFO - node1 cluster status is HEALTHY, 2 nodes up, 1 resources
| METRIC drcm_nodes_up=2
END HOOKS

drra hooks runs them now and prints the section.

Hook rules

• The agent runs as root, so a hook only runs when report.d and the file are owned by root and not group or world writable. Others are listed as skipped= and logged.
• Names may use letters, digits, dot, dash and underscore. .rpmnew, .bak, .swp, .disabled and similar files are skipped.
• [hooks] user= runs them as another user. Then point dir at a folder that user can reach, since /etc/drra is root only.

Hooks in DRSM

A DRSM plugin with LRA_HOOK=<name> in its manifest shows that hook as its own check on agent hosts (the cluster/drcm plugin does this), and linux/hooks shows every hook. DRSM's utils/lra_hook_bundle.sh writes a DRSM plugin as one self-contained hook file:

$ ~/drsm/utils/lra_hook_bundle.sh cluster/drcm > drcm
# install -o root -g root -m 0755 drcm /etc/drra/report.d/drcm
# drra hooks

Hook uploads

A hook upload sends a report from another source with the agent: a scan you run by hand (so a cloud server does not pay for a daily scan), a vendor tool's export, a backup job's result. Each upload hook is a file in /etc/drra/uploads.d/ (root owned, not group or world writable):

# cat /etc/drra/uploads.d/openscap_manual.ini
[upload]
id=openscap_manual
title=Manual OpenSCAP scan
format=xccdf-results
# oscap xccdf eval --profile cis_server_l1 --results /tmp/results.xml \
    /usr/share/xml/scap/ssg/content/ssg-rhel9-ds.xml
# drra submit --hook openscap_manual --now /tmp/results.xml

A tool can also write its file to /var/spool/drra/uploads/<id>/ (write a dot or .tmp file, then rename it). Members of the drra-upload group may do both. Files go to hook.php on the report server after each report, or within seconds with --now. drra send-uploads sends them right away and drra uploads lists them. Sent files are kept in <spool>/<id>/sent/, and the report's UPLOADS section has each upload hook's state. Uploads use the https delivery method.

Server manifests

The report server only takes an upload hook that has a manifest: the DRSM plugin plugins/uploads/<id>/plugin.conf, in the folder named by [hooks] manifest_dir in server.ini. The manifest picks the format (drsm-lines, kv-sections, json, csv, xccdf-results, text, html), the alert rules and how DRSM shows the data. See "Hook uploads" in DRSM's PLUGINS.md.

Which one to use

Use a report hook for a check that must run on the host each time; use a hook upload for a file that some other tool makes now and then.