Policies

Policies Device Control policies are described by the following groups of settings:

1. Description & Grouping
   • Device Groups
   • Computer Groups
   • Device Friendly Names
   • Custom File Types
   • Device Identities
2. Options
   • Global Machine Options
   • Specific Machine Options
3. Policies
   • Permanent Access
     • By Device Class / Model / Instance
     • By Encrypted Volume
     • By Optical Disk
   • Access controlled by Connectivity (Online/Offline)
   • Scheduled Access
   • Temporary Access
   • Copy Limit
   • Shadowing
   • Custom Message

The API supports two mechanism to deliver these policies to the endpoint:

1. JSON Policies
2. Device Control legacy Binary Policies (also know as Policies.dat).

Note that the legacy binary format approach is supported only on a case-by-case basis and is not recommended. Please contact support for more information on this option.

Both formats can be used to provide policies for specific machines, then it is the choice of the integrator either to deploy the same policy to multiple endpoints (let them do the filtering of policies not applying) or deploy a filtered policy for each endpoint. This decision is coupled with the decision to generate and sign the payload(s).

JSON Policies

The following element can be set using a numerical identifier or a text identifier:

• Device class (tag: "class")
• Machine Option (tag: "option")
• File Types (tag: "filetypes") The text identifier are the one defined in annexes. Examples of JSON policies can see found in JsonPolicyExamples.h.

Configuration

This is the Description & Grouping section noted above. It contain header information such as the generation timestamp, a GUID, and presets. The structure of the document is:

{
    "configuration": {
        "source": "{sourceToken}",
        "version": "1",
        "content": "1",
        "timestamp": "2015-07-07T14:26:59.999Z",
        "preset": "audit",
        "devices": {
            "identities": {
                "default": true
            }
        },
        "files": {
            "customtypes": [],
            "trusted": []
        },
        "computers": {
            "groups": []
        }
    },
    "options": [],
    "policies": []
}

Device - Identities

The device identity section is a section of the policy that in general should be unused by integrators. It is the mechanism by which devices are classified into their functional groups.

It is recommended to keep a simple section here with just the default attribute set to true (as in the example above); any modification to this section impacts how the driver categorizes devices and can lead to unwanted behaviors. Customization of this section should be given by or agreed with Device Control Support. Full attribute description is not provided.

Device - Groups

"groups": [
    {
        "id": "1234",
        "name": "Group 1",
        "class": "1",
        "types": [
            {
                "class": "1",
                "name": "a name",
                "model": "IDE\\CdRomNECVMWar_VMware_IDE_CDR10_______________1.00___"
            },
            {
                "class": "3",
                "name": "another name",
                "model": "SCSI\\DiskSamsung_SSD_840_PRO_SeriDXM0",
                "instance": "4&2d8daa90&0&00000"
            }
        ]
    }
]

Device - Names

Provide a "friendly name" for a device.

"names":[
    {
        "name": "VMWare Virtual CD",
        "class": "1",
        "models": [ "IDE\\CdRomNECVMWar_VMware_IDE_CDR10*" ]
    }
]

Files - Custom Types

Policies can include extra definitions for custom file-types, to be used in the file-type filtering capabilities of the agent.

The example of this object is:

"files": {
    "customtypes": [
        {
            "name": "CATIA V5",
            "id": "0x000F0100",
            "steps": [
                {
                    "action": "CheckBlock",
                    "offset": "0",
                    "res": "begin",
                    "value": "0x56355f4346563200"
                },
                {
                    "action": "Variable",
                    "offset": "8",
                    "res": "begin",
                    "len": "4",
                    "endian": "little",
                    "name": "@off1"
                },
                {
                    "action": "Variable",
                    "offset": "12",
                    "res": "begin",
                    "len": "4",
                    "endian": "little",
                    "name": "@off2"
                },
                {
                    "action": "CheckBlock",
                    "offset": "16",
                    "res": "begin",
                    "value": "0xFFFFFFFFFFFFFFFF"
                },
                {
                    "action": "CheckBlock",
                    "offset": "@off1",
                    "res": "begin",
                    "value": "0x43415449415f56352043423030303100"
                },
                {
                    "action": "Move",
                    "offset": "@off1",
                    "res": "begin"
                },
                {
                    "action": "Move",
                    "offset": "@off2",
                    "res": "current"
                },
                {
                    "action": "CheckEOF"
                }
            ]
        }
    ]
 }

CustomFileType node expects these attributes:

1. Id, mandatory, in hexadecimal format, must be in the 0x000F0000 – 0x000FFFFF range. This is selected by the integrator.
2. Name, mandatory, string which must be unique among the custom file types definitions.
3. Ext, optional, this provides the regular extensions used for this type, this is just an informative field, not used by the detection.

