SE Linux Policy Customization and Editing Tool
SePCut, version 0.2
Help File, 25 February 2003
selinux@tresys.com


Overview
--------

This file contains basic help information for using sepcut, a policy 
customization, browsing, editing, and testing tool for Security 
Enhanced Linux.  This is version 0.2 of the tool, i.e., the very
first generation.  Sepcut is a basic editor and early generation
customization tool....use with caution.

The tool has three main tabs (and associated functions):

	BROWSE POLICY: This tab allows you to browse, view, and edit 
	any files within a given policy directory.  

	CUSTOMIZE PROGRAMS: This tab allows you to view all the 
	program "modules" within a policy directory, as well 
	as to enable/disable the module within the built policy.  Each 
	module has a .te and .fc file, each of which may also be 
	edited within this tab.

	TEST POLICY:  This tab allows you to test build, install, and 
	load a 	policy (i.e., by invoking one of the standard make 
	targets) and view 
	the results.  

Together these three tabs gives you a complete, albeit basic, ability 
to view, edit, test, and debug a policy source directory.  


Menus
-----

Most of the menus are straightforward.  

POLICY menu:  This menu allows you to choose (open) a policy 
directory, re-load the currently opened policy directory, or close 
the current policy directory.  A close happens implicitly on opening 
or re-opening a policy directory.  The tool will do some basic 
checking, and if it determines that the chosen directory does not 
appear to be a valid policy directory, it will refuse to open the 
directory and provide some error message. This tool requires a 
reasonable modern policy source directory, that includes the 
modularized .te and .fc program directories.  Sorry, this tool will not 
work with older source directories.  You can also save all modified
files from this menu.

You can define a policy directory to be opened by default when
the tool starts in the global defaults (see below).

	FILE menu:  This menu allows you to view, save or revert files 
	that have been modified.  You can only do "save as" from the browse 
	tab (the customize tab allows you to create new modules on the 
	next menu). This menu is not available in the Test tab.

	EDIT menu:  This menu lets you do three types of functions. 
	First, 	in the Customize tab only, you can add or delete a new 
	module, which will create both a .te and .fc file for the new 
	module.  For Add module, these files are created on disk 
	immediately and added to the current display. Stubs of the 
	file contents are also created.  Future changes will need to 
	be saved.  You can also delete a module (which would 
	permanently delete both the .te and .fc files).  

		NOTE:  We strongly recommend against deleting modules;
		rather just disable them in the Customize 
		tab.

	You can also enable all modules from the Edit menu.

	The Edit menu also allows you to go to a particular line in 
	the currently displayed file, as well as to toggle the Edit 
	mode.  This tool has a read-only and a edit mode.  The default 
	setting for this mode is defined in the global defaults 
	setting (see below). Additionally, you can perform a text search
	from this menu. 

Browse Policy Tab:
-----------------

This tab is a simple browser, file viewer, and editor.  You can view 
and edit any file below the root of the policy directory.  You can 
also "save as" a file to another file, but the tool will not let you 
save a file outside the policy directory and its subdirectories.  This 
tab should remain entirely consistent with any changes 
(enable/disable, file modifications/removal) performed in the 
Customize tab.


Customize Programs Tab:
----------------------

This tab gives you a program module view of a policy source tree.  The 
view focuses on the ./domains/programs directory for type enforcement 
(.te) policy files and their associated file context files in 
file_contexts/programs.  The convention is that each .te program file 
must have a .fe file with the same root filename.  This tab treats 
both files as two halves of a single module package, and allows you to 
enable (include in the built policy) and disable (excluded from the 
built policy) modules by checking the associated checkbox.  The tool
disables a module by moving its .te file to an "Unused" subdirectory,
which will cause it (and its associated .fc) file to be excluded
from the build process.

NOTE:	At some time we'll need to do some serious work in the policy
	to check for dependencies so a tool like this can ensure that
	dependencies are not violated...for now its trial and error.  

Program modules can be displayed by filename or by descriptive name. 
The convention for descriptive name is to look for the first line to 
have a "#DESC" tag, and then to take the string following that tag as 
the descriptive name.  Not all files follow this convention, in which 
case we use the filename for both.  


Test Policy Tab:
---------------

This tab allows you to test compile the policy, with all changes and
module inclusions as specified in other tabs, to check for errors.
The TEST button will run the policy source through checkpolicy 
(i.e., compile the policy and check for syntax/semantic errors).
The CLEAN button will run a "make clean" on the policy directory.
The INSTALL button will compile the policy and attempt to
store the resulting binary in the system install location (if
you have permission).  The LOAD button does the same as install, but
also immediately loads the new policy into the kernel.

You can also open the policy.conf file that results from a test
compile, and search by line number in that file.  This is useful
as it's really the only debug technique that exists for policy
compile errors.  

We also recommend using our policy analysis tool (apol) on the same
policy.conf file to help understand a policy.


Setting Global Defaults:
-----------------------

Sepcut is a straight tcl/tk script, and therefore its an executable 
text script.  The header for the program provides a name space that 
you can directly edit to define some global default settings.  These
settings include whether the tool starts in edit or read-only mode, and
whether a policy is opened by default.  You can either edit these
setting directly in your copy of the script or change them in the
main.tcl file in the source tree.  The default settings section
looks like:

namespace eval Sepct_Main {
	# This var determine whether the tool starts in edit or read-only mode
	# 	(0 read only, 1 edit mode
	variable initial_edit_mode	1
	
	# This var, if defined with something other than "", determines
	# what policy directory will open (load) by default.
	#variable inital_policy_dir	"/etc/security/selinux/src/policy/"
	variable inital_policy_dir	""
	
	# This var determines whether modules are listed using descriptive
	# name (0) or file name (1), by default, in the customize tab
	variable show_customize_file_names	0
}

Just follow the instruction in the comments to change the defaults.  
Eventually we will create a proper per-user default management.


Known bugs
----------

1. Unfortunately if you have a file name that is an integer, the tool
will fail on the policy directory!  It's because of a simple way we
manage file data and modification data...something we'll have to fix
next time!



                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              