Home | History | Annotate | Download | only in sbd
      1 #
      2 # CDDL HEADER START
      3 #
      4 # The contents of this file are subject to the terms of the
      5 # Common Development and Distribution License (the "License").
      6 # You may not use this file except in compliance with the License.
      7 #
      8 # You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
      9 # or http://www.opensolaris.org/os/licensing.
     10 # See the License for the specific language governing permissions
     11 # and limitations under the License.
     12 #
     13 # When distributing Covered Code, include this CDDL HEADER in each
     14 # file and include the License file at usr/src/OPENSOLARIS.LICENSE.
     15 # If applicable, add the following below this CDDL HEADER, with the
     16 # fields enclosed by brackets "[]" replaced with your own identifying
     17 # information: Portions Copyright [yyyy] [name of copyright owner]
     18 #
     19 # CDDL HEADER END
     20 #
     21 
     22 #
     23 # Copyright 2007 Sun Microsystems, Inc.  All rights reserved.
     24 # Use is subject to license terms.
     25 #
     26 # ident	"@(#)README	1.7	08/12/17 SMI"
     27 #
     28 
     29 
     30 1.  INTRODUCTION
     31 2.  HOW TO RUN TESTS AND EXAMINE RESULTS
     32 3.  TEST SUITE DESIGN NOTES
     33 4.  CONTACT US
     34 
     35 
     36 
     37 1.  INTRODUCTION
     38 
     39 This test suite is a functionality test for the Secure By Default (SBD)
     40 functionality of Solaris, which diables almost all network services by
     41 default on a freshly installed system by applying a secured SMF profile,
     42 a.k.a generic_limited_net.xml.  This test suite is designed to test if
     43 any unexpected network port was opened when the secured SMF profile was
     44 applied.
     45 
     46 
     47 2.  HOW TO RUN TESTS AND EXAMINE RESULTS
     48 
     49 This test suite uses the STF harness, but operates in a manner slightly
     50 different from the usual manner in which other STF-based suites do.
     51 Details of the test suite's design and implementation are presented in
     52 the section titled "TEST SUITE DESIGN NOTES."
     53 
     54 To run the suite, make sure the system is s10u3_b4 or snv_42 and above,
     55 freshly installed or upgraded, IPv6 enabled, name service configured to
     56 "NONE", no NFS automounts exist on the test system (i.e., the system
     57 should not have mounted any NFS systems or shared any systems over NFS
     58 after the post-install reboot).
     59 
     60 
     61 a. Get STF tools
     62 
     63    Even though STF allows itself to be used over NFS, it is strongly
     64    recommended that for this suite, STF tools be installed by either 
     65    using pre-compiled packages, or by building a local repository of STF
     66    tools.  NFS accesses can lead to failures in the test suite due 
     67    to mountd/lockd behavior.
     68 
     69 	# pkgrm SUNWstc-stf SUNWstc-checkenv
     70 	# pkgadd -d <package-location> SUNWstc-stf
     71 	# pkgadd -d <package-location> SUNWstc-checkenv
     72 
     73 	where <package-location> refers to the path at which the
     74 	respective packages reside.
     75 
     76 	Checkenv packaging is only partially integrated with STF, and
     77 	the following symlink needs to be made
     78 
     79 		# cd /opt
     80 		# ln -s SUNWstc-checkenv checkenv 
     81 
     82 	OR the STF_CHECKENV_PATH variable needs to be set and exported
     83 	in the shell in which tests will be executed.
     84 
     85 
     86 b.  Get the SBD test suite
     87 
     88     One of two methods may be used for this: building and installing a
     89     local copy of the test suite package, or installing a precompiled
     90     package.
     91 
     92     1) Building a local copy
     93 
     94     This approach is highly recommended because precompiled dtrace
     95     scripts may not be compatible across different builds of Solaris.
     96     To build a local copy of the test suite, obtain the test suite
     97     source (using Source Code Management commands), add STF utilities to
     98     your PATH and invoke 'stf_build'.
     99 
    100     $ PATH=<path-to-STF>/bin/`uname -p`:$PATH; export PATH
    101 
    102     # <WS_ROOT> refers to the root of the STC workspace which contains
    103     # the source code of the sbd test suite.
    104     #
    105     $ cd <WS_ROOT>/usr/src/suites/security/sbd
    106     $ stf_build package
    107     $ su - root
    108     ...
    109     # pkgadd -d <WS_ROOT>/packages/`uname -p` SUNWstc-security-sbd
    110 
    111     Note: /usr/sfw/bin/cpp is used as the default C language
    112     preprocessor.  This behavior can be overridden by exporting the
    113     variable CPP.  If gcc is being used to compile the test suite, a
    114     compatible (i.e., GNU) version of cpp is required.  One such is
    115     distributed with gcc on Solaris and is usually found installed in
    116     /usr/sfw.
    117 
    118     2) Installing a precompiled package
    119 	
    120     # pkgrm SUNWstc-security-sbd
    121     # pkgadd -d <package-location> SUNWstc-security-sbd
    122 
    123     If <package-location> is an NFS-accessible location, then it is
    124     strongly recommended that the test system be rebooted before
    125     beginning test execution.  This is in order to eliminate the
    126     side-effects of NFS access (such as leftover open network ports).
    127 
    128 
    129 c.  Configure the test system to run the test suite
    130 
    131     (Assuming STF utilities are in the PATH)
    132 
    133     $ cd /opt/SUNWstc-security-sbd
    134     $ stf_configure
    135 
    136     STF may prompt for the system root password at this point.
    137 
    138 
    139 d.  Execute the tests
    140 
    141     (Assuming STF utilities are in the PATH)
    142 
    143     $ stf_execute
    144 
    145    The system will reboot automatically 10 minutes after stf_execute has
    146    completed.
    147 
    148 
    149 e. Examine the test results
    150 
    151    If tests were executed from /opt/SUNWstc-security-sbd, the results of
    152    test execution will, by default, be placed under the directory
    153    /var/tmp/SUNWstc-security-sbd/results.  It is possible to place the
    154    results under a different directory (for which, see the STF User's
    155    Guide).
    156 
    157    There will be an STF journal file, a log file from the SMF service
    158    'bindtrace' and a log file from the SMF service 'sbdmonitor' in the
    159    results directory.  To view test status, run:
    160 
    161    $ grep FAIL bindtrace*
    162    $ stf_filter journal*
    163 
    164    You may look at the journals and logs themselves to see detailed
    165    execution information and results.
    166 
    167 
    168 3.  TEST SUITE DESIGN NOTES
    169 
    170 As stated above, this test suite uses the STF harness, but operates in a
    171 manner slightly different from the way usual STF-based tests do.
    172 
    173 This suite has only one STF test case, which uses two distinct
    174 approaches to verify the functionality of the secured SMF profile,
    175 depending on whether the test is running in the global zone, or in a
    176 non-global zone.  The 'sbd_bindtrace' script, which only runs in the
    177 global zone, performs the verification of the application of the secure
    178 (SBD) profile by DTracing suspicious bind(3SOCKET) calls; the
    179 'sbd_netstat' script, which runs only in non-global zones, verifies the
    180 correct application of the secured (SBD) profile by checking against the
    181 output of netstat(1M).
    182 
    183 When the test runs in non-global zones, it acts in a standard STF-based
    184 way.  However, in global zone it operates differently in that the test
    185 is not actually executed when stf_execute runs, but rather during the
    186 booting process *after* stf_execute has completed.  This is what is done
    187 as part of the global-zone test, 'sbd_netlimited': anonymous trace is
    188 enabled, an SMF service named network/bindtrace is set up for examining
    189 DTrace data on the fly, an SMF service named network/sbdmonitor is set
    190 up for applying the secured SMF profile, the system rebooted, logs of
    191 the network/bindtrace service are collected and post-test cleanup
    192 performed.  10 minutes after the target test system has successfully
    193 booted, the actual test is done and the test journal file and services
    194 log files are placed in the test results directory.
    195 
    196 When this test suite is run in the global zone, the log of the SMF
    197 service named 'network/bindtrace' holds the actual test status, and the
    198 the STF journal file and the log of the SMF service 'network/sbdmonitor'
    199 contain useful debug information only.  There's no explicit PASS in the
    200 'network/bindtrace' log file.  The absence of the word "FAIL" from the
    201 'network/bindtrace' log is used to indicate a PASS in this scenario.
    202 Therefore, issuing the command "grep FAIL bindtrace*" demonstrates
    203 whether any unexpected network services were enabled in the hardened
    204 environment (i.e., whether the test has failed).
    205 
    206 When this suite is run in non-global zones, the STF journal contains a
    207 PASS/FAIL result as usual.  The absence of FAIL does not automatically
    208 imply that the test has passed; the result of the test must explicitly
    209 indicate PASS.
    210 
    211 
    212 4.  CONTACT US
    213 
    214 If you have questions or comments on the test suite, please send email
    215 to the STC_CONTACT alias mentioned in the STC.INFO file of this test
    216 suite.  Details on filing bugs against the test suite are also included
    217 in the STC.INFO file.
    218