NAME
    ncat - Network Config Audit Tool for IOS (and other) configs

SYNOPSIS
    ncat [OPTIONS] *config [config ...]*

DESCRIPTION
    ncat reads a rules file (default INSTALLPREFIX/etc/ncat.conf) and checks
    one or more config files specified on the command line against rules
    found in the rules file. Rules specify that a particular chunk of text
    is either required or forbidden. Once all rules have been checked, a
    report is output listing violations.

    There are some special features that apply if the file being checked is
    a CISCO IOS configuration. There are special rules (see below) that
    allow for parsing of per-interface and per-line configurations.

OPTIONS
    -r, --rules
            The "--rules" flag allows the specification of an alternate
            rules config file.

    -l, --limitrulesto
            The "--limitrulesto" allows the commandline specification of a
            regular expression to limit the rules that are checked. The name
            of the rule must match the regexp specified or the rule is
            skipped. You might try something like

              --limitrulesto=finger

            or

               --limitrulesto='finger\|syslog'

    -c, --limitclassto
            The "--limitclassto" allows the command line specification of a
            regular expression to limit the rules that are checked. The
            class of the rule must match the regexp specified or the rule is
            skipped. You might try something like

              --limitclassto=access
              --limitclassto=localrules
              --limitclassto=access,logging,aaa
              --limitclassto='access\|logging\|local.*'

            See the rules file for definition of rule classes. By default,
            only rules matching the class "default" are checked. "all" is
            synonym for ".*". You can give a "normal" comma separated list
            of classes that you want to check because "," is treated as a
            synonym for the regular expression or ("|").

    -p, --onlypass
            The "--onlypass" flag indicates flag indicates that only passing
            rules should be reported. It may not be combined with
            "--onlyfail"

    -f, --onlyfail
            The "--onlyfail" flag indicates flag indicates that only failing
            rules should be reported. It may not be combined with
            "--onlypass"

    -V, --version
            The "--version" option displays the current program version.

