UpGuard subsidiaries API
The subsidiaries API from UpGuard — 8 operation(s) for subsidiaries.
OpenAPI Specification
swagger: '2.0'
info:
description: 'Access information from the CyberRisk platform programmatically using this API.
You can find or generate an API key to access this API in your CyberRisk Account Settings.
Please authorize all requests by setting the "Authorization" header to your api key.
The base url for all public endpoints is https://cyber-risk.upguard.com/api/public'
title: UpGuard CyberRisk breaches subsidiaries API
version: 1.13.2
host: cyber-risk.upguard.com
basePath: /api/public
schemes:
- https
consumes:
- application/json
produces:
- application/json
security:
- API key in header: []
tags:
- name: subsidiaries
paths:
/subsidiaries:
get:
description: 'Returns a list of subsidiaries.
Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
tags:
- subsidiaries
summary: Get a list of subsidiaries
operationId: subsidiaries
responses:
'200':
description: A hierarchy of subsidiaries
schema:
$ref: '#/definitions/GetSubsidiariesV1RespBody'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/subsidiary/domain:
get:
description: 'Returns the details for a domain. It will return 422 when requesting details of an inactive domain.
Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
tags:
- subsidiaries
summary: Retrieve details for a domain
operationId: subsidiary_domain_details
parameters:
- type: string
description: The primary hostname of the subsidiary to show the domain detail for.
name: subsidiary_primary_hostname
in: query
required: true
- type: string
description: The hostname for which to return the details, e.g. "upguard.com"
name: hostname
in: query
required: true
responses:
'200':
description: Domain details
schema:
$ref: '#/definitions/GetDomainDetailsV1RespBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/subsidiary/domain/labels:
put:
description: 'Assign labels to a domain. To remove all labels pass an empty list.
Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
tags:
- subsidiaries
summary: Assign labels to a domain
operationId: subsidiary_domain_update_labels
parameters:
- type: string
description: The primary hostname of the subsidiary to update the domain labels for.
name: subsidiary_primary_hostname
in: query
required: true
- type: string
description: The hostname to update labels for
name: hostname
in: query
required: true
- type: array
items:
type: string
description: The labels to assign to the domain. You can pass an empty array to remove all labels.
name: labels
in: query
required: true
responses:
'204':
description: ' Successful response is empty'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/subsidiary/domains:
get:
description: 'Returns a list of domains for a subsidiary.
Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
tags:
- subsidiaries
summary: List subsidiary domains
operationId: subsidiary_domains
parameters:
- type: string
description: The primary hostname of the subsidiary to show domains for.
name: subsidiary_primary_hostname
in: query
required: true
- type: boolean
default: true
description: Retrieve active domains
name: active
in: query
- type: boolean
default: true
description: Retrieve inactive domains
name: inactive
in: query
- type: array
items:
type: string
description: Filter result by the provided labels
name: labels
in: query
- type: string
description: The `page_token` from a previous request, use this to get the next page of results.
name: page_token
in: query
- maximum: 2000
minimum: 10
type: integer
format: int64
default: 1000
description: The number of results to return per page.
name: page_size
in: query
- enum:
- domain
- active
- automated_score
- scanned_at
type: string
default: domain
description: 'The value to sort the domains by
If not specified will default to `domain` and set `sort_desc` to `true`'
name: sort_by
in: query
- type: boolean
default: false
description: Whether or not to sort the results in descending order
name: sort_desc
in: query
responses:
'200':
description: A list of domains
schema:
$ref: '#/definitions/GetDomainsV1RespBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/subsidiary/ip:
get:
description: 'Returns the details of the IP address. It will return 422 when requesting details of an inactive IP address.
Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
tags:
- subsidiaries
summary: Retrieve details for an IP address
operationId: subsidiary_ip_details
parameters:
- type: string
description: The primary hostname of the subsidiary to show the IP detail for.
name: subsidiary_primary_hostname
in: query
required: true
- type: string
description: The IP address to get details for
name: ip
in: query
required: true
responses:
'200':
description: IP details
schema:
$ref: '#/definitions/GetIpDetailsV1RespBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/subsidiary/ip/labels:
put:
description: 'Assign labels to an IP. To remove all labels pass an empty list.
Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
tags:
- subsidiaries
summary: Assign labels to an IP
operationId: subsidiary_ip_update_labels
parameters:
- type: string
description: The primary hostname of the subsidiary to update the IP labels for.
name: subsidiary_primary_hostname
in: query
required: true
- type: integer
format: int64
description: The IP to update labels for
name: ip
in: query
required: true
- type: array
items:
type: string
description: The labels to assign to the IP. You can pass an empty array to remove all labels.
name: labels
in: query
required: true
responses:
'204':
description: ' Successful response is empty'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/subsidiary/ips:
get:
description: 'Returns a list of ips for a subsidiary.
Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
tags:
- subsidiaries
summary: List subdiary ips
operationId: subsidiary_ips
parameters:
- type: string
description: The primary hostname of the subsidiary to show ips for.
name: subsidiary_primary_hostname
in: query
required: true
- type: array
items:
type: string
description: Filter result by the provided labels
name: labels
in: query
- type: string
description: The `page_token` from a previous request, use this to get the next page of results.
name: page_token
in: query
- maximum: 2000
minimum: 10
type: integer
format: int64
default: 1000
description: The number of results to return per page.
name: page_size
in: query
- enum:
- ip
- owner
- country
- asn
- as_name
- automated_score
type: string
default: ip
description: 'The value to sort the IPs by
If not specified will default to `ip` and set `sort_desc` to `true`'
name: sort_by
in: query
- type: boolean
default: false
description: Whether or not to sort the results in descending order
name: sort_desc
in: query
responses:
'200':
description: A list of ips
schema:
$ref: '#/definitions/GetIPsV1RespBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
/subsidiary/ranges:
get:
description: 'Returns a list of ip ranges for a subsidiary.
Required API key permissions: `BreachRisk` (select when creating API key in Account Settings)'
tags:
- subsidiaries
summary: List subsidiary ip ranges
operationId: subsidiary_ranges
parameters:
- type: string
description: The primary hostname of the subsidiary to show ranges for.
name: subsidiary_primary_hostname
in: query
required: true
- type: array
items:
type: string
description: Filter result by the provided labels
name: labels
in: query
- type: string
description: The `page_token` from a previous request, use this to get the next page of results.
name: page_token
in: query
- maximum: 2000
minimum: 10
type: integer
format: int64
default: 1000
description: The number of results to return per page.
name: page_size
in: query
- enum:
- start
- end
- num_ips
- owner
- country
- asn
- as_name
type: string
default: num_ips
description: 'The value to sort the IP ranges by
If not specified will default to `num_ips` and set `sort_desc` to `true`'
name: sort_by
in: query
- type: boolean
default: false
description: Whether or not to sort the results in descending order
name: sort_desc
in: query
responses:
'200':
description: A list of ranges
schema:
$ref: '#/definitions/GetRangesV1RespBody'
'403':
description: Your API key does not have permission to perform this action.
schema:
$ref: '#/definitions/endpointError'
'422':
description: An invalid parameter was supplied or a mandatory parameter was missing
schema:
$ref: '#/definitions/endpointError'
'429':
description: Too many requests have been made to this endpoint.
schema:
$ref: '#/definitions/endpointError'
'500':
description: An internal system error occurred
schema:
$ref: '#/definitions/endpointError'
definitions:
Category:
description: Category values cannot be changed after first use, as they're referenced in storage.
type: string
title: Category values represent risk categories.
DomainScore:
type: object
properties:
automated_score:
description: The score of the domain
type: integer
format: int64
hostname:
description: The hostname of the domain
type: string
Domain:
type: object
properties:
active:
description: The status of the domain
type: boolean
automated_score:
description: The score of the domain. If the domain is active or hasn't been scanned yet this field will be absent
type: integer
format: int64
hostname:
description: The hostname
type: string
labels:
description: The labels associated with the domain
type: array
items:
type: string
primary_domain:
description: Flag indicating the primary domain for the account
type: boolean
scanned_at:
description: The time the domain was scanned. If the domain is inactive or hasn't been scanned yet this field will be absent
type: string
format: date-time
GetSubsidiariesV1RespBody:
type: object
properties:
account:
$ref: '#/definitions/Account'
Severity:
type: integer
format: int64
GetRangesV1RespBody:
type: object
properties:
next_page_token:
description: 'The token to be used to retrieve the next page of results.
Will not be returned if there are no more results.'
type: string
ranges:
description: The list of ranges
type: array
items:
$ref: '#/definitions/ApiRange'
total_results:
description: The total number of ranges found.
type: integer
format: int64
endpointError:
description: Error details coming from an endpoint
type: object
properties:
error:
description: A description of the error
type: string
GetIPsV1RespBody:
type: object
properties:
ips:
description: The list of ips
type: array
items:
$ref: '#/definitions/IP'
next_page_token:
description: 'The token to be used to retrieve the next page of results.
Will not be returned if there are no more results.'
type: string
total_results:
description: The total number of ips found.
type: integer
format: int64
GetDomainsV1RespBody:
type: object
properties:
domains:
description: The list of domains
type: array
items:
$ref: '#/definitions/Domain'
next_page_token:
description: 'The token to be used to retrieve the next page of results.
Will not be returned if there are no more results.'
type: string
total_results:
description: The total number of domains found.
type: integer
format: int64
ApiRange:
type: object
properties:
as_name:
description: The name of the AS the range belongs to. If no AS is available for a range this field will be omitted.
type: string
asn:
description: The ASN the range belongs to. If no ASN is available for a range this field will be omitted.
type: integer
format: int64
country:
description: The country the range belongs to. If no country is available for a range this field will be omitted.
type: string
end:
description: The range end.
type: string
labels:
description: The labels associated with the range.
type: array
items:
type: string
num_ips:
description: The number of IPs in this range
type: integer
format: int64
owner:
description: The owner of the range.
type: string
sources:
description: The sources of the range.
type: array
items:
$ref: '#/definitions/IPSource'
start:
description: The range start.
type: string
Account:
type: object
properties:
children:
$ref: '#/definitions/AccountHierarchy'
name:
description: The name of the account
type: string
primary_domain:
description: The primary domain of the account
type: string
GetIpDetailsV1RespBody:
type: object
properties:
as_name:
description: The name of the AS the IP belongs to. If no AS is available for an IP this field will be omitted.
type: string
asn:
description: The ASN the IP belongs to. If no ASN is available for an IP this field will be omitted.
type: integer
format: int64
automated_score:
description: The score of the ip. If the ip is inactive or hasn't been scanned yet this field will be absent
type: integer
format: int64
check_results:
description: The results of the IP scan. This field will be omitted if the IP has not been scanned or no results are available, e.g. DNS source IP.
type: array
items:
$ref: '#/definitions/CheckResult'
country:
description: The country the IP belongs to. If no country is available for an IP this field will be omitted.
type: string
domains:
description: The list of domains associated with this IP. This field will be omitted if no domains are associated with the IP.
type: array
items:
$ref: '#/definitions/DomainScore'
ip:
description: The IP.
type: string
labels:
description: The labels associated with the IP.
type: array
items:
type: string
owner:
description: The owner of the IP.
type: string
services:
description: The list of discovered services IP. If no services were detected for the IP this field will be omitted.
type: array
items:
type: string
sources:
description: The sources of the IP.
type: array
items:
$ref: '#/definitions/IPSource'
waived_check_results:
description: The waived risks for this IP. This field will be omitted if no waived risks are present.
type: array
items:
$ref: '#/definitions/CheckResult'
IP:
type: object
properties:
as_name:
description: The name of the AS the IP belongs to. If no AS is available for an IP this field will be omitted.
type: string
asn:
description: The ASN the IP belongs to. If no ASN is available for an IP this field will be omitted.
type: integer
format: int64
automated_score:
description: The score of the ip. If the ip is inactive or hasn't been scanned yet this field will be absent
type: integer
format: int64
country:
description: The country the IP belongs to. If no country is available for an IP this field will be omitted.
type: string
ip:
description: The IP.
type: string
labels:
description: The labels associated with the IP.
type: array
items:
type: string
owner:
description: The owner of the IP.
type: string
services:
description: The list of discovered services IP. If no services were detected for the IP this field will be omitted.
type: array
items:
type: string
sources:
description: The sources of the IP.
type: array
items:
$ref: '#/definitions/IPSource'
CheckResult:
type: object
properties:
actual:
description: The found properties of the check
type: array
items:
$ref: '#/definitions/Property'
category:
$ref: '#/definitions/Category'
checked_at:
description: The time the check was performed in RFC3339 format
type: string
format: date-time
description:
description: The description of the check performed
type: string
expected:
description: The expected properties of the check
type: array
items:
$ref: '#/definitions/Property'
id:
description: The ID of the check
type: string
pass:
description: Flag indicating whether the check passed or not
type: boolean
riskSubtype:
description: The subtype of the risk, e.g. the subtype of the verified_vuln:CVE-2021-34473 is CVE-2021-34473. This field will be empty if the risk has no subtype, e.g. for wp_version_exposed, or for generic risks like verified_vuln:* where the subtype is only determined when the full risk is specified.
type: string
example: CVE-2021-34473
riskType:
description: The type of the risk, e.g. the type of the verified_vuln:CVE-2021-34473 is verified_vuln
type: string
example: verified_vuln
severity:
$ref: '#/definitions/Severity'
severityName:
description: The severity fo the risk in human-readable form
type: string
enum:
- pass
- info
- low
- medium
- high
- critical
sources:
description: 'Sources contains information about the source of a check
e.g. the IP addresses it was found on, or a domain name'
type: array
items:
type: string
title:
description: The title of the check
type: string
Property:
type: object
properties:
property:
description: The name of the property
type: string
value:
description: The value of the property
type: string
IPSource:
type: string
AccountHierarchy:
type: array
items:
$ref: '#/definitions/Account'
GetDomainDetailsV1RespBody:
type: object
properties:
a_records:
description: The list of A records associated with the domain. This field will be omitted if no A records were associated with the domain
type: array
items:
type: string
automated_score:
description: The score for the domain. If the domain has not been scanned or no score is present this field will be omitted.
type: integer
format: int64
check_results:
description: The results of the domain scan. This field will be omitted if the domain has not been scanned or no results are available.
type: array
items:
$ref: '#/definitions/CheckResult'
hostname:
description: The hostname of the domain
type: string
labels:
description: The labels associated with the domain. This field will be omitted if no labels are present.
type: array
items:
type: string
scanned_at:
description: The time the domain was scanned in RFC3339 format
type: string
format: date-time
waived_check_results:
description: The waived risks for this domain. This field will be omitted if no waived risks are present.
type: array
items:
$ref: '#/definitions/CheckResult'
securityDefinitions:
API key in header:
type: apiKey
in: header
name: Authorization