SELinux Policy Analysis Tool Help File
apol, version 1.4
June 02, 2004
selinux@tresys.com

This file contains basic help information for using apol, version
1.4 This version of apol allows you to:

	+ examine, search, and relate policy components (types, type 
	attributes, object classes, object permissions, roles, users,
	initials SIDs and booleans), and policy rules (type allow, 
	neverallow, auditallow, dontaudit, type_transition, 
	type_change); and 
	
	+ perform some automated analysis of policies which 
	currently includes forward and reverse domain transition 
	analyses, direct information flow analysis, and transitive 
	(indirect) information flow analysis.

New in this version is support for binary policies. This allows you to load
either a binary or source policy and use all of the features of Apol as
appropriate. Some features are incompatible with binary policies (notably
attributes and the policy.conf display), so those features are disabled when
using a binary policy. Otherwise, Apol treats the two types of policies
similarly.

Apol attempts to provide compatibility with the current and older 
policy syntax to allow one to analyze current and old policies.  As of 
this version, we believe the tools are compatible with all policy 
versions from Version 11 to the current Version 17.

See setools/ChangeLog-setools for a list of new features in this 
release. See setools/KNOWN_BUGS for a list of current bugs.

1. MENUS:  

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

The QUERY menu allows the user to save and/or load a query for a TE Rules
search or for an analysis module listed on the Analysis tab. Saving a TE
Rules query involves saving the required query parameters, whereas saving an
analysis query involves saving the required query parameters as well as any
specified filter settings to a file. Query files are saved with a '.qf'
extension. Loading a query involves parsing the specified query file,
raising the correct tab in apol and configuring the query options with the
specified query parameters and/or filter settings. Currently, the save query
menu item is only enabled when the ANALYSIS TAB or the TE RULES TAB (see
POLICY RULES TAB below) is raised. However, the load query menu item is
enabled across all tabs. The Query menu also allows the user to display
statistics about the currently loaded policy. A shorthand version of these
statistics is always displayed on the status bar when a policy file is
opened.

The ADVANCED menu currently allows you to directly manage permission 
mappings for apol's direct and transitive information flow analyses, 
which are new features in this version of the tool. You do not need to 
use this dialog in order to perform an information flow analysis. However 
you might need greater control over the mappings of permission to 
read/write access for a given analysis you are performing.  This dialog 
gives you the flexibility to control these mappings directly.  The built-
in default mappings are based on the "mls" file distributed with the 
policy.  See the separate help file on information flow for more 
information about permission mappings and their management.

The ADVANCED menu also allows you to configure settings for apol through
the Tool Options dialog. Currently, you may configure which components of 
the policy should be loaded when opening a policy.

2. POLICY COMPONENTS TAB

These tabs allow you to examine, search, and relate the core 
components of an SELinux policy.

	I. 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. 
	
	II. CLASSES/PERMS TAB:
	
	This tab allows 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 "Permissions", and the 
	button "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 permission 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".
	
	III. 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.
	
	IV. USERS TAB

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

	This tab allows you to search initial sids defined in the policy, 
	as well as view the context for each initial sid.
	
	VI. BOOLEANS TAB

	This tab allows you to search boolean variables defined in the
	policy, as well as view the current state and/or policy default
	state of the variable. Additionally, you can change the state of the
	boolean variable to TRUE or FALSE from this tab. Changing the state
	of a variable will be applied in memory and but will not change the
	state within the actual policy file.


3. POLICY RULES TAB 

These tabs allow more advanced analysis of an SELinux policy.  In these 
tabs you can search and select from the many rules in a policy based on 
a set of search criteria you select.

	I. 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 in 
		the search.  
		
		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.  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).
		
		If the "Only show enabled rules" checkbox is selected, 
		your query results will include all rules that meet the 
		search criteria, EXCLUDING any rules that have been 
		disbled by a conditional expression. If the checkbox is 
		not selected, then your query results will include all 
		rules that meet the search criteria, INCLUDING those 
		rules that have been disabled by a conditional 
		expression.
		
		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 classes and 
		selected permissions will be returned.  Each of these 
		boxes allow multiple selections. In the case of multiple 
		select, apol currently treats them using an "or" 
		semantic (e.g., if two object classes, say dir and file 
		are selected, then rules that apply to file OR directory 
		object classes are selected).
		
		This tab allows 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 checkboxes 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, if the policy
	that is opened is a source policy.conf file, 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. If the policy is a binary policy, then 
	the hyperlinks will not be provided and the policy.conf tab will
	be disabled.
	
	The TE Rules Tab also allows you to have up to 10 results 
	windows.  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 window based 
	on the current search options.  Use the "Close Tab" bar at the 
	bottom to destroy a results window. Also, the TE Rules tab allows
	you to save/load search criteria to a file (see MENU section above).


	II. RBAC RULES TAB:
	
	This tab allows you to search role-based access control rules. 
	It is similar in nature to the TE Rules tab, but somewhat 
	simpler.
	
	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 available only if transition is selected and
	allow is deselected.  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.
	
	
	III. CONDITIONAL EXPRESSIONS TAB:
	
	This tab allows you to search conditional expressions within the 
	policy, as well as view the rules within these conditional 
	expressions. Please note that conditional expressions are displayed 
	in Reverse Polish Notation. Currently, you can only search for the 
	following types of policy rules within conditional expressions:
	
		- Allow rules
		- Audit rules
		- Transition rules
			
	You can search conditional expressions for a specific boolean 
	variable, as well as choose whether to use a regular expression. 
	Additionally, you can choose whether you want to display the 
	rules within conditional expressions. The current state of each  
	rule is provided by means of a tag within the results:
	
		"[enabled]" - indicates the rule is enabled
		"[disabled]" - indicates the rule is disabled	

