The configurations of scripts is presented in this file, in theWebScripts project these files return an error because thearguments section is required. For more information on configuring argumentsclick here (wiki).

To configure a script you can use a specific file.In the main file for configuration (JSON syntax first and second with INI syntax):

{"scripts": {"change_my_password.py":"config_change_my_password"    },"config_change_my_password": {"configuration_file":"./config/files/change_my_password.json"    },}

[scripts]change_my_password.py=config_change_my_password# Define the configuration section ("change_my_password.py") for script named "config_change_my_password"[config_change_my_password]configuration_file=./config/files/change_my_password.json# Define script configuration in a specific file

1. Create ascripts section
2. Define thescript name and thescript section name to configure the script (change_my_password.py=config_change_my_password)
3. Create thescript section (in this example:config_change_my_password)
4. Define the name of the specific file (configuration_file=./config/files/change_my_password.json)

The specific file content (with JSON syntax):

{"script": {"launcher":"python","minimum_access":50,"category":"My Account","args":"change_my_password_args","description":"This script can change your own password (for all authenticated users).","command_generate_documentation":"python\"%(dirname)s/../doc/py_doc.py\"\"%(path)s\""    }}

1. Create thescript section (the content is thescript configuration)
2. Add your configurations

1. Create ascripts section
2. Define thescript name and thescript section name
3. Create thescript section
4. Add your configurations

JSON example:

{"scripts": {"delete_user.py":"config_delete_user"    },"config_delete_user": {"timeout":null,"access_users": [],"no_password":true,"launcher":"python","access_groups": [1000],"content_type":"text/plain","category":"Administration","args":"config_delete_user_args","documentation_content_type":"text/html","path":"./scripts/account/delete_user.py","documentation_file":"./doc/delete_user.html","description":"This script delete user from ID.","command_generate_documentation":"python\"%(dirname)s/../doc/py_doc.py\"\"%(path)s\""    }}

In this configuration:

• Admin users can access it only (group ID 1000 is a default group namedAdmin)
• A user in group ID 1001 and not in group ID 1000 can't access it (group ID is the permission level)

INI example:

[scripts]auth.py=config_auth# Define the configuration section ("config_auth") for script named "auth.py"[config_auth]launcher=python# Define the launcher for this script (if script is executable this line is not necessary)no_password=false# If no_password is true the command line will be written to the logspath=./scripts/account/auth.py# Only necessary if the location of the script is not in "scripts_path"documentation_file=./doc/auth.html# Only needed if the location of the documentation does not match the paths defined in "documentations_path"content_type=text/plain# Define the script output content-type (HTTP headers/javascript interpretation)documentation_content_type=text/html# Define the documentation content-typeminimum_access=0# If a user's group is greater than "minimum_access", the user can use this scriptaccess_groups=0,1# If a user's group is in "access_groups", the user can use this scriptaccess_users=0,1,2# If the user ID is in "access_users", the user can use this scriptargs=auth_args# The arguments are defined in section named "auth_args"description=This script authenticates users.# Short description to help userscategory=My Account# Add a link on the index page in the "My Account" sectiontimeout=10# Timeout for process execution (in seconds)command_generate_documentation=python"%(dirname)s/../doc/py_doc.py""%(path)s"# Command line to generate the documentation file

All users can access the authentication script, permissions are not used for this script (i add it for example).In this configuration:

1. All users with a group greater than 0 can access this script
2. All users in group 0 (group namedNot Authenticated) or 1 (group namedUnknow)
3. Users with ID 0 (user namedNot Authenticated) or ID 1 (user namedUnknow) or ID 2 (user namedAdmin)

This configuration makes no sense because withminimum_access=0 all user can access it, (i add it for example).

• launcher: executable to launch a script (not required and not necessary if the script is executable onLinux, on Windows theWebScripts Server search the default launcher for the file extension)
• path: the path of the script, (absolute or relative path) (not required and not necessary if the script is inscripts_path, a server configuration) it's recommended to defined it for security reason with absolute path, hardening will report a security problem if you don't defined it with absolute path.
• content_type: The content type ofstdout (script output) should betext/plain,text/csv,text/json ortext/html (not required, default istext/plain).Be careful withtext/html output because you can implementsXSS vulnerabilites, escape HTML scpecial characters to protect againstXSS.
• minimum_access: Define who can access it (not required)access documentationwiki
• access_groups: Define who can access it (not required)access documentationwiki
• access_users: Define who can access it (not required)access documentationwiki
• args: Define thearguments section name (not required with no argument)
• description: A short description to help users (not required)
• category: To add a link on the index page (Web Interface), if not defined this script will behidden in the web interface (not in API) (not required)
• timeout: A timeout to kill the process execution of the script (not required). For security reason you should defined it, if not defined it will be reported in the hardening report.
• documentation_file: documentation path and file name (absolute or relative path) (not required and not necessary if the documentation is indocumentations_path, a server configuration)
• documentation_content_type: The content type for documentation page (not required, default istext/html)
• command_generate_documentation: A command to build the documentation file (not required)
• no_password: Ifno_password istrue the command line will be written to the logs (not required, default isfalse). It's important for security reason to log all commands where there is no passwords as arguments (it can be useful forinvestigation,forensic andincident response).
• stderr_content_type: The content type ofstderr (script erreurs) should betext/plain (not required, default istext/plain). Possible values:text/plain andtext/html, for security reason you shouldnever set thestderr_content_type totext/html.
• print_real_time: thestdout (script output) is sent line after line (useful for long scripts and long output). Flush the stdout isnecessary to use this configuration (add a few lines as in theseexampleswiki)

You can use all attributes of script configuration in this command. Script configuration contains all attributes defined in the configuration file and thedirname attribute (the absolute path without the filename).

Syntax:%(<attribute>)s.Example:python "%(dirname)s/../doc/py_doc.py" "%(path)s".

1. Ifminimum_access,access_groups andaccess_users is not definedall users can access it.
2. Ifminimum_access is defined all users with agroup ID and permissions greater thanminimum_access can access it.
3. Ifaccess_groups is defined all users with agroup ID and permissions inaccess_groups can access it.
4. Ifaccess_users is defined all users withuser ID inaccess_users can access it.

All administrators (group ID:1000), the users with ID 5 and 7, all groups with ID greater or equal than 1050 need to acces this script:

{"access_groups": [1000],"access_users": [5,7],"minimum_access":1050}

access_users=5,7access_groups=1000minimum_access=1050

• Use absolute path for launcher.
• Use thepath configuration and use absolute path.
• Set theno_password configuration totrue if no password is in the command-line arguments.
• Set thecontent_type configuration totext/plain as often as possible.
• Never use thestderr_content_type configuration.
• Scripts should have thetimeout configuration defined

You can add your custom attributes and get it in your script.Be careful with custom attributes as they are sent to the/api/ URL.Thesecrets custom configuration is not sent in/api/.

In this example i add two keys (secrets is not send inWebScripts API, andweb_interface_color is send inWebScripts API).

The configuration:

{"scripts": {"example.py":"config_example"    },"config_example": {"description":"Python executable file for the example configuration","secrets": {"key":"azerty"        },"web_interface_color":"orange"    }}

The python script:

#!/usr/bin/env python3# -*- coding: utf-8 -*-fromosimportenvironfromjsonimportloadsconfig=loads(environ["SCRIPT_CONFIG"])key=config["secrets"].get("key")web_interface_color=config.get("web_interface_color")