Log in with the API

Before you send requests with the API to your server, you must log in.

Note

Ensure you are using the TLS 1.2 security protocol on your machine before sending an authentication request.

When you send a request to log in, your Cybereason server returns a session cookie, which is stored on your machine. You can then reference the cookie in subsequent requests.

All cookies are valid for an 8 hour period.

The cookie uses the format of a JSESSIONID:

JESSIONID: 6540146A88QP0F1F82537012D9C565AC

For details on password requirements for the Cybereason platform when sending an authentication request, see Select the password complexity.

Send an authentication request

Follow the steps to log in (depending on the framework you use):

cURL

When you log in with cURL, you have the option of providing your credentials in a separate file or including the credentials in the command.

In a command window, enter one of the following commands:

1. If you add your credentials in a separate file:

   curl -X POST https://[hostname]:[port]/login.html -d @authentication.txt --header "Content-Type:application/x-www-form-urlencoded" -c cookie.txt
   

   In the separate file (login.txt in this example) add your credentials in the format username=<username>&password=<my password>. The username parameter uses the %40 encoding in place of the @ character.

   For example, you can use this for authentication: username=admin%40myserver.com&password=3GYvP9ADQWak.

2. If you enter your credentials directly in the command:

   curl -X POST https://[hostname]:[port]/login.html -d "username=<username>&password=<my password>" --header "Content-Type:application/x-www-form-urlencoded" -c cookie.txt
   

   In this command:

   • The [hostname]:[port] parameter is the address to your Cybereason server.

   • The username parameter uses the %40 encoding in place of the @ character.

   • The cookie.txt contains the authentication cookie for access. Your machine stores the cookie in the root folder where you opened the command window.

REST API Client

1. In your client, create a new request for authentication and save it with a descriptive name.

   1. Set the request method to POST.

   2. Enter the URL for your server in the format https://[hostname]:[port]/login.html.

   3. Set the header value to Content-Type with the value application/x-www-form-urlencoded.

   4. In the request body, create a key for username and password. Enter your username and password as the values for these keys.

   5. Send the request in your client.

   Cybereason returns a cookie stored in your client for the rest of your session.

Python

1. Ensure that Python version 2.7 or higher is installed on your system.

2. Install the requests library using this command:

   pip install requests
   

3. Create your own Python script with this content:

   import requests
   
   username = "<your user name>"
   password = "<password>"
   server = "<server URL>"
   port = "443"
   
   data = {
       "username": username,
       "password": password
   }
   headers = {"Content-Type": "application/x-www-form-urlencoded"}
   
   base_url = "https://" + server + ":" + port
   login_url = base_url + "/login.html"
   
   session = requests.session()
   response = session.post(login_url, data=data, headers=headers, verify=True)
   
   print response.status_code
   print session.cookies.items()
   

The variables in this script include:

Variable	Type	Description
server	String	The base URL for your server. Enter the URL without the https:// prefix.
username	String	Your Cybereason user name.
password	String	The password for your Cybereason user name.
port	Integer	The port used for your Cybereason server.

Note

The final two print lines in the above script are not required for authentication but confirm that you have been authenticated successfully.

Authentication text syntax file

Authentication Python script

Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.

Use the cookie in other requests

Depending on how you send a request, you specify the cookie differently.

cURL

Because cURL requests return the cookie in a file, you specify the cookie file as part of the command:

curl -X POST https://[hostname]:[port]/login.html -d @login.txt --header "ContentType:application/x-www-form-urlencoded" -c cookie.txt

REST API Client

When you use a REST API client, the cookie is often returned as part of the response and displayed in a separate tab. For example, in the Postman API client, you can find the cookie details in the response:

Then, you can reference the cookie in each request if needed. For example, in Postman, you can select from any of the saved cookies:

However, this may not be necessary as your API client may store the cookie until it expires.

Python

As part of the Python authentication script, you specify details on the URL and credentials to use. In addition, you create a session object that returns the details on the session.

You can include this authentication code at the top of each request script, and the cookie is automatically applied to the request.

At the end of the Python code for authentication there is code to create a session object that contains the cookie:

session = requests.session()
response = session.post(login_url, data=data, verify=True)

print response.status_code
print session.cookies.items()

Then later in the Python script, the code for the request, you reference the session object. This example is taken from our reference examples where we create a special variable to hold the response data:

response = session.request("POST", url, data=<variable>, headers=headers)

This ensures you use the current session cookie.

Log out from your machine

If you want, you can also logout from the machine. Follow the steps to log out (depending on the framework you use):

cURL

In a command window, enter one of the following commands:

curl -X GET https://[hostname]:[port]/logout -c cookie.txt

REST API Client

1. In your client, create a new request for authentication and save it with a descriptive name.

2. Set the request method to GET.

3. Enter the URL for your server in the format https://[hostname]:[port]/logout.

4. Send the request in your client.

If your request is successful, the Cybereason platform returns an HTTP 200 status code and returns the HTML code for the login page in the response.

Python

Create your own Python script with this content:

import requests

base_url = "https://" + server + ":" + port
logout_url = base_url + "/logout"

session = requests.session()
response = session.get(logout_url, verify=True)

print response.status_code
print(response.content)

Note

The final two lines in the above script are not required, but confirm that you have logged out of your platform successfully. If your request is successful, the Cybereason platform returns an HTTP 200 status code and returns the HTML code for the login page in the response.

Authentication Python script

Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.