--- title: "Assets" method: POST path: "/api/3/sites/{id}/assets" tags: ["Asset"] --- # Assets `POST /api/3/sites/{id}/assets` Creates or updates an asset with the specified details. ## Path parameters - `id` integer, required ## Request body - AssetCreate — The details of the asset being added or updated. The operating system can be specified in one of three ways, with the order of precedence: `"osFingerprint"`, `"os"`, `"cpe"` - `addresses` Address[] — All addresses discovered on the asset. - `ip` string — The IPv4 or IPv6 address. - `mac` string — The Media Access Control (MAC) address. The format is six groups of two hexadecimal digits separated by colons. - `assessedForPolicies` boolean — Whether the asset has been assessed for policies at least once. - `assessedForVulnerabilities` boolean — Whether the asset has been assessed for vulnerabilities at least once. - `configurations` Configuration[] — Configuration key-values pairs enumerated on the asset. - `name` string, required — The name of the configuration value. - `value` string — The configuration value. - `cpe` string — The Common Platform Enumeration (CPE) of the operating system. This is the tertiary means of specifying the operating system fingerprint. Use `"osFingerprint"` or `"os"` as a more accurate means of defining the operating system. - `databases` Database[] — The databases enumerated on the asset. - `description` string — The description of the database instance. - `id` integer — The identifier of the database. - `name` string, required — The name of the database instance. - `date` string, date-time, required — The date the data was collected on the asset. - `description` string — The description of the source or collection of information on the asset. This description will appear in the history of the asset for future auditing purposes. - `files` File[] — The files discovered with searching on the asset. - `attributes` Configuration[] — Attributes detected on the file. - `name` string, required — The name of the configuration value. - `value` string — The configuration value. - `name` string, required — The name of the file. - `size` integer — The size of the regular file (in bytes). If the file is a directory, no value is returned. - `type` 'file' | 'directory', required — The type of the file. - `history` AssetHistory[] — The history of changes to the asset over time. - `date` string, date-time — The date the asset information was collected or changed. - `description` string — Additional information describing the change. - `scanId` object — The identifier of the scan. - `type` string — The type of change. May be one of: | Type | Source of Data | | ----------------------------------- | ----------------------------------------------------------- | | `ASSET-IMPORT`, `EXTERNAL-IMPORT` | External source such as the API | | `EXTERNAL-IMPORT-APPSPIDER` | Rapid7 InsightAppSec (previously known as AppSpider) | | `SCAN` | Scan engine scan | | `AGENT-IMPORT` | Rapid7 Insight Agent | | `ACTIVE-SYNC` | ActiveSync | | `SCAN-LOG-IMPORT` | Manual import of a scan log | | `VULNERABILITY_EXCEPTION_APPLIED` | Vulnerability exception applied | | `VULNERABILITY_EXCEPTION_UNAPPLIED` | Vulnerability exception unapplied | - `user` string — If a vulnerability exception change, the login name of the user that performed the operation. - `version` integer — The version number of the change (a chronological incrementing number starting from 1). - `vulnerabilityExceptionId` object — The identifier of the vulnerability exception. - `hostName` string — The primary host name (local or FQDN) of the asset. - `hostNames` HostName[] — Additional host names for the asset. - `name` string, required — The host name (local or FQDN). - `source` 'user' | 'dns' | 'netbios' | 'dce' | 'epsec' | 'ldap' | 'other' — The source used to detect the host name. `user` indicates the host name source is user-supplied (e.g. in a site target definition). - `id` object — The identifier of the asset. - `ids` UniqueId[] — Unique identifiers found on the asset, such as hardware or operating system identifiers. - `id` string, required — The unique identifier. - `source` string — The source of the unique identifier. - `ip` string — The primary IPv4 or IPv6 address of the asset. - `links` Link[], required — Hypermedia links to corresponding or related resources. - `deprecation` string - `href` string — A hypertext reference, which is either a URI (see RFC 3986) or URI template (see RFC 6570). - `hreflang` string - `media` string - `rel` string — The link relation type. This value is one from the Link Relation Type Registry or is the type of resource being linked to. - `title` string - `type` string - `mac` string — The primary Media Access Control (MAC) address of the asset. The format is six groups of two hexadecimal digits separated by colons. - `os` string — Free-form textual description of the operating system of the asset, typically from a fingerprinting source. This input will be parsed to produce a full fingerprint. This is the secondary means of specifying the operating system. Use `osFingerprint` for a more accurate definition. - `osCertainty` string — The certainty of the operating system fingerprint. - `osFingerprint` OperatingSystem — The details of the operating system of the asset. At least one of `vendor`, `family`, or `product` must be supplied. This is the preferred means of defining the operating system. - `architecture` string — The architecture of the operating system. - `configurations` Configuration[] — Configuration key-values pairs enumerated on the operating system. - `name` string, required — The name of the configuration value. - `value` string — The configuration value. - `cpe` OperatingSystemCpe — The Common Platform Enumeration (CPE) of the operating system. - `edition` string — Edition-related terms applied by the vendor to the product. - `language` string — Defines the language supported in the user interface of the product being described. The format is of the language tag adheres to RFC5646. - `other` string — Captures any other general descriptive or identifying information which is vendor- or product-specific and which does not logically fit in any other attribute value. - `part` 'o' | 'a' | 'h', required — A single letter code that designates the particular platform part that is being identified. - `product` string — the most common and recognizable title or name of the product. - `swEdition` string — Characterizes how the product is tailored to a particular market or class of end users. - `targetHW` string — Characterize the instruction set architecture on which the product operates. - `targetSW` string — Characterize the software computing environment within which the product operates. - `update` string — Vendor-specific alphanumeric strings characterizing the particular update, service pack, or point release of the product. - `v2.2` string — The full CPE string in the CPE 2.2 format. - `v2.3` string — The full CPE string in the CPE 2.3 format. - `vendor` string — The person or organization that manufactured or created the product. - `version` string — Vendor-specific alphanumeric strings characterizing the particular release version of the product. - `description` string — The description of the operating system (containing vendor, family, product, version and architecture in a single string). - `family` string — The family of the operating system. - `id` integer — The identifier of the operating system. - `product` string — The name of the operating system. - `systemName` string — A combination of vendor and family (with redundancies removed), suitable for grouping. - `type` string — The type of operating system. - `vendor` string — The vendor of the operating system. - `version` string — The version of the operating system. - `rawRiskScore` number, double — The base risk score of the asset. - `riskScore` number, double — The risk score (with criticality adjustments) of the asset. - `services` Service[] — The services discovered on the asset. - `configurations` Configuration[] — Configuration key-values pairs enumerated on the service. - `name` string, required — The name of the configuration value. - `value` string — The configuration value. - `databases` Database[] — The databases enumerated on the service. - `description` string — The description of the database instance. - `id` integer — The identifier of the database. - `name` string, required — The name of the database instance. - `family` string — The family of the service. - `links` Link[], required — Hypermedia links to corresponding or related resources. - `deprecation` string - `href` string — A hypertext reference, which is either a URI (see RFC 3986) or URI template (see RFC 6570). - `hreflang` string - `media` string - `rel` string — The link relation type. This value is one from the Link Relation Type Registry or is the type of resource being linked to. - `title` string - `type` string - `name` string — The name of the service. - `nic` string — The network interface card (NIC) of the service. - `port` integer, required — The port of the service. - `product` string — The product running the service. - `protocol` 'ip' | 'icmp' | 'igmp' | 'ggp' | 'tcp' | 'pup' | 'udp' | 'idp' | 'esp' | 'nd' | 'raw', required — The protocol of the service. - `userGroups` GroupAccount[] — The group accounts enumerated on the service. - `id` integer — The identifier of the user group. - `name` string, required — The name of the user group. - `users` UserAccount[] — The user accounts enumerated on the service. - `fullName` string — The full name of the user account. - `id` integer — The identifier of the user account. - `name` string — The name of the user account. - `vendor` string — The vendor of the service. - `version` string — The version of the service. - `webApplications` WebApplication[] — The web applications found on the service. - `id` integer — The identifier of the web application. - `pages` WebPage[] — The pages discovered on the web application. - `linkType` 'seed' | 'html-ref' | 'robots' | 'js-string' | 'query-param' | 'pdf' | 'css' | 'implied-dir' | 'rss' | 'redirection' | 'sitemap' | 'backup' | 'vck-rewrite' | 'non-ref-guess' | 'soft-404' — The type of link used to traverse or detect the page. - `path` string — The path to the page (URI). - `response` integer — The HTTP response code observed with retrieving the page. - `root` string — The web root of the web application. - `virtualHost` string — The virtual host of the web application. - `software` Software[] — The software discovered on the asset. - `configurations` Configuration[] — The attributes of the software. - `name` string, required — The name of the configuration value. - `value` string — The configuration value. - `cpe` SoftwareCpe — The Common Platform Enumeration (CPE) of the software. - `edition` string — Edition-related terms applied by the vendor to the product. - `language` string — Defines the language supported in the user interface of the product being described. The format is of the language tag adheres to RFC5646. - `other` string — Captures any other general descriptive or identifying information which is vendor- or product-specific and which does not logically fit in any other attribute value. - `part` 'o' | 'a' | 'h', required — A single letter code that designates the particular platform part that is being identified. - `product` string — the most common and recognizable title or name of the product. - `swEdition` string — Characterizes how the product is tailored to a particular market or class of end users. - `targetHW` string — Characterize the instruction set architecture on which the product operates. - `targetSW` string — Characterize the software computing environment within which the product operates. - `update` string — Vendor-specific alphanumeric strings characterizing the particular update, service pack, or point release of the product. - `v2.2` string — The full CPE string in the CPE 2.2 format. - `v2.3` string — The full CPE string in the CPE 2.3 format. - `vendor` string — The person or organization that manufactured or created the product. - `version` string — Vendor-specific alphanumeric strings characterizing the particular release version of the product. - `description` string — The description of the software. - `family` string — The family of the software. - `id` object — The identifier of the software. - `product` string — The product of the software. - `type` string — The version of the software. - `vendor` string — The vendor of the software. - `version` string — The version of the software. - `type` 'unknown' | 'guest' | 'hypervisor' | 'physical' | 'mobile' — The type of asset. - `userGroups` GroupAccount[] — The group accounts enumerated on the asset. - `id` integer — The identifier of the user group. - `name` string, required — The name of the user group. - `users` UserAccount[] — The user accounts enumerated on the asset. - `fullName` string — The full name of the user account. - `id` integer — The identifier of the user account. - `name` string — The name of the user account. - `vulnerabilities` AssetVulnerabilities — Summary information for vulnerabilities on the asset. - `critical` integer — The number of critical vulnerabilities. - `exploits` integer — The number of distinct exploits that can exploit any of the vulnerabilities on the asset. - `malwareKits` integer — The number of distinct malware kits that vulnerabilities on the asset are susceptible to. - `moderate` integer — The number of moderate vulnerabilities. - `severe` integer — The number of severe vulnerabilities. - `total` integer — The total number of vulnerabilities. ## Response `200` OK ## Other responses - `201` — Created - `400` — Bad Request - `401` — Unauthorized - `500` — Internal Server Error - `503` — Service Unavailable --- [API](https://skmtc.net/rapid7/apis/rapid7-vm-api.md) · [All operations](https://skmtc.net/rapid7/apis/rapid7-vm-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rapid7/rapid7-vm-api/versions/3a8197c22d71/schema)