Get Started with FIM APIs

Welcome to File Integrity Monitoring API. This help is intended for application developers who use the FIM APIs.

Qualys API Framework

Learn the basics about making API requests. The base URL depends on the platform where your Qualys account is located.

The Qualys Certificate View API uses the following framework.

Request URLRequest URL

The URL for making API requests respects the following structure:

https://<baseurl>/<module>/<object>/<object_id>/<operation>

Refer to the following table for the field description.

Field Description

<baseurl>

The Qualys API server URL that you should use for API requests depends on the platform where your account is located. The base URL for Qualys US Platform 1 is: https://gateway.qg1.apps.qualys.com

<module>

The API module. For the FIM API, the module is: “fim”.

<object>

The module-specific object.

<object_id>

(Optional) The module-specific object ID, if appropriate.

<operation>

The request operation, such as count.

Qualys API Gateway URL

The Qualys API URL you should use for API requests depends on the Qualys platform.

Click here to identify your Qualys platform and get the API URL

This documentation uses the API gateway URL for Qualys US Platform 1 (https://gateway.qg1.apps.qualys.com) in sample API requests. If you’re on another platform, please replace this URL with the appropriate gateway URL for your account.

Qualys API Postman Collection

Interact with Qualys APIs using Postman. Instead of creating calls manually to send over the command line, you can use the Qualys Postman Collection to get started with Qualys APIs quickly. 

Click here to view the steps involved.

Introduction to FIM API Paradigm  

Get tips on using the Curl command-line tool to make API requests. Every API request must authenticate using a JSON Web Token (JWT) obtained from the Qualys Authentication API. The Qualys File Integrity Monitoring API uses the following framework.

AuthenticationAuthentication

You must authenticate to the Qualys Cloud Platform using Qualys account credentials (user name and password) and get the JSON Web Token (JWT) before you can start using the Certificate View APIs. Use the Qualys Authentication API to get the JWT.

 The Authentication API returns a JSON Web Token (JWT) which you can use for authentication during FIM API calls. The token expires in 4 hours. You must regenerate the token to continue using the FIM API.

Example Authentication Curl Request:

API Request

curl -X POST 
"<qualys_base_url>/auth" -H "Content-Type: application/x-www-form-urlencoded" 
-d "username=value1&password=value2&token=true&permissions=true" -H "ContentType: application/x-www-form-urlencoded"
    

The following table explains the various components of this request:

qualys_base_url It is the base URL for the Qualys API server where your account is located. 
The base URL for Qualys US Platform 1 is: https://gateway.qg1.apps.qualys.com
value1 and value2 value1 is the username and value 2 is the password of the user account for which you want to fetch Asset Management data.
token It must be true.
permissions It must be true.
Content-Type It must be application/x-www-form-urlencoded.

Using CurlUsing Curl

Curl is a multi-platform command-line tool used to transfer data using multiple protocols. This tool is supported on many systems, including Windows, Unix, Linux and Mac. In this document Curl is used in the examples to build Qualys API requests using the HTTP over SSL (https) protocol, which is required.

Want to learn more? Visit https://curl.haxx.se/

The following Curl options are used according to different situations:

Field

Description

- X GET/POST

The GET method is required for all FIM API requests.

-H “Authorization: Bearer <token>”

This option is used to provide a custom HTTP request header parameter for authentication. Provide the JSON Web Token (JWT) received from Qualys authentication API in the following format:

Authorization: Bearer <token>

-d @request.json Provide a request.json file for parameter input.
--data-urlencode Used to encode spaces and special characters in the URL/Parameter values.

The following sample shows a typical Curl request using the options mentioned and how they interact.

Curl Request

curl -X POST
"<qualys_base_url>
/fim/v2/events/search 
-H 'authorization: Bearer <token>'
 -H 'content-type: application/json'
-d @request.json <token>"
  

Response Codes

HTTP response codes are messages sent by servers to indicate how they have handled a request. To know the HTTP response code you receive when you make API requests, refer to the Appendix: HTTP Response Codes

Fetching more than ten Thousand Events

FIM APIs are designed to fetch less that ten thousand (9999 events) per page for optimum performance. You can use the searchAfter parameter in order to fetch more than ten thousand events. First you need to use the sort parameter to sort events using a filter that has unique values such as ID, name, etc. Each event is returned with an identifier called sortValue. To fetch events beyond the current page size, in subsequent API requests, provide the sortValue of an event to the searchAfter parameter to fetch events after that specific event.

searchAfter is supported for the following APIs:

/fim/v2/events/search

/fim/v2/events/ignore/search

/fim/v2/incidents/{incidentId}/events/search

/fim/v3/incidents/search

ExampleExample

Suppose you have fifteen thousand FIM events in your account. The first API request will only return 9999 events. To get events beyond 9999, in a subsequent API request, provide the sortValue of the 9999th event in the searchAfter parameter. The second API request will now fetch the remaining events starting from the 10000th event.

For better performance, it is recommended to use smaller page sizes of 1000/2000 records.

Example 1 

You need to sort a list before you can use searchAfter.

Step 1) Search events using the sort parameter.Step 1) Search events using the sort parameter.

API Request

curl -X POST
<qualys_base_url>/fim/v2/events/search-H'authorization: Bearer <token>' 
-H 'content-type:application/json' -d @request.json

Contents of request.json:

{
  "sort":"[{\"dateTime\":\"desc\"},{\"id\":\"desc\"}]",
  "pageSize":10
}

Response

