API

URLs

/api/ (HTTP GET METHOD): JSON response with scripts details/informations
/api/scripts/<script name> (HTTP POST METHOD): JSON response with script stdout (outputs), stderr (errors) and exitcode. A csrf token is added if you use the WEB interface.
/api/script/get/<key> (HTTP GET METHOD): JSON response with single line stdout scripts with output configured in real time

Structures

Responses

Index

{
	"<script name>": {
		"content_type": "text/<html, plain, csv or json>", 
		"documentation_content_type": "text/<html or plain>", 
		"description": "<short description>", 
		"category": "<category>", 
		"name": "<script name>", 
		"args": [
			{
				"default_value": "<default value>", 
				"html_type": "<input type>", 
				"description": "<short description>", 
				"example": "<example>", 
				"input": false, 
				"predefined_values": ["<value1>", "<value2>"], 
				"list": false, 
				"name": "<argument name>"
			}
		]
	}
}

Script execution

{
	"stdout": "<script outputs>", 
	"stderr": "<script  errors>", 
	"code": 0, 
	"Content-Type": "text/<plain or html>", 
	"csrf": "<token>", 
	"error": "<server timeout error>",
	"key": "<key>"
}

stdout: the output of the script. Required, type string.
stderr: script errors. Required, type string.
code: the exit code of the script. Required, type integer or null.
Content-Type: script output content-type. Required, type string, value: text/plain or text/html.
Stderr-Content-Type: script errors content-type. Required, type string, value: text/plain (recommended for security reason) or text/html.
error: WebScripts error (reason to kill the child process). Required, type string.
key: for real time output only, while key is defined the process is not terminated.
csrf: for web browser only, in the response of the POST request only.

Request

Body - Content

A POST HTTP method is required. The content should be a JSON object with an arguments object as attribute (and a csrf_token string as attribute for webbrowser).

For web browser:

{
	"csrf_token": "<token>",
	"arguments": {
		"<argument name>": {
			"value": "<value or list of values>",
			"input": false
		}
	}
}

For client API:

{
	"arguments": {
		"<argument name>": {
			"value": "<value or list of values>",
			"input": false
		}
	}
}

Headers

Some HTTP Headers are required to use scripts with WebScripts API:

Content-Type should be application/json (you can had charset like this: application/json; charset=utf-8).
Origin should be <scheme>://<host> (examples: http://webscript.local, http://webscript.local:8000, https://webscript.local, https://webscript.local:4430).
Referer should be the last visited page, required for webbrowser only.

For authentication you 3 methods: Basic Auth to execute a simple script from a script with credentials prompts, Api-Key to execute a simple script from service and Api Token (use the Session Cookie in Api-Token HTTP header) to execute multiple scripts. The reason why you can't use Basic Auth and Api-Key for multiple executions is the bruteforce protection.

Authentication

The Api-Token HTTP header should be the session cookie (example: SessionID=2:0123456789abcdef). Session cookie is sent by the server on the response of /auth/ script (the /auth/ script should accept --username and --password arguments OR --api-key argument). You can use Api-Token as much as you want but Basic Auth and Api-Key will be blacklisted if you exceed the anti bruteforce configuration.

To use the WebScripts API you can use HTTP BasicAuth or an API key in a Api-Key header. You should never use these authentication methods with a Web Browser because CSRF protection is not enabled.

Example of HTTP flux

Authentication

Using Username and Password

Request /auth/ to authenticate user using username and password:

POST /auth/ HTTP/1.1
Accept-Encoding: identity
Content-Length: 115
Host: 127.0.0.1:8000
User-Agent: WebScripts client
Origin: http://127.0.0.1:8000
Content-Type: application/json
Connection: close

{"arguments": {"--username": {"value": "Admin", "input": false}, "--password": {"value": "Admin", "input": false}}}

Response:

HTTP/1.0 302 Found
Date: Thu, 22 Jun 2016 02:43:52 GMT
Server: WebScripts 2.4.7
Content-Type: text/html; charset=utf-8
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; form-action 'none'; frame-ancestors 'none'
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: origin-when-cross-origin
Cache-Control: no-store
Pragma: no-store
Clear-Site-Data: "cache", "executionContexts"
Feature-Policy: payment 'none'; geolocation 'none'; microphone 'none'; camera 'none'
Permissions-Policy: microphone=(),camera=(),payment=(),geolocation=()
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin
X-Server: WebScripts
Set-Cookie: SessionID=2:5c02e0ce9c3273ee5b19888cc13551396f429afd9a353c96eb693187e6f5364aeede55eb87dc14d70d938d96ff939e632282fd159fce48c4b16ddad3196c44e0; Path=/; SameSite=Strict; Max-Age=3600; Secure; HttpOnly
Content-Length: 0

