Provided by: authprogs_0.7.5-1_all bug

NAME

       authprogs - SSH command authenticator

SYNOPSIS

       authprogs --run [options]

       authprogs --install_key [options]

       authprogs --dump_config [options]

       authprogs --help

DESCRIPTION

       authprogs  is  an SSH command authenticator. It is invoked on an ssh server and decides if
       the command requested by the ssh client should be run or rejected based on  logic  in  the
       authprogs configuration file.

       Passwordless  SSH  using  ssh  identities  or  pubkeys  can  enable all sorts of wonderful
       automation, for example running unattended batch jobs, slurping down backups,  or  pushing
       out code. Unfortunately a key, once trusted, is allowed by default to run anything on that
       system, not just the small set of commands you actually need. If the key  is  compromised,
       you  are  at  risk  of  a  security breach. This could be catastrophic, for example if the
       access is to the root account.

       Authprogs is run on the  SSH  server  and  compares  the  requested  command  against  the
       authprogs  configuration  file/files. This enables authprogs to make intelligent decisions
       based on things such as the command itself, the SSH key that was used, the client IP,  and
       such.

       authprogs is enabled by using the command= option in the authorized_keys file.

KEY INSTALLATION

       You  can  install  your ssh identities/pubkeys manually, or allow authprogs to do the work
       for you.

MANUAL KEY INSTALLATION

       You need to set up your ~/.ssh/authorized_keys file to force invocation of  authprogs  for
       the key or keys you wish to protect.

       A line of an unrestricted authorized_key entry might look like this:

           ssh-rsa AAAAxxxxx...xxxxx user@example.com

       When setting up this key to use authprogs, you add a command= option to the very beginning
       of that line that points to the location where authprogs lives. For example  if  authprogs
       is in /usr/bin/authprogs, you would use this:

           command="/usr/bin/authprogs --run" ssh-rsa AAAAxxxxx...xxxxx user@example.com

       You must include --run to let authprogs know it is running in SSH command mode.

       Authprogs has other command line options you may wish to include as well, for example

           command="/usr/bin/authprogs --keyname=backups --run" ssh-rsa AAAA...xxxxx user@example.com

       Lastly,  if  you  wish,  ssh offers a number of other helpful restrictions you may wish to
       include that are separate from authprogs. These can be appended right  after  (or  before)
       the command="" section if you wish.

           command="/usr/bin/authprogs --run",no-port-forwarding,no-pty ssh-rsa AAAA...xxxxx user@example.com

       See  the sshd(8) man page for more information about allowed authorized_keys configuration
       options.

AUTOMATED KEY INSTALLATION

       Authprogs   is   capable   of   adding   your   key   to   your    authorized_keys    file
       (~/.ssh/authorized_keys by default) programmatically. It also disables ssh port forwarding
       by default for this key (a sensible default for most batch jobs.)

       authprogs will refuse to install a key that is  already  present  in  the  authorized_keys
       file.

       For example the following

           authprogs --install_key /path/to/backups_key.pub --keyname=backups

       would cause the following line to be added to your ~/.ssh/authorized_keys file:

           command="/usr/bin/authprogs --keyname backups --run",no-port-forwarding ssh-rsa AAAA...xxxxx user@example.com

RUN MODE OPTIONS

       Authprogs  can run in several modes, depending on which of these command line switches you
       provide.

       --run  Act in run mode, as from an authorized_keys file.

       --install_key filename
              Install the key contained in the named file into your authorized_keys file.

       --dump_config
              Dump the configuration in a python-style view. Helpful only for debugging.

       --silent
              Do not inform the user if their command has been rejected. Default is to  let  them
              know it was rejected to prevent confusion.

       --help Show help information

