Giter Club home page Giter Club logo

secmgmt-insights-connector's Introduction

Security and Management Insights Connector

Microsoft 365 provides several advanced security and management features that empower you to improve your, or your customers, security posture. Knowing what features are configured and whether they adhere to the recommended configurations is challenging. Using this connector, you will be able gain insights what components have been adopted and how they are configured.

Bug Bash

As enhancements are made to the connector and new features added it can be difficult to test for every scenario. While we strive to ensure the solution is free of any complications and issues, there is a chance something might make it through testing. This means there is a possbility that the connector might not behave as expected. With this in mind from time to time we will have a virtual bug bash where everyone is encouraged to create bugs for any unexpected behavior. Often these events will happen when significant changes are made to the connector. See our bug bash guide for more details.

Getting Started

Prior to utilizing this connector to gain insights from your, or your customers, environment there are some required actions that need to be taken. The remaining sections of this article will guide you through fulfilling the prerequisites, installing the connector, and how to leverage on the templates. If you have any questions about this process please open an issue for help.

Prerequisites

If you do not already have Power BI Desktop installed, then download and install it. Once installed you will want to perform the perform the following

  1. Start Power BI Desktop on the device where you plan to install the connector
  2. Click file -> options and settings -> options
  3. Click security under the global section
  4. Click (Not Recommended) Allow any extension to load without validation or warning

This step is required because by default the connector that will be installed is not digitally signed. It is not signed because during the installation process an application identifier value will be injected that is unique for your environment. See handling Power Query Connector signing for details on the signing the connector if you are interested.

Installation

To simplify the process of creating and configuring the dependent resources for the connect, the Install-SecMgmtInsightsConnector cmdlet has been added to the Security and Management Open PowerShell module. You can leverage the following PowerShell to install the connector on the device invoking the command

Install-Module SecMgmt

# When prompt for credentials you will need to specify an account that has the ability to create an Azure Active Directory application.
Connect-SecMgmtAccount

# Use the following if you are planning to gain insights for a single tenant.
Install-SecMgmtInsightsConnector -ApplicationDisplayName 'Security and Management Insights'

# Use the following line if you plan to use the connector to gain insights for customers you have through the Cloud Solution Provider program.
Install-SecMgmtInsightsConnector -ApplicationDisplayName 'Security and Management Insights' -ConfigurePreconsent:$true

When you invoke the above a new Azure Active Directory application will be created, for use with the connector. Then the latest version of the connector is downloaded, configured, and installed on the local device.

Template

Once the prerequisites have been fulfilled and the connector has be installed, you can start building reports that incorporate functionality from the connector. You can start from scratch or leverage one of the following templates

Name Description
Customer template Template that is intended to be used if you are looking to get insights for your own tenant
Partner template Template that is intended to be used by partners to gain insights for their customers

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

secmgmt-insights-connector's People

Contributors

microsoft-github-operations[bot] avatar microsoftopensource avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar

secmgmt-insights-connector's Issues

Cannot import templates

Steps to reproduce

Have run latest version of PS script to install the app on Azure, downloaded latest MEZ file and signed it with valid cert. When try to import the PowerBI template file its stuck on waiting for other queries for a very long time, then fails with error. same for both template files.
When I create a new empty report, I can Get Data from the basic connector and see all tables are full with details so I guess the app is configured correctly.
no matter how much I try creating a report from template, same error always.

Expected behavior

would love to see a working PowerBI report using the template.

Environment

CSP partner with lots of customers
Latest Win10, PowerBI desktop
Screen Shot 2020-07-16 at 0 55 04

Device configuration policies

Steps to reproduce

Run the following function

SecMgmtInsights.DeviceConfigurationPolicies({"CUSTOMER-ID-REMOVED"})

Expected behavior

The data from the API to be returned in the resulting table

Actual behavior

Expression.Error: The field 'dmaGuardDeviceEnumerationPolicy' of the record wasn't found.
Details:
    @odata.type=#microsoft.graph.windows10GeneralConfiguration

Note this is like the device compliance issue where the introduction of the dynamic schema feature has caused some errors due to the diverse types of data being returned from the API

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

OneDrive usage detail

Steps to reproduce

Run the following query

SecMgmtInsights.OneDriveUsageAccountDetail(GetTenantList())

Expected behavior

