Package: httpexec
httpexecis anAsynchronous Server Gateway Interface(ASGI) application
that allows remote clients to execute CLI commands on the local host via a
REST API. AnASGI-capable serveris also required.There are critical security considerations when using this application.See
theSecuritysection.REST APISee the project’sOpenAPIspec file (openapi.yaml) for more information.RequestsThe application acceptsPOSTrequests asapplication/jsonto the/<command>endpoint of its bound address. The request defines the
arguments, input and output streams, and environment variables that will be
used to for executing the command.This sample request sent to endpoint/appwill executeapp-ooptionon the local host with the stringinputpiped toSTDIN. The contents ofSTDOUTwill be captured and returned to the client using Base64 encoding.
The variableFOO=BARwill be added to the execution environment. The
contents ofSTDERRwill not be captured.{"args":["-o","option"],"stdin":{"content":"input"},"stdout":{"capture":true,"encode":"base64"},"environment":{"FOO":"BAR"}}ResponsesIf the command was executed, a200(OK) status is returned along with
anapplication/jsonresponse. This doesnotmean the command itself
was successful; thereturnvalue in the response is the exit status
returned by the command.If the requested command is not found, a404(Not Found) status is
returned. If the command could not be executed due to an unexpected error, a500(Internal Server Error) status is returned.If the sample request from above was executed, a response like this will be
returned. The command returned an exit status of0, the output toSTDERRwas not captured, and the output toSTDOUTis encoded binary
data.{"return":0,"stderr":null,"stdout":{"content":"YmluYXJ5IGRhdGE=","encode":"base64"}}Binary DataJSON cannot handle arbitrary binary data. Any binary input toSTDOUTor
output fromSTDERRorSTDOUTmust be encoded as text strings. The
client mustencodethe content ofSTDINin the request anddecodethe
contents ofSTDERRandSTDOUTfrom the response.httpexecwilldecodethe content ofSTDINfrom the request andencodethe contents ofSTDERRandSTDOUTin the response. Thus, encoding is transparent to the
target command.httpexeccurrently supports two encoding schemes,base64andbase85. If
the target command implements its own text-safe encoding for binary data, use"encode": null(or omit it) in the request to make this transparent tohttpexec.Basic SetupInstallationInstall the application, its runtime dependencies, and theHypercornweb
server:$python-mpipinstallhttpexec"hypercorn>=0.14.3,<1"Pinned DependenciesProduction applications should pin their dependencies to exact versions to
avoid unexpected breaking changes. The downside of this is that it makes it
more difficult to receive critical updates. This application relies onSemantic Versioningfor its own dependencies to minimize breaking changes
while allowing for routine updates (seepyproject.toml). Users should use
their packaage manager to pin this package and its dependencies to exact
versions in a production environment.ConfigurationUser-configurable options can be set using aTOMLconfig file or an
environment variable. Environment variable names must be prefixed withHTTPEXEC_,e.g.HTTPEXEC_EXEC_ROOTsetsEXEC_ROOT. Environment
variables have precedence over the config file.EXEC_ROOTFor security,httpexecwill not execute any command outside of this
directory.This must be set explicitly by the user.FOLLOW_LINKSThis is a boolean that controls whether or nothttpexecwill follow a
symbolic link to a path outside ofEXEC_ROOT. If true, the link itself
must still be withinEXEC_ROOT. For an environment variable use1for true and0for false. For security, the default value is false.LOGGING_LEVELThe application uses standardPython logging, and this sets the logging
level. Messages of a lower severity will not be be logged. The default level
isWARNING.CONFIG_PATHThis is the path to the optional config file.This can only set by environment variable.ExecutionStart the web server, andhttpexecwill be available at the bound address.$python-mhypercorn--error-logfile---access-logfile---bind127.0.0.1:8000httpexec.asgi:appThehttpexecexecution environment is set by the web server, which will also
impact the execution environment of the commands being executed byhttpexec.
For example, this will determine whether or nothttpexechas permission to
run a target command, and the environment variables that are available to the
command. See the web server’s documentation.SecurityAllowing arbitrary remote execution is a significant security risk.Do not usehttpexecwithout understanding all of the security implications.
This application was developed for a specific use case: Allowing a CLI command
in one Docker container to be executed by another Docker container. Docker
makes it easier to provide multiple layers of security, but this is also
possible without Docker.The following advice is not authoritative.USE AT YOUR RISK.Network IsolationAccess to the addresshttpexecis bound to must bestrictly controlled.
Under no circumstances should this be globally visible to the outside world.
By default, a Docker container is only accessible to other Docker containers
on that host. Access can be further controlled by using auser-defined bridge
networkto connect thehttpexeccontainer to a subset of containers on the
host. In a non-container environment, firewall rules and VLANs should be
used to restrict access to anhttpexecinstance.Command Isolationhttpexeccan only do what its target commands can do. Make sure it cannot
access dangerous commands. Access control is currently limited by directory
(seeConfiguration). If necessary, create a directory containing only links
to allowed commands, and use that asEXEC_ROOT(FOLLOW_LINKSmust be
enabled). This is applicable to container and non-container environments.Process IsolationBy default, a Docker container (viaLXC) cannot access running processes or
start new processes on its host. Runninghttpexecinside a container limits
its scope to that container. In a non-container environment, this isolation
can be achieved via a virtual machine.User IsolationDocker best practices dictate that a container runs as a non-privileged user.
The UID the container is running as can only access host resources with the
same permissions as that UID on the host (the respective user names are
irrelevant). Ensure that the container does not run asroot(UID0).
Run the container as a UID that does not exist on the host for maximum
isolation. In both container and non-container environments, do not runhttpexecand/or the web server as a UID that has more access than is
necessary.File IsolationA Docker container does not have access to files on the host unless they are
explicitly mounted, and then its access is determined by the UID it is running
as (see above). This isolation can be achieved in a non-container environment
usingchrootor a virtual machine.Environment IsolationEnvironment variables are commonly used to store various credentials and other
privileged information. A Docker container does not have access to environment
variables on the host unless they explicitly exported to it, and this a
read-only static exchange (changes on the host will not be reflected in a
running container). Environment isolation can also be controlled by the web
server (see its documentation).httpexecalso allows limited control over
the environment, but that is limited to modifying the environment, not
restricting access. While it is possible to unset specific environment
variables as seen by the target command, this requires prior knowledge of all
problematic variable names. In a non-container environment, a virtual
machine will ensure a strict separation of environments, but the VM itself may
contain privileged information.DevelopmentUse the project Makefile to simplify development tasks.SetupCreate a Python virtualenv environment and install the project and itsdevdependencies in editable mode:$makedevRun ChecksRun all tests and linters:$makecheckBuild DocumentationBuild HTML documentation usingSphinx:$makedocsBuild PackageBuild source andwheelpackages. This will run all checks first.$makebuild