Re: Comprehensive Documentation on the Linux Audit Framework

Re: Comprehensive Documentation on the Linux Audit Framework

[Richard Guy Briggs]

On 2023-06-05 18:17, Vincent Abraham wrote:
> Greetings,
> Could anyone point me to a source for comprehensive documentation for the
> Linux audit framework? I want to know how the framework interacts with the
> kernel to retrieve log information.

This is the place to start:
	https://github.com/linux-audit/audit-documentation/wiki

And this is the top level page for the 4 sub-projects:
	https://github.com/linux-audit

> Thanks.

- RGB

--
Richard Guy Briggs <rgb@redhat.com>
Sr. S/W Engineer, Kernel Security, Base Operating Systems
Remote, Ottawa, Red Hat Canada
IRC: rgb, SunRaycer
Voice: +1.647.777.2635, Internal: (81) 32635
--
Linux-audit mailing list
Linux-audit@redhat.com
https://listman.redhat.com/mailman/listinfo/linux-audit

Re: Comprehensive Documentation on the Linux Audit Framework

[Steve Grubb]

On Monday, June 5, 2023 6:17:28 PM EDT Vincent Abraham wrote:
> Greetings,
> Could anyone point me to a source for comprehensive documentation for the
> Linux audit framework? I want to know how the framework interacts with the
> kernel to retrieve log information.

If you look at the README page of the userspace portion of code, it mentions 
that there is a netlink api. It simply listens and writes what it finds to 
disk. Auditing must be enabled and you need to set the pid in the kernel and 
then listen for events. There is no extensive documentation - the code is the 
documentation to the low level API.

There is also a best effort multicast netlink api that systemd-journald uses 
to get events out of the kernel.

-Steve


--
Linux-audit mailing list
Linux-audit@redhat.com
https://listman.redhat.com/mailman/listinfo/linux-audit

Re: Comprehensive Documentation on the Linux Audit Framework

[Steve Grubb]

On Tuesday, June 6, 2023 6:31:55 PM EDT Vincent Abraham wrote:
> Thanks. Could you also point to portions in the codebase where these
> functions are called for monitoring file access?

I'll let Richard or Paul point to the place in the kernel if that's 
necessary. I think there's a fundamental mismatch and it might not matter.

> The reason I'm asking for this is that I'm trying to provide auditing for
> files of a specific type and I'm trying to understand how would that work.

The way the audit system works is there is a rule engine in the kernel. User 
space loads the rules and and listens for events. The kernel does all the 
work. This rule matching can be done by a limited set of attributes which for 
a file would be path, kind of access, who is accessing it, program accessing 
it, portions of se linux labeling, and a few other things.

You cannot match by type or anything that looks like a glob. You can arrange 
them in a directory and watch the whole directory. You can create a script 
that looks for files of a certain type and load rules specifically for them 
into the kernel (with a specific key so you can find them later). Or you can 
plug into auditd as a plugin and filter the events and write them to your own 
log.

There might be some other approaches such as using fanotify and filtering 
those events yourself.

-Steve


--
Linux-audit mailing list
Linux-audit@redhat.com
https://listman.redhat.com/mailman/listinfo/linux-audit

Re: Comprehensive Documentation on the Linux Audit Framework

[Paul Moore]

On Tue, Jun 6, 2023 at 3:09 PM Steve Grubb <sgrubb@redhat.com> wrote:
> On Tuesday, June 6, 2023 6:31:55 PM EDT Vincent Abraham wrote:
> > Thanks. Could you also point to portions in the codebase where these
> > functions are called for monitoring file access?
>
> I'll let Richard or Paul point to the place in the kernel if that's
> necessary. I think there's a fundamental mismatch and it might not matter.

The audit subsystem in the Linux Kernel is currently found in the core
kernel/ directory:

% ls -1 kernel/audit*
kernel/audit.c
kernel/auditfilter.c
kernel/audit_fsnotify.c
kernel/audit.h
kernel/auditsc.c
kernel/audit_tree.c
kernel/audit_watch.c

> ... would be path, kind of access, who is accessing it, program accessing
> it, portions of se linux labeling, and a few other things.

FYI for everyone on the thread, the generally accepted way to write to
"SELinux" is as one word (no space between the "SE" and "Linux") and
with the first three letters capitalized.  I know we can be a little
lazy with capitalization, I definitely am, but writing it as one word
is the important part.

-- 
paul-moore.com

--
Linux-audit mailing list
Linux-audit@redhat.com
https://listman.redhat.com/mailman/listinfo/linux-audit

Re: Comprehensive Documentation on the Linux Audit Framework

[Richard Guy Briggs]

On 2023-06-06 18:01, Paul Moore wrote:
> On Tue, Jun 6, 2023 at 3:09 PM Steve Grubb <sgrubb@redhat.com> wrote:
> > On Tuesday, June 6, 2023 6:31:55 PM EDT Vincent Abraham wrote:
> > > Thanks. Could you also point to portions in the codebase where these
> > > functions are called for monitoring file access?
> >
> > I'll let Richard or Paul point to the place in the kernel if that's
> > necessary. I think there's a fundamental mismatch and it might not matter.
> 
> The audit subsystem in the Linux Kernel is currently found in the core
> kernel/ directory:
> 
> % ls -1 kernel/audit*
> kernel/audit.c
> kernel/auditfilter.c
> kernel/audit_fsnotify.c
> kernel/audit.h
> kernel/auditsc.c
> kernel/audit_tree.c
> kernel/audit_watch.c

I could have sworn I'd sent a reply yesterday afternoon with pointers to
three functions to start with, but it didn't make it to the list and I
have no record of it...

Directives from userspace come in here:
	https://github.com/linux-audit/audit-kernel/blob/main/kernel/audit.c#L1542
and are processed here:
	https://github.com/linux-audit/audit-kernel/blob/main/kernel/audit.c#L1204

For file access rules, see 
	https://github.com/linux-audit/audit-kernel/blob/main/kernel/audit_watch.c
For directory access rules, if you dare to tread, see
	https://github.com/linux-audit/audit-kernel/blob/main/kernel/audit_tree.c

Once rules are in place, there are hooks all over the kernel to monitor
activity in various subsystems.

Have a look at audit_log_start() that generates the log messages:
	https://github.com/linux-audit/audit-kernel/blob/main/kernel/audit.c#L1829

and kauditd_send_queue() which manages the queues:
	https://github.com/linux-audit/audit-kernel/blob/main/kernel/audit.c#L718

> > ... would be path, kind of access, who is accessing it, program accessing
> > it, portions of se linux labeling, and a few other things.
> 
> FYI for everyone on the thread, the generally accepted way to write to
> "SELinux" is as one word (no space between the "SE" and "Linux") and
> with the first three letters capitalized.  I know we can be a little
> lazy with capitalization, I definitely am, but writing it as one word
> is the important part.
> 
> -- 
> paul-moore.com

- RGB

--
Richard Guy Briggs <rgb@redhat.com>
Sr. S/W Engineer, Kernel Security, Base Operating Systems
Remote, Ottawa, Red Hat Canada
IRC: rgb, SunRaycer
Voice: +1.647.777.2635, Internal: (81) 32635
--
Linux-audit mailing list
Linux-audit@redhat.com
https://listman.redhat.com/mailman/listinfo/linux-audit