Skip to content

Commit 4ee06c7

Browse files
eshaan7eshaan7
committed
Develop (#4)
* added logging support + few optimizations * updated docs + now using RTD with sphinx * fixed codefactor alerts in examples/
1 parent 01b9292 commit 4ee06c7

File tree

19 files changed

+513
-155
lines changed

19 files changed

+513
-155
lines changed

‎.lgtm.yml‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
queries:
2+
- exclude: py/similar-function
3+
- exclude: py/empty-except
4+
- exclude: py/call-to-non-callable
5+
- include: py/undefined-placeholder-variable
6+
- include: py/uninitialized-local-variable
7+
- include: py/request-without-cert-validation
8+
- include: py/return-or-yield-outside-function
9+
- include: py/file-not-closed
10+
- include: py/exit-from-finally
11+
- include: py/ineffectual-statement
12+
- include: py/unused-global-variable
13+
- include: py/hardcoded-credentials
14+
- include: py/import-of-mutable-attribute
15+
- include: py/cyclic-import
16+
- include: py/unnecessary-lambda
17+
- include: py/print-during-import

‎README.md‎

Lines changed: 12 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,15 @@
11
# Flask-Shell2HTTP
22

3+
[![CodeFactor](https://www.codefactor.io/repository/github/eshaan7/flask-shell2http/badge)](https://www.codefactor.io/repository/github/eshaan7/flask-shell2http)
4+
<a href="https://lgtm.com/projects/g/eshaan7/flask-shell2http/context:python">
5+
<img alt="Language grade: Python" src="https://img.shields.io/lgtm/grade/python/g/eshaan7/flask-shell2http.svg?logo=lgtm&logoWidth=18"/>
6+
</a>
37
[![flask-shell2http on pypi](https://img.shields.io/pypi/v/flask-shell2http)](https://pypi.org/project/Flask-Shell2HTTP/)
48

5-
A minimalist [Flask](https://github.com/pallets/flask) extension that serves as a REST API wrapper for python's subprocess API.<br/>
9+
A minimalist [Flask](https://github.com/pallets/flask) extension that serves as a REST API wrapper for python's subprocess API.
610

711
- **Convert any command-line tool into a REST API service.**
8-
- Execute pre-defined shell commands asynchronously and securely from flask's endpoints.
12+
- Execute pre-defined shell commands asynchronously and securely via flask's endpoints.
913
- Designed for development, prototyping or remote control.
1014

1115
Inspired by the work of awesome folks over at [msoap/shell2http](https://github.com/msoap/shell2http).
@@ -18,91 +22,17 @@ Inspired by the work of awesome folks over at [msoap/shell2http](https://github.
1822
- This is useful for internal docker-to-docker communications if you have lots of different binaries. See [real-life example](https://github.com/intelowlproject/IntelOwl/blob/develop/integrations/peframe/app.py).
1923
- Currently, all commands are run asynchronously, so result is not available directly. An option would be provided for this in future release.
2024

21-
> Note: This module is primarily meant for running long-running shell commands/scripts (like nmap, code-analysis' tools) in background and getting the result at a later time.
25+
> Note: This extension is primarily meant for executing long-running
26+
> shell commands/scripts (like nmap, code-analysis' tools) in background from an HTTP request and getting the result at a later time.
2227
23-
## Quick Start
28+
## Documentation / Quick Start
2429

25-
#### Dependencies
30+
[![Documentation Status](https://readthedocs.org/projects/flask-shell2http/badge/?version=latest)](https://flask-shell2http.readthedocs.io/en/latest/?badge=latest)
2631

27-
- Python: `>=v3.6`
28-
- [Flask](https://pypi.org/project/Flask/)
29-
- [Flask-Executor](https://pypi.org/project/Flask-Executor)
30-
31-
#### Install
32-
33-
```bash
34-
$ pip install flask flask_shell2http
35-
```
36-
37-
#### Example
38-
39-
```python
40-
from flask import Flask
41-
from flask_executor import Executor
42-
from flask_shell2http import Shell2HTTP
43-
44-
# Flask application instance
45-
app = Flask(__name__)
46-
47-
executor = Executor(app)
48-
shell2http = Shell2HTTP(app=app, executor=executor, base_url_prefix="/commands/")
49-
50-
shell2http.register_command(endpoint="saythis", command_name="echo")
51-
```
52-
53-
Run the application server with, `$ flask run -p 4000`.
54-
55-
#### Make HTTP calls
56-
57-
```bash
58-
$ curl -X POST -d '{"args": ["Hello", "World!"]}' http://localhost:4000/commands/saythis
59-
```
60-
61-
<details><summary>or using python's requests module,</summary>
62-
63-
```python
64-
data = {"args": ["Hello", "World!"]}
65-
resp = requests.post("http://localhost:4000/commands/saythis", json=data)
66-
print("Result:", resp.json())
67-
```
68-
69-
</details>
70-
71-
returns JSON,
72-
73-
```json
74-
{
75-
"key": "ddbe0a94847c65f9b8198424ffd07c50",
76-
"status": "running"
77-
}
78-
```
79-
80-
Then using this `key` you can query for the result,
81-
82-
```bash
83-
$ curl http://localhost:4000/commands/saythis?key=ddbe0a94847c65f9b8198424ffd07c50
84-
```
85-
86-
Returns result in JSON,
87-
88-
```json
89-
{
90-
"end_time": 1593019807.782958,
91-
"error": "",
92-
"md5": "ddbe0a94847c65f9b8198424ffd07c50",
93-
"process_time": 0.00748753547668457,
94-
"report": {
95-
"result": "Hello World!\n"
96-
},
97-
"start_time": 1593019807.7754705,
98-
"status": "success"
99-
}
100-
```
32+
Read the [Quickstart](https://flask-shell2http.readthedocs.io/quickstart.html)
33+
from the [documentation](https://flask-shell2http.readthedocs.io/) to get started!
10134

10235
## Why?
10336

10437
This was initially made to integrate various command-line tools easily with [IntelOwl](https://github.com/intelowlproject/IntelOwl).
10538

106-
## Example usage
107-
108-
You can find various examples under [examples](examples/).

‎docs/Makefile‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
# Minimal makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = source
9+
BUILDDIR = build
10+
11+
# Put it first so that "make" without argument is like "make help".
12+
help:
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
14+
15+
.PHONY: help Makefile
16+
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎docs/make.bat‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=source
11+
set BUILDDIR=build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

‎docs/source/Examples.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
## Examples
2+
3+
We have created some example python scripts to demonstrate various use-cases. These include extension setup as well as making HTTP calls with python's [requests](https://requests.readthedocs.io/en/master/) module.
4+
5+
- [run_script.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/run_script.py): Execute a script on a succesful POST request to an endpoint.
6+
- [basic.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/basic.py): Map a base command to an endpoint and pass dynamic arguments to it.
7+
- [multiple_files.py](https://github.com/Eshaan7/Flask-Shell2HTTP/blob/master/examples/multiple_files.py): Upload multiple files for a single command.

‎docs/source/Logging.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
## Logging Configuration
2+
3+
This extension logs messages of different severity `INFO`, `DEBUG`, `ERROR`
4+
using the python's inbuilt [logging](https://docs.python.org/3/library/logging.html) module.
5+
6+
There are no default handlers or stream defined for the logger so it's upto the user to define them.
7+
8+
Here's a snippet of code that shows how you can access this extension's logger object and add a custom handler to it.
9+
10+
```python
11+
# python's inbuilt logging module
12+
import logging
13+
# get the flask_shell2http logger
14+
logger = logging.getLogger("flask_shell2http")
15+
# log messages of severity DEBUG or lower to the console
16+
handler = logging.StreamHandler(sys.stdout)
17+
logger.addHandler(handler)
18+
logger.setLevel(logging.DEBUG)
19+
```
20+
21+
Please consult the Flask's official docs on
22+
[extension logs](https://flask.palletsprojects.com/en/1.1.x/logging/#other-libraries) for more details.

‎docs/source/Quickstart.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
## Quick Start
2+
3+
##### Dependencies
4+
5+
* Python: `>=v3.6`
6+
* [Flask](https://pypi.org/project/Flask/)
7+
* [Flask-Executor](https://pypi.org/project/Flask-Executor)
8+
9+
##### Installation
10+
11+
```bash
12+
$ pip install flask flask_shell2http
13+
```
14+
15+
##### Example Program
16+
17+
Create a file called `app.py`.
18+
19+
```python
20+
from flask import Flask
21+
from flask_executor import Executor
22+
from flask_shell2http import Shell2HTTP
23+
24+
# Flask application instance
25+
app = Flask(__name__)
26+
27+
executor = Executor(app)
28+
shell2http = Shell2HTTP(app=app, executor=executor, base_url_prefix="/commands/")
29+
30+
shell2http.register_command(endpoint="saythis", command_name="echo")
31+
```
32+
33+
Run the application server with, `$ flask run -p 4000`.
34+
35+
With <10 lines of code, we succesfully mapped the shell command `echo` to the endpoint `/commands/saythis`.
36+
37+
##### Making HTTP calls
38+
39+
This section demonstrates how we can now call/ execute commands over HTTP that we just mapped in the [example](#example-program) above.
40+
41+
```bash
42+
$ curl -X POST -d '{"args": ["Hello", "World!"]}' http://localhost:4000/commands/saythis
43+
```
44+
45+
<details><summary>or using python's requests module,</summary>
46+
47+
```python
48+
data = {"args": ["Hello", "World!"]}
49+
resp = requests.post("http://localhost:4000/commands/saythis", json=data)
50+
print("Result:", resp.json())
51+
```
52+
53+
</details>
54+
55+
returns JSON,
56+
57+
```json
58+
{
59+
"key": "ddbe0a94847c65f9b8198424ffd07c50",
60+
"status": "running"
61+
}
62+
```
63+
64+
Then using this `key` you can query for the result,
65+
66+
```bash
67+
$ curl http://localhost:4000/commands/saythis?key=ddbe0a94847c65f9b8198424ffd07c50
68+
```
69+
70+
Returns result in JSON,
71+
72+
```json
73+
{
74+
"end_time": 1593019807.782958,
75+
"error": "",
76+
"md5": "ddbe0a94847c65f9b8198424ffd07c50",
77+
"process_time": 0.00748753547668457,
78+
"report": {
79+
"result": "Hello World!\n"
80+
},
81+
"start_time": 1593019807.7754705,
82+
"status": "success"
83+
}
84+
```

‎docs/source/api.rst‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
API Reference
2+
-------------
3+
4+
If you are looking for information on a specific function, class or
5+
method, this part of the documentation is for you.
6+
7+
.. automodule:: flask_shell2http.base_entrypoint
8+
:members:
9+
10+
.. toctree::
11+
:maxdepth: 2

0 commit comments

Comments
 (0)