added policy documentation, fixed styles on required application prac…

…tice, fixed issues with handling of required applications. Added instructions for required apps.

docs/POLICIES.md

@@ -1 +1,207 @@
-// todo
+# Policies
+
+Policies are a declarative way to describe your organization's security recommendations for endpoint devices. The default policy for Stethoscope can be found in the practices directory [default policy](https://github.com/Netflix-Skunkworks/stethoscope-app/blob/master/practices/policy.yaml).
+
+Though [osquery](https://osquery.io/) (the main mechanism Stethoscope uses to query device details) provides read access to [most aspects of a device](https://osquery.io/schema/3.2.6), we have chosen to disallow raw queries and limit queries to a predefined set of attributes and schemas to prevent potential abuse.
+
+If you would like access to data that osquery provides but Stethoscope does not, please file an issue.
+
+## Specifying Requirements
+
+The specifics are explained in more detail below, but generally there are two main ways to express a requirement:
+
+  * [Semver](https://semver.org/) string (or platform-specific semver strings)
+  * `RequirementOption`
+
+### Semver Strings
+
+[Semver](https://semver.org/) (Semantic Versioning) is a common versioning practice that uses MAJOR.MINOR.PATCH format (e.g. 10.13.2). Semver supports comparisons and logical operators, and the policy allows any valid semver for comparison.
+
+**platform-specific semver**
+
+Some requirements (software versions, os verisons) are dependent on the platform. For these cases we have special GraphQL schemas defined:
+
+```graphql
+# specify one semver requirement per platform
+input PlatformStringRequirement {
+  darwin: Semver
+  win32: Semver
+  ubuntu: Semver
+  linux: Semver
+  all: Semver
+}
+
+# set bracketed (ok, nudge) requirements for platforms
+input PlatformBracketRequirement {
+  darwin: VersionBracket
+  win32: VersionBracket
+  ubuntu: VersionBracket
+  linux: VersionBracket
+  all: VersionBracket
+}
+# defines the acceptable range of versions
+input VersionBracket {
+  ok: Semver
+  nudge: Semver
+}
+```
+
+### RequirementOption
+
+The `RequirementOption` enum contains the following `ALWAYS`, `SUGGESTED`, `NEVER`, `IF_SUPPORTED` [schema](https://github.com/Netflix-Skunkworks/stethoscope-app/blob/master/schema.graphql#L251-L256)
+
+ If the requirement is `ALWAYS`, the user will only pass this practice if their setting is enabled
+
+ If the requirement is `SUGGESTED`, the user will pass whether or not the setting is enabled, but will receive a nudge (yellow) suggesting they enable it.
+
+ If the requirement is `NEVER`, the user will only pass if the setting is disabled.
+
+ If the requirement is `IF_SUPPORTED`, the user will only pass if their platform supports the practice (and reliable querying of the practice)
+
+## Understanding Responses
+
+Scans return a JSON object with an overall status and individual practice status. Valid return values for a scan/practice are: `PASS`, `NUDGE`, and `FAIL`.
+
+e.g.
+```json
+{
+  "data": {
+    "policy": {
+      "validate": {
+        "status": "PASS",
+        "osVersion": "PASS",
+        "firewall": "PASS",
+        "diskEncryption": "PASS",
+        "automaticUpdates": "PASS",
+        "screenLock": "PASS",
+        "remoteLogin": "PASS",
+        "stethoscopeVersion": "PASS",
+        "requiredApplications": [
+          {
+            "name": "Google Chrome",
+            "status": "PASS"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+
+---
+
+## Supported Practices
+
+### `os version` (yaml) | `osVersion` (json)
+
+OS Version allows you to specify what operation system version the user is running, based on the platform the app is running on.
+
+The requirement is specified to each platform and uses `semver` strings to specify version cutoffs. If `ok` matches the user's os version, they will show as passing this practice. If `nudge` matches the user's os version, they will see a yellow warning. If the user's version doesn't match `ok` or `nudge`, they will be shown a red warning.
+
+**Example os version policy (yaml)**
+
+```yaml
+os version:
+  darwin:
+    # High Sierra
+    ok: ">=10.13.6"
+    # Sierra
+    nudge: ">=10.12.6"
+  win32:
+    # Version 1803 - Redstone 3 Fall Creators Update
+    ok: ">=10.0.16299"
+    # Version 1703 - Redstone 2 Creators Update
+    nudge: ">=10.0.15063"
+  ubuntu:
+    ok: ">=18.4.0"
+    nudge: ">=18.0.2"
+```
+**Example os version policy (JSON)**
+
+```json
+{
+  "osVersion": {
+    "darwin": {
+      "ok": ">=10.13.6",
+      "nudge": ">=10.12.6"
+    },
+    "win32": {
+      "ok": ">=10.0.16299",
+      "nudge": ">=10.0.15063"
+    },
+    "ubuntu": {
+      "ok": ">=18.4.0",
+      "nudge": ">=18.0.2"
+    }
+  },
+}
+```
+
+You can use more complex semver strings if you want to warn on a specific OS version.
+
+### `firewall` (yaml) | `firewall` (json)
+
+Firewall checks the local firewall state using the default firewall provider in each platform (and `iptables` on linux). This practice uses the `RequirementOption` enum to specify the requirement.
+.
+Valid values are: `ALWAYS`, `SUGGESTED`, `NEVER`, `IF_SUPPORTED`
+
+### `disk encryption` (yaml) | `diskEncryption` (json)
+
+Disk encryption enumerates mounted drives and checks their encryption status using FileVault (mac), BitLocker (windows), and LUKS (linux). This practice uses the `RequirementOption` enum to specify the requirement.
+
+Valid values are: `ALWAYS`, `SUGGESTED`, `NEVER`, `IF_SUPPORTED`
+
+### `automatic updates` (yaml) | `automaticUpdates` (json)
+
+The automatic updates practice checks that the user has automatic updates enabled on their machine through `plist` values and service state (running). This practice uses the `RequirementOption` enum to specify the requirement.
+
+Valid values are: `ALWAYS`, `SUGGESTED`, `NEVER`, `IF_SUPPORTED`
+
+### `screen lock` (yaml) | `screenLock` (json)
+
+Does not work on El Capitan or higher as this setting was moved to the keychain and is not accessible. This practice uses the `RequirementOption` enum to specify the requirement.
+
+Valid values are: `ALWAYS`, `SUGGESTED`, `NEVER`, `IF_SUPPORTED`
+
+### `remote login` (yaml) | `remoteLogin` (json)
+
+Checks that remote login (RDP, SSH) is disabled for the device. This practice uses the `RequirementOption` enum to specify the requirement.
+
+Valid values are: `ALWAYS`, `SUGGESTED`, `NEVER`, `IF_SUPPORTED`
+
+### `required applications` (yaml) | `requiredApplications` (json)
+
+Application requirements have their own GraphQL schema:
+
+```graphql
+# 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
+}
+```
+
+You can specify requirements as an array of `AppRequirements`. e.g.
+
+```json
+{
+  "requiredApplications": [{
+    "name": "Google Chrome",
+    "version": ">=68.0.3440",
+    "url": "https://www.google.com/chrome/",
+    "description": "Google Chrome is a secure browser..."
+  }]
+}
+```

practices/instructions.en.yaml

@@ -199,3 +199,19 @@ practices:
         1. Click "Restart now"
 
         {{requirement "osVersion" "win32"}}
+
+  requiredApplications:
+    title: >
+      {{#if passing}}
+        Required applications are installed
+      {{else}}
+        Missing required applications
+      {{/if}}
+    description: >
+      Certain applications have been designated as necessary by your organization.
+    directions:
+      darwin: |
+        1. Please install the following applications:
+
+      win32: |
+        1. Please install the following applications

resolvers/platform/MacSecurity.js

@@ -1,5 +1,5 @@
 const semver = require('semver')
-const Device = require('../Device')
+const Device = require('./MacDevice')
 const OSQuery = require('../../sources/osquery')
 const { getScreenLock } = require('../../src/lib/applescript')
 const pkg = require('../../package.json')

src/Action.js

@@ -141,7 +141,6 @@ class Action extends Component {
           <div className='more-info'>
             <div className='description'>
               {action.description}
-              {this.props.children}
             </div>
             { action.details &&
               <pre className='description'>{action.details}</pre>
@@ -156,6 +155,7 @@ class Action extends Component {
               dangerouslySetInnerHTML={{__html: this.parseDirections()}}
             />
           )}
+          {this.props.children}
         </div>
       )
     }

src/Device.css

@@ -20,6 +20,7 @@
   font-size: 12px;
   color: #aaa;
   margin-top: 15px;
+  margin-bottom: 15px;
 }
 ul.mac-addresses {
   padding: 0;
@@ -218,3 +219,28 @@ a.btn:hover {
 .panel.device-summary.warning span {
   color: #5d4a19;
 }
+
+.result-list {
+  margin-left: 20px;
+  margin-bottom: 20px;
+}
+.result-list-item hr {
+  display: block;
+  height: 1px;
+  border: 0;
+  border-top: 1px solid #efefef;
+  margin: 1em 0;
+  padding: 0;
+}
+.result-heading {
+  display: flex;
+  align-items: baseline;
+  width: 90%;
+  justify-content: space-between;
+}
+.result-list-item {
+  display: flex;
+  align-items: baseline;
+  flex-direction: column;
+  justify-content: space-between;
+}

src/Device.js

@@ -54,11 +54,53 @@ class Device extends Component {
         security: this.props.security
       }
 
-      if (action.results) {
+      const hasResults = Array.isArray(action.results)
+      let results = action.results
+
+      if (hasResults && action.name.endsWith('Applications')) {
+        results = results.map(result => {
+          if (action.name in this.props.policy && Array.isArray(this.props.policy[action.name])) {
+            const target = this.props.policy[action.name].find(app => app.name === result.name)
+            if (target) {
+              return Object.assign({}, result, target)
+            }
+            return result
+          }
+        })
+      }
+
+      if (hasResults) {
         return (
           <Action {...actionProps}>
             <ul className='result-list'>
-              {action.results.map(({ name }) => <li key={name}>{name}</li>)}
+              {results.map(({ name, url, status, description }) => {
+                const iconProps = status === 'PASS'
+                  ? { name: 'checkmark', color: '#bbd8ca' }
+                  : { name: 'blocked', color: '#a94442' }
+                return (
+                  <li
+                    className='result-list-item'
+                    key={name}
+                  >
+                    <div className="result-heading">
+                      <strong>
+                        <ActionIcon
+                          className='action-icon'
+                          width='15px'
+                          height='15px'
+                        {...iconProps}
+                        /> {name}
+                      </strong>{' '}
+                      {status !== 'PASS' && url ? (
+                        <a href={`link://${url}`}>Download Application</a>
+                      ) : null}
+                    </div>
+                    <div>
+                      {description ? <p>{description}<hr /></p> : null}
+                    </div>
+                  </li>
+                )
+              })}
             </ul>
           </Action>
         )

src/start.js

@@ -108,7 +108,7 @@ function createWindow () {
   //   app.dock.show()
   // }
 
-  setTimeout(() => app.dock.hide(), 0)
+  if (!IS_DEV) setTimeout(() => app.dock.hide(), 0)
 
   if (process.platform === 'win32') {
     deeplinkingUrl = process.argv.slice(1)