Draft copy of how to write good events
Richard Guy Briggs
rgb at redhat.com
Thu Sep 4 22:08:06 UTC 2014
On 14/09/04, Richard Guy Briggs wrote:
> On 14/09/03, Steve Grubb wrote:
> > Hello,
>
> Hi Steve,
>
> > People have mentioned a couple times that they would like to know more about
> > what is expected of well written events. I put together a draft document
> > located here:
> >
> > http://people.redhat.com/sgrubb/audit/audit-events.txt
>
> Thanks for pulling this together and posting it.
>
> > The intention is to add this to the kernel documentation after people have had
> > a chance to review it and send feedback. Any and all comments are welcome.
>
> I assume the mix of new-, new_, old- and old_ are there due to
> historical raisins and changing them would break userspace...
>
> Here's a unified diff of a few obvious minor cleanups...
Er, that was my fixed up copy... Here's the diff!
> > -Steve
>
> - RGB
- RGB
--
Richard Guy Briggs <rbriggs at redhat.com>
Senior Software Engineer, Kernel Security, AMER ENG Base Operating Systems, Red Hat
Remote, Ottawa, Canada
Voice: +1.647.777.2635, Internal: (81) 32635, Alt: +1.613.693.0684x3545
-------------- next part --------------
--- audit-events.txt 2014-09-03 12:19:09.000000000 -0400
+++ audit-events-rgb1.txt 2014-09-04 17:57:13.678834211 -0400
@@ -37,21 +37,21 @@
When writing events, the author will need to list several attributes so that
no doubt can be left as to what is being recorded. For example, if we are
recording the subject, you would naturally assume we are speaking of the
-current uid. This is after all the user. Well, because of things like sudo or
+current uid, which is after all the user. Because of things like sudo or
su, users can change accounts sometimes. The audit system has a concept of
-loginuid which is the account originally logged in with. But to perform an
+loginuid which is the account originally used to login. To perform an
action, the user invokes a process, so we likely want to show which process
-is acting on the user's behalf. But is pid alone useful when reconstructing
-events? Probably not, so we should record the executable name. However, it
-turns out that if the user invoked a script, the executable is the interpreter.
-So, we also need the command name, too. Because users can log into multiple
+is acting on the user's behalf. Is pid alone useful when reconstructing
+events? Probably not, so we should record the executable name. It
+turns out that if the user invoked a script, the executable is the interpreter,
+so we also need the command name, too. Because users can log into multiple
sessions at the same time, we should also disambiguate which session they are
in with the sessionid. To summarize, we may need to record: uid, auid, pid,
exec, comm, ses fields just to specify exactly who the subject is. Some cases
may require more fields.
The same kind of process needs to be thought about when recording the object.
-Suppose the object was a file. Files are located by an inode on a device.
+Suppose the object was a file. Files are located by an inode on a device.
However, it could be edited and the inode changes. So, we need to record the
path. But if the path could be relative, we need to also record the current
working directory. The inode could contain different kind of file objects like
@@ -59,22 +59,22 @@
in case there is a question about whether access should have been allowed, we
should also gather attributes such as owner and access modes.
-The event writer should alway think about if there has been enough information
+The event writer should always think about whether there has been enough information
recorded so that later a security officer knows what the event means.
Fields
------
An audit record is composed of multiple fields. Information recorded in these
-fields are held by a name/value pair that contains an '=' between them
-(name=value). Each field is separated from one another by a space.
+fields is held by a name/value pair that contains an '=' between them
+(name=value). Each field is separated from one another by a space.
The value recorded is typically numeric. No attempt should be made to interpret
-what the value means. For example, if uid=0 is being recorded, it is not
-necessary to say that its the root account. That can be looked up in post
+the meaning of the value. For example, if uid=0 is being recorded, it is not
+necessary to say that it's the root account. That can be looked up in post
processing.
If the value side is not numeric and user space can influence the
-value, such as file names, unauthenticated acct names, process names, etc,
+value (such as file names, unauthenticated acct names, process names, etc.)
then certain precautions will need to be taken. It may turn out that a clever
user may wish to trick naive parsing to pin blame on another account or to
make it look like something else was being accessed.
@@ -85,7 +85,7 @@
convertered to a hex character encoding so that parsing the field is
unmistakable. This can also be used for recording data structures if it were
ever needed. Hex encoding doubles the number of bytes needed to represent the
-value. This is only done when record a non-numeric value that user space can
+value. This is only done when recording a non-numeric value that user space can
control.
Field Names
@@ -93,7 +93,7 @@
Fields names in a record should be consistent so that the parser can make
sense of the value associated with a field. When writing events, always use
a known field name and don't make one up. If nothing fits, take a guess and
-make sure you check with the linux-audit mail list to see if its acceptable.
+make sure you check with the linux-audit mail list to see if it's acceptable.
The value associated with the field needs to have the same formatting as
listed here or translations of the values can have errors. The following
list enumerates known field names:
@@ -203,7 +203,7 @@
oses - numeric, object's session id
ouid - numeric, file owner user id
parent - numeric, the inode number of the parent file
- path - iencoded, file system path name
+ path - encoded, file system path name
per - numeric, linux personality
perm - numeric, the file permission being used
perm_mask - numeric, file permission mask that triggered a watch event
@@ -221,7 +221,7 @@
role - alphanumeric, user's SE linux role
rport - numeric, remote port number
saddr - encoded, struct socket address structure
- sauid - numeric, sending login user id
+ sauid - numeric, sending login user id
scontext - alphanumeric, the subject's context string
selected-context - alphanumeric, new MAC context assigned to session
seuser - alphanumeric, user's SE Linux user acct
@@ -232,7 +232,7 @@
spid - numeric, sending process id
subj - alphanumeric, lspp subject's context string
success - alphanumeric, whether the syscall was successful or not
- suid - numeric, sending user id
+ suid - numeric, sending user id
syscall - numeric, syscall number in effect when the event occurred
table - alphanumeric, netfilter table name
tclass - alphanumeric, target's object classification
@@ -253,7 +253,7 @@
Maintenance
-----------
Over time compliance regulations change as do Common Criteria needs. Generally
-once you write an event, you should never alter it. If you do, its best to
+once you write an event, you should never alter it. If you do, it's best to
send an email to the linux-audit mail list explaining what the change is prior
to implementing the change. This allows people that might have analysis
programs to know of the change or discuss options. Additionally, it may be
@@ -272,29 +272,31 @@
Kernel:
if (audit_enabled) {
- struct audit_buffer *ab;
- uid_t loginuid = from_kuid(&init_user_ns, audit_get_loginuid(current));
- unsigned int sessionid = audit_get_sessionid(current);
-
- ab = audit_log_start(NULL, GFP_KERNEL, AUDIT_KERNEL_OTHER);
- if (!ab)
- return;
- audit_log_format(ab, "auid=%u ses=%u" ,loginuid, sessionid);
- audit_log_task_context(ab);
- audit_log_format(ab, " comm=");
- audit_log_untrustedstring(ab, comm);
- audit_log_end(ab);
+ struct audit_buffer *ab;
+ uid_t loginuid = from_kuid(&init_user_ns, audit_get_loginuid(current));
+ unsigned int sessionid = audit_get_sessionid(current);
+ char comm[sizeof(current->comm)];
+
+ ab = audit_log_start(NULL, GFP_KERNEL, AUDIT_KERNEL_OTHER);
+ if (!ab)
+ return;
+ audit_log_format(ab, "auid=%u ses=%u" ,loginuid, sessionid);
+ audit_log_task_context(ab);
+ audit_log_format(ab, " comm=");
+ get_task_comm(comm, current);
+ audit_log_untrustedstring(ab, comm);
+ audit_log_end(ab);
}
User space:
- char buf[4096], *acct;
- int fd = audit_open();
- acct = audit_encode_nv_string("acct", pamh->user, 0);
- snprintf(buf, sizeof(buf), "op=change-password sauid=%d %s",
- audit_getloginuid(), acct);
- audit_log_user_message(fd, AUDIT_USER_CHAUTHTOK, "buf", NULL, NULL,
- NULL, 0);
- free(acct);
- close(fd);
+ char buf[4096], *acct;
+ int fd = audit_open();
+ acct = audit_encode_nv_string("acct", pamh->user, 0);
+ snprintf(buf, sizeof(buf), "op=change-password sauid=%d %s",
+ audit_getloginuid(), acct);
+ audit_log_user_message(fd, AUDIT_USER_CHAUTHTOK, "buf", NULL, NULL,
+ NULL, 0);
+ free(acct);
+ close(fd);
More information about the Linux-audit
mailing list