OTHER OPTIONS

       The following options may apply to multiple run modes, as appropriate.

       --keyname key_name
              This  option ´names´ the key, for help in crafting your rules. Since an account may
              have multiple keys allowed, this helps us differentiate which one was  used  so  we
              can make sensible choices.

              In  run mode, this specifies which name is used when matching in the configuration,
              e.g.

             command="/usr/bin/authprogs --keyname backups --run" ...

       In key installation mode, this adds the --keyname option to the authorized_keys entry.

       key_name may contain no whitespace.

       --configfile
       Specifies the authprogs configuration file to read. Defaults to ~/.ssh/authprogs.yaml.

       In key installation mode, this adds the --configfile option to the authorized_keys entry.

       --configdir
       Specifies the authprogs configuration, in which multiple configuration files can be found.
       Defaults to ~/.ssh/authprogs.d if present.

       Files   in  the  configuration  directory  are  read  as  rules  in  filename  order.  See
       CONFIGURATION for more info.

LIMITATIONS

       Commands are executed via fork/exec, and are not processed through the shell.  This  means
       you  cannot  have  multiple  commands  separated  by  semicolons, pipelines, redirections,
       backticks, shell builtins, wildcards, variables, etc.

       Also, you cannot have spaces in any arguments your command runs. This is because  the  SSH
       server  takes  the  command  that  was  specified  by  the client and squashes it into the
       SSH_ORIGINAL_COMMAND variable. By doing this it makes it impossible for us  to  know  what
       spaces in SSH_ORIGINAL_COMMAND were between arguments and which were part of arguments.

       Here are some commands that would not work through authprogs:

       ○   ssh host "rm /tmp/foo; touch /tmp/success"ssh host "rm /tmp/*.html"ssh host "cut -d: -f 1 /etc/passwd > /tmp/users"ssh host "touch ´/tmp/file with spaces´"ssh host "for file in /tmp/*.html; do w3m -dump $file > $file.txt; done"

       You  can  work  around these limitations by writing a shell script that does what you need
       and calling that from authprogs, rather than attempting to run complicated  command  lines
       via ssh directly.

CONFIGURATION FILES

       authprogs rules are maintained in one or more configuration files in YAML format.

       The rules allow you to decide whether the client´s command should be run based on criteria
       such as the command itself, the client IP address, and ssh key in use.

       Rules can be read from a single file (~/.ssh/authprogs.yaml  by  default)  or  by  putting
       files  in  a  configuration  directory  (~/.ssh/authprogs.d).  The configuration directory
       method is most useful when you want to be able to  easily  add  or  remove  rules  without
       manually  editing  a  single  configuration  file,  such as when installing rules via your
       configuration tool of choice.

       All the authprogs configuration files  are  concatenated  together  into  one  large  yaml
       document which is then processed. The files are concatenated in the following order:

       ○   ~/.ssh/authprogs.yaml, if present

       ○   files in ~/.ssh/authprogs.d/ directory, in asciibetical order

       Dotfiles  contained  in a configuration directory are ignored. The configuration directory
       is not recursed; only those files directly contained are processed.

       Each rule in the configuration file/files is tested in order and once a  match  is  found,
       processing stops and the command is run.

       Rules  are  made  of  rule selection options (e.g. client IP address) and subrules (e.g. a
       list of allowed commands). All pieces must match for the command to be run.

       The general format of a rule is as follows:

           # First rule
           -
             # Selection options
             #
             # All must match or we stop processing this rule.
             selection_option_1: value
             selection_option_2: value

             # The allow block, aka subrules
             #
             # This lets us group a bunch of possible commands
             # into one rule. Otherwise we´d need a bunch of
             # rules where you repeat selection options.

             allow:
               -
                 rule_type: value
                 rule_param_1: value
                 rule_param_2: value
               -
                 rule_type: value2
                 rule_param_1: value
                 rule_param_2: value

           # Next rule
           -
             selection_option_3: value
           ...

       Some of the keys take single arguments, while others may take lists. See the definition of
       each to understand the values it accepts.