The resulting table should contain data

Actual behavior

The resulting table contains a Value column with either null or a record

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

License recommendations

Feature Request

Is your feature request related to a problem?
As a partner I would like to have insights into the following

  • churn
  • expansion of licenses
  • licenses my customers currently have

So, I can take the appropriate actions to ensure the success of a customer

Describe the solution you would like
To have the data incorporated into the connector and a tab added to the standard template that shows how the data can be utilized

Describe alternatives you have considered
N/A

Additional context
N/A

Template relationship cardinality

Steps to reproduce

The following table should have a many to one relationship. With the templates they are currently set to one to one

  • Alerts
  • ConditionalAccessPolicies
  • MailboxUsageDetails
  • RiskyUsers
  • WindowsAutoPilotProfiles
  • WindowsMalwareInformation

Expected behavior

The template to refresh without an issue

Actual behavior

Errors were encountered due to duplicate keys

Environment

Windows 10
Power BI Desktop

Function documentation

Feature Request

Is your feature request related to a problem?
As a consumer of the connector it would be helpful to have function documentation, so I will know what each function does

Describe the solution you would like
Implement function documentation as described here

Users query

Steps to reproduce

Invoke the following query

SecMgmtInsights.Users()

Expected behavior

Each column to either contain data or null if not data for that field is present in the response from the API

Actual behavior

Some columns, such as imAddresses, will contain an error with the following details

Expression.Error: We cannot convert the value null to type List.
Details:
    Value=
    Type=[Type]

Environment

Windows 10
Power BI Desktop
SecMgmtInsights connector 1.3

Windows update metrics

Feature Request

Is your feature request related to a problem?
As a administrator I need insights into the success/failure metrics of Windows updates, so I can have a better understanding of the overall health

Describe the solution you would like
Having the ability to gain insights on the success/failure metrics of Windows update

Auto detect schema

Feature Request

Is your feature request related to a problem?
As a consumer of the connector, I am frustrated when new features are added to the API that are not reflected through the connector.

Describe the solution you would like
Ideally the connect would auto detect the schema using data from Microsoft Graph and the process described here

Describe alternatives you have considered
N/A

Additional context
N/A

Connector build output

Steps to reproduce

Build the solution and the last connector is the only file in the artifacts directory

Expected behavior

Both the SecMgmtInsights.mez and SecMgmtInsights.PowerShell.mez files should be in the artifacts directory

Actual behavior

Only the output from the last built connector is found in the artifacts directory

Environment

  • Visual Studio 2019

Nested queries

Feature Request

Is your feature request related to a problem?
The performance of the connector could be improved by not getting the schema for the nested queries until the final request

Describe the solution you would like
There should be an intermediate step that would allow the nest requests to obtain the raw data

Describe alternatives you have considered
N/A

Additional context

Currently the connector handles nested queries using logic similar to the following

[DataSource.Kind="SecMgmtInsights"]
shared SecMgmtInsights.WindowsProtectionState = (optional tenants as list) as table =>
    let 
        source = Request.GraphFeed("/v1.0/deviceManagement/managedDevices?$select=id", tenants),
        renamedColumn = Table.RenameColumns(source, {"id", "deviceId"}),
        data = Table.AddColumn(renamedColumn, "Custom", each try Request.GraphContents("/beta/deviceManagement/managedDevices/" & [deviceId] & "/windowsProtectionState", {[tenantId]}) otherwise null)
    in
        Table.ExpandData(data, {"id", "tenantId"});

Ideally the GraphContents and GraphFeed functions would either be modified to not request the schema or another function used for this need.

Diagnostic Information

Feature Request

Is your feature request related to a problem?
As a consume of the connector, I am frustrated when there is an issue and the diagnostic features of Power BI provide no additional information

Describe the solution you would like
Error information from the connector to be emitted into the diagnostics. An example of how this can be accomplished can be found here

Describe alternatives you have considered
N/A

Additional context
N/A

Template - MailboxUsageDetail relationship

Steps to reproduce

Utilizing the standard partner template with a customer that has numerous mailboxes, when the report refreshes a duplicate value error will be thrown

Expected behavior

The report to refresh without issue

Actual behavior

An exception is encountered because the relationship between the MailboxUsageDetails and Customers tables should be *:1

Environment

