File Metadata Collection exclusions via API

Overview

This article explains how to use the Incydr API to define a list of file types and file paths to exclude from File Metadata Collection monitoring. This helps ensure user devices don't spend resources indexing file metadata for files you're not interested in monitoring. It also prevents irrelevant or unimportant file events from appearing in dashboard visualizations, alerts, and Forensic Search results. The examples in this article use curl, but the concepts apply to any tool you choose for interacting with the API.

Use the Incydr console
You can use the Incydr console instead of the API to exclude file types and paths from monitoring. See File event exclusions for details. Using the Incydr console provides a more streamlined and less error-prone experience. 

Considerations

• Exclusions must be defined in regular expression (regex) format.
• Exclusions apply to all users and organizations in your Incydr environment.
• You must have credentials for an Incydr user with the Org Admin or Cross Org Admin role. An Org Admin must be an administrator of the top-level organization.

Incydr Developer Portal
See the Developer Portal for more API documentation and resources. The portal provides:

• A single access point for documentation of methods for Incydr, including the REST API, Incydr SDK, and command-line interface (CLI)
• A single request URL for API calls to each cloud instance
• API reference documentation 

Use the Developer Portal for your API needs as much as possible. APIs in the portal are the preferred way to integrate with Incydr. If you use APIs that do not appear on the Developer Portal, contact our Technical Support Engineers for guidance on the best way to integrate with Incydr.

API request details

• Request URL: Determine the URL for your Incydr cloud instance 
• Resource: OrgSettings
• Key: artemis_device_fileForensics_fileExclusions_org
• Methods: GET to view existing exclusions; PUT to add or update exclusions

View and update exclusions

Step 1: Find your top-level OrgID

To view and edit exclusions, you must first identify your top-level organization's numeric ID. 

1. Sign in to the Incydr console.
2. Select Administration > Environment > Organizations.
3. Select Export.
   The list of organizations is downloaded to your device as a CSV file.
4. Open the downloaded CSV and locate the applicable organization.
5. Note the numeric ID in the orgID column.

Step 2: View existing exclusions

Use the GET method to view existing exclusions. The OrgSettings resource also contains keys for numerous other settings. Therefore, to view only the exclusions, you must include the appropriate key as a query parameter.

The example below assumes basic familiarity with curl commands. Use this as a template to create a command specific to your Incydr environment:

curl -X GET \
  '<request_url>/api/v1/OrgSettings/<OrgID>?keys=artemis_device_fileForensics_fileExclusions_org' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <auth_token>'

1. Replace <request_url> with the address of your Incydr environment (do not include the brackets in your request).
2. Replace <OrgID> with the number identified in Step 1 above (do not include the brackets in your request).
3. Replace <auth_token>  with an
   The API/Admin/Monitoring_and_managing/Code42_API_resources/Code42_API_authentication_methods#Use_basic_authentication_to_obtain_a_token" href="/hc/en-us/articles/42665963622547-Code42-API-authentication-methods#Use_basic_authentication_to_obtain_a_token" rel="internal"authentication token.
4. returns the existing exclusions. If no exclusions exist yet, the data object in the response is empty.

Step 3: Update or add new exclusions

Use the PUT method to add or modify exclusions. Before sending any updates, make sure to complete Step 2 above to obtain the list of existing exclusions.

Updates overwrite existing exclusions
The OrgSettings API resource does not automatically add to existing values. All PUT requests completely replace existing values. Therefore, to add to existing exclusions, you must first obtain a list of current exclusions and re-submit that entire list with your new additions.

The steps below assume basic familiarity with curl commands. Use the following example as a template to create a command specific to your Incydr environment.

curl -X PUT \
  '<request_url>/api/v1/OrgSettings/<OrgID>' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <auth_token>' \ -d '{ "packets": [ { "key": "artemis_device_fileForensics_fileExclusions_org", "value": { "all":[ "'.*cache.*'" ], "macintosh":[ "'.*.db'" ], "windows":[ "'.*.etl'", "'.*.tmp'" ], "linux": [ "'/sys/.*'", "'/proc/.*'" ] }, "locked": true } ] }'

1. Replace <request_url> with the address of your Incydr environment (do not include the brackets in your request).
2. Replace <OrgID> with the number identified in Step 1 above (do not include the brackets in your request).
3. Replace <auth_token>  with an authentication token.
4. Define exclusions with regex for each operating system in use in your Incydr environment. Defining specific exclusions for each operating system minimizes the resources required on user devices. In this example:
   • All devices will exclude files with the .cache extension
   • Mac devices will exclude files with the .db extension
   • Windows devices will exclude files with the .etl and .tmp extension
   • Linux devices will exclude files in the sys and proc directories
5. Execute the curl command in your command-line tool of choice. When prompted, enter your password.
   A 204 No Content response indicates the Incydr cloud received the request and applied the exclusions to user devices.

Delete all exclusions

Use the DELETE method to remove all exclusions. To prevent inadvertent removal of other system settings, you must include the appropriate key as a query parameter.

Include key parameter to prevent removal of other system settings
To test this request, submit it first as a GET request and make sure the response includes only the artemis_device_fileForensics_fileExclusions_org key. Then resubmit it as a DELETE request.

The OrgSetting resource also contains keys for numerous other settings. Therefore, it is very important to list the correct key as a query parameter in the request URL. Failure to specify the key will cause other system settings to be deleted by this request.

The example below assumes basic familiarity with curl commands. Use this as a template to create a curl command specific to your Incydr environment:

curl -X DELETE \
  '<request_url>/api/v1/OrgSettings/<OrgID>?keys=artemis_device_fileForensics_fileExclusions_org' \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -H 'Authorization: Bearer <auth_token>'

1. Replace <request_url> with the address of your Incydr environment (do not include the brackets in your request).
2. Replace <OrgID> with the number identified in Step 1 above (do not include the brackets in your request).
3. Replace <auth_token>  with an authentication token.
4. Execute the curl command in your command-line tool of choice. When prompted, enter your password.
   A 204 No Content response indicates the Incydr cloud received the request and deleted all exclusions.

External resources

• Curl: Command line tool and library reference
• Wikipedia: Regular expressions (regex)

Related topics

• Forensic Search API 
• File event metadata reference 
• Forensic Search use cases
• Search file activity with Forensic Search