Skip to main content
GET
/
v2
/
assets
cURL
curl --request GET \
  --url https://client.synack.com/api/asset/v2/assets \
  --header 'Authorization: Bearer <token>'
[
  {
    "organizationUid": "<string>",
    "assetType": "cloudaccount",
    "origin": "provided",
    "createdAt": "2023-11-07T05:31:56Z",
    "createdBy": "<string>",
    "uid": "<string>",
    "location": "<string>",
    "inProduction": true,
    "active": true,
    "label": "<string>",
    "description": "<string>",
    "lifecycleState": "confirmed",
    "criticality": "undefined",
    "changeStatus": "unchanged",
    "anyListingActive": false,
    "anyListingActiveWithin2Years": false,
    "scanStateUpdatedAt": "2023-11-07T05:31:56Z",
    "lastCheckedAt": "2023-11-07T05:31:56Z",
    "lastReachableAt": "2023-11-07T05:31:56Z",
    "lastSuccessfulScan": "2023-11-07T05:31:56Z",
    "lastFailedScan": "2023-11-07T05:31:56Z",
    "firstSeen": "2023-11-07T05:31:56Z",
    "lastSeen": "2023-11-07T05:31:56Z",
    "status": "unchecked",
    "errorCode": 123,
    "listings": [
      {
        "listingUid": "<string>",
        "scope": "in",
        "scopeRules": [
          {
            "uid": "<string>",
            "rule": "<string>",
            "scope": "in",
            "appliesTo": "scanners",
            "createdAt": "2023-11-07T05:31:56Z",
            "createdBy": "<string>",
            "updatedAt": "2023-11-07T05:31:56Z",
            "updatedBy": "<string>"
          }
        ],
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z"
      }
    ],
    "scopeRules": [
      {
        "uid": "<string>",
        "rule": "<string>",
        "scope": "in",
        "appliesTo": "scanners"
      }
    ],
    "relationships": [
      {
        "sourceAssetUid": "<string>",
        "targetAssetUid": "<string>",
        "startsAt": "2023-11-07T05:31:56Z",
        "relationshipType": "discoveredBy",
        "createdAt": "2023-11-07T05:31:56Z",
        "createdBy": "<string>",
        "assetScanner": "burp",
        "uid": "<string>",
        "endsAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "updatedBy": "<string>"
      }
    ],
    "externalRelationships": [
      {
        "type": "discoveredBy",
        "sourceAssetUid": "<string>",
        "targetUid": "<string>",
        "targetService": "assetDiscovery",
        "startsAt": "2023-11-07T05:31:56Z",
        "createdAt": "2023-11-07T05:31:56Z",
        "createdBy": "<string>",
        "uid": "<string>",
        "endsAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "updatedBy": "<string>"
      }
    ],
    "gateways": [
      {
        "gatewayId": "<string>",
        "listingUid": "<string>"
      }
    ],
    "updatedAt": "2023-11-07T05:31:56Z",
    "updatedBy": "<string>",
    "cloudAccount": {
      "credentialData": "TXkgdm9pY2UgaXMgbXkgcGFzc3dvcmQu",
      "cloudPlatform": "aws",
      "cloudCredentialFormat": "aws_assume_role"
    }
  }
]

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Query Parameters

​
organizationUid[]
string[]

Unique identifier for an organization. If not supplied the request will apply to all organizations the user is authorized to access.

Unique identifier for an organization.

​
listingUid[]
string[]

Unique identifier for an listing. If not supplied the request will apply to all listings the user is authorized to access.

Unique identifier for an listing.

​
assetType[]
enum<string>[]

Restrict the returned asset summaries to only assets of the specified type.

Available options:
cloudaccount,
host,
network,
mobileapp,
webapp
​
hostType[]
enum<string>[]

Restrict the returned asset summaries to only the types of host assets requested when assetType also includes host.

Available options:
ip,
cidr,
fqdn,
as
​
search
string

Optional query parameter for a search string that will be used to match within the label or location properties of assets. If this query parameter is provided, any location query parameter will be ignored.

