diff --git a/README.md b/README.md index f173995..2212cd6 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ _For urgent issues and priority support, visit [https://xscode.com/eshaan7/flask [![codecov](https://codecov.io/gh/Eshaan7/Flask-Shell2HTTP/branch/master/graph/badge.svg?token=UQ43PYQPMR)](https://codecov.io/gh/Eshaan7/flask-shell2http/) [![CodeFactor](https://www.codefactor.io/repository/github/eshaan7/flask-shell2http/badge)](https://www.codefactor.io/repository/github/eshaan7/flask-shell2http) - Language grade: Python +Language grade: Python A minimalist [Flask](https://github.com/pallets/flask) extension that serves as a RESTful/HTTP wrapper for python's subprocess API. @@ -18,23 +18,20 @@ A minimalist [Flask](https://github.com/pallets/flask) extension that serves as - 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 and [more](https://flask-shell2http.readthedocs.io/en/stable/Examples.html). - ## Use Cases - Set a script that runs on a succesful POST request to an endpoint of your choice. See [Example code](examples/run_script.py). - Map a base command to an endpoint and pass dynamic arguments to it. See [Example code](examples/basic.py). - Can also process multiple uploaded files in one command. See [Example code](examples/multiple_files.py). - This is useful for internal docker-to-docker communications if you have different binaries distributed in micro-containers. See [real-life example](https://github.com/intelowlproject/IntelOwl/blob/master/integrations/static_analyzers/app.py). -- You can define a callback function/ use signals to listen for process completion. See [Example code](examples/with_callback.py). - * Maybe want to pass some additional context to the callback function ? - * Maybe intercept on completion and update the result ? See [Example code](examples/custom_save_fn.py) +- You can define a callback function/ use signals to listen for process completion. See [Example code](examples/with_callback.py). + - Maybe want to pass some additional context to the callback function ? + - Maybe intercept on completion and update the result ? See [Example code](examples/custom_save_fn.py) - You can also apply [View Decorators](https://flask.palletsprojects.com/en/1.1.x/patterns/viewdecorators/) to the exposed endpoint. See [Example code](examples/with_decorators.py). -- Currently, all commands run asynchronously (default timeout is 3600 seconds), so result is not available directly. An option _may_ be provided for this in future releases for commands that return immediately. > Note: This extension is primarily meant for executing long-running > shell commands/scripts (like nmap, code-analysis' tools) in background from an HTTP request and getting the result at a later time. - ## Documentation [![Documentation Status](https://readthedocs.org/projects/flask-shell2http/badge/?version=latest)](https://flask-shell2http.readthedocs.io/en/latest/?badge=latest) @@ -43,14 +40,13 @@ A minimalist [Flask](https://github.com/pallets/flask) extension that serves as - I also highly recommend the [Examples](https://flask-shell2http.readthedocs.io/en/stable/Examples.html) section. - [CHANGELOG](https://github.com/eshaan7/Flask-Shell2HTTP/blob/master/.github/CHANGELOG.md). - ## Quick Start ##### Dependencies -* Python: `>=v3.6` -* [Flask](https://pypi.org/project/Flask/) -* [Flask-Executor](https://pypi.org/project/Flask-Executor) +- Python: `>=v3.6` +- [Flask](https://pypi.org/project/Flask/) +- [Flask-Executor](https://pypi.org/project/Flask-Executor) ##### Installation @@ -109,9 +105,9 @@ returns JSON, ```json { - "key": "ddbe0a94", - "result_url": "http://localhost:4000/commands/saythis?key=ddbe0a94&wait=false", - "status": "running" + "key": "ddbe0a94", + "result_url": "http://localhost:4000/commands/saythis?key=ddbe0a94&wait=false", + "status": "running" } ``` @@ -131,11 +127,10 @@ Returns result in JSON, "end_time": 1593019807.782958, "process_time": 0.00748753547668457, "returncode": 0, - "error": null, + "error": null } ``` - ## Inspiration This was initially made to integrate various command-line tools easily with [Intel Owl](https://github.com/intelowlproject/IntelOwl), which I am working on as part of Google Summer of Code. diff --git a/docs/source/Examples.md b/docs/source/Examples.md index d16e169..c4b2b97 100644 --- a/docs/source/Examples.md +++ b/docs/source/Examples.md @@ -9,3 +9,4 @@ I have created some example python scripts to demonstrate various use-cases. The - [with_signals.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/with_signals.py): Using [Flask Signals](https://flask.palletsprojects.com/en/1.1.x/signals/) as callback function. - [with_decorators.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/with_decorators.py): Shows how to apply [View Decorators](https://flask.palletsprojects.com/en/1.1.x/patterns/viewdecorators/) to the exposed endpoint. Useful in case you wish to apply authentication, caching, etc. to the endpoint. - [custom_save_fn.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/custom_save_fn.py): There may be cases where the process doesn't print result to standard output but to a file/database. This example shows how to pass additional context to the callback function, intercept the future object after completion and update it's result attribute before it's ready to be consumed. +- [deletion.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/deletion.py): Example demonstrating how to request cancellation/deletion of an already running job. diff --git a/docs/source/index.rst b/docs/source/index.rst index 8f31194..c6922e3 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -23,7 +23,6 @@ A minimalist Flask_ extension that serves as a RESTful/HTTP wrapper for python's - This is useful for internal docker-to-docker communications if you have different binaries distributed in micro-containers. - You can define a callback function/ use signals to listen for process completion. - You can also apply View Decorators to the exposed endpoint. -- Currently, all commands run asynchronously (default timeout is 3600 seconds), so result is not available directly. An option _may_ be provided for this in future release. `Note: This extension is primarily meant for executing long-running shell commands/scripts (like nmap, code-analysis' tools) in background from an HTTP request and getting the result at a later time.`