AUTHPROGS(1)

📦 version 0.7.5, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

✨ AUTHPROGS(1) ✨ — the authprogs manual, but make it cute

okay bestie, buckle up, because authprogs is literally the bouncer for your SSH commands and she is NOT letting just anyone walk in 💅

🌸 NAME 🌸

authprogs — SSH command authenticator

🎀 SYNOPSIS 🎀

authprogs --run [options]

authprogs --install_key [options]

authprogs --dump_config [options]

authprogs --help

🦋 DESCRIPTION 🦋

So. authprogs is an SSH command authenticator. It gets invoked over on an ssh server, and it decides whether the command the ssh client asked for should actually run or get rejected, based on the logic living inside the authprogs configuration file. No cap.

Passwordless SSH with ssh identities or pubkeys unlocks sooo much wonderful automation — think unattended batch jobs, slurping down backups, pushing out code. Iconic, honestly. But here's the thing, and it's giving red flag: a key, once it's trusted, is allowed by default to run anything on that system. Not just the small set of commands you actually need. So if that key gets compromised? You're at risk of a security breach 😭 and it could be catastrophic — like, say, if the access is to the root account. Yikes.

Authprogs runs on the SSH server and compares the requested command against the authprogs configuration file/files. That's what lets it make intelligent decisions based on stuff like the command itself, the SSH key that was used, the client IP, and such. Main character energy fr fr.

And how do you turn it on? With the command= option in the authorized_keys file. Periodt.

🔑 KEY INSTALLATION 🔑

You can install your ssh identities/pubkeys manually, or you can let authprogs do the work for you. Dealer's choice, bestie.

💖 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 you set up this key to use authprogs, you add a command= option to the very beginning of that line, pointing to the location where authprogs lives. So, for example, if authprogs is in /usr/bin/authprogs, you'd use this:

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

You must include --run to let authprogs know it's running in SSH command mode. Don't skip it, I'm begging 🙈

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. iykyk 📖

🌈 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 — which is a sensible default for most batch jobs, ngl.

⚠️ 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. (lowkey just a peek behind the curtain 🔍)
  • --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. Which means... no. You cannot have multiple commands separated by semicolons, pipelines, redirections, backticks, shell builtins, wildcards, variables, etc. She said what she said 💅

Also — and this one's a little heartbreaking — you cannot have spaces in any arguments your command runs. Why? 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. The audacity, honestly 😭

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. Slay, problem solved 🫶

🧚 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. Chef's kiss 👑

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:

  1. ~/.ssh/authprogs.yaml, if present
  2. 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 🎀

okay so this whole section is your bestie if rule_type is set to command — or if you didn't set rule_type at all, in which case this is just the default vibe. no notes. 💅

here's the tea: whatever command the client asks for gets compared against the command sitting in the rule. spaces get squashed together (yes, squashed, like a lil bug 🐛). if they match? the command runs. slay.

but listen — and this is the part that lowkey ruins people — the command has to be exactly the same. authprogs has zero clue which arguments a command supports, so it genuinely cannot tell that ls -la and ls -a -l and ls -al and ls -l -a are all, like, the same thing. it's giving literal. so if you need to accept variants, you just list multiple commands. no cap.

simplest config ever, look at her:

-
  allow:
    command: /bin/true

or you can hand it a whole list of commands, main character energy:

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

and then there's a lil pile of optional settings that tweak how the matching goes down. obsessed. 💖

  • allow_trailing_args: true — this lets you write a partial command and have it match as long as what the client asked for is the same or longer. perfect for when you cannot be bothered listing every single variant of a command a client might wanna 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 — compares the command using pcre regular expressions instead of doing an explicit match character by character. and heads up: the regex is not anchored at the beginning or the end of the string, so if you want it anchored, that is 100% on you to do. 🙈
⚠️ caution: never underestimate the sneakiness of an adversary who may find a way to match your regex and still do something nasty. they will. they always do. 💀

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, and it's genuinely so cute of her. you do not have to use it — you could totally just use a simple command subrule and match explicit rsync commands — but an rsync-specific subrule gives you way more 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. she's trying her best, okay?? 😭

