diff --git a/samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/AttrService.md b/samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/AttrService.md new file mode 100644 index 0000000000..e4cf0db2d6 --- /dev/null +++ b/samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/AttrService.md @@ -0,0 +1,65 @@ +# attr::service:: variables + +[Automatic variables](./README.md) in the **attr::service::* namespace are provided with [Service requirements](../ProbeRequirements/ServiceRequirement.md). + +The following variables are available for each service. Service key is a value from [Service requirement supported values](../ProbeRequirements/ServiceRequirement.md#supported-values). + +| Variable name | Type | Description | +|------------------------------|--------|--------------------------------------| +| attr::service::_key_ | bool | Inidicates if the service is present | +| attr::service::_key_.name | string | Actual service name | +| attr::service::_key_.account | string | User account name for this service | + +## Examples + +In the following example the message will report actual user account name when the SQL Server Agent service is present and running under local service account. See [Message template](../MessageTemplate.md). + +```json +{ + … + "message": "Account '@{attr::service::SQLAgent.account}' is not supported for 'SQL Server Agent' service.", + "localServiceAccount": "NT AUTHORITY\\LOCALSERVICE", + "condition": [ + { "not": "@attr::service::SQLAgent" }, + { "ine": [ + "@attr::service::SQLAgent.account", + "@localServiceAccount" + ]} + ], + "probes": [ "IsClusteredServer" ] +} +``` + +The next example extends the previous check with support for clustered servers. When the server is clustered, three more accounts are not supported. + +```json +{ + … + "message": "Account '@{attr::service::SQLAgent.account}' is not supported for 'SQL Server Agent' service.", + "localServiceAccount": "NT AUTHORITY\\LOCALSERVICE", + "unsupportedAccounts": [ + "NT AUTHORITY\\SYSTEM", + "LOCALSYSTEM", + "NT AUTHORITY\\NETWORKSERVICE" + ], + "condition": [ + { "not": "@attr::service::SQLAgent" }, + { + "ine": [ + "@attr::service::SQLAgent.account", + "@localServiceAccount" + ], + "or": [ + { "not": "@is_clustered_server" }, + { "not": { + "iin": [ + "@attr::service::SQLAgent.account", + "@unsupportedAccounts" + ] + }} + ] + } + ], + "probes": [ "IsClusteredServer" ] +} +``` diff --git a/samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/AttrTarget.md b/samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/AttrTarget.md new file mode 100644 index 0000000000..88b6c13ada --- /dev/null +++ b/samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/AttrTarget.md @@ -0,0 +1,12 @@ +# attr::target:: variables + +[Automatic variables](./README.md) in **attr::target::** namespace include the data which matched the [target pattern](../Rule.md#target). + +| Variable name | Type | Description | +|-----------------------------|---------|-------------------| +| attr::target::version | version | Target SQL Server [version](../TargetPattern.md#version) | +| attr::target::platform | string | Target SQL Server host [platform](../TargetPattern.md#platform) (e.g. Windows, Linux) | +| attr:target::engine_edition | string | Target [engine edition](../TargetPattern.md#engineedition) | +| attr::target::server_name | string | Target [server name](../TargetPattern.md#servername) | +| attr::target::machine_type | string | Target [machine type](../TargetPattern.md#machinetype) | +| attr::target::urn | string | Target object URN | diff --git a/samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/README.md b/samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/README.md new file mode 100644 index 0000000000..cc8fc86cdb --- /dev/null +++ b/samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/README.md @@ -0,0 +1,8 @@ +# Automatic variables + +Data for assessment is delivered by probes. Some data is available before the first probe is invoked, e.g. target SQL Server version or requirements for probes. This data might be accessed via automatic variables. + +Automatic variables are grouped in namespaces. + +- [attr::service::](./AttrService.md) +- [attr::target::](./AttrTarget.md) \ No newline at end of file diff --git a/samples/manage/sql-assessment-api/docs/Customization/Probe.md b/samples/manage/sql-assessment-api/docs/Customization/Probe.md index 1f2b077af7..b55ae1a33f 100644 --- a/samples/manage/sql-assessment-api/docs/Customization/Probe.md +++ b/samples/manage/sql-assessment-api/docs/Customization/Probe.md @@ -22,6 +22,14 @@ The `implementation` property contains probe parameters and [data transformation Probe parameters are specific for [probe type](#type). +### requires + +Explicit functional [requirements](./ProbeRequirements/README.md) for this probe. SQL Assessment API checks if all the requirements are met. If not, the probe is not executed, all dependent checks are skipped, and a warning is returned. + +### runFor + +Explicit logical [requirements](./ProbeRequirements/README.md) for this probe. SQL Assessment API checks if all the requirements are met. If not, the probe implementation is not executed and an empty result set is returned immediately. + ### target Target object [pattern](TargetPattern.md). @@ -30,13 +38,13 @@ Target object [pattern](TargetPattern.md). Probe `type` determines the mechanism used to get data. it may be a T-SQL or a WMI. Available probe types are listed in the following table. -|Type|Description| -|---|---| -|[AzGraph](../Reference/Probes/AzGraphProbe.md)|Kusto query to Azure resource graph| -|[AzMetadata](../Reference/Probes/AzMetadataProbe.md)|JSONPath for the object returned by Azure Instance Metadata Service| -|[CMD](../Reference/Probes/CMDShellProbes.md)|Command shell script run on the target machine| -|[External](../Reference//Probes/ExternalProbe.md)|Arbitrary .NET code| -|[PowerShell](../Reference/Probes/PowerShellProbes.md)|PowerShell script| -|[Registry](../Reference/Probes/RegistryProbes.md)|Data from registry| -|[SQL](../Reference/Probes/TSQLProbes.md)|T-SQl query| -|[WMI](../Reference/Probes/WMIProbes.md)|WMI query| \ No newline at end of file +| Type | Description | +|-----------------------------------------------------|--------------------------| +|[AzGraph](../Reference/Probes/AzGraphProbe.md) | Kusto query to Azure resource graph | +|[AzMetadata](../Reference/Probes/AzMetadataProbe.md) | JSONPath for the object returned by Azure Instance Metadata Service | +|[CMD](../Reference/Probes/CMDShellProbes.md) | Command shell script run on the target machine | +|[External](../Reference/Probes/ExternalProbe.md) | Arbitrary .NET code | +|[PowerShell](../Reference/Probes/PowerShellProbes.md)| PowerShell script | +|[Registry](../Reference/Probes/RegistryProbes.md) | Data from registry | +|[SQL](../Reference/Probes/TSQLProbes.md) | T-SQl query | +|[WMI](../Reference/Probes/WMIProbes.md) | WMI query | diff --git a/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/FeatureRequirement.md b/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/FeatureRequirement.md new file mode 100644 index 0000000000..98a08b190b --- /dev/null +++ b/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/FeatureRequirement.md @@ -0,0 +1,23 @@ +# Feature requirement + +Feature requirement lists SQL Server features. + +## Name format + +__feature__ + +## Supported values + +__HADR__ - High Availability and Disaster Recovery ([Always On Availability Groups](https://learn.microsoft.com/sql/database-engine/availability-groups/windows/overview-of-always-on-availability-groups-sql-server)). + +## Examples + +```json +"runFor": { + "feature": [ "HADR" ] +} +``` + +## See also + +- [Probe requirements](./README.md) diff --git a/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/PermissionRequirement.md b/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/PermissionRequirement.md new file mode 100644 index 0000000000..e148434896 --- /dev/null +++ b/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/PermissionRequirement.md @@ -0,0 +1,48 @@ +# Permission requirement + +Permission requirements specify special permissions required by the probe. for more information see [sys.fn_my_permissions](https://learn.microsoft.com/sql/relational-databases/system-functions/sys-fn-my-permissions-transact-sql) + +## Name format + +*securable_class* __permission__ __\[__ __on__ *securable_name* __]__ + +*securable_class* is the name of the class of securable for which permissions are listed. *securable_class* is a sysname. Examples of *securable_class* are: DATABASE, OBJECT, REMOTE SERVICE BINDING, SERVER. + +*securable_name* is the name of the securable. If the securable is the server or a database, this part should be omitted. *securable_name* is a sysname. *securable_name* can be a multipart name. + +## Supported values + +Allowed values depend on securable class. See [SQL Server Permissions](https://learn.microsoft.com/sql/relational-databases/security/permissions-database-engine) and [SQL Server Permissions Hierarchy](https://learn.microsoft.com/sql/relational-databases/security/permissions-hierarchy-database-engine). + +## Examples + +```json +"requires": { + "server permission": [ + "ALTER TRACE" + ] +}, +``` + +```json +"requires": { + "object permission on [msdb].[dbo].[sysalerts]": [ + "SELECT" + ] +}, +``` + +```json +"requires": { + "object permission on [msdb].[dbo].[sysjobs]": [ + "SELECT" + ], + "object permission on [msdb].[dbo].[sysjobsteps]": [ + "SELECT" + ] +}, +``` + +## See also + +- [Probe requirements](./README.md) diff --git a/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/README.md b/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/README.md new file mode 100644 index 0000000000..0d9d4beff7 --- /dev/null +++ b/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/README.md @@ -0,0 +1,100 @@ +# Probe requirements + +Probe requirements help to deal with situations when a probe cannot get data due to insufficient permissions or configuration issues. SQL Assessment API can skip probes when their requirements were stated explicitly. + +By default any error in probe terminates assessment process immediately with an error message. This leads to incomplete results because not all checks have been run. For example, the following probe will generate an error and terminate assessment if current user does not have _sysadmin_ role. + +```json +"DBMetaInfo": [ + { + "type": "SQL", + "target": { "type": "Database" }, + "implementation": { + "query": "DBCC DBINFO(@TargetName) WITH TABLERESULTS,NO_INFOMSGS", + } + } +] +``` + +This requirement can be specified explicitly in the probe's __requires__ property. With this property SQL Assessment API will check if current user has _sysadmin_ role before running the query. If not, the query will not be run and all checks, that depend on this probe, will be skipped. The user will get a warning about this. + +```json +"DBMetaInfo": [ + { + "type": "SQL", + "target": { "type": "Database" }, + "implementation": { + "query": "DBCC DBINFO(@TargetName) WITH TABLERESULTS,NO_INFOMSGS", + }, + "requires": { + "role": [ "sysadmin" ] + } + } +] +``` + +In some scenarios there is no need for the warning. Let's take a probe which detects database mirroring endpoints with the following T-SQL query. + +```sql +SELECT + [name] AS endpoint_name, + is_encryption_enabled, + encryption_algorithm, + encryption_algorithm_desc +FROM + sys.database_mirroring_endpoints +``` + +This probe makes little sense when High Availability abd Disaster Recovery (HADR) is disabled. We can add a requirement for this probe to skip it in these cases. + +```json +"AGEndpoints": [ + { + "type": "SQL", + "target": { "type": "Server" }, + "implementation": { "query": " … " }, + "requires": { + "feature": [ "HADR" ] + } + } +] +``` + +With this implementation, the user will get a warning for each SQL Server instance not involved in HADR operations, which would be confusing. There is another probe propery named __runFor__ which specifies requirements in the same format as __requires__. The difference is the absence of the warning message. The probe does not run the query but return an empty set immediately. + +```json +"AGEndpoints": [ + { + "type": "SQL", + "target": { "type": "Server" }, + "implementation": { "query": " … " }, + "runFor": { + "feature": [ "HADR" ] + } + } +] +``` + +Each requirement is represented by a JSON property. The property name is the requirement name. The property value is a JSON array of strings representing required values. For example, the following probe requires _ALTER TABLE_ and _ADMINISTER BULK OPERATIONS_ server permissions. + +```json +"requires": { + "server permission": [ + "ALTER TABLE", + "ADMINISTER BULK OPERATIONS" + ] +} +``` + +## Requirement types + +SQL Assessment API supports a variety of requirement types. The are documented below. + +Each requirement type has specific name format. Fixed literal characters in the name format are __bold__. Variable parts of the name are _italic_. Optional parts are __\[__ enclosed in square brackets __\]__. + +Supported requirement types: + +- [role](./RoleRequirement.md) +- [permission](./PermissionRequirement.md) +- [feature](./FeatureRequirement.md) +- [service](./ServiceRequirement.md) diff --git a/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/RoleRequirement.md b/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/RoleRequirement.md new file mode 100644 index 0000000000..800e21d88c --- /dev/null +++ b/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/RoleRequirement.md @@ -0,0 +1,26 @@ +# Role requirement + +Specifies current user roles required for running this probe. + +## Name format + +__role__ + +## Supported values + +SQL Server role names. + +## Examples + +```json +"requires": { + "role": [ + "bulkadmin", + "diskadmin" + ] +} +``` + +## See also + +- [Probe requirements](./README.md) diff --git a/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/ServiceRequirement.md b/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/ServiceRequirement.md new file mode 100644 index 0000000000..d941edb30b --- /dev/null +++ b/samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/ServiceRequirement.md @@ -0,0 +1,37 @@ +# Service requirement + +Lists SQL Server services required for the probe. + +## Name format + +__service__ + +## Supported values + +**MSSQL** – SQL Server service + +**SQLAgent** – [SQL Server Agent service](https://learn.microsoft.com/sql/ssms/agent) + +**MSOLAP** – [SQL Server Analysis Services](https://learn.microsoft.com/analysis-services) + +**ReportServer** – [SQL Server Reporting Services](https://learn.microsoft.com/sql/reporting-services) + +**MsDtsServer** – [Integration Services](https://learn.microsoft.com/sql/integration-services) + +**MSSQLFDLauncher** – [Full-Text Filter daemon host launcher service](https://learn.microsoft.com/sql/tools/configuration-manager/sql-full-text-filter-daemon-launcher-sql-server-configuration-manager) + +**SQLBrowser** – [SQL Server Browser service](https://learn.microsoft.com/sql/tools/configuration-manager/sql-server-browser-service) + +## Examples + +```json +"runFor": { + "service": [ "ReportServer" ] +} +``` + +## See also + +- [attr::service:: variables](../AutomaticVariables/AttrService.md) +- [Probe requirements](./README.md) + diff --git a/samples/manage/sql-assessment-api/docs/Customization/Rule.md b/samples/manage/sql-assessment-api/docs/Customization/Rule.md index 6b5367db87..55cddeb9eb 100644 --- a/samples/manage/sql-assessment-api/docs/Customization/Rule.md +++ b/samples/manage/sql-assessment-api/docs/Customization/Rule.md @@ -48,7 +48,7 @@ Hyperlink to an article that explains the best practice recommendations and reme ### level -__Allowed values:__ `Information`, `Low`, `Medium`, 'High' +__Allowed values:__ `Information`, `Low`, `Medium`, `High` The severity level of the issue detected by this check. diff --git a/samples/manage/sql-assessment-api/docs/Customization/img/ProbeStructure.svg b/samples/manage/sql-assessment-api/docs/Customization/img/ProbeStructure.svg index 15e21e68df..c0c3119408 100644 --- a/samples/manage/sql-assessment-api/docs/Customization/img/ProbeStructure.svg +++ b/samples/manage/sql-assessment-api/docs/Customization/img/ProbeStructure.svg @@ -1,4 +1,4 @@ -typeProbe typetarget?   implementation   requires?CharacteristicsrunFor?CharacteristicstypeServer|DatabaseversionVersion pattern……probe_param_1Expressionprobe_param_2Expression……transform?Data transform