FncClient Library Supported Endpoints

The FncClient Library and specifically the FncApiClient, leverage the REST APIs exposed by the FortiNDR Cloud services to manage their services. Only some of the endpoints available on those APIs are supported by the FncClient Library. A complete list of those supported endpoints and a description of each of them is presented in this section.

# Sensors API's Endpoints

GET_TELEMETRY_PACKETSTATS

GET_TELEMETRY_NETWORK

# Entity API's Endpoints

GET_ENTITY_SUMMARY

GET_ENTITY_ANNOTATIONS

GET_ENTITY_PDNS

GET_ENTITY_DHCP

GET_ENTITY_FILE

# Detections API's Endpoints

GET_SENSORS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of sensors.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	UUID of account to filter by.
account_code	string	false	false	Account code to filter by.
sensor_id	string	false	false	ID of the sensor to filter by.
include	string	false	true	Include additional metadata such as `status`, `interfaces`, `admin.sensor`, `admin.zeek`, `admin.suricata`, and `network_ usage`. The values are provided as a comma-separated lists.
enabled	bool	false	false	Filter enabled or disabled sensors. If it is not provided, all the sensors are returned regardless their status.

Response

The return is a JSON containing the two fields. The sensors field contains the list of sensors retrieved and the result_count shows how many sensors were retrieved.

Example

{
    "result_count": 2222, 
    "sensors": […]
}