RULE SELECTION OPTIONS

       These  configuration  options  apply  to  the  entire  rule, and help you limit under what
       conditions the rule matches.

       ○   from: This is a single value or  list  of  values  that  define  what  SSH  client  IP
           addresses  are  allowed  to  match  this  rule.  The  client  IP address is gleaned by
           environment variables set by the SSH server. Any from value may be an IP address or  a
           CIDR network.

       Examples:

           -
             from: 192.168.1.5
             ...

           -
             from: [192.168.0.1, 10.0.0.3]
             ...

           -
             from:
               - 192.168.0.0/24
               - 10.10.0.3
             ...

       ○   keynames:  This  is a single value or list of values that define which SSH pubkeys are
           allowed to match this rule. The keyname is specified by the --keyname foo parameter in
           the authprogs command line in the entry in authorized_keys.

       Examples:

           -
             keynames: backups
             ...

           -
             keynames: [repo_push, repo_pull]
             ...

           -
             keynames:
               - repo_push
               - repo_pull
             ...

ALLOW SUBRULE SECTION

       The allow section of a rule is a single subrule or list of subrules.

       Subrules  can  be simple, for example the explicit command match, or be more program-aware
       such as scp support. You specify which kind of subrule you want with the rule_type option:

           -
             allow:
               -
                 rule_type: command
                 command: /bin/touch /tmp/timestamp
               -
                 command: /bin/rm /tmp/bar
               -
                 rule_type: scp
                 allow_upload: true
           ...

       See the separate subrules sections below for how to craft each type.

COMMAND SUBRULES

       This section applies if rule_type is set to command or is not present at all.

       The command requested by the client is compared to the command listed in the rule. (Spaces
       are squashed together.) If it matches, then the command is run.

       Note  that  the  command  must  be  exactly  the same; authprogs is not aware of arguments
       supported by a command, so it cannot realise that "ls -la" and "ls -a -l" and "ls -al" and
       "ls  -l  -a"  are  all  the  same.  You  can list multiple commands to allow you to accept
       variants of a command if necessary.

       The simplest configuration looks like this:

           -
             allow:
               command: /bin/true

       Or you can provide a list of commands:

           -
             allow:
               - command: /bin/true
               - command: /bin/false

       A number of optional settings can tweak how command matching is performed.

       ○   allow_trailing_args: true: This setting allows you to specify a partial  command  that
           will  match as long as the command requested by the client is the same or longer. This
           allows you to avoid listing every variant of a command that the  client  may  wish  to
           run.

           Examples:

           -
             allow:
               -
                 command: /bin/echo
                 allow_trailing_args: true
               -
                 command: /bin/ls
                 allow_trailing_args: true
               -
                 command: /bin/rm -i
                 allow_trailing_args: true

       ○   pcre_match:  true:  Compare  the  command  using pcre regular expressions, rather than
           doing an explicit match character by character. The  regex  is  not  anchored  at  the
           beginning nor end of the string, so if you wish to anchor it is your responsibility to
           do so.

           Caution: never underestimate the sneakiness of an adversary who  may  find  a  way  to
           match your regex and still do something nasty.

           Examples:

           -
             allow:
               -
                 # Touch the foo file, allowing any
                 # optional command line params
                 # before the filename

                 command: ^touch\\s+(-\\S+\\s+)*foo$
                 pcre_match: true
               -
                 # attempt to allow rm of files in /var/tmp
                 # but actually would fail to catch malicious
                 # commands e.g. /var/tmp/../../etc/passwd
                 #
                 # As I said, be careful with pcre matching!!!

                 command: ^/bin/rm\\s+(-\\S+\\s+)*/var/tmp/\\S*$
                 pcre_match: true

