Set Up to Use Bash or PowerShell

Set up your environment to use Bash (cURL) or PowerShell to send HTTP requests to Deep Security Manager using the API.

Note:

Complete this recipe before performing any other cookbook recipes.

Bash or PowerShell?

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

Check that you can access Deep Security Manager 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 Deep Security Manager uses for securing HTTPS connections.

What to check

Description

Connection to Deep Security Manager
Use your Web browser to navigate to the URL of your instance of Deep Security Manager (for example, url=https://192.168.1.100:4119or url=https://example.com:4119):
  • If the manager 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

cURL software (for Bash)

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 cURL7.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.

PowerShell software

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

  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")

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

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:
Store the key secret in a secure manner and do not share it.

This procedure creates a key with all permissions. Use a different role to limit access to certain API capabilities.

  1. Log into Deep Security Manager in your Web browser and click Administration > User Management > API Keys. If you do not see the API Keys section, talk to your Deep Security administrator about obtaining the required user permissions.
  2. Click New and enter the following property values:
    • Name: Cookbook API key
    • Role: Full Access
  3. Click Next. The key secret is presented. This is the only time that you can obtain the secret.
  4. Copy the secret and securely store it.
  5. Click Close.

Test your setup

CLI type

Description

Bash

  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 your Deep Security Manager, and <YOUR SECRET KEY> with the secret from your API key:

    • url=<YOUR URL>

      for example, url=https://192.168.1.100:4119 or url=https://example.com:4119

    • 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" -k -s -w "\n\nresponse code: %{response_code}\n"

    The -k option is necessary only when your Deep Security Manager uses a self-signed certificate to establish TLS connections (which is not suitable for production environments).

  4. If the response ends with response code: 200, your call was successful and your setup is validated.

PowerShell

  1. Open PowerShell.

  2. Enter the following command if your Deep Security Manager uses a self-signed certificate to establish TLS connections (which is not suitable for production environments):

    [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { False }

  3. Enter the following command to use TLS 1.2:

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

  4. Enter the following commands to store details about your request, replacing <YOUR URL> with the URL of your Deep Security Manager, and <YOUR SECRET KEY> with the secret from your API key:

    • $url = "<YOUR URL>"

      for example, url=https://192.168.1.100:4119 or url=https://example.com:4119

    • $secret = "<YOUR API KEY SECRET>"

      for example, $secret="5C58EADA-04BC-4ABC-45CF-B72725A0B674:aFBgpPV8eJQGaY2Dk0LmyQMD7nUGvyIDfIbIQo8Zgm8="

    • $headers = @{'api-version' = "v1"; 'api-secret-key' = $secret}

  5. Enter the following command to send the request:

    Invoke-WebRequest "$url/api/apikeys" -Headers $headers

  6. If the response that appears includesStatusCode : 200, your call was successful and your setup is validated.

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.

Final comments

After you have successfully sent a request to Deep Security Manager to validate your setup, you are ready to use the other cookbook recipes.

Related resources