GET_DEVICES

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of devices.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	UUID of account to filter by.
start_date	string	false	false	Filter devices based on when they were seen.
end_date	string	false	false	Filter devices based on when they were seen.
cidr	string	false	false	Filter devices that are under a string specific CIDR.
sensor_id	string	false	false	Filter devices that were observed by a specific sensor.
dedup_sensor_id	string	false	false	Allowed values: `YES`, `NO`
traffic_direction	string	false	false	Filter devices that have been noted to only have a certain directionality of traffic (external or "internal). Allowed values: `internal`, `external`
sort_by	string	false	false	Allowed values: `ip_address`, `internal`, `external`
sort_direction	string	false	false	Allowed values: `desc`, `asc`

Response

The return is a JSON containing a devices field containing:

device_list: List of the retrieved devices.
result_count: Total amount of devices.
return_count: The number of retrieved devices.

Example

{
    "devices": {
        "device_list": […],
        "result_count": 310992, 
        "return_count": 10000
    }
}

GET_TASK

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a PCAP task.

Arguments

Argument	Type	Required	Multi-Value	Description
`task_id`	string	true	false	ID of the task to be retrieved

Response

The return is a JSON with a field pcap_task containing the retrieved task.

Example

{
    "pcap_task": {
        "task_uuid": "…",
        "description": "…",
        "name": "…",
        "sensor_ids": [],
        "account_code": "…",
        "bpf": "…",
        "created_uuid": "…",
        "updated_uuid": null, 
        "created_email": "…",
        "updated_email": null, 
        "created": "…",
        "updated": "…",
        "requested_start_time": "…",
        "requested_end_time": "…",
        "actual_start_time": "…",
        "actual_end_time": "…",
        "status": "…",
        "files": [],
        "has_files": false
    }
}

GET_TASKS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of all the PCAP tasks.

Arguments

Argument	Type	Required	Multi-Value	Description
sensor_id	string	false	false	ID of the sensor to filter by.
created_start	string	false	false	Filter tasks based on when they were created.
created_end	string	false	false	Filter tasks based on when they were created.
search_text	string	false	false	Filter tasks including the containing text.
has_files_only	bool	false	false	Filter tasks based on whether they have files or not.
page_size	int	false	false
page_num	int	false	false

Response

The return is a JSON with two fields:

pcaptasks: containing a list with the retrieved tasks.
result_count: containing the number of retrieved tasks

Example

{
    "pcaptasks": […]
    "result_count": 2
}

CREATE_TASK

This endpoint is used to communicate with the FortiNDR Cloud Service to create a new PCAP task.

Arguments

Argument	Type	Required	Multi-Value	Description
description	string	true	false	A description of the task.
name	string	true	false	The name of the task.
sensor_ids	string	true	false	Sensor IDs on which this task will run (separate multiple accounts by comma).
account_uuid	string	true	false	Filter tasks including the containing text.
bpf	string	true	false	The Berkeley Packet Filter for capture filtering.
requested_start_date	string	true	false	The date the task will become active. (2024-01-30T00:00:00.000Z).
requested_end_date	string	true	false	The date the task will become inactive. (2024-12-31T23:59:59.000Z).

Response

The return is a JSON with a field pcaptask containing the created task.

Example

{
    "pcap_task": {
        "task_uuid": "…",
        "description": "…",
        "name": "…",
        "sensor_ids": [],
        "account_code": "…",
        "bpf": "…",
        "created_uuid": "…",
        "updated_uuid": null, 
        "created_email": "…",
        “updated_email”: null, 
        "created": "…",
        "updated": "…",
        "requested_start_time": "…",
        "requested_end_time": "…",
        "actual_start_time": "…",
        "actual_end_time": "…",
        "status": "…",
        "files": [],
        "has_files": false
    }
}

GET_TELEMETRY_EVENTS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve event telemetry data grouped by time.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	UUID of account to filter by.
account_code	string	false	false	Account code to filter by.
sensor_id	string	false	false	Sensor id to filter by.
start_date	string	false	false	Start date/time to query for. The string default is 1 day ago for `interval=hour` or 30 days ago for `interval=day`.
end_date	string	false	false	End date/time to query for. The default is the current time.
event_type	string	false	false	The type of event. Limited to flow, dns, http, ssl, and x509.
interval	string	false	false	Interval to group by: `hour` (default) or `day`.
group_by	string	false	false	Optionally group results by: `event_type`, `sensor_id`, `account_code`
sort_direction	string	false	false	Allowed values: `desc`, `asc`

Response

The return is a JSON with three fields:

columns: Containing the column’s headers for the retrieved information.
data: A list containing the retrieved data. Each element is also a list with the values for each of the column’s headers
result_count: Containing the size of the retrieved list of data

Example

{
    "columns": […]
    "data": […]
    "result_count": 25
}

GET_TELEMETRY_PACKETSTATS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve packetstats telemetry data grouped by time.

Arguments

Argument	Type	Required	Multi-Value	Description
sensor_id	string	false	false	Sensor id to filter by.
account_code	string	false	false	Account code to filter by.
start_date	string	false	false	Start date/time to query for. The string default is 1 day ago for `interval=hour` or 30 days ago for `interval=day`.
end_date	string	false	false	End date/time to query for. The default is the current time.
interval	string	false	false	Interval to group by: `hour` (default) or `day`.
group_by	string	false	false	Optionally group results string by: interface_name, sensor_id or account_code.

Response

The return is a JSON with three fields:

columns: Contains the column’s headers for the retrieved information.
data: A list containing the retrieved data. Each element is also a list with the values for each of the column’s headers
result_count: Contains the size of the retrieved list of data

Example

{
    "columns": […]
    "data": […]
    "result_count": 25
}

GET_TELEMETRY_NETWORK

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve network telemetry data grouped by time.

Arguments

Argument	Type	Required	Multi-Value	Description
account_code	string	false	false	Account code to filter by.
start_date	string	false	false	Start date to filter by.
end_date	string	false	false	End date to filter by.
interval	string	false	false	The interval to filter by (`day`, `month_to_day`).
latest_each_month	string	false	false	Filters out all but the latest day and `month_to_date` for each month.
sort_order	string	false	false	Sorts by account code first, then timestamp. Allowed values: `asc` or `desc`. The default is `desc`.
limit	string	false	false	The number of records to return. Default=100 and Maximum=1000
offset	string	false	false	The number of records to skip. Default = `0`.

Response

The return is a JSON with six fields:

network_usage: Contains a list with the retrieved information.
total_count: he total amount of elements
result_count: Contains the number of elements that were retrieved.
sort_order:Either asc or desc.
limit: The maximum number of elements to be retrieved.
offset: The number of elements to be skipped.

Example

{
    "network_usage": […],
    "total_count": 10379, 
    "result_count": 1000, 
    "sort_order": "desc",
    "limit": 1000, 
    "offset": 0
}

GET_ENTITY_SUMMARY

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve summary information about an IP or domain.

Arguments

Argument	Type	Required	Multi-Value	Description
entity	string	true	false	Entity for which you want to retrieve the information
account_uuid	string	false	true	Account UUIDs to filter by. If absent, all the caller's allowed accounts will be queried.
entity_type	string	false	false	Type of the entity we are searching. Allowed values are: `ip`, `domain`.

Response

The return is a JSON with two fields:

query_type: The type of the query (i.e., ip_address, domain, etc.).
summary: The retrieved summary information.

Example

{
    "query_type": "ip_address",
    "summary": {
        "entity": …,
        "first_seen": …,
        "last_seen": …,
        "prevalence_count_internal": …,
        "tags": […]
    }
}

GET_ENTITY_ANNOTATIONS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve annotations information about an IP address.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	true	Account uuid owning the annotations. If absent or null, all allowed accounts for the caller will be used.
entities	string	true	false	JSON string containing the list of entities to lookup. Each item containing the entity and its type. Example: [ { "entity": "10.0.0.1", "entity_type": "ip" }, { "entity": "10.0.0.2", "entity_type": "ip" } ]

Argument

Type

Required

Multi-Value

Description

account_uuid

string

false

true

Account uuid owning the annotations. If absent or null, all allowed accounts for the caller will be used.

entities

string

true

false

JSON string containing the list of entities to lookup. Each item containing the entity and its type. Example:

[
  {
    "entity": "10.0.0.1",
    "entity_type": "ip"
  },
  {
    "entity": "10.0.0.2",
    "entity_type": "ip"
  }
]

Response

The return is a JSON containing the list of annotations for each entity. Each item containing three fields:

account_code: account owning the annotations.
entity: Contains the provided entity and its type.
annotations: the list of annotations for the specific entity.dhcp

Example:

{
  "entity_annotations": [
    {
      "account_code": "…",
      "entity": {
        "entity": "10.0.0.1",
        "entity_type": "ip"
      },
      "annotations": [ … ]
    },
    {
      "account_code": "…",
      "entity": {
        "entity": "10.0.0.2",
        "entity_type": "ip"
      },
      "annotations": [ … ]
    }
  ]
}

GET_ENTITY_PDNS

This endpoint is used to communicate with FortiNDR Cloud Service to retrieve passive DNS information about an IP or domain.

Arguments

Argument	Type	Required	Multi-Value	Description
entity	string	true	false	Entity for which we want to retrieve the PDNS information.
account_uuid	string	false	true	Limit results to the specified account UUID(s). Defaults to all accounts for which the user has permission.
record_type	string	false	true	Limit results to the specified DNS query type(s). Supported types are: A, AAAA, CNAME, MX, NS. Case insensitive.
source	string	false	true	Limit the results to the specified data source(s). Note that not all Sources populate all fields. Supported sources are: ICEBRG_DNS. Case insensitive.
start_date	string	false	false	The earliest date before which to exclude results. Day granularity, inclusive.
end_date	string	false	false	The latest date before which to exclude results. Day granularity, inclusive.
resolve_external	string	false	false	Sorts by account code first, then timestamp. Allowed values: `asc`or `desc`. The default is `desc`.
limit	string	false	false	Maximum number of records to be returned. Default 1000.

Response

The return is a JSON with three fields:

query_type: The type of the query (i.e., ip_address, domain, etc.).
result_count: Contains the number of elements that were retrieved.
passivedns: A list containing the retrieved PDNS information.

Example

{
    "query_type": "ip_address",
    "result_count": 1000, 
    "passivedns": […]
}

GET_ENTITY_DHCP

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve DHCP information about an IP address.

Arguments

Argument	Type	Required	Multi-Value	Description
entity	string	true	false	Entity for which we want to retrieve the DHCP information
account_uuid	string	false	true	Limit results to the specified account UUID(s). Defaults to all accounts for which the user has permission.
sensor_id	string	false	false	Sensor id to filter by.
start_date	string	false	false	Limit the results to those DHCP leases that `start` after this start date.
end_date	string	false	false	Limit the results to those DHCP leases that `start` before this end date.

Response

The return is a JSON with three fields:

query_type:The type of the query (i.e., ip_address, domain, etc.).
result_count: Contains the number of elements that were retrieved.
dhcp: A list containing the retrieved DHCP information.

Example

{
    "query_type": "ip_address",
    "result_count": 1000, 
    "annotations": […]
}

GET_ENTITY_FILE

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve information about a file.

Arguments

Argument	Type	Required	Multi-Value	Description
entity	string	true	false	Entity for which we want to retrieve the information
account_uuid	string	false	true	Account UUID(s) to filter by. If absent, all the caller's allowed accounts will be queried.

Response

The return is a JSON with three fields:

query_type: The type of the query (i.e., ip_address, domain, etc.).
hash_type: The hash type that was applied.
file: The retrieved file’s information.

Example

{
    "query_type": "ip_address",
    "hash_type": 1000, 
    "file": {…}
}

GET_DETECTIONS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of detections.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	Account to filter results by.
rule_uuid	string	false	true	Rule UUID's to filter results by.
status	string	false	true	Status to filter results by (`active`, `resolved`).
device_ip	string	false	false	Device IP to filter by.
sensor_id	string	false	false	Sensor ID to filter by.
include	string	false	true	Include linked objects (`rules`, `indicators`).
sort_order	string	false	false	Direction of sort (`desc`, `asc`).
sort_by	string	false	false	Filed to sort by `(first_seen`, `last_seen`, `status`, `device_ip`, `indicator_count`).
limit	int	false	false	The number of records to include (default:100, max:10,000)
offset	int	false	false	The number of records to skip.
is_muted	bool	false	false	Filter results by whether a detection is muted by any way.
muted	bool	false	false	Filter results by whether or not the detection is muted.
muted_rule	bool	false	false	Filter results by whether the associated rule is muted for the account.
muted_device	bool	false	false	Filter results by whether the device is muted.
rule_severity	string	false	true	Filter results by rule severity (low, moderate, high).
rule_category	string	false	true	Filter results by rule category.
rule_confidence	string	false	true	Filter results by rule confidence (low, moderate, high).
resolution	string	false	true	Filter results by resolution in resolution table.
resolution_user_uuid	string	false	true	Filter results by resolution user UUID.
uuid	string	false	false	Filter results if there is resolution user UUID on the detection.
resolve_start_date	string	false	false	Resolved start date to filter by (inclusive).
resolve_end_date	string	false	false	Resolved end date to filter by (exclusive).
active_start_date	string	false	false	Active start date to filter by (inclusive).
active_end_date	string	false	false	Active end date to filter by (exclusive).
created_start_date	string	false	false	Created start date to filter by (inclusive).
created_end_date	string	false	false	Created end date to filter by (exclusive)
created_or_shared_start_date	string	false	false	Created or shared start date to filter by (inclusive).
created_or_shared_end_date	string	false	false	Created or shared end date to filter by (exclusive).
rule_enabled	string	false	false	Filter results if the rule is enabled.
rule_attack_id	string	false	true	Filter results by rule attack IDs.
rule_account_uuid	string	false	false	Filter results by rule account UUID.
indicator_value	string	false	false	Indicator value to filter by.

