Client objects contain the client's details and are one of the highest-level objects in the database, as all other objects are within the context of a specific client.
The client object does not hold a list of assets or reports; instead, each asset and report contains the ID of a client.
Clients hold a list of client assets representing a physical asset or web application. This list is dynamically populated as files with assets imported via a scan or manually added within PlexTrac.
The following table explains the fields and data types stored for a client. Fields are presented in alphabetical order by object field name.
The name
field is the only required field when creating a client.
The client object stored in the database is a nested JSON object. Below is a screenshot and sample downloadable file that displays the structure of database objects.
object field name | description | data type |
---|---|---|
client_id
UUID of client
integer
classificationId
CUID of the Classification Level for an authorized user for each client
string or null
custom_field
custom fields related to client
array[ { "label": str, "value": str } ]
custom_field/label
label of the custom field
string
custom_field/value
plain text value of the custom field
string
description
description of client
string
doc_type
field in database to identify object
"client": DB type identifier
name
name of Client
string
poc
point of contact for client
string
poc_email
email address of point of contact
string
role
type of role of user associated with a client; will be one of three values to represent roles of Administrator, Standard User, and Analyst
string containing one of the following values: ["ADMIN", "STD_USER", "ANALYST"]
tenant_id
UUID of tenant
integer
users
list of users and roles within a client
dict { str: user email: Dict{ "classificationId": str || null: CUID, "role": str: ["ADMIN", "STD_USER", "ANALYST"] } }
tags
any tags associated with a client
string array
PlexTrac data is categorized into clients, reports, findings, and assets, which are the primary containers holding information stored in Plextrac. The Clients module holds assets and reports, while reports hold findings.
While these objects exist as their type in the database, some fields about an object are stored both on the object and as values inside other objects. The most common example of this is affected assets and vulnerabilities.
Here is a list of object structures that have been defined:
Reports are the middle-level objects housed under a client and contain report details. The Report object does not hold a list of findings, but each finding includes the ID of a report.
The following table explains the fields and data types stored for a report. Fields are presented in alphabetical order by object field name.
The report object stored in the database is a nested JSON object. Below is a screenshot and sample downloadable file that displays the structure of database objects.
Findings are the most common object in PlexTrac and contain data detailing an exploit.
Findings also exist in client asset information in the form of an affected asset and contain the relationship information about which client assets are affected, which is tracked in the affected_assets
field.
For each client asset, the finding affects, an object exists in that field's list containing information and metadata about the client asset and how it relates to the finding. Since the objects stored in affected_assets
contain this extra relationship metadata, these items are considered separate objects called affected asset objects.
The following table explains the fields and data types stored for a finding. Fields are presented in alphabetical order by object field name.
The required fields when creating a finding are title
, severity
, and description
.
The finding object stored in the database is a nested JSON object. Below are screenshots and a sample downloadable file that displays the structure of different database objects.
continued
Assets are stored at the client level, and only the single doc_type value of "client_asset" exists in the database. An asset can exist as a standalone file added for a client through the Clients module or associated with a finding referred to as an affected asset.
An affected asset refers to a client_asset object with extra properties stored on the finding object. Although it doesn't have its own type or location in the database, it can still be considered a real object since it is technically distinct and exists within the finding object.
The following table explains the fields and data types stored for an asset. Fields are presented in alphabetical order by object field name.
The only required field when creating an asset is the asset name.
Client assets are lower-level objects containing information about an asset or application. They contain some finding information in the form of a vulnerability[link].
Client assets contain the data related to the specific physical machine or web application represented and relational information about which findings they are affected by.
Every client asset object has the findings
field. For each finding affecting the client asset, an object in that field's list contains information about the finding in a specific report and additional metadata showing how the client asset relates to the finding.
Objects stored in findings
contain additional relational metadata for vulnerability objects.
The child asset contains a subset of the related client asset's information.
Affected assets are not objects with their own database type but a value stored in the affected_assets
field of a finding object. It contains information about a client asset being affected and relational metadata about the finding and client asset.
An affected asset object on a finding will have a subset of fields compared to the client asset with the same ID. Some additional fields exist that only make sense when the finding and client asset are viewed together, such as the date the finding started affecting the client asset, the affected ports, location access to vulnerability, vulnerable parameters, and evidence of the affection.
Affected assets are very similar to Vulnerabilities, but the rules and validations defining them differ.
object field name | description | data type |
---|
object field name | description | data type |
---|
object field name | description | data type |
---|
name | name of affected assets | dict {str, {AFFECTED ASSET Object} |
status | status of report | string ["Draft", "Ready For Review", "In Review", "Approved", "Published"] |
includeEvidence | identifies if the report includes evidence | Boolean |
report_id | the UUID of the report | integer |
client_id | client that the report belongs to | integer |
doc_type | field in database to identify object | "report": DB type identifier |
reportType | type of report | "default" |
tags | any tags associated with the report | string array |
custom_field | custom field(s) added to a report | array[ { "label": str, "value": str } ] |
custom_fields | container for fields used to track information about the report executive summary narratives; id (narrative UUID), label (title of narrative), tags (any tags applied to narrative), text (narrative content), isFromNarrativesDB (null/true value identifying if the content is from NarrativesDB). | array[ { "id": str, "label": str, "tags": array[str], "text": str, "isFromNarrativesDB": null or true |
template | if the report did not use the default template, the custom report UUID is listed | string || null: UUID of report template |
start_date | date report was started | null: Zulu date time format |
end_date | date report was closed | null: Zulu date time format |
fields_template | if the report did not use the default fields template, the custom fields template UUID is listed | string || null: UUID of fields/finding template |
exec_summary | a container field that contains any custom fields created for the report | { "custom_fields": array[ { "id": str: CUID of report narrative, "label": str, "tags": array[str], "text": str, } ] } |
isTrackChanges | defines if the rich-text field track changes feature is turned on at the report level (a value of "true" means it is turned on, while a value of "false" means it is turned off and track changes is done per rich-text field) | null or true |
affected_assets | name of affected assets | dict {str, {AFFECTED ASSET Object} |
assignedTo | email address of user that finding is assigned to | string |
client_id | client that the finding belongs to | integer |
closedAt | when finding was closed | integer in epoch milliseconds, such as "1662588579026" |
common_identifiers | includes CVE scores, CWE scores, and code that is related to the finding (added in the Code Sample tab when editing a finding) | "CVE": [{ "name": str, "year": int, "id": int, "link": str } ], "CWE": [ { "name": str, "id": int, "link": str } ] }, "code_samples": [ { "caption": str, "code": str, "id": str } ] } |
createdAt | when finding was created in | integer in epoch milliseconds, such as "1662588579026" |
description | description of finding | string |
doc_type | field in database to identify object | string |
doc_version | version of PlexTrac when finding was created. Should not be added to create or update requests | string |
exhibits | an image or video related to the finding (added in the Screenshots/Video tab when editing a finding) | array: {"assets": [ { "asset": str, "id": str } ], "caption": str, "exhibitID": str:, "index": int, "type": str: MIME type image, such as .png} |
fields | includes any added custom fields, plus any CVSS 3.0 score, CVSS 2.0 score, and 'general' score values entered for a finding | dict {str, dict {label: str, value: str}, "scores": { "cvss", { "type": "cvss", "value": str, "label": str, "calculation": str }, "cvss3", { "type": "cvss3", "value": str, "label": str, "calculation": str }, "general", { "type": "general", "value": str, "label": str, "calculation": str } } }, |
flaw_id | the unique identifier of a finding and is generated based on the finding title, but since a finding with the same title can exist in different reports, this means | integer |
last_update | when finding was last modified | integer in epoch milliseconds, such as "1662588579026" |
repoenedAt | when finding was reopened | integer in epoch milliseconds, such as "1662588579026 |
report_id | ID of report finding is associated with | integer |
report_name | name of report | string |
risk_score | the total risk score of the finding for CVSS v3.1, CVSS v3.0, CVSS v2.0, and CWSS | "CVSS3": "overall": int, "vector": str, "subScore": "base": int |
selectedScore | the identified selected score for the finding | string |
severity | severity of finding | string |
slaData | SLA status of finding | {"title": str, "timeToExpire": str } |
source | source of finding | string |
status | status of finding | string |
subStatus | substatus of finding | string |
tags | any tags associated with finding | string array |
title | title of finding | string |
visibility | visibility of finding | string |
asset | name of asset | string |
assetCriticality | value capturing the asset criticality that must be one of five provided values | string from list: "Critical", "High", "Medium", "Low", "Information" |
assignedTo | email of user vulnerability is assigned to | string |
child_assets | assets identified as belonging to this asset | dict {asset str: UUID of asset, dict {CHILD ASSET Object} |
client_id | client that the asset belongs to | integer |
closedAt | time vulnerability was closed | integer in epoch milliseconds, such as "1661376746781" |
created | when asset was created | string: Zulu date time format, such as "2022-05-20T20:43:59.405Z" |
createdAt | when asset was created | integer in epoch milliseconds, such as "1661376746781" |
data_owner | name of owner | string (defaults to "Data Owner") |
description | description of asset | string |
dns_name | name of dns | string (defaults to "DNS Name") |
doc_type | field in database to identify object | string |
evidence | evidence ID of vulnerability | array string UUID |
findings | list of findings that the asset is associated with and is autogenerated to record the relationship between the finding and asset | dict {int: id of finding: dict {VULNERABILITY Object} |
host_fqdn | fully qualified domain name of host | string |
host_rdns | reverse Domain Name System of host | string, such as "216.58.211.142" |
hostname | hostname | string |
instances | instances of vulnerability | string: report id value: "report_id": int, "report_severity": str: ["Critical", "High", "Medium", "Low", "Information"], "report_status": str: ["Open", "In Process", "Closed"], "report_flaw_title": str, "createdAt": int: epoch milliseconds, "updatedAt": int: epoch milliseconds |
id | asset unique identifier | string: UUID |
knownIps | string array |
locationUrl | url of related vulnerability | string |
mac_address | media access control address unique identifier | string |
netbios_name | 16-byte name for a networking service or function on a machine running Microsoft Windows Server | string |
notes | any added notes to asset | string |
operating_system | operating system related to asset | string array |
parent_asset | asset ID of parent asset | dict {ASSET Object} |
pci_status | PCI compliance status | string: "pass" or "fail" |
physical_location | physical location of asset | string |
ports | known ports | dict { str: value of number: { "number": str, "service": str, "protocol": str, "version": str } |
reopenedAt | when vulnerability was reopened | integer (defaults to "null") |
report_id | ID of report that vulnerability is associated with | integer |
severity | severity of vulnerability that must be one of five provided values | string from list: "Critical", "High", "Medium", "Low", "Information" |
status | status of vulnerability | string: "Open", "In Process", "Closed" |
subStatus | substatus of vulnerability | string |
system_owner | owner of system | string (defaults to "System Owner") |
tags | any tags associated with an asset | string array |
title | title of vulnerability | string |
total_cves | total CVEs score | integer |
type | asset type that must be a specific value | string: "Server", "Workstation", "Network Device", "Application", "General" |
updatedAt | date and time when asset was updated | integer in epoch milliseconds |
vulnerableParameters | parameters of vulnerability | list {"id": str, "text": str} |
Evidence is a small object attached to affected assets or vulnerabilities. Evidence can be added in the UI by importing scanner outputs or manually through API endpoints to an affected asset on new or existing findings.
The following table explains the fields and data types stored for evidence. Fields are presented in alphabetical order by object field name.
object field name | description | data type |
---|---|---|
caption
evidence caption
string
code
evidence code
string
id
unique identifier
string: UUID