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