Windows 10
Power BI Desktop
Template version 1.0

SecureBootEnabled control

Steps to reproduce

The info link for the SecureBootEnabled control is currently a placeholder

Expected behavior

The link should reference a document on docs.microsoft.com

Actual behavior

The link is current https://aka.ms/placeholder

Environment

Windows 10
Power BI Desktop
SecMgmtInsights connector v1.2

Standard template customers query

Steps to reproduce

Using the standard template open it and attempt to load customers

Expected behavior

List of customers should load without an issue

Actual behavior

Due to a hard coded value the customers query does not load as excepted

Environment

Windows 10
Power BI Desktop

Automate deployment

Feature Request

Is your feature request related to a problem?
As a consumer of the solution, I am frustrated with the steps required to get both the standard and advanced templates working.

Describe the solution you would like
A simple solution that performs the configurations required and makes it where both version of the template can be consumed

Describe alternatives you have considered
N/A

Additional context
N/A

Windows protection state function

Steps to reproduce

Run the following function for a customer that does not have any devices that return from the managed devices function

SecMgmtInsights.WindowsProtectionState({"CUSTOMER-ID-HERE"})

Expected behavior

An empty table to be returned

Actual behavior

Expression.Error: The column 'id' of the table wasn't found.
Details:
    id

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

Subscribed SKUs

Feature Request

Is your feature request related to a problem?
As customer, or partner, administrator I would to have access to the SKUs where a tenant has subscribed so I can have insight into the services they have

Describe the solution you would like
That a new function be added to expose the subscribed SKUs

Service communication functions

Steps to reproduce

Run the following functions

SecMgmtInsights.ServiceCurrentStatus(GetTenantList())
SecMgmtInsights.ServiceHistoricalStatus(GetTenantList())

Expected behavior

A table to be returned that contains data from the service communication API

Actual behavior

Expression.Error: There weren't enough elements in the enumeration to complete the operation.
Details:
    [Table]

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

Subscription expiration

Feature Request

Is your feature request related to a problem?
As a customer I would like to have insight into the expiration date for non-CSP subscriptions, so I can ensure everything is being renewed prior to any issues.

Describe the solution you would like
The connector should provide information on the license based subscriptions available through non-CSP channels

Filter actions that require customer action

Feature Request

Is your feature request related to a problem?
As a partner I am frustrated when I see a list of actions to perform, that cannot be done without interacting with the customer.

Describe the solution you would like
The list of actions to be performed should have additional context to give us insights into whether or not an action can be taken without connecting with a customer first.

Integration with Azure KeyVault

Feature Request

Is your feature request related to a problem?
As an administrator I would like to have the Azure Functions application integrate with Azure Key Vault to get the refresh token

Describe the solution you would like
The refresh token required for the Azure Functions application should be pulled from Azure Key Vault

Subscribed SKUs

Steps to reproduce

Run the following function

SecMgmtInsights.SubscribedSkus(GetTenantList())

Expected behavior

A table containing the subscribed SKUs for the specified list of tenants

Actual behavior

Expression.Error: The column '@odata.context' of the table wasn't found.
Details:
    @odata.context

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

Dynamic schema list conversion

Steps to reproduce

Run one of the following queries

SecMgmtInsights.DeviceConfigurationPolicies()
SecMgmtInsights.Users()

Expected behavior

Null value to shown in the field

Actual behavior

Rows that should have null values for the fields may contain an error that states the following

Expression.Error: We cannot convert the value null to type List.
Details:
    Value=
    Type=[Type]

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

Power BI Desktop - get data

Feature Request

Is your feature request related to a problem?
As a consumer of the connector I am frustrated when utilizing the SecMgmtInsights connector in a new report and the Get Data operation does not show all the available tables

Describe the solution you would like
When leveraging Power BI Desktop to add the SecmgmtInsights as a new data source, all of the table should be shown. This way things will be easier to discover

Describe alternatives you have considered
Leveraging the templates is helpful, but they only helpful if you are planning to use them as a starting point.

Expanded columns lost type

Steps to reproduce

Run the following query

SecMgmtInsights.WindowsProtectionState({"c68f63d2-44d5-499e-9fd8-aaf76f96e900"})

Expected behavior

That each column would keep the appropriate type

Actual behavior

