About the connector
FortiAnalyzer is the NOC-SOC security analysis tool built with an operations perspective. FortiAnalyzer supports analytics-powered use cases to provide better detection against breaches.
This document provides information about the Fortinet FortiAnalyzer Connector, which facilitates automated interactions, with your Fortinet FortiAnalyzer server using FortiSOAR™ playbooks. Add the Fortinet FortiAnalyzer Connector, as a step in FortiSOAR™ playbooks and perform automated operations such as creating and updating incidents on the Fortinet FortiAnalyzer and retrieving user and endpoint information from Fortinet FortiAnalyzer.
Data Ingestion support
Use the Data Ingestion Wizard to easily ingest data into FortiSOAR™ by pulling incidents from Fortinet FortiAnalyzer. Currently, "incidents" in Fortinet FortiAnalyzer are mapped to "alerts" in FortiSOAR™.
For more information on the Data Ingestion Wizard, see the "Connectors Guide" in the FortiSOAR™ product documentation. The following playbooks have been added to support data ingestion:
- > FortiAnalyzer > Fetch
- FortiAnalyzer > Ingest
- >> FortiAnalyzer > Init Macros
- FortiAnalyzer > Post Create Incident > Fetch Events
Important: The Fortinet FortiAnalyzer uses new features introduced in FortiSOAR™ 6.0.0 for data ingestion. If you are using this connector in an older version such as 5.1.1, you would require to map the picklists manually. For example the Severity picklist. To ensure that picklists map correctly, enter the following (considering the severity picklist) in the picklist field:
{{vars.item.severity | resolveRange(vars.alerts_severity_map)}}
This issue has been resolved in version FortiSOAR™6.0.0.
Version information
Connector Version: 1.1.0
FortiSOAR™ Version Tested on: 5.1.3-30 and 6.0.0-790
FortiAnalyzer Version Tested on: VM64-KVMv6.2.3 GA build1235
Authored By: Fortinet
Certified: Yes
Release Notes for version 1.1.0
Following enhancements have been made to the Fortinet FortiAnalyzer connector in version 1.1.0:
- Certified the Fortinet FortiAnalyzer v1.1.0 connector.
Installing the connector
From version 5.0.0 onwards, use the Connector Store to install the connector. For the detailed procedure to install a connector, click here.
You can also use the yum command to install connectors. Connectors provided by FortiSOAR™ are delivered using a FortiSOAR™ repository. Therefore, you must set up your FortiSOAR™ repository and run the yum command as a root user to install connectors:
yum install cyops-connector-fortinet-fortianalyzer
Prerequisites to configuring the connector
- You must have the URL of Fortinet FortiAnalyzer server to which you will connect and perform automated operations and credentials (username-password pair) to access that server.
- To access the FortiSOAR™ UI, ensure that port 443 is open through the firewall for the FortiSOAR™ instance.
- The minimum privileges that require to be assigned to users who are going to use this connector and run actions on Fortinet FortiAnalyzer are users with a "Standard" or "Superuser" profile that has "Read" and "Write" access to JSON API.
You can also create a new user in Fortinet Analyzer and you can use this newly-created user in the connector configuration.
Configuring the connector
For the procedure to configure a connector, click here.
Configuration parameters
In FortiSOAR™, on the Connectors page, click the Fortinet FortiAnalyzer connector row (if you are in the Grid view on the Connectors page) and in the Configurations tab enter the required configuration details:
| Parameter |
Description |
| Server URL |
URL of the Fortinet FortiAnalyzer server to which you will connect and perform the automated operations. |
| Username |
Username used to access the Fortinet FortiAnalyzer server to which you will connect and perform the automated operations. |
| Password |
Password used to access the Fortinet FortiAnalyzer server to which you will connect and perform the automated operations. |
| ADOM Name |
Administrative domain name of the Fortinet FortiAnalyzer server to which you will connect and perform the automated operations. |
| Port |
Port number used to access the Fortinet FortiAnalyzer server to which you will connect and perform the automated operations. By default, this is set to 10405. |
| Verify SSL |
Specifies whether the SSL certificate for the server is to be verified or not.
By default, this option is set as True. |
Actions supported by the connector
The following automated operations can be included in playbooks, and you can also use the annotations to access operations from version 4.10.0 onwards:
| Function |
Description |
Annotation and Category |
| Create Incident |
Creates a new incident record in Fortinet FortiAnalyzer based on the incident reporter, affected endpoint and other input parameters you have specified. |
create_incident
Investigation |
| Fetch Incidents |
Fetches all incidents or a specific incident from Fortinet FortiAnalyzer based on the input parameters you have specified. |
list_incidents
Investigation |
| Update Incident |
Updates incident fields like severity, category, status etc. corresponding to a specific incident in Fortinet FortiAnalyzer based on the incident ID and other input parameters you have specified. |
update_incident_details
Investigation |
| Get Events For Incident |
Retrieves all events associated with a specified incident in Fortinet FortiAnalyzer based on the incident ID you have specified. |
get_events_for_incident
Investigation |
| Get Reports |
Retrieves a list of all reports that have been generated or are in the pending state from Fortinet FortiAnalyzer based on the time frame you have specified. |
get_reports
Investigation |
| List Schedules |
Retrieve a list of all schedules from Fortinet FortiAnalyzer. |
get_schedules
Investigation |
| Run Report |
Runs a report on the Fortinet FortiAnalyzer based on the report ID and schedule ID you have specified. |
run_report
Investigation |
| Get Generated Report |
Retrieves a specific generated report from Fortinet FortiAnalyzer based on the report ID you have specified. |
get_generated_report
Investigation |
| List Users |
Retrieves a list of all users or specific users from Fortinet FortiAnalyzer based on the input parameters you have specified. |
get_users
Investigation |
| List Endpoints |
Retrieves a list of all endpoints or specific endpoints from Fortinet FortiAnalyzer based on the input parameters you have specified. |
get_endpoints
Investigation |
operation: Create Incident
Input parameters
| Parameter |
Description |
| Incident Reporter |
Name of reporter of the incident that you want to create in Fortinet FortiAnalyzer. |
| Affected Endpoint |
Details of the endpoint affected by the incident that you want to create in Fortinet FortiAnalyzer.
For example, 10.XXX.YY.Z/32 (10.XXX.YY.Z) or 10.XXX.YY.Z/32 (Charlie Laptop). |
| Category |
(Optional) Category in which you want to create the incident in Fortinet FortiAnalyzer. You can choose from the following options: Unauthorized access, Denial of Service, Malicious Code, Improper Usage, Scans/Probes/Attempted Access, or Uncategorized. |
| Severity |
(Optional) Severity level that you want to assign to the incident, which you want to create in Fortinet FortiAnalyzer. You can choose from the following options: High, Medium, or Low. |
| Status |
(Optional) Status that you want to assign to the incident, which you want to create in Fortinet FortiAnalyzer. You can choose from the following options: New, Analysis, Response, Closed: Remediated, or Closed: False Positive. |
| End User ID |
(Optional) ID of the end user that you want to assign to the incident, which you want to create in Fortinet FortiAnalyzer. |
| Description |
(Optional) Description of the incident that you want to create in Fortinet FortiAnalyzer. |
| Other Fields |
(Optional) Additional fields in the JSON format that you want to add to the incident, which you want to create in Fortinet FortiAnalyzer.
For example, {"epid":123} |
Output
The output contains the following populated JSON schema:
{
"result": {
"incid": ""
},
"jsonrpc": "",
"id": ""
}
operation: Fetch Incidents
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.
| Parameter |
Description |
| Incident IDs |
List of incident IDs based on which you want to fetch incidents from Fortinet FortiAnalyzer. For example, IN00000002,IN00000005 or IN00000002 |
| Status |
Status of the incident using which you want to filter incidents to be fetched from Fortinet FortiAnalyzer. You can choose from the following options: New, Analysis, Response, Closed: Remediated, or Closed: False Positive. |
| Filter |
Query filter using which you want to filter incidents to be fetched from Fortinet FortiAnalyzer.
For example, status='analysis' and severity='low' |
| Detail Level |
Level of detail that you want to retrieve for the incidents from Fortinet FortiAnalyzer. You can choose from the following options: Basic, Standard(default) or Extended. |
| Limit |
Maximum number of records that this operation should return. Values supported are: Default "50", Minimum "1" and Maximum "2000". |
| Offset |
Index of the first item to return. Values supported are: Default "0" and Minimum "0". |
| Sort |
Select this checkbox if you want to sort the incidents by a field and order the results.
If you select this checkbox, i.e., set it as "true", then specify the following parameters:
- Sort by Field: Name of the field on which you want to sort the result.
- Sort by Order: Sorting order of the result, choose between ASC (ascending) or DESC (descending).
|
Output
The output contains the following populated JSON schema:
{
"jsonrpc": "",
"result": {
"data": [
{
"severity": "",
"category": "",
"incid": "",
"euid": "",
"description": "",
"endpoint": "",
"refinfo": "",
"attach_revision": "",
"epid": "",
"createtime": "",
"status": "",
"attach_lastupdate": "",
"lastuser": "",
"revision": "",
"reporter": "",
"lastupdate": ""
}
],
"status": {
"code": "",
"message": ""
},
"detail-level": ""
},
"id": ""
}
operation: Update Incident
Input parameters
| Parameter |
Description |
| Incident ID |
ID of the incident that you want to update in Fortinet FortiAnalyzer. |
| Category |
(Optional) Category that you want to assign to the incident, which you want to update in Fortinet FortiAnalyzer. You can choose from the following options: Unauthorized access, Denial of Service, Malicious Code, Improper Usage, Scans/Probes/Attempted Access, or Uncategorized. |
| Status |
(Optional) Status that you want to assign to the incident, which you want to update in Fortinet FortiAnalyzer. You can choose from the following options: New, Analysis, Response, Closed: Remediated, or Closed: False Positive. |
| Affected Endpoint |
(Optional) Details of the endpoint affected by the incident that you want to update in Fortinet FortiAnalyzer.
For example, 10.XXX.YY.Z/32 (10.XXX.YY.Z) or 10.XXX.YY.Z/32 (Charlie Laptop). |
| Severity |
(Optional) Severity level that you want to assign to the incident, which you want to update in Fortinet FortiAnalyzer. You can choose from the following options: High, Medium, or Low. |
| End User ID |
(Optional) ID of the end user that you want to assign to the incident, which you want to update in Fortinet FortiAnalyzer. |
| Description |
(Optional) Description of the incident that you want to update in Fortinet FortiAnalyzer. |
| Other Fields |
(Optional) Additional fields in the JSON format that you want to modify in the incident, which you want to update in Fortinet FortiAnalyzer.
For example, {"epid":123} |
Output
The output contains the following populated JSON schema:
{
"jsonrpc": "",
"result": {
"status": {
"code": "",
"message": ""
}
},
"id": ""
}
operation: Get Events For Incident
Input parameters
| Parameter |
Description |
| Incident ID |
ID of the incident whose associated events you want to retrieve from Fortinet FortiAnalyzer. |
| Limit |
Maximum number of records that this operation should return. Values supported are: Default "50", Minimum "1" and Maximum "2000". |
| Offset |
Index of the first item to return. Values supported are: Default "0" and Minimum "0". |
Output
The output contains the following populated JSON schema:
{
"result": {
"data": [
{
"createtime": "",
"data": "",
"incid": "",
"lastuser": "",
"attachid": "",
"lastupdate": "",
"revision": "",
"attachtype": ""
}
],
"status": {
"code": "",
"message": ""
}
},
"jsonrpc": "",
"id": ""
}
operation: Get Reports
Input parameters
| Parameter |
Description |
| State |
State of the report that you want to retrieve from Fortinet FortiAnalyzer. The states that are supported are: pending-running or generated. |
| Start Time |
Starting datetime from when you want to retrieve from Fortinet FortiAnalyzer.
Note: If the timezone information is not specified then the Fortinet FortiAnalyzer's timezone considered for retrieving the reports. |
| End Time |
Ending datetime till when you want to retrieve from Fortinet FortiAnalyzer.
Note: If the timezone information is not specified then the Fortinet FortiAnalyzer's timezone considered for retrieving the reports. |
Output
The output contains the following populated JSON schema:
{
"result": {
"count": "",
"revision": "",
"data": [
{
"devtype": "",
"state": "",
"profileid": "",
"date": "",
"title": "",
"timestamp-end": "",
"adminuser": "",
"schedule_color": "",
"format": [],
"tid": "",
"progress-percent": "",
"name": "",
"period-end": "",
"end": "",
"timestamp-start": "",
"start": "",
"period-start": ""
}
]
},
"jsonrpc": "",
"id": ""
}
operation: List Schedules
Input parameters
None.
Output
The output contains the following populated JSON schema:
{
"result": {
"status": {
"code": "",
"message": ""
},
"data": [
{
"report-per-device": "",
"week-start": "",
"date-format": "",
"include-other": "",
"period-last-n": "",
"period-opt": "",
"display-device-by": "",
"schedule-valid-end": [],
"devices": [
{
"devices-name": ""
}
],
"schedule-color": "",
"filter": "",
"admin-user": "",
"filter-type": "",
"report-layout": [
{
"layout-id": ""
}
],
"email-report-per-device": "",
"language": "",
"ldap-user-case-change": "",
"orientation": "",
"name": "",
"time-period": "",
"print-report-filters": "",
"schedule-type": "",
"ldap-server": "",
"auto-hcache": "",
"display-table-contents": "",
"filter-logic": "",
"obfuscate-user": "",
"device-list-type": "",
"include-coverpage": "",
"output-format": "",
"schedule-valid-start": [],
"resolve-hostname": "",
"ldap-query": "",
"schedule-frequency": "",
"output-profile": "",
"dev-type": "",
"max-reports": "",
"status": ""
}
]
},
"jsonrpc": "",
"id": ""
}
operation: Run Report
Input parameters
| Parameter |
Description |
| Schedule |
Name or ID of the schedule using which you want to run the report.
Note: You can get the name or ID of the schedule using the "List Schedules" action. |
| Report ID |
ID of the report that you want to run on Fortinet FortiAnalyzer. |
Output
The output contains the following populated JSON schema:
{
"jsonrpc": "",
"result": {
"tid": ""
},
"id": ""
}
operation: Get Generated Report
Input parameters
| Parameter |
Description |
| Task ID |
Task ID of the generated report that you want to retrieve from Fortinet FortiAnalyzer. |
Output
The output contains the following populated JSON schema:
{
"jsonrpc": "",
"result": {
"tid": "",
"length": "",
"name": "",
"data-type": "",
"checksum": "",
"data": ""
},
"id": ""
}
operation: List Users
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.
| Parameter |
Description |
| User IDs |
List of user IDs based on which you want to fetch users from Fortinet FortiAnalyzer. For example, 1043,1055 or 1043. |
| Filter |
Query filter using which you want to filter users to be fetched from Fortinet FortiAnalyzer.
For example, euuuid='c0a74c48-2367-11ea-aedf-00090f000409' and euname='localhost' |
| Detail Level |
Level of detail that you want to retrieve for the users from Fortinet FortiAnalyzer. You can choose from the following options: Basic, Standard(default) or Extended. |
| Limit |
Maximum number of records that this operation should return. Values supported are: Default "100000", Minimum "1" and Maximum "1000000". |
| Offset |
Index of the first item to return. Values supported are: Default "0" and Minimum "0". |
| Sort |
Select this checkbox if you want to sort the users by a field and order the results.
If you select this checkbox, i.e., set it as "true", then specify the following parameters:
- Sort by Field: Name of the field on which you want to sort the result.
- Sort by Order: Sorting order of the result, choose between ASC (ascending) or DESC (descending).
|
Output
The output contains the following populated JSON schema:
{
"result": {
"data": [
{
"workphone": "",
"socialid": {
"data": []
},
nbsp; "gender": "",
"authtype": "",
"euname": "",
"euuuid": "",
"euid": "",
"title": "",
"eugroup": "",
"employeeid": "",
"email": "",
"lastseen": "",
"workemail": "",
"firstseen": "",
"phone": "",
"firstname": "",
"birthday": "",
"homeaddr": "",
"lastname": "",
"workaddr": ""
}
],
"status": {
"code": "",
"message": ""
}
},
"jsonrpc": "",
"id": ""
}
operation: List Endpoints
Input parameters
Note: All the input parameters are optional. However, if you do not specify any parameter, then no filter criterion is applied, and an unfiltered list is returned.
| Parameter |
Description |
| Endpoint IDs |
List of endpoint IDs based on which you want to fetch endpoints from Fortinet FortiAnalyzer. For example, 1047,1077 or 1077.
The list of endpoint ID's. e.g. 1047,1077 or 1077 |
| Filter |
Query filter using which you want to filter endpoints to be fetched from Fortinet FortiAnalyzer.
For example, epname='10.0.10.3' and detectkey='10.0.10.3' |
| Limit |
Maximum number of records that this operation should return. Values supported are: Default "100000", Minimum "1" and Maximum "1000000". |
| Offset |
Index of the first item to return. Values supported are: Default "0" and Minimum "0". |
| Sort |
Select this checkbox if you want to sort the endpoints by a field and order the results.
If you select this checkbox, i.e., set it as "true", then specify the following parameters:
- Sort by Field: Name of the field on which you want to sort the result.
- Sort by Order: Sorting order of the result, choose between ASC (ascending) or DESC (descending).
|
Output
The output contains the following populated JSON schema:
{
"result": {
"data": [
{
"epname": "",
"fctuid": "",
"detecttype": "",
"osname": "",
"detectkey": "",
"macip": [
{
"lastseen": "",
"epip": "",
"mac": ""
}
],
"lastseen": "",
"adomoid": "",
"epid": "",
"epdevtype": "",
"osversion": "",
"vd": "",
"devid": ""
}
],
"status": {
"code": "",
"message": ""
}
},
"jsonrpc": "",
"id": ""
}
Included playbooks
The Sample - Fortinet FortiAnalyzer - 1.0.1 playbook collection comes bundled with the Fortinet FortiAnalyzer connector. These playbooks contain steps using which you can perform all supported actions. You can see bundled playbooks in the Automation > Playbooks section in FortiSOAR™ after importing the Fortinet FortiAnalyzer connector.
- Create Incident
- > FortiAnalyzer > Fetch
- FortiAnalyzer > Ingest
- >> FortiAnalyzer > Init Macros
- FortiAnalyzer > Post Create Incident > Fetch Events
- Get Events For Incident
- Get Generated Report
- Get Reports
- Get Schedules
- List Endpoints
- List Incidents
- List Users
- Run Report
- Update Incident
Note: If you are planning to use any of the sample playbooks in your environment, ensure that you clone those playbooks and move them to a different collection since the sample playbook collection gets deleted during the connector upgrade and delete.
Limitations of the Fortinet FortiAnalyzer connector
- The "Sort" function does not work for the connector actions when you set the "Detail Level" for the results as 'Extended'. The "Sort" function works fine when you set the "Detail Level" for the results as 'Basic' or 'Standard'.
- The "List Schedules" and "Run Report" actions do not work for FortiAnalyzer’s standard user for all ADOMs.
