infrabot-io.github.io

Documentation

Documentation for infrabot


Example scripts


Before exploring examples please consider to look at arguments which PowerShell can get here.


Example 1

Lets say that you want to create a command which accepts one or more arguments and you want to show specific answer based on what PowerShell script returns. It is preferred to use this script template when command execute type is 3 - PowerShell with custom result answers with sending arguments to script.

			            	
# We check if our arguments count is more than 0
If ($args.Count -gt 0) {
    # We are getting first argument value
    $arg1 = $args[0]
    
    # If you have more than 1 arguments you can add this
    # $arg2 = $args[1]
    # $arg3 = $args[2]
    # ... etc
    
    # We put our main script content into TRY CATCH construction to catch errors.
    # Your code still can perform without TRY CATCH construction. This is just an
    # example.
    try {
        # Begin Some Cool Stuff
        
        # End of Some Cool stuff
        
        # Here you can write IF ELSE construction, but we assume that if something 
        # wrong happens CATCH part will be executed. ATTENTION: Sometimes it is  
        # essential to  write -NoNewline argument here. So only character specified 
        # will be given  back without new lines, spaces or any other unnecessary mess.   
        # It is necessary when you check output in command_execute_results when  
        # comparing values with result_value, especially when result_checktype is - 
        # "1 - if result from Script or Executable Equals". 
        Write-Host -NoNewline 1
    }
    catch {
    	# If error happens we just output "2" (without quotes). Because of the 
    	# -NoNewline parameter no spaces or new lines will be returned.
        Write-Host -NoNewline 2
    }
}
else {
	# If script got no arguments  we just output "0" (without quotes). Because of the 
    # -NoNewline parameter no spaces or new lines will be returned.
    Write-Host -NoNewline 0
}
							
			            

For the given example script minimal configuration in config.json file will be:

			            	
{
    "command_starts_with": "/somecommand",
    "command_data_id": [],
    "command_execute_file": "C:\\Program Files\\infrabot.io\\tools\\MyNewScript.ps1",
    "command_help_manual": "Does some cool stuff. To use this command send `/somecommand server01` to bot",
    "command_help_short": "Some cool stuff",
    "command_author": "infrabot.io",
    "command_version": "1.0.0.0",
    "command_website": "https://infrabot.io",
    "command_default_error": "Cool stuff with name `{DATA}` was not found! Unexpected error!",
    "command_execute_type": 3,
    "command_allowed_users_id": [],
    "command_allowed_chats_id": [],
    "command_show_in_get_commands_list": true,
    "command_execute_results": [
        {
            "result_value": "0",
            "result_output": "Cool stuff with name `{DATA}` was not found! You did not send an argument or arguments to command. Example: /somecommand server01",
            "result_checktype": 1
        },
        {
            "result_value": "1",
            "result_output": "Cool stuff with `{DATA}` has been executed successfully!",
            "result_checktype": 1
        },
        {
            "result_value": "2",
            "result_output": "Your cool stuff with `{DATA}` has not been executed! Some error occured during execution!",
            "result_checktype": 1
        }
    ]
},
			            	
			            

