CS IP filtering: defining rules with Policy Agent and avoiding the elephant traps

To see all my blog posts on IP filtering see here.

Topics in this post.

• It is easy to make your TCPIP instance totally inaccessible
• No syntax checking before activating
• Getting the layout correct
• Using Direction bidirectional drove me crazy
• Filter action DiscardAction didn’t work at first
• Why do I need to specify direction?
• Which rule is used?

It is easy to make your TCPIP instance totally inaccessible.

There are various criteria, such as source IP address, and destination IP Address and port which can be used in the IP filtering rules. The rules are scanned to see if the rule is applicable for the criteria.

• If the criteria matches, and the action is deny the final result is denied, and the other rules are skipped.
• If no rule matches then the system generated DenyAllRule_Generated rule is used.

This means if you get your definitions slightly wrong – you may deny all traffic – and so be unable to logon to TSO to fix the definition. You would have to logon to TSO without using TCPIP.

If you only have access to TSO through TCPIP, you need to restart TCPIP with a parameter file with an IPCONFIG file which does not specify IPSECURITY; or use a TCPIP V6 address. Make sure you have a fall back plan as this will cause you an outage.

No syntax checking before activating

I have not found a way of getting the syntax checked except at deploy time. You make your change to the Policy Agent configuration, and issue the refresh command. If there are any errors you get a message

EZZ8438I PAGENT POLICY DEFINITIONS CONTAIN ERRORS FOR TCPIP : IPSEC

and you need to look in the syslogd output for the policy agent (for me in /var/log). Search for OBJERR and WARNING. You can get messages like

WARNING: No ‘IpFilterPolicy’ policy object found in config

Which means you had an error in your configuration, and it was all ignored.

You can display what is current using a command like

ipsec -f display -c current -p TCPIP > a

or

pasearch -a -e -v f -f Colin443 > a

which displays the policy information for ip filtering (-v f) and policy Colin443 (-f Colin443).

I found the output is not very clear. The pasearch command does give information like

Policy created: Wed Dec 6 10:16:06 2023
Policy updated: Wed Dec 6 10:32:50 2023

so you can see when it was last updated in TCPIP (and if your update was made successfully).

Getting the layout correct

It took me a good half day to find a layout error

IpGenericFilterAction denyit 
{ 
  IpFilterAction deny DiscardAction    ICMP 
  IpFilterLogging yes 
}
  

This ignores the DiscardAction ICMP, because you must have only one attribute and its values on each line. The remainder of the line (DiscardAction ICMP) is ignored.

The correct way of doing it is

IpGenericFilterAction denyit 
{ 
  IpFilterAction deny 
  DiscardAction    ICMP 
  IpFilterLogging yes 
} 

How do I specify an IP address.?

You can specify an individual address, or a group of addresses, in a variety of slightly different ways. You have to specify the dotted IP address, you cannot specify names.

“inline”

You can specify

IpSourceAddr 10.1.0.2
IpSourceAddr 10.1.0.0/24 
IpSourceAddr 10.1.0.0-10.1.0.8 

The first line defines an explicit address.
The second line defines a range of addresses, a subnet, in standard TCP/IP format.
The third defines a range.

Reference “common” definitions.

You can specify IpSourceAddrRef, IpSourceAddrSetRef, IpSourceAddrGroupRef, to definitions defined elsewhere and refer to them. This allows you to share IP address definitions within rules.

• IpSourceAddrRef is the name of an IpAddr statement.
• IpSourceAddrSetRef is the name of a IpAddrSet which has either Prefix 10.1.0.0/24 or a Range 10.1.0.0-10.1.0.8
• IpSourceAddrGroupRef is the name of an IpAddrGroup which has one or more IpAddr, IpAddrRef, IpAddrSet, or IpAddrSetRef statements.

Using Direction bidirectional drove me crazy.

To allow a connection from outside z/OS to an application running on z/OS (and getting a response back) you need definitions like:

IpSourceAddr LAPTOPIP IpDestAddr zOSIP … Direction inbound
IpSourceAddr zOSIP  IpDestAddr LAPTOPIP  … Direction outbound

To stay sane, do not use Directional bidirectional; you should explicitly specify the inbound and outbound connection.

The equivalent bidirectional definition looks like

