Run external command

You can run a standalone external command, for example an external program, script file or Python script, using the Run external command content rule. This content rule allows you to run an executable program or script that performs processing that Secure Email Gateway does not support by default.

For example, this feature may be used when you have a Bash script that wants to copy every image that is sent out of company and stored on disk on the Gateway.

This feature should not be used for actions that might take minutes to perform as this will impact mail flow.

Run external command content rule

In order for the Run external command content rule to trigger, the conditions set in the Which Media Types and Run External Command clauses must be met by the message or item being processed.

Which Media Types clause

See What To Look For? clauses for information.

Run External Command clause

The Run External Command clause looks for details of the executable program or script that Secure Email Gateway will attempt to run.

Specify the following fields in the Run External Command clause to provide Secure Email Gateway with details about the executable program or script:

External Command: The full path and file name of the executable program or script.

You must set the correct permissions on the executable file. Files must be accessible and executable by the user gw-services or by the group cs-adm.

Example user:

chown gw-services /my/app/location/myapp

chmod u+x /my/app/location/myapp

Example group:

chown :cs-adm /my/app/location/myapp

chmod g+x /my/app/location/myapp

Command line parameters: The command-line parameters for the executable program or script.

For the executable program or script to run on content, you must enter the %FILENAME% token. Secure Email Gateway uses the %FILENAME% token to relay the file name which the executable program or script must run.

Enter the %LOGNAME% token to ensure the executable program or script generates a log file .

You can use both the %FILENAME% and %LOGNAME% tokens at the same time. You can also use Property tokens in the command line parameters field. See the "External program tokens" section in this topic.

If you specify the %LOGNAME% token as a command line parameter, you can use the %LOGTEXT% token in the Description field on the Response Codes table. See the "Responses" section in this topic.

Timeout (in seconds): The permitted amount of time, in seconds, for Secure Email Gateway to run the executable program or script on a single message or item. If this limit is exceeded, Secure Email Gateway stops running the executable program or script and triggers either the Message Processing Fails content rule (if you have it applied to a policy route) or the global Message Processing Failure rule.

Log Extract

The portion of the log file generated by the executable program from which Secure Email Gateway uses to extract text.

Enter the text that precedes the information to be extracted: Specify the text in the log file that precedes the text you want Secure Email Gateway to extract and replace with the %LOGTEXT% token. If you leave this field empty, the Gateway uses the start of the log file as the start of the extract.
Enter the text that follows the information to be extracted: Specify the text in the log file that follows the text you want Secure Email Gateway to extract and replace with the %LOGTEXT% token. If you leave this field empty, the Gateway uses the end of the log file as the end of the extract.

Example:

<Useless log text>

START

<Useful log text>

END

<More useless log text>

By entering START in the Enter the text that precedes the information to be extracted: field and END in the Enter the text that follows the information to be extracted: field, the Gateway only extracts the <Useful log text> text from the log file.

Responses

You must also configure Response Codes in the Run External Command clause. Response codes are unique mappings for an executable program's return codes.

Add a response code

Click New in the Responses table. The Add response code dialog appears.

Configure the following fields:

Response Code: The details for mapping the numerical return codes of an executable program to Secure Email Gateway using the Action field.

If you are using a third-party executable program, please refer to their relevant documentation for details about the appropriate return code values.

Action: Action type determines how Secure Email Gateway interprets the value specified in the associated Response Code field.

Action	Description
None	Executable program completed successfully
Modified	Executable program found the condition and made changes
Detected	Executable program found the condition
Failure	Executable program did not complete successfully

You must enter at least one response code for the None action.

You must enter at least one response code for either the Detected or Modified actions.

Description: The description associated with the Detected or Modified actions. This text is displayed in the Structure tab on the View Message page. See Analyze and manage held messages for instructions on accessing the View Message page.

If you have specified the %LOGNAME% token in the Command line parameters field of the Run External Command clause, you can use the %LOGTEXT% token in the Description field of a Response Code. The Gateway replaces the %LOGTEXT% token with the text from the log file as specified in the Log Extract section of the Run External Command clause.

Click Add. Your response code appears in the Responses table.

Edit a response code

Select the response code you want to change.
Click Edit. The Edit Response Code dialog appears.
Modify the Response Code, Action and Description parameters.
Click Update.

Delete a response code

Select the response code you want to remove.
Click Delete. The Confirm Delete? dialog appears.
Confirm that you want to delete the selected response code.

Actions for the run external command content rule

Specify the actions you want the Run external command content rule to perform if the Which Media Types and Run External Command clauses are met:

Status	Description	Default action
On detected	Executable program or script found the condition in a message or an item, but could not automatically change it.	No action
On modified	Executable program or script found the condition in a message or an item, and made changes. If the data item being processed cannot be modified, for example if it is digitally signed, then On modified is mapped to On detected.	No action

External program tokens

You can use the following tokens when configuring the details of your external program:

Token	Description
%FILENAME%	The path to the file containing the contents to be processed by the executable program.
%LOGNAME%	The file name of the log file generated by the third-party executable program.

You can also use Property tokens when configuring the details of your external program. See Tokens in Content Rules and Policy References for a list of available Property tokens.

Copyright © Fortra, LLC and its group of companies.
All trademarks and registered trademarks are the property of their respective owners.