From the example shown above we get the next logic:

  • User sends /somecommand server01 command to telegram Bot
  • Bot accepts that command, and tries to find it in the configuration file in telegram_commands matching with command_starts_with.
  • If user has access to send commands to Bot generally, and has access to that specific command (learn how to do it here), then Bot looks at command_execute_type parameter.
  • Because of the value 3 in the command_execute_type parameter, bot will run PowerShell and send file to it for execution, specified in command_execute_file with arguments.
  • Script in the example will be executed and will return 0 or 1 or 2 value.
  • Bot will look at command_execute_results list and begin to perform steps in the order specified in the list.

    Bot will look at the first result_checktype and perform specified:
    • Because of result_checktype of the first result is 1, Bot will perform exact compare (Equals, case sensitive), with result_value. If our script has returned exactly 0, then message Cool stuff with name `{DATA}` was not found! You did not send an argument or arguments to command. Example: /somecommand server01 will be returned to user. Note that {DATA} - specified here will be replaced with all arguments which have been sent to command, {RESULT} - will be replaced with output received from script.
    • If message to user has been sent then the result check process will be stopped.

    Bot will look at the second result_checktype and perform specified:
    • Because of result_checktype of the second result is 1, Bot will perform exact compare (Equals, case sensitive), with result_value. If our script has returned exactly 1, then message Cool stuff with `{DATA}` has been executed successfully! will be returned to user. Note that {DATA} - specified here will be replaced with all arguments which have been sent to command, {RESULT} - will be replaced with output received from script.
    • If message to user has been sent then the result check process will be stopped.

    Bot will look at the third result_checktype and perform specified:
    • Because of result_checktype of the third result is 1, Bot will perform exact compare (Equals, case sensitive), with result_value. If our script has returned exactly 1, then message Your cool stuff with `{DATA}` has not been executed! Some error occured during execution! will be returned to user. Note that {DATA} - specified here will be replaced with all arguments which have been sent to command, {RESULT} - will be replaced with output received from script.
    • If message to user has been sent then the result check process will be stopped.


Example 2

Lets say that you want to create a command which accepts one or more arguments, but sends all the output from PowerShell script back to us. It is preferred to use this script template when command execute type is 3 - PowerShell with custom result answers with sending arguments to script.

			            	
# We check if our arguments count is more than 0
If ($args.Count -gt 0) {
    # We are getting first argument value
    $arg1 = $args[0]
    
    # If you have more than 1 arguments you can add this
    # $arg2 = $args[1]
    # $arg3 = $args[2]
    # ... etc
    
    # We put our main script content into TRY CATCH construction to catch errors.
    # Your code still can perform without TRY CATCH construction. This is just an
    # example.
    try {
        # Begin Some Cool Stuff
        
        # End of Some Cool stuff
        
        # Here you can write IF ELSE construction, but we assume that if something 
        # wrong happens CATCH part will be executed. ATTENTION: Sometimes it is  
        # essential to  write -NoNewline argument here. So only character specified 
        # will be given  back without new lines, spaces or any other unnecessary mess.   
        # It is necessary when you check output in command_execute_results when  
        # comparing values with result_value, especially when result_checktype is - 
        # "1 - if result from Script or Executable Equals". 
        Write-Host "Some looooong text, for example output from ipconfig"
    }
    catch {
    	# If error happens we just output "2" (without quotes). Because of the 
    	# -NoNewline parameter no spaces or new lines will be returned.
        Write-Host -NoNewline 2
    }
}
else {
    # If script got no arguments  we just output "0" (without quotes). Because of the 
    # -NoNewline parameter no spaces or new lines will be returned.
    Write-Host -NoNewline 0
}
							
			            

For the given example script minimal configuration in config.json file will be:

			            	
{
    "command_starts_with": "/somecommand2",
    "command_data_id": [],
    "command_execute_file": "C:\\Program Files\\infrabot.io\\tools\\MyNewScript2.ps1",
    "command_help_manual": "Does some cool stuff 2",
    "command_help_short": "Some cool stuff 2",
    "command_author": "infrabot.io",
    "command_version": "1.0.0.0",
    "command_website": "https://infrabot.io",
    "command_default_error": "Cool stuff with name `{DATA}` was not found! Unexpected error!",
    "command_execute_type": 3,
    "command_allowed_users_id": [],
    "command_allowed_chats_id": [],
    "command_show_in_get_commands_list": true,
    "command_execute_results": [
        {
            "result_value": "0",
            "result_output": "Cool stuff with `{DATA}` was not performed! Arguments were not sent to script",
            "result_checktype": 1
        },
        {
            "result_value": "2",
            "result_output": "Cool stuff with `{DATA}` was not performed! Error occurred!",
            "result_checktype": 1
        },
        {
            "result_value": "",
            "result_output": "{RESULT}",
            "result_checktype": 2
        }
    ]
},
			            	
			            

