Skip to content

Data Format

Jump to bottom
Roger Zander edited this page Dec 22, 2017 · 3 revisions

Configuration

In the current example, we will use jaindb as an Inventory database. If your container is runnig, you should find an "inventory.ps1" File in your published directory (d:\jaindb in the example). This file is a PowerShell example which collects most important data of a computer and uploads the data to jaindb.

The next view chapters give you some basics on how to upload custom data.

Object ID

To identify the Computer, a unique identifier is required. Inventory.ps1 generates that id based on a hash value of the UUID, Domain and Computer name. If any of these three values changes, a new ID is generated.

function GetMyID {
    $uuid = getinv -Name "Computer" -WMIClass "win32_ComputerSystemProduct" -Properties @("#UUID")
    $comp = getinv -Name "Computer" -WMIClass "win32_ComputerSystem" -Properties @("Domain", "#Name") -AppendProperties $uuid 
    return GetHash($comp | ConvertTo-Json -Compress)
}

Key-Names

Every Object in jaindb can have one or many Key-Names which are used to find an Object by using common names or values. Key-Names are Root-Properties on the Object starting with a '#' (hash sign).

The inventory.ps1 example generates Key-Names for the following values:

  • #id
  • #UUID
  • #Name
  • #SerialNumber
  • #MAC (all IP-Enabled MAC addresses)
function SetID {
    Param(
        [ref]
        $AppendObject )

    if ($AppendObject.Value -ne $null) {
        $AppendObject.Value | Add-Member -MemberType NoteProperty -Name "#id" -Value (GetMyID) -ea SilentlyContinue
        $AppendObject.Value | Add-Member -MemberType NoteProperty -Name "#UUID" -Value (getinv -Name "Computer" -WMIClass "win32_ComputerSystemProduct" -Properties @("#UUID"))."#UUID" -ea SilentlyContinue
        $AppendObject.Value | Add-Member -MemberType NoteProperty -Name "#Name" -Value (getinv -Name "Computer" -WMIClass "win32_ComputerSystem" -Properties @("Name"))."Name" -ea SilentlyContinue
        $AppendObject.Value | Add-Member -MemberType NoteProperty -Name "#SerialNumber" -Value (getinv -Name "Computer" -WMIClass "win32_SystemEnclosure" -Properties @("SerialNumber"))."SerialNumber" -ea SilentlyContinue
        $AppendObject.Value | Add-Member -MemberType NoteProperty -Name "#MAC" -Value (get-wmiobject -class "Win32_NetworkAdapterConfiguration" | Where {($_.IpEnabled -Match "True")}).MACAddress.Replace(':', '-')
        return $null
    }   
}

Dynamic data

jaindb will keep the history of all uploaded objects. To benefit from data deduplication, it's recommended to tag dynamic attributes with a '#' prefix. Dynamic data are all attributes which are unique on a device. Example:

BuildNumber        : 16299
BootDevice         : \Device\HarddiskVolume3
Caption            : Microsoft Windows 10 Enterprise
CodeSet            : 1252
CountryCode        : 41
@CurrentTimeZone   : 60
EncryptionLevel    : 256
Locale             : 0807
Manufacturer       : Microsoft Corporation
MUILanguages       : {en-US}
OperatingSystemSKU : 4
OSArchitecture     : 64-bit
OSLanguage         : 1033
SystemDrive        : C:
Version            : 10.0.16299
#InstallDate       : 22.10.2017 13:24:00
@LastBootUpTime    : 13.12.2017 19:54:16

As you can see, 'InstallDate' is tagged as dynamic data as every computer may have a different installdate. Additionally, we can tag attributes with the sign '@' from being excluded from the data archive and blockchain. This is helpful for attributes that are not relevant for history or change frequently. @ Attributes are only stored in cache and will be deleted if they are not refreshed within 60 Days.

Note: Choose the required data attributes with care and tag dynamic data and short time date as it has a huge impact on the database size.

Normalize values

Storing "free Disk space" in bytes is not very useful as with every check that value will change. Inventory.ps1 will 'Normalize' or 'Round' integer values that are not very important. Example:

  • free Disk Space
  • Disk size
  • total Memory size

as in these cases it's fine if we know the rounded size.

Note: Normalizing data will help to deduplicate data where the exact value is not important.

Get Inventory Data

Every inventory class like OS, BIOS, CPU etc. must be a child Object of the Root-Object: The following part of Inventory.ps1 does generate the Root-Object: $object = New-Object PSObject.

To simplify attribute tagging, inventory.ps1 contains the function "getinv" to collect and tag attributes.
Example:
getinv -Name "BIOS" -WMIClass "win32_BIOS" -Properties @("Name", "Manufacturer", "Version", "#SerialNumber") -AppendObject ([ref]$object) In this case, the class "BIOS" will be added (by using -AppendObject) to the Root-Object.

Convert to JSON and upload

Jaindb can only handle JSON Objects. One of the last steps in invetory.ps1 will convert the $object into a JSON string:
$con = $object | ConvertTo-Json -Compress

The JSON-String is now ready to get upload by using the jaindb Rest-API:
Invoke-RestMethod -Uri "%LocalURL%/upload/$($id)" -Method Post -Body $con -ContentType "application/json; charset=utf-8"

"%LocalURL%" will be automatically replaced with the Docker-Variable if you are using the 'getps' method of the REST-API

Clone this wiki locally