Appendix A: API guide

This section explains how to use the FortiNDR API.

FortiNDR REST API currently supports the following:

• Files submission for scanning
• Retrieve files verdict result
• Get file STIX2 report
• Starting network share scan
• Events API support (detections based on source IP/Mac/hostname and anomaly type)

Get an administrator API key

You can submit files for analysis using API with an API key. You can generate an API key using the GUI or CLI. The API key has all access privileges of the admin user.

The token is only displayed once. If you lose the token, you must generate a new one.

Upload files using API

You can use API to upload files for Express Malware Analysis. The maximum upload file size is 200MB.

To use API to upload files, generate a token. The token is only displayed once. If you lose the token, generate a new one.

To generate a token using CLI:

execute api-key <user-name>

To generate a token using GUI:

1. Go to System > Administrator and edit an administrator.
2. In the API Key section, click Generate.

   

Use an API key

When making API calls, the API key is required in the request. You can include the API key in the API request header or URL parameter.

To pass the API token by request header, explicitly add the following field to the request header.

Authorization: Bearer <YOUR-API-TOKEN>

To pass the API token by URL parameter, explicitly include the following field in the request URL parameter.

access_token=<YOUR-API-TOKEN>

Submit files

/api/v1/files

You can submit files for analysis through the /api/v1/files endpoint with an administrator API key.

For a list of supported file types and formats, see FortiNDR traffic and files input types .

Submit a file using one of the following methods.

In both methods, you can use the API key as a URI parameter or the Authorization field in the header. Passwords for zip files are optional. You can view the verdict of submitted files in Virtual Security Analyst > Express Malware Analysis.

Example 1 of submitting a file or zip file via JSON data using the Python Requests module:

self.session.post(url='/api/v1/files?access_token=***API-KEY HERE***',
     data={" file_name": " b64encode(FILENAME)",
     	"file_content": b64encode(open(PATH_TO_FILE, "rb").read())},
      	"password":" ***ZIP FILE PASSWORD HERE(OPTIONAL)***")

Example 2 of submitting a file or zip file via JSON data using the Python Requests module:

self.session.post(url='/api/v1/files',
     headers={'Authorization': 'Bearer ***API-KEY HERE***'}
     data={" file_name": " b64encode(FILENAME)",
     	"file_content": b64encode(open(PATH_TO_FILE, "rb").read())},
        "password":" ***ZIP FILE PASSWORD HERE(OPTIONAL)***")

Example 1 of submitting a file or zip file as a multi-part file using the Python Requests module:

self.session.post(url='/api/v1/files? access_token=***API-KEY HERE***'',
     data={"password":”***ZIP FILE PASSWORD HERE(OPTIONAL)***”},
     files={"file":( os.path.basename(PATH_TO_FILE),open(PATH_TO_FILE,"rb"))})

Example 2 of submitting a file or zip file as a multi-part file using the Python Requests module:

self.session.post(url='/api/v1/files',
     headers={'Authorization': 'Bearer ***API-KEY HERE***'},
     data={"password":”***ZIP FILE PASSWORD HERE(OPTIONAL)***”},
     files={"file":( os.path.basename(PATH_TO_FILE),open(PATH_TO_FILE,"rb"))})

Upload file by JSON data

Encode the file name into the HTTP body as JSON data using the file_name field.

Encode the file contents into the HTTP body as JSON data using the file_content field. The maximum file size is 200MB.

You have the option to include the password in the HTTP body as JSON data using the password field where a password is needed to extract an archived file.

The following is an example of Python request module by JSON data.

requests.post(url='/api/v1/files',

params={'access_token': 'u4VvEDpUATpJbFUfpbCzlSduTddCOIs'},

data={ 'file_name': b64encode('samples.zip'),

' file_content': b64encode(open('samples.zip', 'rb').read()),

' password': 'xxxxxxxx'})

Upload file by multi-part file

The following is an example of Python request module by multi-part file.