RSYNC SUBRULES

       authprogs  has special support for rsync file transfer. You are not required to use this -
       you could use a simple command subrules to match explicit rsync commands -  but  using  an
       rsync-specific subrule offers you greater flexibility.

       Rsync support is in beta, so please raise any bugs found. Supporting the full set of rsync
       command line options is a moving target.

       To specify rsync mode, use rule_type: rsync.

       The rsync options are as follows.

       ○   rule_type: rsync: This indicates that this is an rsync subrule.

       ○   allow_upload: false|true: Allow files to be uploaded to the ssh  server.  Defaults  to
           false.

       ○   allow_download: false|true: Allow files to be downloaded from the ssh server. Defaults
           to false.

       ○   allow_archive: false|true: Allow file archive, i.e. the  options  that  are  set  when
           using  -a  or  --archive.  This  is  used  to  simplify authprogs configuration files.
           Specifying this and negating one  of  he  associated  options  (e.g.  allow_recursive:
           false) is considered an error. Defaults to false.

       ○   paths: a list of explicit files/directories that are allowed to match. Files specified
           by the client will be resolved via realpath to avoid any symlink trickery, so  members
           of paths must be the real paths.

           WARNING: specifying a directory in paths would allow rsync to act on any files therein
           at potentially infinite depth, e.g. when allow_recursive is set, or  the  client  uses
           --files-from. If you want to restrict to specific files you must name them explicitly.

           See RSYNC SYMLINK SUPPORT for potential limitations to paths.

       ○   path_startswith:  a  list  of  pathname  prefixes  that  are  allowed  to match. Files
           specified by the client will be resolved via realpath and if they start with the  name
           provided then they will be allowed.

           This is a simple prefix match. For example if you had

             path_startswith: [ /tmp ]

       then it would match all of the following

             /tmp
             /tmp/
             /tmpfiles      # may not be what you meant!
             /tmp/foo.txt
             /tmp/dir1/dir2/bar.txt

       If  you  want  it  to  match only a directory (and any infinite subdirectories) be sure to
       include a trailing slash, e.g. /tmp/

       See RSYNC SYMLINK SUPPORT for potential limitations to paths.

       ○   allow_acls: false|true: Allow syncing of file ACLs. (--acls). Defaults to false.

       ○   allow_checksum: true|false: Allow checksum method  for  identifying  files  that  need
           syncing. (-c / --checksum) Defaults to true.

       ○   allow_debug:  true|false:  Allow  fine-grained  debug  verbosity.  (--debug FLAGS). No
           support for sanity checking the debug flags that are specified. Defaults to true.

       ○   allow_delete:  false|true:  Allow  any  of  the  delete   options.   (--del   --delete
           --delete-after   --delete-before   --delete-delay   --delete-during  --delete-excluded
           --delete-missing-args). Defaults to false.

       ○   allow_devices: false|true: Allow syncing of device  files.  (--devices).  Defaults  to
           false.

       ○   allow_group: false|true: Allow group change. (-g --group). Defaults to false.

       ○   allow_info:  true|false:  Allow fine-grained info verbosity. (-info FLAGS). No support
           for sanity checking the info flags that are specified. Defaults to true.

       ○   allow_links: false|true: Allow copying symlinks as symlinks. (-l --links). Defaults to
           false.

       ○   allow_group: false|true: Allow ownership change. (-o --owner). Defaults to false.

       ○   allow_perms: false|true: Allow perms change. (-p --perms). Defaults to false.

       ○   allow_recursive:  false|true:  Allow  recursive  sync.  (-r  --recursive). Defaults to
           false.

       ○   allow_specials: false|true: Allow syncing of special files, e.g. fifos.  (--specials).
           Defaults to false.

       ○   allow_times:  true|false:  Allow  setting synced file times. (-t --times). Defaults to
           true.

       ○   allow_verbose: true|false|#:  Allow  verbose  output.  (-v  --verbose).  Rsync  allows
           multiple  -v  options,  so this option accepts true (allow any verbosity), false (deny
           any verbosity), or a number which indicates the maximum number of -v option  that  are
           allowed, e.g. 2 would allow -v or -vv but not -vvv. Defaults to true.

   RSYNC COMMAND LINE OPTIONS
       Not all rsync options are currently implemented in authprogs.

       If  an  option  is  listed  as  "not  implemented" then there are two possibilities in how
       authprogs will behave:

           * if the option is no actually sent on the remote command line then
             `authprogs` is blissfully unaware and the command will succeed.
             Many options are actually client-side only. We have not thoroughly
             investigated every single option yet.

           * if the option is sent on the remote command line then `authprogs`
             will fail.

       Here is the list of rsync options and their current authprogs support status:

           rsync client arg             authprogs support
           ----------------             -----------------

               --append                   <not implemented>
               --append-verify            <not implemented>
               --backup-dir               <not implemented>
               --bwlimit                  <not implemented>
               --checksum-seed            <not implemented>
               --chown                  converted to --usermap and --groupmap
               --compare-dest             <not implemented>
               --compress-level           <not implemented>
               --contimeout               <not implemented>
               --copy-dest                <not implemented>
               --copy-unsafe-links        <not implemented>
               --debug                  allow_debug
               --del                    allow_delete
               --delay-updates            <not implemented>
               --delete                 allow_delete
               --delete-after           allow_delete
               --delete-before          allow_delete
               --delete-delay           allow_delete
               --delete-during          allow_delete
               --delete-excluded        allow_delete
               --delete-missing-args    allow_delete
               --devices                allow_devices
               --existing                 <not implemented>
               --fake-super               <not implemented>
               --files-from               <not implemented>
               --force                    <not implemented>
               --groupmap                 <not implemented>
               --iconv                    <not implemented>
               --ignore-errors            <not implemented>
               --ignore-existing          <not implemented>
               --ignore-missing-args      <not implemented>
               --info                   allow_info
               --inplace                  <not implemented>
               --link-dest                <not implemented>
               --list-only                <not implemented>
               --log-file                 <not implemented>
               --log-file-format          <not implemented>
               --max-delete               <not implemented>
               --max-size                 <not implemented>
               --min-size                 <not implemented>
               --new-compress             <not implemented>
               --no-XXXXX                 <not implemented> (negating options, e.g. --no-r)
               --numeric-ids              <not implemented>
               --only-write-batch         <not implemented>
               --outbuf                   <not implemented>
               --partial                  <not implemented>
               --partial-dir              <not implemented>
               --preallocate              <not implemented>
               --protocol                 <not implemented>
               --read-batch               <not implemented>
               --remove-sent-files        <not implemented> # deprecated version of remove-source-files
               --remove-source-files      <not implemented>
               --safe-links               <not implemented>
               --size-only                <not implemented>
               --skip-compress            <not implemented>
               --specials               allow_specials
               --stats                    <not implemented>
               --stop-at                  <not implemented>
               --suffix                   <not implemented>
               --super                    <not implemented>
               --time-limit               <not implemented>
               --timeout                  <not implemented>
               --usermap                  <not implemented>
               --write-batch              <not implemented>
           -0, --from0                    <not implemented>
           -@, --modify-window            <not implemented>
           -A, --acls                   allow_acls
           -B, --block-size               <not implemented>
           -C, --cvs-exclude              <not implemented>
           -D                           allow_devices and allow_specials
           -E, --executability            <not implemented>
           -H, --hard-links               <not implemented>
           -I, --ignore-times             <not implemented>
           -J, --omit-link-times          <not implemented>
           -K, --keep-dirlinks            <not implemented>
           -L, --copy-links               <not implemented>
           -O, --omit-dir-times           <not implemented>
           -P                           Same as --partial --progress
           -R, --relative                 <not implemented>
           -S, --sparse                   <not implemented>
           -T, --temp-dir                 <not implemented>
           -W, --whole-file               <not implemented>
           -X, --xattrs                   <not implemented>
           -a, --archive                Same as -rlptgoD; See those options
               --progress                 <not implemented>
           -b, --backup                   <not implemented>
           -c, --checksum               allow_checksum
           -d, --dirs                     <not implemented>
           -f, --filter                   <not implemented>
           -g, --group                  allow_group
           -i, --itemize-changes          <not implemented>
           -k, --copy-dirlinks            <not implemented>
           -l, --links                  allow_links
           -m, --prune-empty-dirs         <not implemented>
           -n, --dry-run                  <not implemented>
           -o, --owner                  allow_owner
           -p, --perms                  allow_perms
           -r, --recursive              allow_recursive
           -s, --protect-args             <not implemented>
           -t, --times                  allow_times
           -u, --update                   <not implemented>
           -v, --verbose                allow_verbose
           -x, --one-file-system          <not implemented>
           -y, --fuzzy                    <not implemented>
           -z, --compress                 <not implemented>
               --checksum-choice=STR      <not implemented>
               --exclude-from             <not implemented>
               --exclude                  <not implemented>
               --include-from             <not implemented>
               --include                  <not implemented>
               --rsync-path               <not implemented>
               --out-format               <not implemented>

       The following are server-side only options that are supported

           -e, --rsh=COMMAND            Value ignored (indicates protocol feature support)
           --sender                     When present means download from server,
                                        when absent means upload to server.
           --server                     Always present on server

       The following rsync client options are only relevant to daemon  mode  (i.e.  rsync  daemon
       listening on TCP directly without SSH) or do not end up on the server command line and are
       thus re not taken into consideration when determining if the command is or is not allowed:

               --address               Client-only option
               --chmod                 Client-only option
                                          (Permissions are indicated via rsync
                                           protocol, not command line flags.)
               --blocking-io           Client-only option
               --daemon                Daemon-only option
               --msgs2stderr           Client-only option
               --munge-links           Client-only option
               --no-motd               Client-only option
               --noatime               Client-only option
               --password-file         Daemon-only option
               --port                  Client-only option
               --sockopts              Daemon-only option
               --version               Client-only option
           -4, --ipv4                  Client-only option
           -6, --ipv6                  Client-only option
           -8, --8-bit-output          Client-only option
           -F                          Client-only option (see --filter)
           -M, --remote-option=OPTION  Client-only option
           -h, --human-readable        Client-only option
           -q, --quiet                 Client-only option

   RSYNC BINARY PATH
       Rsync must be at an official path to prevent a user´s environment  from  choosing  one  of
       their programs over the official one. Official paths are

           * /usr/bin/rsync
           * /usr/local/bin/rsync

       A  user  who  specifies  --rsync-path  with a different value, or who has an rsync program
       earlier in their $PATH will be denied.

   RSYNC SYMLINK SUPPORT
       Rsync has multiple ways of handling symlinks depending on command line parameters and what
       component(s) of a path are symlinks.

       If  you are using paths or paths_startswith to limit what files may be uploaded/downloaded
       then its your responsibility to assure that symlink games  are  not  used  to  exceed  the
       desired restrictions.

       For example if the file /tmp/me.txt is a symlink to /home/wbagg/me.txt and you had

           - rule\_type: rsync
               allow_upload: true
               paths:
                   - /tmp/me.txt

       then if the user ran

           rsync /some/local/file remote:/tmp/me.txt

       then rather than updating the file at /home/wbagg.me.txt, the symlink at /tmp/me.txt would
       be replaced with a normal file.

       A future update to authprogs may attempt to handle symlinks  by  calling  os.path.realpath
       prior to doing comparisons.

   RSYNC PATHNAME GOTCHA
       Say  you wanted to restrict uploads to just the file /tmp/foo.txt, you´d use the following
       rsync subrule::

           - rule\_type: rsync
             allow_upload: true
             paths:
               - /tmp/foo.txt

       From an end-user perspective both of these commands would seem  to  be  allowed  from  the
       client machine because they´d create a file on the remote named /tmp/foo.txt:

           $ rsync foo.txt remote:/tmp/foo.txt  # provide full target filename
           $ rsync foo.txt remote:/tmp          # imply source name for target

       However you´ll find that only the first one works! This is because authprogs on the server
       side sees literally just /tmp in the second case.

       Thus if you wanted to restrict uploads to just the file /tmp/foo.txt then  on  the  client
       side you must run the first (explicit filename) rsync command.

   RSYNC SUBRULE KNOWN AND POSSIBLE BUGS
       ○   If  uploading  to a file that does not yet exist when you´ve set paths this will fail.
           Adding a new allow_create option is  the  most  likely  solution  here,  but  not  yet
           implemented.

       ○   No  investigation  of  the  rsync options --include / --exclude / --files-from has yet
           been performed - may affect path matching security.

       ○   Though we do expand file globs and check each individual path that is returned, we  do
           not  explicitly use these resolved files when calling rsync. (Reason: it´s possible we
           exceed the allowed size of a command line with globs that return many files.) As  such
           if  rsync´s glob and shutils.glob have different behaviour we may have false positives
           or negatives.

       ○   When allow_download is disabled client should  not  be  able  to  get  file  contents.
           However  since  rsync  transfers checksums as part of its protocol it is possible that
           information about server file contents could be  gleaned  by  comparing  checksums  to
           possible content checksums when doing uploads.

