Log Filtering Macros

For SunScreen EFS 3.0, log filters can be defined as named quantities. These are referred to as log macros.

Log macros are defined and stored in the registry (on the primary Screen) or they can be defined in a local registry on any Screen. Log macros defined in the registry of the primary Screen have the benefits of automatic propagation to secondary Screens that are enjoyed by all other SunScreen registry objects. This propagation affords uniform log filter availability and ease of common usage across a collection of managed Screens.

Log macros can also be defined in a registry-like facility that is local to each secondary Screen. This local macro capability is provided as a means to deal with emergency situations and other issues of expediency where the process of central macro definition and mass activation is unacceptable in the face of the conditions at hand. As a general practice, it is a good idea to collect such local macros back into the central registry as soon as practical for permanent storage and propagation.

Log macros are named using a global- and Screen-specific two-level scheme similar to other objects in SunScreen EFS 3.0. Evaluation mechanisms prefer a Screen-specific macro with a given name over a global one. Evaluation of macros occurs at the time of usage. (Users familiar with computer programming languages will recognize this as a traditional delayed name binding mechanism with dynamic scoping.)

Log macros also provide a bridge between the namespace of address and service objects defined in the SunScreen registry and their potential usage (as resolved to values) by the filtering facilities of logdump.

logdump filtering retains the hostname-to-address and service name-to-port number mapping mechanisms of snoop, namely, DNS, NIS, host and service tables defined for standard Solaris.

Log macros provide a way to access the name mappings of the registry in translating names to values.

Displaying and Creating Log Macros

Log macros are actually a derivative of the general SunScreen variable mechanism. Therefore, the variable naming and value structures exist for log macros, namely:

sys=Screen				(optional)
name=macroname
value="macrobody"
description="descriptive text"	(optional)
enabled | disabled			(default is enabled)

Log macros are configured in the registry using the logmacro edit sub-command of ssadm. For group-Screen installations, they are configured on the primary Screen.

The following is an example of what you type to display the definition of a non-Screen specific macro, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro print name=mail-only
NAME="mail-only" ENABLED VALUE="svc
smtp" 

DESCRIPTION="SMTP mail" ...

The following is an example of what you type to define a non-Screen specific macro, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro add name=pkts-only value="loglvl pkt" Description="only network packets"
edit> quit

The following is an example of what you type to define a macro for a specific Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro add sys=Screenname name=SFO-routing value="port rip src SFO-routers" description="routing activity in SFO district"
edit> quit

Although, the output produced by print surrounds the value of each item in double quotes, these are only necessary on input to protect embedded spaces within the values of items. Also, although print outputs all tag names in capital letters (for example, NAME=), these tags are recognized in a case-insensitive manner on input (for example, name=, Name=, NAME= are equivalent.)

The following is an example of the message you see if you attempt to save without changing entities other than these types:

edit> savelock not held
failed (status 244)

This is a non-fatal message and you can simply quit the configuration editor.

Log macros are available for immediate use on the Screen whereupon they have been defined. It is not necessary to do an activate each time a log macro is changed to use it. However, to propagate log macro definitions from a primary Screen to secondaries, activation is necessary.

As previously indicated, it is also possible to create expediency log macros on any Screen. This is done using logmacro as a sub-command of ssadm (rather than a ssadm edit sub-command). The syntax of the rest of the usage is the same as given above.

The following is an example of what you type to display the definition of a non-Screen-specific macro, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro print name=mail-only
NAME="mail-only" ENABLED VALUE="svc
smtp" 

DESCRIPTION="SMTP mail" ...

The following is an example of what you type to define a macro for a specific Screen, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro add sys=slave name=SFO-routing value="port rip src SFO-routers" description="routing activity in SFO district"

It is bad practice to define Screen-non-specific log macros on secondary Screens. In future SunScreen firewall releases, the ability to do so will be removed.

Log Macro Name and Body

The name of a log macro, as has been previously shown, consists of a name=macroname part, preceded by an optional sys=Screenname Screen-restriction part.

Unlike many objects in SunScreen, the macroname portion must be formulated as a simple identifier, rather than a more complicated general string. (A simple identifier begins with an ASCII alphabetic character or an underscore, followed by zero or ASCII alphanumeric characters or underscores.)

