Smart Proxy Shell Hooks

Provides an endpoint for foreman_webhooks plugin executing binaries (shell scripts, python scripts, anything). Remember CGI? :-)

Installation

Install the plugin using the foreman-installer. Never enable this service via HTTP endpoint, only HTTPS with authentication using client certificate should be used.

Open up /var/lib/foreman/shellhooks to see some examples, these are harmless stubs that does nothing.

Writing scripts

Script must be placed in /var/lib/foreman/shellhooks having a name consisting of alphanums, dash or underscore. The file must be executable. To see list of availble and valid scripts matching the requirements, perform:

$ curl -s https://localhost:9090/shellhook/ | jq
{
"valid": [
    "print_args",
    "print_body",
    "my_script"
],
"invalid": [
    "README"
]
}

To execute an example script which prints input back to output (smart-proxy log):

$ curl -sX POST -H 'Content-Type: text/plain' \
    --data "This is a test" \
    https://localhost:9090/shellhook/print_body

Logging

To find out if the script was executed, open up smart-proxy log:

2020-08-27T12:23:37 eabe1a74 [I] Started POST /shellhook/print_body 
2020-08-27T12:23:37 eabe1a74 [D] Headers: {"HTTP_HOST"=>"localhost:9090", "HTTP_USER_AGENT"=>"curl/7.69.1", "HTTP_ACCEPT"=>"*/*", "HTTP_VERSION"=>"HTTP/1.1"}
2020-08-27T12:23:37 eabe1a74 [D] Body: This is a test
2020-08-27T12:23:37 eabe1a74 [I] Finished POST /shellhook/print_body with 200 (0.68 ms)
2020-08-27T12:23:37 eabe1a74 [I] [146347] Started task /home/lzap/work/smart_proxy_shellhooks/examples/print_body
2020-08-27T12:23:37 eabe1a74 [D] [146347] This is a test

It is recommended to switch logging level to DEBUG when writing or editing scripts. Logging level is as follows:

• "Started task" initial message: INFO level
• Standard output: DEBUG level
• Standard error: WARNING level

Arguments

Use X-Shellhook-Arg-1 to N HTTP header to send command arguments:

curl -sX POST -H 'Content-Type: text/plain' \
    -H "X-Shellhook-Arg-1: Hello" \
    -H "X-Shellhook-Arg-2: World!" \
    --data "" https://localhost:9090/shellhook/print_args

This can be useful for passing database ID or other simple fields so standard JSON input does not need to be parsed. Use hammer command or python/ruby API to fetch relevant data.

The contract

• The payload from foreman_webhook (rendered template) is connected to standard input of the script.
• Standard output and error are redirected into smart-proxy logger with an unique integer for each job.
• The script is executed asynchronously in a Ruby (green) thread, no return payload possible.
• The return (exit) value is only logged into the smart-proxy logger.
• Optionally HTTP headers X-Shellhook-Arg-1 to N are passed as arguments.
• HTTP return code is 200 when script was executed (not output) or non-200 when the plugin failed (not script).
• Keep in mind all the input is usafe, clean every individual data element or argument to prevent security vulnerability.
• Example templates are shipped with foreman_webhooks plugin and few scripts with this plugin.