CheckPoint.pm - Perl package to read and use CheckPoint database files
This package is created to support programs that need information from the CheckPoint databases. It is written originally to support CPRULES, a tool to translate CheckPoint FW-1 rulebases to html format. However other purposes might come up ...
The package contains routines to read the provided files and stores them in memory. The GetKey and GetMembers routine makes the data easily accessible for the hostprogram.
Warning: To access the data from the database, one has to know the exact location/syntax of the information in the Check Point tables. This requires thorough understanding of the CheckPoint database structure.
The data read from the CheckPoint files is retained within the package. That means that the main variable (%objects) is not exported (not known outside the package). Routines are provided to allow the data to be read and/or changed by external programs.
Internal to the package, the database is one big hash structure. When reading a file, the contents of this file is added to the same structure over and over again. This will not pose a problem, as long as all CheckPoint data is stored in different tables. For example:
$objects{network_objects}
is the ref to the network_objects table. And to get to a specific value, in this case of a service, one would write:
$port = $objects{services}{http}{port};
This will normally hold the value '80', as http uses tcp port 80 to do its magic :-)
A special case worth mentioning is:
$objects{rule-base}
This will hold a reference to all rulebases defined. If one checks the rulebases file, one could be puzzled. For in the CheckPoint database all rulebases are stored using the same key 'rule-base' (without a proper rulebase name). The name of the rulebase is actually stored much deeper in the structure (see the coding example below). That obviously makes it hard to distinguish between the different rulebases.
To solve this problem, the routine converts the value $objects{rule-base} to an array element. Within this array every member holds the reference to one rulebase.
So the ref to the 'Standard' rulebase might actually be:
$objects{rule-base}[2]
and to make it a bit more confusing, the fourth rule in this rulebase would be:
$objects{rule-base}[2]{rule}[3]
as all the rules are stored as 'rule'.
This is however NOT how this package should be used. In such cases the GetMembers routine will proof its worth.
To start you of, the code below will read the rulebases file and get all comments as noted in the individual rules of all rulebases:
use CheckPoint;
my ($rulebase, $rule); my ($rulebase_name, $rule_comment); my (@rulebases, @rules);
# Read the rulebases
GetObjects('rulebases_5_0.fws');
# Get a list of all rulebases
@rulebases=GetMembers(GetKey('rule-base'));
foreach $rulebase (@rulebases) {
# Get the name of the rulebase
$rulebase_name = GetKey($rulebase, 'collection:Name');
# Get a list of all rules in the rulebase
@rules=GetMembers(GetKey($rulebase, 'rule'));
foreach $rule (@rules) {
# Get the comments of this rule
$rule_comment = GetKey($rule, 'comments');
# Print the comments to stdout
if ($rule_comment) {
print $rulebase_name.': '.$rule_comment."\n";
}
}
}
Note: All the data is retained within the package and can only be accessed through the GetKey and GetMembers routines. A few adaptations could be made to export the hash variables themselves, but that is not recommended.
The first step of any program would be to read the CheckPoint database files in to memory. The most important file is currently 'objects_5_0.C' which holds all objects and its parameters. Other files are 'rulebases_5_0.fws' and 'user.C' (although it is not clear to me what this file exactly is meant to do).
Syntax: GetObjects(filename)
The routine reads the file and stores it in one single hash. The reference to this hash-structure is returned. If more consecutive files are read, the tables are stored in the same hash-structure!
Examples:
To read the objects database in memory you would use the command below. The returned value is a reference to the root of the database.
$objects=GetObjects("objects_5_0.C");
Next the rulebases will be added to the same hash
$objects=GetObjects("rulebases_5_0.fws");
Now the information is stored in memory, the actual work can begin. To retrieve the information from the database, one uses the GetKey function or GetMembers as described later on.
Syntax: GetKey([object_reference], 'key[:more_keys]')
- where the object_reference is optional. If it is not specified, the root object is assumed.
- where the key-part is a colon-delimited list of keys enclosed within quotes (see examples).
Returns: The value of the key requested, or an empty string if the key could not be found.
Examples:
To get the type of an object called 'InternalNetwork':
$type = GetKey('network_objects:InternalNetwork:type');
which will probably return the scalar value 'network'
... or if the reference to an object is first stored in a variable:
$obj = GetKey('network_objects:InternalNetwork');
$color = GetKey($obj, 'color');
which might f.i. return the scalar value 'blue'
$class = GetKey($rule, 'AdminInfo:ClassName');
which will return the class of a rule (referenced by $rule), f.i. the scalar value 'security_rule'
... the same principle is applied here
$obj = GetKey('network_objects:MailServer');
$smtp = GetKey($obj, 'smtp');
which will return a reference to the hash that holds all SMTP specific parameters. So now you would be able to do:
$rcpt = GetKey($smtp, 'maxrecipients');
which might return the scalar value of '50'
To change, add or even remove information to/from the database, one can use the SetKey function.
Syntax: SetKey([object_reference], 'key', ['value' | value_reference])
- where the object_reference is optional. If it is not specified, the root object is assumed.
- where the key-part is the name of the (new) key enclosed within quotes (see examples). Note this can NOT be a colon delimited list as is allowed in the GetKey routine.
- where the value is a scalar, or the value_reference is the reference to a datastructure such as a hash or array. If neither is specified, the key will be destroyed.
Returns: The reference to the newly created key if a value was set successfully, or the reference to the original object if no value was set
Examples:
To set the color of an object called 'InternalNetwork' to 'blue':
$obj = GetKey('network_objects:InternalNetwork');
SetKey($obj, 'color', 'blue');
- or combined in one line -
SetKey(GetKey('network_objects:InternalNetwork'), 'color', 'blue');
To add a list of names to an object (note the reference to the array!):
@names = ('jane', 'mark', 'misterX', 'paul');
$obj = GetKey('network_objects:ServerA');
SetKey($obj, 'Names', \@names);
To remove the above list of names:
$obj = GetKey('network_objects:ServerA');
SetKey($obj, 'Names');
To create a new hash in an object called 'is_used' and set a value within that hash (such as used in the ObjectUsed routine):
$obj = GetKey('network_objects:MyServer');
$obj = SetKey($obj, 'is_used', {});
SetKey($obj, 'byMe', 'true');
This routine is to retrieve the members of an object. This term is used loosely to accomodate different situations, but members should always be organized in some kind of list. For example the members of a group, or a numbered list within the object. So members are NOT all the subkeys of an object/key. This definition makes the GetMembers routine unsuitable to get a list of all (f.i.) services, or network-objects. These are not stored in any kind of list, but in a hash structure (see below for an example on this).
Syntax: GetMembers([object_reference])
The routine returns an array with the members of the requested object (specified by the object_reference). The members are determined in the order specified below.
1. The first method CheckPoint uses to store a list is to use several items with the same name (f.i. rules). As described before, these elements will have been placed in a list already. So if one asks for all rules in a rulebase, the corresponding list will be returned.
2. If the object referenced only holds a single value (SCALAR), this value is returned as a list with only one member.
3. The normal way for CheckPoint to store members is in one or more occurrences of a 'ReferenceObject' (referencing a different object by Table and Name). These objects are stored in a list called 'ReferenceObjects'. Sometimes a key holds a list of unnamed values or objects. These unnamed values/objects are stored in a list called 'AnonymousObjects'. In both cases the list is returned as being the memberlist.
4. Then it can occur that a numbered list is used. This happens f.i. when enumerating the interfaces of an object. All numbered items are returned in the list.
5. If the object referenced has no members, but it is defined as a CheckPoint object, an empty list is returned. This is f.i. the case when querying an empty group.
6. Finally if all tests fail, it is concluded that this key is a list in itself. The function will return the object reference itself as a list with only one member. This can occur f.i where the rulebase has only one rule. During the import of the database there was no indication that this rule was actually the start of a list of rules. Therefore it has not been converted to a list (yet)!
A special known situation is the ACTION key of a rule. It behaves like the start of a list of actions, so it is guessed there might be more ACTIONS in one rule in the future.
Examples:
To get the members of a simple group:
@members = GetMembers(GetKey('network_objects:ServerGroup'));
To get all rules of a given rulebase:
@rules = GetMembers(GetKey($rulebase, 'rule'));
Note: To get a list of all services, this WILL NOT work:
@services = GetMembers(GetKey('services'));
to get a list of services, one should use:
@services = (keys %{GetKey('services')});
The routine ObjectUsed is to flag a CheckPoint object as being 'used' in a rulebase. This is usefull to filter out the objects which are related to in a specific rulebase, or to determine which objects are not used at all.
Some objects use other objects. For instance on the interface of a gateway, one can configure an anti-spoofing group. This group is not necessarily used anywhere else, but because the gateway object is, the anti-spoofing group is used too. So it should me marked as such. This is accomplished by recursively calling the routine for those objects that do have 'children'.
The routine uses the function SetKey to add the elements to the database.
Syntax: ObjectUsed([object_reference], where_used)
- where the object_reference can be any object in the database. However, only CheckPoint objects will be marked as 'used'.
- the where_used defines the rulebase the object is used in. The function will create a new key call 'is_used' which is a hash holding the names of rulebases the object is used in.
Returns: The number of objects marked as being used recursively. Note however that every object can only me marked 'used' once. So this number only reports the objects marked that has not been marked before.
Examples:
$NrObjectsChanged = ObjectUsed(GetKey('network_objects:MyIntranet'), 'ThisRulebase');
This is version 1.0. There is no history yet, as this is the first release...
Please send bug reports to the author. Please include a detailed description of the problem and some test data to reproduce the problem.
Peter-Paul Worm, (Peter-Paul.Worm@wormnet.nl)