
Help file for 'apol' Version 0.7
25 February 2003
selinux@tresys.com

This file contains basic help information for using apol, Version 
0.7. This version of apol allows you to examine types, type 
enforcement rules, roles, RBAC roles, object classes, permissions, 
common permissions, and users. Other portions of the policy are 
ignored for now. 

Apol attempts to provide compatibility with the current and older 
policy syntax to allow one to analyze current and old policies.   

See below for list of known bugs.

1. Menus:  

Most menus are straightforward in their meaning.  The only special 
menu is View->Policy Summary.  This will display interesting 
statistics about the policy.  A shorthand version of these statistics 
are always displayed on the status bar when a policy file is opened.

apol expects you to open a policy.conf file, and it expects that this 
file can be successfully parsed using checkpolicy -d.  Only one 
policy.conf file can be open at a time, so if you open another file, 
the current one will be closed.


2. Types Tab:

This tab lets you search through types and attributes.  You can double 
click on any type or attribute in the list boxes to see full details 
for that type/attribute.  You can also use the search options and hit 
the OK button to perform a search.

The Search box allows you to search for types and/or attributes using 
a POSIX regular expression. 


3. TE Rules Tab:

This tab allows you to search through the type-enforcement rules. This 
is the most complicated tab, and the one we use most extensively.

This tab allows you to specify three different types of search 
criteria:

	1. Rule Selection: allows you to decide the scope of search; 
	only those rules selected will be included.  

	2. Type/Attributes subtab: allows you to refine a search based 
	on types and/or type attributes used by a rule.  There are 
	three general type search options: source, target, and 
	default.  Default is useful only if one or more of type 
	transition/member/change rules 	are selected, and NO OTHER 
	RULE.  The other rules do not use the default field. 
	The source field can also be used as an "any" field.  In this 
	case, the other two options will not be available, and the 
	search will look for the selected type/attribute in any field 
	of the selected rules.  

	The drop down boxes allow you to select a type or attribute. 
	If the 	Enable Regular Expression box is checked, then you can 
	enter a regular 	expression in any type/attrib box. 
	With regular expressions enabled, 	if you use the drop 
	down box to select a type/attrib, the type/attrib 	string 
	will be enclosed within ^& to make it an exact match regular 
	expression.  You can edit this string into any regular 
	expression you 	wish, including the NULL expression (which 
	should match everything). 	With regular expressions 
	enabled, you can restrict the search to 	types, 
	attribs, or both using the Type and Attribs check boxes.

	If regular expressions are disabled, apol currently supports 
	only one 	type/attribute in each box; some day we'll add 
	the ability to select multiple types/attributes, as well as 
	use a regular expression in these fields.  This type/attrib 
	must be a complete, valid type or attrib string.  The Default 
	field can only be a type (not an attribute).

	The "Include Indirect Match" checkbox alters the meaning of 
	the search 	if a type is used in the given field (this 
	option is not available if an attribute is used). In this 
	case, the search will find rules that have either the provided 
	type or any of the type's attributes in the 
	appropriate field.

	3. Classes/Permissions subtab: allows you to refine a search 
	using object classes and/or permissions.  Only rules that 
	contain the selected object class and selected permission will 
	be returned.  Each of these boxes allow multiple selections. 
	In the case of multiple select, apol currently treats them 
	using an "or" semantics (e.g., if two object classes, say dir 
	and file two object classes, say dir and file are selected, 
	then rules that apply to file OR directory object classes are 
	selected).

	This tab allow you to prune the list of permissions based on 
	the 	object classes selected.  If the "Only show 
	permissions for selected object classes" button is selected, 
	then only permissions related to selected objects are shown. 
	As you select different objects, the list of available 
	permissions will change.  The Union and Intersection button 
	determine whether the union or intersection of common 
	permissions is desired.


In the results Tab for a given search, all rules that meet the search 
criteria will be displayed.  In addition, a hyperlink for each rule is 
shown.  Clicking on this list will take you to the policy.conf tab and 
highlight where in the policy.conf file the rule was found.  This will 
allow you to trace the rule back to the ultimate source code.

The TE Rule Tab also allow you to have up to 10 results window.  Each 
active window remembers the search options used for it, and will set 
all the options accordingly when selected.  You can use the "Update" 
button to change the results displayed for the current window based on 
the current search option.  "New" will create a new results windows 
based on the current search options.  Use the "Close Tab" bar at the 
bottom to destroy a results window.


4. Roles Tab:

This tab allows you to search roles and their attributes. It behaves a 
lot like the Types tab (e.g., double click on a role for details about 
that role).

The primary search option allows you to find all roles that include a 
given type.  This tab has become much more useful since the 2002031409 
version of SELinux, as the role definitions have now been spread 
across a number of files.


5. RBAC Rules Tab:

This tab allows you to search role-based access control rules. It is 
similar in nature to the TE Rules tab.

It allows you to search both role allow and transition rules, even 
though the role_transition rule has been deprecated (we see policies 
that still use this rule).

The Default option is only used if only transition is selected.  The 
Target option will change depending on which rule type is selected. 
If only allow is used, then you can select a target role.  If only 
transition is selected then you can select either a type or attribute. 
If both are selected, this option is not available.  All of this is to 
conform with the syntax of these two rules.

As with TE Rules, the Source option can also be used in an "any" 
search.

6. Classes/Perms Tab:

This tab allow you to view and search object classes, common 
permissions, and permissions defined in a policy.  Double clicking on 
any name from the three list boxes will give a brief summary of the 
class, permission, or common permission. The search options allow you 
to view more detailed aspects of classes and permissions.  

For example, if you wanted to know which objects use the permission 
getattr, you would select "Show Permissions", and the button "Show 
Object Classes" directly below it.  Then select "Regular Expression 
Search" and type "^getattr&" in the box.  Then hit OK and see a list 
of object classes that use that permission (a * will mean that the 
class uses that permissions via a common permission).

You can use any regular expression to constrain the search.  So for 
example, to find all the permissions that start with the string "set", 
use the regular expression "^set".


7. Users Tab

This tab allows you to search users defined in the policy, and view 
the roles allowed for that user.

8. policy.conf Tab

This tab provides a convenient display of the raw, policy.conf source 
file.  In addition, the TE rules tab currently supports a hyperlink 
capability between TE rules an the source policy.conf file.


Known Bugs: 

1. If you get a parse error opening a policy file, you need to exit 
and re-start apol.  This bug causes apol to not recognize valid 
policy.conf files; the tool will automatically exit in such cases so 
you may restart the tool.
                                                                                                                                                                                                                                                                                                      