|
Schema update
|
|
Microsoft Graph Security API
|
We're introducing significant changes to our data model (aka schema) based on our partnerships
with security providers and feedback we received on the Public Preview schema to date, in
preparing for General Availability of the Microsoft Graph Security API.
Working with Microsoft and 3rd-party security products (aka 'providers') around the data they can
populate alert with, provided valuable input on additional properties they want to make available
in alerts from their respective products.
We reviewed and verified that properties we include in our schema are not proprietary and are
supported by more than one provider, enabling customers to run a single filtered queries across
multiple providers - before adding them to our schema, to ensure customers can maximize the
benefit they realize from their graph-enabled security products.
This post will focus on changes to the alert entity: describing new properties and any modifications
to existing properties, starting with the major changes, and continuing to other changes.
The online documentation already reflects these changes; please view complete schema details there.
Major changes:
- The networkConnection complex type now supports:
- URL-related properties (domains, URLs, registrar information, etc.)
- Network Address Translation (aka NAT) related properties (more details below)
- New registryKeyState complex type - metadata related to creating/modifying registry keys,
a common form of persistence in fileless attacks
- The registryKeyState captures the previous, and new, registry key properties to
enable understanding what changed
- cloudApplicationState replaces applicationState - supports alerts from Cloud Access Security
Broker (CASB) providers
- The comments property is now a collection of strings (previously a string) -
(breaking change for update alert)
Other changes:
- New properties
- Confidence - provider-generated confidence in the accuracy of the alert/detection
- UserState as two new properties:
- isVpn - indicates if the logon was done over a VPN (effects logon information:
logonId and logonIp)
- emailRole - indicates if the user account was email sender or recipient
(in email-related alerts)
- hostState.hostOs - the Operating system of the related host
- Changed properties
- fileHash (new complex type) - replaces dedicated properties for select
file hashes to support a broad variety of file hashes (Appears in alert.fileStates
and in alert.processes); properties:
- type - enumeration of file hash types (Sha1, Sha256, MD5, AuthenticodeHash256,
LsHash, CTPH)
- value - the file hash value
- cloudAppState (was applicationState) - new/changed properties
- destinationServiceName - the cloud application/service name (e.g. "Salesforce",
"Box", etc.)
- destinationServiceIp - the destination IP Address of the connection to cloud
application/service
- activityGroupName - previously a complex type, now the name of the activity group
(attacking entity);
- malwareState - now incorporates all relevant properties to the malicious file
- category - provider-generated category of the malware (e.g. ransomware, etc.)
- family - provider-generated family of the malware (e.g. wannacry; there may be
multiple variants of this malware, e.g. wannacry.A, etc.)
- wasRunning - moved into the complex type; indicates if the malware was executing
when detected, or at rest on disk (e.g. during static scan)
- vulnerabilityState - has a new property
- wasRunning - indicates if the vulnerability was detected at execution time, or at rest
on disk (e.g. during static scan)
Details of major changes
- networkConnection - new and changed properties:
- [New] applicationName - the name of the application managing the network connection
(e.g. Facebook, SMTP, etc.)
- [Modified] destinationUrl - previously named "uri"; reflect general alignment of
'destination/source' distinction for network communication property
- [New] direction - whether the network communication is inbound or outbound -
impacts the 'source' and 'destination' IP address or URL
- [New] status - whether the network communication was (only) attempted,
successful (completed), blocked, or failed
- [New] destinationDomain - the domain of the destination URL (enables filtering
for network connections to different URLs under the same domain)
- [New] localDnsName - the local DNS name resolution as it appears in the
host's local DNS cache (important in cases of hosts file tampering)
- [New] urlParameters - the segment of the URL after the URI portion (follows "?").
Segmenting the URL for ease of consumption
- [New] domainRegisteredDate - when the domain was registered (new domains
are often suspect)
- [New] natSourceAddress - the network connection's (actual) source IP Address,
where Network Address Translation is performed (e.g. proxies, etc.)
- [New] natDestinationAddress - the (actual) destination IP Address, where
Network Address Translation is performed (e.g. proxies, etc.)
- [New] natSourcePort - the network connection's (actual) source port, where
Network Address Translation is performed (e.g. proxies, etc.)
- [New] natDestinationPort - the (actual) destination port, where Network
Address Translation is performed (e.g. proxies, etc.)
- registryKeyState- new complex type that specifies 'old' and 'new' properties of a registry key:
- process - Process ID (PID) of the process that modified the registry key (process
details will appear in the alert 'processes' collection)
- operation - operation that changed the registry key name and/or value
(add, modify, delete)
- valueType - registry key value type (e.g. REG_BINARY, REG_DWORD, etc. -
enumeration)
- hive - registry hive (e.g. HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER, etc. -
enumeration)
- key - current (i.e. changed) registry key (excludes HIVE)
- valueName - current (i.e. changed) registry key value name
- valueData - current (i.e. changed) registry key value data (contents)
- oldKey - previous (i.e. before changed) registry key (excludes HIVE)
- oldValueName - previous (i.e. before changed) registry key value name
- oldValueData - previous (i.e. before changed) registry key value data (contents)