The macrobody (value part) of a log macro consists of a filtering expression suitable for logdump. It its simplest form, this is simply a string that can be used directly as filtering arguments.

However, the log macro expansion feature parses the value string looking for logdump operators that introduce address and service names and, finding same, attempts to resolve them from the SunScreen registry. So, for addresses, it looks for the operators host, to, from, between, dst, src and tries to resolve their operands in the address registry; if found therein, the operator-operand sequence is rewritten with the registry value for that address.

Similarly, for services, it looks for the operators port, dstport, and srcport and, if their operand resolves in the service registry, the operator-operand sequence is rewritten with the registry value.

In SunScreen EFS 3.0, the registry services expanded in this manner can only consist of TCP or UDP services; ranges of ports are allowed, but groups are disallowed as are services that use non-TCP non-UDP state engines.

Additionally, expansion looks for the operator macro and, if found, looks up the operand and replaces the operator-operand sequence with the named macros body.

From the discussion of the processing done on the macrobody string during evaluation, it should be evident why macro names must be simple identifiers. Similarly, expansion cannot handle addresses nor services from the registry that are not named with simple identifiers as well.

Listing Log Macros

Log macros in the primary registry can be displayed using the logmacro sub-command of ssadm edit. Individual macro definitions can be displayed. Also, all Screen-non-specific definitions, or all definitions specific to a Screen, or all definitions specific to any Screen, can be displayed. An abbreviated listing containing just the names of these last three classes of macros can also be generated.

The following is an example of what you type to display a specific macro definition, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro print name=mail-only
NAME="mail-only" ENABLED VALUE="svc
smtp" DESCRIPTION="SMTP mail"...
edit> logmacro print sys=secondary name=SFO-routing
SYS="secondary" NAME="SFO-routing"
VALUE="port rip src SFO-routers" DESCRIPTION="routing activity in
SFO district" ...

The following is an example of what you type to display all Screen-non-specific definitions, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro print
NAME="mail-only" ENABLED VALUE="svc
smtp" DESCRIPTION="SMTP mail" ...
NAME="pkts-only" ENABLED VALUE="loglvl
pkt" DESCRIPTION="only network packets" ...

The following is an example of what you type to display all definitions specific to a Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro print sys=slave
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to display all definitions specific to any Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro print sys=
SYS="master" NAME="HQ-routing" VALUE="port
rip src HQ-routers" DESCRIPTION="routing activity in HQ district"
...
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to produce name lists, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro names sys=
SYS="master" NAME="HQ-routing" VALUE="port
rip src HQ-routers" DESCRIPTION="routing activity in HQ district"
...
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to display all Screen-non-specific names, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro names
NAME="mail-only"
NAME="pkts-only"

The following is an example of what you type to display all names specific to a Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro names sys=slave
SYS="slave" NAME="SFO-routing"

The following is an example of what you type to display all names specific to any Screen, while logged in to the primary Screen:

admin% ssadm -r primary edit Initialedit> logmacro names sys=
SYS="master" NAME="HQ-routing"
SYS="slave" NAME="SFO-routing"

The following is an example of what you type to display a specific macro definition, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro print name=mail-only
NAME="mail-only" ENABLED VALUE="svc
smtp" DESCRIPTION="SMTP mail" ...
admin% ssadm -r secondary logmacro print sys=slave name=SFO-routing
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to display all Screen-non-specific definitions, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro print
NAME="mail-only" ENABLED VALUE="svc
smtp" DESCRIPTION="SMTP mail" ...
NAME="pkts-only" ENABLED VALUE="loglvl
pkt" DESCRIPTION="only network packets" ...

The following is an example of what you type to display all definitions specific to a Screen, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro print sys=secondary
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to produce name lists, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro names sys=secondary
SYS="slave" NAME="SFO-routing" VALUE="port
rip src SFO-routers" DESCRIPTION="routing activity in SFO district"
...

The following is an example of what you type to display all Screen-non-specific names, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro names
NAME="mail-only"
NAME="pkts-only"