Response

The return is a JSON with eight fields:

detections: A list with the retrieved detections.
rules: A list with the rules associated to the retrieved detections.
total_count: The total amount of elements
result_count: Contains the number of elements that were retrieved.
sort_order: Either asc or desc.
sort_by: Feld used to sort the result (first_seen, last_seen, status, device_ip, indicator_count).
limit: The maximum number of elements to be retrieved
offset: The number of elements to be skipped.

Example

{
    "result_count": 6074, 
    "total_count": 6074, 
    "detections": […],
    "sort_by": "first_seen",
    "sort_order": "asc",
    "offset": 0, 
    "limit": 10000, 
    "rules": […]
}

RESOLVE_DETECTION

This endpoint is used to communicate with the FortiNDR Cloud Service to resolve a detection.

Arguments

Argument	Type	Required	Multi-Value	Description
detection_id	string	true	false	UUID for the detection to be resolved
resolution	string	true	false	Resolution category (`true_positive_mitigated`, `true_positive_no_action`, `false_positive`, `unknown`).
resolution_comment	string	false	false	Optional comment for the resolution.

Response

This endpoint returns an empty HTTP 204 response.

GET_DETECTION_EVENTS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of events associated to a detection.

Arguments

Argument	Type	Required	Multi-Value	Description
detection_uuid	string	true	false	UUID for the detection to filter by.
offset	string	false	false	The number of records to skip past. The default is 0.
limit	string	false	false	The maximum number of records to return. The default is 0 and the max is 1000.

