| Easy heading | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Introduction
The purpose of this document is to provide instructions to apply API (Application Programming Interface) connection to GYTPOL server from a third-party tools.
Overview
Gytpol API v1.0 covers the following use cases:
...
get_miscon_by_computer
get_misconfigurations_start to set a filter and get a token for following calls to get_misconfigurations_next
get_miscon_computers_start to set a filter and get a token for following calls to get_miscon_computers_next
add_to_group - to add computers to your custom group
All methods are POST.
API Keys
All HTTPS requests for REST API functions must include the x-api-key parameter in the request header, as illustrated in the examples below.
...
SaaS customers are advised to reach out to their customer success manager to obtain the necessary x-api-key.
API Port
For On-Prem customers, the default port for API access is 9191. If you wish to use a different port, you can make the adjustment by modifying the port in the file located at c:\gytpol\data\webserv_config.json.
...
For SaaS customers, there is no need to specify a port, as the URL utilizes port 443.
get_miscon_by_computer
This REST API function returns misconfigurations given a computer name and optionally Windows domain name.
Request Structure
JSON string of the following structure:
...
computer | string | mandatory | Computer name |
domainName | string | optional | For windows computers, Windows domain name |
Response Structure
JSON string of the following structure:
...
computers | object array | |||
latestHostReportingDt | datetime | Latest date and time the computer reported to Gytpol | ||
latestScanDt | datetime | Gytpol client scans computers for misconfigurations and sends the report to Gytpol backend. This is the date and time of the latest misconfiguration scan reported for this computer. | ||
computer | string | Computer name | ||
computerOu | string | Name of organizational unit define on this computer | ||
domainName | string | For windows computers, Windows domain name | ||
clientVer | string | Gytpol client version currently installed on this computer | ||
ipAddress | string | Computer’s IP address | ||
os | string | Computer’s operating system | ||
isVdi | bool | Is this computer a VDI | ||
isServer | bool | Is this computer a server | ||
isDC | bool | Is this computer a domain controller | ||
miscon | object array | Array of misconfigurations reported for this computer | ||
topicCode | string | |||
user | string | Username logged into the computer when this misconfiguration had been found | ||
severity | string | Specifies minimal severity of returned misconfigurations. Supported values are: Low Medium High | ||
addInfo | string | Additional information describing this misconfiguration (this is json string) with \ before “ in order to prevent breaking the structure of the response json | ||
param | string | Parameter providing more details for the misconfiguration | ||
paramExtra | string | Parameter providing even more details for the misconfiguration | ||
isRemediable | bool | Is this misconfiguration remediable | ||
isMuted | bool | Is this misconfiguration muted by one of the mute rules | ||
mutedByRuleId | number | The Id of the mute rule that muted this misconfiguration | ||
hostReportingDt | datetime | Datetime when computer reported this misconfiguration to Gytpol backend | ||
scanTimeDt | datetime | Datetime when Gytpol client installed on the computer found this misconfiguration |
| Anchor | ||||
|---|---|---|---|---|
|
curl --location --request POST "{BASE-URL}/gytpolapi/v2.0/get_miscon_by_computer" --header "x-api-key: jyUbUQNuVjClzQ5f6sXgmcgGzyoFiaYXA+OvxObvLV8="--data-raw "{ \"computer\": \"YOUR-COMPUTER-NAME\"}"
...
For On-prem customers, please incorporate your port (i.e., 9191) into the BASE-URL as follows: BASE-URL:PORT.
Response Example
{ "computers": [ { "latestHostReportingDt": "2023-01-17T18:25:05.5389826+02:00", "latestScanTimeDt": "2023-01-17T18:24:47.4503679+02:00", "computer": "YOUR-COMPUTER-NAME", "computerOu": "COMPUTER-OU", "domainName": "YOUR-DOMAIN-NAME", "clientVer": "2.26.1.0", "ipAddress": "10.67.137.160", "os": "Win 10 Enterprise", "isVdi": false, "isServer": false, "isDC": false, "miscon": [ { "topicCode": "gytPSVerIssue", "user": null, "severity": "Medium", "addInfo": "{\"PSversions\":\"2; 5.1.19041.2364\",\"occurrences\":1}", "param": "2; 5.1.19041.2364", "paramExtra": null, "isRemediable": true, "isMuted": false, "mutedByRuleId": 0, "hostReportingDt": "2023-01-17T18:25:05.5389826+02:00", "scanTimeDt": "2023-01-17T18:24:47.4503679+02:00" }, { "topicCode": "gytSmbAnonymous", "user": null, "severity": "Medium", "addInfo": "{\"Current Value\":0,\"Expected Value\":\"1\",\"Registry Name\":\"RestrictAnonymous\",\"Registry Path\":\"HKLM:\\\\System\\\\CurrentControlSet\\\\Control\\\\Lsa\",\"Shares with Everyone\":\"N/A\",\"Shares without Everyone\":\"N/A\",\"occurrences\":1}", "param": "No shares; The configured value is not secure", "paramExtra": null, "isRemediable": true, "isMuted": false, "mutedByRuleId": 0, "hostReportingDt": "2023-01-17T18:25:05.5389826+02:00", "scanTimeDt": "2023-01-17T18:24:47.4503679+02:00" } ] }] } |
HTTP Return Codes
200 Ok
400 Bad Request
401 Unauthorized
429 Too Many Requests
get_misconfigurations_start
Use this function to initiate a series of calls to get misconfigurations by computer.
Request Structure
Request body should contain json object of the following structure:
...
{ "computer": "<string> Optional", "domainName": "<string> Optional", "selTarget": "<string> Optional", "severity": "<string> Optional", "computerOu": "<string> Optional", "topicCodes": ["<string> topic code", "<string> topic code"], "fromHostReportingDt": "<string> that contains datetime Optional", "toHostReportingDt": "<string> that contains datetime Optional", "returnMutedTopics": "boolean default is false Optional" } |
Response Structure
token | string | Encrypted string to use for following calls to the get_misconfigurations_next function |
Request Example
curl --location --request POST "{BASE-URL}/gytpolapi/v2.0/get_misconfigurations_start" --header "x-api-key: jyUbUQNuVjClzQ5f6sXgmcgGzyoFiaYXA+OvxObvLV8=" --data-raw "{ \"computer\": null, \"domainName\": null, \"selTarget\": null, \"severity\": \"Medium\", \"computerOu\": null, \"topicCodes\": null, \"fromHostReportingDt\": \"2023-01-10T19:43:46+02:00\", \"toHostReportingDt\": null, \"returnMutedTopics\": false}"
...
For On-prem customers, please incorporate your port (i.e., 9191) into the BASE-URL as follows: BASE-URL:PORT.
Response Example
{"token":"7h5vmgiKQgvFiTb3xhrSyum52cbfh77xexcus8kGtOP03mliJxbJL99q8wfC2d8kwpNGXa0QF1VuycY6xnosSJePUkaGGUgCQ61rBmVcJI1J6RkUZMWmmGGD3R/+e9b2SrRlamRNusqUBOCphAeyDpBGb7uliNLpfn7wB2JiDGDJRu73Im6UIt3V7ITZDehfsb+JkWXVLlKNIv9+RvxrBCxVa/7StHvyW10cpGF67P9HfLZFbQOCjFsFOs8Mn6amZJrh1bkpasAblUWI0toXZVrlLHr6lfEYZMRnTadcBNTNIUBBWr6ptLUvdcWqEukmdaBublWIQBpAI++Seqc9rMF2WEex9o2n+5NyQBp8+OnuvsUcUybW/MfjG6J/06d07Tf/ks9mQJgZO2vnuJQAPA=="}
HTTP Return Codes
200 Ok
400 Bad Request
401 Unauthorized
429 Too Many Requests
get_misconfigurations_next
Use this function to initiate a series of calls to get misconfigurations by computer
Request Structure
token | string | Mandatory | Encrypted string to use for following calls to the get_misconfigurations_next function |
...
{ "token": "<string> Mandatory } |
Response Structure
computers | object array | Same structure as presented in get_miscon_by_computer Response Structure Keep calling to get_misconfigurations_next each time with the new token until returned computers array is empty, e.g. [] | |
token | string | Encrypted string to use for following calls to the get_misconfigurations_next function |
Request Example
curl --location --request POST "{BASE-URL}/gytpolapi/v2.0/get_misconfigurations_next" --header "x-api-key: jyUbUQNuVjClzQ5f6sXgmcgGzyoFiaYXA+OvxObvLV8=" --data-raw "{ \"token\": \"7h5vmgiKQgvFiTb3xhrSyum52cbfh77xexcus8kGtOP03mliJxbJL99q8wfC2d8kwpNGXa0QF1VuycY6xnosSJePUkaGGUgCQ61rBmVcJI1J6RkUZMWmmGGD3R/+e9b2SrRlamRNusqUBOCphAeyDpBGb7uliNLpfn7wB2JiDGDJRu73Im6UIt3V7ITZDehfsb+JkWXVLlKNIv9+RvxrBCxVa/7StHvyW10cpGF67P9HfLZFbQOCjFsFOs8Mn6amZJrh1bkpasAblUWI0toXZVrlLHr6lfEYZMRnTadcBNTNIUBBWr6ptLUvdcWqEukmdaBublWIQBpAI++Seqc9rMF2WEex9o2n+5NyQBp8+OnuvsUcUybW/MfjG6J/06d07Tf/ks9mQJgZO2vnuJQAPA==\"}"
...
For On-prem customers, please incorporate your port (i.e., 9191) into the BASE-URL as follows: BASE-URL:PORT.
Response Example
{ "computers": “same structure as show in Response Example”, “token” : “new encrypted string for the following call to get_misconfigurations_next” } |
HTTP Return Codes
200 Ok
400 Bad Request
401 Unauthorized
429 Too Many Requests
get_miscon_computers_start
Use this function to initiate a series of calls to get the list of computers that have misconfigurations. Computers will be returned in alphabetical order:
Request Structure
Request body should contain json object of the following structure:
...
{ "computer": "<string> Optional", "domainName": "<string> Optional", "selTarget": "<string> Optional", "computerOu": "<string> Optional } |
Response Structure
token | string | Encrypted string to use for following calls to the get_misconfigurations_next function |
Request Example
curl --location --request POST "{BASE-URL}/gytpolapi/v2.0/get_miscon_computers_start" --header "x-api-key: jyUbUQNuVjClzQ5f6sXgmcgGzyoFiaYXA+OvxObvLV8=" --data-raw "{ \"computer\": null, \"domainName\": null, \"selTarget\": \"Windows Servers\"}"
...
For On-prem customers, please incorporate your port (i.e., 9191) into the BASE-URL as follows: BASE-URL:PORT.
Response Example
{"token":"7h5vmgiKQgvFiTb3xhrSyum52cbfh77xexcus8kGtOP03mliJxbJL99q8wfC2d8kwpNGXa0QF1VuycY6xnosSJePUkaGGUgCQ61rBmVcJI1J6RkUZMWmmGGD3R/+e9b2SrRlamRNusqUBOCphAeyDpBGb7uliNLpfn7wB2JiDGDJRu73Im6UIt3V7ITZDehfsb+JkWXVLlKNIv9+RvxrBCxVa/7StHvyW10cpGF67P9HfLZFbQOCjFsFOs8Mn6amZJrh1bkpasAblUWI0toXZVrlLHr6lfEYZMRnTadcBNTNIUBBWr6ptLUvdcWqEukmdaBublWIQBpAI++Seqc9rMF2WEex9o2n+5NyQBp8+OnuvsUcUybW/MfjG6J/06d07Tf/ks9mQJgZO2vnuJQAPA=="}
HTTP Return Codes
200 Ok
400 Bad Request
401 Unauthorized
429 Too Many Requests
get_miscon_computers_next
Use this function to continue getting results for the list of computers:
| Anchor | ||||
|---|---|---|---|---|
|
token | string | Mandatory | Encrypted string to use for following calls to the get_misconfigurations_next function |
...
{ "token": "<string> Mandatory } |
| Anchor | ||||
|---|---|---|---|---|
|
computers | object array | Keep calling to get_miscon_computers_next until empty computers array is returned, e.g. computers[] | ||||
latestHostReportingDt | datetime | Latest date and time the computer reported to Gytpol | ||||
latestScanDt | datetime | Gytpol client scans computers for misconfigurations and sends the report to Gytpol backend. This is the date and time of the latest misconfiguration scan reported for this computer. | ||||
computer | string | Computer name | ||||
computerOu | string | Name of organizational unit define on this computer | ||||
domainName | string | For windows computers, Windows domain name | ||||
clientVer | string | Gytpol client version currently installed on this computer | ||||
ipAddress | string | Computer’s IP address | ||||
os | string | Computer’s operating system | ||||
isVdi | bool | Is this computer a VDI | ||||
isServer | bool | Is this computer a server | ||||
isDC | bool | Is this computer a domain controller | ||||
token | string | Encrypted string to use for following calls to the get_misconfigurations_next function | ||||
Request Example
curl --location --request POST "{BASE-URL}/gytpolapi/v2.0/get_miscon_computers_next" --header "x-api-key: jyUbUQNuVjClzQ5f6sXgmcgGzyoFiaYXA+OvxObvLV8=" --data-raw "{ \"token\": \"7h5vmgiKQgvFiTb3xhrSyum52cbfh77xexcus8kGtOP03mliJxbJL99q8wfC2d8kwpNGXa0QF1VuycY6xnosSJePUkaGGUgCQ61rBmVcJI1J6RkUZMWmmGGD3R/+e9b2SrRlamRNusqUBOCphAeyDpBGb7uliNLpfn7wB2JiDGDJRu73Im6UIt3V7ITZDehfsb+JkWXVLlKNIv9+RvxrBCxVa/7StHvyW10cpGF67P9HfLZFbQOCjFsFOs8Mn6amZJrh1bkpasAblUWI0toXZVrlLHr6lfEYZMRnTadcBNTNIUBBWr6ptLUvdcWqEukmdaBublWIQBpAI++Seqc9rMF2WEex9o2n+5NyQBp8+OnuvsUcUybW/MfjG6J/06d07Tf/ks9mQJgZO2vnuJQAPA==\"}"
...
For On-prem customers, please incorporate your port (i.e., 9191) into the BASE-URL as follows: BASE-URL:PORT.
HTTP Return Codes
200 Ok
400 Bad Request
401 Unauthorized
429 Too Many Requests
add_to_group
Use this function to add a computer to a computer group.
...
Note 2: The device name should be added exactly as it appears in the UI, without the FQDN, and the device must have reported to the GYTPOL console previously. Devices that have never reported cannot be added.
Request Structure
groupName | string | Mandatory | Group name |
computerName | string | Mandatory | Computer name, case-insensitive |
...
error | string | Error string, returned only on error |
Request Example
curl --location --request POST "{BASE-URL}/gytpolapi/v2.0/add_to_group" --header "x-api-key: jyUbUQNuVjClzQ5f6sXgmcgGzyoFiaYXA+OvxObvLV8=" --data-raw "{\"groupName\":\"Exchange Servers\",\"computerName\":\"WIN-A951IBBEJC2\"}"
...
| Code Block |
|---|
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("x-api-key", "{x-api-key}")
$headers.Add("Content-Type", "application/json")
$body = "{‘groupName’: ‘{GROUP}’, computerName: ‘{COMPUTER}’}"
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
[System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true}
$response = Invoke-RestMethod -uri "https://{BASE-URL}/gytpolapi/v2.0/add_to_group" -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json |
If you wish to use CSV for faster load of devices, please create a CSV file in the below format:
| Code Block |
|---|
Computername, ws0021, ws0042, ws0336, ws0338 |
...
For On-prem customers, please incorporate your port (i.e., 9191) into the BASE-URL as follows: BASE-URL:PORT.
HTTP Return Codes
200 Ok
400 Bad Request
401 Unauthorized
...