Skip to main content

Programmatically Store Client Device Details (macOS) to JSON with FileWave REST API

The Client Info> Device Details of a particular client contain a wealth of information that may be useful to repurpose in other systems (Help Desks, centralized inventory systems, etc). Using the FileWave API, you can extract the deviceID of each client and write that information to a file locally on the client, then use the API to extract the device details to a file saved locally on the machine. 

Because it can be a topic that can trip someone up it is important to note that API calls are normally done on TCP 443. You may see references to 20445 in some documentation, but that is the RESTful API (v1 API) and it is on TCP 20445 however you can make a small change in the URL for the API endpoint and use TCP 443 for all calls by prepending /api/ on to the /inv/api/ URLs to make it /api/inv/api/ in the URLs.

Step-by-step guide

  1. Create a new desktop fileset (Empty).

  2. Create a new script as a "Requirements Script" with the following contents that will write the FileWave deviceID to file:

    #!/bin/sh
    
    # Writes FileWave device_id to a file.
    mkdir /Library/Scripts/FileWave
    touch /Library/Scripts/FileWave/deviceid
    
    echo $1 > /Library/Scripts/FileWave/deviceid

    Set "%device_id%" as the LaunchArgument for this script, executed as a Requirements Script.

  3. Create a new script as a "Verifications Script" with the following contents that will use ${device_id} as a parameter in a curl statement to access the API:

    #!/bin/sh
    
    # This script will read the FileWave device_id from a flat file (/Library/Scripts/FileWave/deviceid).
    # This file is created by a FileWave requirements script with %device_id% as a LaunchArgument.
    
    # Read device_id from file.
    file="/Library/Scripts/FileWave/deviceid"
    read -d $'\x04' device_id < "$file"
    #echo ${device_id}
    
    # Check for a non-null value.
    if [ "$device_id" == "" ]
    then
    echo "No Device ID saved locally, bailing now."
    exit 0
    
    else    # Write Device Details (based on the device_id) to file.
    rm /Library/Scripts/FileWave/device_details.json
    curl -s -k -H "Authorization: <insert_base64_authkey>" https://<insert_server>:20445/inv/api/v1/client/details/${device_id}/DesktopClient | python -m json.tool >> /Library/Scripts/FileWave/device_details.json
    
    fi
    exit 0

    This script will take the deviceID and call the FileWave API to get the individual client details. The client details will be inserted into a new file "device_details.json". 

    Once you have the JSON file, you can parse this at any time and extract any element from the file and redirect to another service, such as a Slack app.

Here is a sample of the device_details.json:

{
    "CustomFields__ldap_username": {
        "status": 0,
        "type": "string",
        "updateTime": "2018-06-21T19:37:23.585851Z",
        "value": "mdm mdm"
    },
    "CustomFields__local_ip_address": {
        "status": 0,
        "type": "string",
        "updateTime": "2018-06-21T19:49:51Z",
        "value": "10.20.30.29"
    },
    "CustomFields__malwarebytes_installed": {
        "status": 0,
        "type": "bool",
        "updateTime": "2018-06-21T19:49:51Z",
        "value": false
    },
    "CustomFields__po_number": {
        "status": 0,
        "type": "string",
        "updateTime": "2018-06-21T19:49:51Z",
        "value": "54654561"
    },
    "CustomFields__property_tag": {
		"status": 0,
        "updateTime": "2018-06-21T19:49:51Z",
        "type": "string",
        "value": "Device Owned by FileWave"
    },
    "CustomFields__purchase_date": {
        "updateTime": null,
        "value": null
    },
    "CustomFields__school_name": {
       	"status": 0,
        "type": "string",
        "updateTime": "2018-06-21T19:49:51Z",
        "value": "Landing Trail Elementary"
    },
    "CustomFields__site_description": {
        "updateTime": null,
        "value": null
    },
    "CustomFields__textedit_version": {
        "status": 0,
        "type": "string",
        "updateTime": "2018-06-21T19:49:51Z",
        "value": "1.13"
    },
    "CustomFields__user_role": {
        "updateTime": null,
        "value": null
    },
    "archived": null,
    "auth_username": "mdm",
    "building": null,
    "cpu_count": 2,
    "cpu_speed": 2759000000,
    "cpu_type": "Intel(R) Core(TM) i5-3470S CPU @ 2.90GHz",
    "current_ip_address": "10.20.30.29",
    "deleted_from_admin": false,
    "department": null,
    "device_id": "f96b8c66c50b358889ba2fbf2dc53bc21036406a",
    "device_manufacturer": "VMware, Inc.",
    "device_name": "FUSION-VM1-10.12",
    "device_product_name": "VMware7,1",
    "enroll_date": "2018-06-17T17:11:08.709785Z",
    "enrollment_state": 2,
    "filewave_client_locked": false,
    "filewave_client_name": "FUSION-VM1-10.13",
    "filewave_client_version": "12.8.1",
    "filewave_id": 219,
    "filewave_model_number": 617,
    "free_disk_space": 56772587520,
    "is_system_integrity_protection_enabled": true,
    "is_tracking_enabled": false,
    "last_check_in": "2018-06-21T19:54:31.615710Z",
    "last_enterprise_app_validation_date": null,
    "last_ldap_username": null,
    "last_logged_in_username": "dhadmin",
    "last_state_change_date": "2018-06-21T19:50:09.339609Z",
    "location": null,
    "management_mode": 0,
    "monitor_id": null,
    "operating_system__build": "17B48",
    "operating_system__edition": "Desktop",
    "operating_system__name": "macOS 10.13 High Sierra",
    "operating_system__type": "OSX",
    "operating_system__version": "10.13.1",
    "operating_system__version_major": 10,
    "operating_system__version_minor": 13,
    "operating_system__version_patch": 1,
    "ram_size": 2147483648,
    "rom_bios_version": "VMW71.00V.0.B64.1706210604",
    "security__enrolled_via_dep": null,
    "security__fde_enabled": false,
    "security__firmware_password_change_pending": false,
    "security__firmware_password_exists": false,
    "security__firmware_password_rom_enabled": true,
    "security__hardware_encryption_caps": null,
    "security__passcode_is_compliant": null,
    "security__passcode_is_compliant_with_profiles": null,
    "security__passcode_lock_grace_period": null,
    "security__passcode_lock_grace_period_enforced": null,
    "security__passcode_present": null,
    "security__system_integrity_protection_enabled": true,
    "security__user_approved_enrollment": null,
    "serial_number": "VMx4NvUkh/Co",
    "state": 0,
    "total_disk_space": 85689589760,
    "unenrolled": false
}