Response

The return is a JSON with three fields:

events: A list containing the retrieved events.
total_count: The total amount of elements
result_count: Contains the number of elements that were retrieved.

Example

{
    "result_count": 6074, 
    "total_count": 6074, 
    "events": […]
}

GET_RULES

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of rules.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	Optional account to filter results by.
rule_account_uuid	string	false	false	Optional account to filter rule account sub-objects by.
search	string	false	false	Search string on name, category or description.
has_detections	bool	false	false	Include rules that have unmuted, unresolved detections.
detection_device_ip	string	false	false	Device IP of associated detections to filter by. Note the associated detections are determined by the `has_detections param`.
indicator_value	string	false	false	Case insensitive prefix search of related indicators.
severity	string	false	true	List of severities to filter by (low, moderate, high).
confidence	string	false	true	List of confidences to filter by (low, moderate, high).
category	string	false	true	Category to filter by (see above).
rule_account_muted	bool	false	false	Include muted rules accounts for the given `account_uuid`.
enabled	bool	false	false	Enabled rules only.
attack_id	string	false	true	List of MITRE ATT&CK technique ID to filter by. Leave blank or null to turn off this filter.
sort_by	string	false	false	The field to sort by: `created`, `updated`, `detections`, `severity`, `confidence`, `category`, `last_seen`, `detections_muted`. Defaults to updated.
sort_order	string	false	false	The sort order: `asc` or `desc`. The default is `desc`.
limit	int	false	false	The maximum number of records to return. Default: 100, Max: 1000.
offset	int	false	false	The number of records to skip past. Default: 0.

Response

The return is a JSON with ten fields:

rules: The list of the rules retrieved.
accounts: The list of the associated accounts.
active_rule_count: The number of active rules
enabled_rule_count: The number of enabled rules.
total_count: The total amount of elements
result_count: Contains the number of elements that were retrieved.
sort_order: Either asc or desc.
sort_by: Filed used to sort the result (first_seen, last_seen, status, device_ip, indicator_count).
limit: The maximum number of elements to be retrieved
offset: The number of elements to be skipped.

Example

{
    "rules": […],
    "accounts": […],
    "active_rule_count": 404, 
    "enabled_rule_count": 1723, 
    "result_count": 100, 
    "total_count": 1843, 
    "sort_by": "updated",
    "sort_order": "desc",
    "offset": 100, 
    "limit": 100
}

GET_RULE

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a specific rule.

Arguments

Argument	Type	Required	Multi-Value	Description
`rule_id`	string	true	false	UUID for the rule to filter by.

Response

The return is a JSON with two fields:

rule: Contains the retrieved rule.
accounts: A list containing the associated accounts.

Example

{ 
    "rule": {…},
    "accounts": […],
}

CREATE_RULE

This endpoint is used to communicate with the FortiNDR Cloud Service to create a rule.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	true	false	Rule’s account
name	string	true	false	Rule’s name
category	string	true	false	Rule’s category
query_signature	string	true	false	Rule’s query signature
description	string	false	false	Rule’s description
severity	string	true	false	Rule’s severity
confidence	string	true	false	Rule’s confidence
primary_attack_id	string	false	false
secondary_attack_id	string	false	false
specificity	string	false	false
device_ip_fields	string	true	false
indicator_fields	string	false	false
run_account_uuids	string	true	false
auto_resolution_minutes	string	false	false	Time to be automatically resolved

Response

The return is a JSON with a field rule containing the created rule.

Example

{ 
    "rule": {
        "uuid": "…",
        "account_uuid": "…",
        "shared_account_uuids": null, 
        "run_account_uuids": ["…"],
        "name": "…",
        "category": "…",
        "query_signature": "…",
        "description": null, 
        "severity": "…",
        "confidence": "…",
        "auto_resolution_minutes": null, 
        "enabled": true, 
        "created_user_uuid": "…",
        "created": "…",
        "updated_user_uuid": "…",
        "updated": "…",
        "critical_updated": "…",
        "primary_attack_id": null, 
        "secondary_attack_id": null, 
        "specificity": null, 
        "rule_accounts": null, 
        "device_ip_fields": ["…"],
        "indicator_fields": null, 
        "source_excludes": ["…"]
    }
}

GET_RULE_EVENTS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of events associated to a rule.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	UUID for the account to filter by.
offset	string	false	false	The number of records to skip past. The default is 0.
limit	string	false	false	The maximum number of records to return.The default is 0 and the max is 1000.

Response

The return is a JSON with three fields:

events: A list containing the retrieved events.
total_count: The total amount of elements
result_count: Contains the number of elements that were retrieved.

Example

{
    "result_count": 6074, 
    "total_count": 6074, 
    "events": […]
}

FncClient Library Supported Endpoints

# Sensors API's Endpoints

GET_TELEMETRY_PACKETSTATS

GET_TELEMETRY_NETWORK

# Entity API's Endpoints

GET_ENTITY_SUMMARY

GET_ENTITY_ANNOTATIONS

GET_ENTITY_PDNS

GET_ENTITY_DHCP

GET_ENTITY_FILE

# Detections API's Endpoints

GET_SENSORS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of sensors.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	UUID of account to filter by.
account_code	string	false	false	Account code to filter by.
sensor_id	string	false	false	ID of the sensor to filter by.
include	string	false	true	Include additional metadata such as `status`, `interfaces`, `admin.sensor`, `admin.zeek`, `admin.suricata`, and `network_ usage`. The values are provided as a comma-separated lists.
enabled	bool	false	false	Filter enabled or disabled sensors. If it is not provided, all the sensors are returned regardless their status.

