NAV Navbar
cURL

Introduction

Cymatic Security's API provides the digital infrastructure you will need to reliably secure your fintech application in savings, investing, wealth, insurance, and financial wellness. This includes the base functionality to create, authenticate, onboard clients and accounts, and store and process data which all other APIs in the Cymatic platform will utilize.

All of Cymatic Security APIs are built on REST principles, with resource oriented URLs and HTTP response codes. All API responses are returned in JSON format.

IDs

Name Explanation
sdk_uuid SDK_UUID

Production Base URL

  https://api.cymaticsecurity.com/

Authentication

API Authentication

After successful registration of your tenant and site, you will be provided a client_id and client_secret which will be used to identify your site when calling any CymaticSecurity API.

We require all API calls to be made over HTTPS connections.

OAuth2 Authorization

CymaticSecurity uses OAuth 2.0 to facilitate authorization on the API, an industry standard framework for authorization. The client credentials flow is used by your site to obtain permission to act on its own behalf. A call will be made to our OAuth server to exchange your client_id, client_secret, and grant_type=client_credentials for an access_token, which can then be used to make calls to CymaticSecurity on behalf of the site.

HTTP Request

POST https://<tenant>.api.cymaticsecurity.com/auth/token

Request Arguments

Parameter Type Required Description
grant_type string required Must be set to client_credentials.
client_id string required Site's credential id for identification, which will be given to you when you register a site.
client_secret string required Site's credential secret, which will be given to you only once when you register a site. Please keep this in a safe place.

Response

Field Description
access_token Token that will be used for all subsequent API calls
expires_in When the token expires in seconds and will need to be called again. Default is 86400 or 24 hours.
scope The scope your user has been granted in the application

Example Request

curl -X POST https://<tenant>.api.cymaticsecurity.com/auth/token --data-urlencode "grant_type=client_credentials" \
  -H "Authorization: Basic Y2xpZW50X2lkOmNsaWVudF9zZWNyZXQ="

Example Response

  {
    "access_token": "6F63A27A-082D-49F3-9F6B-E143E0F823DA",
    "expires_in": 10800,
    "scope": "email profile"
  }

Token Refresh

An access_token will need to be refreshed to continue being authorized for the app. Access tokens are short lived: 24 hours. The Client Credentials grant type doesn’t return a refresh token. When your access_token expires, the site has to simply request a new token which will invalidate the previous token. The token can be deserialized to determine how much longer it is valid.

To authorize, use this code:

Command Endpoints

Login

This endpoint creates a new session for an end user in Cymatic's environment.

Example Request

  curl POST "https://<tenant>.api.cymaticsecurity.com/login"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"
  --data '{"c_uuid": "DCBF72CF-A5BC-463B-A648-C7FD909DF39C", "jwt": "BEB82D40-1433-482F-B469-5C2EF8605D60"}'

Example Response

{
  "session_id": "B26A4AFE-2B7A-413A-AABF-CB2402F4F951",
  "c_uuid": "DCBF72CF-A5BC-463B-A648-C7FD909DF39C",
  "sdk_uuid": "83c1462d-26c2-406e-9f2b-778e7fd63b21",
  "device_id": "5c772b5bd101b600130d04c9",
  "socket_id": "/client#AFxaNRHEpX5iVo8nAAJc",
  "jwt": "BEB82D40-1433-482F-B469-5C2EF8605D60",
  "started_at": "2019-02-28T20:31:35.873Z",
}

HTTP Request

POST https://<tenant>.api.cymaticsecurity.com/login

Request Arguments

Parameter Type Required Description
jwt string required JWT (string) that represents the enduser traking identity.
c_uuid string required UUID (string) An enduser's profile identificator provided to you at the moment you created this user's profile.

Logout

This endpoint closes an end user's open session on Cymatic's environment.

Example Request

  curl POST "https://<tenant>.api.cymaticsecurity.com/logout"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"
  --data '{"session_id": "B26A4AFE-2B7A-413A-AABF-CB2402F4F951"}'

Example Response

Closed

HTTP Request

POST https://<tenant>.api.cymaticsecurity.com/logout

Request Arguments

Parameter Type Required Description
session_id string required Session identificator returned from a successful /login call to Cymatic.

Credentials

Darkweb analytics

Darkweb usernames summary

