Development

.env.example

@@ -1,2 +1,6 @@
 CLIENT_ID=
-CLIENT_SECRET=
+CLIENT_SECRET=
+TENANT=
+FINDING_SEVERITY=
+FINDING_LIMIT=
+BASE_URL_API=

.gitignore

@@ -5,3 +5,4 @@ dist/
 .env
 .eslintcache
 tsconfig.tsbuildinfo
+ coverage/

docs/development.md

@@ -5,24 +5,174 @@ Please reference any SDKs or API docs used to help build the integration here.
 
 ## Prerequisites
 
-Supply details about software or tooling (like maybe Docker or Terraform) that
-is needed for development here.
+- An Azure account with an App Registration that will provide credentials for
+  the integration to authenticate with Microsoft Graph APIs. The App
+  Registration also defines the permissions the integration requires and which
+  the target tenant must authorize.
+- An Active Directory tenant to target for ingestion. It is possible to target
+  the Active Directory tenants defined in the Azure account holding the App
+  Registration. Multi-tenant App Registrations that have not undergone
+  [Publisher Verification][publisher-verification] cannot access other tenants.
+- A Microsoft Defender for Endpoint account to create devices and run attacks
+  via simulation technique. Can track vulnerabilities data, user groups creation
+  and mapping users to devices.
 
-Please supply references to documentation that details how to install those
-dependencies here.
+A JupiterOne staff developer can provide credentials for an existing development
+Azure account with an App Registration and tenants that tests are written
+against. This is the easiest way to begin making changes to the integration.
 
-Tools like Node.js and NPM are already covered in the [README](../README.md) so
-don't bother documenting that here.
+Alternatively, you may establish a new Azure account, though tests will likely
+need to be improved to avoid specific account information.
 
-## Provider account setup
+## App Registration
 
