AnkraDocs
Console

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#

GET/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

200 response fields
FieldTypeDescription
is_enabledrequiredbooleanFalse once the account opted out.
changed_atrequiredstring (date-time) | nullWhen 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_credentials on 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

bash
curl 'https://cloud.ankra.app/v1/account/exposure-scanning' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"

Scan the account's public addresses, or opt out#

PUT/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

Request body fields
FieldTypeDescription
is_enabledrequiredbooleanFalse opts the account out.

Responses

200The account's setting afterwards.application/json · ExposureScanning

200 response fields
FieldTypeDescription
is_enabledrequiredbooleanFalse once the account opted out.
changed_atrequiredstring (date-time) | nullWhen someone last changed it; null if nobody has.
  • 400The request is invalid; detail says 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_credentials on 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

bash
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#

GET/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

Parameters
NameInTypeDescription
statequerystringWhich findings to list; open when left out.
cursorquerystringThe next_cursor of the previous page.
limitqueryintegerPage size; the server applies its default and maximum.

Responses

200A page of findings (limit at most 200, default 50).application/json · ExposureFindingList

200 response fields
FieldTypeDescription
itemsrequiredarray of ExposureFinding
idrequiredstring
addressrequiredstringThe public address scanned.
portrequiredinteger
servicerequiredstringThe service the port is known for: ssh, redis, https and so on.
kindrequiredstringWhat 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
severityrequiredstringOne of info, low, medium, high, critical
detailrequiredstringOne line for people: the banner, the server header, the expiry of the certificate.
productrequiredstringThe product the service announced; empty when it did not.
versionrequiredstringThe version the service announced; empty when it did not.
vulnerabilitiesrequiredarray of stringThe 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.
remediationrequiredstringHow to fix it, in plain language.
zonerequiredstring
resource_typerequiredstringWhat holds the address.One of server, load_balancer, floating_ip
resource_idrequiredstring
first_seen_atrequiredstring (date-time)
last_seen_atrequiredstring (date-time)
resolved_atrequiredstring (date-time) | null
resolutionrequiredstring | nullWhy the finding is no longer open: no_longer_seen, address_released or opted_out.
next_cursorrequiredstring | nullPass as ?cursor= for the next page; null on the last page.
  • 400The request is invalid; detail says 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_credentials on 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

bash
curl 'https://cloud.ankra.app/v1/exposure-findings' \
  -H "Authorization: Bearer $ANKRA_CLOUD_TOKEN"