Introduction

The purpose of this document is to provide instructions to apply API (Application Programming Interface) connection to Remedio server from a third-party tools.

Overview

Remedio API v1.0 covers the following use cases:

Getting misconfigurations for a given computer
Getting misconfigurations for all computers
Getting the list of all computers that had misconfigurations

These use cases are addressed accordingly by the following REST API functions:

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.

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:

# Your existing code here

# Add a pause of 2 seconds (adjust as needed) between each iteration
Start-Sleep -Seconds 2

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.

To generate an API key, please contact your Remedio TAM.

API Port

For SaaS customers, there is no need to specify a port, as the URL utilizes port 443.

Base URL

The Base URL variable in both the scripts and the examples provided below should be set to your Remedio URL.

For on-premises customers, it's necessary to append the port after the Remedio 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.

There is an extended version for this API in V3 requires Backend Version 2.27.17 and above link accessed the same using V3 instead of V2 so the URL changes like so:
https://gytpol.eu.cloud.gytpol.com/gytpolapi/v3.0/get_miscon_by_computer.

Request Structure

JSON string of the following structure:

computer	string	mandatory	Computer name

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 Remedio
	latestScanDt	datetime		Remedio sensor scans computers for misconfigurations and sends the report to Remedio 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		Remedio 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 Remedio backend
		scanTimeDt	datetime	Datetime when Remedio sensor installed on the computer found this misconfiguration

V3 Response Structure

JSON string of the v2 format with the following structure added in miscon array:

computers	object array
	miscon	object array		Array of misconfigurations reported for this computer
		topicTitle	string	The topic Title as reflected by the UI
		description	string	The Topic Description as reflected by the UI
		score	[optional] object	The Topic Score as reflected by the UI as a JSON object like `"score": { "cvss": 7.8 }`
		remediations	string (delimited)	The Topic Remediations as reflected by the UI as a delimited string like `"Remove Cron ... permissions for 'group' and 'others'.\nRemove Cron Dir Write Permissions ... permissions for 'group' and 'others'."`

Request Example

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\"}"

or for the V3:
curl --location --request POST "{BASE-URL}/gytpolapi/v3.0/get_miscon_by_computer" --header "x-api-key: jyUbUQNuVjClzQ5f6sXgmcgGzyoFiaYXA+OvxObvLV8=" --data-raw "{ \"computer\": \"YOUR-COMPUTER-NAME\"}"

Powershell:

$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

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": [

{

"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	Computer name
domainName	string	optional	For windows computers, Windows domain name
selTarget	string	optional	Narrows down returned computers to a specified type. One of following possible values can be passed: All Windows Computers Windows Endpoints Windows Servers Windows Non-VDI Endpoints Windows VDI Endpoints Windows DC Servers Windows Non-DC Servers Debian Linux Computers Red Hat Linux Computers SUSE Linux Computers Linux Unknown Computers MAC Computers
severity	string	optional	Specifies minimal severity of returned misconfigurations. Supported values are: Low Medium High
computerOu	string	optional	Return only computers that belong to the provided Organization Unit
topicCodes	string array	optional	Restrict returned misconfigurations only to specify misconfiguration types. The parameter has a form of: [ "gytHostsFile", "gytSmbAnonymous", "gytTLSSSLClient"]
fromHostReportingDt	string	optional	Return only computers with latest misconfigurations reported after a given date and time. Example: "2023-01-10T19:43:46+02:00" or just “2023-01-01”
toHostReportingDt	string	optional	Return only computers with latest misconfigurations reported before a given date and time. Example: "2023-01-10T19:43:46+02:00" or just “2023-01-01”
returnMutedTopics	bool	optional	Remedio product allows to mute misconfigurations meaning that they will not visually appear in the application. Default value is false meaning that muted misconfiguration will not be returned.

Json in the request body looks like in the following example:

{

"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}"

Powershell:

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"

$headers.Add("x-api-key", "{API KEY}")

$headers.Add("Content-Type", "application/json")

$body = "{`"severity`":`"High`"}"

$response = Invoke-RestMethod 'https://{BASE-URL}/gytpolapi/v2.0/get_misconfigurations_start' -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

{"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

Json in the request body looks like in the following example:

{

"token": "<string> Mandatory

}

API Guide: Classic Endpoints (v1.0 & v2.0 & v3.0 Legacy Support)

Introduction

Overview

API Keys

API Port

Base URL

get_miscon_by_computer

Request Structure

Response Structure

V3 Response Structure

Request Example

Response Example

HTTP Return Codes

get_misconfigurations_start

Request Structure

Response Structure

Request Example

Response Example

HTTP Return Codes

get_misconfigurations_next

Request Structure

Response Structure