to get into rsync mode, use rule_type: rsync. periodt.

the rsync options are, in order, as follows. buckle up bestie, there's a lot: 🫶

  • rule_type: rsync — this is the lil flag that says "yes 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 get set when you use -a or --archive. this exists to simplify authprogs config files. specifying this and negating one of the associated options (like 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 get resolved via realpath to avoid any symlink trickery, so the members of paths have to 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 when the client uses --files-from. if you want to restrict to specific files, you must name them explicitly. no shortcuts, babe. 💀

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 get resolved via realpath, and if they start with the name you provided, they're allowed. ✨

this is a simple prefix match. so like, 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 one accepts true (allow any verbosity), false (deny any verbosity), or a number which is the maximum number of -v options 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. she's working on it. 🧚

if an option is listed as "not implemented", then there are two possibilities for how authprogs will behave:

  • if the option is not 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's the list of rsync options and their current authprogs support status:

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

...and we're BACK in the option list bestie, no skipping, no summarising, every single one of these is getting its moment 💅

  • --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 — maps to allow_debug ✅
  • --del — maps to allow_delete ✅
  • --delay-updates — <not implemented> 🙈
  • --delete — maps to allow_delete ✅
  • --delete-after — maps to allow_delete ✅
  • --delete-before — maps to allow_delete ✅
  • --delete-delay — maps to allow_delete ✅
  • --delete-during — maps to allow_delete ✅
  • --delete-excluded — maps to allow_delete ✅
  • --delete-missing-args — maps to allow_delete ✅
  • --devices — maps to 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 — maps to 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> (that's negating options, like --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 — maps to 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 — maps to allow_acls ✅
  • -B, --block-size — <not implemented> 🙈
  • -C, --cvs-exclude — <not implemented> 🙈
  • -D — maps to 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; go see those options 👀
  • --progress — <not implemented> 🙈
  • -b, --backup — <not implemented> 🙈
  • -c, --checksum — maps to allow_checksum ✅
  • -d, --dirs — <not implemented> 🙈
  • -f, --filter — <not implemented> 🙈
  • -g, --group — maps to allow_group ✅
  • -i, --itemize-changes — <not implemented> 🙈
  • -k, --copy-dirlinks — <not implemented> 🙈
  • -l, --links — maps to allow_links ✅
  • -m, --prune-empty-dirs — <not implemented> 🙈
  • -n, --dry-run — <not implemented> 🙈
  • -o, --owner — maps to allow_owner ✅
  • -p, --perms — maps to allow_perms ✅
  • -r, --recursive — maps to allow_recursive ✅
  • -s, --protect-args — <not implemented> 🙈
  • -t, --times — maps to allow_times ✅
  • -u, --update — <not implemented> 🙈
  • -v, --verbose — maps to 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> 🙈

<h2>✨ server-side only options that ARE supported ✨</h2>

These ones only ever show up on the server, and they're supported, so:

  • -e, --rsh=COMMAND — the value is ignored (it's just there to indicate protocol feature support) 🫶
  • --sender — when it's present, that means download from server; when it's absent, that means upload to server 🔄
  • --server — always present on server 👑

<h2>🌈 client options that don't count 🌈</h2>

Okay so these rsync client options only matter for daemon mode (aka an rsync daemon listening on TCP directly, no SSH involved), or they just never end up on the server command line at all. Which means they're not taken into consideration when we're figuring out if a command is allowed or not. So don't stress about them 💅

  • --address — client-only option
  • --chmod — client-only option (permissions get indicated via the rsync protocol, not via 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 (peep --filter)
  • -M, --remote-option=OPTION — client-only option
  • -h, --human-readable — client-only option
  • -q, --quiet — client-only option

🔒 RSYNC BINARY PATH 🔒

So like, rsync has to live at an official path, because otherwise a user's environment could just... pick one of their own little programs instead of the real one. Not on our watch bestie 💅 The official paths are:

  • /usr/bin/rsync
  • /usr/local/bin/rsync

If a user hits us with --rsync-path pointing somewhere else, or they've got an rsync sitting earlier in their $PATH? Denied. Periodt. 🚫

rsync has multiple ways of handling symlinks, and which one you get depends on the command line parameters and on which component(s) of a path happen to be symlinks. It's giving choose-your-own-adventure 😭

If you're using paths or paths_startswith to limit what files may be uploaded/downloaded, then it is your responsibility to make sure symlink games aren't being used to exceed the restrictions you wanted. no cap.

Example time, bestie. Say 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 instead of updating the file at /home/wbagg.me.txt, the symlink at /tmp/me.txt would be replaced with a normal file. Yeah. 🙈

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

🚨 RSYNC PATHNAME GOTCHA 🚨

Okay so picture this: you wanna restrict uploads to just the file /tmp/foo.txt, so you write yourself this rsync subrule:

- rule_type: rsync
  allow_upload: true
  paths:
    - /tmp/foo.txt

From an end-user's perspective, both of these commands would seem allowed from the client machine, because both would 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

But plot twist 💀 only the first one actually works! Why? Because authprogs on the server side sees literally just /tmp in the second case. That's it. That's the whole gotcha.

So if you wanted to restrict uploads to just the file /tmp/foo.txt, then on the client side you must run that first (explicit filename) rsync command. No shortcuts, bestie 🎀

💀 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 it's not yet implemented. 😭
  • No investigation of the rsync options --include / --exclude / --files-from has yet been performed — this 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 get false positives or negatives. 🙃
  • when allow_download is off, the client should NOT be able to grab file contents. but bestie, plot twist: rsync ships checksums as part of its protocol, so it's possible that info about server file contents could be gleaned by comparing those checksums to possible content checksums when doing uploads. 💀 so like, it's not a full leak of the file, but it's not nothing either. noted, on the record, moving on.

🌸 SCP SUBRULES 🌸

authprogs has special support for scp file transfer, and it's genuinely so nice of it. you are not required to use this — you could just use a plain command subrule to match explicit scp commands — but an scp-specific subrule gives you so much more flexibility. ✨

to flip on scp mode, use rule_type: scp.

the scp options are, in order, no skipping: 🎀

  • rule_type: scp — says hey, this one is an scp subrule. that's it. that's the vibe. 💅
  • allow_upload: false|true — let files be uploaded to the ssh server. defaults to false.
  • allow_download: false|true — let files 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. ngl, retire her. 🙈
  • allow_permissions: true|false — let scp get/set the permissions of the file/files being transferred. defaults to false.
  • paths — lets you say exactly which file or files are allowed to be transferred. if you don't specify this, then transfers are not restricted based on filename. (iykyk — that's a big deal.) 👑

examples, because seeing it is believing:

-
  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's a sample configuration file with multiple rules, going from simple to more complex. she ate, fr fr.

note that this config can be spread around between the ~/.ssh/authprogs.yaml and ~/.ssh/authprogs.d directory. so like, organize her however you want. 🧚

# 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. your actual bestie. ✨ if your yaml config isn't parsing, consider --dump_config --logfile=/dev/tty for more debug output to find the error. do it, thank me later. 💖

💜 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. (ask your admin bestie.)
  • ~/.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 — used to determine the client IP address.
  • SSH_CLIENT — 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 when rejecting the command, authprogs will exit 126. periodt.

if the command was accepted, then it returns the exit code of the command that was run. cute, right?

heads up bestie: if you're invoking ssh via another tool, that program may provide a different exit status and give you 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. 😭 so don't let the wrong tool gaslight you about what happened.

🎀 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. so readable, so structured, we love her. 📝

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. everything. the whole tea. ☕

🦋 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. glow-up of the century, no cap. 💅

👑 SEE ALSO 👑

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

🌸 AUTHOR 🌸

Bri Hatch mailto:bri@ifokr.org

okay that's the whole page bestie, you made it to the end!! 🎉 this was AUTHPROGS(1), dated March 2021 — go forth and lock down your ssh, you're the main character now. mwah. 💖✨🎀

📦 where this page comes from