schema.graphql

# Semver string e.g. "<=5.0.0"
scalar Semver

type Query {
  device: Device
  policy: Policy
}

type Policy {
  validate(policy:DevicePolicy): PolicyResult!
}

# Available information about user device
type Device {
  # machine information
  deviceId: String
  # name of device
  deviceName: String # system_info
  # standard, less-friendly name of platform
  platform: String
  # friendly name of platform
  platformName: String
  # operating system version
  osVersion: String
  # os build
  osBuild: String
  # os name
  osName: String
  # device firmware version
  firmwareVersion: String
  # device model
  hardwareModel: String
  # friendly name of model
  friendlyName: String
  # device serial number
  hardwareSerial: String
  # installed applications
  applications: [Application]
  # browser extensions
  extensions(browser: Browser): [Extension]
  # current IP addresses
  ipAddresses: [IpAddress]
  # interface_details
  macAddresses: [NetworkInterface]
  # version of the stethoscope application
  stethoscopeVersion: String
  # osquery version (platform specific)
  osqueryVersion: String
  # available hard disks
  disks: [Disk]
  security(policy:DevicePolicy): SecurityInfo
  policyResult: FeatureState
}

type SecurityInfo {
  osVersion: FeatureState
  # current firewall state
  firewall: FeatureState
  # whether automatic updates are enabled
  automaticUpdates: FeatureState
  # if OS specific disk encryption is enabled
  diskEncryption: FeatureState
  # if screen lock is enabled
  screenLock: FeatureState
  # remote login setting
  remoteLogin: FeatureState
  # whether applications auto update
  automaticAppUpdates: FeatureState
  # whether automatic security updates are enabled
  automaticSecurityUpdates: FeatureState
  # whether OS Updates are automatically downloaded (Mac only)
  automaticOsUpdates: FeatureState
  # whether software updates are downloaded in background (Mac only)
  automaticDownloadUpdates: FeatureState
  # whether system config data is set to auto update
  automaticConfigDataInstall: FeatureState
  # Windows
  publicFirewall: FeatureState
  # Windows
  privateFirewall: FeatureState
  # Windows
  domainFirewall: FeatureState
}

type Application {
  name: String!
  displayName: String
  version: String!
  lastOpenedTime: String
  installDate: String
}

type Extension {
  name: String!
  path: String!
  version: String!
  author: String!
  identifier: String!
  browser: String!
}

# A DevicePolicy is a description of the desired state of a set of pre-selected device features
input DevicePolicy {
  # current operation system version, use [semver](https://www.nodesource.com/blog/semver-a-primer/) strings to define requirement
  osVersion: PlatformBracketRequirement
  # whether or not software firewall is required
  firewall: RequirementOption
  # whether or not disk encryption is required (this is not a comprehensive check as users are free to employ encyption that isn't baked into the OS)
  diskEncryption: RequirementOption
  # whether or not automatic updates need to be enabled
  automaticUpdates: RequirementOption
  # whether or not screen lock is required ("IF_SUPPORTED" is recommended)
  screenLock: RequirementOption
  # remote login status
  remoteLogin: RequirementOption
  # require applications to be installed
  requiredApplications: [AppRequirement]
  # ban applications from being installed on user's machine
  bannedApplications: [AppRequirement]
  # placeholder for suggested applications
  suggestedApplications: [AppRequirement]
  # add extensions
  stethoscopeVersion: Semver
  # [WINDOWS ONLY] optional maximum screenlock timeout (in seconds)
  windowsMaxScreenLockTimeout: Int
}

# Defines a requirement for an installed application
input AppRequirement {
  # required application name
  name: String!
  # optional application version requirement
  version: Semver
  # optional platform if only required for specific OS
  platform: PlatformStringRequirement
  # controls whether regex or equality check is performed against application name
  exactMatch: Boolean
  # controls whether bin packages are checked (homebrew, chocolatey, etc)
  includePackages: Boolean
  # install URL
  url: String
  # explanation to show user
  description: String
}

type PolicyResult {
  # overall policy result
  status: FeatureState
  # status indicating whether osVersion passed test
  osVersion: FeatureState
  # current firewall state
  firewall: FeatureState
  # whether automatic updates are enabled
  automaticUpdates: FeatureState
  # if OS specific disk encryption is enabled
  diskEncryption: FeatureState
  # if screen lock is enabled
  screenLock: FeatureState
  # remote login setting
  remoteLogin: FeatureState
  # whether or not all requiredApplications are installed
  requiredApplications: [ApplicationFeatureState]
  # whether or not any bannedApplications are installed
  bannedApplications: [ApplicationFeatureState]
  # placeholder for suggested applications
  suggestedApplications: [ApplicationFeatureState]
  # stethoscope is up-to-date
  stethoscopeVersion: FeatureState
}

type Security {
  # operating system version requirement
  osVersion(requirement: PlatformBracketRequirement!): Boolean!
  firewall(requirement: RequirementOption!): Boolean!
  diskEncryption(requirement: RequirementOption!): Boolean!
  screenLock(requirement: RequirementOption!): Boolean!
  remoteLogin(requirement: RequirementOption!): Boolean!
  requiredApplications(requirement: RequirementOption!): [Boolean!]!
  bannedApplications(requirement: RequirementOption!): [Boolean!]!
  suggestedApplications(requirement: RequirementOption!): [Boolean!]!
  stethoscopeVersion(requirement: Semver!): Boolean!
  automaticUpdates(requirment: RequirementOption!): Boolean!
  automaticOsUpdates(requirement: RequirementOption!): Boolean!
  automaticSecurityUpdates(requirement: RequirementOption!): Boolean!
  automaticAppUpdates(requirement: RequirementOption!): Boolean!
  automaticDownloadUpdates(requirement: RequirementOption!): Boolean!
  automaticConfigDataInstall(requirement: RequirementOption!): Boolean!
  publicFirewall(requirement: RequirementOption!): Boolean!
  privateFirewall(requirement: RequirementOption!): Boolean!
  domainFirewall(requirement: RequirementOption!): Boolean!
}

type IpAddress {
  interface: String
  address: String
  mask: String
  broadcast: String
}

# describes a network interface on a device
type NetworkInterface {
  interface: String
  type: String
  mac: String
  physicalAdapter: Boolean
  # the last time network interface was updated
  lastChange: String
}

# describes a hard disk on a device
type Disk {
  name: String
  uuid: String
  label: String
  encrypted: Boolean
}

type ApplicationFeatureState {
  name: String
  status: FeatureState
}

# a platform string requirement defines a target string value for specific platforms
input PlatformStringRequirement {
  darwin: Semver
  win32: Semver
  ubuntu: Semver
  linux: Semver
  all: Semver
}

input PlatformBracketRequirement {
  darwin: VersionBracket
  win32: VersionBracket
  ubuntu: VersionBracket
  linux: VersionBracket
  all: VersionBracket
}

# a platform boolean requirement defines a target boolean value for specific platforms
input PlatformBoolRequirement {
  darwin: Boolean
  win32: Boolean
  ubuntu: Boolean
  linux: Boolean
  all: Boolean
}

input VersionBracket {
  ok: Semver
  nudge: Semver
}

enum Browser {
  chrome
  firefox
  safari
  all
}

# possible states that a device 'feature' can be in
enum FeatureState {
  PASS
  FAIL
  NUDGE
  ON
  OFF
  UNKNOWN
}

# valid values for a given policy requirement
enum RequirementOption {
  ALWAYS
  SUGGESTED
  IF_SUPPORTED
  NEVER
}