Copyright (C) 2022-2026 James S. Seymour (jseymour@LinxNet.com)
See Copyright.txt for license terms.

 atre-parser

 Parse and display individual attacks from standard input using a regular
 expression engine.

 Usage:

   atre-parser [-b|--bail-on-mismatch] [-c|--config <config file>]
               [-d|--debug <level>] [-f|--facility <facility>] [-g|--grep]
               [-n|--line-number] [-r|--regression-test] [-t|--tag <tag>]
               [-u|--usage [subject]] [-v|--verbose <level>] [-V|--version]
               [file]

     -b|--bail-on-mismatch

         Bail on mismatch (with -r only)

     -c|--config <config file>

         Specify non-default regexp expression config file

         Default is /etc/sshguard/attack_parser_re.conf for POSIX regexp
         builds, /etc/sshguard/attack_parser_re.pcre for PCRE builds.

     -d|--debug <level>

         emit debugging statements to stderr

     -f|--facility <facility>

         Log to syslog facility (-r disables)

         Valid facility names are system-specific, but examples are
         (Linux and most Unixen?): auth, authpriv, cron, daemon, ftp,
         lpr, mail, news, syslog, user, uucp, and local0 to local7

         If -f not specified, messages otherwise written to a logfile
         instead will be sent to stderr, preceded with the log level
         (e.g.: "log_info:")

         Specifying an input file disables syslogging, regardless of
         this option.

     -g|--grep

         Grep-like behavior: Emits log file lines that match any regular
         expressions in the default or specified RE config file.

         Useful for developing or debugging new expressions.

     -n|--line-number

         With -g|--grep only - Prefixes emitted lines with the 1-based config
         file RE line that matched it.

     -r|--regression-test

         Regression-testing mode

     -t|--tag <tag>

         syslog logging tag (with -l only, default is "atre-parser")
         (Aka: syslog "ident")

     -u|--usage [subject]

        Besides command-line usage, help is available for:

            services - list the known service names

     -v|--verbose <level>

         Increase logging verbosity

     -V|--version

         Print version string and exit

     [file] - input log file (otherwise stdin)

 Notes:

    SIGUSR1 sent to the running process will cause it to reload its
    regexp configuration file if it has a modification time newer than
    when it was last read.  E.g.:

        $ pkill -USR1 atre-parser

    One or more "reload" messages will be logged, depending upon logging
    verbosity level.

    SIGHUP, SIGTERM, and SIGINT terminate execution

    It's okay to specify POSIX regexp config files with PCRE builds,
    but not vice-versa.

    Fatal errors result in immediate program termination, with error
    messages emitted to stderr (and possibly syslog), and a non-zero
    exit value.

    "-t <tag>" is Linux "logger" utility semantics.

 Examples:

    Used in an sshguard PARSER pipeline:

        atre-parser -f auth -t sshguard

    Using an alternate regexp config file and increased logging verbosity:

        atre-parser -c path_to_config_file -f auth -t sshguard -v1

    Input is expected to be logfile lines.  Output, to stdout, is in
    the form:

        <service code> <IP address> <IP address type> <dangerousness>

    Specifying debug mode changes the output to stdout to be more
    verbose. (Incompatible with using in an sshguard stream.)

    Checking a log file with an experimental regexp in a file named
    "test.conf", with debugging enabled:

        atre-parser -d1 -v1 -c test.conf log_file

    Regression-testing:

        atre-parser -b -r -c examples/attack_parser_re.conf <test/mytests.txt

    The input file must be in a particular format.  See the file,
    noted above.  For lines that fail, specify debug mode to get
    result/expected output.

 Bugs:

     None known at this time.