#!/usr/bin/perl
#
# pod2man outputpbnj.man.1 | gzip -c > outputpbnj.1p.gz && gunzip outputpbnj.1p.gz
#
# Copyright (C) 2005-2006 Joshua D. Abraham (jabra@ccs.neu.edu)
#
# This manpage is released under the terms of the GNU General Public
# License (GPL), which is distributed with this software in the file
# "COPYING". The GPL specifies the terms under which users may copy
# and use this software.
#

=pod

=begin man

=head1 NAME
 
 OutputPBNJ - a program to query a PBNJ 2.0 database.

=head1 SYNOPSIS

 outputpbnj [Query Options] [Database Options] [General Options]

=cut

=begin man

=head1 DESCRIPTION

 OutputPBNJ uses a query yaml config file to execute queries against 
 the PBNJ 2.0 database. OutputPBNJ returns the result in various 
 output types (csv, tab and html).

 Apart of PBNJ 2.0 suite of tools to monitor changes on a network.
 
=head1 OPTIONS 

 Usage: outputpbnj [Query Options] [Config Options] [General Options]
 Query Options:
   -q  --query <name>     Perform sql query
   -t  --type <type>      Output Type [csv,tab,html]
   -f  --file <file>      Store the result in file otherwise stdout
       --both             Print results and store them in a file
       --dir <dir>        Store the result in this directory [def .]

   -l  --lookup <name>    Lookup description based on name
       --list             List of names and descriptions
   -n  --name             Lookup all the names
   -d  --desc             Lookup all the descriptions
   -s  --sql              Lookup all the sql queries

 Config Options:
        --qconfig <file>  Config of sql queries [def query.yaml]
        --dbconfig <file> Config for accessing database [def config.yaml]        
        --dbdir <dir>     Directory for Config file [def .]
        
        --data <file>     SQLite Database override [def data.dbl]

 General Options:
       --test <level>     Test Level
       --debug <level>    Verbose information
   -v  --version          Display version
   -h  --help             Display this information

 Send Comments to Joshua D. Abraham ( jabra@ccs.neu.edu )

=end man

=cut


__END__

=begin man
 
=head1 THINGS TO NOTE

 * OutputPBNJ requires root privileges to query a database that is
 owned by root. Thus, if you are scanning with ScanPBNJ you will need
 to run OutputPBNJ with root privileges to access the database.

 * If there are configs in the current directory, they are used
 instead of those in the user's config directory. 

=head1 Query Options

=head2  -q  --query <name>  Perform sql query

 This option is where the actual query is specified. Therefore, once
 you know the query you wish to use simply pass it as an argument to
 this option.

=head2  -t  --type <type>  Output Type [csv,tab,html]
 
 This options is used to specify which output format you wish to use.
 For example, if you would like to have output that you can show
 someone else the CSV format is useful because you can simply pull the
 file into OpenOffice Calc or Excel as it is a comma delimited file.

=head2  -f  --file <file>      

 This option is used to specifiy output to a file rather than standard
 output. This is useful if you want to grow the results of queries as
 the result will be added onto the end of the file. 

=head2  --both             

 This option is used when you want both output to standard output, as
 well as to a file. This will save the result to a file if you are
 having the result sent to the screen or piped to your email which you
 may or may not disregard. 

=head2  --dir <dir>  Store the result in this directory [default .]

 This option is used with the writing to a file. This option will
 store the file in a alternative directory than the current directory. 

=head2  -l  --lookup <name>     
 
 This options is used to lookup the description of a specific query.
 This will return the description of the query.  

=head2  --list  List of names and descriptions

 This option is used to return a list of all the queries with the
 names and descriptions. This is very useful when you are starting to
 use OutputPBNJ or using a new query config.

=head2  -n  --name            

 This option is used to print the all the query names. 
 
=head2  -d  --desc            

 This option is used to print the all the query descriptions. This is 
 useful to find out all the queries do.
 
=head2  -s  --sql            

 This option is used to print the all the queries. This is useful for 
 developing new queries based on other queries.
 
=head1 Config Options
        
=head2  --qconfig <file>  
 
 Config of sql queries [default query.yaml]
       
 This option is used to specify an alternative query.yaml file.
 
=head2  --dbconfig <file> 

 Config for accessing results database [default config.yaml]        

 This option is used to specify an alternative config.yaml file.
 
=head2  --dbdir <dir>  
 
 Directory for Config file [default .]
 
 This option is used to specify an alternative directory for the
 config.yaml file.
  

=head1 GENERAL OPTIONS