Each CustomFileType node has a sequenced child list (0-n) of these nodes:

CheckBlock node is used to check for a specific byte sequence at a location or in a range, this node expects these attributes:

1. Offset, mandatory, a decimal or a variable, this will provide indication for the seek operation. This is tight to the next attribute res.
2. Res, optional, string with defaulted begin; specifies how the seek operation is performed, values are: begin, current or end.
3. Range, optional, a decimal or a variable defaulted to 0; specifies the range starting at the offset of where to look at the sequence.
4. Value, mandatory, binary in hexadecimal format; represents the binary sequence, which is to be located in (offset, range + length(value)).

Variable node is used to read a variable from the input. This can then be used by the following actions in the sequence, this node expects these attributes:

1. Offset, mandatory, a decimal or a variable, this will provide indication for the seek operation. This is tight to the next attribute res.
2. Res, optional, string with defaulted begin; specifies how the seek operation is performed, values are: begin, current or end.
3. Len, mandatory, integer value, valid values are 1, 2, 4, 8; represents the length in bytes of the variable to be read.
4. Endian, optional, specifies if the variable is to be read in little or big-endian.
5. Name, mandatory, variable name, starts with @ by convention (no enforcement).

Move node is used to set the current position in the input stream; this nodes expects the attributes:

1. Offset, mandatory, a decimal or a variable, this will provide indication for the seek operation. This is tight to the next attribute res.
2. Res, optional, string with defaulted begin; specifies how the seek operation is performed, values are: begin, current or end.

CheckEOF node is used to check that the current position in the input stream is actually at the end of the file; this node expects no attributes.

Offset/Range can either use hard-coded values or variables:

1. Decimals are composed by 1-n digit(s) and can start with '–'
2. Variable name must start with @ or a letter

Example For CATIA v5

This file format is a Dassault Systemes format. Based on an analysis of 3 files, the following properties were found and were chosen to be used for file identification:

1. V5_CFV2 is to be found at start
2. A couple of 32 bits integer offset follows (let’s call then @off1 and @off2)
3. An FF block of 8 bytes follows
4. At @off1, CATIA_V5 CB0001 is to be found
5. The size of the file is @off1 + @off2

These kinds of properties can usually be reverse engineered using a HEX editor to examine the file. The complexity of the rule will be a function of the file format itself.

Example for Matroska (.mkv)

A Matroska video file usually uses a .mkv extension, and is an EBML document. The RFC specs are also available for checking. Our checks in this example are:

1. This is an EBML document -> it starts with 4 specific bytes [1A][45][DF][A3]
2. The EBML document type is "matroska". The doc type is tagged with [42][82] and may be 0 padded. So our search is for 0x4282886d6174726f736b61

This leads to a Custom File Type Definition:

{
    "name": "Matroska",
    "id": "0x000F0200",
    "ext": ".mkv",
    "steps": [
        {
            "action": "CheckBlock",
            "offset": "0",
            "res": "begin",
            "value": "0x1A45DFA3"
        },
        {
            "action": "CheckBlock",
            "offset": "0",
            "range": "32",
            "res": "begin",
            "value": "0x4282886d6174726f736b61"
        }
    ]
}

Files - Trusted Applications

The structure of this object is composed by trusted applications identified by sha256. SHA1 is not supported, so ensure that option 86 is used to set the hash mode correctly (see below). Scopes and rights restrictions are not used yet. A trusted application can bypass the hardening and this is intended for integration. For example, another service is trusted and consumes the logs and shadow files through the API while hardening is enabled.

{
    "configuration": {
        "source": "{sourceToken}",
        "version": "1",
        "content": "12",
        "timestamp": "2016-11-11T14:26:59.999Z",
        "devices": {
            "identities": {
                "default": true
            }
        },
        "files": {
            "trusted": [
                {
                    // Add a trusted application
                    // This example is for a version of cmd.exe
                    "sha256": "17F746D82695FA9B35493B41859D39D786D32B23A9D2E00F4011DEC7A02402AE"
                }
            ]
        }
    },
    "options": [
        {
            "id": "101",
            "name": "optionset1",
            "what": [
                {
                    // turn on hardening
                    // Prevents access to protected areas like the data file directory
                    "option": "58",
                    "value": "1" 
                },
                {
                    "option": "86",
                    "value": "2" // Use SHA-256
                }
            ]
        }
    ],
    // Give all users RW access to everything
    "policies": [
        {
            "id": "1200",
            "name": "RW_ALL",
            "who": {
                "sids": [
                    "S-1-1-0"
                ]
            },
            "devices": {
                "types": [
                    {
                        "class": "Default Settings"
                    }
                ]
            },
            "how": {
                "priority": "Low"
            },
            "what": {
                "access": {
                    "granted": [
                        "Read",
                        "Write"
                    ]
                }
            },
            "when": {
                "permanent": "always"
            }
        }
    ]
}

