schema.graphql

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

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
  screenIdle: 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

  automaticCheckEnabled: FeatureState
  # Windows
  publicFirewall: FeatureState
  # Windows
  privateFirewall: FeatureState
  # Windows
  domainFirewall: FeatureState
}

type Application {
  name: String! # e.g. Slack.app
  path: String # ~/Applications for Mac, or Win32 Registry path for Windows
  version: Semver
  assertion: RequirementOption! # ALWAYS, NEVER, SUGGESTED, etc.
  description: String
  installFrom: String
}

input ApplicationPaths {
  darwin: String # "/Applications"
  win32: String # "HKLM\Software\Microsoft\Windows\CurrentVersion\Uninstall"
  linux: String # "/usr/share"
}

input ApplicationRequirement {
  name: String! # e.g. Slack.app
  paths: ApplicationPaths
  platform: PlatformStringRequirement
  version: Semver
  assertion: RequirementOption! # ALWAYS, NEVER, SUGGESTED, etc.
  description: String
  installFrom: 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 encryption 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
  screenIdle: NumericRange
  # remote login status
  remoteLogin: RequirementOption
  # require applications to be installed
  applications: [ApplicationRequirement]
  # add extensions
  stethoscopeVersion: Semver
  # [WINDOWS ONLY] optional maximum screenlock timeout (in seconds)
  windowsMaxScreenLockTimeout: Int
  openWifiConnections: RequirementOption
}

# 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
  screenIdle: FeatureState
  # remote login setting
  remoteLogin: FeatureState
  # whether or not applications requirements are satisfied
  applications: [ApplicationFeatureState]
  # stethoscope is up-to-date
  stethoscopeVersion: FeatureState
  # Open Wi-Fi
  openWifiConnections: FeatureState
}

type Security {
  # operating system version requirement
  osVersion(requirement: PlatformBracketRequirement!): Boolean!
  firewall(requirement: RequirementOption!): Boolean!
  diskEncryption(requirement: RequirementOption!): Boolean!
  screenLock(requirement: RequirementOption!): Boolean!
  screenIdle(requirement: NumericRange!): Boolean!
  remoteLogin(requirement: RequirementOption!): Boolean!
  applications(requirement: RequirementOption!): [Boolean!]!
  stethoscopeVersion(requirement: Semver!): Boolean!
  automaticUpdates(requirement: RequirementOption!): Boolean!
  automaticOsUpdates(requirement: RequirementOption!): Boolean!
  automaticSecurityUpdates(requirement: RequirementOption!): Boolean!
  automaticAppUpdates(requirement: RequirementOption!): Boolean!
  automaticDownloadUpdates(requirement: RequirementOption!): Boolean!
  automaticConfigDataInstall(requirement: RequirementOption!): Boolean!
  automaticCheckEnabled(requirement: RequirementOption!): Boolean!
  publicFirewall(requirement: RequirementOption!): Boolean!
  privateFirewall(requirement: RequirementOption!): Boolean!
  domainFirewall(requirement: RequirementOption!): Boolean!
  openWifiConnections(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
  version: String
  installed: Boolean
  state: String
}

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

input PlatformBracketRequirement {
  darwin: VersionBracket
  win32: VersionBracket
  ubuntu: VersionBracket
  linux: VersionBracket
  awsWorkspace: 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
  awsWorkspace: 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
}