Skip to content

Commit c9b0d7c

Browse files
aguzevaguzev
committed
Add docs for SQL Assessment API probe requirements
1 parent c98809a commit c9b0d7c

22 files changed

Lines changed: 420 additions & 92 deletions

‎samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/AttrService.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# attr::service:: variables
2+
3+
[Automatic variables](./README.md) in the **attr::service::* namespace are provided with [Service requirements](../ProbeRequirements/ServiceRequirement.md).
4+
5+
The following variables are available for each service. Service key is a value from [Service requirement supported values](../ProbeRequirements/ServiceRequirement.md#supported-values).
6+
7+
| Variable name | Type | Description |
8+
|------------------------------|--------|--------------------------------------|
9+
| attr::service::_key_ | bool | Inidicates if the service is present |
10+
| attr::service::_key_.name | string | Actual service name |
11+
| attr::service::_key_.account | string | User account name for this service |
12+
13+
## Examples
14+
15+
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).
16+
17+
```json
18+
{
19+
…
20+
"message": "Account '@{attr::service::SQLAgent.account}' is not supported for 'SQL Server Agent' service.",
21+
"localServiceAccount": "NT AUTHORITY\\LOCALSERVICE",
22+
"condition": [
23+
{ "not": "@attr::service::SQLAgent" },
24+
{ "ine": [
25+
"@attr::service::SQLAgent.account",
26+
"@localServiceAccount"
27+
]}
28+
],
29+
"probes": [ "IsClusteredServer" ]
30+
}
31+
```
32+
33+
The next example extends the previous check with support for clustered servers. When the server is clustered, three more accounts are not supported.
34+
35+
```json
36+
{
37+
…
38+
"message": "Account '@{attr::service::SQLAgent.account}' is not supported for 'SQL Server Agent' service.",
39+
"localServiceAccount": "NT AUTHORITY\\LOCALSERVICE",
40+
"unsupportedAccounts": [
41+
"NT AUTHORITY\\SYSTEM",
42+
"LOCALSYSTEM",
43+
"NT AUTHORITY\\NETWORKSERVICE"
44+
],
45+
"condition": [
46+
{ "not": "@attr::service::SQLAgent" },
47+
{
48+
"ine": [
49+
"@attr::service::SQLAgent.account",
50+
"@localServiceAccount"
51+
],
52+
"or": [
53+
{ "not": "@is_clustered_server" },
54+
{ "not": {
55+
"iin": [
56+
"@attr::service::SQLAgent.account",
57+
"@unsupportedAccounts"
58+
]
59+
}}
60+
]
61+
}
62+
],
63+
"probes": [ "IsClusteredServer" ]
64+
}
65+
```