Columns have lost their types due to the expansion and how the GraphContents and GraphFeed functions are adding the columns with specifying the type

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

Add support for single tenant

Feature Request

Is your feature request related to a problem?
As a tenant administrator I could use the same insights, to get better understanding of my security posture

Describe the solution you would like
Currently the design only supports partners, I would like to see it where a list of tenant identifiers could be a parameter to each function in the SecMgmtInsights connector

Describe alternatives you have considered
With the current design there is not alternative solution using this connector

Updating the connector

Feature Request

Is your feature request related to a problem?
As a consumer of the connector, I need a way to update the module without having to recreate the Azure AD application

Describe the solution you would like
A defined process to update the connector that does not involve creating a new Azure AD application

Describe alternatives you have considered
Performing the update manually, but this operation can be complex.

Additional context
N/A

Risk detections

Steps to reproduce

Run the following query

SecMgmtInsights.RiskDetections()

Expected behavior

Data or an empty table to be returned

Actual behavior

Expression.Error: We cannot convert a value of type Record to type Text.
Details:
    Value=[Record]
    Type=[Type]

This is a permissions issue caused by a permission missing from the Azure Active Directory application registration

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

Microsoft Information Protection

Feature Request

Is your feature request related to a problem?
As an administrator it would be helpful to have a view of the available labels, so I can ensure everything is provisioned as expected.

Describe the solution you would like
To have a function that pull the label information as documented here.

There weren't enough elements

Steps to reproduce

Run the following query using credentials associated with a tenant that does not have Microsoft Intune

SecMgmtInsights.SubscriptionState()

Expected behavior

There should be a table with no data returned

Actual behavior

Expression.Error: There weren't enough elements in the enumeration to complete the operation.
Details:
    [Table]

Environment

Windows 10
Power Desktop 10
SecMgmtInsights version 1.3

Query Folding

Feature Request

Is your feature request related to a problem?
As a consumer of the connector I am frustrated with the performance for large datasets.

Describe the solution you would like
Query folding should be implemented to help with the performance. An example of how this can be accomplished can be found here

Describe alternatives you have considered
N/A

Additional context
N/A

Identity security defaults function

Steps to reproduce

Run the following function

SecMgmtInsights.IdentitySecurityDefaultsEnforcementPolicy(GetTenantList())

Expected behavior

The resulting table to be returned and data to be expanded

Actual behavior

The resulting table contains the tenant identifier and a column with a list

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

Office 365 service health

Feature Request

Is your feature request related to a problem?
As an administrator I need insight into the service health for Office 365 to know if there is an issue

Describe the solution you would like
Having the ability to identify issues with Office 365 services

HTTP Request Optimization

Feature Request

Is your feature request related to a problem?
As a consumer of this connector it is frustrating when HTTP request that should fail are retried (e.g. request data for Intune when the customer does not have an entitlement for that feature)

Describe the solution you would like
The connector should either handle the bad request from the API so it is not retried, or it should validate the customer has the appropriate entitlement before attempting the call

Describe alternatives you have considered
N/A

Additional context
N/A

Errors are replaced with null

Steps to reproduce

When invoking queries against customers where you do not have permissions, no error is being returned. The table only contains the tenantId and null for each column

Expected behavior

The resulting table for invoking any query should contain error details for the network operations

Actual behavior

The errors are being masked with null values

Environment

Windows 10
Power BI Desktop
SecMmgtInsights 1.3

Endpoint analytics

Feature Request

Is your feature request related to a problem?
As an administrator I would like to have insight into the device analytics, so I can determine where issues might exists

Describe the solution you would like
That data from the endpoint analytics feature be included in the report

Describe alternatives you have considered
N/A

Additional context
N/A

Identity Security Default query

Steps to reproduce

Invoke the SecMgmtInsights.IdentitySecurityDefaultsEnforcementPolicy query and the data returned will be null

Expected behavior

The query should return data for the given list of tenants

Actual behavior

The table only contains the tenant identifiers and nul

Environment

Windows 10
Power BI Desktop
SecMgmtInsights Connect v1.2

Audit and DLP activities

Feature Request

Is your feature request related to a problem?
As an administrator I need insight into audit and DLP activities, so I can better understand what is happening within my environment

Describe the solution you would like
Incorporate data from the Office 365 Service Communication API as documented here

Memory consumption