IpSourceAddr zOSIP  IpDestAddr LAPTOP … Direction bidirectional

which generates the outbound statement then swaps the IP Address round, and generates an inbound. This makes my head spin… as the actual source is my laptop  and the target is z/OS – not the other way round. 

A ping request

A more detailed definition, to allow a ping request from my laptop to z/OS would include

IpSourceAddr LAPTOPIP IpDestAddr zOSIP … Direction inbound Protocol icmp Type 8 …
IpSourceAddr zOSIP  IpDestAddr LAPTOPIP  … Direction outbound Protocol icmp Type 0 …

A ping request is a packet with protocol type of icmp, and icmp-type of 8. The response to a ping is an icmp packet with icmp-type of 0. A definition using direction bidirectional would not work, as you can only specify one icmp type.

Of course you could have a definition without the type, so all icmp packets are accepted but that is an implementation decision.

Accessing a server on z/OS

I have an HTTP server on z/OS with port 443. The definitions are

IpSourceAddr LAPTOPIP IpDestAddr zOSIP … Direction inbound Protocol Tcp DestinationPortRange 443
IpSourceAddr zOSIP  IpDestAddr LAPTOPIP  … Direction outbound

The server has an IP address and port which I specify in my web browser. The definition for the return has no port, because it is variable (different invocations used ports 46938, and 46656 on the laptop).

If you know the range of ports that will be used you can specify DestinationPortRange nn mm and/or SourcePortRange nn mm.

Filter action DiscardAction didn’t work at first

When you have created a rule, you need to decide what action it should take.

You use the IpFilterAction to Permit or Deny the packet.

If the packet is to be discarded, then it can be silently dropped, with no further action ( so the requester does not get notified), or it can send back an ICMP packet to the requestor. If you use this, you will need to define a rule to allow these packets to get out of your TCPIP image, and so need a rule to allow icmp packets of type 3.

The documentation implied

IpFilterAction deny DiscardAction ICMP
IpFilterAction deny DiscardActionzzz ICMPzzz

The first line is the documented syntax, which is ignored. The second line did not produce any errors, event though it has invalid content.

The correct syntax is

IpFilterAction deny
DiscardAction ICMP

IpFilterAction deny
DiscardActionzzz ICMPzzz

With the values spread one per line. When I did this, it correctly complained that DiscardActionzzz ICMPzzz was invalid.

Why do I need to specify direction?

I struggled with why direction inbound/outbound is needed.

I have

IpFilterRule icmpin 
{ 
  IpSourceAddr 10.1.0.2 
  IpDestAddr   10.1.1.2 
  IpGenericFilterActionRef permit 
  IpService 
  { 
    Protocol icmp 
    Direction inbound 
    Routing local 
  } 
} 

Where

• IpSourceAddr 10.1.0.2 is my laptop
• IpDestAddr 10.1.1.2 is z/OS

To send a packet from my laptop to z/OS the traffic is inbound.

IpFilterRule icmpout 
{ 
  IpSourceAddr 10.1.1.2 
  IpDestAddr   10.1.0.2 
  IpGenericFilterActionRef permit 
  IpService 
  { 
    Protocol icmp 
    Direction outbound 
    Routing local 
  } 
} 

Where

• IpSourceAddr 10.1.1.2 is my z/OS image
• IpDestAddr 10.1.0.2 is my laptop.

To send a packet from my z/OS to my laptop, the direction is outbound.

I do not see what value having direction gives you!

Which rule is used?

For allow/deny

The short answer is all rules are scanned. If the criteria matches, and the action is deny the final result is denied.

For example with

1. IpSourceAddr 10.1.0.3 IpDestAddr … IpGenericFilterActionRef allowit
2. IpSourceAddr 10.1.0.0/24 IpDestAddr … IpGenericFilterActionRef denyit
3. IpSourceAddr 10.1.0.2 IpDestAddr … IpGenericFilterActionRef allowit

For my laptop with address 10.1.0.2:

• The first rule does not apply because the IpSourceAddress does not match
• The second,generic rule matches and the action is deny, and future checks are not done.
• The third rule matches but is ignored because the action has been set to deny.

For logging

The first matching rule is used. If you have a generic definition, followed by a specific definition, the definitions from the generic definition will be used.