FreeBSD 7.0 manual page repository

FreeBSD is a free computer operating system based on BSD UNIX originally. Many IT companies, like DeployIS is using it to provide an up-to-date, stable operating system.

audit - Basic Security Module (BSM) file format

 

NAME

      audit - Basic Security Module (BSM) file format
 

DESCRIPTION

      The audit file format is based on Sun’s Basic Security Module (BSM) file
      format, a token-based record stream to represent system audit data.  This
      file format is both flexible and extensible, able to describe a broad
      range of data types, and easily extended to describe new data types in a
      moderately backward and forward compatible way.
 
      BSM token streams typically begin and end with a “file” token, which pro‐
      vides time stamp and file name information for the stream; when process‐
      ing a BSM token stream from a stream as opposed to a single file source,
      file tokens may be seen at any point between ordinary records identifying
      when particular parts of the stream begin and end.  All other tokens will
      appear in the context of a complete BSM audit record, which begins with a
      “header” token, and ends with a “trailer” token, which describe the audit
      record.  Between these two tokens will appear a variety of data tokens,
      such as process information, file path names, IPC object information, MAC
      labels, socket information, and so on.
 
      The BSM file format defines specific token orders for each record event
      type; however, some variation may occur depending on the operating system
      in use, what system options, such as mandatory access control, are
      present.
 
      This manual page documents the common token types and their binary for‐
      mat, and is intended for reference purposes only.  It is recommended that
      application programmers use the libbsm(3) interface to read and write
      tokens, rather than parsing or constructing records by hand.
 
    File Token
      The “file” token is used at the beginning and end of an audit log file to
      indicate when the audit log begins and ends.  It includes a pathname so
      that, if concatenated together, original file boundaries are still
      observable, and gaps in the audit log can be identified.  A “file” token
      can be created using au_to_file(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Seconds                         4 bytes            File time stamp
         Microseconds                    4 bytes            File time stamp
         File name lengh                 2 bytes            File name of audit
                                                            trail
         File pathname                   N bytes + 1 NUL    File name of audit
                                                            trail
 
    Header Token
      The “header” token is used to mark the beginning of a complete audit
      record, and includes the length of the total record in bytes, a version
      number for the record layout, the event type and subtype, and the time at
      which the event occurred.  A 32-bit “header” token can be created using
      au_to_header32(3); a 64-bit “header” token can be created using
      au_to_header64(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Record Byte Count               4 bytes            Number of bytes in
                                                            record
         Version Number                  2 bytes            Record version
                                                            number
         Event Type                      2 bytes            Event type
         Event Modifier                  2 bytes            Event sub-type
         Seconds                         4/8 bytes          Record time stamp
                                                            (32/64-bits)
         Nanoseconds                     4/8 bytes          Record time stamp
                                                            (32/64-bits)
 
    Expanded Header Token
      The “expanded header” token is an expanded version of the “header” token,
      with the addition of a machine IPv4 or IPv6 address.  A 32-bit extended
      “header” token can be created using au_to_header32_ex(3); a 64-bit
      extended “header” token can be created using au_to_header64_ex(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Record Byte Count               4 bytes            Number of bytes in
                                                            record
         Version Number                  2 bytes            Record version
                                                            number
         Event Type                      2 bytes            Event type
         Event Modifier                  2 bytes            Event sub-type
         Address Type/Length             1 byte             Host address type
                                                            and length
         Machine Address                 4/16 bytes         IPv4 or IPv6
                                                            address
         Seconds                         4/8 bytes          Record time stamp
                                                            (32/64-bits)
         Nanoseconds                     4/8 bytes          Record time stamp
                                                            (32/64-bits)
 
    Trailer Token
      The “trailer” terminates a BSM audit record, and contains a magic number,
      TRAILER_PAD_MAGIC and length that can be used to validate that the record
      was read properly.  A “trailer” token can be created using
      au_to_trailer(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Trailer Magic                   2 bytes            Trailer magic
                                                            number
         Record Byte Count               4 bytes            Number of bytes in
                                                            record
 
    Arbitrary Data Token
      The “arbitrary data” token contains a byte stream of opaque (untyped)
      data.  The size of the data is calculated as the size of each unit of
      data multipled by the number of units of data.  A “How to print” field is
      present to specify how to print the data, but interpretation of that
      field is not currently defined.  An “arbitrary data” token can be created
      using au_to_data(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         How to Print                    1 byte             User-defined
                                                            printing
                                                            information
         Basic Unit                      1 byte             Size of a unit in
                                                            bytes
         Unit Count                      1 byte             Number of units of
                                                            data present
         Data Items                      Variable           User data
 
    in_addr Token
      The “in_addr” token holds a network byte order IPv4 or IPv6 address.  An
      “in_addr” token can be created using au_to_in_addr(3) for an IPv4
      address, or au_to_in_addr_ex(3) for an IPv6 address.
 
      See the BUGS section for information on the storage of this token.
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         IP Address Type                 1 byte             Type of address
         IP Address                      4/16 bytes         IPv4 or IPv6
                                                            address
 
    Expanded in_addr Token
      The “expanded in_addr” token ...
 
      See the BUGS section for information on the storage of this token.
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         XXXX
 
    ip Token
      The “ip” token contains an IP packet header in network byte order.  An
      “ip” token can be created using au_to_ip(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Version and IHL                 1 byte             Version and IP
                                                            header length
         Type of Service                 1 byte             IP TOS field
         Length                          2 bytes            IP packet length in
                                                            network byte order
         ID                              2 bytes            IP header ID for
                                                            reassembly
         Offset                          2 bytes            IP fragment offset
                                                            and flags, network
                                                            byte order
         TTL                             1 byte             IP Time-to-Live
         Protocol                        1 byte             IP protocol number
         Checksum                        2 bytes            IP header checksum,
                                                            network byte order
         Source Address                  4 bytes            IPv4 source address
         Destination Address             4 bytes            IPv4 destination
                                                            address
 
    Expanded ip Token
      The “expanded ip” token ...
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         XXXX
 
    iport Token
      The “iport” token stores an IP port number in network byte order.  An
      “iport” token can be created using au_to_iport(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Port Number                     2 bytes            Port number in
                                                            network byte order
 
    Path Token
      The “path” token contains a pathname.  A “path” token can be created
      using au_to_path(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Path Length                     2 bytes            Length of path in
                                                            bytes
         Path                            N bytes + 1 NUL    Path name
 
    path_attr Token
      The “path_attr” token contains a set of NUL-terminated path names.  The
      libbsm(3) API cannot currently create a “path_attr” token.
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Count                           2 bytes            Number of NUL-
                                                            terminated
                                                            string(s) in token
         Path                            Variable           count NUL-
                                                            terminated
                                                            string(s)
 
    Process Token
      The “process” token contains a description of the security properties of
      a process involved as the target of an auditable event, such as the des‐
      tination for signal delivery.  It should not be confused with the
      “subject” token, which describes the subject performing an auditable
      event.  This includes both the traditional UNIX security properties, such
      as user IDs and group IDs, but also audit information such as the audit
      user ID and session.  A “process” token can be created using
      au_to_process32(3) or au_to_process64(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Audit ID                        4 bytes            Audit user ID
         Effective User ID               4 bytes            Effective user ID
         Effective Group ID              4 bytes            Effective group ID
         Real User ID                    4 bytes            Real user ID
         Real Group ID                   4 bytes            Real group ID
         Process ID                      4 bytes            Process ID
         Session ID                      4 bytes            Audit session ID
         Terminal Port ID                4/8 bytes          Terminal port ID
                                                            (32/64-bits)
         Terminal Machine Address        4 bytes            IP address of
                                                            machine
 
    Expanded Process Token
      The “expanded process” token contains the contents of the “process”
      token, with the addition of a machine address type and variable length
      address storage capable of containing IPv6 addresses.  An “expanded
      process” token can be created using au_to_process32_ex(3) or
      au_to_process64_ex(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Audit ID                        4 bytes            Audit user ID
         Effective User ID               4 bytes            Effective user ID
         Effective Group ID              4 bytes            Effective group ID
         Real User ID                    4 bytes            Real user ID
         Real Group ID                   4 bytes            Real group ID
         Process ID                      4 bytes            Process ID
         Session ID                      4 bytes            Audit session ID
         Terminal Port ID                4/8 bytes          Terminal port ID
                                                            (32/64-bits)
         Terminal Address Type/Length    1 byte             Length of machine
                                                            address
         Terminal Machine Address        4 bytes            IPv4 or IPv6
                                                            address of machine
 
    Return Token
      The “return” token contains a system call or library function return con‐
      dition, including return value and error number associated with the
      global variable errno.  A “return” token can be created using
      au_to_return32(3) or au_to_return64(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Error Number                    1 byte             Errno value, or 0
                                                            if undefined
         Return Value                    4/8 bytes          Return value
                                                            (32/64-bits)
 
    Subject Token
      The “subject” token contains information on the subject performing the
      operation described by an audit record, and includes similar information
      to that found in the “process” and “expanded process” tokens.  However,
      those tokens are used where the process being described is the target of
      the operation, not the authorizing party.  A “subject” token can be cre‐
      ated using au_to_subject32(3) and au_to_subject64(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Audit ID                        4 bytes            Audit user ID
         Effective User ID               4 bytes            Effective user ID
         Effective Group ID              4 bytes            Effective group ID
         Real User ID                    4 bytes            Real user ID
         Real Group ID                   4 bytes            Real group ID
         Process ID                      4 bytes            Process ID
         Session ID                      4 bytes            Audit session ID
         Terminal Port ID                4/8 bytes          Terminal port ID
                                                            (32/64-bits)
         Terminal Machine Address        4 bytes            IP address of
                                                            machine
 
    Expanded Subject Token
      The “expanded subject” token consists of the same elements as the
      “subject” token, with the addition of type/length and variable size
      machine address information in the terminal ID.  An “expanded subject”
      token can be created using au_to_subject32_ex(3) or
      au_to_subject64_ex(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Audit ID                        4 bytes            Audit user ID
         Effective User ID               4 bytes            Effective user ID
         Effective Group ID              4 bytes            Effective group ID
         Real User ID                    4 bytes            Real user ID
         Real Group ID                   4 bytes            Real group ID
         Process ID                      4 bytes            Process ID
         Session ID                      4 bytes            Audit session ID
         Terminal Port ID                4/8 bytes          Terminal port ID
                                                            (32/64-bits)
         Terminal Address Type/Length    1 byte             Length of machine
                                                            address
         Terminal Machine Address        4 bytes            IPv4 or IPv6
                                                            address of machine
 
    System V IPC Token
      The “System V IPC” token contains the System V IPC message handle,
      semaphore handle or shared memory handle.  A System V IPC token may be
      created using +.Xr au_to_ipc 3 .
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Object ID type                  1 byte             Object ID
         Object ID                       4 bytes            Object ID
 
    Text Token
      The “text” token contains a single NUL-terminated text string.  A “text”
      token may be created using au_to_text(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Text Length                     2 bytes            Length of text
                                                            string including
                                                            NUL
         Text                            N bytes + 1 NUL    Text string
                                                            including NUL
 
    Attribute Token
      The “attribute” token describes the attributes of a file associated with
      the audit event.  As files may be identified by 0, 1, or many path names,
      a path name is not included with the attribute block for a file; optional
      “path” tokens may also be present in an audit record indicating which
      path, if any, was used to reach the object.  An “attribute” token can be
      created using au_to_attr32(3) or au_to_attr64(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         File Access Mode                1 byte             mode_t associated
                                                            with file
         Owner User ID                   4 bytes            uid_t associated
                                                            with file
         Owner Group ID                  4 bytes            gid_t associated
                                                            with file
         File System ID                  4 bytes            fsid_t associated
                                                            with file
         File System Node ID             8 bytes            ino_t associated
                                                            with file
         Device                          4/8 bytes          Device major/minor
                                                            number (32/64-bit)
 
    Groups Token
      The “groups” token contains a list of group IDs associated with the audit
      event.  A “groups” token can be created using au_to_groups(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Number of Groups                2 bytes            Number of groups in
                                                            token
         Group List                      N * 4 bytes        List of N group IDs
 
    System V IPC Permission Token
      The “System V IPC permission” token contains a System V IPC access per‐
      missions.  A System V IPC permission token may be created using
      au_to_ipc_perm(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Owner user ID                   4 bytes            User ID of IPC
                                                            owner
         Owner group ID                  4 bytes            Group ID of IPC
                                                            owner
         Creator user ID                 4 bytes            User ID of IPC
                                                            creator
         Creator group ID                4 bytes            Group ID of IPC
                                                            creator
         Access mode                     4 bytes            Access mode
         Sequnce number                  4 bytes            Sequnce number
         Key                             4 bytes            IPC key
 
    Arg Token
      The “arg” token contains informations about arguments of the system call.
      Depending on the size of the desired argument value, an Arg token may be
      created using au_to_arg32(3) or au_to_arg64(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Argument ID                     1 byte             Argument ID
         Argument value                  4/8 bytes          Argument value
         Length                          2 bytes            Length of the text
         Text                            N bytes + 1 nul    The string
                                                            including nul
 
    exec_args Token
      The “exec_args” token contains informations about arguements of the
      exec() system call.  An exec_args token may be created using
      au_to_exec_args(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Count                           4 bytes            Number of arguments
         Text                            * bytes            Count null-
                                                            terminated strings
 
    exec_env Token
      The “exec_env” token contains current eviroment variables to an exec()
      system call.  An exec_args token may be created using au_to_exec_env(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Count ID                        4 bytes            Number of variables
         Text                            * bytes            Count nul-
                                                            terminated strings
 
    Exit Token
      The “exit” token contains process exit/return code information.  An
      “exit” token can be created using au_to_exit(3).
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Status                          4 bytes            Process status on
                                                            exit
         Return Value                    4 bytes            Process return
                                                            value on exit
 
    Socket Token
      The “socket” token contains informations about UNIX domain and Internet
      sockets.  Each token has four or eight fields.  Depend on type of socket
      a socket token may be created using au_to_sock_unix(3),
      au_to_sock_inet32(3) or au_to_sock_inet128(3).
 
         Field                  Bytes            Description
         Token ID               1 byte           Token ID
         Socket family          2 bytes          Socket family
         Local port             2 bytes          Local port
         Socket address         4 bytes          Socket address
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID +.It Li
                                                            "Socket domain" Ta
                                                            "4 bytes" Ta
                                                            "Socket domain"
                                                            +.It Li "Socket
                                                            family" Ta "2
                                                            bytes" Ta "Socket
                                                            family" +.It Li
                                                            "Address type" Ta
                                                            "1 byte" Ta
                                                            "Address type
                                                            (IPv4/IPv6)" +.It
                                                            Li "Local port" Ta
                                                            "2 bytes" Ta "Local
                                                            port" +.It Li
                                                            "Local IP address"
                                                            Ta "4/16 bytes" Ta
                                                            "Local IP address"
                                                            +.It Li "Remote
                                                            port" Ta "2 bytes"
                                                            Ta "Remote port"
                                                            +.It Li "Remote IP
                                                            address" Ta "4/16
                                                            bytes" Ta "Remote
                                                            IP address"
 
    Expanded Socket Token
      The “expanded socket” token ...
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         XXXXX
 
    Seq Token
      The “seq” token contains a unique and monotonically increasing audit
      event sequence ID.  Due to the limited range of 32 bits, serial number
      arithmetic and caution should be used when comparing sequence numbers.
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         Sequence Number                 4 bytes            Audit event
                                                            sequence number
 
    privilege Token
      The “privilege” token ...
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         XXXXX
 
    Use-of-auth Token
      The “use-of-auth” token ...
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         XXXXX
 
    Command Token
      The “command” token ...
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         XXXXX
 
    ACL Token
      The “ACL” token ...
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         XXXXX
 
    Zonename Token
      The “zonename” token ...
 
         Field                           Bytes              Description
         Token ID                        1 byte             Token ID
         XXXXX
      auditreduce(1), praudit(1), libbsm(3), audit(4), auditpipe(4), audit(8)
 

HISTORY

      The OpenBSM implementation was created by McAfee Research, the security
      division of McAfee Inc., under contract to Apple Computer Inc. in 2004.
      It was subsequently adopted by the TrustedBSD Project as the foundation
      for the OpenBSM distribution.
 

AUTHORS

      The Basic Security Module (BSM) interface to audit records and audit
      event stream format were defined by Sun Microsystems.
 
      This manual page was written by Robert Watson 〈rwatson@FreeBSD.org〉.
 

BUGS

      The “How to print” field in the “arbitrary data” token has undefined val‐
      ues.
 
      The “in_addr” and “in_addr_ex” token layout documented here appears to be
      in conflict with the libbsm(3) implementations of au_to_in_addr(3) and
      au_to_in_addr_ex(3).
 

Sections

Based on BSD UNIX
FreeBSD is an advanced operating system for x86 compatible (including Pentium and Athlon), amd64 compatible (including Opteron, Athlon64, and EM64T), UltraSPARC, IA-64, PC-98 and ARM architectures. It is derived from BSD, the version of UNIX developed at the University of California, Berkeley. It is developed and maintained by a large team of individuals. Additional platforms are in various stages of development.