-Please provide information about the steps needed to create an account with a
-provider. Images and references to a provider's documentation is very helpful
-for new developers picking up your work.
+In Ms Defender portal:
+
+1. [Create a Microsoft Defender for Endpoint account](https://www.microsoft.com/en-us/security/business/threat-protection/endpoint-defender)
+2. [Set up the lab and add devices](#add-devices-and-simulations)
+
+In the Azure portal:
+
+1. Create a mulit-tenant App Registration
+2. Configure the required [API permissions](#api-permissions)
+3. Add a 2-year secret
+
+## Add Devices and Simulations
+
+In the [Defender portal](https://security.microsoft.com/homepage), navigate to
+**Evaluations**.
+
+1. Setup Lab
+
+   1. Choose number of devices
+   2. Accept terms and provide consent by checking the check box
+   3. Setup lab
+
+2. Add devices
+   1. Available Tools
+   2. Refresh the page to see the device status
+
+It should be Status → Active and Simulator status → Completed . (It will take
+some time to set up the device). After device setup is completed:
+
+3. Go to Simulation tab and create simulation Select simulator → All Select
+   simulation → SafeBreach: Credential Theft Select device → testmachine1
+4. Click on create simulation
+
+### API Permissions
+
+Need to setup API permissions under two containers (one for
+[azure account data](#microsoft-graph) and one for
+[defender account data](#windowsdefenderatp))
+
+#### Microsoft Graph
+
+1. `Organization.Read.All`
+   1. Read organization information
+   2. Needed for creating the `Account` entity
+2. `Directory.Read.All`
+   1. Read directory data
+   2. Needed for creating `User`, `Group`, and `GroupUser` entities
+
+#### WindowsDefenderATP
+
+1. `Machine.Read.All`
+   1. Read machine information
+   2. Needed for creating `Device` and `HostAgent` entities
+2. `User.Read.All`
+   1. Read user profiles
+   2. Needed for creating `User` entities
+3. `Vulnerability.Read.All`
+   1. Read Threat and Vulnerability Management vulnerability information
+   2. Needed for creating `Finding` entity
+
+## Target Tenants
+
+The integration is tested against three Active Directory tenants:
+
+1. The app is installed, all permissions are granted
+1. The app is installed, most permissions are insufficient
+1. The app is not installed
+
+This allows for ensuring the Microsoft Graph API code handles some common target
+configuration scenarios.
+
+You'll need a user account with global administrator access in each tenant.
+[Grant admin consent](#authentication) to the multi-tenant application as
+follows:
+
+1. Default tenant: grant permission now and always grant new permissions as
+   development of converters advances
+2. "J1 Insufficient Permissions" tenant: grant permissions now
+   (`Directory.Read.All` is all at this point in setup), but never grant any
+   additional permisssions, to allow for testing cases where the app cannot
+   fetch resources
+3. "J1 Inaccessible" tenant: do not install the app at all here, to allow for
+   testing cases where we have not been installed in a valid directory
+
+Update `test/config.ts` with directory IDs as appropriate.
 
 ## Authentication
 
-Supply details here for information on how to authenticate with a provider so
-that developers have an idea of what's needed to hit APIs. It may be useful to
-provide explanations for each value specified in the
-[`IntegrationInstanceConfigFieldMap`](../src/config.ts).
+The flow will provide the tenant ID where consent has been granted, which is
+stored for use in Microsoft Graph API calls.
+
+Admin consent is granted to JupiterOne by:
+
+1. Log in to JupiterOne as a user with permission to set up an integration
+2. Add a Microsoft defender integration instance
+3. You will be directed to Microsoft's identity platform, where you must login
+   in as a global administrator of the Active Directory tenant you intend to
+   target/ingest
+4. Review the requested permissions and grant consent
+
+To exercise the grant flow:
+
+1. Log in as a global administrator to the Active Directory Tenant you intend to
+   target/ingest
+1. Follow the url returned from the J1
+   `/integration-microsoft-365/v1/generate-auth-url` endpoint.
+1. After being redirected to something like
+   `https://localhost/microsoft-365/oauth-microsoft-365/v1/authorize?admin_consent=True&tenant=tenant-id&state=12345`,
+   capture the `tenant` query param.
+   1. You may need to check your network history for this query param as you
+      will likelybe redirected back to your instance configuration page faster
+      than you can pull the the tenant param.
+   1. This will be the same tenant id that you are logged into when you granted
+      concent.
+
+Use this `tenant` ID and information from the App Registration to create an
+`.env` file for local execution of the daemon/server application (this
+repository):
+
+```
+CLIENT_ID='885121e7-c3c6-4378-8f6b-e315cc5994ce'
+CLIENT_SECRET='<top secret passphrase>'
+TENANT='<tenant / directory id>'
+```
+
+## References
+
+How to set up permissions in the Azure console
+
+- https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-configure-app-expose-web-apis
+- https://docs.microsoft.com/en-us/azure/active-directory/develop/scenario-daemon-overview
+
+How to add a client secret in the Azure console
+
+- https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app#add-a-client-secret
+
+Sample Client Credentials Flow Project
+
+- https://github.com/AzureAD/azure-activedirectory-library-for-nodejs/blob/master/sample/client-credentials-sample.js
+
+SDK Links
+
+- https://docs.microsoft.com/en-us/azure/developer/javascript/azure-sdk-library-package-index
+- https://docs.microsoft.com/en-us/javascript/api/overview/azure/activedirectory?view=azure-node-latest
+
+Client Credentials oAuth flow Overview
+
+- https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-client-creds-grant-flow#application-permissions
+
+[msgraph-api]: https://docs.microsoft.com/en-us/graph/overview

docs/jupiterone.md

@@ -96,21 +96,33 @@ https://github.com/JupiterOne/sdk/blob/main/docs/integrations/development.md
 
 The following entities are created:
 
-| Resources | Entity `_type` | Entity `_class` |
-| --------- | -------------- | --------------- |
-| Account   | `acme_account` | `Account`       |
-| User      | `acme_user`    | `User`          |
-| UserGroup | `acme_group`   | `UserGroup`     |
+| Resources     | Entity `_type`                     | Entity `_class`  |
+| ------------- | ---------------------------------- | ---------------- |
+| Account       | `microsoft_defender_account`       | `Account`        |
+| CVE           | `cve`                              | `Vulnerability`  |
+| Device        | `user_endPoint`                    | `Device`, `Host` |
+| Machine       | `microsoft_defender_machine`       | `HostAgent`      |
+| User          | `microsoft_defender_logon_user`    | `User`           |
+| Vulnerability | `microsoft_defender_vulnerability` | `Finding`        |
 
 ### Relationships
 
 The following relationships are created:
 
-| Source Entity `_type` | Relationship `_class` | Target Entity `_type` |
-| --------------------- | --------------------- | --------------------- |
-| `acme_account`        | **HAS**               | `acme_group`          |
-| `acme_account`        | **HAS**               | `acme_user`           |
-| `acme_group`          | **HAS**               | `acme_user`           |
+| Source Entity `_type`        | Relationship `_class` | Target Entity `_type`              |
+| ---------------------------- | --------------------- | ---------------------------------- |
+| `microsoft_defender_account` | **HAS**               | `microsoft_defender_machine`       |
+| `microsoft_defender_machine` | **HAS**               | `microsoft_defender_logon_user`    |
+| `microsoft_defender_machine` | **IDENTIFIED**        | `microsoft_defender_vulnerability` |
+
+### Mapped Relationships
+
+The following mapped relationships are created:
+
+| Source Entity `_type`              | Relationship `_class` | Target Entity `_type` | Direction |
+| ---------------------------------- | --------------------- | --------------------- | --------- |
+| `microsoft_defender_machine`       | **MANAGES**           | `*user_endPoint*`     | FORWARD   |
+| `microsoft_defender_vulnerability` | **IS**                | `*cve*`               | FORWARD   |
 
 <!--
 ********************************************************************************

jest.config.js

@@ -1 +1,4 @@
-module.exports = require('@jupiterone/integration-sdk-dev-tools/config/jest');
+module.exports = {
+  ...require('@jupiterone/integration-sdk-dev-tools/config/jest'),
+  setupFiles: ['dotenv/config'],
+};