​
active
boolean

Optional parameter that determines whether the response includes assets regardless of active state (the default, if this query parameter is not provided); active assets only if true; or inactive assets only if false.

​
inProduction
boolean

Optional query parameter that determines whether production or non-production assets will be included in the response.

​
maxHostDiscoveryAgeMins
integer
default:0

Optional query parameter to get host assets which are discovered by cloudEnumeration scanner shifted by maxHostDiscoveryAgeMins. Assets which are added via boss or discovered by other type of scanners will be included in response. E.g. CloudEnumeration hosts are valid for 1 hour from each time they are discovered, maxHostDiscoveryAgeMins=0 means that if the end time of the relationship has passed, the asset will not be returned - maxHostDiscoveryAgeMins=60 however, would return assets that were still valid 60 minutes ago

​
scope[]
enum<string>[]

Restrict the returned assets to only assets associated to listings by the specified scopes.

Set to in-scope means automated and manual testing should occur; out-of-scope means automated and manual testing must not occur; discovered means observed through automated discovery and may be automatically removed if not observed again during subseqent discovery activities.

Available options:
in,
out,
discovered,
blocked
​
cloudPlatform[]
enum<string>[]

Restrict the returned assets to only assets enumerated from a particular cloud platform.

Identifies cloud platform

Available options:
aws,
azure,
gcp
​
location
string

Prefix search of the derived location property.

​
errorCode[]
integer<int32>[]

Filter assets to only include assets with matching error codes.

Optional numeric error code set by an automated process such as scanning or checking.

​
portNumber[]
integer<int32>[]

Filter assets to only include hosts with open ports matching the port number.

Required range: 0 <= x <= 65535
​
maxOpenPorts
integer<int32>

Max open ports from a single IP address.

Required range: 0 <= x <= 65535
​
hasNetwork
boolean

Filter assets to include/exclude those with networks. Deprecating.

​
networkUid[]
string[]

Unique identifier for a network. If not supplied the request will apply to all networks the user is authorized to access. Deprecating.

Unique Identifier.

​
gatewayId[]
string[]

Unique gateway id. If not supplied the request will apply to all gateways.

Identifier for Launchpoint-managed VPN gateway.

​
earliestCreatedAt
string<date-time>

Filter assets with a createdAt date greater or equal to this value

​
latestCreatedAt
string<date-time>

Filter assets with a createdAt date less than or equal to this value

​
userUid
string

Restricts the credentials to only those available to the user. This query parameter is ignored if the user is a researcher. Unique identifier for a user.

​
relationshipTargetAssetUid
string

Filter assets which have a relationship with targetAssetUid equal to this value.

Unique identifier for an asset.

​
relationshipType
enum<string>

Filter assets which have a relationship of this type.

Type or relationship between assets.

Available options:
discoveredBy
​
perPage
integer<int32>

Requested page size for pagination. A server-selected default of 100 will be used when no perPage is requested via query parameter.

Required range: 1 <= x <= 5000
​
page
integer<int32>

Page to retrieve in paginated response. A server-selected default of 1 will be used when no page is requested via query parameter.

Required range: x >= 1
​
sort
enum<string>

Optional property to sort results by.

Available options:
location,
label,
createdAt,
updatedAt,
lastReachableAt,
lastScan
​
sortDir
enum<string>
default:asc

Direction of sort-order for items in the response.

Available options:
asc,
desc
​
origin
enum<string>

Optional property to filter results by human created or system discovered assets.

Available options:
provided,
discovered
​
lifecycleState[]
enum<string>[]

Optional property to filter results by asset lifecycle state. When not supplied, all assets except archived will be returned.

Available options:
confirmed,
unconfirmed,
archived,
ignored
​
omitFields
enum<string>[]

Fields to omit from response.

Available options:
ALL,
relationships,
externalRelationships,
ports,
networks,
scopeRules,
binaries,
userRoles
​
ipRanges[]
string[]

