
# SID   @(#) tools.txt 1.9 22/04/20 10:05:34

NAME

        O-Saft Tools - tools for  o-saft.pl


DESCRIPTION

        Description of tools around  o-saft.pl,  when, where and how to use.


SYNOPSIS

        o-saft [OPTIONS ..] [COMMANDS ..] target [target target ...]

        o-saft.pl [OPTIONS ..] [COMMANDS ..] target [target target ...]

        o-saft.pl [OPTIONS ..] [COMMANDS ..] target [target target ...] | CMD

        o-saft.tcl [OPTIONS ..] target [target target ...]

        o-saft-docker [OPTIONS ..] [COMMANDS ..] target [target target ...]

        env  QUERY_STRING="--cgi&OPTIONS&--cmd=CMD&--host=target" o-saft.cgi

        https://o-saft.pl/o-saft.cgi?--cgi&OPTIONS&--cmd=CMD&--host=target

        checkAllCiphers.pl

        INSTALL.sh

        contrib/install_openssl.sh

        contrib/install_perl_modules.pl

        contrib/gen_standalone.sh

        contrib/cipher_check.sh

        contrib/critic.sh

        where  [COMMANDS]  and  [OPTIONS]  are described in the corresponding
        documentation of the tool.


CONCEPTS

        The main tool, doing all the SSL/TLS related tests, is  o-saft.pl .
        All other tools described here are just wrappers around  o-saft.pl or
        tools for postprocessing output data of  o-saft.pl .

        These tools can be categorised as follows:

           category       tools            purpose
         #---------------+----------------+----------------------------------
          CLI             o-saft.pl       # it's me
          General Wrapper o-saft          # use o-saft.pl with prostprocessors
          GUI             o-saft.tcl      # use o-saft.pl from GUI
          CGI             o-saft.cgi      # use o-saft.pl from web server
          VM              o-saft-docker   # use o-saft.pl inside docker
          CLI             checkAllCiphers.pl    # simple quick cipher check
          Postprocess     contrib/*       # prostprocessor tools
          Advanced Tools  contrib/*       # use o-saft.pl in advanced modes
          Installation    INSTALL.sh      # simple installation tool
          Development     make            # functional testing
          Development     ....            # ... comming soon
         #---------------+----------------+----------------------------------

        For a description of  o-saft.pl  itself, please see:
          o-saft.pl --help

        All results printed by  o-saft.pl  are on STDOUT.  It does not create
        any files, even no intermediate/temporary files. So it is very simple
        to pipe  o-saft.pl  to other programs, they are called postprocessors
        here.

TOOLS

    CLI
        o-saft.pl  is the main tool, see  CONCEPTS  above.  It will be called
        by most other tools.

    General Wrapper
        o-saft  is the general wrapper.  It calls  o-saft.pl  with all passed
        arguments. All output from called  o-saft.pl  is piped to the command
        specified with the  -post=  option.
        The main purpose is to use postprocessors inside a VM like docker, or
        when called from a CGI script.

          o-saft [COMMANDS] [OPTIONS] target
          o-saft [COMMANDS] [OPTIONS] target -post='bunt.pl'
          o-saft-docker -id=osawp/o-saft -post='bunt.pl' ' [COMMANDS] [OPTIONS] target

    Simple check for ciphers

          checkAllCiphers.pl target

    GUI
        o-saft.tcl is the graphical user interface for  o-saft.pl .

          o-saft.tcl
          o-saft.tcl --docker
          o-saft-docker gui -id=osawp/o-saft

    CGI
        o-saft.cgi is a wrapper to start  o-saft.pl  via a webserver.
        The webpage to use  o-saft.pl  as CGI can be generated with:

          o-saft.pl --no-rc --no-warning --help=gen-cgi

        it can also be generated using:

          make o-saft.cgi.html

        this HTML form then calls o-saft.cgi with the appropriate parameters.

        o-saft.php  is a wrapper to start  o-saft.pl  via a webserver, usage
        is not recommended, see  WARNING in the file itself.

    VM
        o-saft-docker calls  o-saft.pl  in a docker image.

          o-saft-docker [COMMANDS] [OPTIONS] target
          o-saft-docker -id=osawp/o-saft.pl [COMMANDS] [OPTIONS] target

        See also docs/o-saft-docker.pdf .

    Postprocess
        Various postprocessors exist.  They all change the  content or format
        of o-saft.pl's output. See the files itself what they do.

          contrib/bunt.pl
          contrib/Cert-beautify.pl
          contrib/symbol.pl
          contrib/*.awk
          contrib/* TBD

        They are used in general like:

          o-saft.pl ... target | contrib/.....

        Formatting quick cipher check:

          checkAllCiphers.pl target > target-alerts.csv
          contrib/alertscript.pl --csv=target-alerts.csv

    Advanced Tools
        Check a target for ciphers with various methods:

          contrib/cipher_check.sh

        In legacy systems,  or when resources are limited,  a special version
        o-saft-standalone.pl  can be used.  It is a single Perl script, which
        contains most functionality. This script can be generated with:
        
          make o-saft-standalone.pl

    Installation
        INSTALL.sh  can be used to install anything in its own directory.  It
        can also be used to check and cleanup the installation.

          INSTALL.sh
          contrib/install_openssl.sh
          contrib/install_perl_modules.pl
          contrib/distribution_install.sh
          contrib/*_completion_o-saft
          contrib/zap_config.*

    Development

        Various, mainly functional, tests have been defined in Makefiles.
        Simply call  make  (without arguments) to get more informations.

        Other files for development are:
          o-saft-docker-dev
          t/.perlcriticrc
          contrib/critic.sh


CUSTOMISATION

        The tools can be customised with following files:

        * o-saft.pl
           .o-saft.pl
           o-saft-usr.pl

        * o-saft.tcl
           .o-saft.tcl
           o-saft-img.tcl

        * o-saft.cgi
           none, but see contrib/o-saft.php

        * o-saft-docker
           none, but see o-saft-docker-dev

        * SHELL TWEAKS
           contrib/bash_completion_o-saft
           contrib/fish_completion_o-saft
           contrib/tcsh_completion_o-saft


EXAMPLES

        As described in  CONCEPTS  above,  all results printed by  o-saft.pl
        are on STDOUT.

        The simplest and most common usage looks like:
          o-saft.pl       +check --header some.tld
          o-saft          +check --header some.tld

        Using postprocessors is done as usual:
          o-saft.pl       +check --header some.tld | contrib/bunt.pl
        which is the same as:
          o-saft          -post=bunt.pl +check --header some.tld

        Even if  o-saft.pl  runs in a container like docker,  its results can
        be postprocessed either in docker itself, like:
          o-saft -docker  -post=bunt.pl +check --header some.tld
          o-saft-docker   -post=bunt.pl +check --header some.tld
        or do it the traditional way with postprocessing on the calling host:
          o-saft -docker  +check --header some.tld | contrib/bunt.pl
          o-saft-docker   +check --header some.tld | contrib/bunt.pl

        The GUI  o-saft.tcl  can also be run in docker:
          o-saft -docker  -gui
          o-saft-docker   -gui
        or  o-saft.tcl  can use  o-saft.pl  in the container
          o-saft.tcl -docker


SEE ALSO

        * o-saft
        * o-saft.pl
        * o-saft.tcl
        * o-saft-docker
        * o-saft-docker-dev
        * Dockerfile
        * docker
        * INSTALL.sh


VERSION

        @(#) $VERSION

AUTHOR

        18. Jan. 2018 Achim Hoffmann


