> ## Documentation Index > Fetch the complete documentation index at: https://docs.synack.com/llms.txt > Use this file to discover all available pages before exploring further. # Get Assets > Retrieve the list of assets for one or more organizations, considering filtering and pagination query parameters. When an organization-level OAuth2 scope is provided, the results will be restricted to those organizations the user is authorized for. Similarly, if a listing- level OAuth2 scope is provided, the results will be restricted to those listings the user is authorized for. Additional query parameters generally restrict the resulting set of assets according to AND semantics. Use of organizationUid and listingUid query parameters will further restrict the results. If neither are specified, the returned assets are the set of assets the user is allowed to access with organization OR listing specific privileges. If listing UIDs are supplied without organization UIDs, then only the assets assigned to those listings (which the user is authorized for) will be returned. Conversely, if organization UIDs are supplied without listing UIDs, then only the assets owned by those organizations (which the the user is authorized for) will be returned. Should both organization UIDs and listing UIDs be supplied, then the set of assets returned is restricted to assets assigned to any of the supplied listings, AND owned by any of the supplied organizations, further restricted to only those the user is authorized to access. Researcher users are restricted to only viewing credentials of in scope assets for listings to which they have been assigned. ## OpenAPI ````yaml /asset-v2-openapi.yaml get /v2/assets openapi: 3.0.3 info: title: Asset Service version: 2.1.020 contact: name: Synack Engineering email: engineering@synack.com servers: - url: https://client.synack.com/api/asset description: Commercial - url: https://client.synack.us/api/asset description: FedRAMP (Medium) security: [] tags: - name: asset-relationships description: Relationships between assets. - name: Assets description: Assets managed by Synack. - name: cloudaccounts description: Cloud account assets. - name: credentials description: Credentials are restricted to authorized users. - name: Hosts description: Host assets. - name: Assessments description: Assets are associated with listings. - name: mobileapps description: Mobile application assets. - name: networks description: Network assets. - name: ports description: Ports for single host assets. - name: scoperules description: >- Scope-rules provide fine grained control for what is in and out of scope for an asset. - name: scripts description: Scripts for mobile and web applications. - name: userroles description: Defines persona-specific user roles for asset credential management. - name: users description: Users of credentials. - name: webapps description: Web application assets. paths: /v2/assets: get: tags: - Assets - cloudaccounts - Hosts - mobileapps - networks - webapps description: > Retrieve the list of assets for one or more organizations, considering filtering and pagination query parameters. When an organization-level OAuth2 scope is provided, the results will be restricted to those organizations the user is authorized for. Similarly, if a listing- level OAuth2 scope is provided, the results will be restricted to those listings the user is authorized for. Additional query parameters generally restrict the resulting set of assets according to AND semantics. Use of organizationUid and listingUid query parameters will further restrict the results. If neither are specified, the returned assets are the set of assets the user is allowed to access with organization OR listing specific privileges. If listing UIDs are supplied without organization UIDs, then only the assets assigned to those listings (which the user is authorized for) will be returned. Conversely, if organization UIDs are supplied without listing UIDs, then only the assets owned by those organizations (which the the user is authorized for) will be returned. Should both organization UIDs and listing UIDs be supplied, then the set of assets returned is restricted to assets assigned to any of the supplied listings, AND owned by any of the supplied organizations, further restricted to only those the user is authorized to access. Researcher users are restricted to only viewing credentials of in scope assets for listings to which they have been assigned. operationId: getAssets parameters: - $ref: '#/components/parameters/OrganizationUIDQuery' - $ref: '#/components/parameters/ListingUIDQuery' - $ref: '#/components/parameters/AssetTypeQuery' - $ref: '#/components/parameters/HostTypeQuery' - in: query name: search schema: type: string required: false description: > 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. - in: query name: active schema: type: boolean required: false description: > 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. - in: query name: inProduction schema: type: boolean required: false description: > Optional query parameter that determines whether production or non-production assets will be included in the response. - in: query name: maxHostDiscoveryAgeMins schema: type: integer default: 0 required: false description: > 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 - in: query name: scope[] schema: type: array items: $ref: '#/components/schemas/Scope' required: false explode: true description: >- Restrict the returned assets to only assets associated to listings by the specified scopes. - in: query name: cloudPlatform[] schema: type: array items: $ref: '#/components/schemas/CloudPlatform' required: false explode: true description: >- Restrict the returned assets to only assets enumerated from a particular cloud platform. - in: query name: location schema: type: string required: false description: | Prefix search of the derived location property. - in: query name: errorCode[] schema: type: array items: $ref: '#/components/schemas/ErrorCode' required: false explode: true description: Filter assets to only include assets with matching error codes. - in: query name: portNumber[] schema: type: array items: $ref: '#/components/schemas/PortNumber' required: false explode: true description: >- Filter assets to only include hosts with open ports matching the port number. - in: query name: maxOpenPorts schema: type: integer format: int32 minimum: 0 maximum: 65535 required: false description: Max open ports from a single IP address. - in: query name: hasNetwork schema: type: boolean required: false description: | Filter assets to include/exclude those with networks. Deprecating. - in: query name: networkUid[] schema: type: array items: $ref: '#/components/schemas/UID' required: false explode: true description: > Unique identifier for a network. If not supplied the request will apply to all networks the user is authorized to access. Deprecating. - in: query name: gatewayId[] schema: type: array items: $ref: '#/components/schemas/GatewayID' required: false explode: true description: | Unique gateway id. If not supplied the request will apply to all gateways. - in: query name: earliestCreatedAt schema: type: string format: date-time required: false description: Filter assets with a createdAt date greater or equal to this value - in: query name: latestCreatedAt schema: type: string format: date-time required: false description: Filter assets with a createdAt date less than or equal to this value - in: query name: userUid schema: $ref: '#/components/schemas/UserUID' required: false description: >- Restricts the credentials to only those available to the user. This query parameter is ignored if the user is a researcher. - in: query name: relationshipTargetAssetUid schema: $ref: '#/components/schemas/AssetUID' required: false description: > Filter assets which have a relationship with targetAssetUid equal to this value. - in: query name: relationshipType schema: $ref: '#/components/schemas/AssetRelationshipType' required: false description: | Filter assets which have a relationship of this type. - $ref: '#/components/parameters/PerPageQuery' - $ref: '#/components/parameters/PageQuery' - in: query name: sort schema: type: string enum: - location - label - createdAt - updatedAt - lastReachableAt - lastScan description: Optional property to sort results by. required: false - $ref: '#/components/parameters/SortDirQuery' - in: query name: origin schema: type: string enum: - provided - discovered description: >- Optional property to filter results by human created or system discovered assets. required: false - name: lifecycleState[] required: false in: query schema: type: array items: type: string enum: - confirmed - unconfirmed - archived - ignored description: >- Optional property to filter results by asset lifecycle state. When not supplied, all assets except `archived` will be returned. - in: query name: omitFields description: Fields to omit from response. schema: type: array items: type: string enum: - ALL - relationships - externalRelationships - ports - networks - scopeRules - binaries - userRoles - $ref: '#/components/parameters/IpRanges' responses: '200': $ref: '#/components/responses/PaginatedArrayOfAssets' '400': $ref: '#/components/responses/400BadRequest' '401': $ref: '#/components/responses/401Unauthorized' '403': $ref: '#/components/responses/403Forbidden' '500': $ref: '#/components/responses/500InternalServerError' '503': $ref: '#/components/responses/503ServiceUnavailable' security: - OAuth2: - asset_gr - asset_or - asset_lr - asset_srt_lr - asset_scan_gr components: parameters: OrganizationUIDQuery: name: organizationUid[] in: query explode: true schema: type: array items: $ref: '#/components/schemas/OrganizationUID' required: false description: >- Unique identifier for an organization. If not supplied the request will apply to all organizations the user is authorized to access. ListingUIDQuery: name: listingUid[] in: query explode: true schema: type: array items: $ref: '#/components/schemas/ListingUID' required: false description: >- Unique identifier for an listing. If not supplied the request will apply to all listings the user is authorized to access. AssetTypeQuery: name: assetType[] in: query schema: type: array items: $ref: '#/components/schemas/AssetType' required: false explode: true description: >- Restrict the returned asset summaries to only assets of the specified type. HostTypeQuery: name: hostType[] in: query schema: type: array items: $ref: '#/components/schemas/HostType' required: false explode: true description: > Restrict the returned asset summaries to only the types of host assets requested when assetType also includes host. PerPageQuery: name: perPage in: query schema: type: integer format: int32 minimum: 1 maximum: 5000 required: false description: > Requested page size for pagination. A server-selected default of 100 will be used when no perPage is requested via query parameter. PageQuery: name: page in: query schema: type: integer format: int32 minimum: 1 required: false description: > Page to retrieve in paginated response. A server-selected default of 1 will be used when no page is requested via query parameter. SortDirQuery: name: sortDir in: query schema: type: string enum: - asc - desc default: asc required: false description: Direction of sort-order for items in the response. IpRanges: name: ipRanges[] in: query schema: $ref: '#/components/schemas/ArrayOfIpRanges' required: false explode: true description: >- Restrict the returned asset summaries to only assets of the specified ip ranges. schemas: Scope: description: > 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. type: string enum: - in - out - discovered - blocked CloudPlatform: description: Identifies cloud platform type: string enum: - aws - azure - gcp ErrorCode: type: integer format: int32 description: >- Optional numeric error code set by an automated process such as scanning or checking. PortNumber: type: integer format: int32 minimum: 0 maximum: 65535 UID: type: string pattern: ^[0-9a-f]{12} readOnly: true description: Unique Identifier. GatewayID: type: string pattern: ^[0-9a-f]{16} description: Identifier for Launchpoint-managed VPN gateway. UserUID: type: string pattern: ^[-_0-9a-z]{1,100} description: Unique identifier for a user. AssetUID: type: string pattern: ^[0-9a-f]{24} description: Unique identifier for an asset. AssetRelationshipType: type: string description: Type or relationship between assets. enum: - discoveredBy OrganizationUID: type: string pattern: ^[-_0-9a-z]{1,50} description: Unique identifier for an organization. ListingUID: type: string pattern: ^[-_0-9a-z]{1,50} description: Unique identifier for an listing. readOnly: true AssetType: type: string enum: - cloudaccount - host - network - mobileapp - webapp HostType: type: string enum: - ip - cidr - fqdn - as ArrayOfIpRanges: type: array items: $ref: '#/components/schemas/IpRange' ArrayOfAssets: type: array items: $ref: '#/components/schemas/SingleAsset' ProblemDetails: type: object description: >- See [RFC 7807: Problem Details for HTTP APIs](https://tools.ietf.org/html/rfc7807) properties: type: type: string readOnly: true title: type: string readOnly: true status: type: integer format: int32 minimum: 100 maximum: 511 description: HTTP Status code. readOnly: true detail: type: string description: Message detailing the problem. readOnly: true instance: type: string description: generated problem instance number to correlate with logs readOnly: true failedValidation: type: array description: Array of failed validation rules. readOnly: true items: $ref: '#/components/schemas/FailedValidation' failedValidations: type: array description: Array of indexed failed validation rules. readOnly: true items: $ref: '#/components/schemas/IndexedFailedValidations' maxBatchSize: type: integer description: Maximum processable batch size. readOnly: true batchSize: type: integer description: Batch size sent when batch is too large. readOnly: true IpRange: type: string description: IP Range could be a CIDR or an IP Range SingleAsset: oneOf: - $ref: '#/components/schemas/CloudAccountAsset' - $ref: '#/components/schemas/HostAsset' - $ref: '#/components/schemas/MobileApplicationAsset' - $ref: '#/components/schemas/NetworkAsset' - $ref: '#/components/schemas/WebApplicationAsset' discriminator: propertyName: assetType mapping: cloudaccount: $ref: '#/components/schemas/CloudAccountAsset' host: $ref: '#/components/schemas/HostAsset' mobileapp: $ref: '#/components/schemas/MobileApplicationAsset' network: $ref: '#/components/schemas/NetworkAsset' webapp: $ref: '#/components/schemas/WebApplicationAsset' FailedValidation: type: object required: - message properties: property: type: string readOnly: true value: type: string readOnly: true message: type: string readOnly: true IndexedFailedValidations: type: object properties: index: type: integer description: >- Zero-based index indicating the which item in request containing an array of items has failed validation. readOnly: true failedValidation: type: array description: Array of failed validation rules. readOnly: true items: $ref: '#/components/schemas/FailedValidation' CloudAccountAsset: allOf: - $ref: '#/components/schemas/Asset' - type: object properties: cloudAccount: $ref: '#/components/schemas/CloudAccountProperties' HostAsset: allOf: - $ref: '#/components/schemas/Asset' - type: object properties: host: $ref: '#/components/schemas/HostProperties' MobileApplicationAsset: allOf: - $ref: '#/components/schemas/Asset' - type: object properties: mobileApplication: $ref: '#/components/schemas/MobileApplicationProperties' NetworkAsset: allOf: - $ref: '#/components/schemas/Asset' - type: object properties: network: $ref: '#/components/schemas/NetworkProperties' WebApplicationAsset: allOf: - $ref: '#/components/schemas/Asset' - type: object properties: webApplication: $ref: '#/components/schemas/WebApplicationProperties' Asset: allOf: - type: object required: - assetType - origin - organizationUid properties: uid: $ref: '#/components/schemas/UID' organizationUid: $ref: '#/components/schemas/OrganizationUID' location: type: string readOnly: true description: >- Derived human-readable text representation of the asset, based on assetType and other properties. assetType: $ref: '#/components/schemas/AssetType' description: Derived from the properties associated with the asset. inProduction: type: boolean description: Indicates whether the asset resides in a production environment. default: true active: description: >- 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. type: boolean default: true label: type: string description: >- 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: type: string description: Optional description for the asset. origin: $ref: '#/components/schemas/AssetOrigin' lifecycleState: $ref: '#/components/schemas/AssetLifecycleState' criticality: $ref: '#/components/schemas/AssetCriticality' changeStatus: $ref: '#/components/schemas/AssetChangeStatus' anyListingActive: type: boolean description: >- 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. default: false anyListingActiveWithin2Years: type: boolean description: >- 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. default: false hasCredentials: type: boolean readOnly: true description: >- Indicates whether any credentials are associated with this asset. Only webapp and mobileapp assets can have credentials; all other asset types will always be false. default: false scanStateUpdatedAt: type: string format: date-time description: The date time the scan state was updated. lastCheckedAt: type: string format: date-time description: The last date time the asset was checked. lastReachableAt: type: string format: date-time description: >- The last date time the asset was successfully checked for reachability. lastSuccessfulScan: type: string format: date-time description: The last date time the asset scan was successful. lastFailedScan: type: string format: date-time description: The last date time the asset scan was failed. firstSeen: type: string format: date-time description: > For assets with an origin of discovered. The date time when the asset was first discovered. lastSeen: type: string format: date-time description: > For assets with an origin of discovered. The date time when the asset was last discovered or fingerprinted. status: $ref: '#/components/schemas/CheckerStatus' errorCode: $ref: '#/components/schemas/ErrorCode' listings: description: Array of listings the asset belongs to. readOnly: true type: array items: $ref: '#/components/schemas/AssetListing' scopeRules: description: Rules that modify the scope of security research for this asset. readOnly: true type: array items: $ref: '#/components/schemas/ScopeRuleSummary' relationships: description: >- Relationships which this asset participates in, either as a source or as a target. readOnly: true type: array items: $ref: '#/components/schemas/SingleAssetRelationship' sourceRelationships: description: >- Relationships which have this asset as a source (SourceAssetID and SourceAssetUID will be set automatically). This property is only available in the postAssetBulk request body and is not returned as part of any responses. writeOnly: true type: array items: $ref: '#/components/schemas/SingleAssetRelationship' externalRelationships: description: >- External relationships which this asset participates in as a source. When used in postAssetBulk request, AssetID and AssetUID will be set automatically. type: array items: $ref: '#/components/schemas/ExternalRelationship' gateways: description: Array of Launchpoint-managed VPN gateways per listing. readOnly: true type: array items: $ref: '#/components/schemas/AssetGateway' - $ref: '#/components/schemas/Updatable' CloudAccountProperties: description: >- Keeps credentials for accessing the cloud provider. Mandatory for assets of 'cloudaccount' type. type: object properties: credentialData: $ref: '#/components/schemas/Base64Data' cloudPlatform: $ref: '#/components/schemas/CloudPlatform' cloudCredentialFormat: $ref: '#/components/schemas/CloudCredentialFormat' required: - credentialData - cloudPlatform - cloudCredentialFormat HostProperties: allOf: - $ref: '#/components/schemas/NetworkRef' - type: object properties: ipAddress: type: string description: IP v4 or v6 address. cidr: type: string description: IP v4 or v6 CIDR notation. ipRanges: $ref: '#/components/schemas/ArrayOfIpRanges' description: List of CIDRs and IP Ranges firstIPAddress: type: string description: The first IP address in the range (CIDRs only). readOnly: true lastIPAddress: type: string description: The last IP address in the range (CIDRs only). readOnly: true fqdn: type: string description: Fully-qualified domain name. hostname: type: string description: Host name. autonomousSystemNumber: type: string description: >- Autonomous System Number in asdot notation. See https://datatracker.ietf.org/doc/rfc5396/. autonomousSystemName: type: string description: >- Name of Autonomous System. See https://datatracker.ietf.org/doc/rfc5396/. cloudInstanceName: description: Name of instance when cloudPlatform is provided. type: string cloudPlatform: $ref: '#/components/schemas/CloudPlatform' operatingSystem: $ref: '#/components/schemas/OperatingSystem' providerName: description: >- Name of the cloud or hosting provider according to fingerprinting. type: string latitude: description: Latitude of geolocated asset according to fingerprinting. type: number format: double longitude: description: Longitude of geolocated asset according to fingerprinting. type: number format: double city: description: City of geolocated asset according to fingerprinting. type: string country: description: Country of geolocated asset according to fingerprinting. type: string state: description: State of geolocated asset according to fingerprinting. type: string ports: type: array items: $ref: '#/components/schemas/Port' description: Ports of a single host. portsOpenTotal: type: integer readOnly: true description: >- The number of open ports (TCP or UDP) for a single IP address host asset. minimum: 0 maximum: 65535 rdnsHostnames: description: Hostnames returned by reverse DNS part of fingerprinting. type: string lastFingerprint: description: Last time a fingerprinting scan checked the asset. type: string format: date-time lastSuccessfulScan: type: string format: date-time description: The last date time the asset scan was successful. lastFailedScan: type: string format: date-time description: The last date time the asset scan was failed. timesFinished: type: integer format: int32 minimum: 0 description: Number of times web application scan finished. timesFailed: type: integer format: int32 minimum: 0 description: Number of times web application scan failed. timesLastFailed: type: integer format: int32 minimum: 0 description: >- Number of times web application scan failed since the last finished scan. scanState: $ref: '#/components/schemas/ScanState' scanStateUpdatedAt: type: string format: date-time description: The date time the scan state was updated. MobileApplicationProperties: allOf: - $ref: '#/components/schemas/ApplicationAsset' - type: object required: - applicationName properties: applicationName: type: string description: Name of the application. operatingSystem: $ref: '#/components/schemas/MobileOperatingSystem' binaries: type: array items: $ref: '#/components/schemas/ApplicationBinary' readOnly: true mfa: type: boolean description: Optional MFA/OTP/CAPTCHA selfRegistration: type: boolean description: Optional self registration ntlm: type: boolean description: Optional new technology lan manager. sslCertificatePinning: type: boolean description: Optional SSL certifications pinning or root detection NetworkProperties: type: object properties: gatewayId: $ref: '#/components/schemas/GatewayID' type: string description: Identifier for Launchpoint-managed VPN gateway. WebApplicationProperties: allOf: - $ref: '#/components/schemas/ApplicationAsset' - $ref: '#/components/schemas/NetworkRef' - type: object required: - url properties: url: type: string reachabilityImageCaptureUrl: type: string format: uri description: Optional URL to image capture of failed reachability check. mfa: type: boolean description: Optional MFA/OTP/CAPTCHA selfRegistration: type: boolean description: Optional self registration ntlm: type: boolean description: Optional new technology lan manager. httpingSettings: $ref: '#/components/schemas/HTTPingSettings' timesFinished: type: integer format: int32 minimum: 0 description: Number of times web application scan finished. timesFailed: type: integer format: int32 minimum: 0 description: Number of times web application scan failed. timesLastFailed: type: integer format: int32 minimum: 0 description: >- Number of times web application scan failed since the last finished scan. scanState: $ref: '#/components/schemas/ScanState' scanStateUpdatedAt: type: string format: date-time description: The date time the scan state was updated. scanLastAcceptedAt: type: string format: date-time description: The last date time the web application was accepted to scan. lastSuccessfulScan: type: string format: date-time description: The last date time the asset scan was successful. lastFingerprint: description: Last time a fingerprinting scan checked the asset. type: string format: date-time AssetOrigin: type: string description: >- Indicates the origin for the asset, i.e. whether the asset was provided manually or it was discovered by some sort of automation. default: provided enum: - provided - discovered AssetLifecycleState: type: string description: Indicates the asset position in asset lifecycle FSM. default: confirmed enum: - confirmed - unconfirmed - ignored - archived AssetCriticality: type: string description: Indicates importance of the asset to the customer. default: undefined enum: - high - medium - low - undefined AssetChangeStatus: type: string description: >- Indicates whether the asset is newly discovered, has changed since last evaluated, or is unchanged. default: unchanged enum: - new - changed - unchanged CheckerStatus: type: string enum: - unchecked - invalid - valid description: Status reported by automated checkers. AssetListing: type: object description: Listings the asset is assigned to. properties: listingUid: $ref: '#/components/schemas/ListingUID' scope: $ref: '#/components/schemas/Scope' scopeRules: description: Out of scope locations for this asset. type: array items: $ref: '#/components/schemas/ScopeRule' createdAt: type: string format: date-time readOnly: true description: >- Automatically set by the server to the time the listing asset association was created. updatedAt: type: string format: date-time readOnly: true description: >- Automatically set by the server to the time the listing asset association is updated. ScopeRuleSummary: type: object description: >- Part of the scope of an asset that is included/excluded from a specific activity. required: - uid - rule - scope - appliesTo properties: uid: $ref: '#/components/schemas/UID' rule: $ref: '#/components/schemas/WebRULE' description: >- A textual definition of the scope rule. Format will vary by assetType. scope: $ref: '#/components/schemas/ScopeRuleInclusion' appliesTo: $ref: '#/components/schemas/ScopeRuleApplicability' SingleAssetRelationship: oneOf: - $ref: '#/components/schemas/DiscoveredByRelationship' discriminator: propertyName: relationshipType mapping: discoveredBy: $ref: '#/components/schemas/DiscoveredByRelationship' ExternalRelationship: description: > A relationship between two assets. Source asset points to an asset in AssetService `assets` table while Target asset points to some external asset stored outside of AssetService. The target is fully identified by two fields: `targetUid` and `targetService`. Generally the relationship may be read as `source`-asset `type` `target`-asset. There cannot be multiple relationships between a pair of assets with the same `type`. Relationships have a `startsAt` date-time and an optional `endsAt` time; a relationship is considered `active` at a point-in-time if the `startsAt` date is prior-to/equal-to the time point, and the `endsAt` time is unset or is after/equal-to the time point. Furthermore, for any given `type` linking a pair of assets, there can only be one active relationship at any given time point. A new relationship cannot be created with a `startsAt` time after an existing relationship's `startsAt` when that relationship has an unset `endsAt` date-time, or the relationship has an `endsAt` after/equal-to the `startsAt` of the new relationship (such that these relationships active ranges would overlap). allOf: - type: object required: - type - sourceAssetUid - targetUid - targetService - startsAt properties: uid: $ref: '#/components/schemas/AssetRelationshipUID' type: description: >- Type of relationship between assets. The direction of reading is `sourceAsset` -- `type` -- `targetAsset`. type: string enum: - discoveredBy sourceAssetUid: $ref: '#/components/schemas/AssetUID' targetUid: $ref: '#/components/schemas/ExternalUID' targetService: description: The type of the external service, holding the "target" entity. type: string enum: - assetDiscovery - fractalScan - xpanse startsAt: type: string format: date-time description: >- The date-time at which the relationship between the source and target assets was observed to begin. endsAt: type: string format: date-time description: >- The date-time at which the relationship between the source and target assets was observed to end. - $ref: '#/components/schemas/Updatable' AssetGateway: type: object description: Gateways and listings the asset is assigned to. properties: gatewayId: $ref: '#/components/schemas/GatewayID' listingUid: $ref: '#/components/schemas/ListingUID' Updatable: allOf: - $ref: '#/components/schemas/Creatable' - type: object properties: updatedAt: type: string format: date-time readOnly: true description: >- Automatically set by the server to the time the request was processed whenever the resource is updated. updatedBy: $ref: '#/components/schemas/OperationUserUID' Base64Data: type: string description: Base64 encoding of data. example: TXkgdm9pY2UgaXMgbXkgcGFzc3dvcmQu CloudCredentialFormat: description: Describes format of the cloud credential type: string enum: - aws_assume_role - aws_secret_access - azure_certificate - azure_password - gcp_cloud_asset - gcp_compute_engine NetworkRef: type: object description: > Reference to the network that an asset can be found on. The asset in question and the network must belong to the same organization. Deprecating. properties: networkUid: $ref: '#/components/schemas/UID' OperatingSystem: type: object properties: name: description: Name of operating system according to fingerprinting. type: string cpe: type: string description: CPE of operating system according to fingerprinting. Port: allOf: - type: object required: - scope - observedState properties: number: $ref: '#/components/schemas/PortNumber' protocol: $ref: '#/components/schemas/PortProtocol' scope: $ref: '#/components/schemas/Scope' service: type: string description: > Name of (expected) service running on port. Will use the [Service Name and Transport Protocol Port Number Registry](https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml) for well-known ports. observedState: $ref: '#/components/schemas/PortObservedState' detectedService: type: string description: > Name of detected service running on port according to fingerprinting. readOnly: true detectedProductName: type: string description: > Name of software product running on port according to fingerprinting. readOnly: true detectedProductVersion: type: string description: >- Version of software product running on port according to fingerprinting. readOnly: true detectedProductConfidenceLevel: type: integer format: int minimum: 1 maximum: 10 description: >- Confidence level of detected product on port according to fingerprinting. readOnly: true detectedProductCPE: type: string description: | CPE for detected product according to fingerprinting. readOnly: true serviceBanner: type: string description: Port banner according to fingerprinting. readOnly: true - $ref: '#/components/schemas/Updatable' ScanState: type: string enum: - new - accepted - queued - dispatched - failed - finished - in-progress description: Scan state of asset. ApplicationAsset: type: object properties: userRoles: description: User roles available for the application. readOnly: true type: array items: $ref: '#/components/schemas/UserRole' MobileOperatingSystem: type: string enum: - ios - android description: The operating system for the asset. ApplicationBinary: type: object properties: version: type: string readOnly: true downloadUrl: type: string format: uri HTTPingSettings: description: >- HTTPingSettings represents custom settings for webapp reachability checks. All fields are optional. type: object properties: url: type: string description: >- URL to perform the check. If not defined, webapp main URL will be used. insecure: type: boolean description: When set to `true`, bypasses SSL/TLS checks. responseHeaderTimeout: type: integer minimum: 0 description: Max time waiting for the HTTP response header, in seconds. timeout: type: integer minimum: 0 description: Max time waiting for the whole HTTP response, in seconds. followRedirects: type: boolean description: >- When set to `false`, redirects are not followed and the last server response returned. method: type: string description: HTTP method to use. headers: $ref: '#/components/schemas/HTTPingSettings_Headers' description: Custom HTTP headers to send. It must be a string-to-string map. example: X-Custom-Header1: value1 X-Custom-Header2: value2 body: type: string description: HTTP request entity to send. validCodes: type: array items: type: integer minimum: 0 description: HTTP response code description: >- List of response status codes considered as valid. When defined, ping will be considered succeeded only when response status code exists in this list. Mutually exclusive with InvalidCodes. example: - 200 - 201 - 204 invalidCodes: type: array items: type: integer minimum: 0 description: HTTP response code description: >- List of response status codes considered as invalid When defined, ping will be considered succeeded only when response status code does not exist in this list. Mutually exclusive with ValidCodes. example: - 400 - 401 - 403 - 500 ScopeRule: allOf: - $ref: '#/components/schemas/ScopeRuleSummary' - $ref: '#/components/schemas/Updatable' WebRULE: type: string pattern: >- ^(/([a-zA-Z0-9_-~!$&'()+,;=:@.]|%[0-9a-fA-F]{2})+/)*(/?((([A-z]|[0-9]|[-_~])|%[0-9a-fA-F]{2}|[!$&'()*+,;=]|[:@])|[/?])*){0,1}//(#((([A-z]|[0-9]|[-_~.])|%[0-9a-fA-F]{2}|[!$&'()*+,;=]|[:@])|[/?])*){0,1}/?$ description: Rule for web asset validation ScopeRuleInclusion: type: string enum: - in - out ScopeRuleApplicability: type: string enum: - scanners - srt - both DiscoveredByRelationship: description: >- Relationship indicating the source asset was discovered by scanning the target asset. Discovered-by relationships extend the uniqueness constraint to allow multiple pairs of this relationship-type between a pair of assets however each such relationship must have a unique asset-scanner property. allOf: - $ref: '#/components/schemas/AssetRelationship' - type: object required: - assetScanner properties: assetScanner: description: The asset-scanner that discovered the relationship. type: string enum: - burp - cloudEnumeration - masscan - nessus - openVAS - tarantulaBurpV2 - cidrExpansion - amass - fingerprinter - easm AssetRelationshipUID: type: string pattern: ^[0-9a-f]{12} description: Unique identifier for a scan. ExternalUID: type: string pattern: ^[0-9a-zA-Z-_]{1,}$ description: >- Unique identifier for an external entity. It has much more loose requirements than AssetUID since in general we don't control these external services. Creatable: type: object required: - createdAt - createdBy properties: createdAt: type: string format: date-time readOnly: true description: >- Automatically set by the server to the time the request was processed whenever the resource was created. createdBy: $ref: '#/components/schemas/OperationUserUID' OperationUserUID: type: string pattern: ^[0-9a-f]{12} readOnly: true description: >- 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. PortProtocol: type: string enum: - tcp - udp PortObservedState: type: string enum: - open - closed - filtered description: Observed state reported by automated scanning. UserRole: allOf: - type: object properties: uid: $ref: '#/components/schemas/UID' name: type: string description: Unique name for the role with the mobile or web application. scannable: type: boolean description: >- Only roles with this property set to true will be scanned by automated scanners. default: false authenticationStrategies: $ref: '#/components/schemas/AuthenticationStrategies' credentials: type: array description: Credentials owned by this role. readOnly: true items: $ref: '#/components/schemas/UserRoleCredentialSummary' credentialCounts: $ref: '#/components/schemas/CredentialCounts' - $ref: '#/components/schemas/Updatable' HTTPingSettings_Headers: type: object properties: additionalProperties: type: object additionalProperties: type: string AssetRelationship: description: >- A relationship between two assets. Generally the relationship may be read as _source_-asset _relationship_-type _target_-asset. There cannot be multiple relationships between a pair of assets with the same relationship-type. Relationships have a starts-at date-time and an optional ends-at date-time; a relationship is considered _active_ at a point-in-time if the starts-at date is prior-to/equal-to the time-point, and the ends-at date-time is unset or is after/equal-to the time-point. Furthermore, for any given relationship-type linking a pair of assets, there can only be one active relationship at any give time point. A new relationship cannot be created with a start-at date-time after an existing relationship's starts-at when that relationship has an unset ends-at date-time, or the relationship has an ends-at after/equal-to the starts-at of the new relationship (such that these relationships active ranges would overlap). allOf: - type: object required: - sourceAssetUid - targetAssetUid - startsAt - relationshipType properties: uid: $ref: '#/components/schemas/AssetRelationshipUID' sourceAssetUid: $ref: '#/components/schemas/AssetUID' targetAssetUid: $ref: '#/components/schemas/AssetUID' startsAt: type: string format: date-time description: >- The date-time at which the relationship between the source and target asset is observed to first begin. endsAt: type: string format: date-time description: >- The date-time at which the relationship between the source and target asset was observed to end. relationshipType: type: string description: Type or relationship between assets. enum: - discoveredBy - $ref: '#/components/schemas/Updatable' AuthenticationStrategies: type: object description: >- Map of authentication strategies for various scanners, keyed by asset scanner name. properties: tarantulaBurpV2: $ref: '#/components/schemas/AuthenticationStrategy' burp: $ref: '#/components/schemas/AuthenticationStrategy' UserRoleCredentialSummary: description: Credential used by an application in context of a user role. type: object properties: uid: $ref: '#/components/schemas/UID' status: $ref: '#/components/schemas/CheckerStatus' lastCheckedAt: type: string format: date-time description: The last date time the credential was checked. sharing: $ref: '#/components/schemas/CredentialSharing' CredentialCounts: description: Credential counts by credential status in context of a user role. type: object readOnly: true properties: unchecked: type: integer description: >- Total of credentials in context of a user role with unchecked status. invalid: type: integer description: Total of credentials in context of a user role with invalid status. valid: type: integer description: Total of credentials in context of a user role with valid status. AuthenticationStrategy: allOf: - type: object properties: scripts: $ref: '#/components/schemas/Scripts' CredentialSharing: type: string description: >- Determines the limits on users that may be assigned; "one" permits only one user to be assigned, "many" places no limit, and "all" prevents any users to explicitly assigned as all users are implicitly allowed to use the credential. enum: - one - many - all Scripts: type: object description: Map of scripts used by this strategy, keyed by script role. properties: authentication: $ref: '#/components/schemas/UserRoleScript' sessionValidation: $ref: '#/components/schemas/UserRoleScript' recordedLogin: $ref: '#/components/schemas/UserRoleScript' UserRoleScript: allOf: - type: object description: Script used to test a mobile or web applications. properties: uid: $ref: '#/components/schemas/UID' status: $ref: '#/components/schemas/CheckerStatus' filename: type: string description: Generated script name. readOnly: true error: type: string description: >- Optional text of error message. Server will unset this property when status is set to any value other than invalid. imageCaptureUrl: type: string format: uri description: Optional Url to image capture of the script execution. lastCheckedAt: type: string format: date-time description: The most reecent date time the script was run. lastSuccessfulAt: type: string format: date-time description: The most recent date time the script was successfully run. responses: PaginatedArrayOfAssets: description: Paginated assets. headers: Pagination-Limit: $ref: '#/components/headers/PaginationLimit' Pagination-Current-Page: $ref: '#/components/headers/PaginationCurrentPage' Pagination-Total-Pages: $ref: '#/components/headers/PaginationTotalPages' Pagination-Total-Count: $ref: '#/components/headers/PaginationTotalCount' Link: $ref: '#/components/headers/Link' content: application/json: schema: $ref: '#/components/schemas/ArrayOfAssets' 400BadRequest: description: Bad Request 401Unauthorized: description: Unauthorized. 403Forbidden: description: Forbidden 500InternalServerError: description: Internal Server Error. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' 503ServiceUnavailable: description: Service Unavailable. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: PaginationLimit: description: Maximum number of items returned in a paginated response. schema: type: integer format: int32 minimum: 1 PaginationCurrentPage: description: Current page in a paginated response. schema: type: integer format: int32 minimum: 1 PaginationTotalPages: description: Total number of pages in a paginated response. schema: type: integer format: int32 minimum: 1 PaginationTotalCount: description: Total number of items in all pages of a paginated response. schema: format: int32 minimum: 1 Link: description: Standard link header. schema: type: string securitySchemes: OAuth2: type: oauth2 flows: implicit: authorizationUrl: login.synack.com scopes: asset_lr: Grants per-listing read access for all types of assets. asset_srt_lr: Grants per-listing read access to assets that may be read by SRTs. asset_or: >- Grants organization-level read access for all types of assets owned by a particular organization. asset_boss_ow: >- Grants organization-level access to assets owned by a particular organization that may be modified by BOSS users. asset_boss_lw: >- Grants per-listing write access to assets that may be modified by BOSS users. asset_client_ow: >- Grants organization-level access to assets owned by a particular organization that may be modified by Client users. asset_client_lw: >- Grants per-listing write access to assets that may be modified by Client users. asset_user_or: >- Grants user-level read access to asset stats that owned by a particular organization. asset_gr: >- Grants unrestricted read access to all assets. Except for credential data of cloud accout assets. asset_gw: Grants unrestricted write access to all assets. asset_scan_gr: >- Grants unrestricted read access to all assets. Including credential data of cloud account assets. ````