4. ANALYSIS TAB

This tab provides automated analysis capabilities.  The "Info" button provides 
a description for the selected analysis type. Also, this tab allows you to 
save/load any query criteria to a file (see MENU section above). Current 
analyses are:

	I. DOMAIN TRANSITION ANALYSIS
	
	The Domain Transition analysis module allows you to specify a
	transition direction for the analysis. The 2 directions provided
	are:
	 
		FORWARD: The Forward Domain Transition (FDT) analysis takes
		a starting SOURCE domain and presents a tree of all the
		resulting TARGET domains that can be transitioned into from
		that starting domain. The tree can be walked to follow the
		FDT tree as deep as you like. The only restriction is that a
		subtree will not expand if its parent is the same as the
		node. Each node in the FDT tree represents a TARGET domain
		to which the parent domain can directly transition.
	
		REVERSE: As its name implies, the Reverse Domain Transition
		(RDT) analysis is the reverse of the FDT analysis. The RDT
		takes a starting TARGET domain and presents a tree of all
		the resulting SOURCE domains that can directly transition to
		that TARGET domain. The tree can be walked to follow the RDT
		tree as deep as you like. The only restriction is that a
		subtree will not expand if its parent is the same as the
		node. Each node in the RDT tree represents a SOURCE domain
		that can transition to its parent node.

	Selecting a child node will show all the rules that permit the 
	transition to occur.

	See the separate help file for an overview of the criteria that 
	constitute an allowed domain transition.
	
	II. DIRECT INFORMATION FLOW ANALYSIS
	
	The Direct Information Flow (DIF) analysis takes a starting type 
	and an information flow direction (IN, OUT, EITHER, or BOTH), 
	and presents a tree with the starting type as the root node. The 
	child nodes represent other types in the policy where 
	information flow can occur DIRECTLY between its parent node and 
	itself.  If the flow direction is IN, then information in the 
	child node types can flow to the parent node type.  If the flow 
	direction is OUT, then information in the parent node can 
	DIRECTLY flow to the child node.  If the direction is BOTH then 
	information can flow from child to parent and from parent to 
	child. If EITHER is selected then flow direction will be IN, 
	OUT, or BOTH.
	
	Selecting a child node will show all the rules that permit the 
	information flow to occur.  Results are presented by object class.
	
	You can filter the results by selecting one or more object 
	classes. This will ensure that only those flows that are allowed 
	for the selected object class will be shown (e.g., if you select 
	file, then flows allowed for sockets will not be presented). You 
	can also use a regular expression to limit the results by end 
	type.  Only those end types that match the provided regular 
	expression will be presented.
	
	See the separate help file on information flow for more 
	information about direct information flow.
	
	III. TRANSITIVE INFORMATION FLOW ANALYSIS
	
	Whereas the DIF analysis identifies information flows that are 
	directly allowed by one or more explicit rule, the Transitive 
	Information Flow (TIF) analysis attempts a much more extensive 
	analysis.  Specifically the TIF identifies indirect paths 
	between two types.  Since such paths can be circuitous, over many 
	hops, this analysis is quite difficult to achieve.  
	
	Our current TIF takes a starting type and an information flow 
	direction (FLOW TO or FLOW FROM) and presents a tree with the 
	starting type as the root node.  The child nodes represent other 
	types in the policy where information flow can occur (directly or 
	transitively) between its parent node and itself.  If the flow 
	direction is FLOW TO then the information flow is to the parent 
	node.  If the flow direction is FLOW FROM then the information 
	flow is to the child node. 
	
	Selecting a child node will show each step in the flow chain 
	between the starting node and the child node, along with the 
	rules that allow that step to occur.  Results are presented by 
	object class. Additionally, embedded in the text of the results
	is a hyperlink for finding more flows between the starting node
	and the selected child node. This link displays a dialog where
	you can specify a time limit for the search and/or limit the 
	number of flows to find in the search. 
	
	As with the DIF analysis, you can filter the results using end 
	type regular expression. The TIF analysis also includes a text 
	widget for providing comments. 
	
	Additionally, the TIF analysis provides the Advanced Filters 
	dialog for filtering results by object class permissions and/or 
	types. Selecting an object class in the Advanced Filters dialog 
	will display a list of permissions for that object class, whereby 
	you can then choose to include or exclude certain permissions. By 
	default, all permissions for an object class are included in the 
	query, unless you exlude a permission(s) by selecting its' 'Exclude' 
	radiobutton. Configuring all permissions for an object class to be 
	excluded will exclude the object class itself from the query. When 
	an object class becomes excluded, its' label will change to indicate 
	that the object class is to be excluded from the analysis query.
	
	Additionally, the Advanced Filters dialog displays the weight value 
	of a permission, as specified in the loaded permission map (see the 
	separate help file on information flow for more information about 
	managing permission mappings). You can specify a weight threshold 
	in order to exclude permissions from the results that have weights 
	below a certain threshold. You can also filter the query results by 
	including or excluding intermediate types. Comboboxes are provided 
	for filtering these lists by attribute. 
				
	See the separate help file on information flow for more 
	information about transitive information flow.	



5. POLICY.CONF TAB

This tab provides a convenient display of the raw policy.conf source 
file.  In addition, the TE rules tab and the Domain Transition analysis 
(on the Analysis tab) currently support a hyperlink to the source 
policy.conf file, only if the policy is a source policy.conf file.
Otherwise, this tab will be disabled and hyperlinks to this tab will
not be provided.

																																																																																                                                                                                                                                                                                                                                                                                                                                 