Using API key

Request /auth/ to authenticate user using API key:

POST /auth/ HTTP/1.1
Accept-Encoding: identity
Content-Length: 219
Host: 127.0.0.1:8000
User-Agent: WebScripts client
Origin: http://127.0.0.1:8000
Content-Type: application/json
Connection: close

{"arguments": {"--api-key": {"value": "AdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdmin", "input": false}}}

Response:

HTTP/1.0 302 Found
Date: Thu, 22 Jun 2016 05:09:45 GMT
Server: WebScripts 2.4.8
Content-Type: text/html; charset=utf-8
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; form-action 'none'; frame-ancestors 'none'
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: origin-when-cross-origin
Cache-Control: no-store
Pragma: no-store
Clear-Site-Data: "cache", "executionContexts"
Feature-Policy: payment 'none'; geolocation 'none'; microphone 'none'; camera 'none'
Permissions-Policy: microphone=(),camera=(),payment=(),geolocation=()
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin
X-Server: WebScripts
Set-Cookie: SessionID=2:7de7040268fead766ebaa1dbf245568efb0cb14b51158cafd2e9e811a396135f96edacf55d144cb5abf4200fee53a070e12cb4cd8ed656ef8d2d488251364710; Path=/; SameSite=Strict; Max-Age=3600; Secure; HttpOnly
Content-Length: 0

Execute script after authentication

Request script execution after authentication:

POST /api/scripts/test_config.py HTTP/1.1
Accept-Encoding: identity
Content-Length: 433
Host: 127.0.0.1:8000
User-Agent: WebScripts client
Origin: http://127.0.0.1:8000
Api-Token: SessionID=2:5c02e0ce9c3273ee5b19888cc13551396f429afd9a353c96eb693187e6f5364aeede55eb87dc14d70d938d96ff939e632282fd159fce48c4b16ddad3196c44e0; Path=/; SameSite=Strict; Max-Age=3600; Secure; HttpOnly
Content-Type: application/json
Connection: close

{"arguments": {"select": {"value": "test", "input": false}, "--timeout": {"value": true, "input": false}, "password": {"value": ["Admin", "Admin"], "input": false}, "--test-date": {"value": "2016-06-22", "input": false}, "test_input": {"value": "abc", "input": false}, "test_number": {"value": 8.8, "input": false}, "test_file": {"value": "file content", "input": true}, "select-input": {"value": ["test", "select"], "input": true}}}

