README rewrite
This commit is contained in:
Josh Uy
parent
c1872295c2
commit
e9a14e8a47
241
readme.md
241
readme.md
|
|
@ -1,68 +1,175 @@
|
||||||
## Piston
|
<h1 align="center">Piston</h1>
|
||||||
|
<h1 align="center">
|
||||||
|
<br>
|
||||||
|
<a href="https://github.com/engineer-man/piston"><img src="https://emkc.org/images/icon_circle_64.png" alt="engineer-man piston"></a>
|
||||||
|
</h1>
|
||||||
|
|
||||||
|
<h3 align="center">A high performance general purpose code execution engine.</h3>
|
||||||
|
<br>
|
||||||
|
|
||||||
|
<p align="center">
|
||||||
|
<a href="https://github.com/ArmynC/ArminC-AutoExec/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
|
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.
|
possibly malicious code without fear from any harmful effects.
|
||||||
It's used in numerous places including
|
</h4>
|
||||||
[EMKC Challenges](https://emkc.org/challenges),
|
<br>
|
||||||
[EMKC Weekly Contests](https://emkc.org/contests), the
|
|
||||||
[Engineer Man Discord Server](https://discord.gg/engineerman) via
|
|
||||||
[I Run Code](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.
|
|
||||||
|
|
||||||
#### Use Public API
|
It's used in numerous places including:
|
||||||
Requires no installation and you can use it immediately. Reference the Versions/Execute sections
|
* [EMKC Challenges](https://emkc.org/challenges),
|
||||||
below to learn about the request and response formats.
|
* [EMKC Weekly Contests](https://emkc.org/contests),
|
||||||
- `GET` `https://emkc.org/api/v1/piston/versions`
|
* [Engineer Man Discord Server](https://discord.gg/engineerman),
|
||||||
- `POST` `https://emkc.org/api/v1/piston/execute`
|
* [I Run Code (Discord Bot)](https://github.com/engineer-man/piston-bot) bot as well as 1300+ other servers
|
||||||
|
and 100+ direct integrations.
|
||||||
|
|
||||||
Important Note: The Piston API is rate limited to 5 requests per second. If you have a need for more requests than that
|
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)
|
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.
|
so we can discuss potentially getting you an unlimited key.
|
||||||
|
|
||||||
#### Cloning and System Dependencies
|
<br>
|
||||||
```
|
|
||||||
# clone and enter repo
|
# Getting Started
|
||||||
git clone https://github.com/engineer-man/piston
|
|
||||||
cd piston/lxc
|
### Host System Package Dependencies
|
||||||
|
|
||||||
|
* NodeJS
|
||||||
|
* lxc
|
||||||
|
* libvirt
|
||||||
|
|
||||||
|
<br>
|
||||||
|
|
||||||
|
If your OS is not documented below, please open pull requests with the correct commands for your OS.
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><span style="font-size:1.43em;">CentOS / RHEL</span></summary>
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash
|
||||||
|
nvm install --lts
|
||||||
|
nvm use --lts
|
||||||
|
|
||||||
# centos/rhel dependencies:
|
|
||||||
yum install -y epel-release
|
yum install -y epel-release
|
||||||
yum install -y lxc lxc-templates debootstrap libvirt
|
yum install -y lxc lxc-templates debootstrap libvirt
|
||||||
systemctl start libvirtd
|
systemctl start libvirtd
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
# ubuntu server 18.04 dependencies:
|
<details>
|
||||||
apt install lxc lxc-templates debootstrap libvirt0
|
<summary><span style="font-size:1.43em;">Ubuntu (18.04)</span></summary>
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash
|
||||||
|
nvm install --lts
|
||||||
|
nvm use --lts
|
||||||
|
|
||||||
|
apt install -y lxc lxc-templates debootstrap libvirt0
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary><span style="font-size:1.43em;">Arch Linux</span></summary>
|
||||||
|
|
||||||
|
```sh
|
||||||
|
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.37.2/install.sh | bash
|
||||||
|
nvm install --lts
|
||||||
|
nvm use --lts
|
||||||
|
|
||||||
# arch dependencies:
|
|
||||||
sudo pacman -S lxc libvirt unzip
|
sudo pacman -S lxc libvirt unzip
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
# everything else:
|
#### After system dependencies are installed, clone this repository:
|
||||||
# not documented, please open pull requests with commands for debian/arch/macos/etc
|
|
||||||
|
```sh
|
||||||
|
# clone and enter repo
|
||||||
|
git clone https://github.com/engineer-man/piston
|
||||||
|
cd piston/lxc
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Installation (simple)
|
#### Installation (simple)
|
||||||
Coming soon.
|
|
||||||
|
|
||||||
#### Installation (advanced/manual)
|
- Coming soon.
|
||||||
See `var/install.txt` for how to create a new LXC container and install all of the required
|
|
||||||
|
#### Installation (advanced)
|
||||||
|
|
||||||
|
- See `var/install.txt` for how to create a new LXC container and install all of the required
|
||||||
software.
|
software.
|
||||||
|
|
||||||
#### CLI Usage
|
<br>
|
||||||
- `lxc/execute [language] [file path] [args]`
|
|
||||||
|
|
||||||
#### API Usage
|
# 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
|
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:
|
LXC then the API must also be running as root. To start the API, run the following:
|
||||||
|
|
||||||
```
|
```
|
||||||
cd api
|
cd api
|
||||||
./start
|
./start
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Base URLs
|
For your own local installation, the API is available at</h3>
|
||||||
When using the public Piston API, use:
|
|
||||||
```
|
|
||||||
https://emkc.org/api/v1/piston
|
|
||||||
```
|
|
||||||
For your own local installation, use:
|
|
||||||
```
|
```
|
||||||
http://127.0.0.1:2000
|
http://127.0.0.1:2000
|
||||||
```
|
```
|
||||||
|
|
@ -135,44 +242,38 @@ Content-Type: application/json
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
#### Supported Languages
|
<br>
|
||||||
- awk
|
|
||||||
- bash
|
|
||||||
- brainfuck
|
|
||||||
- c
|
|
||||||
- cpp
|
|
||||||
- csharp
|
|
||||||
- deno
|
|
||||||
- erlang
|
|
||||||
- elixir
|
|
||||||
- emacs
|
|
||||||
- elisp
|
|
||||||
- go
|
|
||||||
- haskell
|
|
||||||
- java
|
|
||||||
- jelly
|
|
||||||
- julia
|
|
||||||
- kotlin
|
|
||||||
- lua
|
|
||||||
- nasm
|
|
||||||
- node
|
|
||||||
- paradoc
|
|
||||||
- perl
|
|
||||||
- php
|
|
||||||
- python2
|
|
||||||
- python3
|
|
||||||
- ruby
|
|
||||||
- rust
|
|
||||||
- swift
|
|
||||||
- typescript
|
|
||||||
|
|
||||||
#### Principle of Operation
|
# Supported Languages
|
||||||
|
| | |
|
||||||
|
|:---------:|------------|
|
||||||
|
| awk | julia |
|
||||||
|
| bash | kotlin |
|
||||||
|
| brainfuck | lua |
|
||||||
|
| c | nasm |
|
||||||
|
| cpp | node |
|
||||||
|
| csharp | paradoc |
|
||||||
|
| deno | perl |
|
||||||
|
| erlang | php |
|
||||||
|
| elixir | python2 |
|
||||||
|
| emacs | python3 |
|
||||||
|
| elisp | ruby |
|
||||||
|
| go | rust |
|
||||||
|
| haskell | swift |
|
||||||
|
| java | typescript |
|
||||||
|
| jelly | |
|
||||||
|
|
||||||
|
<br>
|
||||||
|
|
||||||
|
# Principle of Operation
|
||||||
Piston utilizes LXC as the primary mechanism for sandboxing. There is a small API written in Node which takes
|
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
|
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.
|
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.).
|
The source file is either ran or compiled and ran (in the case of languages like c, c++, c#, go, etc.).
|
||||||
|
|
||||||
#### Security
|
<br>
|
||||||
|
|
||||||
|
# Security
|
||||||
LXC provides a great deal of security out of the box in that it's separate from the system.
|
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
|
Piston takes additional steps to make it resistant to
|
||||||
various privilege escalation, denial-of-service, and resource saturation threats. These steps include:
|
various privilege escalation, denial-of-service, and resource saturation threats. These steps include:
|
||||||
|
|
@ -186,5 +287,7 @@ various privilege escalation, denial-of-service, and resource saturation threats
|
||||||
- Capping stdout to 65536 characters (resists yes/no bombs and runaway output)
|
- Capping stdout to 65536 characters (resists yes/no bombs and runaway output)
|
||||||
- SIGKILLing misbehaving code
|
- SIGKILLing misbehaving code
|
||||||
|
|
||||||
#### License
|
<br>
|
||||||
|
|
||||||
|
# License
|
||||||
Piston is licensed under the MIT license.
|
Piston is licensed under the MIT license.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue