...
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
Info |
---|
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.
On-Prem Customers:
To generate an API key in the GYTPOL UI, navigate to the
Note | |||||
---|---|---|---|---|---|
The on-prem server API permits only 100 reads per minute. To prevent surpassing this limit, it's recommended to integrate a timeout or pause within the PS1 script between loops. For example:
|
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.
On-Prem Customers:
To generate an API key in the GYTPOL UI, navigate to the gear icon > Settings > GYTPOL API Keys. To create a new key, click the + (Plus) icon and assign a name that corresponds to the system. The key will expire after 1 year by default.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
Base URL
The Base URL variable in both the scripts and the examples provided below should be set to your GYTPOL URL.
For on-premises customers, it's necessary to append the port after the GYTPOL server URL, like so: https://gytpol.domain.local:9191/gytpolapi/v2.0/<function-name>
.
However, SaaS customers can simply utilize the URL of their tenant without the port: https://gytpol.eu.cloud.gytpol.com/gytpolapi/v2.0/<function-name>
.
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
...
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
...
curl --location --request POST "{BASE-URL}/gytpolapi/v2.0/get_miscon_by_computer" --header "x-api-key: jyUbUQNuVjClzQ5f6sXgmcgGzyoFiaYXA+OvxObvLV8="--data-raw "{ \"computer\": \"YOUR-COMPUTER-of the following structure:
computers | object array | |||
latestHostReportingDt | datetime | Latest date and time the computer reported to Gytpol | ||
latestScanDt | datetime | Gytpol sensor 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 sensor 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 sensor 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\"}"
Powershell:
Code Block |
---|
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]" $headers.Add("x-api-key", "{API KEY}") $body = "{`"computer`": `"{PCName}`"}" $response = Invoke-RestMethod 'https://{BASE-URL}/gytpolapi/v2.0/get_miscon_by_computer' -Method 'POST' -Headers $headers -Body $body $response | ConvertTo-Json |
...
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==\"}"
Powershell:
...
06d07Tf/ks9mQJgZO2vnuJQAPA==\"}"
Powershell:
Code Block |
---|
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("x-api-key", "{API KEY}")
$headers.Add("Content-Type", "application/json")
$body = "{`"Token`":{TOKEN}}"
$response = Invoke-RestMethod 'https://{BASE-URL}/gytpolapi/v2.0/get_misconfigurations_next' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json |
Note: Change BASE-URL to your base URL. Change x-api-key to your API key.
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
Example script to extract a list of all reporting devices and their misconfigurations
Code Block | ||
---|---|---|
| ||
$headers = @{ "x-api-key" = "{API KEY}" "Content-Type" = "application/json" } $body = "{}" $outputData = @() $response = Invoke-RestMethod -Uri 'https://{BASE URL}/gytpolapi/v2.0/get_misconfigurations_start' -Method 'POST' -Headers $headers -Body $body do { # Convert response to JSON and output $response | ConvertTo-Json -Depth 3 # Accumulate data for each iteration $outputData += $response # Prepare next request body $body = @{ token = $response.token } | ConvertTo-Json [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12 [System.Net.ServicePointManager]::ServerCertificateValidationCallback = {$true} # Make next request $response = Invoke-RestMethod -Uri 'https://{BASE- URL}/gytpolapi/v2.0/get_misconfigurations_next' -Method 'POST' -Headers $headers -Body $body } until ($response.computers.Count -eq 0) # Export all the data | ConvertTo-Json |
...
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
to a JSON file
$outputData | ConvertTo-Json | Set-Content -Path "C:\path\to\output_data.json" |
get_miscon_computers_start
...
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 sensor 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 sensor 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 |
...
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")
# Ensure the computer group is created in the UI with at least one device
# Replace {GROUP} with the actual group name, i.e SERVERS
$groupName = "{GROUP}"
# Read computer names from CSV file without headers
$computers = Get-Content -Path "c:\path\to\computers.csv" | Select-Object -Skip 1
# Loop through each computer and add it to the group
foreach ($line in $computers) {
# Split the line by commas and take the first part as the computer name
$computerName = $line.Split(',')[0].Trim()
# Create the body for the API request
$body = @{
groupName = $groupName
computerName = $computerName
} | ConvertTo-Json
# Send the API request
[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
# Optional: Add a 2-second pause between each iteration. Remove the comment if needed.
# Start-Sleep -Seconds 2
} |
Note: Change BASE-URL to your base URL. Change x-api-key to your API key.
...