Meta-security
=============

This layer provides security tools, hardening tools for Linux kernels
and libraries for implementing security mechanisms.

Dependencies
============

This layer depends on:

  URI: git://git.openembedded.org/openembedded-core
  branch: master
  revision: HEAD
  prio: default

  URI: git://git.openembedded.org/meta-openembedded/meta-oe
  branch: master
  revision: HEAD
  prio: default

  URI: git://git.openembedded.org/meta-openembedded/meta-perl
  branch: master
  revision: HEAD
  prio: default

  URI: git://git.openembedded.org/meta-openembedded/meta-networking
  branch: master
  revision: HEAD
  prio: default

Adding the security layer to your build
========================================

In order to use this layer, you need to make the build system aware of
it.

Assuming the security layer exists at the top-level of your
yocto build tree, you can add it to the build system by adding the
location of the security layer to bblayers.conf, along with any
other layers needed. e.g.:

  BBLAYERS ?= " \
    /path/to/oe-core/meta \
    /path/to/meta-openembedded/meta-oe \
    /path/to/meta-openembedded/meta-perl \
    /path/to/meta-openembedded/meta-python \
    /path/to/meta-openembedded/meta-networking \
    /path/to/layer/meta-security \

Contents and Help
=================

In this section the contents of the layer is listed, along with a short
help for each package.

         == bastille ==

        Bastille  is  a  system hardening / lockdown program which enhances the
        security of a Unix host.  It configures daemons, system settings and
        firewalls to be more secure.  It can shut off unneeded services
        like rcp and rlogin, and helps create "chroot jails" that help limit the
        vulnerability of common Internet services like Web services and DNS.

        usage : The functionality of Bastille which is available is
                restricted to a purely informational one. The command:
                bastille -c --os Yocto
                will cause a series of menus containing security questions
                about the system to be displayed to the user. For each
                question, a default response, specified in the configuration
                file which is installed with Bastille, will be selected.
                The user may select an alternate response. When the user
                has completed the sequence of menus Bastille saves the
                responses to the configuration file.

                The command:
                bastille -l lists the configuration files that Bastille
                is able to locate.

                The other functionality which Bastille is intended to provide
                is actually unavailable. This is not due to errors in poky
                installation or configuration of the application. The Bastille
                distribution is no longer supported. Significant modifications
                would be required to make it possible to make use of the
                functionality which is currently unavailable.


        Additional information about Bastille can be found in the package
        README file and other documentation.

        Alternatives to Bastille include buck-security and checksecurity,
        described elsewhere in this file.


        == redhat-security ==

        Sometimes you want to check different aspects of a distribution for security problems.
        This can be anything from file permissions to correctness of code. This is a collection of those tools.
        Depending on what information the tool has to access, it may need to be run as root.

        - rpm-chksec.sh : This will take an rpm name as input and verify each ELF file to see if its compiled with the intended flags
                          to most effectively use PIE and RELRO. Green is good, Orange could use work but is acceptable, and Red needs fixing.
                          It has a mode --all that is the equivalent of using rpm -qa and feeding the packages to it.
                          In this mode it will only give a summary result for the package. To find which files don't comply,
                          re-run using just the package name.

		!!! WARNING !!! - in order to use this script you need to add to your conf/local.conf file the following lines:
						IMAGE_ROOTFS_EXTRA_SPACE = ""  - specifying the extra space of the image
						IMAGE_FEATURES += "package management" - for the correct output of rpm -qa

        - find-nodrop-groups.sh : This will scan a whole file system to see if a program makes calls to change UID
                                  and GID without also calling setgroups or initgroups.

        - rpm-drop-groups.sh : Same as above, but takes an rpm name instead.

        - find-chroot.sh : This script scans the whole file system looking for ELF files that calls chroot(2) that also do not include a call to chdir.
                           Programs that fail to do this do not have the cwd inside the chroot. This means the app can escape the protection that was intended.

        - find-chroot-py.sh : This test is like the one above except it examines python scripts for the same problem.

        - find-execstack.sh : This program scans the whole file system for ELF programs that have marked the stack as being executable.
                              This means that if the program has another vulnerablity such as stack buffer overflow,
                              any code the attacker places there is executable. Any program found must be fixed.

        - find-hidden-exec.sh : This program scans the whole file system looking for excutables that are hidden.
                                Anything found must be investigated since its highly unusual for executables to be hidden.

        - find-sh4errors.sh : This program scans the whole file system looking for shell scripts.
                              It then does a sh -n on the script which causes bash to parse the file to see if there are any mistakes.

        - selinux-check-devices.sh : This script checks the /dev directory to see if there are any devices that are not correctly labeled.
                                     Anything found by this test should be reported so that selinux policy can be fixed.
                                     This test is very hardware specific, so to be effective a lot of people with different hardware
                                     should run this test each upstream kernel version release.

        - selinux-ls-unconfined.sh :  This script scans the running processes and looks for anything labeled with initrc_t or inetd.
                                      These both mean that there are daemons that do not have policy and are therefore running unconfined.
                                      These should be reported as SE Linux policy problems. Because it checks currently running daemons,
                                      the more you have running, the better the test is.

        - find-sh4tmp.sh : This script scans the whole filesystem to check if shell scripts are using well known tmp file names
                           instead of obscure ones created by something like mktemp.

        - find-elf4tmp.sh : This script scans the whole file system for ELF files using /tmp. When it finds this,
                            it also looks to see if any of the known good random name generator functions is called by looking
                            at the symbol table. If not, it will output the string.

        - lib-bin-check.sh : This will check all installed library packages to see if an application is also part of the package.
                             The relationship to security is that the SHA256 hash check will fail if a 32 bit version overwrites it.
                             Also, the less binaries on a system, the more secure it is by virtue of removing the chance for an exploitable bug.


                usage : simply invoke the script name in the terminal.


        == pax-utils ==

		( This package can be found in oe-core )

        pax-utils is a small set of various PaX aware and related utilities for
        ELF binaries.

        - scanelf : With this application you can print out information specific to the ELF structure of a binary.
                    For more help please consult the man pages or the readme file.

        - pspax : is a user-space utility that scans the proc directory and list
                  ELF types, as well as their respective PaX flags and filenames and
                  attributes. Depending on build options, it may additionaly display the
                  process running set of capabilities.

        - scanmacho : is a user-space utility to quickly scan given
                      Mach-Os, directories, or common system paths for different information. This
                      may include Mach-O types, their install_names, etc.

        - dumpelf : is a user-space utility to dump all of the internal
                    ELF structures into the equivalent C structures for fun debugging and/or
                    reference purposes.


                usage : simply invoke the script name in the terminal.


        == buck-security ==

        Buck-Security is a security scanner for Debian and Ubuntu Linux. It runs a couple of important checks and helps you to harden your Linux
        system. This enables you to quickly overview the security status of your Linux system.

                usage :	!!! before starting to use this tool please run the following command: !!!

						export GPG_TTY=`tty`

						This command is needed for the usage of the comand --make-checksum, which creates
						a checksum for the files in the system.

						switch to directory /usr/local/buck-security.
                        before running the script, you should check the activated checks in conf/buck-security.conf file.
                        after altering the changes, save the file and simply run :

                        ./buck-security

                        you can choose between different outputs : 1, 2(default) or 3.

                        More detailed usage can be found typing ./buck-security --help


        == libseccomp ==

        The libseccomp library provides and easy to use, platform independent, interface to the Linux Kernel's syscall filtering mechanism: seccomp.
        The libseccomp API is designed to abstract away the underlying BPF based syscall filter language and present a more conventional
        function-call based filtering interface that should be familiar to, and easily adopted by application developers.

                usage : More detailed usage can be found in the man pages and README file of the package.


        == checksecurity ==

        checksecurity is a simple package which will scan your system for several simple security holes.
        It uses a simple collection of plugins, all of which are shell scripts which are configured by environmental variables.


                usage : To start checksecurity simply write in the terminal :

                        checksecurity

        More detailed usage can be found in the man pages and README file of the package.


        == nikto ==

        Nikto is an Open Source (GPL) web server scanner which performs comprehensive tests against web servers for multiple items,
        including over 6500 potentially dangerous files/CGIs, checks for outdated versions of over 1250 servers, and version specific
        problems on over 270 servers. It also checks for server configuration items such as the presence of multiple index files,
        HTTP server options, and will attempt to identify installed web servers and software.

                usage : To start nikto simply write in the terminal :

                        nikto

        More detailed usage can be found in the man pages and README file of the package.


        == nmap ==

        Nmap ("Network Mapper") is a free and open source (license) utility for network discovery and security auditing.
        Many systems and network administrators also find it useful for tasks such as network inventory,
        managing service upgrade schedules, and monitoring host or service uptime.

                usage : To start nikto simply write in the terminal :

                        nmap

        More detailed usage can be found in the man pages and README file of the package.

Maintenance
-----------

Send pull requests, patches, comments or questions to yocto@yoctoproject.org

When sending single patches, please using something like:
'git send-email -1 --to yocto@yoctoproject.org --subject-prefix=meta-security][PATCH'

Maintainers:    Saul Wold <sgw@linux.intel.com>
                Armin Kuster <akuster@mvista.com>


License
=======

All metadata is MIT licensed unless otherwise stated. Source code included
in tree for individual recipes is under the LICENSE stated in each recipe
(.bb file) unless otherwise stated.