Response

The return is a JSON containing the two fields. The sensors field contains the list of sensors retrieved and the result_count shows how many sensors were retrieved.

Example

{
    "result_count": 2222, 
    "sensors": […]
}

GET_DEVICES

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of devices.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	UUID of account to filter by.
start_date	string	false	false	Filter devices based on when they were seen.
end_date	string	false	false	Filter devices based on when they were seen.
cidr	string	false	false	Filter devices that are under a string specific CIDR.
sensor_id	string	false	false	Filter devices that were observed by a specific sensor.
dedup_sensor_id	string	false	false	Allowed values: `YES`, `NO`
traffic_direction	string	false	false	Filter devices that have been noted to only have a certain directionality of traffic (external or "internal). Allowed values: `internal`, `external`
sort_by	string	false	false	Allowed values: `ip_address`, `internal`, `external`
sort_direction	string	false	false	Allowed values: `desc`, `asc`

Response

The return is a JSON containing a devices field containing:

device_list: List of the retrieved devices.
result_count: Total amount of devices.
return_count: The number of retrieved devices.

Example

{
    "devices": {
        "device_list": […],
        "result_count": 310992, 
        "return_count": 10000
    }
}

GET_TASK

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a PCAP task.

Arguments

Argument	Type	Required	Multi-Value	Description
`task_id`	string	true	false	ID of the task to be retrieved

Response

The return is a JSON with a field pcap_task containing the retrieved task.

Example

{
    "pcap_task": {
        "task_uuid": "…",
        "description": "…",
        "name": "…",
        "sensor_ids": [],
        "account_code": "…",
        "bpf": "…",
        "created_uuid": "…",
        "updated_uuid": null, 
        "created_email": "…",
        "updated_email": null, 
        "created": "…",
        "updated": "…",
        "requested_start_time": "…",
        "requested_end_time": "…",
        "actual_start_time": "…",
        "actual_end_time": "…",
        "status": "…",
        "files": [],
        "has_files": false
    }
}

GET_TASKS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of all the PCAP tasks.

Arguments

Argument	Type	Required	Multi-Value	Description
sensor_id	string	false	false	ID of the sensor to filter by.
created_start	string	false	false	Filter tasks based on when they were created.
created_end	string	false	false	Filter tasks based on when they were created.
search_text	string	false	false	Filter tasks including the containing text.
has_files_only	bool	false	false	Filter tasks based on whether they have files or not.
page_size	int	false	false
page_num	int	false	false

Response

The return is a JSON with two fields:

pcaptasks: containing a list with the retrieved tasks.
result_count: containing the number of retrieved tasks

Example

{
    "pcaptasks": […]
    "result_count": 2
}

CREATE_TASK

This endpoint is used to communicate with the FortiNDR Cloud Service to create a new PCAP task.

Arguments

Argument	Type	Required	Multi-Value	Description
description	string	true	false	A description of the task.
name	string	true	false	The name of the task.
sensor_ids	string	true	false	Sensor IDs on which this task will run (separate multiple accounts by comma).
account_uuid	string	true	false	Filter tasks including the containing text.
bpf	string	true	false	The Berkeley Packet Filter for capture filtering.
requested_start_date	string	true	false	The date the task will become active. (2024-01-30T00:00:00.000Z).
requested_end_date	string	true	false	The date the task will become inactive. (2024-12-31T23:59:59.000Z).

Response

The return is a JSON with a field pcaptask containing the created task.

Example

{
    "pcap_task": {
        "task_uuid": "…",
        "description": "…",
        "name": "…",
        "sensor_ids": [],
        "account_code": "…",
        "bpf": "…",
        "created_uuid": "…",
        "updated_uuid": null, 
        "created_email": "…",
        “updated_email”: null, 
        "created": "…",
        "updated": "…",
        "requested_start_time": "…",
        "requested_end_time": "…",
        "actual_start_time": "…",
        "actual_end_time": "…",
        "status": "…",
        "files": [],
        "has_files": false
    }
}

GET_TELEMETRY_EVENTS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve event telemetry data grouped by time.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	UUID of account to filter by.
account_code	string	false	false	Account code to filter by.
sensor_id	string	false	false	Sensor id to filter by.
start_date	string	false	false	Start date/time to query for. The string default is 1 day ago for `interval=hour` or 30 days ago for `interval=day`.
end_date	string	false	false	End date/time to query for. The default is the current time.
event_type	string	false	false	The type of event. Limited to flow, dns, http, ssl, and x509.
interval	string	false	false	Interval to group by: `hour` (default) or `day`.
group_by	string	false	false	Optionally group results by: `event_type`, `sensor_id`, `account_code`
sort_direction	string	false	false	Allowed values: `desc`, `asc`

Response

The return is a JSON with three fields:

columns: Containing the column’s headers for the retrieved information.
data: A list containing the retrieved data. Each element is also a list with the values for each of the column’s headers
result_count: Containing the size of the retrieved list of data

Example

{
    "columns": […]
    "data": […]
    "result_count": 25
}

GET_TELEMETRY_PACKETSTATS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve packetstats telemetry data grouped by time.

Arguments

Argument	Type	Required	Multi-Value	Description
sensor_id	string	false	false	Sensor id to filter by.
account_code	string	false	false	Account code to filter by.
start_date	string	false	false	Start date/time to query for. The string default is 1 day ago for `interval=hour` or 30 days ago for `interval=day`.
end_date	string	false	false	End date/time to query for. The default is the current time.
interval	string	false	false	Interval to group by: `hour` (default) or `day`.
group_by	string	false	false	Optionally group results string by: interface_name, sensor_id or account_code.

Response

The return is a JSON with three fields:

columns: Contains the column’s headers for the retrieved information.
data: A list containing the retrieved data. Each element is also a list with the values for each of the column’s headers
result_count: Contains the size of the retrieved list of data

Example

{
    "columns": […]
    "data": […]
    "result_count": 25
}

GET_TELEMETRY_NETWORK

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve network telemetry data grouped by time.

Arguments

Argument	Type	Required	Multi-Value	Description
account_code	string	false	false	Account code to filter by.
start_date	string	false	false	Start date to filter by.
end_date	string	false	false	End date to filter by.
interval	string	false	false	The interval to filter by (`day`, `month_to_day`).
latest_each_month	string	false	false	Filters out all but the latest day and `month_to_date` for each month.
sort_order	string	false	false	Sorts by account code first, then timestamp. Allowed values: `asc` or `desc`. The default is `desc`.
limit	string	false	false	The number of records to return. Default=100 and Maximum=1000
offset	string	false	false	The number of records to skip. Default = `0`.

Response

The return is a JSON with six fields:

network_usage: Contains a list with the retrieved information.
total_count: he total amount of elements
result_count: Contains the number of elements that were retrieved.
sort_order:Either asc or desc.
limit: The maximum number of elements to be retrieved.
offset: The number of elements to be skipped.

Example

{
    "network_usage": […],
    "total_count": 10379, 
    "result_count": 1000, 
    "sort_order": "desc",
    "limit": 1000, 
    "offset": 0
}

GET_ENTITY_SUMMARY

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve summary information about an IP or domain.

Arguments

Argument	Type	Required	Multi-Value	Description
entity	string	true	false	Entity for which you want to retrieve the information
account_uuid	string	false	true	Account UUIDs to filter by. If absent, all the caller's allowed accounts will be queried.
entity_type	string	false	false	Type of the entity we are searching. Allowed values are: `ip`, `domain`.

Response

The return is a JSON with two fields:

query_type: The type of the query (i.e., ip_address, domain, etc.).
summary: The retrieved summary information.

Example

{
    "query_type": "ip_address",
    "summary": {
        "entity": …,
        "first_seen": …,
        "last_seen": …,
        "prevalence_count_internal": …,
        "tags": […]
    }
}

GET_ENTITY_ANNOTATIONS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve annotations information about an IP address.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	true	Account uuid owning the annotations. If absent or null, all allowed accounts for the caller will be used.
entities	string	true	false	JSON string containing the list of entities to lookup. Each item containing the entity and its type. Example: [ { "entity": "10.0.0.1", "entity_type": "ip" }, { "entity": "10.0.0.2", "entity_type": "ip" } ]

Argument

Type

Required

Multi-Value

Description

account_uuid

string

false

true

Account uuid owning the annotations. If absent or null, all allowed accounts for the caller will be used.

entities

string

true

false

JSON string containing the list of entities to lookup. Each item containing the entity and its type. Example:

[
  {
    "entity": "10.0.0.1",
    "entity_type": "ip"
  },
  {
    "entity": "10.0.0.2",
    "entity_type": "ip"
  }
]

Response

The return is a JSON containing the list of annotations for each entity. Each item containing three fields:

account_code: account owning the annotations.
entity: Contains the provided entity and its type.
annotations: the list of annotations for the specific entity.dhcp

Example:

{
  "entity_annotations": [
    {
      "account_code": "…",
      "entity": {
        "entity": "10.0.0.1",
        "entity_type": "ip"
      },
      "annotations": [ … ]
    },
    {
      "account_code": "…",
      "entity": {
        "entity": "10.0.0.2",
        "entity_type": "ip"
      },
      "annotations": [ … ]
    }
  ]
}

GET_ENTITY_PDNS

This endpoint is used to communicate with FortiNDR Cloud Service to retrieve passive DNS information about an IP or domain.

Arguments

Argument	Type	Required	Multi-Value	Description
entity	string	true	false	Entity for which we want to retrieve the PDNS information.
account_uuid	string	false	true	Limit results to the specified account UUID(s). Defaults to all accounts for which the user has permission.
record_type	string	false	true	Limit results to the specified DNS query type(s). Supported types are: A, AAAA, CNAME, MX, NS. Case insensitive.
source	string	false	true	Limit the results to the specified data source(s). Note that not all Sources populate all fields. Supported sources are: ICEBRG_DNS. Case insensitive.
start_date	string	false	false	The earliest date before which to exclude results. Day granularity, inclusive.
end_date	string	false	false	The latest date before which to exclude results. Day granularity, inclusive.
resolve_external	string	false	false	Sorts by account code first, then timestamp. Allowed values: `asc`or `desc`. The default is `desc`.
limit	string	false	false	Maximum number of records to be returned. Default 1000.

Response

The return is a JSON with three fields:

query_type: The type of the query (i.e., ip_address, domain, etc.).
result_count: Contains the number of elements that were retrieved.
passivedns: A list containing the retrieved PDNS information.

Example

{
    "query_type": "ip_address",
    "result_count": 1000, 
    "passivedns": […]
}

GET_ENTITY_DHCP

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve DHCP information about an IP address.

Arguments

Argument	Type	Required	Multi-Value	Description
entity	string	true	false	Entity for which we want to retrieve the DHCP information
account_uuid	string	false	true	Limit results to the specified account UUID(s). Defaults to all accounts for which the user has permission.
sensor_id	string	false	false	Sensor id to filter by.
start_date	string	false	false	Limit the results to those DHCP leases that `start` after this start date.
end_date	string	false	false	Limit the results to those DHCP leases that `start` before this end date.

Response

The return is a JSON with three fields:

query_type:The type of the query (i.e., ip_address, domain, etc.).
result_count: Contains the number of elements that were retrieved.
dhcp: A list containing the retrieved DHCP information.

Example

{
    "query_type": "ip_address",
    "result_count": 1000, 
    "annotations": […]
}

GET_ENTITY_FILE

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve information about a file.

Arguments

Argument	Type	Required	Multi-Value	Description
entity	string	true	false	Entity for which we want to retrieve the information
account_uuid	string	false	true	Account UUID(s) to filter by. If absent, all the caller's allowed accounts will be queried.

Response

The return is a JSON with three fields:

query_type: The type of the query (i.e., ip_address, domain, etc.).
hash_type: The hash type that was applied.
file: The retrieved file’s information.

Example

{
    "query_type": "ip_address",
    "hash_type": 1000, 
    "file": {…}
}

GET_DETECTIONS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of detections.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	Account to filter results by.
rule_uuid	string	false	true	Rule UUID's to filter results by.
status	string	false	true	Status to filter results by (`active`, `resolved`).
device_ip	string	false	false	Device IP to filter by.
sensor_id	string	false	false	Sensor ID to filter by.
include	string	false	true	Include linked objects (`rules`, `indicators`).
sort_order	string	false	false	Direction of sort (`desc`, `asc`).
sort_by	string	false	false	Filed to sort by `(first_seen`, `last_seen`, `status`, `device_ip`, `indicator_count`).
limit	int	false	false	The number of records to include (default:100, max:10,000)
offset	int	false	false	The number of records to skip.
is_muted	bool	false	false	Filter results by whether a detection is muted by any way.
muted	bool	false	false	Filter results by whether or not the detection is muted.
muted_rule	bool	false	false	Filter results by whether the associated rule is muted for the account.
muted_device	bool	false	false	Filter results by whether the device is muted.
rule_severity	string	false	true	Filter results by rule severity (low, moderate, high).
rule_category	string	false	true	Filter results by rule category.
rule_confidence	string	false	true	Filter results by rule confidence (low, moderate, high).
resolution	string	false	true	Filter results by resolution in resolution table.
resolution_user_uuid	string	false	true	Filter results by resolution user UUID.
uuid	string	false	false	Filter results if there is resolution user UUID on the detection.
resolve_start_date	string	false	false	Resolved start date to filter by (inclusive).
resolve_end_date	string	false	false	Resolved end date to filter by (exclusive).
active_start_date	string	false	false	Active start date to filter by (inclusive).
active_end_date	string	false	false	Active end date to filter by (exclusive).
created_start_date	string	false	false	Created start date to filter by (inclusive).
created_end_date	string	false	false	Created end date to filter by (exclusive)
created_or_shared_start_date	string	false	false	Created or shared start date to filter by (inclusive).
created_or_shared_end_date	string	false	false	Created or shared end date to filter by (exclusive).
rule_enabled	string	false	false	Filter results if the rule is enabled.
rule_attack_id	string	false	true	Filter results by rule attack IDs.
rule_account_uuid	string	false	false	Filter results by rule account UUID.
indicator_value	string	false	false	Indicator value to filter by.

