# Flask-Terminal
Flask-Terminal is a bad idea wrapped in an even worse implementation
Use this with care, it is a shell on your server
- [Flask-Terminal](#flask-terminal)
- [Genesis](#genesis)
- [Overview](#overview)
- [Features](#features)
- [Getting started](#getting-started)
- [Security](#security)
- [Requirements](#requirements)
- [Quickstart](#quickstart)
## Genesis
While running a docker instance with the need to do adhoc commands to interact with a mounted volume
We looked for some sort of terminal that would run in flask as a blueprint, none to be found.
Wrote our own, heavily inspired by Chad Smith's https://github.com/cs01/pyxtermjs
Flask-Terminal employs Flask and xterm.js to deliver a real-time terminal experience, enabling the execution of terminal within a web browser.
## Overview
The backend of Flask-Terminal is built on Flask, utilizing python-pty for pseudo-terminal emulation, enabling shell command execution.
The frontend leverages xterm.js for rendering the terminal interface.
Communication is handled through HTTP polling, circumventing the need for WebSockets.
The application is structured as a Flask Blueprint, allowing ease of integration into larger Flask applications.
## Features
- **Browser-based Terminal**: Provides a terminal interface within the browser using xterm.js.
- **Command Execution**: Supports the execution of /bin/sh commands, including the capability to spawn additional shells.
- **Real-time Output**: Displays command execution output in real-time, facilitated by HTTP polling.
- **Command Logging**: Utilizes a Python logger to log terminal activities, aiding in audit and debugging.
.gif)
## Getting started
### Security
We cannot stress how much you need to secure this application, and recommend to enable only as needed and disable immediately afterwards.
To add security to a blueprint please review how we do this with [Flask File Explorer](https://github.com/thevgergroup/flask-file-explorer?tab=readme-ov-file#flask-login-with-a-blueprint)
### Requirements
- Python 3.9 or newer
- Flask web framework
- xterm.js
- A modern web browser
### Quickstart
Installation
```sh
pip install flask-terminal
```
Configuration within flask
Ensure you implement some level of authentication in your application
```python
from flask import Flask
from flask_terminal import terminal_blueprint, configure_logger
app = Flask(__name__)
app.logger = configure_logger('flask_terminal')
app.config['SECRET_KEY'] = 'your_secret_key_here'
# Register the terminal blueprint
app.register_blueprint(terminal_blueprint, url_prefix='/terminal')
@app.route('/ping')
def ping():
app.logger.info("Accessed /ping route")
try:
app.logger.info("Successfully returned 'pong'")
return 'pong', 200
except Exception as e:
app.logger.error(f"Error in ping route: {e}", exc_info=True)
return "An error occurred", 500
####
## IMPLEMENT SOME SORT OF SECURITY
## Around your application, below is an example
###
def is_authenticated():
"""Check if the user is authenticated based on a token stored in the session."""
# Example logic for checking if a user is authenticated
return 'user_token' in session and session['user_token'] == 'your_secure_token'
@terminal_blueprint.before_request
def before_request_func():
if not is_authenticated():
# Redirect to login page or return an error
current_app.logger.info("User not authenticated, redirecting to login.")
return redirect('/login') # Adjusted to use a direct path
if __name__ == '__main__':
app.run(port=8080)
```
Launch your flask app as normal
```sh
flask -A app.py --debug run --port 8000
```
This will now make the terminal available at http://localhost:8080/terminal
The URL can be configured via the url_prefix
```python
app.register_blueprint(terminal_blueprint, url_prefix='/terminal')
```
Raw data
{
"_id": null,
"home_page": "https://github.com/thevgergroup/flask-terminal",
"name": "flask-terminal",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "flask, terminal, browser, shell",
"author": "patrick o'leary",
"author_email": "pjaol@pjaol.com",
"download_url": "https://files.pythonhosted.org/packages/14/03/f449bdb4b12b6425e5f6123bc9158b8d4e119fef6dc7bad385af52abeb2f/flask_terminal-0.2.1.tar.gz",
"platform": null,
"description": "# Flask-Terminal\n\nFlask-Terminal is a bad idea wrapped in an even worse implementation\nUse this with care, it is a shell on your server\n- [Flask-Terminal](#flask-terminal)\n - [Genesis](#genesis)\n - [Overview](#overview)\n - [Features](#features)\n - [Getting started](#getting-started)\n - [Security](#security)\n - [Requirements](#requirements)\n - [Quickstart](#quickstart)\n\n\n## Genesis \nWhile running a docker instance with the need to do adhoc commands to interact with a mounted volume\nWe looked for some sort of terminal that would run in flask as a blueprint, none to be found.\nWrote our own, heavily inspired by Chad Smith's https://github.com/cs01/pyxtermjs\n\nFlask-Terminal employs Flask and xterm.js to deliver a real-time terminal experience, enabling the execution of terminal within a web browser.\n\n## Overview\n\nThe backend of Flask-Terminal is built on Flask, utilizing python-pty for pseudo-terminal emulation, enabling shell command execution. \nThe frontend leverages xterm.js for rendering the terminal interface. \nCommunication is handled through HTTP polling, circumventing the need for WebSockets. \nThe application is structured as a Flask Blueprint, allowing ease of integration into larger Flask applications.\n\n\n## Features\n\n- **Browser-based Terminal**: Provides a terminal interface within the browser using xterm.js.\n- **Command Execution**: Supports the execution of /bin/sh commands, including the capability to spawn additional shells.\n- **Real-time Output**: Displays command execution output in real-time, facilitated by HTTP polling.\n- **Command Logging**: Utilizes a Python logger to log terminal activities, aiding in audit and debugging.\n\n.gif)\n\n## Getting started\n\n### Security\nWe cannot stress how much you need to secure this application, and recommend to enable only as needed and disable immediately afterwards.\nTo add security to a blueprint please review how we do this with [Flask File Explorer](https://github.com/thevgergroup/flask-file-explorer?tab=readme-ov-file#flask-login-with-a-blueprint)\n\n\n### Requirements\n\n- Python 3.9 or newer\n- Flask web framework\n- xterm.js\n- A modern web browser\n\n### Quickstart\n\nInstallation\n```sh\npip install flask-terminal\n```\n\nConfiguration within flask\nEnsure you implement some level of authentication in your application\n\n```python\n\nfrom flask import Flask\nfrom flask_terminal import terminal_blueprint, configure_logger\n\n\napp = Flask(__name__)\napp.logger = configure_logger('flask_terminal')\n\napp.config['SECRET_KEY'] = 'your_secret_key_here'\n\n# Register the terminal blueprint\napp.register_blueprint(terminal_blueprint, url_prefix='/terminal')\n\n@app.route('/ping')\ndef ping():\n app.logger.info(\"Accessed /ping route\")\n try:\n app.logger.info(\"Successfully returned 'pong'\")\n return 'pong', 200\n except Exception as e:\n app.logger.error(f\"Error in ping route: {e}\", exc_info=True)\n return \"An error occurred\", 500\n\n####\n## IMPLEMENT SOME SORT OF SECURITY \n## Around your application, below is an example\n###\ndef is_authenticated():\n \"\"\"Check if the user is authenticated based on a token stored in the session.\"\"\"\n # Example logic for checking if a user is authenticated\n return 'user_token' in session and session['user_token'] == 'your_secure_token'\n\n@terminal_blueprint.before_request\ndef before_request_func():\n if not is_authenticated():\n # Redirect to login page or return an error\n current_app.logger.info(\"User not authenticated, redirecting to login.\")\n return redirect('/login') # Adjusted to use a direct path\n\n\n\nif __name__ == '__main__':\n app.run(port=8080)\n```\n\nLaunch your flask app as normal\n```sh\nflask -A app.py --debug run --port 8000\n```\n\nThis will now make the terminal available at http://localhost:8080/terminal\nThe URL can be configured via the url_prefix\n```python\napp.register_blueprint(terminal_blueprint, url_prefix='/terminal')\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Browser based terminal for flask, use with hyper HYPER caution",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/thevgergroup/flask-terminal",
"Repository": "https://github.com/thevgergroup/flask-terminal"
},
"split_keywords": [
"flask",
" terminal",
" browser",
" shell"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d5ba84852aff0b1402b6c25cff14a4af177490f699f26e260a991006ee44a26a",
"md5": "d5380eb6563e34c62a6fe0f7a31cd885",
"sha256": "39812d4c97e6f22f4177ec3ac2c5ff2b13f7f6969e975f32f3d906700c307870"
},
"downloads": -1,
"filename": "flask_terminal-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d5380eb6563e34c62a6fe0f7a31cd885",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 8554,
"upload_time": "2024-04-06T17:50:21",
"upload_time_iso_8601": "2024-04-06T17:50:21.798327Z",
"url": "https://files.pythonhosted.org/packages/d5/ba/84852aff0b1402b6c25cff14a4af177490f699f26e260a991006ee44a26a/flask_terminal-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "1403f449bdb4b12b6425e5f6123bc9158b8d4e119fef6dc7bad385af52abeb2f",
"md5": "33c75bf8923573b9b2e40ef46060128f",
"sha256": "153e04dbcc7e9daf5d176f8adf198669f25acc9a47f8483bec44027d9e7c7546"
},
"downloads": -1,
"filename": "flask_terminal-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "33c75bf8923573b9b2e40ef46060128f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 8219,
"upload_time": "2024-04-06T17:50:23",
"upload_time_iso_8601": "2024-04-06T17:50:23.392395Z",
"url": "https://files.pythonhosted.org/packages/14/03/f449bdb4b12b6425e5f6123bc9158b8d4e119fef6dc7bad385af52abeb2f/flask_terminal-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-06 17:50:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thevgergroup",
"github_project": "flask-terminal",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "flask-terminal"
}
JSON