‎samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/AttrTarget.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# attr::target:: variables
2+
3+
[Automatic variables](./README.md) in **attr::target::** namespace include the data which matched the [target pattern](../Rule.md#target).
4+
5+
| Variable name | Type | Description |
6+
|-----------------------------|---------|-------------------|
7+
| attr::target::version | version | Target SQL Server [version](../TargetPattern.md#version) |
8+
| attr::target::platform | string | Target SQL Server host [platform](../TargetPattern.md#platform) (e.g. Windows, Linux) |
9+
| attr:target::engine_edition | string | Target [engine edition](../TargetPattern.md#engineedition) |
10+
| attr::target::server_name | string | Target [server name](../TargetPattern.md#servername) |
11+
| attr::target::machine_type | string | Target [machine type](../TargetPattern.md#machinetype) |
12+
| attr::target::urn | string | Target object URN |

‎samples/manage/sql-assessment-api/docs/Customization/AutomaticVariables/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Automatic variables
2+
3+
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.
4+
5+
Automatic variables are grouped in namespaces.
6+
7+
- [attr::service::](./AttrService.md)
8+
- [attr::target::](./AttrTarget.md)

‎samples/manage/sql-assessment-api/docs/Customization/Probe.md‎

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,14 @@ The `implementation` property contains probe parameters and [data transformation
2222

2323
Probe parameters are specific for [probe type](#type).
2424

25+
### requires
26+
27+
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.
28+
29+
### runFor
30+
31+
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.
32+
2533
### target
2634

2735
Target object [pattern](TargetPattern.md).
@@ -30,13 +38,13 @@ Target object [pattern](TargetPattern.md).
3038

3139
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.
3240

33-
|Type|Description|
34-
|---|---|
35-
|[AzGraph](../Reference/Probes/AzGraphProbe.md)|Kusto query to Azure resource graph|
36-
|[AzMetadata](../Reference/Probes/AzMetadataProbe.md)|JSONPath for the object returned by Azure Instance Metadata Service|
37-
|[CMD](../Reference/Probes/CMDShellProbes.md)|Command shell script run on the target machine|
38-
|[External](../Reference//Probes/ExternalProbe.md)|Arbitrary .NET code|
39-
|[PowerShell](../Reference/Probes/PowerShellProbes.md)|PowerShell script|
40-
|[Registry](../Reference/Probes/RegistryProbes.md)|Data from registry|
41-
|[SQL](../Reference/Probes/TSQLProbes.md)|T-SQl query|
42-
|[WMI](../Reference/Probes/WMIProbes.md)|WMI query|
41+
| Type | Description |
42+
|-----------------------------------------------------|--------------------------|
43+
|[AzGraph](../Reference/Probes/AzGraphProbe.md) | Kusto query to Azure resource graph |
44+
|[AzMetadata](../Reference/Probes/AzMetadataProbe.md) | JSONPath for the object returned by Azure Instance Metadata Service |
45+
|[CMD](../Reference/Probes/CMDShellProbes.md) | Command shell script run on the target machine |
46+
|[External](../Reference/Probes/ExternalProbe.md) | Arbitrary .NET code |
47+
|[PowerShell](../Reference/Probes/PowerShellProbes.md)| PowerShell script |
48+
|[Registry](../Reference/Probes/RegistryProbes.md) | Data from registry |
49+
|[SQL](../Reference/Probes/TSQLProbes.md) | T-SQl query |
50+
|[WMI](../Reference/Probes/WMIProbes.md) | WMI query |

‎samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/FeatureRequirement.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Feature requirement
2+
3+
Feature requirement lists SQL Server features.
4+
5+
## Name format
6+
7+
__feature__
8+
9+
## Supported values
10+
11+
__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)).
12+
13+
## Examples
14+
15+
```json
16+
"runFor": {
17+
"feature": [ "HADR" ]
18+
}
19+
```
20+
21+
## See also
22+
23+
- [Probe requirements](./README.md)

‎samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/PermissionRequirement.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Permission requirement
2+
3+
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)
4+
5+
## Name format
6+
7+
*securable_class* __permission__ __\[__ __on__ *securable_name* __]__
8+
9+
*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.
10+
11+
*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.
12+
13+
## Supported values
14+
15+
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).
16+
17+
## Examples
18+
19+
```json
20+
"requires": {
21+
"server permission": [
22+
"ALTER TRACE"
23+
]
24+
},
25+
```
26+
27+
```json
28+
"requires": {
29+
"object permission on [msdb].[dbo].[sysalerts]": [
30+
"SELECT"
31+
]
32+
},
33+
```
34+
35+
```json
36+
"requires": {
37+
"object permission on [msdb].[dbo].[sysjobs]": [
38+
"SELECT"
39+
],
40+
"object permission on [msdb].[dbo].[sysjobsteps]": [
41+
"SELECT"
42+
]
43+
},
44+
```
45+
46+
## See also
47+
48+
- [Probe requirements](./README.md)

‎samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/README.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Probe requirements
2+
3+
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.
4+
5+
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.
6+
7+
```json
8+
"DBMetaInfo": [
9+
{
10+
"type": "SQL",
11+
"target": { "type": "Database" },
12+
"implementation": {
13+
"query": "DBCC DBINFO(@TargetName) WITH TABLERESULTS,NO_INFOMSGS",
14+
}
15+
}
16+
]
17+
```
18+
19+
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.
20+
21+
```json
22+
"DBMetaInfo": [
23+
{
24+
"type": "SQL",
25+
"target": { "type": "Database" },
26+
"implementation": {
27+
"query": "DBCC DBINFO(@TargetName) WITH TABLERESULTS,NO_INFOMSGS",
28+
},
29+
"requires": {
30+
"role": [ "sysadmin" ]
31+
}
32+
}
33+
]
34+
```
35+
36+
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.
37+
38+
```sql
39+
SELECT
40+
[name] AS endpoint_name,
41+
is_encryption_enabled,
42+
encryption_algorithm,
43+
encryption_algorithm_desc
44+
FROM
45+
sys.database_mirroring_endpoints
46+
```
47+
48+
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.
49+
50+
```json
51+
"AGEndpoints": [
52+
{
53+
"type": "SQL",
54+
"target": { "type": "Server" },
55+
"implementation": { "query": " … " },
56+
"requires": {
57+
"feature": [ "HADR" ]
58+
}
59+
}
60+
]
61+
```
62+
63+
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.
64+
65+
```json
66+
"AGEndpoints": [
67+
{
68+
"type": "SQL",
69+
"target": { "type": "Server" },
70+
"implementation": { "query": " … " },
71+
"runFor": {
72+
"feature": [ "HADR" ]
73+
}
74+
}
75+
]
76+
```
77+
78+
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.
79+
80+
```json
81+
"requires": {
82+
"server permission": [
83+
"ALTER TABLE",
84+
"ADMINISTER BULK OPERATIONS"
85+
]
86+
}
87+
```
88+
89+
## Requirement types
90+
91+
SQL Assessment API supports a variety of requirement types. The are documented below.
92+
93+
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 __\]__.
94+
95+
Supported requirement types:
96+
97+
- [role](./RoleRequirement.md)
98+
- [permission](./PermissionRequirement.md)
99+
- [feature](./FeatureRequirement.md)
100+
- [service](./ServiceRequirement.md)

‎samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/RoleRequirement.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Role requirement
2+
3+
Specifies current user roles required for running this probe.
4+
5+
## Name format
6+
7+
__role__
8+
9+
## Supported values
10+
11+
SQL Server role names.
12+
13+
## Examples
14+
15+
```json
16+
"requires": {
17+
"role": [
18+
"bulkadmin",
19+
"diskadmin"
20+
]
21+
}
22+
```
23+
24+
## See also
25+
26+
- [Probe requirements](./README.md)

‎samples/manage/sql-assessment-api/docs/Customization/ProbeRequirements/ServiceRequirement.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
# Service requirement
2+
3+
Lists SQL Server services required for the probe.
4+
5+
## Name format
6+
7+
__service__
8+
9+
## Supported values
10+
11+
**MSSQL** – SQL Server service
12+
13+
**SQLAgent** – [SQL Server Agent service](https://learn.microsoft.com/sql/ssms/agent)
14+
15+
**MSOLAP** – [SQL Server Analysis Services](https://learn.microsoft.com/analysis-services)
16+
17+
**ReportServer** – [SQL Server Reporting Services](https://learn.microsoft.com/sql/reporting-services)
18+
19+
**MsDtsServer** – [Integration Services](https://learn.microsoft.com/sql/integration-services)
20+
21+
**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)
22+
23+
**SQLBrowser** – [SQL Server Browser service](https://learn.microsoft.com/sql/tools/configuration-manager/sql-server-browser-service)
24+
25+
## Examples
26+
27+
```json
28+
"runFor": {
29+
"service": [ "ReportServer" ]
30+
}
31+
```
32+
33+
## See also
34+
35+
- [attr::service:: variables](../AutomaticVariables/AttrService.md)
36+
- [Probe requirements](./README.md)
37+

‎samples/manage/sql-assessment-api/docs/Customization/Rule.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ Hyperlink to an article that explains the best practice recommendations and reme
4848

4949
### level
5050

51-
__Allowed values:__ `Information`, `Low`, `Medium`, 'High'
51+
__Allowed values:__ `Information`, `Low`, `Medium`, `High`
5252

5353
The severity level of the issue detected by this check.
5454

0 commit comments

Comments
 (0)