Quickstart

Use this guide to get started with the Seemplicity API quickly. This guide will show you how to:

1. Generate a Seemplicity API token in the production environment.

2. Make your first API call using the production endpoint.

For our Seemplicity GraphQL API Reference, see our documentation here.

Get started in the production environment

This guide uses cURL.

Prerequisites

Confirm with Customer Services that Seemplicity has enabled the API for your company and provides access to the Authentication - API Token settings.

The following procedure explains how to acquire the required parameters for your company:

• <API_TOKEN>

• <API_URL>

Generate a Bearer token and start using the Seemplicity API

To access the Seemplicity API:

1. From Seemplicity's top menu bar, go to Settings > Authentication - API Tokens.

2. Select +Add API Token. The API Token dialog displays.

3. Enter a descriptive Name and select Create.

4. Copy the generated token and save it for future use. When finished, select Close.

5. Next, generate a JWT from the token in step 4 by running the following script in your preferred coding platform.

NOTE

If you access https://app.seemplicity.io, enter eu-central-1 as your region.

If you access https://app.us.seemplicity.io, enter us-east-2 as your region.

Example in Bash:

#!/bin/bash
REGION="eu-central-1"

token=$(echo "$1" | base64 -d | curl -s -X POST \
-d @- \
-H 'X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth' \
-H 'Content-Type: application/x-amz-json-1.1' \
"https://cognito-idp."$REGION".amazonaws.com/" | jq -r ".AuthenticationResult.AccessToken")

echo $token

Example in Python:

import requests
import base64
import json

REGION = 'eu-central-1'


def get_token(api_key: str) -> str:
    cognito_data = base64.b64decode(api_key)
    cognito_url = f'https://cognito-idp.{REGION}.amazonaws.com'
    cognito_headers = {'X-Amz-Target': 'AWSCognitoIdentityProviderService.InitiateAuth',
                       'Content-Type': 'application/x-amz-json-1.1'}
    cognito_response = requests.post(cognito_url, headers=cognito_headers,      data=cognito_data)
    return json.loads(cognito_response.content)['AuthenticationResult']['AccessToken']

6. Copy the JWT. It will be valid for a limited period of time. This is the Bearer < JWT > token.

Make your API call: example in cURL

1. Use the example request below.

   curl --location 'https://api.seemplicity.io/api/v1' \
   --header 'Content-Type: application/json' \
   --header 'Authorization: Bearer <JWT>' \
   --data '{"query":"query get_finding_by_id($id: ID!) {\n  finding(id: $id) {\n    id\n    id_int\n    finding_id\n    last_reported_time\n    cloud_provider\n    original_status\n    discovered_time\n    cloud_account\n    package_name\n    datasource {\n      friendly_name\n    }\n    main_resource {\n      resource_name\n    }\n    title\n    finding_score {\n      score\n      severity\n      original_score\n    }\n    age\n    description\n  }\n}","variables":{"id":"RmluZGluZzoxODAxNTA="}}'

2. The location < API_ENDPOINT_URL >, is as included in the example request (https://api.seemplicity.io/api/v1).

3. For the authorization: Bearer < JWT >, enter the generated JWT from step 6 above.

If successful, you'll receive an HTTP 200 response with a JSON payload. See the example below.

{
    "data": {
        "finding": {
            "id": "RmluZGluZzoxODAxNTA=",
            "id_int": 180150,
            "finding_id": "1-1-findings.id IN (902, 905) and (1 is not null)",
            "last_reported_time": "2021-04-07T14:52:29+00:00",
            "cloud_provider": "github",
            "original_status": "",
            "discovered_time": "2022-02-19T06:58:31+00:00",
            "cloud_account": "github:mobile-app",
            "package_name": null,
            "datasource": {
                "friendly_name": "GHB"
            },
            "main_resource": {
                "resource_name": "mobile-app"
            },
            "title": "Code Injection in js-yaml - Multiple Vulnerabilities",
            "finding_score": {
                "score": 10.0,
                "severity": 3,
                "original_score": null
            },
            "age": 709,
            "description": "Versions of `js-yaml` prior to 3.13.1 are vulnerable to Code Injection. The `load()` function may execute arbitrary code injected through a malicious YAML file. Objects that have `toString` as key, JavaScript code as value and are used as explicit mapping keys allow attackers to execute the supplied code through the `load()` function. The `safeLoad()` function is unaffected.\n\nAn example payload is \n`{{ toString: !<tag:yaml.org,2002:js/function> 'function (){{return Date.now()}}' }} : 1` \nwhich returns the object \n{{\n  \"1553107949161\": 1\n}}\n\n\n## Recommendation\n\nUpgrade to version 3.13.1."
        }
    }
}