Log Filtering Macros
For SunScreen, 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 are automatically propagated to secondary Screens in the same way as 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 for emergency situations and other cases where central macro definition and mass activation is unacceptable. 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. Evaluation mechanisms prefer a Screen-specific macro with a given name over a global one. Evaluation of macros occurs at the time of usage.
Note -
If you are familiar with computer programming languages you 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.
Note -
logdump filtering retains the host name-to-address and service name-to-port number mapping mechanisms of snoop--namely, DNS, NIS, host, and service tables defined for Solaris software.
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=Screenname (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 subcommand of ssadm. For group-Screen installations, they are configured on the primary Screen.
Note -
You do not have to save a log macro to use it; it is saved when it is created. However, to propagate log macro definitions from a primary Screen to secondaries, you must activate the configuration.
Examples: Log Macros on the Primary Screen
The following are examples of using log macros while logged into the primary Screen.
To display the definition of a non-Screen specific macro:
admin% ssadm -r primary edit Initial edit> logmacro print name=mail-only NAME="mail-only" ENABLED VALUE="svc smtp" DESCRIPTION="SMTP mail" ... |
To define a non-Screen specific macro:
admin% ssadm -r primary edit Initial edit> logmacro add name=pkts-only value="loglvl pkt" Description="only network packets" edit> quit |
To define a macro for a specific Screen:
admin% ssadm -r primary edit Initial edit> logmacro add sys=Screenname name=SFO value="port SFO" description="routing SFO" edit> quit |
Note -
Although, the output produced by print surrounds the value of each item in double quotes, these are only necessary on input if there are 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.)
You can create expediency log macros on any Screen using logmacro as a subcommand of ssadm (rather than an ssadm edit subcommand). The syntax of the rest of the usage is the same as given above.
Examples: Log Macros on the Secondary Screen
The following are examples of using log macros while logged into the secondary Screen.
To display the definition of a non-Screen-specific macro:
admin% ssadm -r secondary logmacro print name=mail-only NAME="mail-only" ENABLED VALUE="svc smtp" DESCRIPTION="SMTP mail" ... |
To define a macro for a specific Screen:
admin% ssadm -r secondary logmacro add sys=secondary name=SFO-routing value="port rip src SFO-routers" description="routing activity in SFO district" |
Caution - Do not define log macros on secondary Screens which are not Screen-specific.
Log Macro Name and Body
The name of a log macro 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 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 they are found, 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. If their operand resolves in the service registry, the operator-operand sequence is rewritten with the registry value.
Note -
In SunScreen, 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 macro's body. Expansion cannot handle addresses or 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 subcommand of ssadm edit. Individual macro definitions can be displayed. Also, all Screen-nonspecific definitions, or all definitions specific to a Screen, or all definitions specific to any Screen, can be displayed. You can generate an abbreviated listing that contains just the names of these last three classes of macros.
Examples: Macro Definitions for the Primary Screen
The following are examples of displaying definitions while logged into the primary Screen.
To display two specific macro definitions:
admin% ssadm -r primary edit Initial edit> logmacro print name=mail-only NAME="mail-only" ENABLED VALUE="svc smtp" DESCRIPTION="SMTP mail"... edit> logmacro print sys=secondary name=SFO SYS="secondary" NAME="SFO" VALUE="port SFO" DESCRIPTION="routing SFO" ... |
To display all Screen-nonspecific definitions:
admin% ssadm -r primary edit Initial edit> logmacro print NAME="mail-only" ENABLED VALUE="svc smtp" DESCRIPTION="SMTP mail" ... NAME="pkts-only" ENABLED VALUE="loglvl pkt" DESCRIPTION="only network packets" ... |
To display all definitions specific to a Screen:
admin% ssadm -r primary edit Initial edit> logmacro print sys=secondary SYS="secondary" NAME="SFO" VALUE="port SFO" DESCRIPTION="routing SFO" ... |
To display all definitions specific to any Screen:
admin% ssadm -r primary edit Initial edit> logmacro print sys= SYS="primary" NAME="HQ-routing" VALUE="port HQ-routers" DESCRIPTION="HQ routing" ... SYS="secondary" NAME="SFO-routing" VALUE="port SFO" DESCRIPTION="routing SFO" ... |
To display all Screen-nonspecific names:
admin% ssadm -r primary edit Initial edit> logmacro names NAME="mail-only" NAME="pkts-only" |
To display all names specific to a Screen:
admin% ssadm -r primary edit Initial edit> logmacro names sys=secondary SYS="secondary" NAME="SFO-routing" |
To display all names specific to any Screen:
admin% ssadm -r primary edit Initial edit> logmacro names sys= SYS="primary" NAME="HQ-routing" SYS="secondary" NAME="SFO-routing" |
Examples: Macro Definitions for the Secondary Screen
The following are examples of displaying definitions while logged into the secondary Screen.
To display two specific macro definitions:
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=secondary name=SFO-routing SYS="secondary" NAME="SFO-routing" VALUE="port SFO" DESCRIPTION="routing SFO" ... |
To display all Screen-nonspecific definitions:
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" ... |
To display all definitions specific to a Screen:
admin% ssadm -r secondary logmacro print sys=secondary SYS="secondary" NAME="SFO-routing" VALUE="port SFO" DESCRIPTION="routing SFO" ... |
The following is an example of what you would type to produce name lists:
admin% ssadm -r secondary logmacro names sys=secondary SYS="secpndary" NAME="SFO-routing" |
To display all Screen-nonspecific names:
admin% ssadm -r secondary logmacro names NAME="mail-only" NAME="pkts-only" |
To display all names specific to a Screen:
admin% ssadm -r secondary logmacro names sys=secondary SYS="secondary" NAME="SFO-routing" |
Log Macro Usage
To use a log macro, you expand its value and cause that expansion to be presented as a filter expression to a log get* or logdump command.
To introduce examples of log macro expansion using logmacro as a subcommand to ssadm, the first example shows the defined values to two macros as rendered by ssadm logmacro print:
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" |
Two macros are defined. The first macro, probed-ports, is Screen-nonspecific and ostensibly defines services that are thought to be targets for initial probes leading to security attacks. The second macro, suspicious, is specific to a Screen and contains a more complete macro for filtering potential probes. It restricts itself to:
-
Packets logged because no rule was found or that had source addresses that were illegal on their interface (logwhy 256)
-
Packets arriving on a specific (presumably outside) interface (logiface le0)
-
Packets originating from untrusted hosts or targeted at hosts that are unpublished (not from trusted or to hidden)
-
Restrictions imposed by the macro "probed-ports"
Tip -The verb names,flat produces a list of names that are available for macro expansion on a particular Screen. For example, while logged into a Screen, type:
admin% ssadm -r Screen logmacro names,flat "probed-ports" "suspicious"
This hides Screen-specific issues of macros and lists macro names as they are used by embedded macro references.
Assume that 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
|
To expand a given macro, while logged into a 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. 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.
Note -
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 to facilitate simple command-line usage in conjunction with the other log processing facilities of SunScreen.
To employ the above macro to retrieve the suspicious items in the current log on the Screen and display them, while logged into the Screen:
admin% ssadm -r Screen log get `ssadm -r Screen logmacro expand suspicious` | ssadm logdump -v -i- |
- © 2010, Oracle Corporation and/or its affiliates