docs: readme
This commit is contained in:
Thomas Hobson
parent
ac46c1b5bb
commit
72f57ef1ce
|
|
@ -0,0 +1,238 @@
|
|||
<h1 align="center">
|
||||
<a href="https://github.com/engineer-man/piston"><img src="docs/images/icon_circle.svg" width="25" height="25" alt="engineer-man piston"></a>
|
||||
Piston
|
||||
</h1>
|
||||
|
||||
<h3 align="center">A high performance general purpose code execution engine.</h3>
|
||||
<br>
|
||||
|
||||
<p align="center">
|
||||
<a href="https://github.com/engineer-man/piston/commits/master">
|
||||
<img src="https://img.shields.io/github/last-commit/engineer-man/piston.svg?style=for-the-badge&logo=github&logoColor=white"
|
||||
alt="GitHub last commit">
|
||||
<a href="https://github.com/engineer-man/piston/issues">
|
||||
<img src="https://img.shields.io/github/issues/engineer-man/piston.svg?style=for-the-badge&logo=github&logoColor=white"
|
||||
alt="GitHub issues">
|
||||
<a href="https://github.com/engineer-man/piston/pulls">
|
||||
<img src="https://img.shields.io/github/issues-pr-raw/engineer-man/piston.svg?style=for-the-badge&logo=github&logoColor=white"
|
||||
alt="GitHub pull requests">
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
<h4 align="center">
|
||||
<a href="#About">About</a> •
|
||||
<a href="#Public-API">Public API</a> •
|
||||
<a href="#Getting-Started">Getting Started</a> •
|
||||
<a href="#Usage">Usage</a> •
|
||||
<a href="#Supported-Languages">Supported Languages</a> •
|
||||
<a href="#Principle-of-Operation">Principles</a> •
|
||||
<a href="#Security">Security</a> •
|
||||
<a href="#License">License</a>
|
||||
</h4>
|
||||
|
||||
---
|
||||
<br>
|
||||
|
||||
# About
|
||||
|
||||
<h4>
|
||||
Piston is a high performance general purpose code execution engine. It excels at running untrusted and
|
||||
possibly malicious code without fear from any harmful effects.
|
||||
</h4>
|
||||
<br>
|
||||
|
||||
It's used in numerous places including:
|
||||
* [EMKC Challenges](https://emkc.org/challenges),
|
||||
* [EMKC Weekly Contests](https://emkc.org/contests),
|
||||
* [Engineer Man Discord Server](https://discord.gg/engineerman),
|
||||
* [I Run Code (Discord Bot)](https://github.com/engineer-man/piston-bot) bot as well as 1300+ other servers
|
||||
and 100+ direct integrations.
|
||||
|
||||
To get it in your own server, go here: https://emkc.org/run.
|
||||
|
||||
<br>
|
||||
|
||||
# Public API
|
||||
|
||||
- Requires no installation and you can use it immediately.
|
||||
- Reference the Versions/Execute sections below to learn about the request and response formats.
|
||||
|
||||
<br>
|
||||
|
||||
When using the public Piston API, use the base URL:
|
||||
|
||||
```
|
||||
https://emkc.org/api/v1/piston
|
||||
```
|
||||
|
||||
#### GET
|
||||
```
|
||||
https://emkc.org/api/v1/piston/versions
|
||||
```
|
||||
#### POST
|
||||
```
|
||||
https://emkc.org/api/v1/piston/execute
|
||||
```
|
||||
|
||||
> Important Note: The Piston API is rate limited to 5 requests per second. If you have a need for more requests than that
|
||||
and it's for a good cause, please reach out to me (EngineerMan#0001) on [Discord](https://discord.gg/engineerman)
|
||||
so we can discuss potentially getting you an unlimited key.
|
||||
|
||||
<br>
|
||||
|
||||
# Getting Started
|
||||
|
||||
### Host System Package Dependencies
|
||||
|
||||
- Docker
|
||||
- Docker Compose
|
||||
- Node JS
|
||||
|
||||
#### After system dependencies are installed, clone this repository:
|
||||
|
||||
```sh
|
||||
# clone and enter repo
|
||||
git clone https://github.com/engineer-man/piston
|
||||
```
|
||||
|
||||
#### Installation
|
||||
|
||||
- docker-compose up
|
||||
|
||||
#### CLI Usage
|
||||
- `cli/execute [language] [file path] [args]`
|
||||
<br>
|
||||
|
||||
# Usage
|
||||
|
||||
### CLI
|
||||
|
||||
```sh
|
||||
lxc/execute [language] [file path] [args]
|
||||
```
|
||||
|
||||
### API
|
||||
To use the API, it must first be started. Please note that if root is required to access
|
||||
LXC then the API must also be running as root. To start the API, run the following:
|
||||
|
||||
```
|
||||
cd api
|
||||
./start
|
||||
```
|
||||
|
||||
For your own local installation, the API is available at:
|
||||
|
||||
```
|
||||
http://127.0.0.1:2000
|
||||
```
|
||||
|
||||
#### Versions Endpoint
|
||||
`GET /versions`
|
||||
This endpoint will return the supported languages along with the current version and aliases. To execute
|
||||
code for a particular language using the `/execute` endpoint, either the name or one of the aliases must
|
||||
be provided.
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
[
|
||||
{
|
||||
"name": "awk",
|
||||
"aliases": ["awk"],
|
||||
"version": "1.3.3"
|
||||
},
|
||||
{
|
||||
"name": "bash",
|
||||
"aliases": ["bash"],
|
||||
"version": "4.4.20"
|
||||
},
|
||||
{
|
||||
"name": "c",
|
||||
"aliases": ["c"],
|
||||
"version": "7.5.0"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### Execute Endpoint
|
||||
`POST /execute`
|
||||
This endpoint requests execution of some arbitrary code.
|
||||
- `language` (**required**) The language to use for execution, must be a string and supported by Piston (see list below).
|
||||
- `source` (**required**) The source code to execute, must be a string.
|
||||
- `stdin` (*optional*) The text to pass as stdin to the program. Must be a string or left out of the request.
|
||||
- `args` (*optional*) The arguments to pass to the program. Must be an array or left out of the request.
|
||||
```json
|
||||
{
|
||||
"language": "js",
|
||||
"source": "console.log(process.argv)",
|
||||
"stdin": "",
|
||||
"args": [
|
||||
"1",
|
||||
"2",
|
||||
"3"
|
||||
]
|
||||
}
|
||||
```
|
||||
A typical response upon successful execution will contain the `language`, `version`, `output` which
|
||||
is a combination of both `stdout` and `stderr` but in chronological order according to program output,
|
||||
as well as separate `stdout` and `stderr`.
|
||||
```json
|
||||
HTTP/1.1 200 OK
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"ran": true,
|
||||
"language": "js",
|
||||
"version": "12.13.0",
|
||||
"output": "[ '/usr/bin/node',\n '/tmp/code.code',\n '1',\n '2',\n '3' ]",
|
||||
"stdout": "[ '/usr/bin/node',\n '/tmp/code.code',\n '1',\n '2',\n '3' ]",
|
||||
"stderr": ""
|
||||
}
|
||||
```
|
||||
If a problem exists with the request, a `400` status code is returned and the reason in the `message` key.
|
||||
```json
|
||||
HTTP/1.1 400 Bad Request
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"message": "Supplied language is not supported by Piston"
|
||||
}
|
||||
```
|
||||
|
||||
<br>
|
||||
|
||||
# Supported Languages
|
||||
|
||||
`python`,
|
||||
|
||||
|
||||
<br>
|
||||
<!--
|
||||
# Principle of Operation
|
||||
Piston utilizes LXC as the primary mechanism for sandboxing. There is a small API written in Node which takes
|
||||
in execution requests and executes them in the container. High level, the API writes
|
||||
a temporary source and args file to `/tmp` and that gets mounted read-only along with the execution scripts into the container.
|
||||
The source file is either ran or compiled and ran (in the case of languages like c, c++, c#, go, etc.).
|
||||
|
||||
<br>
|
||||
<!--
|
||||
# Security
|
||||
LXC provides a great deal of security out of the box in that it's separate from the system.
|
||||
Piston takes additional steps to make it resistant to
|
||||
various privilege escalation, denial-of-service, and resource saturation threats. These steps include:
|
||||
- Disabling outgoing network interaction
|
||||
- Capping max processes at 64 (resists `:(){ :|: &}:;`, `while True: os.fork()`, etc.)
|
||||
- Capping max files at 2048 (resists various file based attacks)
|
||||
- Mounting all resources read-only (resists `sudo rm -rf --no-preserve-root /`)
|
||||
- Cleaning up all temp space after each execution (resists out of drive space attacks)
|
||||
- Running as a variety of unprivileged users
|
||||
- Capping runtime execution at 3 seconds
|
||||
- Capping stdout to 65536 characters (resists yes/no bombs and runaway output)
|
||||
- SIGKILLing misbehaving code
|
||||
-->
|
||||
<br>
|
||||
<!-- Someone please do this -->
|
||||
|
||||
# License
|
||||
Piston is licensed under the MIT license.
|
||||
|
|
@ -0,0 +1,32 @@
|
|||
<?xml version="1.0" encoding="utf-8"?>
|
||||
<!-- Generator: Adobe Illustrator 24.2.3, SVG Export Plug-In . SVG Version: 6.00 Build 0) -->
|
||||
<svg version="1.1" id="Logo" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
|
||||
viewBox="0 0 1024 1024" style="enable-background:new 0 0 1024 1024;" xml:space="preserve">
|
||||
<style type="text/css">
|
||||
.st0{fill:url(#Circle_1_);}
|
||||
.st1{fill:#00E300;}
|
||||
.st2{fill:#FFFFFF;}
|
||||
</style>
|
||||
<radialGradient id="Circle_1_" cx="512" cy="512" r="512" gradientUnits="userSpaceOnUse">
|
||||
<stop offset="0" style="stop-color:#0B0B0B"/>
|
||||
<stop offset="1" style="stop-color:#1B1B1B"/>
|
||||
</radialGradient>
|
||||
<path id="Circle" class="st0" d="M512,1024L512,1024c282.77,0,512-229.23,512-512v0C1024,229.23,794.77,0,512,0h0
|
||||
C229.23,0,0,229.23,0,512v0C0,794.77,229.23,1024,512,1024z"/>
|
||||
<g id="E">
|
||||
<path class="st1" d="M218,840.5c-4.31,0-8.4-1.92-11.15-5.23c-2.75-3.32-3.89-7.68-3.1-11.92l117-628
|
||||
c1.28-6.87,7.27-11.84,14.25-11.84h427c3.58,0,7.03,1.32,9.69,3.72l99,89c4.47,4.01,5.99,10.37,3.84,15.97
|
||||
c-2.15,5.61-7.53,9.31-13.54,9.31H481.02l-28.52,151H541c3.58,0,7.03,1.32,9.69,3.72l99,89c4.47,4.01,5.99,10.37,3.84,15.97
|
||||
c-2.15,5.61-7.53,9.31-13.54,9.31H430.03l-28.55,152H771c6.37,0,11.99,4.15,13.86,10.24c1.87,6.08-0.45,12.68-5.71,16.26l-131,89
|
||||
c-2.4,1.63-5.24,2.51-8.15,2.51H218z"/>
|
||||
<path d="M762,198l99,89H469l-34,180h106l99,89H418l-34,181h387l-131,89H218l117-628H762 M762,169H335
|
||||
c-13.97,0-25.95,9.96-28.51,23.69l-117,628c-1.58,8.48,0.69,17.21,6.2,23.84C201.2,851.16,209.38,855,218,855h422
|
||||
c5.81,0,11.49-1.75,16.3-5.01l131-89c10.53-7.16,15.16-20.34,11.42-32.51C794.98,716.3,783.73,708,771,708H418.95l23.1-123H640
|
||||
c12.01,0,22.78-7.4,27.08-18.62c4.3-11.21,1.24-23.92-7.69-31.95l-99-89c-5.32-4.79-12.23-7.43-19.39-7.43h-71.01l23.04-122H861
|
||||
c12.01,0,22.78-7.4,27.08-18.62c4.3-11.21,1.24-23.92-7.69-31.95l-99-89C776.06,171.65,769.16,169,762,169L762,169z"/>
|
||||
</g>
|
||||
<g id="Highlight">
|
||||
<polygon id="Top" class="st2" points="640,556 541,467 435,467 469,287 645.78,287 632.79,198 378,198 430.19,556 "/>
|
||||
<polygon id="Bottom" class="st2" points="456.57,737 469.55,826 640,826 716.83,773.81 711.45,737 "/>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 2.1 KiB |
Loading…
Reference in New Issue