From the example shown above we get the next logic:

  • User sends /somecommand2 server01 command to telegram Bot
  • Bot accepts that command, and tries to find it in the configuration file in telegram_commands matching with command_starts_with.
  • If user has access to send commands to Bot generally, and has access to that specific command (learn how to do it here), then Bot looks at command_execute_type parameter.
  • Because of the value 3 in the command_execute_type parameter, bot will run PowerShell and send file to it for execution, specified in command_execute_file with arguments.
  • Script in the example will be executed and will return some text.
  • Bot will look at command_execute_results list and begin to perform steps in the order specified in the list.

    Bot will look at the first result_checktype and perform specified:
    • Because of result_checktype of the first result is 1, Bot will perform exact compare (Equals, case sensitive), with result_value. If our script has returned exactly 0, then message Cool stuff with `{DATA}` was not performed! Arguments were not sent to script will be returned to user. Note that {DATA} - specified here will be replaced with all arguments which have been sent to command, {RESULT} - will be replaced with output received from script.
    • If message to user has been sent then the result check process will be stopped.

    Bot will look at the second result_checktype and perform specified:
    • Because of result_checktype of the second result is 1, Bot will perform exact compare (Equals, case sensitive), with result_value. If our script has returned exactly 2, then message Cool stuff wit `{DATA}` was not performed! Error occurred! will be returned to user. Note that {DATA} - specified here will be replaced with all arguments which have been sent to command, {RESULT} - will be replaced with output received from script.
    • If message to user has been sent then the result check process will be stopped.

    Bot will look at the third result_checktype and perform specified:
    • Because of result_checktype of the third result is 2, Bot will perform string Contains check (Contains, case sensitive), with result_value. Since value in the result_value is "", it will always succeed. So all the output from script will be returned to user. Note that {DATA} - specified here will be replaced with all arguments which have been sent to command, {RESULT} - will be replaced with output received from script.
    • The result check process will be stopped.

    Note that this check is third in the list. Third check will be always true, so it will block next checks. Specifying execute results after this one is useless, because third check will always succeed and block execution of the next checks.


Example 3

Lets say that you want to create a command which does not accept arguments, but sends all the output from PowerShell script back to us. It is preferred to use this script template when command execute type is 4 - PowerShell with ignoring result all output and forwarding it directly to you without sending arguments to script.

			            	
ipconfig
							
			            

For the given example script minimal configuration in config.json file will be:

			            	
{
    "command_starts_with": "/gethostipconfig",
    "command_data_id": [
        0
    ],
    "command_execute_file": "C:\\Program Files\\infrabot.io\\tools\\GetHostIpConfig.ps1",
    "command_help_manual": "Shows IPCONFIG of the host where BOT works. Write `/gethostipconfig` to get host IPCONFIG",
    "command_help_short": "Shows IPCONFIG of the host where BOT works",
    "command_author": "infrabot.io",
    "command_version": "1.0.0.0",
    "command_website": "https://infrabot.io",
    "command_default_error": "",
    "command_execute_type": 4,
    "command_allowed_users_id": [],
    "command_allowed_chats_id": [],
    "command_show_in_get_commands_list": true,
    "command_execute_results": []
},
			            	
			            
  • User sends /gethostipconfig command to telegram Bot
  • Bot accepts that command, and tries to find it in the configuration file in telegram_commands matching with command_starts_with.
  • If user has access to send commands to Bot generally, and has access to that specific command (learn how to do it here), then Bot looks at command_execute_type parameter.
  • Because of the value 4 in the command_execute_type parameter, bot will run PowerShell and send file to it for execution, specified in command_execute_file without arguments.
  • Script in the example will be executed and will return some text, which will be shown directly to user.



The same configuration logic must be set for your custom application.

Infrabot comes with default set of plugins which are located in the C:\Program Files\infrabot.io\plugins folder.