Steps to reproduce

Using the partner template refresh the entire report

Expected behavior

The report to refresh to with minor impact to memory

Actual behavior

As the report is refreshing it will continue to consume memory at a higher than expected rate. This is only happening with the version 1.3 which has not been released yet.

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

Software deployment metrics

Feature Request

Is your feature request related to a problem?
As an administrator I need to see success/failure metrics for software deployments, so I can work to remediate any issues

Describe the solution you would like
Having the ability to query software deployments and get metrics for success/failure

Microsoft Defender collection column duplication

Steps to reproduce

Invoke the SecMgmtInsights.DetectedMalwareState function and there will be two columns named category

Expected behavior

This column should not be duplicated

Actual behavior

Currently there are two columns with the name category included in the table returned from the function

Environment

Power BI Desktop

Power BI template

Feature Request

Is your feature request related to a problem?
As an administrator it would be helpful to have a Power BI template, that way I can see how everything could work together

Describe the solution you would like
To have a Power BI template that demonstrates how the connector could be leveraged to gain insights from the data

Paging not working

Steps to reproduce

Request a resource that supports paging and has more entries then the default page size

Expected behavior

All records available should be returned

Actual behavior

Only the records for the first page will be returned

Environment

Power BI Desktop

Controls defined in source control

Feature Request

Is your feature request related to a problem?
As an administrator I would like to have the controls defined through GitHub instead of Azure Cosmos DB, that way they are easy to modify

Describe the solution you would like
The controls used to measure feature adoption should be included in GitHub

Require MFA

Feature Request

Is your feature request related to a problem?
As a partner, who is required to authenticate using MFA, I am frustrated when the connector does not work as expected because the user account used to authenticate was not challenged for MFA due to way Identity Security Defaults works.

Describe the solution you would like
The connector should require MFA

Device compliance policies

Steps to reproduce

Run the following query

SecMgmtInsights.DeviceCompliancePolicies({"TENANT-ID-REMOVED", "TENANT-ID-REMOVED"})

Expected behavior

Data for each compliance policy to be returned

Actual behavior

Information for some of the compliance policies will be returned and others will result in an error like the following

Expression.Error: The field 'passwordBlockSimple' of the record wasn't found.
Details:
    @odata.type=#microsoft.graph.androidCompliancePolicy
    roleScopeTagIds=[List]

Note this is being caused by the fact the request for device compliance policies returns multiple types. So, the code, as it stands now, needs to detect each type returned in the collection.

Environment

Windows 10.
Power BI Desktop
SecMgmtInsights version 1.3

Error Install-SecMgmtInsightsConnector

Hi Isaiah
Get the following error trying to Install the application.
Also I want specify for it to go into a specific subscription. Can you provide relevant coding for that.
Would you be willing to arrange a one-on-one teams session to work through this with me? I am keen to see if this does what I am hoping it does

Install-SecMgmtInsightsConnector -ApplicationDisplayName 'Security and Management Insights' -ConfigurePreconsent:$true
Install-SecMgmtInsightsConnector : Code: Request_UnsupportedQuery
Message: Unsupported Query.
Inner error:
AdditionalData:
date: 2020-07-10T03:51:13
request-id: 1ad30bc8-e71a-4501-b8df-7aebc87c25a0
ClientRequestId: 1ad30bc8-e71a-4501-b8df-7aebc87c25a0
At line:1 char:1

  • Install-SecMgmtInsightsConnector -ApplicationDisplayName 'Security an ...
  •   + CategoryInfo          : CloseError: (:) [Install-SecMgmtInsightsConnector], ServiceException
      + FullyQualifiedErrorId : Microsoft.Online.SecMgmt.PowerShell.Commands.InstallSecMgmtInsightsConnector
    

Mobile app status functions

Steps to reproduce

Invoke one of the following functions

  • MobileAppDeviceStatuses
  • MobileAppInstallSummary
  • MobileAppUserStatuses

Expected behavior

Data to be returned for the specified list of tenants

Actual behavior

Data is only returned for the tenant associated with the authenticated user that is refreshing the report

Environment

Windows 10
Power BI Desktop
SecMgmtInsights version 1.3

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    ๐Ÿ–– Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. ๐Ÿ“Š๐Ÿ“ˆ๐ŸŽ‰

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google โค๏ธ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.