[
  {
    "sortValues":[
      1556199372947,
      "9df007e9-9532-3558-a3a8-0b14d943670d"
    ],
    "data":{
      "dateTime":"2019-04-25T13:36:12.947+0000",
      "fullPath":"\\Device\\HarddiskVolume2\\Windows\\inf\\setupapi.app.log",
      "severity":4,
      "profiles":[
        {
          "name":"Minimum Baseline for PCI for Windows
OS_addTag",
          "rules":[
            {
              "severity":4,
              "number":6,
              "name":"Rule-6",
              "description":null,
              "id":"9287a14c-8036-4403-af88-
f98ae8f920fb",
              "type":"directory"
            }
          ],
          "id":"03dc1773-ae2a-4d5f-a5b3-e662e14afbd2",
          "type":"WINDOWS",
          "category":{
            "name":"PCI",
            "id":"2dab5022-2fdd-11e7-93ae-92361f002671"
          }
        }
      ],
      "type":"File",
      "changedAttributes":null,
      "platform":"WINDOWS",
      "oldContent":null,
      "actor":{
        "process":"NPFInstall.exe",
        "processID":8632,
        "imagePath":"\\Device\\HarddiskVolume2\\Program
Files\\Npcap\\NPFInstall.exe",
        "userName":"MALWARELAB-IOC\\Administrator",
        "userID":"S-1-5-21-122566442-3410611961-
1220210811-500"
      },
      "newContent":null,
      "customerId":"58b888be-a90f-e3be-838d-88877aee572b",
      "name":"setupapi.app.log",
      "action":"Attributes",
      "id":"9df007e9-9532-3558-a3a8-0b14d943670d",
      "asset":{
        "agentId":"f2a0a778-e5b6-4486-826d-a16762588a2a",
        "interfaces":[
          {
            "hostname":"MALWARELAB-IOC",
            "macAddress":"00:50:56:AA:6B:B8",
            "address":"10.115.77.190",
            "interfaceName":"Intel(R) PRO/1000 MT
Network Connection"
          }
        ],
        "lastCheckedIn":"2019-04-25T13:51:48.000Z",
        "created":"2018-11-01T04:58:21.000+0000",
        "hostId":"290890",
        "operatingSystem":"Microsoft Windows 7 Professional
6.1.7601 Service Pack 1 Build 7601",
        "tags":[
          "7650412",
          "7655820",
          "7895614"
        ],
        "assetType":"HOST",
        "system":{
          "lastBoot":"2019-03-13T21:49:47.500Z"
        },
        "ec2":null,
        "lastLoggedOnUser":".\\Administrator",
        "netbiosName":"MALWARELAB-IOC",
        "name":"MALWARELAB-IOC",
        "agentVersion":"3.0.0.101",
        "updated":"2019-04-25T13:51:48.729+0000"
      },
      "class":"Disk"
    }
  },
  {
   .
   .
    }
  },
  "..."
]

Step 2) Take one of the sort Values from the above response and provide it as input for search after. This will fetch events after that particular sort value.Step 2) Take one of the sort Values from the above response and provide it as input for search after. This will fetch events after that particular sort value.

API Request

curl -X POST 
<qualys_base_url>/fim/v2/events/search -H 'authorization: Bearer <token>' 
-H 'content-type: application/json' -d @request.json

Contents of request.json:

{
  "sort":"[{\"dateTime\":\"desc\"},{\"id\":\"desc\"}]",
  "pageSize":10,
  "searchAfter":[
    1556199372947,
    "05a9bbea-d03c-3bc3-9421-5d3cbb8ac630"
  ]
}

Response

[
  {
    "sortValues":[
      1556199372946,
      "d47984c3-71d8-36b5-84d4-bb0ec34af828"
    ],
    "data":{
      "dateTime":"2019-04-25T13:36:12.946+0000",
      "fullPath":"\\Device\\HarddiskVolume2\\Windows\\inf\\setupapi.app.log",
      "severity":4,
      "profiles":[
        {
          "name":"Minimum Baseline for PCI for Windows
OS_addTag",
          "rules":[
            {
              "severity":4,
              "number":6,
              "name":"Rule-6",
              "description":null,
              "id":"9287a14c-8036-4403-af88-
f98ae8f920fb",
              "type":"directory"
            }
          ],
          "id":"03dc1773-ae2a-4d5f-a5b3-e662e14afbd2",
          "type":"WINDOWS",
          "category":{
            "name":"PCI",
            "id":"2dab5022-2fdd-11e7-93ae-92361f002671"
          }
        }
      ],
      "type":"File",
      "changedAttributes":null,
      "platform":"WINDOWS",
      "oldContent":null,
      "actor":{
        "process":"NPFInstall.exe",
        "processID":8632,
        "imagePath":"\\Device\\HarddiskVolume2\\Program
Files\\Npcap\\NPFInstall.exe",
        "userName":"MALWARELAB-IOC\\Administrator",
        "userID":"S-1-5-21-122566442-3410611961-
1220210811-500"
      },
      "newContent":null,
      "customerId":"58b888be-a90f-e3be-838d-88877aee572b",
      "name":"setupapi.app.log",
      "action":"Attributes",
      "id":"d47984c3-71d8-36b5-84d4-bb0ec34af828",
      "asset":{
        "agentId":"f2a0a778-e5b6-4486-826d-a16762588a2a",
        "interfaces":[
          {
            "hostname":"MALWARELAB-IOC",
            "macAddress":"00:50:56:AA:6B:B8",
            "address":"10.115.77.190",
            "interfaceName":"Intel(R) PRO/1000 MT
  "..."
]
                   

Data Retention Policy

To comply with data retention policies and regulations, the API allows access to data only from the last 15 months. Data older than 15 months cannot be accessed. This restriction is implemented to ensure legal compliance and effective data management.

For example, even if you request an API to fetch data from the last four years, the response includes data from the last 15 months only. 

The affected APIs are:

Get API Notifications

Subscribe to our API Notifications RSS Feeds for announcements and the latest news.

From our Community

Join our Community

API Notifications RSS Feeds