AUDIT_SUBMIT(3)

✨ NAME ✨

okay bestie, this is AUDIT_SUBMIT(3) from the Library Functions Manual, and audit_submit is literally the general purpose audit record submission function. no cap, that's the whole gig 🫶

📚 LIBRARY 📚

it lives in the Basic Security Module Library (libbsm, -lbsm) — iconic, we love a specialized library 💅

🌈 SYNOPSIS 🌈

#include <bsm/libbsm.h>

int
audit_submit(short au_event, au_id_t auid, char status, int reterr,
    const char * restrict format, ...);

💖 DESCRIPTION 💖

audit_submit() is your generic programming interface for audit record submission. the record it makes has a header, a subject token, an optional text token, a return token, and a trailer. it's giving full audit ensemble, fr fr ✨

• the header contains the event class specified by au_event.
• the subject token is generated based on auid.
• the return token depends on the status and reterr arguments. real talk: unlike the argument to au_to_return, reterr should be a local rather than BSM error number — do not mix those up, bestie 😭
• optionally, a text token gets created as part of this record.

the text token output is under the control of a format string. that string specifies how the subsequent arguments — or arguments accessed via the variable-length argument facilities of stdarg(3) — are converted for output. if format is NULL, then no text token is created in the audit record. periodt. 🎀

important vibe check: audit_submit() assumes that setaudit(2) or setaudit_addr(2) has already been called. as a direct result, the terminal ID for the subject will be retrieved from the kernel via getaudit(2) or getaudit_addr(2). iykyk 👑

🔥 RETURN VALUES 🔥

if successful, audit_submit will return zero — slay. otherwise, -1 is returned, and the global variable errno is set to indicate the error. so check that errno, okay? 🫶

🧚 EXAMPLES 🧚

okay so here's the example, and it's lowkey main character energy: audit_bad_su tries getaudit_addr() first, falls back to getaudit() when it gets ENOSYS, then calls audit_submit() with AUE_su, EPERM, and a format string. iconic behavior, ngl 💜

#include <bsm/audit.h>
#include <bsm/libbsm.h>
#include <bsm/audit_uevents.h>

#include <stdio.h>
#include <stdarg.h>
#include <errno.h>

void
audit_bad_su(char *from_login, char *to_login)
{
        struct auditinfo_addr aia;
        struct auditinfo ai;
        au_id_t aid;
        int error;

        error = getaudit_addr(&aia, sizeof(aia));
        if (error < 0 && errno == ENOSYS) {
                error = getaudit(&ai);
                if (error < 0)
                        err(1, "getaudit");
                aid = ai.ai_auid;
        } else if (error < 0)
                err(1, "getaudit_addr");
        else
                aid = aia.ai_auid;
        error = audit_submit(AUE_su, aid, EPERM, 1,
            "bad su from %s to %s", from_login, to_login);
        if (error != 0)
                err(1, "audit_submit");
}

will generate the following audit record:

header,94,1,su(1),0,Mon Apr 17 23:23:59 2006, + 271 msec
subject,root,root,wheel,root,wheel,652,652,0,0.0.0.0
text,bad su from from csjp to root
return,failure : Operation not permitted,1
trailer,94

🌸 SEE ALSO 🌸

• auditon(2)
• getaudit(2)
• libbsm(3)
• stdarg(3)

👑 HISTORY 👑

the audit_submit() function first appeared in OpenBSM version 1.0. OpenBSM 1.0 was introduced in FreeBSD 7.0. a whole era, honestly ⭐

💌 AUTHORS 💌

the audit_submit() function was written by Christian S.J. Peron <csjp@FreeBSD.org>. thank you for your service, king 🫡

---

mwah 💋 — this page is from Debian, dated January 18, 2008, and the manual is AUDIT_SUBMIT(3). byeee 🦋