Response (this is a special example with real time output configuration, that send a key to request output lines by lines, it's the reason why stdout and stderr are empty and code is null):

HTTP/1.0 200 OK
Date: Thu, 22 Jun 2016 02:43:53 GMT
Server: WebScripts 2.4.7
Content-Type: application/json; charset=utf-8
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; form-action 'none'; frame-ancestors 'none'
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: origin-when-cross-origin
Cache-Control: no-store
Pragma: no-store
Clear-Site-Data: "cache", "executionContexts"
Feature-Policy: payment 'none'; geolocation 'none'; microphone 'none'; camera 'none'
Permissions-Policy: microphone=(),camera=(),payment=(),geolocation=()
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin
X-Server: WebScripts
Content-Length: 191

{"stdout": "", "stderr": "", "code": null, "Content-Type": "text/plain", "Stderr-Content-Type": "text/plain", "error": null, "key": "EO0IhFUW2xoB-HgjQmvrGj8rpSzy6U6H-EWT9lnRgVBSO7r98brTaQ=="}

Execute script with BasicAuth

Request script execution with Basic Auth:

POST /api/scripts/test_config.py HTTP/1.1
Accept-Encoding: identity
Content-Length: 433
Host: 127.0.0.1:8000
User-Agent: WebScripts client
Origin: http://127.0.0.1:8000
Authorization: Basic QWRtaW46QWRtaW4=
Content-Type: application/json
Connection: close

{"arguments": {"select": {"value": "test", "input": false}, "--timeout": {"value": true, "input": false}, "password": {"value": ["Admin", "Admin"], "input": false}, "--test-date": {"value": "2016-06-22", "input": false}, "test_input": {"value": "abc", "input": false}, "test_number": {"value": 8.8, "input": false}, "test_file": {"value": "file content", "input": true}, "select-input": {"value": ["test", "select"], "input": true}}}

Response:

HTTP/1.0 200 OK
Date: Thu, 22 Jun 2016 04:22:10 GMT
Server: WebScripts 2.4.7
Content-Type: application/json; charset=utf-8
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; form-action 'none'; frame-ancestors 'none'
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: origin-when-cross-origin
Cache-Control: no-store
Pragma: no-store
Clear-Site-Data: "cache", "executionContexts"
Feature-Policy: payment 'none'; geolocation 'none'; microphone 'none'; camera 'none'
Permissions-Policy: microphone=(),camera=(),payment=(),geolocation=()
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin
X-Server: WebScripts
Content-Length: 191

{"stdout": "", "stderr": "", "code": null, "Content-Type": "text/plain", "Stderr-Content-Type": "text/plain", "error": null, "key": "DiJ_9fQSaAMaZGWFUtaAbl2DN5mbusiY69S3-4mXg2wd6jgxqIg8kg=="}

Execute script with API Key

Request /api/ to get informations about scripts and arguments using API key:

GET /api/ HTTP/1.1
Accept-Encoding: identity
Host: 127.0.0.1:8000
User-Agent: WebScripts client
Origin: http://127.0.0.1:8000
Api-Key: AdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdminAdmin
Connection: close

Response:

HTTP/1.0 200 OK
Date: Thu, 22 Jun 2016 05:09:12 GMT
Server: WebScripts 2.4.7
Content-Type: application/json; charset=utf-8
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; form-action 'none'; frame-ancestors 'none'
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: origin-when-cross-origin
Cache-Control: no-store
Pragma: no-store
Clear-Site-Data: "cache", "executionContexts"
Feature-Policy: payment 'none'; geolocation 'none'; microphone 'none'; camera 'none'
Permissions-Policy: microphone=(),camera=(),payment=(),geolocation=()
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin
X-Server: WebScripts
Content-Length: 22610

{"/auth/": {"documentation_content_type": "text/html", "stderr_content_type": "text/plain", "content_type": "text/plain", "description": "This script authenticates users.", "category": "Authentication", "name": "/auth/", "args": [{"javascript_attributs": {}, "default_value": null, "is_advanced": false, "html_type": "text", "description": "Your username (to log in)", "example": "user", "input": false, "predefined_values": null, "list": false, "name": "--username"}, {"javascript_attributs": {}, "default_value": null, "is_advanced": false, "html_type": "password", "description": "Your password (to log in)", "example": "password", "input": null, "name": "--password"}]}}

Request real time output

Request lines for real time output script configuration:

GET /api/script/get/GKUBELTPuZbF2GIWBFll1kojTnnp-eyrX5y1UgFEO2xRC7kGqPQg3g== HTTP/1.1
Accept-Encoding: identity
Host: 127.0.0.1:8000
User-Agent: WebScripts client
Origin: http://127.0.0.1:8000
Api-Token: SessionID=2:7de7040268fead766ebaa1dbf245568efb0cb14b51158cafd2e9e811a396135f96edacf55d144cb5abf4200fee53a070e12cb4cd8ed656ef8d2d488251364710; Path=/; SameSite=Strict; Max-Age=3600; Secure; HttpOnly
Connection: close

Response:

HTTP/1.0 200 OK
Date: Thu, 22 Jun 2016 05:09:52 GMT
Server: WebScripts 2.4.8
Content-Type: application/json; charset=utf-8
Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
Content-Security-Policy: default-src 'self'; form-action 'none'; frame-ancestors 'none'
X-Frame-Options: deny
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: origin-when-cross-origin
Cache-Control: no-store
Pragma: no-store
Clear-Site-Data: "cache", "executionContexts"
Feature-Policy: payment 'none'; geolocation 'none'; microphone 'none'; camera 'none'
Permissions-Policy: microphone=(),camera=(),payment=(),geolocation=()
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Resource-Policy: same-origin
X-Server: WebScripts
Content-Length: 206

{"stdout": "15 seconds...\r\n", "stderr": "", "code": null, "Content-Type": "text/plain", "Stderr-Content-Type": "text/plain", "error": "", "key": "GKUBELTPuZbF2GIWBFll1kojTnnp-eyrX5y1UgFEO2xRC7kGqPQg3g=="}

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

API

API

URLs

Structures

Responses

Index

Script execution

Request

Body - Content

Headers

Authentication

Example of HTTP flux

Authentication

Using Username and Password

Using API key

Execute script after authentication

Execute script with BasicAuth

Execute script with API Key

Request real time output

Clone this wiki locally