The following is an example of what you type to display all names specific to a Screen, while logged in to the primary Screen:

admin% ssadm -r secondary logmacro names sys=secondary
SYS="slave" NAME="SFO-routing"

Log Macro Usage

A log macro is utilized by expanding its value and by causing that expansion to be presented as a filter expression to a log get* or logdump command.

The following is an example of what you type to perform log macro expansion using logmacro as a sub-command to ssadm, consider the following, while logged in to Screen:

admin% ssadm -r Screen logmacro print
NAME="probed-ports" ENABLED VALUE="icmp
or dstport telnet or dstport rlogin or dstport rsh or dstport ftp
or srcport X11 or port adminweb"
admin% ssadm -r Screen logmacro print sys=
SYS="Screen" NAME="suspicious" ENABLED
VALUE="logwhy 256 logiface le0 ( not from trusted or to hidden )
macro probed-ports"

The above shows two macros defined. The first, probed-ports is Screen-non-specific and ostensibly defines services that are thought to be targets for initial probes leading to security attacks. The second, suspicious, is specific to Screen and contains a more complete macro for filtering potential probes; it restricts itself to packets logged because there was no rule found or they had source addresses that were illegal on their interface ("logwhy 256"), further to packets arriving on a specific (presumably outside) interface ("logiface le0"), yet further to packets originating from non-trusted hosts or targeted at hosts that are non-published ("not from trusted or to hidden"), and yet further to restrictions imposed by the macro "probed-ports".

As a brief aside, the verb names,flat produces a list of names that are available for macro expansion on a particular Screen.

For example, while logged in to Screen, type:

admin% ssadm -r Screen logmacro names,flat
"probed-ports"
"suspicious"

Screen-specific issues of macros have been hidden, listing macro names as they are used by embedded macro references.

Assuming the following definitions have been created and activated for registry items:

edit> list Address
"abraham" HOST 1.2.3.4
"hidden" RANGE 129.9.9.0 129.9.9.255
"john" HOST 2.3.4.5
"martin" HOST 3.4.5.6
"trusted" GROUP { "abraham" "martin"
"john" } { }
edit> list Service
"rlogin" SIMPLE FORWARD "tcp" PORT
513
"rsh" SIMPLE FORWARD "tcp" PORT 514
"telnet" SIMPLE FORWARD "tcp" PORT
23
"X11" SIMPLE FORWARD "tcp" PORT 6000-6063

The following is an example of what you type to expand the given macro, while logged in to Screen:

admin% ssadm -r Screen logmacro expand suspicious
logwhy 256 logiface le0 ( not ( from
1.2.3.4 or from 2.3.4.5 or from 3.4.5.6 ) or to 129.9.9.0..129.9.9.255
) ( icmp or dstport 23 or dstport 513 or dstport 514 or ( srcport
20 or dstport 21 ) or srcport 6000..6063 or port adminweb )

This usage illustrates various expansion and resolution operations performed by expand. The clause "from trusted" has been replaced by the registry values for the GROUP "trusted". The clause "to hidden" has also been resolved to a registry RANGE, using the logdump syntax for IP address ranges "a.b.c.d..e.f.g.h."

The embedded macro reference "macro probed-ports" has been expanded. The clauses that can be resolved from the registry ("dstport telnet", "dstport rlogin", "dstport rsh", "dstport ftp", and "srcport X11"), have been expanded using registry values whereas clauses that were not found in the registry ("icmp" and "port adminweb") were left to be resolved by logdump itself. The "dstport ftp" clause further illustrates some special processing employed for that protocol, and the expansion of the "srcport X11" clause shows the logdump syntax for port ranges "x..y".

Resolution of SunScreen registry items performed by expand is made using those of the currently activated policy and for the Screen whereon the expand operation is executed.

The logmacro expand mechanism has been designed facilitate simple command-line usage in conjunction with the other log processing facilities of SunScreen.

The following is an example of what you type to employ the above macro to retrieve the suspicious items in the current log on the Screen and display them, while logged in to Screen:

admin% ssadm -r Screen log get `ssadm -r Screen logmacro expand suspicious` | ssadm logdump -V