The effect of the policy above is that all users by default can access everything. However, hardening is enabled, meaning that the user cannot access parts of the system related to the agent install. That, however, does not apply to the trusted application we have specified by its SHA-256 hash code. So in this example, a user cannot delete files from the Data File Directory unless they use the command line.

Computers - Groups

The structure of this object is composed by groups and their computer members identified by various means (IP v4, NetBios name, and so on: see the full list in the table under Where).

"groups": [
    {
        "id": "42",
        "name": "Comp Group 1",
        "members": {
            "fqn": [ "hubertb.engdev.org" ],
            "netbios": [  "hubertb" ],
            "ipv4": [ "192.168.1.42" ],
            "ipv4range": [ "192.168.1.100-192.168.1.199" ],
            "ou": [ "CN=Computers,DC=engdev,DC=org" ]
        }
    }
]

This object is needed only if the policy is generated for multiple endpoints and filtering is performed by Device Control. In some other scenarios where the integrator generates policies specific to an endpoint, endpoint filtering is then performed up front and not described in the policy payload.

Options

The structure of this object’s array is defined as below. An option object contains targets and a collection of option key-value pairs.

Global machine options are identified by the lack of where attributes. As with the computer groups, the need of options tied to specific computers is defined by the policy generation strategy.

A list of options can be referenced on the Machine Options page.

"options": [
    {
        // NON-GLOBAL OPTION GROUP
        "id": "101",
        "name": "Extra secure plus audit",
        "where": {
            // Same options as computer groups can be used here
            "ou": [
                "CN=Computers,DC=engdev,DC=heat,DC=org"
            ],
            "group": [ "42" ]
        },
        "what": [
            {
                // password min length
                "option": "68",
                "value": "16"
            },
            {
                // SysLog server Address
                "option": "67",
                "value": "my.syslog.server"
            }
        ]
    },
    {
        // GLOBAL OPTION GROUP
        "id": "102",
        "name": "Signing Key Option",
        "what": [
            {
                "option": "91",
                "value": "454353312000000013EFAE5A8F405293D836DAE99A84EEE86B6A0021E984235369D283C5115781F44C5A5D9A990607CB95E835E359B2F13B36CCF55BAE2C62CA34545E89288AD367"
            }
        ]
    }
]

Policies

"policies": [
    {
        "id": "1234",
        "name": "An Empty Policy!",
        "who": {},
        "where": {},
        "devices": {},
        "how": {},
        "what": {},
        "when": {}
    }
]

These are the sets of Device Control settings to apply to clients.

Who

"who": {
    "sids": [
        "S-1-5-32-544",
        "S-1-5-32-547"
    ], 
    "accounts": [
        "dave",
        "jane"
    ]
}

Restrict the option to a list of accounts (user / group, well known / local / domain).

When SID is known, it should be the preferred way to pass the identity. However, in some cases, you may have many machines with the same local account name and different SIDs, so it can rely on resolution on the agent (restricted to local accounts).

Where

As with the Options settings, identifies the computers to which to apply the policy.

Devices

"devices": {
    "types": [
        {
            "class": "2"
        },
        {
            "class": "1",
            "name": "a name",
            "model": "IDE\\CdROIINECWar_\nMare_IDE_CDR10 1 . 00—"
        },
        {
            "class": "3",
            "name": "another name",
            "model": "SCSI\\DiskSamsung_SSD_840_PRO_SeriDXMO",
            "instance": "4&2080AA90&0&00000"
        }
    ],
    "groups": [
        "1234",
        "5678"
    ],
    "media": [
        {
            "class": "1",
            "name": "and yet another name",
            "shal": "0123456789012345678901234567890123456789"
        },
        {
            "class": "3",
            "name": "and yet another name one more time",
            "type": "1",
            "uniqueid": "{01234567-0123-0123-0123-012345678901}",
            "keys": [
                {
                    "thumbprint": "0123456789012345678901234567890123456789",
                    "type": "1",
                    "cipher": "01234567890123456789012345678901234567890123456789012345678901234"
                },
                {
                    "thumbprint": "1234567890123456789012345678901234567890",
                    "type": "1",
                    "cipher": "01234567890123456789012345678901234567890123456789012345678901234"
                }
            ]
        }
    ]
}

Describes the device targets. It can be a device class (including all devices), a device model, a device group (contains device models and instances), a specific instance of a device, an optical disk instance, or an encrypted volume.

How

"how": {
    "priority": "50",
    "match": "OR"
}

The how node expects the attributes:

1. priority, mandatory: This is a 32-bit signed integer designating priority when resolving conflicting policies. Higher priority policies override lower ones.
2. match, optional, Defines logic between the Machine and User filters when both are provided:
   • AND (default): machine and user filters must match for the policy to apply
   • OR: machine or user filters must match for the policy to apply

What

Access

"access": {
    "bus": [
        "All",
        "IDE",
        "BT",
        "USB",
        "SCSI",
        "IRDA",
        "FM",
        "PCMCIA"
    ],
    "disk": [
        "All",
        "Fixed",
        "Removable"
    ],
    "encryption": [
        "All",
        "Encrypted",
        "Unencrypted"
    ],
    "granted": [
        "None",
        "Read",
        "write",
        "Encrypt",
        "Decrypt",
        "Import",
        "Export(File)",
        "Export(Medium)"
    ]
}

The access node expects the attributes:

1. Bus, optional: Restricts the policy to a specific bus. If All or if not set, the policy has no bus filtering.
2. Disk, optional: Restricts the policy to a specific removable type. If All or if not set, the policy has no removable type filtering.
3. Encryption, optional: Restricts the policy to a specific encryption state. If All or if not set, the policy has no encryption state filtering.
4. Granted, mandatory: Lists the various actions allowed (or denied) by the policy.

Audit

"audit": {
    "shadow": {
        "read": "Filename",
        "write": "Content"
    }
}

The audit/shadow node expects the attributes:

1. Read, optional: Sets a shadowing value for read-granted operations.
2. Write, optional: Sets a shadowing value for write-granted operations.

The options for shadowing are:

1. none: No shadow information is captured, only the event itself is logged.
2. filename: The name of the file is captured along with the event.
3. content: The content of the file is captured along with the event. Administrators will then have access to the files.

Content

 "content": {
    "quota": "42",
    "filters": {
        "settings": "0",
        "filetypes": [
            "00020000",  // Abobe Acrobat
            "R00030000", // Archives on Read Operations
            "W00040000"  // Executables on Write Operations
        ]
    },
    "dlptypes": {
        "settings": "0",
        "filetypes": [
            "00020000",  // Abobe Acrobat
            "000A0100"   // Microsoft Word (*.DOCX)
        ]
    }
}

This is an optional node, which is used to specify options for content-related checks, such as File-Type Filtering and Data Loss Prevention. This applies the policy only to the specified type of file. For example, if the above example were used with a access for USB Removable devices and permission for read and write, then this would allow read/write for pdf files, read for zip files and write for .exe files.

The Content node expects the attributes:

1. Quota: Sets the copy limit in MB. 0 means the copy limit is disabled. The maximum value is 134217727, which is far above current media capacities.
2. filters: Settings for File-Type Filtering.
   • Settings: Configures the file filtering engine (unused).
   • Filetypes: List of hexadecimal values defining the file type or the custom file types. See File Types.
     • Preceded by R if restricted to read operation (has no meaning if used within dlptypes)
     • Preceded by W if restricted to write operation (has no meaning if used within dlptypes)
3. dlptypes: Settings for the Data Loss Prevention feature.
   • Settings: Configure the DLP engine (unused).
   • Filetypes: List of hexadecimal values defining the filetype or the custom file types. See File Types. The R/W options from the File-Type Filtering settings do not apply here.

Messages

"messages": {
    "notify" :  true,
    "denied": "Acces is restricted, please call ..."
}

Configures a message to be displayed on access denial due to this policy.

1. Notify: Specifies if the notification is enabled or not. A High Priority policy can be made to disable the notification (for example for specific users).
2. Denied: Message displayed to the user when read or write operations are denied by Device Control.

When

Configures when the policy is applied in relation to network connectivity, either by a schedule or over a time range.

Permanent

"when":{ 
    "permanent": "Always"
}

This is a 'permanent' non-temporally affected policy. The possible values for this are:

1. Always: The policy is applied to the client at all times.
2. Online: The policy is applied only when the client is online (connected to the corporate LAN).
3. Offline: The policy is applied only when the client is offline (not connected to the corporate LAN).

Schedule

"when":{ 
    "schedule": {
        "start": "08:00:00",
        "end": "17:00:00",
        "rrule": "BYDAY=SU,SA"
    }
}

This rule applies a recurring daily schedule during which the policy is applied. The properties for the rule are:

1. Start: Time of the day from which the policy starts to apply.
2. End: Time of the day at which the policy stops applying.
3. Rrule: Recurrence rule specifying the list of weekdays for which the policy applies. MO, TU, WE, TH, FR, SA and SU are valid.

Temporary

"when":{ 
    "temporary": {
        "start": "2016-01-01T08:00:00Z",
        "end": "2016-08-01T17:00:00Z",
    }
}

This is a policy applied within a continuous date-time range. The start and end properties delineate the range, and are ISO 8601 formatted UTC datetime strings.