SCP SUBRULES

       authprogs  has  special  support for scp file transfer. You are not required to use this -
       you could use a simple command subrules to match explicit scp  commands  -  but  using  an
       scp-specific subrule offers you greater flexibility.

       To specify scp mode, use rule_type: scp.

       The scp options are as follows.

       ○   rule_type: scp: This indicates that this is an scp subrule.

       ○   allow_upload:  false|true:  Allow  files to be uploaded to the ssh server. Defaults to
           false.

       ○   allow_download: false|true: Allow files to be downloaded from the ssh server. Defaults
           to false.

       ○   allow_recursive: false|true: Allow recursive (-r) file up/download. Defaults to false.

       ○   allow_recursion: false|true: Deprecated version of allow_recursive. will be removed in
           1.0 release.

       ○   allow_permissions: true|false: Allow scp to get/set the permissions of the  file/files
           being transferred. Defaults to false.

       ○   paths:  The  paths  option allows you to specify which file or files are allowed to be
           transferred. If this is not specified then  transfers  are  not  restricted  based  on
           filename.

           Examples:

           -
             allow:
               - rule_type: scp
                 allow_download: true
                 paths:
                   - /etc/group
                   - /etc/passwd
               - rule_type: scp
                 allow_upload: true
                 paths: [/tmp/file1, /tmp/file2]

