Edit

Authenticated scan methods and properties

  • Article

Applies to:

Want to experience Microsoft Defender for Endpoint? Sign up for a free trial.

Want to experience Microsoft Defender Vulnerability Management? Learn more about how you can sign up to the Microsoft Defender Vulnerability Management public preview trial.

Important

Some information in this article relates to a prereleased product which may be substantially modified before it's commercially released. Microsoft makes no warranties, expressed or implied, with respect to the information provided here.

Note

If you are a US Government customer, please use the URIs listed in Microsoft Defender for Endpoint for US Government customers.

Tip

For better performance, you can use server closer to your geo location:

  • us.api.security.microsoft.com
  • eu.api.security.microsoft.com
  • uk.api.security.microsoft.com
  • au.api.security.microsoft.com
  • swa.api.security.microsoft.com

Methods

Method Description
Get all scan definitions List all scan definitions.
Add, delete, or update a scan definition Add, delete, or update a new scan definition.
Get all scan agents List all scan agents.
Get scan agent by ID Retrieves the details for a specified agent by its ID.
Get scan history by definition List scan definition history.
Get scan history by session List scan history for a session.

Learn more about Windows authenticated scan and Network authenticated scans.

Properties

Property Data type Description
id String Scan ID.
scanType Enum The type of scan. Possible values are: Windows, Network.
scanName String Name of the scan.
isActive Boolean Status of whether the scan actively running.
orgId String Related organization ID.
intervalInHours Int The interval at which the scan runs.
createdBy String Unique identity of the user that created the scan.
targetType String The target type in the target field. Possible types are IP Address or Hostname. Default value is IP Address.
target String A comma separated list of targets to scan, either IP addresses or hostnames.
scanAuthenticationParams Object An object representing the authentication parameters, see Authentication parameters object properties for expected fields. This property is mandatory when creating a new scan and is optional when updating a scan.
scannerAgent Object An object representing the scanner agent, contains the machine Id of the scanning device.

Authentication parameters object properties

Property Data type Description
@odata.type Enum The scan type authentication parameters. Possible values are: #microsoft.windowsDefenderATP.api.SnmpAuthParams for Network scan type, and #microsoft.windowsDefenderATP.api.WindowsAuthParams for Windows scan type.
type Enum The authentication method. Possible values vary based on @odata.type property.
- If @odata.type is SnmpAuthParams, possible values are CommunityString, NoAuthNoPriv, AuthNoPriv, AuthPriv.
- If @odata.type is WindowsAuthParams possible values are Kerberos or Negotiate.
KeyVaultUrl String (Optional) An optional property that specifies from which KeyVault the scanner should retrieve credentials. If KeyVault is specified there's no need to specify username, password.
KeyVaultSecretName String (Optional) An optional property that specifies KeyVault secret name from which the scanner should retrieve credentials. If KeyVault is specified there's no need to specify username, password.
Domain String (Optional) Domain name when using WindowsAuthParams.
Username String (Optional) Username when using WindowsAuthParams or the username when choosing SnmpAuthParams with any type other than CommunityString.
IsGMSAUser Boolean (Optional) Must be set to true when choosing WindowsAuthParams.
CommunityString String (Optional) Community string to use when choosing SnmpAuthParams with CommunityString
AuthProtocol String (Optional) Auth protocol to use with SnmpAuthParams and AuthNoPriv or AuthPriv. Possible values are MD5, SHA1.
AuthPassword String (Optional) Auth password to use with SnmpAuthParams and AuthNoPriv or AuthPriv.
PrivProtocol String (Optional) Priv protocol to use with SnmpAuthParams and AuthPriv. Possible values are DES, 3DES, AES.
PrivPassword String (Optional) Priv password to use with SnmpAuthParams and AuthPriv.

Tip

Do you want to learn more? Engage with the Microsoft Security community in our Tech Community: Microsoft Defender for Endpoint Tech Community.