NCAT CONFIG FILE SYNTAX
            The ncat config file or "rules file"
            (ncat.conf/ncat.conf.MASTER) contains four different types of
            information. "Rules" define rules to be checked, "ConfigClass"
            specifies groups of optional rules, "ConfigLocal" specified
            local configuration value, and "ConfigGlobal" specifies global
            configuration options.

  Rules Syntax

            The rules file contains a series of records defining rules to be
            checked. Each Record begins with "RuleName:..." field and
            continues until the next "RuleName:.." field or end-of-file.
            Each record consists of a number of named fields. The fields
            begin with an alphanumeric keyword followed by a colon and then
            a value. Values may be continued across multiple lines by ending
            the line with a backslash (\). The following is the list of
            valid field names and permissible values.

            " RuleName:unique rule name RuleClass:class[,class...]
            RuleVersion:regular-expression
            RuleContext:(Global,IOSInterface,IOSLine)
            RuleType:(Required|Forbidden) RuleMatch:regular-expression
            [RuleInstance:regular-expression] [RuleImportance:number]
            [RuleDescription:Text...] [RuleFix:Text...] "

            where

              * RuleName specifies a unique name for the rule.  

              * RuleClass specifies a class or classes to which the rule belongs.  Every rule
                is a member of the class "default" unless otherwise specified.   A rule can
                be a member of multiple classes.  The list of member classes is a comma separated list.   

              * RuleVersion specifies a pattern that indicates which config file
                version a rules applies to.

                For example, if RuleVersion is "1[12].*" then the rule will apply
                to all IOS 11 and 12 configurations.

              * RuleContext lists the context of the rule.  Possible values are

                - Global - The rule must match anywhere in the config.

                - IOSInterface - The rule must match in the context of an IOS interface definition

                - IOSLine - The rule must match in the context of an IOS line definition.

              * RuleType determines if the match should be required or forbidden

              * RuleMatch specifies a regular expression to match within the given context.

              * RuleInstance defines the instance of the rule that must match, for instance
                "Serial0/0","Vlan\d+","vty", or "aux".
 
              * RuleImportance specifies a number indicating the relative importance
                of a rule.  The higher the number, the more important it is.
                                                                                    
              * RuleDescription contains a description/justification of the rule.

              * RuleFix contains text to be applied to make the config "correct"

              * regular-expression is a Perl regular expression

              * rules and values enclosed in "[...]" are optional.

  Rules Example

            Here is an example of a rules file

                RuleName:enable secret
                RuleClass:default,access
                RuleVersion:version 1[12]\.*
                RuleContext:Global
                RuleType:Required
                RuleMatch:enable secret \d \S+
                RuleImportance:3
                RuleDescription:Require enable secret.\
                See rules.html#enablesecret for details.
                RuleFix:enable secret EDIT-BY-HAND

                RuleName:Apply VTY ACL
                RuleClass:default,access
                RuleVersion:version 1[12]\.*
                RuleContext:IOSLine
                RuleInstance:vty
                RuleType:Required
                RuleMatch: access-class 92 in
                RuleImportance:2
                RuleDescription:Require ACL 92 to be applied to VTYs\
                See rules.html#ApplyVTYACL for details.
                RuleFix:\
                line vty 0 4\
                access-class 92 in\
                exit

                RuleName:no ip directed broadcast
                RuleClass:default,routing
                RuleVersion:version 11\.*
                RuleContext:IOSInterface
                RuleInstance:.*
                RuleType:Required
                RuleMatch:no ip directed-broadcast
                RuleImportance:2
                RuleDescription:Disallow directed broadcasts by default.\
                See rules.html#noipdirectedbroadcast for details.
                RuleFix:\
                int INSTANCE\
                no ip directed-broadcast\
                exit

            In the above example, the rules have the following meaning

                Rule 1 requires a global (anywhere in the config) rule matching
                "enable secret" followed by a non-blank string.

                Rule 2 requires that all vty lines have "access-class 92 in". It lists the commands
                that need to be entered to add the rule.

                Rule 3 requires that all Vlan interfaces have "no ip directed
                broadcast" set and lists the commands needed to set it.  This rule applies 
                only to IOS version 11.

  Global Config Options Syntax and Example

            In addition, there are several global rules file options:

            " ConfigVersion:1.3 ConfigOrganization:My Organization
            ConfigDocumentType:Security Audit Rules ConfigPlatforms:Cisco
            IOS Routers ConfigFeedbackTo:me@my.org ConfigGuide:guide.pdf
            ConfigGuidePath:/usr/doc /usr/local/doc ~/doc ./doc
            ConfigRulesAlias:my-special-audit.html ConfigIntroText:Text
            (html)... ConfigTrailingText:Text (html)...
            ConfigOutputGroups:value [value ...]
            ConfigLineSkip:pattern[:pattern...] "

            where

              * ConfigVersion defines the version number of the rules

              * ConfigOrganziation describes the auditing organization

              * ConfigDocumentType describes the type of document (e.g. "rules", "benchmark"...)

              * ConfigPlatforms describes the type of systems being audited ("production routers...")

              * ConfigFeedback lists contact info (e.g "me@some.place.org")

              * ConfigGuide defines the name of a "configuration guide" to be symlinked into
                the directory where the audits are run.  This is useful because it allows the
                description portion of individual rules to make hyperlinks to a document
                containing a more complete justification for the rule.

              * ConfigGuidePath defines the path to search for the guide.                                                                              

              * ConfigLineSkip defines a list of one or more patterns that causes
                checking to be skipped.  The default is "^ shutdown".

              * ConfigRulesAlias defines an alias for the rules.html file.  A symlink
                from this name to "rules.html" will be created.    

              * ConfigIntroText defines text (HTML) to be inserted before the list
                of individual rules.

              * ConfigTrailingText defines text (HTML) to be inserted after the list
                of individual rules.

              * ConfigOutputGroups specifies groups (such as datacenter names) by which
                output is grouped in index.html.  The groups are space separated and
                are regular expressions.  The regular expressions are matched against
                the names of the configurations being checked.                                                                                

            These global rules file options are mostly used during report
            generation.

  Local Configuration Options Syntax

            ConfigLocal options allow the specification simple text
            substitution macros, i.e. a string that will be replaced with a
            given value. The syntax is

            In addition, there are several global rules file options:

            " ConfigLocalName:KEY ConfigLocalValue:VALUE
            [ConfigLocalPrereqs:CLASS_NAME[,CLASS_NAME...]]
            [ConfigLocalDescription:COMMENT] "

            where

                * KEY is a keyword (e.g. "EternalInterface") that will
                  be replaced by VALUE in the resulting config file.

                * VALUE is a value ("Ethernet0") that will be substituted.

                * CLASS_NAME is a list of one or more classes to which use the option

                * COMMENT is a description of the option

                * comments may be continued across several lines by ending
                  each line to be continued with "\".                                           

  Local Configuration Options Example

            Here is an example of a local configuration option:

                ConfigLocalName:Local_Timezone
                ConfigLocalValue:GMT
                ConfigLocalClassPrereq:localtime 
                ConfigLocalDescription:\
                 Specify the name of the timezone to be used.  For example, GMT,EST, etc.

            In the above example, the fields have the following meaning

                * ConfigLocalName specifies "Local_Timezone" as the name of the local option

                * ConfigLocalValue specifies the value "GMT"

                * ConfigLocalClassPrereq says that this option only applies if the class
                  "localtime" is selected (this sets the "local" timezone to "GMT")

                * ConfigLocalDescription specifies text to describe the option

  Optional Rule Class Syntax

            The master file may also contain ConfigClass: rules, which
            describe groups of configuration options. ncat_config will
            prompt for inclusion/exclusion of classes ConfigClass: entries.
            They are of the form:

            " ConfigClass:CLASS_NAME
            [ConfigClassConflictsWith:CLASS_NAME[,CLASS_NAME...]]
            [ConfigClassPrereq:CLASS_NAME[,CLASS_NAME...]]
            [ConfigClassDescription:COMMENT] . . . "

            where

                * CLASS_NAME is the name of the rule class.  It should correspond to
                  one rules having the same value for RuleClass.

                * COMMENT is a description of the option

                * Comments may be continued across several lines by ending
                  each line to be continued with "\".

                * ConfigClassClassPrereq: is a comma-separated list of classes
                  that are prerequisites of the class being defined
 
               * ConfigClassConflictsWith: is a comma-separated list of classes
                 that are incompatible with this class.

  Optional Rule Class Example

            Here is an example of a rule class:

                ConfigClass:2nd_External_Interface
                ConfigClassPrereq:exterior_router
                ConfigClassDescription:\
                    Define a second external interface.

            In this example

                * ConfigClass specified the name of the config class as "2nd_External_Interface"

                * ConfigClassPrereq says that this rule only applies of the ruleclass
                  exterior_router is specified.

                * ConfigClassDescription describes the purpose of the second ruleclass.                                                                                 

RETURN VALUE
            0 - success >0 - some error occurred

FILES
                    INSTALLPREFIX/etc/ncat.conf - The rules file.

                    a config file - At least one config file on the command
                    line (required)

CAVEATS
            Rules themselves may not contain colon (":") characters.

BUGS
            Yes.

AUTHOR
            George M. Jones <gmj@users.sourceforge.net>

CREDIT WHERE CREDIT IS DUE
            John Stewart has helped with the code in numerous ways. It's
            much cleaner, and the install process is better thanks to his
            efforts.

            Rob Thomas collected and wrote an excellent baseline IOS 12
            secure configuration which is used as the basis for the example
            ncat.conf. The first version of that config provided the "ah ha"
            insight that "config checking can be simple" and thus the
            impetus for the creation of this script.

            Eric Brandwine has written a much more elegant and complete
            config checker. Some of the features of this script are inspired
            by his work. In particular, the size and complexity of that
            program inspired the (at least initial) simplicity of this one.

            Joshua Wright did the port for ActiveState on Windows.