Restrict the returned asset summaries to only assets of the specified ip ranges.

IP Range could be a CIDR or an IP Range

Response

Paginated assets.

  • Option 1
  • Option 2
  • Option 3
  • Option 4
  • Option 5
​
organizationUid
string
required

Unique identifier for an organization.

​
assetType
enum<string>
required

Derived from the properties associated with the asset.

Available options:
cloudaccount,
host,
network,
mobileapp,
webapp
​
origin
enum<string>
default:provided
required

Indicates the origin for the asset, i.e. whether the asset was provided manually or it was discovered by some sort of automation.

Available options:
provided,
discovered
​
createdAt
string<date-time>
required

Automatically set by the server to the time the request was processed whenever the resource was created.

​
createdBy
string
required

Automatically set by the server to the requesting user whenever the resource is updated. May be a user account or a service account if the action is performed by an automated.

​
uid
string

Unique Identifier.

​
location
string

Derived human-readable text representation of the asset, based on assetType and other properties.

​
inProduction
boolean
default:true

Indicates whether the asset resides in a production environment.

​
active
boolean
default:true

Active assets may participate in listings. When inactive, the asset is essentially soft-deleted and may not be scanned or subject to new research by SRT.

​
label
string

Optional label for the asset. If present, label is part of the derived property of asset location, which enables creation of multiple assets with different labels under a single organization.

​
description
string

Optional description for the asset.

​
lifecycleState
enum<string>
default:confirmed

Indicates the asset position in asset lifecycle FSM.

Available options:
confirmed,
unconfirmed,
ignored,
archived
​
criticality
enum<string>
default:undefined

Indicates importance of the asset to the customer.

Available options:
high,
medium,
low,
undefined
​
changeStatus
enum<string>
default:unchanged

Indicates whether the asset is newly discovered, has changed since last evaluated, or is unchanged.

Available options:
new,
changed,
unchanged
​
anyListingActive
boolean
default:false

This field is used for scheduling Fingerprinting scans. A calculated field based on if the asset has any listings in which it is active. This field is read only and relates only to assets created after Apr 1 2023.

​
anyListingActiveWithin2Years
boolean
default:false

This field is used for scheduling Fingerprinting scans. A calculated field based on if the asset has any active listings or listings deactivated less than 2 years ago. This field is read only and relates only to assets created prior to Apr 1 2023.

​
scanStateUpdatedAt
string<date-time>

The date time the scan state was updated.

​
lastCheckedAt
string<date-time>

The last date time the asset was checked.

​
lastReachableAt
string<date-time>

The last date time the asset was successfully checked for reachability.

​
lastSuccessfulScan
string<date-time>

The last date time the asset scan was successful.

​
lastFailedScan
string<date-time>

The last date time the asset scan was failed.

​
firstSeen
string<date-time>

For assets with an origin of discovered. The date time when the asset was first discovered.

​
lastSeen
string<date-time>

For assets with an origin of discovered. The date time when the asset was last discovered or fingerprinted.

​
status
enum<string>

Status reported by automated checkers.

Available options:
unchecked,
invalid,
valid
​
errorCode
integer<int32>

Optional numeric error code set by an automated process such as scanning or checking.

​
listings
object[]

Array of listings the asset belongs to.

​
scopeRules
object[]

Rules that modify the scope of security research for this asset.

​
relationships
object[]

Relationships which this asset participates in, either as a source or as a target.

​
externalRelationships
object[]

External relationships which this asset participates in as a source. When used in postAssetBulk request, AssetID and AssetUID will be set automatically.

​
gateways
object[]

Array of Launchpoint-managed VPN gateways per listing.

​
updatedAt
string<date-time>

Automatically set by the server to the time the request was processed whenever the resource is updated.

​
updatedBy
string

Automatically set by the server to the requesting user whenever the resource is updated. May be a user account or a service account if the action is performed by an automated.

​
cloudAccount
object

Keeps credentials for accessing the cloud provider. Mandatory for assets of 'cloudaccount' type.