=head2  --test <level>

 Increases the Test level, causing OutputPBNJ to print testing
 information about the Query. Using the Test level is mostly only
 using for testing. This will also print the debugging information so
 it can get rather lengthy. The greater the Test level the more output
 will be given.

 This option is also used for reporting bugs. All bug reports should
 be submitted using --test 1 and an additional report may be needed
 depending on the issue

=head2  --debug <level>

 Increases the Debug level, causing OutputPBNJ to print more
 information about the query in progress. The higher the debug leve
 the more output the user will receive.


=head2  -v --version  
     
 Prints the OutputPBNJ version number and exits.
     
=head2  -h --help  Display this information
     
 Prints a help screen with the command flags.
 Running OutputPBNJ without any arguments does the same thing.
 
=head1 FILES

 PBNJ's data files are stored in ScanPBNJ and OutputPBNJ. When either
 of these programs is run the configuration files will be generated
 for the user if they do not already exists and placed in the
 $HOME/.pbnj-2.0 directory. Again, if there is a configuration file in
 the current directory it is used instead of the version in the
 configuration directory.

 $HOME/.pbnj-2.0/config.yaml - holds settings for connecting to the
 database which store the information from PBNJ scans.

 $HOME/.pbnj-2.0/query.yaml - lists all queries that can be used to
 retrieve information from the database. Also, includes the name and
 description for each query. This is only generated when you executed
 OutputPBNJ.

 For Windows, the pbnj-2.0 config directory is in the APPDATA
 directory, which contains both config.yaml and query.yaml. Depending
 on your environment, the APPDATA directory may be a different location
 from other environments. Therefore, when the configs are executed for
 the first time they will display the path where the configs were 
 generated.

=head1 QUERY

 The query.yaml file contains the list of various names, descriptions
 and sql queries that can be executed by OutputPBNJ.

 Here is one example:

 - name: vulnssh
   desc: list all of the services that have old ssh running
   sql: |-
    select S.updated_on,M.ip,S.service,S.port,S.version from services
    as S, machines as M where service='ssh' and state='up' and
    version!='4.1p1'

 This examples shows how the name, description and sql are layed out in
 the yaml format. Therefore, we know the name of the query is vulnssh
 and it's purpose is to list SSH servers which are not running
 a version 4.1p1. It is very easy to create another script that would
 check for the latest version of a given service and therefore the
 user would be able to verify that that particular service needed to
 be updated on the machine that was scanned.

=head1 FEATURE REQUESTS

 Any feature requests should be reported to the online
 feature-request-tracking system available on the web at: 
 http://sourceforge.net/tracker/?func=add&group_id=149390&atid=774489
 Before requesting a feature, please check to see if the features has
 already been requested.

=head1 BUG REPORTS

 Any bugs found should be reported to the online bug-tracking system 
 available on the web at :  
 http://sourceforge.net/tracker/?func=add&group_id=149390&atid=774488.  
 Before reporting bugs, please check to see if the bug has already been
 reported.

 When reporting PBNJ bugs, it is important to include a reliable way
 to reproduce the bug, version number of PBNJ and Nmap, OS
 name and version, and any relevant hardware specs. And of course,
 patches to rectify the bug are even better.

=head1 SUPPORTED DATABASES

 The following databases are supported:

 * SQLite [default]
 * MySQL
 * Postgres
 * CSV

=head1 DATABASE SCHEMA

 The following is the SQLite version of the database schema:
 
 CREATE TABLE machines (
            mid INTEGER PRIMARY KEY AUTOINCREMENT,
            ip TEXT,
            host TEXT,
            localh INTEGER,
            os TEXT,
            machine_created TEXT,
            created_on TEXT);
 CREATE TABLE services (
            mid INTEGER,
            service TEXT,
            state TEXT,
            port INTEGER,
            protocol TEXT,
            version TEXT,
            banner TEXT,
            machine_updated TEXT,
            updated_on TEXT);

=head1 SEE ALSO

 scanpbnj(1), genlist(1), nmap(1)

=head1 AUTHORS

 Joshua D. Abraham ( jabra@ccs.neu.edu )

=head1 LEGAL NOTICES

 This program is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 General Public License for more details at
 http://www.gnu.org/copyleft/gpl.html, or in the COPYING file included
 with PBNJ.

 It should also be noted that PBNJ has occasionally been known to crash
 poorly written applications, TCP/IP stacks, and even operating systems.
 While this is extremely rare, it is important to keep in mind.  PBNJ
 should never be run against mission critical systems unless you are
 prepared to suffer downtime. We acknowledge here that PBNJ may crash
 your systems or networks and we disclaim all liability for any damage
 or problems PBNJ could cause.


=end man
