Scan and Remediate Local Storage Locations with Reference Number in Path

This example describes the workflow and sequence of requests to make to (i) scan specific folders and files containing certain reference numbers in the path name on a server or workstation Target, and (ii) remediate (Delete Permanently) the folders and files that match that criteria.

• Step 1 - Create Global Filter
• Step 2 - Scan Local Storage Files
• Step 3 - List Objects with Matches
• Step 4 - Remediate Files with Matches

Defaults and Assumptions

This example uses the following default values and makes the following assumptions:

1. "My-Windows-Server" is the host name of the Windows workstation that has been added as a Target (Target id = 13449404194559543980).
2. Local storage ("All local files") has been added as a Target Location (Target Location id = 8987302884414283716).
3. You want to scan folders and files that contain the following any of the following reference numbers in the path name:
   • 12345
   • 67890

Step 1 - Create Global Filter

Create a new Global Filter for "My-Windows-Server" to only scan specific folders and files that contain certain reference numbers in the path.

• apply_to will be applied to the My-Windows-Server (id = 13449404194559543980).
• type: exclude_expression.
• expression: !*12345* | !*67890*.

Sample Request

curl --request POST 'https://er-master:8339/v1/filters' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "apply_to": "13449404194559543980",
  "type": "exclude_expression",
  "expression": "!*12345* | !*67890*"
}'

Expected Response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: xxx
{
  "id": "5127911297873299453"
}  

The global filter created in this request will then be automatically be applied to all scans for the "My-Windows-Server" Target.

Step 2 - Scan Local Storage Files

Schedule a scan for the "My-Windows-Server" Target, where:

• label is a descriptive label for the scan.
• targets.id is 13449404194559543980 (see Defaults and Assumptions).
• targets.locations.id is 8987302884414283716 (see Defaults and Assumptions),
• targets.locations.subpath is the folder or file to scan. Leaving this field blank will scan all paths under "All local files".
• profiles is the list of data type profiles to be enabled in for the scan schedule.
• trace = true.

Sample Request

curl --request POST 'https://er-master:8339/v1/schedules' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "label": "My-Windows-Server API scan",
  "targets": {
    "id": "13449404194559543980",
    "locations": [
      {
        "id": "8987302884414283716",
        "subpath": ""
      }
    ]
  },
  "profiles": [
    "1",
    "2",
    "3"
  ],
  "cpu": "low",
  "throughput": 0,
  "memory": 0,
  "capture": true,
  "trace": true,
  "match_detail": "balanced"
}'

Expected Response

HTTP/1.1 201 Created
Content-Type: application/json
Content-Length: xxx
{
  "id": "34"
}  

You can check the status and progress of the scan using the scan schedule id (34) created in this request.

You can also view the Scan Trace Log to check that the folders and files have been scanned or filtered correctly according to the Global Filter rules set up in Step 1.

Step 3 - List Objects with Matches

Get a list of objects with matches using the file_name query parameter to limit the results to match objects with 12345 or 67890 in the folder or file name, where:

• target_id is 13449404194559543980 (see Defaults and Assumptions).

Sample Request

Get a list of objects that contain the reference number 12345 in the folder and/or file name.

curl --request GET 'https://er-master:8339/v1/targets/13449404194559543980/matchobjects?file_name=12345' \
--user apiuser:password123 \
--header "Accept: application/json"

Get a list of objects that contain the reference number 67890 in the folder and/or file name.

curl --request GET 'https://er-master:8339/v1/targets/13449404194559543980/matchobjects?file_name=67890' \
--user apiuser:password123 \
--header "Accept: application/json"

Expected Response

List of objects that contain the reference number 12345 in the folder and/or file name.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": "8",
    "path": "D:\\Folder-With-Reference-Numbers\\12345\\test-12345.txt",
    "owner": "EXAMPLE.COM\\userA"
  },
  {
    "id": "9",
    "path": "D:\\Folder-With-Reference-Numbers\\12345\\test-13579.txt",
    "owner": "EXAMPLE.COM\\userA"
  },
  {
    "id": "10",
    "path": "D:\\Folder-With-Reference-Numbers\\12345\\test-67890.txt",
    "owner": "EXAMPLE.COM\\userA"
  },
  {
    "id": "11",
    "path": "D:\\Folder-With-Reference-Numbers\\13579\\test-12345.txt",
    "owner": "EXAMPLE.COM\\userA"
  },
  {
    "id": "13",
    "path": "D:\\Folder-With-Reference-Numbers\\67890\\test-12345.txt",
    "owner": "EXAMPLE.COM\\userA"
  }
]

List of objects that contain the reference number 67890 in the folder and/or file name.

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: xxx
[
  {
    "id": "10",
    "path": "D:\\Folder-With-Reference-Numbers\\12345\\test-67890.txt",
    "owner": "EXAMPLE.COM\\userA"
  },
  {
    "id": "12",
    "path": "D:\\Folder-With-Reference-Numbers\\13579\\test-67890.txt",
    "owner": "EXAMPLE.COM\\userA"
  },
  {
    "id": "13",
    "path": "D:\\Folder-With-Reference-Numbers\\67890\\test-12345.txt",
    "owner": "EXAMPLE.COM\\userA"
  },
  {
    "id": "14",
    "path": "D:\\Folder-With-Reference-Numbers\\67890\\test-13579.txt",
    "owner": "EXAMPLE.COM\\userA"
  },
  {
    "id": "15",
    "path": "D:\\Folder-With-Reference-Numbers\\67890\\test-67890.txt",
    "owner": "EXAMPLE.COM\\userA"
  }
]

Get a unique list of match object IDs (id) (and the corresponding path value) from the output of both API requests. These IDs will be required when remediating the match objects.

For this example, the list of unique match object ids and the corresponding paths are:

Step 4 - Remediate Files with Matches

Remediate the match objects containing 12345 or 67890 in the folder and/or file name, based on the output in Step 3, where:

• target_id is 13449404194559543980 (see Defaults and Assumptions).
• location_id is 8987302884414283716 (see Defaults and Assumptions).
• action is delete.
• path and object_ids are the path and id values for each match object from Step 3.
• sign_off is user signing off on the remediation action.

Sample Request

curl --request POST 'https://er-master:8339/v1/targets/13449404194559543980/locations/8987302884414283716/remediation/delete' \
--user apiuser:password123 \
--header "Content-Type: application/json" \
--data-raw '{
  "path": "D:\\Folder-With-Reference-Numbers\\12345\\test-12345.txt",
  "sign_off": "userA",
  "reason": "Files to be deleted permanently.",
  "object_ids": [
    "8"
  ]
}'

Expected Response

HTTP/1.1 202 Accepted
Content-Type: application/json
Content-Length: xxx
{
  "path": "D:\\Folder-With-Reference-Numbers\\12345\\test-12345.txt",
  "job_id": 1676865285
}  

The Delete Permanently remediation action deletes the selected match object and leaves a tombstone text file in its place. Please see Remediation - Act Directly on Selected Location for more information.

The deleted file will no longer be picked up as a match object upon rescans of the same Target and Location.