Add a YARA rule

Submits a YARA rule file.

POST https://<address>/wsapis/[v1.2.0|v2.0.0]/customioc/yara/add/<ytype>

Availability

This command is available on the following appliances:

Central Management System
Malware Analysis
Email Security — Server
File Protect
Network Security

Required header:

X-FeApi-Token: [API-Token]

Request content-type:

multipart/form-data

Parameters

address—This is the IP address of the appliance running the Web Services API.
API-Token—This token authenticates the session. By default, the session times out after 15 minutes of inactivity.
ytype—The file type of the YARA rules file being submitted, such as exe, pdf, or ppt. See the Filetype dropdown menu in the Upload YARA Rule dialog in your appliance's Web UI for a complete list of file types.
target_type—Specifies which contentType the new YARA rule should be applied to. Valid types are:
- active_content—Extracts the macros from files and executes special YARA rules on them.
- base—Default. If file contains a macro, don’t extract and analyze macros; only analyze the base file.
- all—Does both.

Options (applicable for Central Management System appliance only)

You can specify options to add a YARA rule to specific appliances or groups managed by a Central Management System appliance.

These options are added as the first part of a multipart MIME attachment to the body of the document. The options should be encoded as a JSON attachment.

Format

The JSON-formatted attachment should include the following values:

{\"resource_type\":\"[value]\", \"resource_name\":\"[value1, value2]\"}

`resource_type`	Specifies the type of resource to which the YARA rule is applied. It can take the following values: `appliance`—To add the YARA rule to specific managed appliances. `group`—To add the YARA rule to specific appliance groups.
`resource_name`	Specifies the appliances or groups to which the YARA is added. It can take multiple values, separated by a comma.

Example request

To add a YARA rule with base content, use:

POST https://<address>/wsapis/v1.2.0/customioc/yara/add/<ytype>

To add a YARA rule using v2.0.0 with base, active_content or all content, use:

POST https://<address>/wsapis/v2.0.0/customioc/yara/add/<ytype>?target_type=base

POST https://<address>/wsapis/v2.0.0/customioc/yara/add/<ytype>?target_type=active_content

POST https://<address>/wsapis/v2.0.0/customioc/yara/add/<ytype>?target_type=all

Request Body: (applicable for Central Management System appliance only)

MIME Type application/json
{"resource_type": "appliance","resource_name":["NX","NX1"]}

Results

The specified YARA rule is submitted to the server.

Add a YARA rule response

Response Code—A standard HTML response code.

200—Request successful.
500—Request unsuccessful because the server encountered a problem.

Response Message—A standard HTML response message.

OK—Request successful.
Internal Server Error—Request unsuccessful because the server encountered a problem.

OK—Request successful.
Internal Server Error—Request unsuccessful because the server encountered a problem.

cURL code sample: add a YARA rule

The following code sample can be copied and executed from any command-line interface that includes the cURL library.

Note

In this sample, line breaks are added for readability. Remove these line breaks before you paste the code sample into your command-line tool.

curl -qgsSk --header "${COOKIE}" -F filename=@${file} -F 'options= {"resource_type" : "group","resource_name":["test","test1"]} "https://${HOST}/wsapis/${API_VERSION}/customioc/yara/add/xls?target_type=all"

This cURL sample includes the following options:

-q—This option specifies that the curlrc config file is not read or used. Although this is an optional setting, Trellix recommends that you include this option.
-g—This option turns off the URL globbing parser. Although this is an optional setting, Trellix recommends that you include this option.
-s—This option turns off the progress meter and error message. Although this is an optional setting, Trellix recommends that you include this option.
-S—When used with the -s option, this option shows error messages if your cURL switch fails. Although this is an optional setting, Trellix recommends that you include this option.
-k—This option explicitly allows cURL to perform insecure SSL connections and transfers. This allows you to test your SSL connection without installing a CA certificate.
-H—This option allows you to specify a custom header.
-F filename=@${file}—This option specifies the YARA file to submit.
-F 'options= {"resource_type":"group","resource_name":["test","test1"]}—This is applicable for the Central Management System appliance only. This option specifies the resource type as a group and specifies the appliance groups (test, test1) to which the YARA rule is added.

https://xxx.xxx.xxx.xxx/wsapis/${API_VERSION}/customioc/yara/add/xls?target_type=all—The add request URL. Replace the IP address xxx.xxx.xxx.xxx with the IP address of your appliance.