The Windows Agent provides a custom YARA module, CBEP. The module provides attributes which contain useful information about files that are being scanned. You can use the examples of the attributes that are provided here in your YARA rules, and combine them to form complex rules, as required.
You can use attributes that relate to files, processes, signatures, volumes, and devices in your YARA rules.
- CBEP Schema Version Attribute
- File-related Attributes
- Process-related Attributes
- General Signature-related Attributes
- Signing and Timestamping Signature-related Attributes
- Volume-related Attributes
- Device-related Attributes
- Hashes are calculated in YARA using lower case.
- == and contains string comparisons in YARA are case-sensitive.
CBEP Schema Version Attribute
| Attribute | Namespace Availability | Description | Type | Example and Comments |
|---|---|---|---|---|
| schema_version | Both | The CBEP schema version. | Integer | cbep.schema_version >= 1. The schema version is incremented when YARA attributes are added or removed. The initial value is 1. |
File-related Attributes
| Attribute | Namespace Availability | Description | Type | Example and Comments |
|---|---|---|---|---|
| filename | Both | The full path to the file. | String | cbep.analysis.file.filename contains "cmd.exe" |
| sha256 | Classify | The SHA-256 hash of the file contents. | String | cbep.analysis.file.sha256 == "6f88fb88ffb0f1d5465c2826e5b4f523598b1b8378377c8378ffebc171bad18b" |
| sha1 | Classify | The SHA-1 hash of the file contents. | String | cbep.analysis.file.sha1 == "7c3d7281e1151fe4127923f4b4c3cd36438e1a12" |
| md5 | Classify | The MD5 hash of the file contents. | String | cbep.analysis.file.md5 == "f5ae03de0ad60f5b17b82f2cd68402fe" |
| publisher | Classify | The publisher of the file. This is available only if the file is signed. | String | cbep.analysis.file.publisher contains "Microsoft" |
| in_td | Both | The file is in a trusted directory. | Integer | cbep.in_td == 1 The possible values are 0 (not in a trusted directory) or 1 (in a trusted directory). |
| type | Both | The reason why the file is being analyzed. | String | cbep.analysis.type contains "Kernel" The possible values are: "Kernel", "Initialization", "IntegrityCheck", "Trickle Complete", "Level2 Complete", "MSICallback", "TrustedDirCheck", "NotifierResponse", "LoadedImageCheck", "ProcessStart", "AnalysisTypeAutoStartFile", "InstallDirCheck", "DatabaseCorrections", "DownloadedFile", "USNRecord", "OSUpgradeComplete", "UnitTest", or "ForcedDeletion". |
| operation | Both | If a file analysis is triggered from the kernel, the attribute contains the operation involved. | String | cbep.analysis.operation contains "Write" The possible values are: "Don't Care", "Open", "Open/Execute", "Open/Write", "Read", "Write", "Delayed Write", "Delete", "Execute", "Rename", "Cleanup", "Create", "Script Execute", "Process Create", "Process Terminate", "Image Load", "ScriptExecute+Delete", "Permissions Change", "Ownership Change", "LockFile", "Cleanup w/ delete pending", "MmapRead", "MmapWrite", "Image Enum", or "ChangeFileType". |
Process-related Attributes
The last process that modified a file is tracked, and this information can be used in YARA rules. Information about the ancestors of the writing process, such as parent and grandparent, is usually available, depending on when the file was written and whether it was tracked. Even if the parent process no longer exists, usually the chain can be reconstructed by using the cache.
process[0]refers to the writing process.process[1]is the parent of the writing process.process[2]is the grandparent of the writing process.Systemis the last process in the array, when it is possible to retrace the processes that far.
| Attribute | Namespace Availability | Description | Type | Example and Comments |
|---|---|---|---|---|
| user.name | Both | The account name under which the process is running. | String | cbep.analysis.process[0].user.name contains "al" |
| user.sid | Both | The account SID under which the process is running. | String | cbep.analysis.process[0].user.sid == "S-1-5-18" |
| file.filename | Both | The full path to the main process executable. | String | cbep.analysis.process[0].file.filename contains "explorer" |
| file.sha256 | Both | The SHA-256 hash of the process executable. | String | cbep.analysis.process[0].file.sha256 == "c3159f629b9e989ee354834aa5a6a9af146b8bd1c07204e6ed9e94c96f2509fb" |
| file.publisher | Both | The publisher of the process executable. This is only available for signed processes. | String | cbep.analysis.process[0].file.publisher contains "Microsoft" |
| cmdline | Both | The full command line of the process. | String | cbep.analysis.process[0].cmdline contains "first" |
| browser | Both | The process is a Web browser. | Integer | cbep.analysis.process[0].browser The possible values are 0 (not a Web browser) or 1 (a Web browser). |
| email_client | Both | The process is an email client. | Integer | cbep.analysis.process[0].email_client The possible values are 0 (not an email client) or 1 (an email client). |
| script_interpreter | Both | The process is a script interpreter. | Integer | cbep.analysis.process[0].script_interpreter The possible values are 0 (not a script interpreter) or 1 (a script interpreter). |
| trusted | Both | The process is promoted. Files written from a promoted process are automatically approved. | Integer | cbep.analysis.process[0].trusted The possible values are 0 (not promoted) or 1 (promoted). |
| never_trust | Both | The process can be promoted. Some processes, such as browser processes, should never be promoted. | Integer | cbep.analysis.process[0].never_trust The possible values are 0 (cannot be promoted) or 1 (can be promoted). |
| tags | Both | The classification tags for this process. | String | cbep.analysis.process[0].tags contains "nevertrust" |
| process_depth | Both | The number of processes in the process array. This may be less than the actual number of processes in the chain because it may not be possible to trace back to the System process. | Integer | cbep.analysis.process_depth == 1 |
| combined_state | Both | The overall approval state of the file. This is calculated from local, global, and publisher information. | String | cbep.analysis.process[0].file.combined_state contains “Locally” The possible values are: "Invalid", "Approved", "Unapproved (Persisted)", "Banned", "Locally Approved", "Banned by Name", "Banned by Name (Report Only)", "Locally Approved (Auto)", "Trusted", "Inactive", "File Exists", "Approved", "Trusted (Top Level)", "Banned by Hash (Report Only)", "Unapproved", or "Uninteresting". |
| Signing attributes | Both | Process attributes include signing information for the main executable, similar to what is provided for the file under scan. | cbep.analysis.process[1].file.signature.signature_error cbep.analysis.process[1].file.signature.codesigning_chain[0].cert[0].issuer For information, see General Signature-related Attributes and Signing and Timestamping Signature-related Attributes. |
General Signature-related Attributes
General signing attributes are available for both files and processes.
| Attribute | Description | Type | Example and Comments |
|---|---|---|---|
| signature_time | The signing time, expressed as a Unix Epoch time. | Integer | cbep.analysis.file.signature.signature_time == 1617926400 For reference, see https://www.epochconverter.com/. |
| signature_error | Errors found during signature validation, expressed as a bitmask. These values are CERT_TRUST_* error codes, as provided by Microsoft in the CERT_TRUST_STATUS structure. Caution is required as not all errors are treated as fatal by Carbon Black App Control. | Integer | cbep.analysis.file.signature.signa ture_error & ~0x01000041) != 0 For reference, see CERT_TRUST_STATUS structure. |
| detached | Indicates whether the signature is embedded in the file or catalog-signed and detached from the file. | Integer | cbep.analysis.file.signature.detached == 0 The possible values are 0 (embedded) or 1 (catalog-signed). If the file is not signed, detached will be 0. |
| meets_cb_requirements | The signature meets the configurable requirements for supported algorithms, public key size, certificate validity periods, timestamping, and so on. | Integer | cbep.analysis.file.signature.meets_cb_requirements The possible values are 0 (does not meet requirements) or 1 (meets requirements). |
Signing and Timestamping Signature-related Attributes
For signed files and processes, a single code-signing certificate chain and a single timestamping certificate chain are available for use in YARA rules. This is the case even if a file has multiple signers.
cbep.analysis.file.signature.codesigning_chain[0].cert[0] cbep.analysis.file.signature.timestamp_chain[0].cert[0]
cbep.analysis.file.signature.codesigning_chain[0].cert[1] cbep.analysis.file.signature.timestamp_chain[0].cert[1]
| Attribute | Description | Type | Example and Comments |
|---|---|---|---|
| serial | The serial number of a certificate. | String | cbep.analysis.file.signature.codesigning_chain[0].cert[0].serial == "0c1cd3eea47edda7a032573b014d0afd" cbep.analysis.file.signature.timestamp_chain[0].cert[0].serial == "0a7a4a889ec99942900663384d86979d" |
| issuer | The issuer of a certificate. This is the common name (CN) only. | String | cbep.analysis.file.signature.codesigning_chain[0].cert[0].issuer == "DigiCert SHA2 Assured" |
| publisher | The subject of a certificate. This is the common name (CN) only. | String | cbep.analysis.file.signature.codesigning_chain[0].cert[0].publisher contains "Microsoft" |
| sha1_thumbprint | The SHA-1 thumbprint hash of the certificate. | String | cbep.analysis.file.signature.codesigning_chain[0].cert[0].sha1_thumbprint == "1326b39c3d5d2ca012f66fb439026f7b59cb1974" |
| valid_from_time | The certificate validity start time, expressed as a Unix Epoch time. | Integer | cbep.analysis.file.signature.codesigning_chain[0].cert[0].valid_from_time == 1617926400 For reference, see https://www.epochconverter.com/. |
| valid_to_time | The certificate validity end time, expressed as a Unix Epoch time. | Integer | cbep.analysis.file.signature.timestamp_chain[0].cert[0].valid_to_time == 1994457599 For reference, see https://www.epochconverter.com/. |
| validation_error | Errors found during certificate validation. | Integer | cbep.analysis.file.signature.timestamp_chain[0].cert[0].validation_error & ~0x01000041) != 0 For more details, see signature_error in General Signature-related Attributes. |
Volume-related Attributes
Information is available about the volume on which a file resides. You can use the dascli devices command to see the information collected.
| Attribute | Description | Type | Examples and Comments |
|---|---|---|---|
| volume.guid | The GUID of the volume where the file resides. | String | cbep.analysis.volume.guid == "da156407-d07a-4f9b-a8ee-7c583c8ef8d1" |
| volume.system_volume | The file resides on the system volume. This is the volume that contains the system directory. | Integer | cbep.analysis.volume.system_volume == 1 The possible values are 0 (does not reside) or 1 (resides). |
| volume.harddisk | The file resides on a fixed hard disk. | Integer | cbep.analysis.volume.harddisk == 1 The possible values are 0 (does not reside) or 1 (resides). |
| volume.cdrom | The file resides on a CD-ROM. | Integer | cbep.analysis.volume.cdrom == 1 The possible values are 0 (does not reside) or 1 (resides). |
| volume.removable | The file resides on a removable volume. | Integer | cbep.analysis.volume.removable == 1 The possible values are 0 (does not reside) or 1 (resides). |
| volume.remote | Indicates whether the file resides remotely or locally. | Integer | cbep.analysis.volume.remote == 1 The possible values are 0 (locally) or 1 (remotely). |
Device-related Attributes
Information is available about the device on which a file resides. You can use the dascli devices command to see the information collected.
| Attribute | Description | Type | Examples and Comments |
|---|---|---|---|
| device.name | The friendly name of the device where the file resides, for example, "INTEL SS DSC2BF480A5 SCSI Disk Device". | String | cbep.analysis.device.name contains "VMware Virtual disk SCSI Disk Device" |
| device.manufacturer | The manufacturer of the device where the file resides, for example, "INTEL_SS". | String | cbep.analysis.device.manufacturer contains "VMWARE" |
| device.serial | The serial number of the device where the file resides. This is not the volume serial number. The length and format varies depending on the manufacturer. | String | cbep.analysis.device.serial == "5&1EC51BF7&0&000000" |
| device.model | The model of the device where the file resides, for example, "DSC2BF480A5". | String | cbep.analysis.device.model contains "VIRTUAL_DISK" |