Response

The return is a JSON with eight fields:

detections: A list with the retrieved detections.
rules: A list with the rules associated to the retrieved detections.
total_count: The total amount of elements
result_count: Contains the number of elements that were retrieved.
sort_order: Either asc or desc.
sort_by: Feld used to sort the result (first_seen, last_seen, status, device_ip, indicator_count).
limit: The maximum number of elements to be retrieved
offset: The number of elements to be skipped.

Example

{
    "result_count": 6074, 
    "total_count": 6074, 
    "detections": […],
    "sort_by": "first_seen",
    "sort_order": "asc",
    "offset": 0, 
    "limit": 10000, 
    "rules": […]
}

RESOLVE_DETECTION

This endpoint is used to communicate with the FortiNDR Cloud Service to resolve a detection.

Arguments

Argument	Type	Required	Multi-Value	Description
detection_id	string	true	false	UUID for the detection to be resolved
resolution	string	true	false	Resolution category (`true_positive_mitigated`, `true_positive_no_action`, `false_positive`, `unknown`).
resolution_comment	string	false	false	Optional comment for the resolution.

Response

This endpoint returns an empty HTTP 204 response.

GET_DETECTION_EVENTS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of events associated to a detection.

Arguments

Argument	Type	Required	Multi-Value	Description
detection_uuid	string	true	false	UUID for the detection to filter by.
offset	string	false	false	The number of records to skip past. The default is 0.
limit	string	false	false	The maximum number of records to return. The default is 0 and the max is 1000.

