xref: /test/ontest-stc2/src/suites/security/sbd/README

#
# CDDL HEADER START
#
# The contents of this file are subject to the terms of the
# Common Development and Distribution License (the "License").
# You may not use this file except in compliance with the License.
#
# You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
# or http://www.opensolaris.org/os/licensing.
# See the License for the specific language governing permissions
# and limitations under the License.
#
# When distributing Covered Code, include this CDDL HEADER in each
# file and include the License file at usr/src/OPENSOLARIS.LICENSE.
# If applicable, add the following below this CDDL HEADER, with the
# fields enclosed by brackets "[]" replaced with your own identifying
# information: Portions Copyright [yyyy] [name of copyright owner]
#
# CDDL HEADER END
#

#
# Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
# ident	"@(#)README	1.5	08/03/03 SMI"
#


1.  INTRODUCTION
2.  HOW TO RUN TESTS AND EXAMINE RESULTS
3.  TEST SUITE DESIGN NOTES
4.  CONTACT US



1.  INTRODUCTION

This test suite is a functionality test for the Secure By Default (SBD)
functionality of Solaris, which diables almost all network services by
default on a freshly installed system by applying a secured SMF profile,
a.k.a generic_limited_net.xml.  This test suite is designed to test if
any unexpected network port was opened when the secured SMF profile was
applied.


2.  HOW TO RUN TESTS AND EXAMINE RESULTS

This test suite uses the STF harness, but operates in a manner slightly
different from the usual manner in which other STF-based suites do.
Details of the test suite's design and implementation are presented in
the section titled "TEST SUITE DESIGN NOTES."

To run the suite, make sure the system is s10u3_b4 or snv_42 and above,
freshly installed or upgraded, IPv6 enabled, name service configured to
"NONE", no NFS automounts exist on the test system (i.e., the system
should not have mounted any NFS systems or shared any systems over NFS
after the post-install reboot).


a. Get STF tools

   Even though STF allows itself to be used over NFS, it is strongly
   recommended that for this suite, STF tools be installed by either 
   using pre-compiled packages, or by building a local repository of STF
   tools.  NFS accesses can lead to failures in the test suite due 
   to mountd/lockd behavior.

	# pkgrm SUNWstc-stf SUNWstc-checkenv
	# pkgadd -d <package-location> SUNWstc-stf
	# pkgadd -d <package-location> SUNWstc-checkenv

	where <package-location> refers to the path at which the
	respective packages reside.

	Checkenv packaging is only partially integrated with STF, and
	the following symlink needs to be made

		# cd /opt
		# ln -s SUNWstc-checkenv checkenv 

	OR the STF_CHECKENV_PATH variable needs to be set and exported
	in the shell in which tests will be executed.


b.  Get the SBD test suite

    One of two methods may be used for this: building and installing a
    local copy of the test suite package, or installing a precompiled
    package.

    1) Building a local copy

    This approach is highly recommended because precompiled dtrace
    scripts may not be compatible across different builds of Solaris.
    To build a local copy of the test suite, obtain the test suite
    source (using Source Code Management commands), add STF utilities to
    your PATH and invoke stf_build:


    $ PATH=<path-to-STF>/bin/`uname -p`:$PATH; export PATH

    (CODEMGR_WS will be set if using TeamWare for source code
    management.  Otherwise, set CODEMGR_WS to the parent directory of
    the 'src/suites' PATH hierarchy.)

    $ cd $CODEMGR_WS/src/suites/security/sbd
    $ stf_build package
    $ cd ${CODEMGR_WS}/packages/`uname -p`
    $ su - root
    ...
    # pkgadd -d `pwd` SUNWstc-sbd

    Note: /usr/sfw/bin/cpp is used as the default C language
    preprocessor.  This behavior can be overridden by exporting the
    variable CPP.  If gcc is being used to compile the test suite, a
    compatible (i.e., GNU) version of cpp is required, which is
    distributed with gcc on Solaris, and is usually found installed in
    /usr/sfw.

    2) Installing a precompiled package
	
    # pkgrm SUNWstc-sbd
    # pkgadd -d <package-location> SUNWstc-sbd

    If <package-location> is an NFS-accessible location, then it is
    strongl recommended that the test system be rebooted in ordre to
    eliminate the side-effects of NFS access.


c.  Configure the test system to run the test suite

    (Assuming STF utilities are in the PATH)

    $ cd /opt/SUNWstc-sbd
    $ stf_configure

    STF may prompt for the system root password at this point.


d.  Execute the tests

    (Assuming STF utilities are in the PATH)

    $ stf_execute

   The system will reboot automatically 10 minutes after stf_execute has
   completed.


e. Examine the test results

   If tests were executed from /opt/SUNWstc-sbd, the results of test
   execution will, by default, be placed at /var/tmp/SUNWstc-sbd/results
   It is possible to place the results under a different directory (for
   which, see the STF User's Guide).

   There will be an STF journal file, a log file from the SMF service
   'bindtrace' and a log file from the SMF service 'sbdmonitor'.  To
   view test status, run:

   $ grep FAIL bindtrace*
   $ stf_filter journal*

   You may look at the journals and logs themselves to see detailed
   execution information and results.


3.  TEST SUITE DESIGN NOTES

As stated above, this test suite uses the STF harness, but operates in a
manner slightly different from the way usual STF-based tests do.

This suite has only one STF test case, which uses two distinct
approaches to verify the functionality of the secured SMF profile,
depending on whether the test is running in the global zone, or in a
non-global zone.  The 'sbd_bindtrace' script, which only runs in the
global zone, performs the verification of the application of the secure
(SBD) profile by DTracing suspicious bind(3SOCKET) calls; the
'sbd_netstat' script, which runs only in non-global zones, verifies the
correct application of the secured (SBD) profile by checking against the
output of netstat(1M).

When the test runs in non-global zones, it acts in a standard STF-based
way.  However, in global zone it operates differently in that the test
is not actually executed when stf_execute runs, but rather during the
booting process *after* stf_execute has completed.  This is what is done
as part of the global-zone test, 'sbd_netlimited': anonymous trace is
enabled, an SMF service named network/bindtrace is set up for examining
DTrace data on the fly, an SMF service named network/sbdmonitor is set
up for applying the secured SMF profile, the system rebooted, logs of
the network/bindtrace service are collected and post-test cleanup
performed.  10 minutes after the target test system has successfully
booted, the actual test is done and the test journal file and services
log files are placed in the test results directory.

When this test suite is run in the global zone, the log of the SMF
service named 'network/bindtrace' holds the actual test status, and the 
the STF journal file and the log of the SMF service 'network/sbdmonitor'
contain useful debug information only.  There's no explicit PASS in the
'network/bindtrace' log file.  The absence of the word "FAIL" from the
'network/bindtrace' log is used to indicate a PASS in this scenario.
Therefore, issuing the command "grep FAIL bindtrace*" demonstrates
whether any unexpected network services were enabled in the hardened
environment (i.e., whether the test has failed).

When this suite is run in non-global zones, the STF journal contains a
PASS/FAIL result as usual.  The absence of FAIL does not automatically
imply that the test has passed; the result of the test must explicitly
indicate PASS.


4.  CONTACT US

If you have questions or comments on the test suite, please send email
to the STC_CONTACT alias mentioned in the STC.INFO file of this test
suite.  Details on filing bugs against the test suite are also included
in the STC.INFO file.