Analytic summary of usernames that have logged into the site and that have been scanned against the darkweb databases.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/usernames?period=week"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "counters": 
  {
    "total": 10,
    "risky": 8,
    "safe" : 2
  },
  "graph": [
    {
      "tick" : "1550793600000",
      "risky": 5,
      "safe" : 1
    },
    {
      "tick" : "1550880000000",
      "risky": 3,
      "safe" : 1
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/usernames

Request Arguments

Parameter Type Required Description
period string required Starting period of time to look for records. Current time marks the end of the search. Possible values: day, week, month.

Response

Field Description
counters.total Total of usernames scanned.
counters.risky Number of risky usernames found.
counters.safe Number of safe usernames found.
graph List containing the target results.
graph.tick The epoch timestamp of the result.
graph.risky Number of risky usernames found in this timestamp.
graph.safe Number of safe usernames found in this timestamp.

Darkweb usernames condensed summary

Condensed summary of usernames that have logged into the site and that have been scanned against the darkweb databases.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/usernames/summary?seen_after=1550815200000"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "totalCount":0,
  "graph":[
    {"risky":0},
    {"safe":0}
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/usernames/summary

Request Arguments

Parameter Type Required Description
seen_after epoch timestamp required Start date to look for records. Current time marks the end of the search.

Darkweb usernames summary with trend data

Analytic summary of usernames that have been scanned against the darkweb databases. Payload includes trending data from a past period of time.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/usernames?period=week"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "counters": 
  {
    "total"          : 10,
    "risky"          : 8,
    "safe"           : 2,
    "percentageRisky": 100,
    "percentageSafe" : -50
  },
  "graph": 
  [
    {
      "tick"        : "1550880000000",
      "risky"       : 5,
      "safe"        : 1,
      "historyIndex": 0
    },
    {
      "tick"        : "1550966400000",
      "risky"       : 3,
      "safe"        : 1,
      "historyIndex": 0
    },
    {
      "tick"        : "1551052800000",
      "risky"       : 4,
      "safe"        : 0,
      "historyIndex": 1
    },
    {
      "tick"        : "1551052800000",
      "risky"       : 0,
      "safe"        : 4,
      "historyIndex": 1
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/usernames/trend

Request Arguments

Parameter Type Required Description
period string required Starting period of time to look for records. Current time marks the end of the search. Possible values: day, week, month. Trending data includes one period of time before the current period, for example, the period of week will get the data from the last 7 days, and the trending data from the week before that.

Response

Field Description
counters.total Total of usernames scanned.
counters.risky Number of risky usernames found.
counters.safe Number of safe usernames found.
counters.percentageRisky Trending percentage of risky usernames. This value is calculated by comparing the data from the past period against the current period.
counters.percentageSafe Trending percentage of safe usernames. This value is calculated by comparing the data from the past period against the current period.
graph List containing the target results.
graph.tick The epoch timestamp of the result.
graph.risky Number of risky usernames found in this timestamp.
graph.safe Number of safe usernames found in this timestamp.
graph.historyIndex 0 represents the current period of time, 1 represents the past period of time.

Darkweb passwords summary

Analytic summary of end user passwords that have logged into the site and that have been scanned against the darkweb databases.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/passwords?period=week"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "counters": 
  {
    "total": 10,
    "risky": 8,
    "safe" : 2
  },
  "graph": [
    {
      "tick" : "1550793600000",
      "risky": 5,
      "safe" : 1
    },
    {
      "tick" : "1550880000000",
      "risky": 3,
      "safe" : 1
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/passwords

Request Arguments

Parameter Type Required Description
period string required Starting period of time to look for records. Current time marks the end of the search. Possible values: day, week, month.

Response

Field Description
counters.total Total of passwords scanned.
counters.risky Number of risky passwords found.
counters.safe Number of safe passwords found.
graph List containing the target results.
graph.tick The epoch timestamp of the result.
graph.risky Number of risky passwords found in this timestamp.
graph.safe Number of safe passwords found in this timestamp.

Darkweb passwords condensed summary

Condensed summary of end user passwords that have logged into the site and that have been scanned against the darkweb databases.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/passwords/summary?seen_after=1550815200000"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "totalCount":0,
  "graph":[
    {"risky":0},
    {"safe":0}
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/passwords/summary

Request Arguments

Parameter Type Required Description
seen_after epoch timestamp required Start date to look for records. Current time marks the end of the search.

Darkweb passwords summary with trend data

Analytic summary of end user passwords that have been scanned against the darkweb databases. Payload includes trending data from a past period of time.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/passwords/trend?period=week"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json" 

Example Response

{
  "counters": 
  {
    "total"          : 10,
    "risky"          : 8,
    "safe"           : 2,
    "percentageRisky": 100,
    "percentageSafe" : -50
  },
  "graph": 
  [
    {
      "tick"        : "1550880000000",
      "risky"       : 5,
      "safe"        : 1,
      "historyIndex": 0
    },
    {
      "tick"        : "1550966400000",
      "risky"       : 3,
      "safe"        : 1,
      "historyIndex": 0
    },
    {
      "tick"        : "1551052800000",
      "risky"       : 4,
      "safe"        : 0,
      "historyIndex": 1
    },
    {
      "tick"        : "1551052800000",
      "risky"       : 0,
      "safe"        : 4,
      "historyIndex": 1
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/darkweb/passwords/trend

Request Arguments

Parameter Type Required Description
period string required Starting period of time to look for records. Current time marks the end of the search. Possible values: day, week, month. Trending data includes one period of time before the current period, for example, the period of week will get the data from the last 7 days, and the trending data from the week before that.

Response

Field Description
counters.total Total of passwords scanned.
counters.risky Number of risky passwords found.
counters.safe Number of safe passwords found.
counters.percentageRisky Trending percentage of risky passwords. This value is calculated by comparing the data from the past period against the current period.
counters.percentageSafe Trending percentage of safe passwords. This value is calculated by comparing the data from the past period against the current period.
graph List containing the target results.
graph.tick The epoch timestamp of the result.
graph.risky Number of risky passwords found in this timestamp.
graph.safe Number of safe passwords found in this timestamp.
graph.historyIndex 0 represents the current period of time, 1 represents the past period of time.

Password strength reports

Password strength filtered by risk

Summary of risky end user passwords that have logged into the site and that have been scanned to evaluate its strength.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/passwordstrength/risks"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "totalCount": 1,
  "resources" : [
    {
      "c_uuid"    : "560de83b-7b82-49c4-a4fe-7c40de85bf44",
      "alias"     : "[email protected]",
      "first_seen": "2019-03-18T23:45:31.580Z",
      "last_seen" : "2019-03-18T23:45:31.580Z",
      "times_used": 1,
      "vulnerabilities": [
        "No special symbols",
        "No uppercase characters"
      ],
      "strength": "weak"
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/passwordstrength/risks

Request Arguments

Parameter Type Required Description
page number optional Use to paginate results.
per_page number optional Number of paginated records to fetch.
report string optional If set, it will stream a file with the search data. Possible values: csv

Response

Field Description
totalCount The number of risky devices detected.
resources List containing the target results.
resources.c_uuid The user ID the password belongs to.
resources.alias The identified username or email for the user.
resources.first_seen_at The epoch timestamp when the device was first seen.
resources.last_seen_at The epoch timestamp when the device was last seen.
resources.times_used The number of times the user has logged into the site using this password.
resources.vulnerabilities List containing the password vulnerabilities.
resources.strength The level of strength that the password presents.

Password strength analytics

Password strength summary

Analytic summary of end user passwords that have logged into the site and that have been scanned to evaluate its strength.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/passwordstrength?period=week"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "counters": 
  {
    "total": 10,
    "risky": 8,
    "safe" : 2
  },
  "graph": [
    {
      "tick" : "1550793600000",
      "risky": 5,
      "safe" : 1
    },
    {
      "tick" : "1550880000000",
      "risky": 3,
      "safe" : 1
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/passwordstrength

Request Arguments

Parameter Type Required Description
period string required Starting period of time to look for records. Current time marks the end of the search. Possible values: day, week, month.

Response

Field Description
counters.total Total of passwords scanned.
counters.risky Number of risky passwords found.
counters.safe Number of safe passwords found.
graph List containing the target results.
graph.tick The epoch timestamp of the result.
graph.risky Number of risky passwords found in this timestamp.
graph.safe Number of safe passwords found in this timestamp.

Password strength condensed summary

Condensed summary of end user passwords that have logged into the site and that have been scanned to evaluate its strength.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/passwordstrength/summary?seen_after=1550815200000"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "totalCount":10,
  "graph":[
    {
      "Very Weak"  : 1,
      "Weak"       : 3,
      "Medium"     : 2,
      "Strong"     : 1,
      "Very Strong": 2,
      "Perfect"    : 1
    }
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/passwordstrength/summary

Request Arguments

Parameter Type Required Description
seen_after epoch timestamp required Start date to look for records. Current time marks the end of the search.

Response

Field Description
totalCount Total of passwords scanned.
graph List containing the target results.
graph["Very Weak"] Number of Very Weak passwords detected.
graph["Weak"] Number of Weak passwords detected.
graph["Medium"] Number of Medium passwords detected.
graph["Strong"] Number of Strong passwords detected.
graph["Very Strong"] Number of Very Strong passwords detected.
graph["Perfect"] Number of Perfect passwords detected.

Password strength summary with trend data

Analytic summary of end user passwords that have logged into the site and that have been scanned to evaluate its strength. Payload includes trending data from a past period of time.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/passwordstrength/trend?period=week"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "counters": 
  {
    "total"          : 10,
    "risky"          : 8,
    "safe"           : 2,
    "percentageRisky": 100,
    "percentageSafe" : -50
  },
  "graph": 
  [
    {
      "tick"        : "1550880000000",
      "risky"       : 5,
      "safe"        : 1,
      "historyIndex": 0
    },
    {
      "tick"        : "1550966400000",
      "risky"       : 3,
      "safe"        : 1,
      "historyIndex": 0
    },
    {
      "tick"        : "1551052800000",
      "risky"       : 4,
      "safe"        : 0,
      "historyIndex": 1
    },
    {
      "tick"        : "1551052800000",
      "risky"       : 0,
      "safe"        : 4,
      "historyIndex": 1
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/credentials/sites/<sdk_uuid>/passwordstrength/trend

Request Arguments

Parameter Type Required Description
period string required Starting period of time to look for records. Current time marks the end of the search. Possible values: day, week, month. Trending data includes one period of time before the current period, for example, the period of week will get the data from the last 7 days, and the trending data from the week before that.

Response

Field Description
counters.total Total of passwords scanned.
counters.risky Number of risky passwords found.
counters.safe Number of safe passwords found.
counters.percentageRisky Trending percentage of risky passwords. This value is calculated by comparing the data from the past period against the current period.
counters.percentageSafe Trending percentage of safe passwords. This value is calculated by comparing the data from the past period against the current period.
graph List containing the target results.
graph.tick The epoch timestamp of the result.
graph.risky Number of risky passwords found in this timestamp.
graph.safe Number of safe passwords found in this timestamp.
graph.historyIndex 0 represents the current period of time, 1 represents the past period of time.

Devices

Data in the devices endpoints are related to properties of browsers, os and mobile devices and their vulnerabilities as determined in the Common Vulnerabilities Enumeration by NIST. The properties and risks are reported from least to more granular from the Account's, Site's and User's levels.

Devices reports

Devices filtered by risk

Summary of risky devices that have logged into the site.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>/risks"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "totalCount": 1,
  "resources" : [
    {
      "device_id"    : "5c86e42f489ad4001005cbb0",
      "c_uuid"       : "f5e1bfb6-bb21-4747-976c-9d9f52297c04",
      "session_count": 11,
      "user_agent"   : "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:65.0) Gecko/20100101 Firefox/65.0",
      "first_seen_at": "2019-03-18T22:08:44.131Z",
      "last_seen_at" : "2019-03-19T17:17:40.124Z",
      "nist_risk"    : {
        "score": 6.256521739130433,
        "calculated_at": "2019-03-19T17:17:40.124Z",
        "threats": [
          {
            "cve_id": "CVE-2018-8209",
            "name": "Credentials Management",
            "description": "An information disclosure vulnerability exists when Windows allows a normal user to access the Wireless LAN profile of an administrative user...",
            "base_score": 2.7,
            "severity": "LOW",
            "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-8209"
          }
        ]
      }
    }
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>/risks

Request Arguments

Parameter Type Required Description
page number optional Use to paginate results.
per_page number optional Number of paginated records to fetch.

Response

Field Description
totalCount The number of risky devices detected.
resources List containing the target results.
resources.device_id The device ID.
resources.c_uuid The user ID the device belongs to.
resources.session_count The number of sessions this device has been seen.
resources.user_agent The user agent detected on the device.
resources.first_seen_at The epoch timestamp when the device was first seen.
resources.last_seen_at The epoch timestamp when the device was last seen.

Devices filtered by profile

Summary of devices related to an end user profile that have logged into the site.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>/profiles/<c_uuid>"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "totalCount": 1,
  "resources": [
    {
      "device_id"    : "5c86e42f489ad4001005cbb0",
      "c_uuid"       : "f5e1bfb6-bb21-4747-976c-9d9f52297c04",
      "session_count": 11,
      "user_agent"   : "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:65.0) Gecko/20100101 Firefox/65.0",
      "first_seen_at": "2019-03-18T22:08:44.131Z",
      "last_seen_at" : "2019-03-19T17:17:40.124Z",
      "nist_risk"    : {
        "score": 6.256521739130433,
        "calculated_at": "2019-03-19T17:17:40.124Z",
        "threats": [
          {
            "cve_id": "CVE-2018-8209",
            "name": "Credentials Management",
            "description": "An information disclosure vulnerability exists when Windows allows a normal user to access the Wireless LAN profile of an administrative user...",
            "base_score": 2.7,
            "severity": "LOW",
            "url": "https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2018-8209"
          }
          ...
        ]
      }
    }
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>/profiles/<c_uuid>

Request Arguments

Parameter Type Required Description
page number optional Use to paginate results.
per_page number optional Number of paginated records to fetch.

Response

Field Description
totalCount The number of risky devices detected.
resources List containing the target results.
resources.device_id The device ID.
resources.c_uuid The user ID the device belongs to.
resources.session_count The number of sessions this device has been seen.
resources.user_agent The user agent detected on the device.
resources.first_seen_at The epoch timestamp when the device was first seen.
resources.last_seen_at The epoch timestamp when the device was last seen.

Devices analytics

Devices summary

Analytic summary of devices that have logged into the site.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>?period=week"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "counters": 
  {
    "total": 10,
    "risky": 8,
    "safe" : 2
  },
  "graph": 
  [
    {
      "tick" : "1550880000000",
      "risky": 5,
      "safe" : 1
    },
    {
      "tick" : "1550966400000",
      "risky": 3,
      "safe" : 1
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>

Request Arguments

Parameter Type Required Description
period string required Starting period of time to look for records. Current time marks the end of the search. Possible values: day, week, month.

Response

Field Description
counters.total Total of devices scanned.
counters.risky Number of risky devices found.
counters.safe Number of safe devices found.
graph List containing the target results.
graph.tick The epoch timestamp of the result.
graph.risky Number of risky devices found in this timestamp.
graph.safe Number of safe devices found in this timestamp.

Devices summary with trend data

Analytic summary of devices that have logged into the site. Payload includes trending data from a past period of time.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>?period=week"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "counters": 
  {
    "total"          : 10,
    "risky"          : 8,
    "safe"           : 2,
    "percentageRisky": 100,
    "percentageSafe" : -50
  },
  "graph": 
  [
    {
      "tick"        : "1550880000000",
      "risky"       : 5,
      "safe"        : 1,
      "historyIndex": 0
    },
    {
      "tick"        : "1550966400000",
      "risky"       : 3,
      "safe"        : 1,
      "historyIndex": 0
    },
    {
      "tick"        : "1551052800000",
      "risky"       : 4,
      "safe"        : 0,
      "historyIndex": 1
    },
    {
      "tick"        : "1551052800000",
      "risky"       : 0,
      "safe"        : 4,
      "historyIndex": 1
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>/trend

Request Arguments

Parameter Type Required Description
period string required Starting period of time to look for records. Current time marks the end of the search. Possible values: day, week, month. Trending data includes one period of time before the current period, for example, the period of week will get the data from the last 7 days, and the trending data from the week before that.
report string optional If set, it will stream a file with the search data. Possible values: csv

Response

Field Description
counters.total Total of devices scanned.
counters.risky Number of risky devices found.
counters.safe Number of safe devices found.
counters.percentageRisky Trending percentage of risky devices. This value is calculated by comparing the data from the past period against the current period.
counters.percentageSafe Trending percentage of safe devices. This value is calculated by comparing the data from the past period against the current period.
graph List containing the target results.
graph.tick The epoch timestamp of the result.
graph.risky Number of risky devices found in this timestamp.
graph.safe Number of safe devices found in this timestamp.
graph.historyIndex 0 represents the current period of time, 1 represents the past period of time.

Devices ordered by top risky

Analytic summary of the top risky devices that have logged into the site.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>/toprisks/seen_after=1550815200000"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA" 
  -H "Content-Type: application/json"

Example Response

{
  "graph": 
  [
    {
      "os"     : "Windows",
      "browser": "Firefox",
      "risky"  : "2"
    },
    {
      "os"     : "Windows",
      "browser": "Chrome",
      "risky"  : "4"
    },
    {
      "os"     : "Linux",
      "browser": "Chrome",
      "risky"  : "1"
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>/toprisks

Request Arguments

Parameter Type Required Description
seen_after epoch timestamp required Start date to look for records. Current time marks the end of the search.

Response

Field Description
graph List containing the target results.
graph.os The operating system used by the device.
graph.browser The browser used by the device.
graph.risky Number of vulnerabilities the device has for the current OS and Browser.

IPs

IPs reports

IPs filtered by risk

Summary of risky IPs we've seen the end users coming from that have logged into the site.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/threats"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "totalCount": 1,
  "resources" : [
    {
      "ip": "3.16.136.175",
      "threats": [
        {
          "name"       : "Port Scan",
          "description": "Scanning for open ports and vulnerable services. "
        }
      ],
      "affected_users": [
        "f5e1bfb6-bb21-4747-976c-9d9f52297c04"
      ],
      "risk"     : "Very High",
      "last_seen": 1553126988614
    }
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/threats

Request Arguments

Parameter Type Required Description
page number optional Use to paginate results.
per_page number optional Number of paginated records to fetch.

Response

Field Description
totalCount The number of risky ips detected.
resources List containing the target results.
resources.ip The target IP address.
resources.threats List containing the IP address threats.
resources.threats.name The name of the threat.
resources.threats.description The description of the threat.
resources.affected_users List containing the user IDs affected by the IP address.
resources.risk The level of risk that the IP address presents.
resources.last_seen The epoch timestamp when the IP address was last seen.

IPs filtered by profile

Summary of IPs related to an end user profile that has logged into the site.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/profiles/<c_uuid>"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "totalCount": 1,
  "resources" : [
    {
      "ip": "3.16.136.175",
      "threats": [
        {
          "name"       : "Port Scan",
          "description": "Scanning for open ports and vulnerable services. "
        }
      ],
      "risk"      : "Very High",
      "first_seen": 1553665825057,
      "last_seen" : 1553126988614
    }
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/devices/sites/<sdk_uuid>/profiles/<c_uuid>

Request Arguments

Parameter Type Required Description
page number optional Use to paginate results.
per_page number optional Number of paginated records to fetch.
only_threats boolean optional If set to true, the fetched results will contain only IPs that have at least one detected threat.

Response

Field Description
totalCount The number of risky ips detected.
resources List containing the target results.
resources.ip The target IP address.
resources.threats List containing the IP address threats.
resources.threats.name The name of the threat.
resources.threats.description The description of the threat.
resources.risk The level of risk that the IP address presents.
resources.first_seen The epoch timestamp when the IP address was first seen.
resources.last_seen The epoch timestamp when the IP address was last seen.

IPs locations countries

Summary of countries related to the IPs we see the end users coming from that have logged into the site.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/locations/countries?seen_after=1550815200000&has_threats=true"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "resources": [
    {
      "location"  : "Sao Paulo, BR",
      "count"     : 3,
      "first_seen": 1551143143960,
      "last_seen" : 1551143417479
    },
    {
      "location"  : "Jalisco, MX",
      "count"     : 1,
      "first_seen": 1551143143960,
      "last_seen" : 1551143417479
    },
    ...
  ],
  "totalCount": 2
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/locations/countries

Request Arguments

Parameter Type Required Description
seen_after epoch timestamp required Starting date to look for records. Current time marks the end of the search.
has_threats boolean optional If set to true, the results will come filtered with only those locations that contain risky IPs.

Response

Field Description
resources List containing the target results.
resources.location The geopolitical division: "state, country" where the end user has been seen coming from.
resources.count Number of times the end user has been seen coming from this geopolitical division.
resources.first_seen First time the end user was seen coming from this geopolitical division.
resources.last_seen Last time the end user was seen coming from this geopolitical division.

IPs analytics

IPs summary

Analytic summary of IPs we've seen the end users coming from that have logged into the site.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/threats/summary?seen_after=1550815200000"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "counters": 
  {
    "total": 10,
    "risky": 8,
    "safe" : 2
  },
  "graph": 
  [
    {
      "tick" : "1550880000000",
      "risky": 5,
      "safe" : 1
    },
    {
      "tick" : "1550966400000",
      "risky": 3,
      "safe" : 1
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/threats/summary

Request Arguments

Parameter Type Required Description
seen_after epoch timestamp required Starting date to look for records. Current time marks the end of the search.

Response

Field Description
counters.total Total of IPs scanned.
counters.risky Number of risky IPs found.
counters.safe Number of safe IPs found.
graph List containing the target results.
graph.tick The epoch timestamp of the result.
graph.risky Number of risky IPs found in this timestamp.
graph.safe Number of safe IPs found in this timestamp.

IPs summary with trend data

Analytic summary of IPs we've seen see the end users coming from that have logged into the site. Payload includes trending data from a past period of time.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/threats/summary/trend?period=week"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "counters": 
  {
    "total"          : 10,
    "risky"          : 8,
    "safe"           : 2,
    "percentageRisky": 100,
    "percentageSafe" : -50
  },
  "graph": 
  [
    {
      "tick"        : "1550880000000",
      "risky"       : 5,
      "safe"        : 1,
      "historyIndex": 0
    },
    {
      "tick"        : "1550966400000",
      "risky"       : 3,
      "safe"        : 1,
      "historyIndex": 0
    },
    {
      "tick"        : "1551052800000",
      "risky"       : 4,
      "safe"        : 0,
      "historyIndex": 1
    },
    {
      "tick"        : "1551052800000",
      "risky"       : 0,
      "safe"        : 4,
      "historyIndex": 1
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/threats/summary/trend

Request Arguments

Parameter Type Required Description
period string required Starting period of time to look for records. Current time marks the end of the search. Possible values: day, week, month. Trending data includes one period of time before the current period, for example, the period of week will get the data from the last 7 days, and the trending data from the week before that.

Response

Field Description
counters.total Total of IPs scanned.
counters.risky Number of risky IPs found.
counters.safe Number of safe IPs found.
counters.percentageRisky Trending percentage of risky IPs. This value is calculated by comparing the data from the past period against the current period.
counters.percentageSafe Trending percentage of safe IPs. This value is calculated by comparing the data from the past period against the current period.
graph List containing the target results.
graph.tick The epoch timestamp of the result.
graph.risky Number of risky IPs found in this timestamp.
graph.safe Number of safe IPs found in this timestamp.
graph.historyIndex 0 represents the current period of time, 1 represents the past period of time.

IPs countries

Analytic summary of the countries with the most IPs we see the end users coming from that have logged into the site.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/locations/countries/counts?has_threats=true&period=week"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "graph": 
  [
    {
      "location": "MX",
      "total"   : 10
    },
    {
      "location": "US",
      "total"   : 8
    },
    ...
  ]
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/locations/countries/counts

Request Arguments

Parameter Type Required Description
period string required Starting period of time to look for records. Current time marks the end of the search. Possible values: day, week, month.
has_threats boolean optional If set to true, the results will come filtered with only those locations that contain risky IPs.

Response

Field Description
graph List containing the target results.
graph.location The country code where the IP belongs.
graph.total The total count of IPs seen from this location.

IPs locations coordinates

Summary of coordinates for all the IPs we see the end users coming from that have logged into the site.

Example Request

  curl GET "https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/locations?seen_after=1550815200000&has_threats=true"
  -H "Authorization: Bearer 6F63A27A-082D-49F3-9F6B-E143E0F823DA"
  -H "Content-Type: application/json"

Example Response

{
  "resources": [
    {
      "coord": [
        19.7419,
        -103.4528
      ]
    },
    {
      "coord": [
        19.2548,
        -103.6982
      ]
    },
    ...
  ],
  "totalCount": 2
}

HTTP Request

GET https://api.cymaticsecurity.com/v1/ips/sites/<sdk_uuid>/locations

Request Arguments

Parameter Type Required Description
seen_after epoch timestamp required Starting date to look for records. Current time marks the end of the search.
has_threats boolean optional If set to true, the results will come filtered with only those locations that contain risky IPs.

Response

Field Description
resources List containing the target results.
resources.coord Tuples of latitude and longitude where we detect our users coming from.