Response

The return is a JSON with three fields:

events: A list containing the retrieved events.
total_count: The total amount of elements
result_count: Contains the number of elements that were retrieved.

Example

{
    "result_count": 6074, 
    "total_count": 6074, 
    "events": […]
}

GET_RULES

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of rules.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	Optional account to filter results by.
rule_account_uuid	string	false	false	Optional account to filter rule account sub-objects by.
search	string	false	false	Search string on name, category or description.
has_detections	bool	false	false	Include rules that have unmuted, unresolved detections.
detection_device_ip	string	false	false	Device IP of associated detections to filter by. Note the associated detections are determined by the `has_detections param`.
indicator_value	string	false	false	Case insensitive prefix search of related indicators.
severity	string	false	true	List of severities to filter by (low, moderate, high).
confidence	string	false	true	List of confidences to filter by (low, moderate, high).
category	string	false	true	Category to filter by (see above).
rule_account_muted	bool	false	false	Include muted rules accounts for the given `account_uuid`.
enabled	bool	false	false	Enabled rules only.
attack_id	string	false	true	List of MITRE ATT&CK technique ID to filter by. Leave blank or null to turn off this filter.
sort_by	string	false	false	The field to sort by: `created`, `updated`, `detections`, `severity`, `confidence`, `category`, `last_seen`, `detections_muted`. Defaults to updated.
sort_order	string	false	false	The sort order: `asc` or `desc`. The default is `desc`.
limit	int	false	false	The maximum number of records to return. Default: 100, Max: 1000.
offset	int	false	false	The number of records to skip past. Default: 0.

