Repository files navigation

A minimalistFlask extension that serves as a RESTful/HTTP wrapper for python's subprocess API.

• Convert any command-line tool into a REST API service.
• Execute pre-defined shell commands asynchronously and securely via flask's endpoints with dynamic arguments, file upload, callback function capabilities.
• Designed for binary to binary/HTTP communication, development, prototyping, remote control andmore.

• Set a script that runs on a succesful POST request to an endpoint of your choice. SeeExample code.
• Map a base command to an endpoint and pass dynamic arguments to it. SeeExample code.
• Can also process multiple uploaded files in one command. SeeExample code.
• This is useful for internal docker-to-docker communications if you have different binaries distributed in micro-containers. Seereal-life example.
• You can define a callback function/ use signals to listen for process completion. SeeExample code.
  • Maybe want to pass some additional context to the callback function ?
  • Maybe intercept on completion and update the result ? SeeExample code
• You can also applyView Decorators to the exposed endpoint. SeeExample code.

Note: This extension is primarily meant for executing long-runningshell commands/scripts (like nmap, code-analysis' tools) in background from an HTTP request and getting the result at a later time.

• Read theQuickstart from thedocumentation to get started!
• I also highly recommend theExamples section.
• CHANGELOG.

• Python:>=v3.6
• Flask
• Flask-Executor

$ pip install flask flask_shell2http

Create a file calledapp.py.

fromflaskimportFlaskfromflask_executorimportExecutorfromflask_shell2httpimportShell2HTTP# Flask application instanceapp=Flask(__name__)executor=Executor(app)shell2http=Shell2HTTP(app=app,executor=executor,base_url_prefix="/commands/")defmy_callback_fn(context,future):# optional user-defined callback functionprint(context,future.result())shell2http.register_command(endpoint="saythis",command_name="echo",callback_fn=my_callback_fn,decorators=[])

Run the application server with,$ flask run -p 4000.

With <10 lines of code, we succesfully mapped the shell commandecho to the endpoint/commands/saythis.

This section demonstrates how we can now call/ execute commands over HTTP that we just mapped in theexample above.

$ curl -X POST -H'Content-Type: application/json' -d'{"args": ["Hello", "World!"]}' http://localhost:4000/commands/saythis

# You can also add a timeout if you want, default value is 3600 secondsdata= {"args": ["Hello","World!"],"timeout":60}resp=requests.post("http://localhost:4000/commands/saythis",json=data)print("Result:",resp.json())

Note: You can see the JSON schema for the POST requesthere.

returns JSON,

{"key":"ddbe0a94","result_url":"http://localhost:4000/commands/saythis?key=ddbe0a94&wait=false","status":"running"}

Then using thiskey you can query for the result or just by going to theresult_url,

$ curl http://localhost:4000/commands/saythis?key=ddbe0a94&wait=true# wait=true so we do not have to poll

Returns result in JSON,

{"report":"Hello World!\n","key":"ddbe0a94","start_time":1593019807.7754705,"end_time":1593019807.782958,"process_time":0.00748753547668457,"returncode":0,"error":null}

This was initially made to integrate various command-line tools easily withIntel Owl, which I am working on as part of Google Summer of Code.

The name was inspired by the awesome folks over atmsoap/shell2http.