requests.post(url='/api/v1/files',

params={'access_token': 'u4VvEDpUATpJbFUfpbCzlSduTddCOIs'},

files={'samples.zip':open('samples.zip', 'rb')})

Retrieve file verdict results

/api/v1/verdict

The query string can only have one search query parameter.

Examples

GET /api/v1/verdict?sid= ***submission_id***

{
  "results": {
    "fileids": [
      7,8,9,10,11,12,13,14,15

    ],
    "total_fileids": 9
  } 
}

GET /api/v1/verdict?fileid= ***file_id***

{
  "results": {
    "file_id": 5742600,
    "virus_name": "W32/Miner.VI!tr",
    "md5": "bbd72472f8d729f4c262d6fe2d9f2c8c",
    "sha512": "cce8e67772f19bcfe5861e4c1b8eec87016bb7cf298735db633490243bc0391a017c7d6b805f225775405598614be48c5479cb7f1c54d957e6129effbf9cca37",
    "file_size": 1141544,
    "source": "http://172.16.77.46/api/sample_download/1106042791/",
    "severity": "High",
    "category": "Trojan",
    "family":"Emotet",
    "feature_composition": [
      {
        "feature_type": "Trojan",
        "appearance_in_sample": 986
      },
      {
        "feature_type": "Application",
        "appearance_in_sample": 95
      }
    ],
    "create_date": "2020-07-31",
    "confidence": "High",
    "file_type": "PE",
    "victim_ip": "172.19.235.225",
    "attacker_ip": "172.16.77.46",
    "victim_port": 35400,
    "attacker_port": 80,
    "engine_version": 1.013,
    "kdb_version": 1.037,
    "tmfc": 0,
    "pbit": 3
  }
}

parent_fname

Example of problems retrieving results

{
  "http_code": 400,
  "message": "INVALID_PARAM"
}

Submitted file errors explanation:

When using /ap1/v1/verdict?sid=xxx to retrieve the file verdict in the following two cases:

• Oversized file
• Oversized archive contents

You will get reply: {"http_code": 400, "message":"OVERSIZED_FILE"}

In the other following cases:

• Unextractable archive
• File is still in queue
• File is still scanned

You will get successful reply with only supported file ids in the fileids list:

{

"results": {

    "fileids": [xx],

    "total_fileids": x

}

}

Once you get the fileid from submit id, using /ap1/v1/verdict?fileid=xxx

In the following two cases:

• File is still in queue
• File is still to be scanned

You will get reply: {"http_code": 200, "message":"DATA_IN_PROCESS"}

Get file stix2 report

/api/v1/report

The query string can only have one search query parameter.

Examples

GET /api/v1/report?fileid= ***file_id***

{
  "results": {
    *** STIX2 report content ***
  } 
}

HTTP status table

Start Network Share scan

/api/v1/nfs/scan

Examples

GET /api/v1/nfs/scan?sname= ***network share profile name***
{
	"http_code": 200,
	"message": "OK"
}

Example of failed to start Network Share scan

{
	"http_code": 400,
	"message": "Scanning in Progress"
}

Events API support

/api/v1/events

Examples

GET /api/v1/events?ip= 192.168.1.114 &type=network-attack&start_time=1695020154&end_time=1698111999 &start=0&size=2
{
   "results":[
      {
         "event_time":"2023-10-23 16:15:53",
         "source_ip":"192.168.1.114",
         "source_port":38123,
         "destination_ip":"192.168.1.110",
         "destination_port":17185,
         "severity":"Low",
         "attack_name":"Nmap.Script.Scanner"
      },
      {
         "event_time":"2023-10-23 16:15:53",
         "source_ip":"192.168.1.114",
         "source_port":38124,
         "destination_ip":"192.168.1.110",
         "destination_port":17185,
         "severity":"Low",
         "attack_name":"Nmap.Script.Scanner"
      }
   ]
}