Response

The return is a JSON with ten fields:

rules: The list of the rules retrieved.
accounts: The list of the associated accounts.
active_rule_count: The number of active rules
enabled_rule_count: The number of enabled rules.
total_count: The total amount of elements
result_count: Contains the number of elements that were retrieved.
sort_order: Either asc or desc.
sort_by: Filed used to sort the result (first_seen, last_seen, status, device_ip, indicator_count).
limit: The maximum number of elements to be retrieved
offset: The number of elements to be skipped.

Example

{
    "rules": […],
    "accounts": […],
    "active_rule_count": 404, 
    "enabled_rule_count": 1723, 
    "result_count": 100, 
    "total_count": 1843, 
    "sort_by": "updated",
    "sort_order": "desc",
    "offset": 100, 
    "limit": 100
}

GET_RULE

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a specific rule.

Arguments

Argument	Type	Required	Multi-Value	Description
`rule_id`	string	true	false	UUID for the rule to filter by.

Response

The return is a JSON with two fields:

rule: Contains the retrieved rule.
accounts: A list containing the associated accounts.

Example

{ 
    "rule": {…},
    "accounts": […],
}

CREATE_RULE

This endpoint is used to communicate with the FortiNDR Cloud Service to create a rule.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	true	false	Rule’s account
name	string	true	false	Rule’s name
category	string	true	false	Rule’s category
query_signature	string	true	false	Rule’s query signature
description	string	false	false	Rule’s description
severity	string	true	false	Rule’s severity
confidence	string	true	false	Rule’s confidence
primary_attack_id	string	false	false
secondary_attack_id	string	false	false
specificity	string	false	false
device_ip_fields	string	true	false
indicator_fields	string	false	false
run_account_uuids	string	true	false
auto_resolution_minutes	string	false	false	Time to be automatically resolved

Response

The return is a JSON with a field rule containing the created rule.

Example

{ 
    "rule": {
        "uuid": "…",
        "account_uuid": "…",
        "shared_account_uuids": null, 
        "run_account_uuids": ["…"],
        "name": "…",
        "category": "…",
        "query_signature": "…",
        "description": null, 
        "severity": "…",
        "confidence": "…",
        "auto_resolution_minutes": null, 
        "enabled": true, 
        "created_user_uuid": "…",
        "created": "…",
        "updated_user_uuid": "…",
        "updated": "…",
        "critical_updated": "…",
        "primary_attack_id": null, 
        "secondary_attack_id": null, 
        "specificity": null, 
        "rule_accounts": null, 
        "device_ip_fields": ["…"],
        "indicator_fields": null, 
        "source_excludes": ["…"]
    }
}

GET_RULE_EVENTS

This endpoint is used to communicate with the FortiNDR Cloud Service to retrieve a list of events associated to a rule.

Arguments

Argument	Type	Required	Multi-Value	Description
account_uuid	string	false	false	UUID for the account to filter by.
offset	string	false	false	The number of records to skip past. The default is 0.
limit	string	false	false	The maximum number of records to return.The default is 0 and the max is 1000.

Response

The return is a JSON with three fields:

events: A list containing the retrieved events.
total_count: The total amount of elements
result_count: Contains the number of elements that were retrieved.

Example

{
    "result_count": 6074, 
    "total_count": 6074, 
    "events": […]
}

Secure Networking

Hybrid Mesh Firewall

NOC Management

LAN

WAN

Unified SASE

Single Vendor SASE

Cloud Network Security

Secure Endpoint Connectivity

Web Application / API Protection

Security Operations

Security Operations Automation

Identity

Early Detection & Prevention

Secure Networking

Hybrid Mesh Firewall

NOC Management

LAN

WAN

Communication & Surveillance

Unified SASE

Single Vendor SASE

Secure Endpoint Connectivity

Cloud Network Security

Cloud-Native Security

Web Application / API Protection

Security Operations

Security Operations Automation

Endpoint

Data Protection

Identity

Email

Early Detection & Prevention

Expert Services

Edge Firewall

Orchestration & management

SD Branch

Application Delivery

Single Vendor SASE

Secure Endpoint Connectivity

Secure Private Access

Thin Edge

Identity

Application Gateway

Enterprise Asset Management

Endpoint Agent

Agentless Security Posture

Identity

Wireless

Switching

Identity

Privilege Acccess Management

Next Generation Firewall

Orchestration & management

Expert Services

Web Application / API Protection

All

All

Account Management

SAAS Management

SAAS Application Security

Managed Services

Platform as a service (PAAS)

Other SAAS Services

4D Pillars

Cloud

Popular Solutions

All Products

FNC Python Library

FncClient Library Supported Endpoints

FncClient Library Supported Endpoints

GET_SENSORS

Arguments

Response

Example

GET_DEVICES

Arguments

Response

Example

GET_TASK