API examples

Overview

Here are some example API operations. This is current as of Cydarm 0.8.27.

Interaction with the API requires an authenticated session. This can be done using a regular user account, or via a service account. For production use it is recommended to create a service account. Note that you cannot use an SSO account.

Start a session (login) and create an API key

To start a session, username and password need to be base64 encoded and put into a JSON payload, and posted to /cydarm-api/auth/password. On successful auth, a response will be returned with a JWT authorisation (authz) token in the header Access-Token. This access token header needs to be included with all other requests. As the authz token is a long string, we represent it as "eyJhbGci..." or $bearerToken from here on in.

If authentication is successful, a HTTP 200 response code will be issued. If the password is incorrect, a 401 Unauthorized will be returned. Other response codes may indicate a malformed payload.

Shell script:

encUserName=$(echo -n username | base64)
encPassword=$(echo -n password | base64)
bearerToken=$(curl -i -k  https://stackname.cydarm.com/cydarm-api/auth/password -d '{"username":"'$encUserName'", "password":"'$encPassword'"}'  | grep -i -E 'Access-Token: ' | cut -d ' ' -f 2- )

Python:

import requests

baseUrl="https://stackname.cydarm.com"

def authenticate(fuser, fpass):
    "authenticate to get an auth token, to use in subsequent API interactions in the X-Cydarm-Authz header"

    params = dict(
        username=str(base64.b64encode(fuser.encode('utf-8')), 'utf-8'),
        password=str(base64.b64encode(fpass.encode('utf-8')), 'utf-8')
    )

    authUrl='%s/cydarm-api/auth/password' % baseUrl
    logging.info("Authenticating to: {}".format(authUrl))

    result = requests.post(authUrl, json=params)

    if(result.status_code != 200):
        bearerToken=-1
        logging.error("Error. HTTP response: {}".format(result.status_code))
        logging.error("headers: {}".format(result.headers))
    else:
        logging.info("Success. HTTP response: {}".format(result.status_code))
        logging.info("headers: {}".format(result.headers))
        bearerToken=result.headers['Access-Token']
    return bearerToken

PowerShell:

$un="<username>"
$pw="<password>"
$baseUrl="https://<stackname>.cydarm.com"

function authenticate {
    param(
        $username,
        $password,
        $url
    )
    $cydarmAuthEndpoint = $baseUrl + "/cydarm-api/auth/password"
    $cydarmAuthTokenPostParams = @{
        username=[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($un))
        password=[System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes($pw))
    } | ConvertTo-Json
    $cydarmAuthRes = Invoke-WebRequest -Uri $cydarmAuthEndpoint -ContentType "application/json" -Method Post -Body $cydarmAuthTokenPostParams
    return $cydarmAccessToken=$cydarmAuthRes.Headers."Access-Token"
}
$bearertoken = authenticate -username $un -password $pw -url $cydarmURL

End a session (logout)

This operation requires extracting the session UUID from the authz token, which can be done as follows:

echo $bearerToken | cut -d '.' -f 2 | sed -e 's/$/===/g' | base64 -D | jq .jti | tr -d '"'

Now we can logout using the session UUID:

curl -i -k -H "x-cydarm-authz: eyJhbGci..."  https://stackname.cydarm.com/cydarm-api/auth/session/62d83efa-3a0e-4a45-b8dc-5412c151fd4e -X DELETE

Create a case

curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case -d "{\"description\":\"name of new case\"}"

Add a tag to a case

curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/tag -d "{\"caseUuid\":\"55131c1a-8c20-45dd-8722-f06550b9ccd3\",\"tagValue\":\"name-of-tag\"}"

Update the severity of a case

This is an update so requires a PUT. Note also that the severity field is an integer, not a string, usually from 1 (Emergency) to 5 (Low).

curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3 -d "{\"severity\":4}" -X PUT

Add a comment to a case

This example uses the default ACL for the case.

curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/data -d "{\"data\":\"aGVsbG8gd29ybGQ=\",\"mimeType\":\"text/plain\",\"significance\":\"Comment\"}"

Upload a file to a case

Note that data is the actual contents of the file, and fileLastMod is UNIX time, ie. seconds since 1970-01-01T00:00:00+00:00.

curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/data -d "{\"data\":\"aGVsbG8gd29ybGQK\",\"mimeType\":\"text/plain\",\"fileName\":\"hello.txt\",\"fileLastMod\":1567489274,\"significance\":\"Comment\"}"

Set the status of a case

curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3 -d "{\"status\":\"Contain\"}" -X PUT

Add Members to a Case

Note that the case group is the first UUID and the member is the second UUID.

curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/member/09cf3b4a-fc85-4d3b-8dab-60ad5ff04f1d -X POST

Add a reply to a comment

Note that the first UUID is the case UUID (as per adding a comment to a case) and the second UUID is the UUID of the comment we are replying to.

curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/data/3d886ba2-9023-4969-b4d4-101c75b1ea12 -d "{\"data\":\"aGVsbG8gd29ybGQ=\",\"mimeType\":\"text/plain\",\"significance\":\"Comment\"}"

Also note that in future API versions, replies will be submitted against /data/{dataUuid} rather than /case/{caseUuid}/data/{dataUuid}, as the caseUuid is redundant.

Add a playbook to a case

Note that the first UUID is the case UUID and the second is the playbook UUID.

curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case/55131c1a-8c20-45dd-8722-f06550b9ccd3/playbook/33c2ba93-0df1-4ea5-bcc8-cb123bbbe993 -X POST

List cases (with filtering and sorting)

curl -i -k -H "x-cydarm-authz: $bearerToken" https://stackname.cydarm.com/cydarm-api/case?page%5bnumber%5d=0&page%5bsize%5d=5&filter%5bcreate_start%5d=2022-12-05T00%3A00%3A00.000Z&filter%5bseverity%5d=Low,Medium