Endpoint Protection 14 REST API and PowerShell

Products

• Endpoint Protection

Issue/Introduction

Familiarize how to PowerShell with the new Symantec Endpoint Protection (SEP) 14 Representational StateTransfer (REST) API.

Environment

On-Prem SEP 14.x

Resolution

The purpose of this article is to familiarize yourself with PowerShell. Also to familiarize how to PowerShell with the new Symantec Endpoint Protection (SEP) 14 Representational State Transfer (REST) API. The example scripts are designed to show you examples of how to use the API functions, and what you need to invoke a REST method request call in PowerShell. You can also use these scripts for troubleshooting purposes.

If you download the example scripts, please note that you must replace SEPM_IP in the "URI" section of the scripts with your own SEP Manager IP address or hostname. You must also add a valid username and password to the SEPM_Authentication-test.ps1 script before it returns a valid access token. Finally, you must update the access token in each script before running them.

Note: These scripts are meant for testing purposes only and are not supported by Symantec.

Please read Symantec Endpoint Protection Manager 14 REST API Reference when referencing the attached scripts.

Before you begin:

PowerShell must be at least version 3.0 to use the Invoke-RestMethod.

The "get-host" cmdlet verifies the version of PowerShell.

The "get-help Invoke-RestMethod" cmdlet, if it exists (it is not in versions before 3.0), shows command info.

PowerShell execution policy

The default policy is Restricted and can be enforced by your group policy. You must set the execution policy before you can run scripts. The RemoteSigned policy is best for single-system testing.

All PowerShell execution policies:

• Restricted - No scripts can be run. Windows PowerShell can be used only in interactive mode.
• AllSigned - Only scripts that are signed by a trusted publisher can be run.
• RemoteSigned - Downloaded scripts must be signed by a trusted publisher before they can be run.
• Unrestricted - No restrictions; all Windows PowerShell scripts can be run.

The "Get-ExecutionPolicy" cmdlet shows the current PowerShell execution policy.

The "Set-ExecutionPolicy" cmdlet changes the PowerShell execution policy.

Force PowerShell to use TLS 1.2

By default, PowerShell uses TLS 1.0. Because SEP uses TLS 1.2, you will receive a connection error message if you do not change this behavior. To force PowerShell to use TLS 1.2, add the following line to your script:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12;

Install the SEPM Certificate

In these scripts, PowerShell makes HTTPS requests, so it must have a valid certificate to use for that process.

To download and install the SEPM certificate, first connect your web browser to http://[SEPM_IP]:9090 (where [SEPM_IP] is the address of your SEPM server). Next, install the certificate on the computer from which you will run your PowerShell scripts. Then add the following line to your script to trust self-signed certificates:

[System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $True }

NOTE: If you use a third-party certificate, this line is only required if your certificate cannot be verified.

API function: PATCH /api/v1/computers

Currently, the "Request: PATCH /api/v1/computers" function description is incomplete in the current SEPM documentation. It lacks the following information:

API: moveClients

Request: PATCH /api/v1/computers

Description: Checks and moves a client to the specified group.

Example JSON payload to move multiple clients to a specified group:

[
    {
        "group": {
            "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
        "hardwareKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    {
        "group": {
            "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
        "hardwareKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    },
    {
        "group": {
            "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
        },
        "hardwareKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
    }
]

This JSON example can be used for moving multiple clients, each separated by a comma within the array. Note that the final element in the array does not end with a comma, nor is a comma necessary when moving only a single client. Multiple clients going to the same group must have the same group "id" defined, as illustrated in the example.

*The Move_Client_test.ps1 and the clients.json files in the attached PowerShell zip file has a functional example*

 

API function: DELETE /api/v1/computers/{ID.EN_US}

Currently, the "Request: DELETE /api/v1/computers/{ID.EN_US}" Parameter table states to use the ID of the computer you want to delete. To clarify, you will need the computer ID of the computer you want to delete. The computer ID is located in the SEM_COMPUTER table in the SEP DB. Replace {ID.EN_US} at the end of the URI with the actual "computer ID" to delete.

Request: DELETE /api/v1/computers/{ID.EN_US}

Description: Deletes an existing computer

*The Delete_client_test.ps1 script in the attached PowerShell zip file has a functional example*

References and Additional Information:

• MS REST API PowerShell reference  Invoke-RestMethod:
  https://msdn.microsoft.com/en-us/powershell/reference/5.1/microsoft.powershell.utility/invoke-restmethod
• Using the Set-ExecutionPolicy Cmdlet:
  https://technet.microsoft.com/en-us/library/ee176961.aspx
• Symantec Endpoint Protection Manager 14 REST API Reference:
  https://apidocs.securitycloud.symantec.com/#
• JSON - Introduction (JavaScript Object Notation):
  https://www.w3schools.com/js/js_json_intro.asp
• Scripting with Windows PowerShell:
  https://learn.microsoft.com/en-us/training/modules/script-with-powershell/