EXAMPLES

       Here  is  a  sample  configuration  file  with  multiple  rules, going from simple to more
       complex.

       Note that  this  config  can  be  spread  around  between  the  ~/.ssh/authprogs.yaml  and
       ~/.ssh/authprogs.d directory.

           # All files should start with an initial solo dash -
           # remember, we´re being concatenated with all other
           # files!

           # Simple commands, no IP restrictions.
           -
             allow:
               - command: /bin/tar czvf /backups/www.tgz /var/www/
               - command: /usr/bin/touch /var/www/.backups.complete

           # Similar, but with IP restrictions
           -
             from: [192.168.0.10, 192.168.0.15, 172.16.3.3]
             allow:
               - command: git --git-dir=/var/repos/foo/.git pull
               - command: sudo /etc/init.d/apache2 restart

           # Some more complicated subrules
           -
             # All of these ´allows´ have the same ´from´ restrictions
             from:
               - 10.1.1.20
               - 10.1.1.21
               - 10.1.1.22
               - 10.1.1.23
             allow:
               # Allow unrestricted ls
               - command: /bin/ls
                 allow_trailing_args: true

               # Allow any ´service apache2 (start|stop)´ commands via sudo
               - command: sudo service apache2
                 allow_trailing_args:true

               # How about a regex? Allow wget of any https url, outputting
               #  to /tmp/latest
               - command: ^/usr/bin/wget\\s+https://\\S+\\s+-O\\s+/tmp/latest$
                 pcre_match: true

               # Allow some specific file uploads
               - rule_type: scp
                 allow_upload: true
                 paths:
                   - /srv/backups/host1.tgz
                   - /srv/backups/host2.tgz
                   - /srv/backups/host3.tgz

               # Allow rsync to upload everything, deny any download
               - rule_type: rsync
                 allow_upload: true

               # Allow rsync to recursively sync /tmp/foo/ to the server
               # in archive mode (-a, or any subset of -logptrD)
               # but do not allow download
               - rule_type: rsync
                 allow_upload: true
                 allow_recursive: true
                 allow_archive: true
                 paths:
                   - /tmp/foo

               # Allow rsync to write some specific files and any individual
               #   files under /data/lhc/ directory, such as /data/lhc/foo
               #   or /data/lhc/subdir/foo.
               #
               # Disallow download (explicitly listed) or recursive
               #    upload (default false).
               - rule_type: rsync
                 allow_upload: true
                 allow_download: false
                 paths:
                   - /srv/htdocs/index.html
                   - /srv/htdocs/status.html
                 path_startswith:
                   - /data/lhc/

