Views:
Set up your environment to use Bash (cURL) or PowerShell to send HTTP requests to Server & Workload Protection using the API.
Note
Note
Complete this recipe before performing any other cookbook recipes.

Bash or PowerShell? Parent topic

If you are new to scripting you might not be familiar with these tools, which is fine. Your operating system determines which one you'll be using:
  • Windows: PowerShell
  • Mac or Linux: Bash
If you're on Windows you can ignore the information about Bash (and cURL). Conversely, if you'll be using Bash you can ignore all the PowerShell information.

Check your environment Parent topic

Check that you can access Server & Workload Protection and that you have the required software installed. You will check the version of your software to make sure it supports TLS 1.2 which Server & Workload Protection uses for securing HTTPS connections.

Check your connection to Server & Workload Protection Parent topic

Use your Web browser to navigate to Server & Workload Protection https://cloudone.trendmicro.com:
  • If the page opens then you have the required network access
  • If you cannot open the page, check that you have a network connection and that your URL is correct

Check your cURL software (for Bash) Parent topic

If you want to use Bash (typically Linux or Mac users), check the version of cURL and OpenSSL or NSS or LibreSSL that are installed. Open Terminal or your preferred command line tool and enter the following command:
curl --version
  • Make sure you have cURL 7.34.0 or later
  • Locate one of the following libraries in the output:
    • OpenSSL 1.01 or later (1.02 recommended)
    • Network Security Services (NSS) 3.15.1 or later
    • LibreSSL 2.1.4 or later
    • A different library that secures network communications and supports TLS 1.2
If any of the required software is not installed or is too old, refer to your operating system's documentation for information about installing or upgrading it.

Check your PowerShell software Parent topic

If you want to use PowerShell (Windows), check the version of PowerShell and .NET Framework that is installed.

Procedure

  1. To check that your version of PowerShell is 3.0 or later, open PowerShell, enter the following command, and check that the value of PSVersion is 3.0 or higher:
    $psversiontable
  2. To check that your version of .NET Framework is 4.5 or later, enter the following command that returns the version from the registry:
    (Get-Childitem 'HKLM:\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full').GetValue("Version")

What to do next

If PowerShell or .NET Framework is not installed or is too old, refer to your Windows documentation for information about installing or upgrading it.

Create an API key Parent topic

Create an API key for authenticating your API calls. When you create the key, a key secret is presented that you must store for later use.
Note
Note
Store the key secret in a secure manner and do not share it.
If you're not sure whether you're using a new account or a legacy account, see Changes to Trend Micro Cloud One accounts.

Test your setup Parent topic

Bash Parent topic

Procedure

  1. Open Terminal or your preferred command line tool.
  2. Enter the following commands to store details about your request, replacing <YOUR URL> with the URL of yServer & Workload Protection, and <YOUR SECRET KEY> with the secret from your API key:
    • url=<YOUR URL>
      for example, url=https://cloudone.trendmicro.com
    • secret=<YOUR SECRET KEY>
      for example, secret=5C58EADA-04BC-4ABC-45CF-B72925A0B674:aFBgpPV8eJQGaY2Dk0LmyQMD7nUGvyIDfIbIQo8Zgm8=
  3. Enter the following command to send the request:
    curl -X GET $url/api/apikeys -H "api-secret-key: $secret" -H "api-version: v1" -s -w "\n\nresponse code: %{response_code}\n"
  4. If the response ends with response code: 200, your call was successful and your setup is validated.

What to do next

PowerShell Parent topic

Procedure

  1. Open PowerShell.
  2. Enter the following command to use TLS 1.2:
    [Net.ServicePointManager]::SecurityProtocol += [Net.SecurityProtocolType]::Tls12
  3. Enter the following commands to store details about your request, replacing <YOUR URL> with the URL of Server & Workload Protection, and <YOUR SECRET KEY> with the secret from your API key:
    • $url = "_<YOUR URL>_" for example, url=https://cloudone.trendmicro.com
    • $secret = "_<YOUR API KEY SECRET>_" for example, $secret="5C58EADA-04BC-4ABC-45CF-B72725A0B674:aFBgpPV8eJQGaY2Dk0LmyQMD7nUGvyIDfIbIQo8Zgm8="
    • $headers = @{'api-version' = "v1"; 'api-secret-key' = $secret}
  4. Enter the following command to send the request: Invoke-WebRequest "$url/api/apikeys" -Headers $headers
  5. If the response that appears includes StatusCode : 200, your call was successful and your setup is validated.
    Tip
    Tip
    If you receive the error message The underlying connection was closed: An unexpected error occurred on a send, close PowerShell, open PowerShell again, and try repeating the test.

What to do next

Final comments Parent topic

After you have successfully sent a request to Server & Workload Protection to validate your setup, you are ready to use the other cookbook recipes.

Related resources Parent topic