API reference · Access and identity
Exposure scanning
3 operations of the Ankra Cloud API: External exposure scanning: the control plane connects to commonly exposed ports on the account's public addresses once a day, reads only what each service volunteers, and reports what it found with how to fix it. It notifies and never blocks. On by default; an account may opt out.
Whether the account's public addresses are scanned for exposed services#
/v1/account/exposure-scanning- Operation
get_exposure_scanning- Credentials
- API token, Portal session
- Requires
- Permission
read
Responses
200The account's setting. Scanning is on until someone opts out.application/json · ExposureScanning
| Field | Type | Description |
|---|---|---|
is_enabledrequired | boolean | False once the account opted out. |
changed_atrequired | string (date-time) | null | When someone last changed it; null if nobody has. |
- 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/account/exposure-scanning' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"Scan the account's public addresses, or opt out#
/v1/account/exposure-scanning- Operation
set_exposure_scanning- Credentials
- API token, Portal session
- Requires
- Permission
members.manage
Opting out stops the scans at once and resolves the account's open findings (opted_out). Recorded in the account's audit log (account.exposure_scanning.update).
Request bodyapplication/json · SetExposureScanning
| Field | Type | Description |
|---|---|---|
is_enabledrequired | boolean | False opts the account out. |
Responses
200The account's setting afterwards.application/json · ExposureScanning
| Field | Type | Description |
|---|---|---|
is_enabledrequired | boolean | False once the account opted out. |
changed_atrequired | string (date-time) | null | When someone last changed it; null if nobody has. |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl -X PUT 'https://cloud.ankra.app/v1/account/exposure-scanning' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
"is_enabled": false
}'What the exposure scan found on the account's public addresses, newest first#
/v1/exposure-findings- Operation
list_exposure_findings- Credentials
- API token, Portal session
- Requires
- Permission
read
The control plane connects to a fixed list of commonly exposed ports on every public IPv4 and IPv6 address the account's servers, floating IPs and load balancers hold, about once a day, and reads only what each service volunteers. Each finding names the address, the port, what was found, its severity and how to fix it. A finding stays open until a scan no longer sees it. vulnerabilities is empty unless the announced product and version are in a conservative catalogue; a distribution's build makes no claim, because distributions patch without changing the version. Nothing is ever blocked. See docs/operations/exposure-scanning.md.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
state | query | string | Which findings to list; open when left out. |
cursor | query | string | The next_cursor of the previous page. |
limit | query | integer | Page size; the server applies its default and maximum. |
Responses
200A page of findings (limit at most 200, default 50).application/json · ExposureFindingList
| Field | Type | Description |
|---|---|---|
itemsrequired | array of ExposureFinding | |
idrequired | string | |
addressrequired | string | The public address scanned. |
portrequired | integer | |
servicerequired | string | The service the port is known for: ssh, redis, https and so on. |
kindrequired | string | What a scan found on a port. New kinds may be added; treat an unknown one as a plain message.One of open_port, database_exposed, unauthenticated_database, docker_api_exposed, telnet_exposed, remote_access_exposed, unauthenticated_remote_access, file_sharing_exposed, expired_tls_certificate, self_signed_tls_certificate, known_vulnerable_version |
severityrequired | string | One of info, low, medium, high, critical |
detailrequired | string | One line for people: the banner, the server header, the expiry of the certificate. |
productrequired | string | The product the service announced; empty when it did not. |
versionrequired | string | The version the service announced; empty when it did not. |
vulnerabilitiesrequired | array of string | The CVE identifiers of that product and version, from a conservative catalogue. Empty for every kind but known_vulnerable_version, and for a distribution's build. |
remediationrequired | string | How to fix it, in plain language. |
zonerequired | string | |
resource_typerequired | string | What holds the address.One of server, load_balancer, floating_ip |
resource_idrequired | string | |
first_seen_atrequired | string (date-time) | |
last_seen_atrequired | string (date-time) | |
resolved_atrequired | string (date-time) | null | |
resolutionrequired | string | null | Why the finding is no longer open: no_longer_seen, address_released or opted_out. |
next_cursorrequired | string | null | Pass as ?cursor= for the next page; null on the last page. |
- 400The request is invalid;
detailsays why. - 401Not signed in, or the credential is invalid or expired.
- 403The role lacks the permission, the token is read-only (a read-only token also gets
reason: read_only_token_cannot_read_credentialson every credential read), the CSRF header is missing, a support session may not do this, or the route needs a verified email address and the caller's is not (reason: email_unverified). - 429Rate limited. On a customer operation the credential (the API token, or the signed-in user for a session) is over its requests per minute and the
X-RateLimit-*headers say when the window ends; on a sign-in route the client network is over its attempts or the email is locked out. - defaultAny other error, usually 500.
Example
curl 'https://cloud.ankra.app/v1/exposure-findings' \
-H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"