TROUBLESHOOTING

       --dump_config  is  your  friend. If your yaml config isn´t parsing, consider --dump_config
       --logfile=/dev/tty for more debug output to find the error.

FILES

~/.ssh/authorized_keys: The default place your key should be installed and  configured
           to  call  authprogs.  The actual location can differ if your administrator has changed
           it.

       ○   ~/.ssh/authprogs.yaml:   Default   authprogs   configuration   file.   Override   with
           --configfile.

       ○   ~/.ssh/authprogs.d:   Default   authprogs   configuration   directory.  Override  with
           --configdir.

ENVIRONMENT

       authprogs uses the following environment variables that are set by the sshd(8) binary:

       ○   SSH_CONNECTION: This is used to determine the client IP address.

       ○   SSH_CLIENT: This is used to determine the client IP address if SSH_CONNECTION was  not
           present.

       ○   SSH_ORIGINAL_COMMAND:  The  (squashed)  original  SSH  command  that was issued by the
           client.

       authprogs sets the following environment variables for use by the authenticated process

       ○   AUTHPROGS_KEYNAME: the value of the --keyname command line. Will be set  to  an  empty
           string if no --keyname was set.

EXIT STATUS

       On unexpected error or rejecting the command authprogs will exit 126.

       If the command was accepted then it returns the exit code of the command that was run.

       Note  that  if  you´re  invoking ssh via another tool that program may provide a different
       exit status and provide a misleading error message when authprogs returns a  failure,  For
       example  rsync will exit 12 and assume a "protocol problem" rather than a rejection on the
       server side.

LOGGING AND DEBUGGING

       If a --logfile is specified then it will be opened in append mode and a  line  about  each
       command  that is attempted to be run will be written to it. The line itself is in the form
       of a python dictionary.

       If authprogs is  run  with  --debug,  then  this  logfile  will  get  increased  debugging
       information, including the configuration, rule matching status as they are checked, etc.

HISTORY

       A      perl      version      of     authprogs     was     originally     published     at
       https://www.hackinglinuxexposed.com/articles/20030115.html in 2003.  This  is  a  complete
       rewrite  in  python,  with  a  more  extensible  configuration,  and  avoiding some of the
       limitations of the former.

SEE ALSO

       ssh(1), sshd(8), scp(1).

AUTHOR

       Bri Hatch mailto:bri@ifokr.org

                                            March 2021                               AUTHPROGS(1)